Risprogg

for 32-Bit Applications
RIS Programmers Guide

August 1996
DNA119040
Version 5.4

Warranties and Liabilities
Al l warranti es gi ven by I ntergraph Corporati on about equi pment or software are set forth i n your purchase contract,
and nothi ng stated i n, or i mpl i ed by, thi s document or i ts contents shal l be consi dered or deemed a modi fi cati on or
amendment of such warranti es.
The i nformati on and the software di scussed i n thi s document are subject to change wi thout noti ce and shoul d not be
consi dered commi tments by I ntergraph Corporati on. I ntergraph Corporati on assumes no responsi bi l i ty for any
error that may appear i n thi s document.
The software di scussed i n thi s document i s furni shed under a l i cense and may be used or copi ed onl y i n accordance
wi th the terms of thi s l i cense.
No responsi bi l i ty i s assumed by I ntergraph for the use or rel i abi l i ty of software on equi pment that i s not suppl i ed by
I ntergraph or i ts affi l i ated compani es.
Trademarks
I nterAct, I ntergraph, and RI S are regi stered trademarks of I ntergraph Corporati on. DI ALOG, I nterServe, and TD1
are trademarks of I ntergraph Corporati on. Al l other brands and product names are trademarks of thei r respecti ve
owners.
Copyright
1996 I ntergraph Corporati on
Al l Ri ghts Reserved
I ncl udi ng software, fi l e formats, and audi ovi sual di spl ays; may be used pursuant to appl i cabl e software l i cense
agreement; contai ns confi denti al and propri etary i nformati on of I ntergraph and/or thi rd parti es whi ch i s protected
by copyri ght and trade secret l aw and may not be provi ded or otherwi se made avai l abl e wi thout proper
authori zati on.
RESTRICTED RIGHTS LEGEND
Use, dupl i cati on, or di scl osure by the government i s subject to restri cti ons as set forth i n subparagraph (c) (1) (i i ) of
The Ri ghts i n Techni cal Data and Computer Software cl ause at DFARS 252.227-7013 or subparagraphs (c) (1) and
(2) of Commerci al Computer Software Restri cted Ri ghts at 48 CFR 52.227-19, as appl i cabl e.
Unpubl i shed ri ghts reserved under the copyri ght l aws of the Uni ted States.
I ntergraph Corporati on
Huntsvi l l e, Al abama 35894-0001

Tableof Contents
__________________________________________________________________________________________________________________________________________________

__________________________________________________________________________________________________________________________________________________
Tableof Contents

1. Before You Begi n .................................................................................................. 1 - 3
1.1 Changes to the Software .............................................................................. 1 - 3
1.2 Rel ated Documentati on ............................................................................... 1 - 3
1.3 Document Conventi ons ................................................................................ 1 - 3
1.4 Usi ng On-l i ne Hel p ...................................................................................... 1 - 5
1.4.1 Parts of the Hel p Wi ndow ................................................................ 1 - 5
2. Creati ng Appl i cati ons wi th RI S ........................................................................... 2 - 3
2.1 I ntroducti on to the RI S Devel opment Pl atform ......................................... 2 - 3
2.2 Products Needed to Use the RI S Devel opment Pl atform ........................... 2 - 4
2.3 Changes to the Software .............................................................................. 2 - 4
2.4 On-l i ne Hel p ................................................................................................. 2 - 4
2.5 Embedded SQL Standard ............................................................................ 2 - 4
2.6 RI S Preprocessor .......................................................................................... 2 - 5
2.7 Error Handl i ng ............................................................................................. 2 - 9
2.8 Host Vari abl es .............................................................................................. 2 - 11
2.9 Categori es of Embedded SQL Statements .................................................. 2 - 14
2.9.1 Stati c Noncursor SQL Statements .................................................. 2 - 15
2.9.2 Stati c Cursor SQL Statements ........................................................ 2 - 16
2.9.3 Dynami c Noncursor SQL Statements ............................................. 2 - 18
2.9.4 Dynami c Cursor SQL Statements ................................................... 2 - 21
2.10 Mul ti pl e Transacti ons ................................................................................ 2 - 23
2.11 Asynchronous Executi on of Statements .................................................... 2 - 24
3. Usi ng Bi nary and Text Data ................................................................................ 3 - 3
3.1 RI S_BLOB .................................................................................................... 3 - 3
3.2 RI S_TEXT .................................................................................................... 3 - 6
4. Embedded SQL Reference .................................................................................... 4 - 3
4.1 Qui ck Reference ........................................................................................... 4 - 3
4.2 I ncl ude Fi l es, Li brari es, and Exampl e Programs ....................................... 4 - 6
4.3 RI S Embedded SQL Statements ................................................................. 4 - 6
5. RI S Functi ons ....................................................................................................... 5 - 3

5.1 Reference Structures .................................................................................... 5 - 3
5.3 Functi ons ...................................................................................................... 5 - 7
6. RI S Forms Functi ons ............................................................................................ 6 - 3
6.2 I ni ti al i ze Forms Functi on ............................................................................ 6 - 4
6.3 Set Functi ons ............................................................................................... 6 - 9
6.4 Di spl ayed Forms Functi ons ......................................................................... 6 - 10
6.5 Di spl ay Forms Functi ons ............................................................................. 6 - 11
6.6 Erase Forms Functi ons ................................................................................ 6 - 12
6.7 Forms Functi ons Error Handl i ng ................................................................ 6 - 13
7. Embedded Loadi ng and Unl oadi ng of RI S Objects ............................................. 7 - 3
7.1 Usi ng ri sl oddes for Embedded Loadi ng ...................................................... 7 - 3
7.2 Usi ng ri sul ddes for Embedded Unl oadi ng .................................................. 7 - 4
7.4 ri sl oddes Structures ..................................................................................... 7 - 5
7.4.1 ri sl oddbs Structure ........................................................................... 7 - 8
7.4.2 ri sl odsch Structure ........................................................................... 7 - 8
7.5 ri sul ddes Structures ..................................................................................... 7 - 17
7.5.1 ri sul dsch Structure ........................................................................... 7 - 19
7.6 Di recti ons for Usi ng ri sl oddes and ri sul ddes .............................................. 7 - 27
7.6.1 Di recti ons for Usi ng ri sl oddes .......................................................... 7 - 27
7.6.2 Di recti ons for Usi ng ri sul ddes ......................................................... 7 - 29
7.7 RI S_l oader and RI S_unl oader Embedded Functi ons ................................. 7 - 31
Appendi x A: Changes to Thi s Versi on of RI S .......................................................... A - 3
A.1 RDBMS Versi ons ............................................................................................... A - 3
A.2 UNI ON and UNI ON ALL Supported ................................................................ A - 3
A.3 Objects of Di fferent Owners Wi thi n a Schema ................................................. A - 3
A.4 Object Al i ases ..................................................................................................... A - 4
A.5 Mul ti -User/Secure Schemas .............................................................................. A - 5
A.6 Shared Di cti onari es ........................................................................................... A - 6
A.7 Di cti onary Objects .............................................................................................. A - 6
A.8 Di cti onary Vi ews ................................................................................................ A - 7
A.9 RI S_BLOB/RI S_TEXT ....................................................................................... A - 8
A.10 I nteroperabi l i ty ................................................................................................ A - 11
A.11 Upgrade Uti l i ty ................................................................................................ A - 12
A.12 Uti l i ti es ............................................................................................................. A - 12
A.13 Parameters ....................................................................................................... A - 12

A.14 I nternati onal i zati on ......................................................................................... A - 13
Appendi x B: Programmi ng Notes and Performance Consi derati ons ..................... B - 3
B.1 Decl ari ng Tabl es/Vi ews ..................................................................................... B - 3
B.2 Error Handl i ng ................................................................................................... B - 3
B.3 I ni ti al i zi ng and Termi nati ng RI S ...................................................................... B - 4
B.4 Locki ng ............................................................................................................... B - 4
B.5 Managi ng Statements ........................................................................................ B - 5
B.6 Order By Statement ........................................................................................... B - 5
B.7 Prepari ng Statements ........................................................................................ B - 5
B.8 RI S Di rect versus RI SNET Connecti on ............................................................ B - 6
B.9 Schema Fi l es ...................................................................................................... B - 6
B.10 Set Mode Veri fy ................................................................................................ B - 6
B.11 Temporary Tabl es ............................................................................................ B - 7
B.12 Transacti ons ..................................................................................................... B - 7
B.13 Uni que Record I denti fi ers ................................................................................ B - 7
B.14 Usi ng I ndexes ................................................................................................... B - 10
B.15 Usi ng Si gnal s ................................................................................................... B - 12
B.16 Usi ng SQL Statements Wi sel y ........................................................................ B - 12
Appendi x C: Language Confi gurati on Fi l e .............................................................. C - 3
Appendi x D: Redi stri buti on of RI S Runti me and RI S Uti l i ti es .............................. D - 3
D.1 Di rectory Structure ............................................................................................ D - 3
D.2 Setup Fi l es ......................................................................................................... D - 3
D.3 I nstal l i ng the RI S Shared Component .............................................................. D - 5
Gl ossary ....................................................................................................................... GL - 3
I ndex ............................................................................................................................ I N - 3

Before You Begin 1 - 1

BeforeYou Begin
__________________________________________________________________________________________________________________________________________________
1 - 2 Before You Begin


__________________________________________________________________________________________________________________________________________________
1.
BeforeYou Begin
Thi s document gi ves programmers an overvi ew of how to use RI S i n appl i cati ons and
descri bes the features supported by RI S. These features i ncl ude Embedded SQL statements,
functi ons, and riscpp.
Thi s document i s wri tten for appl i cati ons devel opers who use the RI S Devel opment Pl atform
to i nteract wi th database systems through Embedded SQL or who want to wri te thei r own
database-i ndependent C programs.
1.1 Changes to theSoftware
I f you are currentl y usi ng an earl i er versi on of RI S, read the secti on Changes toThis Version
of RI S before usi ng RI S 5. I mportant changes have been made to the software.
1.2 Related Documentation
DNA1116 RI S SQL Users Guidefor 32-Bit Applications
DNA1117 RI S Utilities Guidefor 32-Bit Applications
DNA1151 RI S I nstallation Guidefor 32-Bit Applications
DNA1003 RI S SQL Commands Quick Reference
DNA1009 RI S Programmers Quick Reference
DNA0016 I / Forms Users Guide
DNUC074 I / Forms Programmers Guide
1.3 Document Conventions
Fi l enames and di rectory paths appear i n i tal i c typeface. However, the i tal i c typeface i s
al so used for emphasi s of new words or i mportant phrases. For exampl e:
c:\ windows
Command names, menu names, tool s, system prompts and messages, and keys may
appear i n bol dface type. For exampl e:
Filemenu
OR
Press Enter
The word mouserefers to the 2-button or 3-button mouse.

The word select means to sel ect a command by pressi ng the l eft mouse button over a
menu command or by pressi ng the Alt key and the underl i ned character
si mul taneousl y.
The word choosemeans to choose a button or i con by pressi ng the l eft mouse button
over a Tool bar button, or appl i cati on i con.
The word reset means to termi nate a command i ni ti ated wi th the mouse. Reset by
pressi ng the ri ght mouse button.
The word identifymeans to defi ne an area or pl ace graphi c el ements i n a graphi cs fi l e.
For PCs, i denti fy wi th the l eft mouse button.
The phrase key in general l y means to enter data i nto a fi el d on a di al og box. To
advance to the next fi el d, use the Tabkey.
System key-i ns, keywords, and programmi ng code segments, appear i n monospaced
type. For exampl e:
main ( )
OR
commit I n actual usage, keywords can be i n ei ther upper or l owercase.
Words that appear i n angl e brackets, < >, are i denti fi ers or names that you must
suppl y, or dynami c i nformati on that can change for each error message. For exampl e:
ERROR: Error openi ng the fi l e <fi l ename>
Phrases i n square brackets, [ ], are opti onal phrases.
Curl y braces contai n several opti ons (used i n conjuncti on wi th a l ogi cal OR symbol ( | )
or phrases that can be repeated (used i n conjuncti on wi th [, ...]). A comma fol l owed by a
seri es of three peri ods i n square brackets ([, ...]) i ndi cates that the l ast phrase contai ned
wi thi n curl y braces ({}), or the l ast i tem, can be repeated numerous ti mes (separated by
commas).
For exampl e: {<col umn> <data type> }[, ...] means that numerous col umn names and
associ ated data types can be speci fi ed (separated by commas).
The logical or symbol ( | ) separates phrases or keywords wi thi n curl y braces ({}) that
can be used al one but not together.
For exampl e: { user | database }means that ei ther the user keyword or the
database keyword can be speci fi ed, but not both.

Thi s symbol notes i mportant i nformati on.

Thi s symbol cauti ons about operati ons that can cause l i mi ted damage.

Thi s symbol warns about operati ons that can cause severe damage.
1.4 UsingOn-lineHelp
On-l i ne Hel p i s an on-l i ne reference tool accessi bl e at any ti me the appl i cati on i s i n use. The
on-l i ne Hel p contai ns a descri pti on for each command and tool and step-by-step procedures
for common tasks. For exampl e, i f you need to perform a certai n task, search and di spl ay the
topi c. You can move or resi ze your appl i cati on and Hel p wi ndows so that they are next to
each other. Thi s l ets you fol l ow the procedures wi thout havi ng to search for the pages i n the
documentati on.

1.4.1 Parts of theHelp Window
To vi ew the on-l i ne Hel p, sel ect Contents from the Help menu. To get more speci fi c
i nformati on, sel ect one of the major topi cs or perform a search on a speci fi c topi c.


Use To
Contents Di spl ay a l i sti ng of the tabl e of contents for
the on-l i ne Hel p fi l e.
Search Locate i nformati on about a certai n topi c that
you enter i n the Search box.
Back Take you back to the previ ous Hel p topi cs you
have al ready vi ewed.
Hi story Di spl ay a sequenti al l i st of every Hel p topi c
you have vi ewed duri ng your current Wi ndows
sessi on.
Fi nd Di spl ay a di al og box used to retri eve parti al or
ful l text stri ngs i n the hel p fi l e. Use the
Hints button for i nformati on on constructi ng
your search query.
<< Vi ew the previ ous topi c i n a seri es of rel ated
topi cs. The button i s di mmed when you reach
the fi rst topi c i n the seri es.
>> Vi ew the next topi c i n a seri es of rel ated
topi cs. The button i s di mmed when you reach
the l ast topi c i n the seri es.

I f the graphi cs i n the on-l i ne Hel p appear di storted, check your graphi cs dri ver.
I f you are usi ng an I ntergraph TD1 machi ne, the S3 1024x768 256 col or (Large
Font) di storts the graphi cs sl i ghtl y. Changi ng to the (Smal l Font) versi on
corrects the di spl ay. I f you are usi ng other dri vers, check wi th your PC manual
for i nformati on about avai l abl e graphi cs dri vers.

Creating Applications with RI S 2 - 1

CreatingApplications with RIS
__________________________________________________________________________________________________________________________________________________
2 - 2 Creating Applications with RI S


__________________________________________________________________________________________________________________________________________________
2.
CreatingApplications with RIS
2.1 Introduction to theRIS Development Platform
The I ntergraph Rel ati onal I nterface System (RI S) i s a generi c i nterface to rel ati onal
database management systems (RDBMSs). RI S offers si mul taneous connecti ons to RDBMSs
from many vendors on di ssi mi l ar hardware pl atforms usi ng numerous protocol s. RI S makes
an enti re network of databases avai l abl e as i f there were a si ngl e, l ocal database.
RI S i s based upon a cl i ent/server archi tecture. The cl i ent requests i nformati on from the
server. The server then retri eves the i nformati on from the database and returns i t to the
cl i ent.
When you downl oad the RI S Devel opment Pl atform or any data server, the RI S Cl i ent and
RI S Uti l i ti es are automati cal l y i ncl uded as one package.
The RI S Cl i ent provi des the executabl e necessary to communi cate wi th the RI S data server,
as wel l as several other necessary fi l es. The features of the RI S Cl i ent are documented i n the
RI S SQL Users Guidefor 32-Bit Applications.
Several uti l i ti es for performi ng tasks such as schema management, ad hoc queri es, and bul k
l oadi ng of data are provi ded by RI S Uti l i ti es. The RI S Uti l i ti es features are documented i n
the RI S Utilities Guidefor 32-Bit Applications.
The RI S Devel opment Pl atform (RI SDP) contai ns an Embedded SQL preprocessor for the C
programmi ng l anguage al ong wi th the l i brari es, i ncl ude fi l es, and sampl e programs
necessary for the devel opment of RI S-based appl i cati ons. The RI S Devel opment Pl atform
functi ons and features l et you:
Provi de the same i nterface that I ntergraph uses to bui l d database-i ndependent
appl i cati ons.
Embed SQL statements i n Mi crosoft Vi sual C++ source code. Onl y standard C code i s
acceptabl e.
Provi de a si ngl e i nterface to mul ti pl e brands of rel ati onal databases.
Provi de the remote access bui l t i nto RI S.
Support numerous network protocol s.
El i mi nate expensi ve network products.

Access I BM/MVS envi ronments.
Provi de capabi l i ti es across I ntergraph, Sun SPARC, and PC pl atforms.
The RI S i nterface i s based on the Ameri can Nati onal Standards I nsti tute (ANSI ) Structured
Query Language (SQL) standard and i s therefore compati bl e wi th al l RDBMSs that are
compati bl e wi th the standard.
2.2 Products Needed to UsetheRIS Development Platform
Mi crosoft Vi sual C++ 2.0 (or l ater)
Shamrock (for embedded RI S forms cal l s) (Wi n32)
See the RI S I nstallation Guidefor 32-Bit Applications for i nformati on on the product
requi rements for usi ng the RI S Devel opment Pl atform.
2.3 Changes to theSoftware
I f you are currentl y usi ng an earl i er versi on of RI S, read the secti on Changes toThis Version
of RI S before usi ng RI S 5. Several i mportant changes have been made to the software.
2.4 On-lineHelp
On-l i ne Hel p i s now avai l abl e for some RI S pl atforms. For more i nformati on see the RI S
I nstallation Guidefor 32-Bit Applications.
2.5 Embedded SQL Standard
RI S uses Embedded SQL as i ts i nterface l anguage. The Embedded SQL i nterface i s an ANSI
Standard SQL (X3.135-1989) program i nterface that permi ts SQL statements i n C l anguage
source code. These statements can di rectl y access program vari abl es to enter and retri eve
data.
The currentl y adopted SQL standard i s defi ci ent i n handl i ng dynami c SQL statements
(statements not known unti l program executi on ti me). Because the proposed revi si on to the
SQL standard does address these i ssues, RI S has i ncorporated some features from the
proposed revi si on. However, i f these features are not adopted as currentl y proposed, changes
to RI S shoul d conform to the features as they are eventual l y adopted.

2.6 RIS Preprocessor
To process C source code contai ni ng Embedded SQL, run the source code through the RI S
preprocessor riscpp.exe. The envi ronment vari abl e RI S_LANGUAGE speci fi es the l anguage
that riscpp.exeuses for parsi ng and error messages. The defaul t l anguage i s Engl i sh. See
the RI S SQL Users Guidefor 32-Bit Applications for more i nformati on about l anguage
vari abl es.

The RI S Preprocessor provi ded wi th the RI S Devel opment Pl atform i s dependent on
Mi crosoft Vi sual C++ 2.0 or l ater and onl y standard C code i s acceptabl e. You must
l oad Mi crosoft Vi sual C++ and pl ace i t i n your path before usi ng the preprocessor.
The riscpp.exepreprocessor automati cal l y tri es to l i nk wi th the User Message System (UMS)
l i brary. I f the UMS l i brary does not exi st, riscpp.exereturns an error. The riscpp.exe
preprocessor al so cal l s the Mi crosoft Vi sual C++ compi l er to compi l e and l i nk the program,
unl ess di rected otherwi se, and creates an executabl e.
Fi l es processed by riscpp.exemust end i n the suffi x .rc (for exampl e, filename.rc). The
preprocessor can be i nvoked as fol l ows:
riscpp.exe [<flags>] [@command file] <filename>
Flag
_____
Description
___________
-r Preprocesses the fi l e, but does not compi l e. The resul ti ng
fi l e has a .c suffi x. I f you do not speci fy thi s opti on, the .c
fi l e i s compi l ed and then del eted.
-l Does not pl ace #l i ne di recti ves i n the .c fi l e. Thi s makes
the .c fi l e easi er to debug.
-I <di r> Searches for i ncl ude fi l es i n di rectory <di r>.
-V Di spl ays the versi on of RI S.
-ext Speci fi es an al ternate ri scpp.exe fi l e extensi on. The
defaul t extensi on i s *.rc.
-DWI N32 Requi red i f compi l er i s cal l ed outsi de ri scpp.exe.

Any non-ri scpp fl ags passed to riscpp.exeare further passed on to the compi l er.
The riscpp.exepreprocessor returns zero (0) to the shel l i f the program was processed
successful l y and one (1) i f unsuccessful . When the -r opti on i s used, the .c fi l e must be
compi l ed and l i nked manual l y.

LinkingFiles
The fol l owi ng l i sts show the order and names of the l i nk fi l es and the products wi th whi ch
they are associ ated:
Library/ Object File
___________________
Description
___________
Users l i brari es/objects User created l i brari es of objects.
<RI SDP>\ri s.l i b RI S l i brary (requi red).
<RI SDP>\ri sforms.l i b RI S l oad/unl oad l i brary (needed onl y
when l oadi ng/unl oadi ng data).
<RI SDP>\ri sl dul d.l i b RI S l oad/unl oad l i brary (needed onl y
when l oadi ng/unl oadi ng data).
<MSVC>\msvcrt.l i b The C runti me l i brary.
<MSVC>\kernel 32.l i b Wi n32api l i brary.
<MSVC>\advapi 32.l i b Advanced api l i brary.
<MSVC>\user32.l i b Needed for message boxes.
<SHARE>\i 9shamr2.dl l Shamrock DLL, del i vered wi th the
shared component (needed at runti me).
<SHARE>\i 9ums2.dl l UMS DLL, del i vered wi th the shared
component (needed at runti me).

The previ ous tabl e i s based on whether the RI S Devel opment Pl atform product
for 32-bi t appl i cati ons i s i nstal l ed i n the di rectory <RI SDP>(the defaul t
di rectory i s c:\ ProgramFiles\ risdp) and the shared component i s i nstal l ed i n
the di rectory <SHARE>(the defaul t di rectory i s c:\ ProgramFiles\ Common
Files\ I ntergraph). The <MSVC>di rectory i s the l ocati on of the Mi crosoft
Vi sual C++ Tool s software (the defaul t di rectory i s c:\ msvc20\ lib).

The fol l owi ng fi gure shows the steps taken when processi ng a 32-bi t RI S fi l e.

Examples
Creati ng an executabl e .exefi l e di rectl y from the .rc fi l e:
riscpp.exe -DWIN32 main_app.rc
OR
riscpp.exe -DWIN32 main.rc func1.rc func2.rc -I c:\myapp\include
riscpp.exepreprocesses three fi l es: main.rc, func1.rc, func2.rc. I t then produces the
fi l es: main.c, func1.c, and func2.c. The preprocessor i nvokes the compi l er and
automati cal l y compi l es the .c fi l es to produce the .obj fi l es. I t then i nvokes the l i nker to
l i nk the .obj fi l es wi th the l i brari es and creates an executabl e. The -I opti on di rects the
compi l er to the di rectory c:\ myapp\ include.
Preprocessi ng the .rc fi l e usi ng riscpp.exewi th the -r opti on:
riscpp.exe -r main_app.rc
After the .c fi l e i s generated, compi l e the .c fi l e and l i nk i t wi th the requi red l i brari es
usi ng the Mi crosoft Vi sual C++ compi l er as fol l ows:
cl -DWIN32 main_app.c
c:\Program Files\risdp\lib\ris.lib
kernel32.lib advapi32.lib user32.lib

Files
_____
<RI SDP>\ bin\ riscpp.exe
<RI SDP>\ lib\ ris.lib
<RI SDP>\ include\ ris.h
<RI SDP>\ include\ ris_err.h
<RI SDP>\ include\ net_err.h
<RI SDP>\ include\ rislimit.h
<RI SDP>\ include\ ris.prt
<SHARE>\ ris<major.minor>\ config\ english\ messages\ ris.msg
The major and minor versi on numbers are determi ned as fol l ows:
I n the product rel ease number 05.01, the major number i s 05 and the minor number i s 01.
Status Returns
______________
0 Normal termi nati on.
1 Abnormal termi nati on.

2.7 Error Handling
RI S returns a status code for each statement executed. I f a statement generates an error
whi l e the program i s runni ng, the gl obal i nteger vari abl e SQLCODE (uppercase) i s set to a
negati ve val ue.
Exception handlers are effecti ve for handl i ng errors. RI S provi des two devi ces for
constructi ng excepti on handl ers.
The whenever cl ause
Use the whenever cl ause to defi ne an excepti on handl er to conti nue, perform a goto, or
defi ne other acti ons when an error or END_OF_DATA occurs. See the whenever
statement descri pti on for more i nformati on.
The report error statement can be used to retri eve the message resul ti ng from an error.
For more i nformati on, see the report error statement descri pti on.
The rissqlca structure
Addi ti onal nonstandard error handl i ng capabi l i ti es are provi ded through an sqlca
structure. Al though the sqlca structure i s not menti oned i n ei ther the currentl y
adopted standard or i n the proposed standard, al l popul ar database systems provi de
some form of i t. Therefore, to gi ve appl i cati ons more unformatted error i nformati on,
RI S provi des poi nters to two error structures of the type rissqlca.
risca i s a poi nter to a rissqlca error structure that contai ns more detai l ed error
i nformati on. Currentl y, risca gi ves i nformati on onl y when an error occurs by fi l l i ng i n
the sqlcodeand sqlerrmfi el ds wi th a RI S error code and message. The sqlcodefi el d
al ways contai ns the same val ue as the SQLCODE i nteger vari abl e.
The rissqlca structure i s:
typedef struct rissqlca {
char sqlcaid[8];
long sqlabc;
long sqlcode;
struct {
char sqlerrmc[512];
short sqlerrml;
short pad;
} sqlerrm;
char sqlerrp[8];
long sqlerrd[8];
char sqlwarn[8];
char sqlext[8];
char *sqlstmt;
} rissqlca;

Type
_____
Name
______
Description
___________
char [8] sql cai d SQLCAxxx ai d for readi ng memory dumps.
l ong sql abc Length (i n bytes) of the rissqlca structure.
l ong sql code Most recent error code.
char [512] sql errmc SQL error message correspondi ng to SQL
code.
short sql errml Length of the stri ng i n the sqlerrmcfi el d.
short pad Not used.
char [8] sql errp Not used.
l ong [8] sql errd I nternal use onl y.
char [8] sql warn SQL Warni ng Fl ag.
char [8] sql ext Not used.
char * sql stmt Poi nter to i nternal SQL statement buffer.
RI S al so provi des the poi nter dbca that poi nts to a rissqlca structure contai ni ng the
error number and message from the underl yi ng DBMS. Thi s structure provi des
database-speci fi c error i nformati on and can onl y be accessed through the dbca poi nter.
Onl y the sqlcodeand sqlerrmfi el ds are currentl y supported.

Usi ng the dbca poi nter renders your appl i cati on nonportabl e because
i nformati on contai ned i n the rissqlca structure i s speci fi c to a parti cul ar
database system and di fferent database systems support di fferent
structure fi el ds. Use the dbca poi nter onl y for i nformati onal purposes.

2.8 Host Variables
RI S supports the use of C l anguage host variables wi thi n SQL statements. These vari abl es
are passed on to the C compi l er. Therefore, they need not be defi ned anywhere el se, but they
must conform to C syntax.
To use host vari abl es, they must:
Be defi ned (or decl ared, i n the case of an external vari abl e) wi thi n an SQL
decl arati ve secti on.
Conform to C syntax.
Be preceded by a col on (:) when referenced.
The fol l owi ng C data types are supported for host vari abl es:
I nteger 2 byte: short
4 byte: int
Fl oati ng Poi nt Si ngl e preci si on: float
Doubl e preci si on: double
Character Poi nter: char *
Stri ng: char[] (NULL termi nated by RI S)
Examples
_________
exec sql begin declare section;
char building_name[15];
char drawing_rev[15];
long drawing_rev_ind;
char *error_ptr;
exec sql end declare section;
Once decl ared, host vari abl es can be used i n the fol l owi ng i nstances:
I nput or output buffers.
Asynchronous statement i denti fi ers.
I nsert: val ues l i st, sel ect l i st, or val ues i n the wherecl ause of the sel ect
statement.
Update: assi gnment expressi on or val ues i n the wherecl ause.
Delete: val ues i n the wherecl ause.
Select: vari abl es i n the into cl ause, val ues i n the whereor havingcl auses.

Examples
_________
exec sql insert into location (building_name, room_no, location_no)
values (:building_name, :room_no, :location_no);
Host vari abl es cannot be di rectl y referenced from a dynami c SQL stri ng (an SQL statement
not known at compi l e ti me). To parameteri ze a dynami c SQL statement, use a questi on
mark (?) for the unknown val ue. The questi on mark repl aces the host vari abl e i n the SQL
statement. Later, when the statement i s opened or executed, host vari abl es can be bound to
the questi on mark wi th the usingcl ause. Dynami c SQL statements are di scussed further i n
the secti ons Dynamic Noncursor SQL Statements and Dynamic Cursor SQL Statements.
Indicator Variables
I ndicator variables can be used to manage NULL data. These vari abl es are constructed by
fol l owi ng a host vari abl e wi th the i ndi cator vari abl e (for exampl e, :vari abl e1:i ndi cator1).
I ndi cator vari abl es are l ong i ntegers that can opti onal l y be used, wi th i nput or output
vari abl es, to i ndi cate i f a NULL val ue i s bei ng i nserted or retri eved. These vari abl es can al so
be checked to see whether data i nput or output i s NULL and are useful i n trappi ng
i nput/output errors. For exampl e, a host vari abl e used wi th an i ndi cator vari abl e for data
i nput woul d trap NULL data and prevent an attempt to i nput a NULL val ue i nto a col umn
decl ared wi th the not null keywords.
NULL val ues are i ndi cated as fol l ows:
Val ue < 0 i ndi cates a NULL
Val ue >= 0 i ndi cates not NULL
Examples
_________
exec sql select emp_no, emp_name
into :employee_no, :employee_name:emp_name_ind
from employee where emp_no = :emp_in_no;
exec sql insert into location (building_name, room_no,
location_no, drawing_no, drawing_rev)
values (:building_name, :room_no, :location_no
:drawing_no:drawing_no_ind,
:drawing_rev:drawing_rev_ind);
Virtual Variables
Because the SQL Standard uses si mpl e scal ar types for host vari abl es, RI S provi des a speci al
vari abl e decl arati on format to al l ow compl ex typi ng and addressi ng expressi ons for host
vari abl es. Thi s format i s cal l ed a virtual variabledeclaration. Vi rtual vari abl e decl arati ons
do not resul t i n any addi ti onal C code.

The syntax of the vi rtual vari abl e decl arati on i s:
virtual <C type> <virtual variable> as <address expression>
Keyword/ I dentifier
__________________
Description
___________
<virtual variable> Name to use as a host vari abl e wi thi n the SQL statements.
The name i s mapped by the preprocessor to the address
expressi on gi ven i n the <address expression>cl ause. The
vi rtual vari abl e i s essenti al l y a macro for the address
expressi on.
<C type> Scal ar C l anguage type assi gned to the vi rtual vari abl e. The
preprocessor i nterprets the vi rtual vari abl e as bei ng of thi s
type.
<address
expression>
Address expressi on for the vi rtual vari abl e. Thi s cl ause i s
substi tuted for the vi rtual vari abl e name whenever i t appears
i n the Embedded SQL statements. Si nce thi s cl ause i s onl y
used as a stri ng substi tuti on, i t i s not necessary that the
vari abl es used i n the address expressi on be decl ared wi thi n
the SQL decl arati on secti on. However, no checki ng i s done to
ensure that thi s cl ause i s correct or i s of the type speci fi ed i n
the <C type> i denti fi er. The cl ause i s passed on i n the C code.
Examples
_________
The fol l owi ng statements compare the contents of pointer1->array2[5] to column1 when
the SQL statement i s executed.
virtual int dummy_var as pointer1->array2[5];
select * from table1 where column1 = :dummy_var;
I ncorrect syntax or addressi ng i n the <address expression>cl ause does not cause the
preprocessor to generate errors, but may cause errors duri ng compi l ati on or at runti me.
I n the fol l owi ng secti on of code, an i nteger i i s decl ared. I n the virtual decl arati on, the
address expressi on references i as a poi nter to an i nteger. RI S does not catch thi s error,
but the C compi l er does. The error message i s most l i kel y an illegal operation.
int i;
virtual int my_int as *i;
SeeAlso
________
prepare

2.9 Categories of Embedded SQL Statements
An embedded SQL statement i s si mpl y any SQL statement pl aced di rectl y wi thi n C source
code. However, each SQL statement must be prefi xed by the keywords execsql (uppercase or
l owercase) and termi nated wi th the SQL termi nator (;).
SQL statements are di vi ded i nto four categori es:

1. Stati c statements known at compi l e ti me.
2. Dynami c statements not known unti l runti me.
3. Cursor statements al l select statements (except the speci al select intostatement).
4. Noncursor statements al l other SQL statements (i ncl udi ng the speci al select into
statement).

2.9.1 Static Noncursor SQL Statements
Stati c noncursor statements are easy to use. The SQL statement must si mpl y be prefi xed by
the SQL prefi x and termi nated wi th the SQL termi nator.
RI S keeps stati c, noncursor statements prepared as l ong as possi bl e and then automati cal l y
cl ears them. You can set the number of stati c statements RI S keeps prepared by modi fyi ng
the MAX_STATI C_STMTS parameter. For more i nformati on on thi s parameter and other
performance consi derati ons, see the secti on ProgrammingNotes and Performance
Considerations.
Examples
_________
The fol l owi ng exampl e i nserts the val ues 1 and 2 i nto col1 and col2 of table1, respecti vel y.
exec sql insert into table1 (col1, col2) values (1, 2);
The fol l owi ng exampl e assi gns val ues to the host vari abl es var1 and var2 and i nserts them
i nto table1.
var1 = 1;
var2 = 2;
exec sql insert into table1 (col1, col2) values (:var1, :var2);
The fol l owi ng exampl e i nserts NULL val ues i nto col1 and col2 of table1 by usi ng i ndi cator
vari abl es set to a negati ve number.
ind1 = -1;
ind2 = -1;
exec sql insert into table1 (col1, col2)
values (:var1:ind1, :var2:ind2);

2.9.2 Static Cursor SQL Statements
To use stati c cursor statements (select statements known at compi l e ti me), fol l ow these steps:
1. Decl are a cursor work area for use by the stati c statement and check the syntax of the
statement.
exec sql declare <cursor> cursor for <select-statement>;
2. Open the cursor to execute the statement and set up a cursor for fetchi ng.
exec sql open <cursor>;
3. Fetch the i nformati on to retri eve one row of resul ts from the cursor. To retri eve
another row of resul ts, i ssue the fetch statement agai n. When there are no more resul t
rows, SQLCODE i s set to END_OF_DATA.
loop
exec sql fetch <cursor> into <host variables>;
until END_OF_DATA;
4. Cl ose the cursor. When a cursor i s cl osed and then reopened, i t wi l l be poi nti ng at the
begi nni ng of the data.
exec sql close <cursor>;
5. Cl ear the cursor to free al l memory used by the stati c statement and render the cursor
usel ess. The cursor cannot be reopened once cl eared.
exec sql clear cursor <cursor>;
Examples
_________
The fol l owi ng exampl e decl ares the cursor curs1. When opened, curs1sel ects col1 and
col2 from table1. The two col umns are then fetched i nto the host vari abl es result1and
result2.
exec sql declare curs1 cursor for select col1, col2 from table1;
exec sql open curs1;
do
{
exec sql fetch curs1 into :result1, :result2;
}
while ( SQLCODE != END_OF_DATA );
exec sql close curs1;
exec sql clear cursor curs1;

The fol l owi ng exampl e decl ares the cursor curs1. When opened, curs1sel ects col1 and
col2 from table1. The two col umns are then fetched i nto the host vari abl es result1and
result2. The i ndi cator vari abl e i s set to a negati ve val ue i f the col umn retri eved had a
NULL val ue i n i t.
exec sql declare curs1 cursor for select col1, col2 from table1;
do
{
exec sql fetch curs1 into :result1:ind1, :result2 :ind2;
}
while ( SQLCODE != END_OF_DATA );

2.9.3 Dynamic Noncursor SQL Statements
RI S provi des two ways to use dynami c noncursor statements wi thout i nput parameters.
Ei ther prepare and then execute the statement, or use the executeimmediatestatement.
Dynami c noncursor statements wi th i nput parameters (speci fi ed by a questi on mark (?) i n
the SQL stri ng) requi re parameter defi ni ti on for i nput buffers. The i nput buffers can be
defi ned wi th host vari abl es or wi th a descri ptor. Descri ptors permi t the number and types of
parameters to be determi ned at runti me.
Hints:
______
For nonsel ect statements wi th no parameters, use executeimmediate.
For nonsel ect statements wi th parameters, use the prepareand executestatements.
Use host vari abl es i f you know the number and types of parameters needed by the
statement.
Use descri ptors i f the number and types of parameters needed by the statement are
unknown unti l runti me.
When usi ng host vari abl es i n nonsel ect statements wi th parameters, these steps are needed:
1. Prepare the statement.
exec sql prepare <stmt_id> from <host_string>;
2. Execute the statement usi ng the host vari abl es.
exec sql execute <stmt_id> using <host vars>;
3. Cl ear the statement.
exec sql clear <stmt_id>;
When usi ng descri ptors, the fol l owi ng steps are needed:
exec sql prepare <stmt_id> from <host_string>;
2. Descri be the SQL descri ptor.
exec sql describe input <stmt_id> using descriptor <descriptor>;

3. Execute the statement usi ng the descri ptor.
exec sql execute <stmt_id> using descriptor <descriptor>;
4. Cl ear the statement.
exec sql clear <stmt_id>;
Examples
_________
The fol l owi ng exampl es demonstrate the two ways to dynami cal l y execute an insert
statement. The fi rst way assi gns the statement to the character poi nter char_ptr,
prepares intostatement I D stmt1, executes, and cl ears. The second way uses the
executeimmediatestatement for the same task.
strcpy(char_ptr, "insert into t1 values (1,2)");
exec sql prepare stmt1 from :char_ptr;
exec sql execute stmt1;
exec sql clear stmt1;
OR
exec sql execute immediate "insert into t1 values (1,2)";
The fol l owi ng exampl e executes a parameteri zed insert statement. The val ues i nserted
i nto the tabl e are speci fi ed (i n the statement stri ng) usi ng questi on marks (?). The
usingcl ause i n the executestatement substi tutes the appropri ate host vari abl es var1
and var2 for the two questi on marks.
strcpy(char_ptr, "insert into t1 values (?,?)");
exec sql prepare stmt1 from :char_ptr;
var1 = 1;
var2 = 2;
exec sql execute stmt1 using :var1, :var2;

The fol l owi ng exampl e executes a noncursor statement that i s not known at compi l ati on
ti me. Thi s statement may or may not have parameters. I f i t has parameters, al l ocate a
si ngl e sqlda structure and one sqlvar structure for each parameter. These structures
must then be fi l l ed wi th i nformati on about the i nput data buffers bei ng bound to the
parameters. See the statement descri pti on and the usingcl ause descri pti on for more
i nformati on about the sqlda and sqlvar structures.
exec sql prepare stmt2 from :sql_string1;
desc1 = (sqlda *)malloc(sizeof(sqlda));
desc1->sqln = 0;
exec sql describe input stmt2 using descriptor desc1;
desc1->sqln = desc1->sqld;
desc1->sqlvar = (sqlvar *)malloc(sizeof(sqlvar)*desc1->sqln);
exec sql describe input stmt2 using descriptor desc1;
for (i=0;i < desc1->sqld;i++)
{
desc1->sqlvar[i].sqldata = malloc(desc1->sqlvar[i].sqllen);
desc1->sqlvar[i].sqlind = (long *)malloc(sizeof(long));
*desc1->sqlvar[i].sqldata = i;
*desc1->sqlvar[i].sqlind = 0;
}
exec sql execute stmt2 using descriptor desc1;

2.9.4 Dynamic Cursor SQL Statements
To i mpl ement a dynami c cursor statement, fol l ow these steps:
exec sql prepare <stmt> from <host select string>;
2. Descri be the SQL descri ptor for i nput.
exec sql describe input <stmt> using descriptor <descriptor>;
3. Descri be the SQL descri ptor for output.
exec sql describe output <stmt> using descriptor <descriptor>;
4. Decl are the cursor.
exec sql declare <cursor> for <stmt>;
5. Open the cursor.
exec sql open <cursor> [using <input information>];
6. Fetch the i nformati on.
loop
exec sql fetch <cursor> [using <output information>];
until END_OF_DATA
7. Cl ose the cursor.
8. Cl ear the cursor.
exec sql clear cursor <cursor>;
The describe, declare, and open statements can be ordered as needed. However, si nce the
open statement uses i nput i nformati on, al l i nput i nformati on must be fi l l ed i n before thi s
statement i s executed.
Use the describestatement to determi ne how many sqlda and sqlvar structures are needed
for i nput or output vari abl es. You must al l ocate one sqlda for i nput and one sqlda for output.
Addi ti onal l y, an sqlvar for each i nput and output vari abl e must be al l ocated. For more
i nformati on on usi ng the describestatement, see the describestatement descri pti on.

Examples
_________
The fol l owi ng exampl e i s si mi l ar to the previ ous exampl e for a dynami c noncursor statement.
I t di ffers i n that you must al l ocate and fi l l i n another sqlda structure and a set of sqlvar
structures to defi ne the output buffers for the fetched data. See the describestatement
descri pti on and the usingcl ause descri pti on for more i nformati on.
prepare stmt3 from :sel_string3;
in_desc = (sqlda *)malloc(sizeof(sqlda));
in_desc->sqln = 0;
exec sql describe input stmt3 using descriptor in_desc;
in_desc->sqln = in_desc->sqld;
in_desc->sqlvar = (sqlvar *)malloc(sizeof(sqlvar)*in_desc->sqln);
exec sql describe input stmt3 using descriptor in_desc;
for (i=0;i < in_desc->sqld;i++)
{
in_desc->sqlvar[i].sqldata = malloc(in_desc->sqlvar[i].sqllen);
in_desc->sqlvar[i].sqlind = (long *)malloc(sizeof(long));
*in_desc->sqlvar[i].sqldata = i;
*in_desc->sqlvar[i].sqlind = 0;
}
out_desc = (sqlda *)malloc(sizeof(sqlda));
out_desc->sqln = 0;
exec sql describe output stmt3 using descriptor out_desc;
out_desc->sqln = out_desc->sqld;
out_desc->sqlvar = (sqlvar *)malloc(sizeof(sqlvar)*out_desc->sqln);
for (i=0;i < out_desc->sqld;i++)
{
out_desc->sqlvar[i].sqldata = malloc(out_desc->sqlvar[i].sqllen);
out_desc->sqlvar[i].sqlind = (long *)malloc(sizeof(long));
}
exec sql declare curs3 cursor for stmt3;
exec sql open curs3 using descriptor in_desc;
do
{
exec sql fetch curs3 using descriptor out_desc;
}
while (SQLCODE != END_OF_DATA);

2.10 MultipleTransactions
The mul ti pl e transacti ons abi l i ty i s speci fi ed by the MAX_TRANSACTI ONS parameter i n
the parms fi l e. MAX_TRANSACTI ONS speci fi es the maxi mum number of statements
executi ng si mul taneousl y. Thi s l i mi t al so speci fi es the number of asynchronous I Ds.
Notes
______
Onl y one transacti on at a ti me can be i n progress for a si ngl e schema.
The defaul t val ue for MAX_TRANSACTI ONS i s 1.
A new transacti on i s automati cal l y started each ti me a new schema i s referenced.
The default schema statement can be used to swi tch between transacti ons wi thout
affecti ng thei r state.
The RI Sget_schema_transactionsfuncti on can be used to fi nd the schemas wi th
transacti ons i n progress.
For more i nformati on about mul ti pl e transacti ons, see the secti on Asynchronous Execution of
Statements.

2.11 Asynchronous Execution of Statements
Formerl y, RI S onl y executed statements synchronousl y. Thi s meant that each statement
had to execute to compl eti on before control was returned to the appl i cati on. Now RI S al so
supports asynchronous executi on of statements. I n asynchronous executi on, RI S l ets
appl i cati ons start the executi on of a statement and then i mmedi atel y returns control to the
appl i cati on. The appl i cati on can then check the status of the statement to determi ne i f i t has
compl eted. A good use of thi s asynchronous capabi l i ty i s to execute an SQL statement, then,
whi l e that statement i s processi ng, have the appl i cati on i ni ti al i ze a form or conti nue other
noncri ti cal processi ng that does not depend on the outcome of the processi ng SQL statement.
Notes
______
The i nterface for asynchronous executi on i s bui l t around the dynami c SQL i nterface,
speci fi cal l y the prepare, execute, decl are, open, fetch, and cl ose sequences.
Onl y one SQL statement can be i n progress per schema at any ti me. I f another
asynchronous statement i s i ssued for the same schema, the error Theserver is already
executinga statement i s returned.
I f multipletransactions i s enabl ed, statements can be executed i n paral l el for mul ti pl e
schemas.
Test and wai t compl eti on can be done for a l i st of asynchronous i denti fi ers, al l
i denti fi ers, any i denti fi er, or usi ng a descri ptor.
Test and wai t compl eti on statements return one of four condi ti ons:
RI S_SUCCESS
END_OF_DATA
STATEMENT_FAI LED
STATEMENT_NOT_COMPLETE
The report error for asynchronous statement can be used to get the statement status.
exec sql report error for async :async_id;
The RI Sget_async_stmts functi on can be used to fi nd al l pendi ng asynchronous
statements.

To i mpl ement asynchronous processi ng, fol l ow these steps:
1. Add the asynckeyword and a host vari abl e for the asynchronous statement i denti fi er to
the embedded SQL statement.
exec sql insert into tools (hammer, 2000, 9.95);
becomes
exec sql async :async_id insert into tools (hammer, 2000, 9.95);
2. Determi ne when the statement compl etes executi on by usi ng a test or wai t compl eti on
statement.
exec sql test :async_id completion;
OR
exec sql wait :async_id completion;
3. Cl ear the async_id when the statement has compl eted.
exec sql clear async :async_id;
For more i nformati on about mul ti pl e transacti ons, see the secti on MultipleTransactions.
Examples
_________
The fol l owi ng exampl e executes an i nsert statement asynchronousl y.
main()
{
int asyncl;
exec sql default schema schl;
/*
** The following asynchronous insert statement returns control
** immediately to the application, while executing the insert
** statement as a background process. So that, application can
** go ahead and execute another asynchronous statement on
** another schema.
*/
exec sql async :asyncl insert into table1 values (ris_async_test);
/*
** Check to see if the statement is completed
*/
exec sql test :asyncl completion;
/* If the statement has not completed, then wait for its
** completion before proceeding further (if necessary)
*/

if( SQLCODE == STATEMENT_NOT_COMPLETE )
{
exec sql wait :asyncl completion;
}
/*
** clear the memory associated with the asynchronous id (asyncl).
*/
exec sql clear async :asyncl;
}
Using Binary and Text Data 3 - 1

UsingBinary and Text Data
__________________________________________________________________________________________________________________________________________________
3 - 2 Using Binary and Text Data


__________________________________________________________________________________________________________________________________________________
3.
UsingBinary and Text Data
RI S now supports l ong bi nary and text data types for use i n pi cture or document storage.
These new data types are RI S_BLOB and RI S_TEXT.
Nei ther RI S_BLOB nor RI S_TEXT i s transportabl e. Therefore, they cannot be used as
embedded RI S l oad or unl oad objects.

To unti l i ze RI S_BLOB and RI S_TEXT data types, the cl i ent and server must
both be runni ng at l east RI S 5.1.1.
3.1 RIS_BLOB
The RI S_BLOB data type can be used i n embedded insert, update, and fetch statements to
mani pul ate data i n a fi l e or character poi nter array. I t cannot be used i n i ndexi ng or i n
where, order, or group cl auses.
The fi el ds of the RI S_BLOB structure are descri bed i n the fol l owi ng tabl e. See the ris.h fi l e
for the actual structure decl arati on.
Data Type
__________
Name
______
Description
___________
char *fi l ename Poi nter to the ful l path for the
fi l ename hol di ng the bl ob data.
char *array Poi nter to the character array
hol di ng the bl ob data.
unsi gned i nt array_si ze Si ze of the character array.
unsi gned i nt i nput_l en Total l ength of the bl ob data
i nserted. Thi s val ue i s returned
by the server. Use thi s fi el d onl y
for i nserti on.
unsi gned i nt output_l en Actual l ength of the bl ob data
retri eved. Thi s val ue i s returned
for retri eval .

unsi gned i nt fi l e_offset Offset of the fi l e where the bl ob i s
to be appended. Use thi s fi el d onl y
for retri eval .
0 = fi l e i s to be overwri tten.
unsi gned char fi l e_used 1 = a fi l e i s to be used.
0 = a character array i s to be used.
char pad[11] Not used.

The fi el ds i n thi s structure must be set before accessi ng bl ob data as i nput or
output parameters through the sqlvar structure.
Because RI S does not track the data object l ength, your appl i cati on must track thi s l ength.
Therefore, the array_sizefi el d must be suffi ci entl y al l ocated to hol d the enti re bl ob. RI S
makes no attempt to ensure thi s array i s properl y al l ocated.
Duri ng an i nsert, RI S returns an error i f the fi l e si ze i s l arger than the bl ob col umn si ze.
However, I NFORMI X and ORACLE al l ow the i nserti on of bl ob data l arger than the speci fi ed
bl ob col umn si ze.
Duri ng a retri eval , the data i s truncated i f the array si ze i s smal l er than the col umn si ze. No
truncati on occurs when usi ng a fi l e.
The file_offset fi el d offers a conveni ent way to fetch mul ti -bl ob col umns i nto one fi l e. RI S
appends the bl ob data to the fi l e by the si ze speci fi ed i n the file_offset fi el d. The data i s
appended to the end of the fi l e i f the file_offset fi el d speci fi es a l ength exceedi ng the current
fi l e si ze. I f the fi l e does not exi st, RI S creates the output fi l e and i gnores the file_offset fi el d.
To overwri te an exi sti ng fi l e, set file_offset to zero.
Examples
_________
#include <stdio.h>
#include <fcntl.h>
#include <errno.h>
#include "ris.prt"
extern char * calloc();
main()
{
/*
** Host variable declarations
*/
ris_blob in_picture;
ris_blob out_picture;
int id;
char name[30];
char *err_ptr;
/*
** Define exception handlers
** i.e., if SQL error detected goto label error
** if no more rows detected goto label not_found
*/

exec sql whenever sqlerror goto :error;
/*
** Default to schema risblob (static SQL with no parameters)
*/
exec sql default schema ifxblobtest;
printf("Create table employee\n");
exec sql create table employee(id int, name char(30),
picture ris_blob(200000));
/*
** Insert into table employee using file
*/
in_picture.filename = "c:\\users\\default\\blob.out";
in_picture.file_used= 1;
id=0;
strcpy(name,"Joe Buddy");
/*
** Prepare & execute the static insert statement
*/
exec sql insert into employee(id, name, picture)
values(:id, :name, :in_picture);
/*
** Print the size inserted
*/
printf("The size inserted %d\n", in_picture.input_len);
/*
** Select from table employee using file
*/
out_picture.file_used= 1;
out_picture.filename = "c:\\users\\default\\blob.out";
exec sql select picture into :out_picture
from employee where id = 0;
/*
** Print the size selected
*/
printf("The size selected %d\n", out_picture.output_len);
return;
error:
exec sql whenever sqlerror continue;
exec sql report error into :err_ptr;
puts(err_ptr);
exit();
}

The describeSQL statement does not return the actual l ength of the bl ob
col umn i n the sqllen fi el d of the sqlvar structure. RI S sets sqllen to the si ze of
the ris_blob structure. You must query the ris5columns di cti onary tabl e to get
the actual l ength of the bl ob col umn.
3.2 RIS_TEXT
The RI S_TEXT data type can be used i n embedded insert, update, and fetch statements to
mani pul ate data i n a fi l e or character poi nter array. I t cannot be used i n i ndexi ng or i n
where, order, or group cl auses.
The fi el ds of the RI S_TEXT structure are descri bed i n the fol l owi ng tabl e. See the ris.h fi l e
for the actual structure decl arati on.
Data Type
__________
Name
______
Description
___________
char *fi l ename Poi nter to the ful l path for the
fi l ename hol di ng the text data.
char *array Poi nter to the character array
hol di ng the text data.
unsi gned i nt array_si ze Si ze of the character array.
unsi gned i nt i nput_l en Total l ength of the text data
i nserted. Thi s val ue i s returned
for i nserti on.
unsi gned i nt output_l en Actual l ength of the text data
retri eved. Thi s val ue i s returned
for retri eval .
unsi gned i nt fi l e_offset Offset of the fi l e where the text i s
to be appended. Use thi s fi el d onl y
for retri eval .
0 = fi l e i s to be overwri tten.
unsi gned char fi l e_used 1 = a fi l e i s to be used.
0 = a character array i s to be used.
char pad[11] Not used.

The fi el ds i n thi s structure must be set before accessi ng text data as i nput or
accessi ng output parameters through the sqlvar structure.
Because RI S does not track the data object l ength, your appl i cati on must track thi s l ength.
Therefore, the array_sizefi el d must be suffi ci entl y al l ocated to hol d the enti re text fi l e. RI S
makes no attempt to ensure thi s array i s properl y al l ocated.

Duri ng an i nsert, RI S returns an error i f the fi l e si ze i s l arger than the text col umn si ze.
However, I NFORMI X and ORACLE al l ow the i nserti on of text data l arger than the speci fi ed
text col umn si ze.
Duri ng a retri eval , the data i s truncated i f the array si ze i s smal l er than the col umn si ze. No
truncati on occurs when usi ng a fi l e.
The file_offset fi el d offers a conveni ent way to fetch mul ti -text col umns i nto one fi l e. RI S
appends the text data to the fi l e by the si ze speci fi ed i n the file_offset fi el d. The data i s
appended to the end of the fi l e i f the file_offset fi el d speci fi es a l ength exceedi ng the current
fi l e si ze. I f the fi l e does not exi st, RI S creates the output fi l e and i gnores the file_offset fi el d.
To overwri te an exi sti ng fi l e, set file_offset to zero.
Examples
_________
#include <stdio.h>
#include <fcntl.h>
#include <errno.h>
#include "ris.prt"
main()
{
/*
*/
ris_text in_article;
ris_text out_article;
int id;
char name[30];
char *err_ptr;
unsigned int column_len;
int fd, ret_status;
/*
*/
/*
** Default to schema ristext (static SQL with no parameters)
*/
exec sql default schema ifxtexttest;
printf("Create table document\n");
exec sql create table document(id int, name char(30),
article ris_text(200000));

/*
** Select the column size of from ris5column table
*/
exec sql select char_max_length into :column_len from
ris5columns where table_name = document and
column_name = article;
/*
** Insert into table document using char array
*/
fd = open("c:\users\jchang\textdata\texttst1", O_RDWR);
in_article.array= (char *) malloc(column_len);
in_article.file_used= 0;
ret_status= read(fd, in_article.array, column_len);
if (ret_status > 0)
{
in_article.array_size= ret_status;
}
else
{
return;
}
id=0;
strcpy(name,"Southern Living");
/*
** Prepare & execute the static insert statement
*/
exec sql insert into document(id, name, article)
values(:id, :name, :in_article);
/*
** Print the size inserted
*/
printf("The size inserted %d\n", in_article.input_len);
/*
** Select from table document using char array
*/
out_article.array= (char *) malloc(column_len);
out_article.file_used= 0;
exec sql select article into :out_article
from document where id = 0;
/*
** Print the size selected
*/
printf("The size selected %d\n", out_article.output_len);
return;

error:
puts(err_ptr);
exit();
}

The describeSQL statement does not return the actual l ength of the text
col umn i n the sqllen fi el d of the sqlvar structure. RI S sets sqllen to the si ze of
the ris_text structure. You must query the ris5columns di cti onary tabl e to get
the actual l ength of the text col umn.
Dynamic Blob Example
Thi s exampl e can be found i n the fi l e blob2.rc.
#include <stdio.h>
#include <fcntl.h>
#include <errno.h>
#include "ris.prt"
exec sql define MAX_MEM_SIZE 200000;
void main()
{
/*
*/
char sql_stmt[100];
sqlda out_desc;
char *err_ptr;
int id;
char name[30];
ris_blob picture;
/*
** C Program Variables
*/
int i;
ris_blob *blobcol;
ris_text *textcol;
/*
*/
exec sql whenever not found goto :not_found;

/*
** Default to schema sch1 (static SQL with no parameters)
*/
printf("Default to schema sch1\n");
exec sql default schema sch1 ;
/*
** Insert into table employee (dynamic SQL with known parameters)
*/
strcpy(sql_stmt, "insert into employee (id, name, picture)
values(?,?,?)");
/*
** Prepare the dynamic insert statement
*/
printf("Prepare insert statement stmt1\n");
exec sql prepare stmt1 from :sql_stmt;
id = 1008;
strcpy(name,"Bob Shorty");
#if defined(WIN32) || defined(DOS) || defined(WIN32S)
picture.filename = "C:\\users\\hpatel\\blob\\net.msg";
#else
picture.filename = "/usr2/risapp/blob/utl.msg";
#endif
picture.file_used = 1; /* picture data from a file */
/*
** Now, execute the dynamic insert statement
*/
printf("Execute stmt1\n");
exec sql execute stmt1 using :id, :name, :picture;
/*
** Clear the dynamic insert statement
*/
/*
** Update table employee (dynamic SQL with known parameters)
*/
strcpy(sql_stmt, "update employee set picture = ?
where name = Bob Shorty");
/*
** Prepare the dynamic update statement
*/
printf("Prepare update statement stmt2\n");
#if defined(WIN32) || defined(DOS) || defined(WIN32S)
picture.filename = "C:\\users\\hpatel\\blob\\utl.msg";
#else
picture.filename = "/usr2/risapp/blob/utl.msg";
#endif

picture.file_used = 1; /* picture data from a file */
/*
** Now, execute the dynamic update statement
*/
printf("Execute stmt2\n");
exec sql execute stmt2 using :picture;
/*
** Clear the dynamic update statement
*/
/*
** Select from table employee (dynamic cursor SQL)
*/
strcpy(sql_stmt, "select * from employee");
/*
** Prepare the dynamic select statement
*/
printf("Prepare stmt3\n");
/*
** To check if there are any output parameters for stmt3 set
** the following. (for column names > id, name, picture)
*/
out_desc.sqld = 0;
out_desc.sqln = 0;
out_desc.sqlvar = 0;
/*
** RIS will fill the value of sqld if output SQL variables exists
*/
printf("Describe stmt3\n");
/*
** Allocate sqlvars for any output parameters
*/
out_desc.sqlvar = (sqlvar*)calloc(out_desc.sqld, sizeof(sqlvar));
out_desc.sqln = out_desc.sqld;
/*
** Get information about output variables
*/
/*
** Allocate user output buffers for each result column
** (depending upon RIS data type)
*/

for (i = 0; i < out_desc.sqld; ++i)
{
if (out_desc.sqlvar[i].sqltype == RIS_BLOB
|| out_desc.sqlvar[i].sqltype == RIS_TEXT)
{
/*
** Assuming identical blob and text
** structures. Because describing a blob/text
** column will not return the size of
** blob/text column, the size of blob/text
** should be known before hand. Query the RIS
** dictionary table riscolumns to get the size
** of blob/text column size.
*/
out_desc.sqlvar[i].sqldata =
calloc(1, sizeof(ris_blob));
blobcol = (ris_blob *) out_desc.sqlvar[i].sqldata;
blobcol->array = calloc(1, MAX_MEM_SIZE);
blobcol->array_size = MAX_MEM_SIZE;
blobcol->file_used = 0;
}
else
{
out_desc.sqlvar[i].sqldata =
calloc(1, out_desc.sqlvar[i].sqllen);
}
out_desc.sqlvar[i].sqlind = (long*)calloc(1, sizeof(long));
out_desc.sqlvar[i].sqlnull = 1;
}
/*
** Declare a cursor curs1 for select statement
*/
printf("Declare cursor for stmt3\n");
exec sql declare curs1 cursor for stmt3;
/*
** Open cursor curs1
*/
printf("Open cursor for stmt3\n");
for (;;)
{
/*
** Fetch a row of output
*/
printf("Fetch from cursor\n");
exec sql fetch curs1 using descriptor out_desc;
/*
** print all columns of the recently fetched row
*/

for (i = 0; i < out_desc.sqld; ++i)
{
/*
** Print column name
*/
printf ("%-20.20s:",
out_desc.sqlvar[i].sqlname.sqlnamec);
/*
** Check if the value is NULL
*/
if (*out_desc.sqlvar[i].sqlind < 0)
{
printf ("<NULL>\n");
continue;
}
/*
** Determine RIS data type
*/
switch(out_desc.sqlvar[i].sqltype)
{
case RIS_CHARACTER:
printf("%s\n", out_desc.sqlvar[i].sqldata);
break;
case RIS_DECIMAL:
printf("%s\n", out_desc.sqlvar[i].sqldata);
break;
case RIS_INTEGER:
printf("%d\n",
*(int*)out_desc.sqlvar[i].sqldata);
break;
case RIS_SMALLINT:
printf("%hd\n",
*(short*)out_desc.sqlvar[i].sqldata);
break;
case RIS_DOUBLE:
printf("%lf\n",
*(double*)out_desc.sqlvar[i].sqldata);
break;
case RIS_REAL:
printf("%f\n",
*(float*)out_desc.sqlvar[i].sqldata);
break;
case RIS_TEXT:
textcol = (ris_text *)out_desc.sqlvar[i].sqldata;
printf("TEXT Datatype - Size of TEXT is
%d\n", textcol->output_len);
break;
case RIS_BLOB:
blobcol = (ris_blob *)out_desc.sqlvar[i].sqldata;
printf("BLOB Datatype - Size of BLOB
%d\n", blobcol->output_len);
break;

default:
printf("error: unknown output RIS data type");
break;
}
}
printf("\n");
}
not_found:
exec sql whenever not found continue;
printf("No more data\n");
return;
error:
puts(err_ptr);
exit();
}
Embedded SQL Reference 4 - 1

Embedded SQL Reference
__________________________________________________________________________________________________________________________________________________
4 - 2 Embedded SQL Reference


__________________________________________________________________________________________________________________________________________________
4.
Embedded SQL Reference
Thi s secti on contai ns a qui ck reference and an expanded al phabeti cal l i sti ng of the
Embedded SQL statements supported by RI S. I t al so l i sts the i ncl ude fi l es, l i brari es, and
exampl e programs for reference when usi ng Embedded SQL. An exi sti ng knowl edge of the
concepts and the proper usage of an RDBMS i s assumed. For more i nformati on on the use of
RI S Embedded SQL, see the secti on Categories of Embedded SQL Statements. For a more
compl ete descri pti on of rel ati onal theory and i mpl ementati on, refer to a textbook and/or user
and reference manual s for the underl yi ng RDBMS. The fol l owi ng qui ck reference
i nformati on can al so be found i n the RI S SQL Commands Quick Referencecard.

Refer to the RI S SQL Users Guidefor 32-Bit Applications for a compl ete l i sti ng
of the general SQL statements supported by RI S i n both the i nteracti ve and
programmati c i nterfaces.
The notati ons for syntax used throughout thi s document are descri bed i n the
secti on BeforeYou Begin.
4.1 Quick Reference
async
exec sql async <:async_id> <ris sql statement>;
begin declare
clear
exec sql clear { <statement-id> | {cursor <cursor>} };
clear async
exec sql clear async <:async_id>;
close
declarecursor
exec sql declare <cursor> cursor
for { <select-statement> | <statement-id> };

define
exec sql define <name> [ <integer> ];
describe
exec sql describe { input | output } <statement-id> using descriptor <sqlda>;
else
exec sql else;
end declare
endif
exec sql endif;
execute
exec sql execute <statement-id>
[ using { descriptor <sqlda> } | <host variables> ];
executeimmediate
exec sql execute immediate <string>;
fetch
OR
exec sql fetch <cursor> using descriptor <sqlda>;
ifdef
exec sql ifdef <name>;
ifndef
exec sql ifndef <name>;
include
exec sql include { <filename> | "<filename>" };
open
exec sql open <cursor> [ using { descriptor <sqlda> } | <host variables> ];

prepare
exec sql prepare <statement-id> from <string>;
report error
exec sql report error [ for async <:async_id> ] into <char_ptr>;
select into
exec sql select <column-list> into <host variables>
from ... [ where ... ];
sql
exec sql <sql statement>;
test completion
exec sql test { <:async1>, <:async2>, ... | all | any | using
descriptor <desc1> } completion;
undef
exec sql undef <name>;
wait completion
exec sql wait { <:async1>, <:async2>, ... | all | any | using
whenever
exec sql whenever { not found | sqlerror }
{ continue | {goto <C label>} | {go to <C label>} };

4.2 IncludeFiles, Libraries, and ExamplePrograms
The fol l owi ng are SQL i ncl ude fi l es:
ris_err.h
net_err.h
ris.h
rislimit.h
ris.prt
The SQL l i brary i s:
ris.lib
The fol l owi ng are SQL exampl e programs:
async1.rc
async2.rc
asynctrn.rc
datetime.rc
dclar.rc
dynamic.rc
extern.rc
multiple.rc
static.rc
transact.rc
blob1.rc
blob2.rc
loccli.rc
sharedic.rc
secure.rc
union.rc
setup.rc
cleanup.rc
4.3 RIS Embedded SQL Statements
The fol l owi ng al phabeti zed l i st gi ves a detai l ed descri pti on of each Embedded SQL statement
supported by RI S.

async
The asyncstatement executes any RI S SQL statement asynchronousl y. An async_i d
must be associ ated wi th each statement.
exec sql async <:async_id> <ris sql statement>;
Examples
_________
exec sql async :async_id execute immediate "create table t1 (c1 int)";
exec sql async :async_id insert into table t1 values (1);
SeeAlso
________
Asynchronous Executi on of Statements

begin declare
The begin declarestatement marks the begi nni ng of the vari abl e decl arati on secti on
of the program to the preprocessor. Defi ne and decl are al l host vari abl es used i n SQL
statements wi thi n a decl arati on secti on. You must termi nate a decl are secti on wi th
the end declarestatement.
Examples
_________
struct anystruct sa[10];
int i,j;
char buf[20];
virtual int sa_element as sa[i].element;
begin declaremust be speci fi ed at the begi nni ng of a bl ock of code before any
executabl e statements. I n the decl are secti on, use onl y vari abl es i n Embedded SQL
statements. Pl ace al l other l ocal vari abl es i mmedi atel y before or after the decl are
secti on.
Notes
______
The RI S preprocessor supports the fol l owi ng C l anguage data types:
int (4 bytes)
short (2 bytes)
float
double
char*
char[ ]
char[ ] i s NULL-termi nated by RI S i f there i s enough room i n the array.
The RI S preprocessor al so supports the fol l owi ng structures:
blob
datetime
sqlda
text
SeeAlso
________
end decl are

clear
The clear statement frees al l memory for a dynami cal l y prepared statement or a
cursor. The cursor i s rendered usel ess. Once a statement i s cl eared, i t cannot be
used agai n. Once a cursor has been cl eared, i t cannot be reopened. Cl eari ng an open
cursor causes the cursor to cl ose and a commi t i s forced.
exec sql clear { <statement-id> | {cursor <cursor>} };
Examples
_________
exec sql clear cursor c1;
Notes
______
Cl eari ng the statement and cl eari ng the cursor decl ared for i t have the same effect.
I t i s not necessary to cl ear both. I f an attempt i s made to cl ear both the statement
and the cursor, an error i s returned i ndi cati ng the use of an i nval i d statement I D.
SeeAlso
________
cl ose
decl are cursor
execute
execute i mmedi ate
open
prepare

clear async
The clear asyncstatement frees the addi ti onal memory al l ocated for the
asynchronous I D.
exec sql clear async <:async_id>;
Examples
_________
exec sql clear async :async1;
Notes
______
Cl eari ng async I D i s di fferent from cl eari ng a RI S statement. Cl eari ng asynchronous
I D does not cl ear the RI S statement and vi ce versa.

close
The close statement cl oses a cursor. The cursor can be reopened wi th the open
statement or cl eared wi th the clear statement.
Examples
_________
exec sql close c1;
Notes
______
RI S automati cal l y cl oses al l cursors i f a commit or rollback statement i s i ssued or an
error occurs duri ng the executi on of any DML statement. I n autocommi t mode,
cl osi ng a cursor causes a commi t to occur. Thi s then cl oses al l other cursors.
SeeAlso
________
cl ear
decl are cursor
fetch
open

declarecursor
The declarecursor statement decl ares a cursor work area for use by a stati c or
dynami c select statement.
exec sql declare <cursor> cursor
for { <select-statement> | <statement-id> };
__________________
Description
___________
<select-statement> Val i d SQL select statement that sel ects data i nto the cursor.
Use parameters wi thi n the sel ect statement for val ues i n the
wherecl ause or the havingcl ause. For more i nformati on, see
the select statement descri pti on i n the RI S SQL Users Guide.
<statement-id> Name of a dynami cal l y prepared sel ect statement. For more
i nformati on, see the preparestatement.
Examples
_________
exec sql declare c1 cursor for select * from tab1;
exec sql declare c1 cursor for stmt1;
Notes
______
You do not need a cursor for the speci al select intostatement.
I f the select statement onl y retri eves one row of data, use the more si mpl e embedded
select intostatement i nstead of the declare, open, and fetch sequence of statements.
SeeAlso
________
cl ear
cl ose
fetch
open
prepare
sel ect i nto

define
The definestatement assi gns a compi l e-ti me val ue to a name. Thi s assi gnment
occurs duri ng the RI S preprocessi ng stage. I n the statement wi th a normal C
preprocessor #define.
exec sql define <name> [<integer>];
Examples
_________
exec sql define MAX_ID;
exec sql define MIN_ID 10;
Notes
______
The definestatement defi nes onl y i nteger constants. I t does not support defi ni ti on of
stri ng constants or parameteri zed macros.
SeeAlso
________
el se
endi f
i fdef
i fndef
i ncl ude
undef

describe
The describestatement returns i nformati on about the i nput parameters or the output
resul ts of a dynami c SQL statement. Thi s i nformati on i s returned i n a structure of
type sqlda (defi ned i n the fi l e ris.h).
exec sql describe { input | output } <statement-id> using descriptor <sqlda>;
Examples
_________
exec sql describe input s1 using descriptor in_sqlda;
exec sql describe output s1 using descriptor out_sqlda;
Notes
______
When you execute a dynami c SQL statement, you must provi de a si ngl e sqlda
structure and an array of sqlvar structures (one structure for each i nput or output
parameter). For exampl e, the fol l owi ng statement needs one sqlda structure for
output and three sqlvar structures for the output vari abl es a, b, and c. The
statement al so needs one sqlda structure for i nput pl us one sqlvar structure for the
i nput vari abl e d.
select a,b,c from t1 where d = ?
For i nput parameters, the describestatement l ooks for the questi on marks i n the
val ue l i st i n the wherecl ause and assi gnment l i st i n the updatestatement. For
output parameters, the describestatement l ooks for the col umn names i n the select
statement.
sqlda Structure


The sqlda structure consi sts of the fol l owi ng fi el ds:
Data Type
__________
Field
_____
Description
___________
short sql n Number of el ements i n sqlvar
array. I f sqln <= sqld, then RI S
sets the sqld fi el d to the number
of SQL vari abl es. You must
update thi s fi el d.
short sql d Number of SQL vari abl es that
actual l y exi st. I f sqln >= sqld,
then thi s fi el d i ndi cates the
number of SQL vari abl es that
RI S has fi l l ed i n.
I f sqld =0, a nonsel ect statement
(insert, update, or delete) was
executed.
struct sql var *sql var Poi nter to array of sqlvar
structures, one for each i nput or
output SQL vari abl e.
sqlvar Structure
The sql var structure consi sts of the fol l owi ng fi el ds:
Data Type
__________
Field
_____
Description
___________
char *sql data Poi nter to the program data
buffer.
l ong *sql i nd Poi nter to the program i ndi cator
buffer.
short sql type SQL type for the SQL vari abl e:
RI S_BLOB, RI S_CHARACTER,
RI S_DECI MAL, RI S_I NTEGER,
RI S_SMALLI NT, RI S_REAL,
RI S_DOUBLE, RI S_DATETI ME,
RI S_TEXT, RI S_TI MESTAMP.
RI S_UNSUPPORTED_TYPE
i denti fi es unsupported types that
were created outsi de of RI S.
(These constants are defi ned i n
the ris.h i ncl ude fi l e).
short sql nul l Set to nonzero i f NULLs are
al l owed.
short sql l en Length of the SQL vari abl e.
short sql scal e Preci si on and scal e of a SQL
vari abl e of type DECI MAL.
seethefollowingtable sql name Name of the SQL vari abl e.

The sqlnamefi el d i s a nested structure whi ch consi sts of the fol l owi ng fi el ds:
Data Type
__________
Field
_____
Description
___________
short sql namel Length of the name.
char sql namec[34] Name of the SQL vari abl e not
nul l termi nated.
You can use the describestatement to set up the sqlda and sqlvar structures by
fol l owi ng these steps:
1. Usi ng malloc, al l ocate an sqlda structure, but do not fi l l i n the sqld fi el d.
in_sqlda = (sqlda *)malloc(sizeof(sqlda));
out_sqlda = (sqlda *)malloc(sizeof(sqlda));
2. I ssue the describestatement wi th sqln set to zero.
in_sqlda->sqln = 0;
exec sql describe input my_statement using descriptor in_sqlda;
out_sqlda->sqln = 0;
exec sql describe output my_statement using descriptor out_sqlda;
RI S sets the sqld fi el d to the number of sqlvar structures needed.
3. Al l ocate the array of sqlvar structures and set up the sqlda structure.
in_sqlda->sqln = in_sqlda->sqld;
in_sqlda->sqlvar = (sqlvar *)malloc(sizeof(sqlvar)*in_sqlda->sqln);
out_sqlda->sqln = out_sqlda->sqld;
out_sqlda->sqlvar = (sqlvar *)malloc(sizeof(sqlvar)*out_sqlda->sqln);
4. I ssue the describestatement agai n.
exec sql describe input my_statement using descriptor in_sqlda;
exec sql describe output my_statement using descriptor out_sqlda;
RI S sets the fi el ds i n the sqlvar structures for each of the SQL vari abl es.
I f you al ready know whi ch fi el ds need modi fyi ng, ski p thi s step and di rectl y
modi fy those fi el ds. You can modi fy the fol l owi ng fi el ds:
sqlnull: set thi s fi el d to a nonzero val ue i f you want to al l ow NULL val ues.
sqlind: i f sqlnull i s nonzero, set thi s fi el d to the address of an i ndi cator
vari abl e (l ong i nteger). A negati ve number i ndi cates a NULL val ue.
sqltype: set thi s fi el d to a SQL type that i s equi val ent to the C program
vari abl e type.

sqllen: set thi s fi el d to the l ength of the C program vari abl e.
RI S sets sqllen =sizeof(struct ris_blob) for the RI S_BLOB data type and
sqllen =sizeof(struct ris_text) for the RI S_TEXT data type. To determi ne the
actual si ze of the RI S_BLOB or RI S_TEXT data type, query the riscolumns
di cti onary tabl e. See the secti on UsingBinaryand Text Data for more
i nformati on about RI S_BLOB and RI S_TEXT data types.
sqldata: set thi s fi el d to the address of the vari abl e to contai n the i nput or
output val ue. Thi s vari abl e shoul d be compati bl e wi th the type and si ze
i ndi cated i n sqltypeand sqllen.
5. I f you have not al ready, modi fy the sqldata and sqlind fi el ds i n the sqlvar
structure.
in_sqlda->sqlvar[0]->sqldata = &my_data;
in_sqlda->sqlvar[0]->sqlind = &my_indicator;
out_sqlda->sqlvar[0]->sqldata = &my_data;
out_sqlda->sqlvar[0]->sqlind = &my_indicator;
You can speci fy the fol l owi ng keywords wi th the descri be statement:
__________________
Description
___________
output RI S sets sqltypeto the data type, sqllen to the l ength, and
sqlnameto the col umn name, i n the sqlvar structures. You
must set the sqldata and sqlind fi el ds. I f the SQL statement
i s not a select statement, RI S sets sqld to zero (0).
input RI S sets sqltypeto the expected data type, and sqllen to the
l ength, i n the sqlvar structures. You can use a di fferent type
and l ength of vari abl e, but thi s may cause a data conversi on
error. Most numeri c types are i nterchangeabl e, but character
types and numeri c types cannot be i nterchanged.

The val ue returned i n the sqllen fi el d for character col umns i s the
maxi mum l ength of character data. Si nce C stri ngs are nul l termi nated,
al l ocate one extra byte to hol d the nul l termi nator. Otherwi se, the data
may be truncated.

else

The elsestatement, used wi th ifdef or ifndef, control s substi tuti on of C code duri ng
the RI S preprocessi ng stage. I f the ifdef or ifndef condi ti on fai l s, riscpp.exe
substi tutes code fol l owi ng the elsecommand wi th C code for compi l ati on.
exec sql else;
Examples
_________
exec sql ifdef MAX_ID;
printf("MAX_ID is defined\n");
exec sql else;
printf("MAX_ID is not defined\n");
exec sql endif;
Notes
______
Use onl y one elsestatement for every ifdef or ifndef statement.
SeeAlso
________
defi ne
endi f
i fdef
i fndef
i ncl ude
undef

end declare
The end declarestatement i nforms the preprocessor that a vari abl e decl arati on
secti on i s endi ng.
SeeAlso
________
begi n decl are

endif
The endif statement i s the requi red endi ng for every ifdef or ifndef statement.
exec sql endif;
Examples
_________
exec sql endif;
Notes
______
Use onl y one endif statement for every ifdef or ifndef statement.
SeeAlso
________
defi ne
el se
i fdef
i fndef
i ncl ude
undef

execute
The executestatement executes a dynami c noncursor SQL statement agai nst a
database. Use the usingcl ause onl y i f there are i nput parameters i n the prepared
statement. See the describestatement for more i nformati on about i nput parameters.
exec sql execute <statement-id> [ <using clause> ];
__________________
Description
___________
statement-id Name of a dynami cal l y prepared select statement. For more
i nformati on, see the preparestatement.
usingclause Provi des i nformati on about i nput and output buffers. Speci fy
the vari abl es by usi ng host vari abl e names or by fi l l i ng i n an
sqlda structure wi th vari abl e i nformati on:
using<host vari abl es>
OR
usingdescriptor <sql descri ptor area>
Examples
_________
exec sql execute stmt1 using :input1, :input2;
exec sql execute stmt1 using :input1:ind1, :input2:ind2;
exec sql execute stmt1 using descriptor in_sqlda;
Notes
______
The executestatement i s val i d onl y on previ ousl y prepared statements and must be
used on the same schema used to prepare the statement.
I f there are no i nput parameters, use the executeimmediatestatement i nstead.
The executestatement i s not val i d for dynami c cursor statements. Use the open
statement i nstead.
SeeAlso
________
cl ear
descri be
execute i mmedi ate
prepare

executeimmediate
The executeimmediatestatement executes a dynami c noncursor SQL statement
agai nst a database. Thi s statement cannot have any i nput parameters. Use the
prepareand executestatements i f i nput parameters are requi red. Use the open
statement for dynami c cursor statements.
exec sql execute immediate <string>;
__________________
Description
___________
<string> Host vari abl e or stri ng l i teral .
Examples
_________
exec sql execute immediate :sql_string;
exec sql execute immediate "insert into t1 values (1,2)";
Notes
______
The executeimmediatestatement i s the same as executi ng the prepareand execute
statements on a dynami c statement wi thout i nput parameters.
To i mprove performance of executeimmediatestatements executed mul ti pl e ti mes,
spl i t the statement i nto the equi val ent prepareand executestatements. Next, i ssue
the preparestatement onl y once and i ssue the executestatement mul ti pl e ti mes. Thi s
checks the syntacti c correctness of the SQL statement onl y once. For more
i nformati on, see the secti on PreparingStatements.
SeeAlso
________
cl ear
execute
prepare

fetch
The fetch statement retri eves one row of resul ts from a cursor select statement.
OR
exec sql fetch <cursor> using <using clause>;
__________________
Description
___________
<host variables> Speci fi es where to pl ace the resul ts of a stati c select
statement. Speci fy one or more host vari abl es i n the fol l owi ng
form:
{:single_variable[:host_variable] } [, ...]
<usingclause> Provi des i nformati on about i nput and output buffers. Speci fy
OR
Examples
_________
fetch c1 into :output1, :output2;
fetch c1 into :output1:ind1, :output2:ind2;
fetch c1 using descriptor out_sqlda;

Notes
______
When retri evi ng character data (stri ngs), RI S nul l -termi nates the stri ng onl y i f there
i s suffi ci ent space i n the character data buffer.

RI S automati cal l y cl oses al l cursors i f a commit or rollback statement i s
i ssued or an error occurs duri ng the executi on of any DML statement.
SeeAlso
________
cl ear
cl ose
decl are cursor
descri be
open

ifdef
The ifdef statement control s substi tuti on of C code duri ng the RI S preprocessi ng
stage. I f the ifdef condi ti on succeeds, riscpp.exesubsti tutes the code between the
ifdef and endif statements wi th C code for compi l ati on.
exec sql ifdef <name>;
Examples
_________
printf("MAX_ID is defined\n");
exec sql endif;
Notes
______
Every ifdef statement must have a matchi ng endif statement. You can nest the ifdef
statement. You can al so have embedded elsestatements.
SeeAlso
________
defi ne
el se
endi f
i fndef
i ncl ude
undef

ifndef
The ifndef statement control s substi tuti on of C code duri ng the RI S preprocessi ng
stage. I f the ifndef condi ti on succeeds, riscpp.exesubsti tutes the code between the
ifndef and endif statements wi th C code for compi l ati on.
exec sql ifndef <name>;
Examples
_________
exec sql ifndef MAX_ID;
printf("MAX_ID is not defined\n");
exec sql endif;
Notes
______
Every ifndef statement must have a matchi ng endif statement. You can nest the
ifndef statement. You can al so have embedded elsestatements.
SeeAlso
________
defi ne
el se
endi f
i fdef
i ncl ude
undef

include
The includestatement i ncl udes a source fi l e at a speci fi ed poi nt i n the .c fi l e. Thi s
occurs duri ng the RI S preprocessi ng stage.
I f the speci fi ed fi l ename does not exi st i n the l ocal di rectory, riscpp.exel ooks i n the
i ncl ude di rectory search paths gi ven by the -I opti on.
exec sql include {<filename> | "<filename>"};
Examples
_________
exec sql include "filename";
exec sql include filename;
exec sql include "/usr/my_app/filename";
exec sql include /usr/my_app/filename;
Notes
______
You can nest the includestatement.
Quotati on marks around pathnames are opti onal .
SeeAlso
________
defi ne
el se
endi f
i fdef
i fndef
undef

open
The open statement executes the select statement and sets up a cursor for fetchi ng.
exec sql open <cursor> [ <using clause> ];
__________________
Description
___________
<usingclause> Provi des i nformati on about i nput and output buffers. Speci fy
OR
Examples
_________
exec sql open cl;
exec sql open c1 using :input1, :input2;
exec sql open c1 using :input1:ind1, :input2:ind2;
exec sql open c1 using descriptor in_sqlda;
Notes
______
The open statement opens a stati c or dynami c cursor, executi ng the decl ared SQL
statement agai nst a database. The open statement i s onl y val i d for cursors
previ ousl y decl ared wi th the declarestatement.

RI S automati cal l y cl oses al l cursors i f a commit or rollback statement i s
i ssued or an error occurs duri ng the executi on of any DML statement.
SeeAlso
________
cl ear
cl ose
decl are cursor
descri be

prepare
The preparestatement prepares a dynami c SQL statement for l ater use. Prepari ng a
statement checks the statement for proper syntax and i ni ti al i zes the structures to be
used duri ng statement executi on.
exec sql prepare <statement-id> from <string>;
__________________
Description
___________
<statement id> Name consi sti ng of l etters, numbers, and underscores. The
statement I Ds scope i s l i mi ted to the fi l e contai ni ng the
preparestatement.
<string> Character stri ng l i teral (for exampl e: "a string"), a
character poi nter (char *) host vari abl e, or a character array
(char [n]) host vari abl e contai ni ng the SQL statement to be
prepared.
Examples
_________
exec sql prepare c1 from "select * from tab1 where tab1.col1 = ?";
char_ptr = "select * from tab1 where tab1.col1 = ?";
exec sql prepare c1 from :char_ptr;
char_ptr = "insert into tab1 (col1) values (?);
char_ptr = "delete from tab1 where col1 = ?";
strcpy (char_array,"update tab1 set col1 = ? where col1 = ?");
exec sql prepare c1 from :char_array;
Notes
______
Once a noncursor statement i s prepared, i t can be executed numerous ti mes. Use the
executestatement to execute i t. The same schema used to prepare the statement
must be used to execute the statement.
After a cursor statement i s prepared, i t must be decl ared and opened usi ng the
declareand open statements. Once the statement i s prepared and decl ared, i t can be
opened numerous ti mes.
Use parameters, desi gnated by a questi on mark (?), for val ues i n the wherecl ause or
for val ues i n the insert, update, and deletestatements.
SeeAlso
________
cl ear
execute
execute i mmedi ate

report error
The report error statement retri eves the message resul ti ng from the l ast error. I t
returns a poi nter to the message buffer i n the address speci fi ed by the <char_ptr>
i denti fi er. I f an asynchronous I D i s gi ven then the error message retri eved pertai ns
to the statement associ ated wi th the asynchronous I D.
exec sql report error [for async <:async_id>] into <char_ptr>;
__________________
Description
___________
<char_ptr> Poi nter set to the address of the message buffer contai ni ng
the error message. The buffer i s an i nternal RI S buffer and i s
overwri tten whenever the report error statement i s i ssued.
Examples
_________
exec sql report error into :ptr;
SeeAlso
________
whenever

select into
The select intostatement i s a noncursor versi on of select. Thi s statement retri eves
one row from a rel ati on i n the database. The sel ecti on cri teri a (speci fi ed i n the where
cl ause) must match onl y one row. I f more than one match i s found, an error i s
returned. Executi ng a select intostatement mul ti pl e ti mes retri eves the same row
mul ti pl e ti mes.
exec sql select <column-list> into <host variables>
from ... [ where ... ];
Examples
_________
exec sql select column1, column2
into :output1, :output2 from table1;
into :output1, :output2 from table1
where table1.column3 = :input1;
into :output1:ind1, :output2:ind2 from table1;
Notes
______
To sel ect mul ti pl e rows from a rel ati on, use a cursor select statement.
Use host vari abl es i n the intocl ause and for val ues i n the wherecl ause or the having
cl ause.
When retri evi ng character data (stri ngs), RI S nul l -termi nates the stri ng onl y i f there
i s suffi ci ent space i n the character data buffer.
I f select intostatement i s executed i n autocommi t mode, i t causes a commi t to occur.
Thi s cl oses al l open cursors.
SeeAlso
________
sel ect statement

sql

Thi s statement executes a stati c SQL statement. The <SQL statement>cl ause can be
any SQL statement other than the select statement. You must decl are, open, and
fetch al l select statements usi ng the declare, open, and fetch statements.
exec sql <sql statement>;
Examples
_________
exec sql default schema jim;
exec sql insert into table1 values(1, abc, 2.0);
exec sql insert into table1 values(:val1, :val2, :val3);
exec sql insert into table1 select a, b, c from table2 where d = :val4;
exec sql update table1 set column1 = 1, column2 = abc;
exec sql update table1 set column1 = :val1, column2 = :val2;
Notes
______
See the SQL statement descri pti ons i n the RI S SQL ReferenceManual for more
i nformati on on the supported SQL statements.
RI S attempts to keep stati c SQL statements prepared as l ong as possi bl e. You can
confi gure the number of stati c statements RI S keeps prepared i n the RI S parameters
fi l e. RI S automati cal l y cl ears stati c statements when necessary. For more
i nformati on, see the secti on PreparingStatements.
Host vari abl es can be used i n the fol l owi ng Embedded SQL statements:
insert I n the val ues l i st or i n the sel ect l i st, or val ues i n the wherecl ause of
the select statement.
update I n the assi gnment expressi ons or for val ues i n the wherecl ause.
delete For val ues i n the wherecl ause.
SeeAlso
________
execute i mmedi ate

test completion
The test completion statement returns the status of a RI S statement bei ng executed
asynchronousl y. The status can be compl ete, i ncompl ete, or fai l .
exec sql test { <:async1>, <:async2>, ... | all | any | using
The test completion statement can be performed on a speci fi c asynchronous I D, a l i st
of asynchronous I Ds, al l the acti ve asynchronous I Ds, or by usi ng a descri ptor whi ch
can speci fy a l i st of asynchronous I Ds.
The fol l owi ng i s a l i st of the four possi bl e status states and thei r descri pti ons:
__________________
Description
___________
RI S_SUCCESS RI S_SUCCESS status returns i f the
statement was executed successful l y.
SQLCODE i s set to RI S_SUCCESS.
END_OF_DATA END_OF_DATA status i s returned whi l e
executi ng DML statements such as select,
insert, update, or deletei f the operati on coul d
not be compl eted. SQLCODE i s set to
END_OF_DATA.
STATEMENT_FAI LED STATEMENT_FAI LED status i s returned i f
the statement fai l s. SQLCODE i s set to
STATEMENT_FAI LED.
STATEMENT_NOT_COMPLETE STATEMENT_NOT_COMPLETE status i s
returned i f RI S i s sti l l processi ng the
statement. SQLCODE i s set to
STATEMENT_NOT_COMPLETE.
The fi rst three states are referred to as completestates whi l e the fourth state i s
referred to as an incompletestate.
These opti ons gi ve the appl i cati on the fl exi bi l i ty to test for speci fi c asynchronous I Ds.
The status returned depends upon the opti on speci fi ed.
I f one of the statements i n the l i st of asynchronous I Ds i s i ncompl ete, the test
compl eti on statement returns STATEMENT_NOT_COMPLETE status. I f al l the
statements are successful l y compl eted (that i s RI S_SUCCESS state onl y), i t returns
RI S_SUCCESS. The fol l owi ng i s the precedence of status returned:
STATEMENT_NOT_COMPLETE ( highest priority )
STATEMENT_FAILED
END_OF_DATA
RIS_SUCCESS ( lowest priority )

The any cl ause returns the status of the fi rst statement found i n a completestate
(RI S_SUCCESS, END_OF_DATA, or STATEMENT_FAI LED). Otherwi se i t returns
STATEMENT_NOT_COMPLETE. The remai ni ng statements must be tested or an
error i s returned.
Examples
_________
exec sql test all completion;
exec sql test :async1, :async2, :async3 completion;
exec sql test any completion;
int async_ids[2];
sqlvar in_sqlvar[2];
sqlda in_sqlda;
async_ids[0] = 10; /*asynchronous id 10 */
async_ids[1] = 11; /*asynchronous id 11 */
in_sqlvar[0].sqltype = INTEGER;
in_sqlvar[0].sqldata = (char*)&async_ids[0];
in_sqlvar[1].sqltype = INTEGER;
in_sqlvar[1].sqldata = (char*)&async_ids[1];
in_sqlda.sqln = 2;
in_sqlda.sqld = 2;
in_sqlda.sqlvar = in_sqlvar;
exec sql test using descriptor in_sqlda completion;
Notes
______
Executi ng test compl eti on on an asynchronous statement that was al ready
successful l y compl eted (i n any one of the completestates), returns the error An
asynchronous statement has not been specified.

undef
The undef statement removes a defi ned name. Thi s occurs duri ng the RI S
preprocessi ng stage. I n the .c fi l e, riscpp.exesubsti tutes the undef statement wi th a
normal C preprocessor #undef.
exec sql undef <name>;
Examples
_________
exec sql undef MAX_ID;
SeeAlso
________
defi ne
el se
endi f
i fdef
i fndef
i ncl ude

wait completion
The wait completion statement wai ts for the compl eti on of the asynchronous
statements.
exec sql wait { <:async1>, <:async2>, ...| all | any | using
The wait completion statement I D i s i denti cal to the test compl eti on statement except
that there i s no STATEMENT_NOT_COMPLETE return status.
Examples
_________
exec sql wait all completion;
exec sql wait :async1, :async2, :async3 completion;
exec sql wait using descriptor desc1 completion;
Notes
______
Fol l ow the i nformati on gi ven for the test completion statement. The same condi ti ons
appl y for wait completion.
SeeAlso
________
test compl eti on

whenever
The whenever statement decl ares an excepti on (error) handl er or an acti on to perform
when an excepti on occurs.
exec sql whenever { not found | sqlerror }
{ continue | goto <C label> | go to <C label> };
__________________
Description
___________
sqlerror Acti on to occur after an error occurs. sqlcodei s set to a
negati ve val ue.
not found Acti on to occur when there are no more rows to fetch. sqlcode
i s set to END_OF_DATA.
continue I gnore error and conti nue processi ng. Thi s i s not equi val ent
to the C l anguage conti nue statement.
goto Equi val ent to the C l anguage gotostatement.
Examples
_________
exec sql whenever sqlerror goto:error_label;
exec sql whenever not found goto:end_of_data;
Notes
______
The RI S preprocessor determi nes the scope of a whenever statement l i nearl y at
compi l e ti me. The scope i s a functi on of the statements posi ti on i n the source fi l e
onl y.

Use cauti on when handl i ng an error. Executi ng a clear statement or close
statement after an error has occurred may generate further errors. I f a new
whenever statement has not been executed, an i nfi ni te l oop may resul t.
SeeAlso
________
report error

RI S Functions 5 - 1

RIS Functions
__________________________________________________________________________________________________________________________________________________
5 - 2 RI S Functions


__________________________________________________________________________________________________________________________________________________
5.
RIS Functions
Thi s secti on contai ns an al phabeti cal l i sti ng of functi ons supported by RI S. I t al so provi des
reference structures to use wi th these functi ons, and a l i st of the i ncl ude fi l es, l i brari es, and
exampl e programs needed when usi ng RI S functi ons.
5.1 ReferenceStructures
Refer to the fol l owi ng structures when usi ng RI S functi ons:
client_parms
typedef struct client_parms
{
char protocol;
char address[29];
char username[32];
char password[38];
short major;
short feature;
} client_parms;
datetime
typedef struct datetime
{
unsigned int second;
unsigned int minute;
unsigned int hour;
unsigned int day;
unsigned int month;
unsigned int year;
} datetime;

ris_db_info
typedef struct ris_db_info
{
unsigned short dbid;
unsigned char dtype;
char dbname[241];
struct
{
unsigned char protocol;
char netaddr[29];
} pathways[4];
union
{
ris_ifx_info ifx;
ris_igs_info igs;
ris_ora_info ora;
ris_db2_info db2;
ris_rdb_info rdb;
ris_syb_info syb;
ris_os400_info os400;
ris_mssql_info mssql;
} info;
char pad[3];
unsigned char ostype;
struct ris_db_info *next;
} ris_db_info;
Structures Related to theris_db_info Structure
typedef struct ris_ifx_info
{
char dir[241];
char sqlexec[241];
char dbtemp[241];
char tbconfig[241];
} ris_ifx_info;
typedef struct ris_igs_info
{
char dir[241];
} ris_igs_info;
typedef struct ris_ora_info
{
char dir[241];
char osuser[32];
char ospass[38];
} ris_ora_info;

typedef struct ris_db2_info
{
char osuser[32];
char ospass[38];
char arch[32];
char os[32];
char net_protocol[32];
char env[32];
char host_program[5];
char ris_lu[18];
char host_lu[18];
char mode[9];
char group[9];
char node[32];
char pad[1];
unsigned short port;
} ris_db2_info;
typedef struct ris_rdb_info
{
char dummy;
} ris_rdb_info;
typedef struct ris_syb_info
{
char osuser[32];
char ospass[38];
char dir[241];
char dsquery[32];
char sybifile[32];
} ris_syb_info;
typedef struct ris_os400_info
{
char osuser[32];
char ospass[38];
char net_protocol[32];
char host_program[22];
char ris_lu[18];
char host_lu[18];
char mode[9];
char group[9];
char node[32];
char ris_dict_dbname[11];
char pad;
unsigned short port;
} ris_os400_info;
typedef struct ris_mssql_info
{
char osuser[32];
char ospass[38];
char dir[241];
char dsquery[32];
char mssqlifile[32];
} ris_mssql_info;

ris_grantee_info
typedef struct ris_grantee_info
{
char schname[32];
char grantee[32];
struct ris_grantee_info *next;
} ris_grantee_info;
ris_parameters
typedef struct ris_parameters
{ int shared_memory;
int max_local_servers;
int max_rows;
int max_buffer_size;
int max_static_stmts;
int max_user_stmts;
int max_secondary_schemas;
int max_transactions;
int max_tables_in_memory;
int timestamp_interval;
int initial_timeout;
int timestamp_tolerance;
int buffer_full_size;
int buffer_full_timeout;
char schema_file_protocol;
char schema_file_address[29];
char schema_file_username[32];
char schema_file_password[38];
char schema_file_filename[241];
int lock_file_retry;
char client_protocol;
char client_address[29];
char client_username[32];
char client_password[38];
short client_major;
short client_feature;
} ris_parameters;
schema_file_parms
typedef struct schema_file_parms
{ char protocol;
char address[29];
char username[32];
char password[32];
char filename[241];
} schema_file_parms;

ris_schema_info
typedef struct ris_schema_info
{ char schname[32];
char schowner[32];
char schownpass[40];
char dictowner[32];
unsigned short secure;
unsigned short dbid;
unsigned short server_version_major;
unsigned short server_version_feature;
struct ris_schema_info *next;
} ris_schema_info;
The fol l owi ng are i ncl ude fi l es for RI S functi ons:
ris_err.h
rislimit.h
net_err.h
rap.prt
ris.prt
ris.h
The l i brary for RI S functi ons i s:
ris.lib
The functi ons exampl e programs are i n the \ risdp\ disk1 di rectory of the RI S Devel opment
Pl atform. Thi s di rectory contai ns the fol l owi ng exampl e programs:
async1.rc
async2.rc
asynctrn.rc
blob1.rc
blob2.rc
cleanup.rc
datetime.rc
dclar.rc
dynamic.rc
extern.rc
loccli.rc
multiple.rc
secure.rc
sharedic.rc
setup.rc
static.rc
transact.rc
union.rc
For detai l s about usi ng these exampl e programs, see the readme.spl fi l e i n the \ risdp\ disk1
di rectory.
5.3 Functions
The fol l owi ng reference secti on provi des detai l ed descri pti ons of each RI S functi on.

RISascii_to_datetime
RI Sascii_to_datetimeconverts an ASCI I stri ng to a datetimestructure. I t accepts an
ASCI I buffer as i nput and fi l l s i n a datetimestructure format. Format i s i nterpreted
i n the same way as i n RI Sdatetime_to_ascii.
char * RISascii_to_datetime( datetime *date,
char *buffer,
char *format );
__________________
Description
___________
date Poi nter to datetimestructure fi l l ed i n by
RI Sascii_to_datetime.
buffer Character stri ng representi ng a dateti me val ue.
format Character stri ng descri bi ng the format of the dateti me stri ng
i n the buffer.
Examples
_________
See exampl es for RI Sdatetime_to_ascii.
Status Returns
______________
Success 0
Fai l ure Poi nter to an error stri ng
SeeAlso
________
RI Sdatetime_to_ascii

RISdatetime_to_ascii
RI Sdatetime_to_ascii accepts a datetimestructure as i nput and generates a nul l -
termi nated ASCI I stri ng i n buffer-based format.
int RISdatetime_to_ascii( datetime *date,
char *buffer,
char *format );
__________________
Description
___________
date Poi nter to a datetimestructure contai ni ng a dateti me val ue.
See the Notes secti on on thi s functi on for more i nformati on.
buffer Poi nter to a character buffer where dateti me structure i s
generated.
format Poi nter to a character stri ng that speci fi es the dateti me
structures format. See the Notes secti on on thi s functi on for
more i nformati on.
Examples
_________
Assume the dateti me structure contai ns the fol l owi ng:
date.year = 1990
date.month = 12
date.day = 5
date.hour = 10
date.mi nute = 33
date.second = 32
format = "<m/d/y>"
buffer = "<12/5/1990>"
format = "mm/dd/yy"
buffer = "12/05/90"
format = "mm/dd/yyyy"
buffer = "12/05/1990"
format = "dy, mon d yyyy"
buffer = "wed, dec 5 1990"
format = "day, month d yyyy"
buffer = "wednesday, december 5 1990"
format = "day = day, month d yyyy"
buffer = "day = wednesday, december 5 1990"
format = "day = day, month d yyyy"
buffer = "day = wednesday, december 5 1990"
format = "Dy, Mon d yyyy"
buffer = "Wed, Dec 5 1990"

format = "Day, Month d yyyy"
buffer = "Wednesday, December 5 1990"
format = "DY, MON d yyyy"
buffer = "WED, DEC 5 1990"
format = "DAY, MONTH d yyyy"
buffer = "WEDNESDAY, DECEMBER 5 1990"
format = "DAY, MONTH d yyyy hh12:nn:ss AM"
buffer = "WEDNESDAY, DECEMBER 5 1990 10:33:32 AM"
format = "DAY, MONTH d yyyy hh:nn:ss P.M."
buffer = "WEDNESDAY, DECEMBER 5 1990 10:33:32 P.M."
format = "day, month d yyyy hh12:nn:ss am"
buffer = "wednesday, december 5 1990 10:33:32 am"
format = "day, month d yyyy hh:nn:ss p.m."
buffer = "wednesday, december 5 1990 10:33:32 p.m."
format = "day, month d yyyy hh24:nn:ss"
buffer = "wednesday, december 5 1990 10:33:32"
format = "Day the dth day of Month, yyyy"
buffer = "Wednesday the 5th day of December, 1990"
format = "The sth second of the nth minute of the h24th hour"
buffer = "The 32nd second of the 33rd minute of the 10th hour"
Status Returns
______________
Success 0
Fai l ure Non-zero val ue

Notes
______
The datetimestructure i s defi ned as fol l ows:
typedef struct datetime
{
unsigned int second;
unsigned int minute;
unsigned int hour;
unsigned int day;
unsigned int month;
unsigned int year;
} datetime;
The format i s i nterpreted as fol l ows:
ASCI I string
____________
Unit
_____
Format
_______
Padding
________
yyyy Year Four di gi ts. Leadi ng zeros.
yy Year Last two di gi ts. Leadi ng zeros.
y Year One to four di gi ts. None.
mm Month Two di gi ts. Leadi ng zeros.
m Month One or two di gi ts. No paddi ng.
month Name of month One to ni ne characters. None.
mon Name of month Three character
abbrevi ati on.
None.
ddd Day of year One to three di gi ts. None.
dd Day of month Two di gi ts. Leadi ng zeros.
d Day of month One to two di gi ts. None.
day Day of week
name
One to ni ne characters. None.
dy Day of week
name
Three character
abbrevi ati on.
None.
hh24 24 hour mode Two di gi ts. Leadi ng zeros.
h24 24 hour mode One to two di gi ts. None.
h12 or hh 12 hour mode Two di gi ts. Leadi ng zeros.

h12 or h 12 hour mode One to two di gi ts. None.
nn Mi nute Two di gi ts. Leadi ng zeros.
n Mi nute One to two di gi ts. None.
ss Second Two di gi ts. Leadi ng zeros.
s Second One to two di gi ts. None.
am or pm Meri di an
i ndi cator
Two characters. None.
ASCI I string
____________
Unit
_____
Format
_______
Padding
________
a.m. or p.m. Meri di an
i ndi cator wi th
peri ods
Four characters. None.
text Si ngl e
quotati on
stri ng
Reproduced i n desti nati on
stri ng.
None.
Si ngl e
quotati on
stri ng.
None.
defaul t Any other
character
stri ng.
None.

Capi tal i zati on i n a word or abbrevi ati on fol l ows capi tal i zati on i n the
correspondi ng format el ement.
RI Sdatetime_to_ascii assumes buffer i s l arge enough to hol d the
resul ti ng stri ng. No si ze checki ng i s performed.
SeeAlso
________
RI Sascii_to_datetime

RISget_ansi_mode
RI Sget_ansi_modechecks i f ANSI mode fl ag i s on or off. I f i t i s on, ANSI mode i s set
to one. Otherwi se, i t i s zero. I f ANSI mode i s on, RI S restri cts user-suppl i ed names
for schemas, tabl es, col umns, vi ews, and i ndexes to a maxi mum of 18 characters
whi l e they are created. I f ANSI mode i s off, the RI S l i mi t i s extended to 31
characters. ANSI mode i s set usi ng the set modestatement.
void RISget_ansi_mode( int *ansi_mode );
__________________
Description
___________
ansi_mode Poi nter to i nteger representi ng ansi _mode fl ag.
1 = ANSI mode on.
0 = ANSI mode off.
Defaul t i s 1.
Examples
_________
main()
{
int *ansi_mode;
RISget_ansi_mode(&ansi_mode);
if (SQLCODE != RIS_SUCCESS)
printf("Error in the called function\n");
if (ansi_mode)
{
printf("ANSI mode flag is ON.\n");
printf("RIS restricts user_supplied names
to 18 characters.\n");
}
else
printf("ANSI mode is OFF\n");
}
Status Returns
______________
Success SQLCODE = RI S_SUCCESS
Fai l ure SQLCODE = Error number
I f RI S cl i ent process has termi nated, an
RI S_E_CLI ENT_DEAD error i s returned.
Notes
______
Not every DBMS can handl e names l onger than 18 characters.

RISget_app_version
RI Sget_app_version gets the current versi on of RI S. The poi nter arguments: maj,
mi n, and rel are set by RI S.
void RISget_app_version( int *maj,
int *min,
int *rel );
__________________
Description
___________
maj Poi nter to i nteger representi ng major number of the versi on.
min Poi nter to i nteger representi ng mi nor number of the versi on.
rel Poi nter to i nteger representi ng rel ease number of the versi on.
Examples
_________
main()
{
int *maj,*min,*rel;
RISget_app_version(&maj,&min,&rel);
printf("Application Major : %d \n", maj);
printf("Application Minor : %d \n", min);
printf("Application Release : %d \n", rel);
}
Status Returns
______________

RISget_async_stmts
RI Sget_async_stmts gets the number of asynchronous statements and thei r I Ds. The
buffer i s an array of asynchronous I Ds. To determi ne the si ze of the buffer, cal l
RI Sget_async_stmts wi th *countp equal to zero. On i nput, *countp sets the number of
async I Ds to return. On output, *countp contai ns the number of async I Ds that exi st.
You can cal l RI Sget_async_stmts a second ti me wi th *countp set to the number of
async I Ds. Thi s retri eves the async I Ds.
void RISget_async_stmts( int *buffer,
int *countp );
__________________
Description
___________
buffer Poi nter to an i nteger contai ni ng the asynchronous I Ds.
countp Poi nter to an i nteger contai ni ng the number of asynchronous
I Ds.
Examples
_________
#include "rislimit.h"
main()
{
int count;
int *buffer;
int i;
int async1;
int async2;
char * err_ptr;
exec sql default schema sch1;
exec sql async :async1 insert into t1 values (1);
exec sql async :async2 insert into t2 values (2);
exec sql wait :async1 completion;
exec sql wait :async2 completion;

/*
** Find out how many asynchronous statements.
*/
count = 0;
RISget_async_stmts(buffer, &count);
{
printf("%s", err_ptr);
return SQLCODE;
}
/*
** Allocate the space to hold the asynchronous IDs.
*/
buffer = (int *) malloc (count * sizeof(int));
/*
** Retrieve the async IDs
*/
RISget_async_stmts(buffer, &count);
{
return SQLCODE;
}
/*
** Output the results
*/
for(i = 0; i < count; i++)
{
printf("buffer[%d]=%d\n", i, buffer[i]);
}
not_found:
printf("No more data\n");
exit();
error:
puts(err_ptr);
exit();
}

RISget_autocommit_mode
RI Sget_autocommit_modechecks i f autocommi t mode i s on or off. I f i t i s on,
autocommi t i s set to one. Otherwi se, i t i s zero. When autocommi t i s on, data
mani pul ati on statements such as select, insert, update, and deleteare automati cal l y
commi tted. The set transaction statement sets the transacti on state.
void RISget_autocommit_mode( int *autocommit );
__________________
Description
___________
autocommit Poi nter to i nteger representi ng autocommi t fl ag.
1 = autocommi t on.
0 = autocommi t off.
Defaul t i s 1.
Examples
_________
main()
{
int *autocommit;
RISget_autocommit_mode(&autocommit);
if (autocommit)
{
printf("Autocommit mode flag is ON.\n");
printf("Data manipulation statements are
automatically committed.\n");
}
else
printf("Autocommit mode is OFF \n");
}
Status Returns
______________

RISget_autorename_mode
RI Sget_autorename_modechecks i f the autorename mode i s on or off. I f i t i s on,
autorename i s set to one and RI S regenerates the col umn and tabl e names (greater
than the ten characters) ori gi nal l y suppl i ed by the user. I f i t i s off, autorename i s set
to zero and RI S wi l l not regenerate col umn and tabl e names. The autorename mode
i s set usi ng the set modestatement.
void RISget_autorename_mode( int *autorename );
__________________
Description
___________
autorename Poi nter to an i nteger representi ng the autorename mode fl ag.
1 = On.
0 = Off.
Defaul t i s 1.
Examples
_________
main()
{
int *autorename_mode;
RISget_autorename_mode(&autorename_mode);
if (autorename_mode)
{
printf("Autorename mode flag is ON.\n");
printf("RIS will regenerate table/column names > than\n");
printf("ten characters in length\n");
}
else
printf("Autorename is OFF \n");
}
Status Returns
______________

RISget_blankstrip_mode
RI Sget_blankstrip_modechecks i f the bl ankstri p mode i s on or off. I f i t i s on,
blankstrip_modei s set to one and RI S stri ps trai l i ng bl anks from character data. I f i t
i s off, blankstrip_modei s set to zero and RI S does not stri p trai l i ng bl anks. The
bl ankstri p mode i s set usi ng the set modestatement.
void RISget_blankstrip_mode( int *blankstrip_mode );
__________________
Description
___________
blankstrip_mode Poi nter to an i nteger representi ng the bl ankstri p mode fl ag.
1 = On.
0 = Off.
Defaul t i s 1.
Examples
_________
main()
{
int *blankstrip_mode;
RISget_blankstrip_mode(&blankstrip_mode);
if (blankstrip_mode)
{
printf("Blankstrip mode flag is ON.\n");
printf("RIS will strip trailing blanks
from character data \n");
}
else
printf("Blankstrip mode is OFF \n");
}
Status Returns
______________

RISget_client_location
RI Sget_client_location retri eves the l ocati on of the RI S cl i ent process speci fi ed i n the
parameters fi l e.
void RISget_client_location( client_parms *parms );
__________________
Description
___________
parms Poi nter to client_parms structure that speci fi es the l ocati on of
the RI S cl i ent process. See the secti on ReferenceStructures
for detai l ed i nformati on about thi s structure.
Examples
_________
main()
{
client_parms parms;
RISget_client_location(&parms);
printf("Protocol : %c \n", parms.protocol);
printf("Address : %s \n", parms.address);
printf("Major : %d \n", parms.major);
printf("Feature : %d \n", parms.feature);
}
Status Returns
______________
Notes
______
The protocol fi el d i n the client_parms structure speci fi es the protocol i nteracti ng wi th
the node where the RI S cl i ent process resi des. The protocol s and thei r correspondi ng
codes are:
Protocol Code
xns X
tcp/i p T
decnet D
memory(l ocal ) M

The address fi el d speci fi es the address of the node. The protocol s and thei r
correspondi ng address formats are:
Protocol Code
xns name or XXXXXXXX.XX-XX-XX-XX-XX-XX
tcp/i p name or XXX.XXX.XXX.XXX
decnet name or XX.XXXX
memory(l ocal ) I NVALI D
Use the major fi el d i n the client_parms structure to speci fy the major versi on of the
cl i ent and the feature fi el d to speci fy the feature versi on of the cl i ent. The major
versi on of the cl i ent shoul d be greater than or equal to the major versi on of the
appl i cati on.
The major cl i ent versi on defaul t and the feature cl i ent defaul t i s zero. Use these
defaul ts when the cl i ent versi on i s the same as the appl i cati on versi on.

RI S for Wi ndows NT currentl y supports onl y the TCP/I P protocol .

RISget_current_stmt_schema_name
RI Sget_current_stmt_schema_nameretri eves the schema name associ ated wi th the
l ast RI S statement executed but not cl eared. The buffer i s an array of character
stri ngs of si ze RI S_MAX_I D_SI ZE, defi ned i n the rislimit.h i ncl ude fi l e, wi th the
schema name.
void RISget_current_stmt_schema_name( char (buffer) [RIS_MAX_ID_SIZE] );
__________________
Description
___________
buffer Poi nter to a character buffer used to retri eve the schema
name of the current statement.
Examples
_________
main ()
{
char buffer[RIS_MAX_ID_SIZE];
exec sql prepare s1 from "select * from ristables";
RISget_current_stmt_schema_name(buffer);
printf("schema name: <%>s\n", buffer);
}
Status Returns
______________

RISget_db_info
RI Sget_db_infogets database i nformati on from the RI S schema fi l e. I t takes a
database I D as i nput and pl aces thi s database i nformati on i nto the ris_db_info
structure. The dbp poi nter poi nts to thi s structure. I f dbp i s nonzero, the structures
are al l ocated automati cal l y through malloc. Otherwi se, the structure i s not
al l ocated. You must free the structures after use by cal l i ng free.
void RISget_db_info( int dbid,
ris_db_info **dbp );
__________________
Description
___________
dbid Database I D of a database structure i n the schema fi l e.
dbp Address of the poi nter to the ris_db_infostructure. For more
i nformati on on thi s and rel ated structures, see the secti on
ReferenceStructures.
Examples
_________
main()
{
ris_db_info *dbp;
char *ptr;
RISget_db_info(2, &dbp);
{
printf("%s", ptr);
return SQLCODE;
}
printf("db info : \n\tdbid %d \n\tdtype %c
\n\tdbname <%s> \n\tprotocol %c
\n\tnetaddr <%s> \n\tifx: \n\t\tdir <%s>
\n\t\tsqlexec <%s> \n\t\tdbtemp <%s>
\n\t\ttbconfig <%s>\n\t\tostype<%c>\n",
dbp->dbid, dbp->dtype, dbp->dbname,
dbp->pathways->protocol, dbp->pathways->netaddr,
dbp->info.ifx.dir, dbp->info.ifx.sqlexec,
dbp->info.ifx.dbtemp, dbp->info.ifx.tbconfig, dbp->ostype);
free(dbp);
}

Sampl e Output:
db info :
dbid 2
dtype X
dbname <inf2>
protocol T
netaddr <129.135.145.157>
ifx:
dir </usr3/informix>
sqlexec </usr3/informix/lib/sqlturbo>
dbtemp <>
tbconfig <>
ostype <>
Status Returns
______________
I f RI S cl i ent process has termi nated, a
RI S_E_CLI ENT_DEAD error i s returned. I f database i s not
found, a RI Sapp_UNKNOWN_DB error i s returned.

RISget_dbca
RI Sget_dbca returns a poi nter to the risca vari abl e (rissqla structure) contai ni ng a
copy of the vendor databases sqlca structure. For more i nformati on, see the secti on
Error Handling.
rissqla *RISget_dbca( void );
__________________
Description
___________
dbca Structure of type rissqlca to hol d error i nformati on.
Examples
_________
main()
{
rissqlca *DBCA;
if(RISget_sqlcode() != RIS_SUCCESS)
{
DBCA = RISget_dbca();
printf("Database SQLCODE = %d\n", DBCA -> sqlcode);
}
}
Status Returns
______________

RISget_default_schema_name
RI Sget_default_schema_namereturns the current defaul t schema name i nto the
buffer vari abl e.
void RISget_default_schema_name( char (buffer) [RIS_MAX_ID_SIZE] );
__________________
Description
___________
buffer Poi nter to a character buffer to retri eve defaul t schema name.
Examples
_________
main ()
{
char buffer [RIS_MAX_ID_SIZE];
exec sql default schema my_schema;
RISget_default_schema_name(buffer);
printf("Default schema: %\n", buffer);
}
Status Returns
______________
None

RISget_enabled_databases
RI Sget_enabled_databases determi nes whi ch RI S-supported DBMSs are enabl ed. I f
al l the databases are enabl ed, the bi t mask RI S_ENABLE_ALL i s set i n
enable_dbms. I f onl y some of the databases are enabl ed, the bi t masks correspondi ng
to the enabl ed databases are set i n enable_dbms. These bi t masks are defi ned i n
ris.h. The ris.h i ncl ude fi l e al so defi nes macros. These macros return zero or one i f
the appropri ate bi t i s set i n the bi t mask. The macro names are
I S_XXX_ENABLED(mask) where XXX i s the DBMS name i n uppercase. For
exampl e, I S_I NFORMI X_ENABLED i s the i nteger bi t mask vari abl e.
The set databasestatement speci fi es the types of underl yi ng databases you can use.
Thi s causes veri fi cati on of user-suppl i ed names agai nst the reserved words of the
speci fi ed databases.
void RISget_enabled_databases( int *enable_dbms );
__________________
Description
___________
enable_dbms Poi nter to an i nteger wi th bi ts representi ng enabl ed
databases.
Examples
_________
main()
{
int enable_dbms;
RISget_enabled_databases(&enable_dbms);
if (IS_INFORMIX_ENABLED(enable_dbms))
printf("Informix database is enabled\n");
}
The fol l owi ng fi gure represents the i nteger to whi ch enable_dbms poi nts. The bi t
masks i n thi s graphi c match those i n ris.h.

enable_dbms Bit Masks as Defined in ris.h
Status Returns
______________

RISget_language_name
RI Sget_language_nameretri eves the l anguage name currentl y set by RI S. The RI S-
supported l anguages are l i sted i n the RI S l anguage confi gurati on fi l e. See the
secti on LanguageConfiguration Filei n the RI S SQL Users Guidefor 32-Bit
Applications for more i nformati on about sel ecti ng l anguages.
RISget_language_name( char *name );
__________________
Description
___________
name Poi nter to a character buffer that hol ds the l anguage stri ng of
si ze RI S_MAX_LANGNAME_SI ZE.
Examples
_________
main()
{
char language [RIS_MAX_LANGNAME_SIZE];
RISinitialize("english");
RISget_language_name(language);
printf("Language is set to %s\n", language);
}
Status Returns
______________
Notes
______
I f RI S i s not i ni ti al i zed, the i nput vari abl e i s set to the nul l stri ng.

RISget_parameters
RI Sget_parameters retri eves the RI S parameters currentl y set by RI S. The
parameters poi nter poi nts to the RI S parameter i nformati on structure.
void RISget_parameters( ris_parameters *parameters );
__________________
Description
___________
parameters Poi nter to ris_parameter structure used to recei ve parameters
i nformati on. See the secti on ReferenceStructures for detai l ed
i nformati on about thi s structure.
Examples
_________
main()
{
ris_parameters parameters;
RISget_parameters(&parameters);
printf("max_local_servers: %d\n", parameters.max_local_servers);
printf("max_local_servers: %d\n", parameters.max_rows);
}
Status Returns
______________
Notes
______
Each fi el d corresponds to a fi el d speci fi ed i n the parameters fi l e.

RISget_risca
RI Sget_risca returns a poi nter to the risca vari abl e (rissqla structure), whi ch
provi des consi stent error and other i nformati on regardl ess of the database system.
For detai l ed i nformati on on the risca vari abl e, see the secti on Error Handling.
rissqla *RISget_risca( void );
__________________
Description
___________
risca Structure of type rissqlca to hol d error i nformati on.
Examples
_________
main()
{
rissqlca *RISCA;
if(RISget_sqlcode()!= RIS_SUCCESS)
{
RISCA = RISget_risca();
printf("SQLCODE=%d\n", RISCA -> sqlcode);
}
}
Status Returns
______________

RISget_schema_file
RI Sget_schema_fileretri eves schema fi l ename, schema, database, and grantee
i nformati on from the RI S schema fi l e. I t returns a l i st of i nformati on about every
schema fi l ename, database, schema, and grantee usi ng the schema_filenamep,
dblistp, schlistp, and granteep poi nters. The structures rel ated to these poi nters are
automati cal l y al l ocated through malloc. However, you must deal l ocate them after
use by cal l i ng free. I f any of the parameters are zero, the correspondi ng structures
are not al l ocated.
void RISget_schema_file( char **schema_filenamep
ris_db_info **dblistp,
ris_schema_info **schlistp,
ris_grantee_info **granteep );
__________________
Description
___________
schema_filenamep Address of schema_filenamepto recei ve schema fi l ename.
dblistp Address of ris_db_infopoi nter, whi ch i s a structure for
recei vi ng database i nformati on. See the secti on Reference
Structures for detai l ed i nformati on about thi s structure.
schlistp Address of ris_schema_infopoi nter, whi ch i s a structure for
recei vi ng schema i nformati on. See the secti on Reference
granteep Address of ris_grantee_infopoi nter, whi ch i s a structure for
recei vi ng grantee i nformati on. See the secti on Reference
Examples
_________
main()
{
char *ptr;
char *schema_filenamep;
ris_schema_info *schemap;
ris_db_info *dbp;
ris_grantee_info *granteep;
RISget_schema_file(&schema_filenamep, &dbp, &schemap, &granteep);
{
printf("%s", ptr);
return SQLCODE;
}
printf("schema filename: <%>s\n",schema_filenamep);

while (schemap)
{
printf("schema info: \n\tname <%s>\n\tpasswd <%s>
\n\tlogin <%s>\n\tdictowner <%s>
\n\tschtype <%d>\n\tdbid %d
\n\tmajor <%d>\n\tfeature <%d>\n",
schemap->schname, schemap->schownpass,
schemap->schowner, schemap->dictowner,
schemap->secure, schemap->dbid,
schemap->server_version_major,
schemap->server_version_feature);
schemap=schemap->next;
}
while (dbp)
{
\n\tnetaddr <%s> \n\tostype <%c>\n",
dbp->pathways->protocol,
dbp->pathways->netaddr, dbp->ostype);
dbp=dbp->next;
}
while (granteep)
{
printf("grantee info : schname <%s> grantee <%s>\n",
granteep->schname, granteep->grantee);
granteep=granteep->next;
}
}
SampleOutput
_______________
:
schema info:
name <inf2>
user <ris>
passwd <o%2H;,w]MZpOcA%2]H;w]H-C6r_<L<Q5"W>
dbid 2
schema info:
name <inf1>
user <michal>
passwd <{<sB1SqZeP}lk07Bj9J(JQM<m)0qL7aj>
dbid 1
db info :
dbid 2
dtype X
dbname <inf2>
protocol T
netaddr <129.135.145.157>
ostype <u>
db info :
dbid 1
dtype X
dbname </usr2/michal/inf1>
protocol T
netaddr <129.135.145.76>
ostype <u>

Status Returns
______________
I f RI S cl i ent process has termi nated, a

RISget_schema_info
RI Sget_schema_infoaccepts a schema name as i nput and retri eves the schema
i nformati on, database i nformati on, and grantee i nformati on correspondi ng to
schnamefrom the schema fi l e. The schemap, dbp, and granteep poi nters poi nt to
schema i nformati on, database i nformati on, and a l i st of accessi bl e grantees.
I f schemap, dbp, or granteep i s nonzero, the structure i s al l ocated through mallocand
i nformati on i s fi l l ed i nto i ts fi el ds. I f any of the parameters i s zero, the structure i s
not al l ocated. After usage, you must deal l ocate the structures by cal l i ng free.
void RISget_schema_info( char *schname,
ris_schema_info **schemap,
ris_db_info **dbp,
ris_grantee_info **granteep );
__________________
Description
___________
schname Schema name.
schemap Address of ris_schema_infopoi nter, whi ch i s a structure for
recei vi ng schema i nformati on. See the secti on Reference
dbp Address of ris_db_infopoi nter, whi ch i s a structure for
recei vi ng database i nformati on. See the secti on Reference
granteep Address of ris_grantee_infopoi nter, whi ch i s a structure for
recei vi ng grantee i nformati on. See the secti on Reference
Examples
_________
main()
{
char *ptr;
ris_schema_info *schemap;
ris_db_info *dbp;
ris_grantee_info *granteep;
RISget_schema_info("inf1", &schemap, &dbp, &granteep);
{
printf("%s", ptr);
return SQLCODE;
}
while (schemap)
{

printf("schema info: \n\tname <%s>\n\tpasswd <%s>
\n\tlogin <%s>\n\tdictowner <%s>
\n\tschtype <%d>\n\tdbid %d
\n\tmajor <%d>\n\tfeature <%d>\n",
schemap->schname, schemap->schownpass,
schemap->schowner, schemap->dictowner,
schemap->secure, schemap->dbid,
schemap->server_version_major,
schemap->server_version_feature);
schemap=schemap->next;
}
while (dbp)
{
\n\tnetaddr <%s> \n\tostype <%c>\n",
dbp->pathways->protocol,
dbp->pathways->netaddr, dbp->ostype);
dbp=dbp->next;
}
while (granteep)
{
printf("grantee info : schname <%s> grantee <%s>\n",
granteep->schname, granteep->grantee);
granteep = granteep->next;
}
}
Sample Output: (note the encrypted password)
schema info:
name <inf1>
passwd <%/.-AR2-!kjX1j:9HM9-/5.BS.)7Gu=Evh>
login < >
dictowner <skapoor>
schtype <0>
dbid 1
major <-1>
feature <-1>
db info :
dbid 1
dtype X
dbname </usr2/risdb>
protocol X
netaddr <000134bb.08-00-36-f0-d5-00>
ostype <U>
Status Returns
______________
I f RI S cl i ent process has termi nated, RI S_E_CLI ENT_DEAD
error i s returned. I f schema i s not found,
RI Sapp_UNKNOWN_SCHEMA i s returned.

RISget_schema_file_location
RI Sget_schema_file_location retri eves the l ocati on of the RI S schema fi l e speci fi ed i n
the parameters fi l e. The defaul t l ocati on i s i n the di rectory where the RI SCLI
product i s i nstal l ed.
void RISget_schema_file_location( schema_file_parms *parms );
__________________
Description
___________
parms Poi nter to a schema_file_parms structure, speci fyi ng the
l ocati on of the RI S schema fi l e. See the secti on Reference
Examples
_________
main()
{
schema_file_parms parms;
RISget_schema_file_location(&parms);
printf("Protocol : %c \n", parms.protocol);
printf("Address : %s \n", parms.address);
printf("Filename : %s \n", parms.filename);
}
Status Returns
______________
Notes
______
The protocol fi el d i n the schema_file_parms structure speci fi es the protocol
i nteracti ng wi th the node where the RI S schema fi l e resi des. The protocol s and thei r
correspondi ng codes are:
Protocol Code
tcp/i p T
memory(l ocal ) M
Protocol Code

RI Sget_schema_file_location does not use the password fi el d. The username fi el d
speci fi es a val i d username on the node. The fi l ename fi el d speci fi es the name of the
RI S schema fi l e.
I n RI S for Wi ndows NT, i f the fi l ename does not speci fy a path, then the RI S schema
fi l e i s assumed to be on the node where the RI S shared component resi des, i n the
\ ProgramFiles\ Common Files\ I ntergraph\ ris05.xxdi rectory.

RISget_schema_names
RI Sget_schema_names retri eves the l i st of schema names from the RI S schema fi l e.
RI Sget_schema_names reads the RI S schema fi l e and fi l l s i n the buffer. The buffer i s
an array of character stri ngs of si ze RI S_MAX_I D_SI ZE, defi ned i n the rislimit.h
i ncl ude fi l e, wi th the names of the schemas defi ned i n the schema fi l e.
To determi ne the si ze of the buffer, cal l RI Sget_schema_names wi th *countp equal to
zero. On i nput, *countp sets the number of schema names to return. On output,
*countp contai ns the number of schemas that exi st. You can then cal l
RI Sget_schema_names a second ti me wi th *countp set to the number of schema
names. Thi s retri eves the schema names.
void RISget_schema_names( char (*buffer)[RIS_MAX_ID_SIZE],
int *countp );
__________________
Description
___________
buffer Poi nter to a character array contai ni ng the schema names.
countp Poi nter to i nteger contai ni ng the number of schemas.
Examples
_________
main()
{
int i;
int count;
char (*buffer)[RIS_MAX_ID_SIZE];
char *ptr;
/*
** Find out how many schema names
*/
count = 0;
RISget_schema_names(buffer, &count);
{
printf("%s", ptr);
return SQLCODE;
}
/*
** Allocate the space to hold the schema names
*/
buffer = (char (*)[RIS_MAX_ID_SIZE])malloc(count * RIS_MAX_ID_SIZE);

/*
** Retrieve the schema names
*/
{
printf("%s", ptr);
return SQLCODE;
}
/*
*/
for (i = 0; i < count; i++)
printf("buffer[%d]:<%s>\n", i, buffer[i]);
}
Usi ng the fol l owi ng typedef can si mpl i fy the decl arati on and mal l oc of the schema
name array.
typedef char risschema_name[RIS_MAX_ID_SIZE];
The fol l owi ng exampl e i s the same as the previ ous exampl e, except that i t uses
typedef.
#include "RISlimits.h"
typedef char risschema_name[RIS_MAX_ID_SIZE];
main()
{
int i;
int count;
risschema_name *buffer;
char *ptr;
/*
** Find out how many schema names
*/
count = 0;
{
printf("%s", ptr);
return SQLCODE;
}
/*
*/
buffer = (risschema_name *)malloc(count * sizeof(risschema_name));

/*
*/
{
printf("%s", ptr);
return SQLCODE;
}
/*
*/
for (i = 0; i < count; i++)
}
Status Returns
______________
I f *countp i s l ess than the number of schema names,
SQLCODE i s set to RI S_E_NOT_ENOUGH_SPACE.

RISget_schema_transactions
RI Sget_schema_transactionsgets the number and names of schemas i nvol ved i n the
uncommi tted transacti ons. The buffer i s an array of character stri ngs of si ze
RI S_MAX_I D_SI ZE, defi ned i n the rislimit.h i ncl ude fi l e, wi th the names of the
schemas.
To determi ne the si ze of the buffer, cal l RI Sget_schema_transactionswi th *countp
equal to zero. On i nput, *countp sets the number of schema names to return. On
output, *countp contai ns the number of schemas that exi st. You can cal l
RI Sget_schema_transactionsa second ti me wi th *countp set to the number of schema
names to retri eve the schema names currentl y i n transacti on.
void RISget_schema_transactions( char (*buffer)[RIS_MAX_ID_SIZE],
int *countp );
__________________
Description
___________
buffer Poi nter to a character array contai ni ng
the schema names.
countp Poi nter to i nteger contai ni ng the number
of schemas.
Examples
_________
main()
{
int count;
char (*buffer)[RIS_MAX_ID_SIZE];
int i;
char * err_ptr;
exec sql set transaction autocommit off;
exec sql default schema stwo;
exec sql insert into stwo.t2 values (1);
exec sql default schema sone;
exec sql insert into sone.t1 values (1);
/*
** Find out how many schemas
*/
count = 0;
RISget_schema_transactions(buffer, &count);
{

return SQLCODE;
}
/*
*/
buffer = (char (*)[RIS_MAX_ID_SIZE])malloc(count * RIS_MAX_ID_SIZE);
/*
*/
RISget_schema_transactions(buffer, &count);
{
return SQLCODE;
}
/*
*/
for(i = 0; i < count; i++)
{
}
exec sql commit;
exec sql default schema stwo;
exec sql commit;
not_found:
printf("No more data");
exit();
error:
puts(err_ptr);
exit();
}
Status Returns
______________
I f *countp i s l ess than the number of schema
names, SQLCODE i s set to RI S_E_NOT_ENOUGH_SPACE.

RISget_ris_sqltype_code
RI Sget_ris_sqltype_coderetri eves the RI S SQL data type code for a gi ven RI S SQL
data type stri ng. The RI S data type codes and thei r correspondi ng stri ngs are l i sted
i n the ris.h fi l e.
void RISget_ris_sqltype_code( int *code,
char *str );
__________________
Description
___________
code Poi nter to i nteger type to hol d RI S SQL data type code.
str Poi nter to character stri ng to pass RI S SQL data type stri ng.
Examples
_________
main()
{
int code;
RISget_ris_sqltype_code (&code,"int");
}
Status Returns
______________

RISget_ris_sqltype_string
RI Sget_ris_sqltype_stringretri eves the RI S SQL data type stri ng for a gi ven RI S SQL
data type code. Al l data types are l i sted i n the ris.h fi l e.
void RISget_ris_sqltype_string( char *str,
int *code );
__________________
Description
___________
str Poi nter to character stri ng to retri eve RI S SQL data type
stri ng.
code I nteger vari abl e i ndi cati ng RI S SQL data type code.
Examples
_________
main()
{
char str[RIS_MAX_ID_SIZE]
RISget_ris_sqltype_string(str, 2);
}
Status Returns
______________

RISget_sqlcode
RI Sget_sqlcodereturns the l ast RI S error code (sqlcode). The sqlcodereturned i s the
most recent error code set by the previ ous RI S SQL statement or functi on cal l .
An appl i cati on shoul d cal l thi s functi on i mmedi atel y after a RI S SQL statement or
RI S functi on cal l to determi ne the success or fai l ure of that statement or cal l .
The error codes are i nteger si ze val ues. An sqlcodeof RI S_SUCCESS (val ue 0)
i ndi cates a success. Any negati ve val ue i ndi cates a fai l ure.
int RISget_sqlcode( void );
Examples
_________
main()
{
if(RISget_sqlcode != RIS_SUCCESS)
{
printf("Default schema failed.\n");
}
}
Status Returns
______________

RISget_verify_mode
RI Sget_verify_modechecks to see i f the veri fy mode swi tch i s on or off. I f i t i s on,
verify_modei s set to one and the tabl e and vi ew defi ni ti ons are retri eved from the
underl yi ng database and val i dated agai nst defi ni ti ons stored i n the RI S di cti onary
tabl es. I f i t i s off, verify_modei s set to zero and the val i dati on phase i s omi tted. The
val i dati on phase ensures consi stency between the RI S di cti onary tabl es and the
underl yi ng database. The verify_modei s set usi ng the set modestatement.
void RISget_verify_mode( int *verify_mode );
__________________
Description
___________
verify_mode Poi nter to i nteger representi ng veri fy mode fl ag.
1 = On.
0 = Off.
Defaul t i s 1.
Examples
_________
main()
{
int *verify_mode;
RISget_verify_mode(&verify_mode);
if (verify_mode)
{
printf("Verify mode flag is ON.\n");
printf("Underlying database tables and view
definitions will be \n");
printf("validated against the RIS dictionary table
definitions \n");
}
else
printf("Verify mode is OFF \n");
}
Status Returns
______________

RISinitialize
RI Sinitializei ni ti al i zes the RI S system i n the fol l owi ng order:
1. I ni ti al i zes the l anguage fi l e based on the l anguage val ue passed through the
language_namevari abl e. I f NULL i s passed as the l anguage, RI S uses english
as the defaul t l anguage. The val i d l anguages currentl y supported by RI S are
l i sted i n the RI S l anguage confi gurati on fi l e. See the secti on Language
Configuration Filei n the RI S SQL Users Guidefor 32-Bit Applications for more
i nformati on about sel ecti ng l anguages.
2. Reads the parameters fi l e and confi gures RI S accordi ng to the parameter
speci fi cati ons.
3. Al l ocates the necessary gl obal memory to run RI S.
Cal l i ng RI Sinitializei s opti onal . The fi rst RI S statement executed automati cal l y
i nvokes RI Sinitializewi th the defaul t l anguage set to the l anguage Wi ndows NT i s
usi ng. Thus, i f Wi ndows NT i s set to German, the defaul t l anguage i s set to German.
void RISinitialize( char *language_name );
__________________
Description
___________
language_name Poi nter to the character stri ng representi ng the l anguage
name to be used by RI S.
Examples
_________
main()
{
RISinitialize(NULL);
if(SQLCODE != RIS_SUCCESS)
{
printf("Could not initialize\n");
}
}
Status Returns
______________

RISlocate_client
RI Slocate_client stores the l ocati on of the RI S cl i ent executabl e i n the parameters
fi l e.
void RISlocate_client( client_parms *parms );
__________________
Description
___________
parms Poi nter to client_parms structure, speci fyi ng the l ocati on of
the RI S cl i ent process. See the secti on ReferenceStructures
for detai l ed i nformati on about thi s structure.
Examples
_________
client_parms parms;
parms.protocol = T;
strcpy (parms.address, "123.456.789.10");
strcpy (parms.username, "pschalla");
strcpy (parms.password, "enigmal");
RISlocate_client(&parms);
Status Returns
______________
Notes
______
The protocol fi el d i n client_parms structure speci fi es the protocol i nteracti ng wi th the
node where the RI S cl i ent executabl e resi des. The protocol s and thei r correspondi ng
codes are:
Protocol Code
xns X
tcp/i p T
decnet D
memory (l ocal ) M
Use the memory protocol when the RI S cl i ent resi des on the l ocal machi ne.

Protocol Code
memory (l ocal ) i nval i d
I t i s i nval i d to speci fy an address wi th the memory protocol . Use the username fi el d
to speci fy a val i d username on the node. I t i s i nval i d to speci fy a user wi th the
memory protocol . I f the username speci fi ed requi res a password, speci fy i t i n the
password fi el d.
Use the major fi el d i n the client_parms structure to speci fy the major versi on of the
cl i ent and the feature fi el d to speci fy the feature versi on of the cl i ent. The major
versi on of the cl i ent shoul d be greater than or equal to the major versi on of the
appl i cati on.
The major cl i ent versi on defaul t and the feature cl i ent defaul t i s zero. Use these
defaul ts when the cl i ent versi on i s the same as the appl i cati on versi on.


RISlocate_schema_file
RI Slocate_schema_filestores the l ocati on of the RI S schema fi l e i n the parameters
fi l e. You must speci fy the l ocati on of the RI S schema fi l e on a parti cul ar node i n the
parms fi l e. You must cal l RI Slocate_schema_fileto modi fy the l ocati on speci fi ed i n
the parms fi l e.
void RISlocate_schema_file( schema_file_parms *parms );
__________________
Description
___________
parms Poi nter to a schema_file_parms structure, speci fyi ng the
l ocati on of the RI S schema fi l e. See the secti on Reference
Status Returns
______________
I f the memory protocol i s speci fi ed, and address, username, or
password i s al so speci fi ed, then error code
RI S_E_I NCONSI STENT_SCHFI LE_SPEC i s returned.
I f other protocol s (X, T, and D) are speci fi ed, but address and
username are not, the same error code i s returned. I f the fi l e
name i s not speci fi ed, the error code
RI S_E_MI SSI NG_SCH_FI LE_NAME i s returned.
Notes
______
The protocol fi el d i n schema_file_parms structure speci fi es the protocol i nteracti ng
wi th the node where the RI S schema fi l e resi des. The protocol s and thei r
correspondi ng codes are:
Protocol Code
xns X
tcp/i p T
decnet D
memory(l ocal ) M

Use the memory protocol when the RI S for Wi ndows NT schema fi l e
resi des on the l ocal machi ne.

Protocol Code

You cannot speci fy an address wi th the memory protocol . Use the
username fi el d to speci fy a val i d username on the node. You al so
cannot speci fy a user wi th the memory protocol .
I f the username speci fi ed requi res a password, speci fy i t i n the password
fi el d.
The fi l ename fi el d speci fi es the name of the RI S schema fi l e. I f the fi l e resi des on a
remote node, you must l ocate i t i n a di rectory that can be read and wri tten by the
speci fi ed username. I f the fi l e resi des on the l ocal machi ne, you must l ocate i t i n a
di rectory that can be read and wri tten by the user runni ng RI S. I f the fi l ename does
not speci fy a path, then the RI S schema fi l e i s assumed to be i n the di rectory where
RI S i s i nstal l ed (for CLI X), or i n the shared component di rectory (for Wi ndows NT).
Examples
_________
parms.protocol = M;
parms.address[0] = ;
parms.username[0] = ;
parms.password[0] = ;
strcpy(parms.filename, "/usr/bob/risschema");
RISlocate_schema_file(&parms);
parms.protocol = X;
strcpy(parms.address, "000134e3.08-00-36-e2-4f-00");
strcpy(parms.username, "bob");
strcpy(parms.password, "vandy");
strcpy(parms.filename, "risschema");
RISlocate_schema_file(&parms);

RISrestore_schema_file_checksum
RI Srestore_schema_file_checksumreads the RI S schema fi l e, cal cul ates the
checksum, and updates the checksum val ue i n the RI S schema fi l e.
You must recal cul ate the checksum val ue i f you update the RI S schema fi l e di rectl y,
or when the RI S schema fi l e i s corrupted.
void RISrestore_schema_file_checksum( void );
Examples
_________
main()
{
RISrestore_schema_file_checksum( );
}
Status Returns
______________

RISstart_client
RI Sstart_client starts the RI S cl i ent process speci fi ed i n the cl i ent parameters of RI S
parameters fi l e.
void RISstart_client( void );
Examples
_________
main
{
RISstart_client();
{
printf("could not start client\n");
}
}
Status Returns
______________
Notes
______
See functi on RI Slocate_client to set previ ousl y menti oned RI S cl i ent parameters.

RISstop_client
RI Sstop_client cl ears al l prepared statements, cl ears al l asynchronous statements,
and stops the RI S cl i ent process.
void RISstop_client( void );
Examples
_________
main
{
RISstop_client();
{
printf("could not stop client\n");
}
}
Status Returns
______________
Notes
______
I f any asynchronous statements are i n incompletestate, then RI Sstop_client fai l s.

RISterminate
RI Sterminatetermi nates the RI S cl i ent process and any RI S servers i t i s usi ng.
RI Sterminateal so frees resources such as shared memory segments and semaphore
sets. Cal l i ng RI Sterminatei s opti onal . RI S automati cal l y termi nates when the
appl i cati on process exi ts.
void RISterminate( void );
Examples
_________
main()
{
RISinitialize("english");
{
printf("Could not initialize\n");
}
RISterminate();
{
printf("Could not terminate\n");
}
}
Status Returns
______________
RI S Forms Functions 6 - 1

RIS Forms Functions
__________________________________________________________________________________________________________________________________________________
6 - 2 RI S Forms Functions


__________________________________________________________________________________________________________________________________________________
6.
RIS Forms Functions
The functi ons i n thi s secti on control the forms of the RI S Schema Manager. To use
embedded RI S forms functi ons i n your appl i cati ons, you must i nstal l the Shamrock.dl l . The
RI S Schema Manager i s a standal one uti l i ty that creates, di spl ays, al ters, or drops RI S
schemas. For more i nformati on on thi s uti l i ty, refer to the RI S SQL Users Guidefor 32-Bit
Applications. The forms functi ons perform the fol l owi ng:
I nitialize I ni ti al i ze the RI S forms.
Set Change the functi ons defi ned RI Sfrm_i ni ti al i ze.
Displayed Check to see i f a form i s currentl y di spl ayed.
Display Di spl ay a form.
Erase Erase a form.

You must cal l the i ni ti al i ze functi on (RI Sfrm_initialize) before cal l i ng the other
RI S forms functi ons.
The functi ons can control the fol l owi ng forms:
Al ter Tabl e Form
Create Schema Form
Create Tabl e Form
Data Defi ni ti on Form
Di cti onary Access Form
Drop Schema Form
Drop Tabl e Form
Excl ude Form
I ncl ude Form
Locate Cl i ent Form
Modi fy DB2 Password Form
Modi fy Node I nfo Form
Modi fy Schema Password Form
RI S Database Form
Schema Defi ni ti on Form
Schema Fi l e Form
Schema I nformati on Form
Schema Manager Form
Secure Schema Access Form
Set Form
Tabl e I nformati on Form
The fol l owi ng are i ncl ude fi l es for forms functi ons:
utl_err.h
risforms.h
risforms.prt
ris.h

The fol l owi ng are l i brari es for forms functi ons:
ris.a
risforms.a
xrisforms.a
The fol l owi ng are exampl e programs for forms functi ons:
frmsample1.c
frmsample2.c
xfrmsample1.c
xfrmsample2.c
6.2 InitializeForms Function

You must cal l the RI Sfrm_initializefuncti on before cal l i ng the other RI S forms
functi ons.
extern int RISfrm_initialize(RISfrm_init_parms *init_parms);
Data Type
__________
Argument
__________
I / O
____
Description
___________
RI Sfrm_i ni t_parms *init_parms I Poi nter to a structure whi ch
contai ns poi nters to user-
defi ned functi ons.
Notes
______
The RI Sfrm_init_parms data type i s defi ned i n the risforms.h i ncl ude fi l e as fol l ows:
typedef struct RISfrm_init_parms_s
{
/*
** Notification routines
*/
void (*pre_notification_routine)();
void (*post_notification_routine)();
/*
** Initialization routines
*/
void (*alter_table_init_routine)();
void (*create_schema_init_routine)();
void (*create_table_init_routine)();
void (*data_definition_init_routine)();
void (*db2pass_init_routine)();
void (*dict_access_init_routine)();
void (*drop_schema_init_routine)();
void (*drop_table_init_routine)();
void (*exclude_init_routine)();
void (*include_init_routine)();
void (*locate_client_init_routine)();
void (*node_info_init_routine)();
void (*ris_dbs_init_routine)();

void (*schema_access_init_routine)();
void (*schema_definition_init_routine)();
void (*schema_file_init_routine)();
void (*schema_info_init_routine)();
void (*schema_mgr_init_routine)();
void (*schema_password_init_routine)();
void (*set_init_routine)();
void (*table_info_init_routine)();
/*
** Execution routines
*/
int (*alter_table_exec_routine)();
int (*create_schema_exec_routine)();
int (*create_table_exec_routine)();
int (*db2pass_exec_routine)();
int (*dict_access_exec_routine)();
int (*drop_schema_exec_routine)();
int (*drop_table_exec_routine)();
int (*exclude_exec_routine)();
int (*include_exec_routine)();
int (*node_info_exec_routine)();
int (*schema_access_exec_routine)();
int (*schema_password_exec_routine)();
int (*set_exec_routine)();
/*
** Error Handler
*/
int (*error_handler_routine)();
/*
** Display Help Buttons
*/
char display_help_buttons;
} RISfrm_init_parms;
These fi el ds, except display_help_buttons, are poi nters to your functi ons. RI S automati cal l y
cal l s the functi ons after vari ous events, as descri bed i n the fol l owi ng l i st. To i gnore an event,
set the correspondi ng fi el d to NULL. To i gnore al l events, set the init_parms argument to
NULL. To di spl ay Hel p buttons on the forms set di spl ay_hel p_buttons to 1, otherwi se set i t
to 0.
I f you provi de the fol l owi ng functi ons, RI S cal l s them i mmedi atel y before or after any
user i nput to any of the RI S forms.
void (*pre_notification_routine)()
void (*post_notification_routine)()
Defi ne these functi ons as fol l ows:
void pre_notification_routine( f_label, g_label, value, fp )
int f_label; /* form label */
int g_label; /* gadget label */
double value; /* value of the gadget */
Form fp; /* pointer to the form */
post_notification_routine( f_label, g_label, value, fp )
int f_label; /* form label */
int g_label; /* gadget label */

double value; /* value of the gadget */
The risforms.h i ncl ude fi l e contai ns the form and gadget l abel s. For more i nformati on
about form noti fi cati on routi nes, see the I / Forms Programmers Guide.
I f you provi de the fol l owi ng functi ons, RI S cal l s each one i mmedi atel y before i ts
respecti ve form di spl ays.
void (*alter_table_init_routine)()
void (*create_schema_init_routine)()
void (*create_table_init_routine)()
void (*data_definition_init_routine)()
void (*db2pass_init_routine)()
void (*dict_access_init_routine)()
void (*drop_schema_init_routine)()
void (*drop_table_init_routine)()
void (*exclude_init_routine)()
void (*include_init_routine)()
void (*locate_client_init_routine)()
void (*node_info_init_routine)()
void (*ris_dbs_init_routine)()
void (*schema_access_init_routine)()
void (*schema_definition_init_routine)()
void (*schema_file_init_routine)()
void (*schema_info_init_routine)()
void (*schema_mgr_init_routine)()
void (*schema_password_init_routine)()
void (*set_init_routine)()
void (*table_info_init_routine)()
void alter_table_init_routine( fp )
void create_schema_init_routine( fp )
void create_table_init_routine( fp )
void data_definition_init_routine( fp )
void db2pass_init_routine( fp )
void dict_access_init_routine( fp )
void drop_schema_init_routine( fp )
void drop_table_init_routine( fp )
void exclude_init_routine( fp )

void include_init_routine( fp )
void locate_client_init_routine( fp )
void node_info_init_routine( fp )
void ris_dbs_init_routine( fp )
void schema_access_init_routine( fp )
void schema_definition_init_routine( fp )
void schema_file_init_routine( fp )
void schema_info_init_routine( fp )
void schema_mgr_init_routine( fp )
void schema_password_init_routine( fp )
void set_init_routine( fp )
void table_info_init_routine( fp )
I f you provi de the fol l owi ng functi ons, RI S cal l s each one when the user sel ects the
execute button on the respecti ve form.
int (*alter_table_exec_routine)()
int (*create_schema_exec_routine)()
int (*create_table_exec_routine)()
int (*db2pass_exec_routine)()
int (*dict_access_exec_routine)()
int (*drop_schema_exec_routine)()
int (*drop_table_exec_routine)()
int (*exclude_exec_routine)()
int (*include_exec_routine)()
int (*node_info_exec_routine)()
int (*schema_access_exec_routine)()
int (*schema_password_exec_routine)()
int (*set_exec_routine)()
int alter_table_exec_routine( fp, str )
char *str; /* pointer to the RIS command string to be executed */

int create_schema_exec_routine( fp, str )
int create_table_exec_routine( fp, str )
int drop_table_exec_routine( fp, str )
int db2pass_exec_routine( fp, str )
int dict_access_exec_routine( fp, str )
int drop_schema_exec_routine( fp, str )
int exclude_exec_routine( fp, str )
int include_exec_routine( fp, str )
int node_info_exec_routine( fp, str )
int schema_access_exec_routine( fp, str )
int schema_password_exec_routine( fp, str )
int set_exec_routine( fp, str )
These functi ons must return an i nteger val ue. I f they return a zero (0), RI S does not
execute the RI S command stri ng. I f they return a nonzero, RI S attempts to execute the
RI S command stri ng.
The argument str poi nts to a stati c vari abl e whi ch contai ns the actual RI S command
stri ng to execute. I f you al ter the contents of str, you al so al ter the command that RI S
attempts to execute.

I f you provi de thi s functi on, RI S cal l s i t whenever a RI S error occurs.
int (*error_handler_routine)();
Defi ne thi s functi on as fol l ows:
int error_handler_routine( ris_error, ris_error_str )
int ris_error;
char *ris_error_str;
Thi s functi on must return an i nteger val ue. I f i t returns a zero (0), RI S does not di spl ay
the RI S error stri ng. I f i t returns a nonzero, RI S di spl ays the RI S error stri ng.
The argument ris_error_str poi nts to a stati c vari abl e whi ch contai ns the actual RI S
error stri ng to di spl ay. I f you al ter the contents of ri s_error_str, you al so al ter the error
message that RI S di spl ays.

Before usi ng these routi nes wi th I /Forms, you must cal l the Enter_tools,
Enable_events, and FI _enter functi ons. You must al so l oad the fi xed VLT.
Before usi ng these routi nes wi th I /XForms, you must cal l the XOpenDisplay,
FSEnter, and FI _enter functi ons.
6.3 Set Functions
These functi ons al ter the user-defi ned functi ons cal l ed by RI S.
extern void RISfrm_set_pre_notification_routine(
void (*pre_notification_routine)())
extern void RISfrm_set_post_notification_routine(
void (*post_notification_routine)())
extern void RISfrm_set_form_init_routine(
int form_label,
void (*form_init_routine)())
extern void RISfrm_set_form_exec_routine(
int form_label,
int (*form_exec_routine)())
extern void RISfrm_set_error_handler_routine(
int (*error_handler_routine)())
To al ter the prenoti fi cati on, postnoti fi cati on, and error-handl er routi nes, cal l
RI Sfrm_set_pre_notification_routine, RI Sfrm_set_post_notification_routine, and
RI Sfrm_set_error_handler_routine, passi ng the address of the new functi on as the argument.
These functi ons shoul d be defi ned as descri bed i n the I nitializeForms Function secti on.
To al ter the form_i ni t and form_exec routi nes for a speci fi c form, cal l
RI Sfrm_set_form_init_routineand RI Sfrm_set_form_exec_routine, passi ng the form_label and
the address of the new functi on as the arguments.

Notes
______
I t i s val i d to pass NULL as a functi on address. Thi s cancel s any previ ousl y defi ned
functi ons.
6.4 Displayed Forms Functions
The functi ons i n thi s secti on determi ne i f thei r correspondi ng forms are currentl y di spl ayed.
extern int RISfrm_alter_table_form_displayed(void)
extern int RISfrm_create_schema_form_displayed(void)
extern int RISfrm_create_table_form_displayed(void)
extern int RISfrm_data_def_form_displayed(void)
extern int RISfrm_db2pass_form_displayed(void)
extern int RISfrm_dict_access_form_displayed(void)
extern int RISfrm_drop_schema_form_displayed(void)
extern int RISfrm_drop_table_form_displayed(void)
extern int RISfrm_exclude_form_displayed(void)
extern int RISfrm_include_form_displayed(void)
extern int RISfrm_locate_client_form_displayed(void)
extern int RISfrm_node_info_form_displayed(void)
extern int RISfrm_ris_dbs_form_displayed(void)
extern int RISfrm_schema_access_form_displayed(void)
extern int RISfrm_schema_definition_form_displayed(void)
extern int RISfrm_schema_file_form_displayed(void)
extern int RISfrm_schema_info_form_displayed(void)
extern int RISfrm_schema_mgr_form_displayed(void)
extern int RISfrm_schpass_form_displayed(void)
extern int RISfrm_set_form_displayed(void)
extern int RISfrm_table_info_form_displayed(void)
Status Returns
______________
0 Form i s not currentl y di spl ayed.
non-zero Form i s currentl y di spl ayed.

6.5 Display Forms Functions
The functi ons i n thi s secti on di spl ay thei r correspondi ng forms.

You must cal l the functi on RI Sfrm_initializebefore cal l i ng these functi ons.
extern int RISfrm_display_alter_table_form(void)
extern int RISfrm_display_create_schema_form(void)
extern int RISfrm_display_create_table_form(void)
extern int RISfrm_display_data_def_form(void)
extern int RISfrm_display_db2pass_form(void)
extern int RISfrm_display_dict_access_form(void)
extern int RISfrm_display_drop_schema_form(void)
extern int RISfrm_display_drop_table_form(void)
extern int RISfrm_display_exclude_form(void)
extern int RISfrm_display_include_form(void)
extern int RISfrm_display_locate_client_form(void)
extern int RISfrm_display_node_info_form(void)
extern int RISfrm_display_ris_dbs_form(void)
extern int RISfrm_display_schema_access_form(void)
extern int RISfrm_display_schema_definition_form(void)
extern int RISfrm_display_schema_file_form(void)
extern int RISfrm_display_schema_info_form(void)
extern int RISfrm_display_schema_mgr_form(void)
extern int RISfrm_display_schpass_form(void)
extern int RISfrm_display_set_form(void)
extern int RISfrm_display_table_info_form(void)
Status Returns
______________
RI S_SUCCESS Success defi ned i n ris.h.
Other Error code defi ned i n the utl_err.h i ncl ude fi l e.
Notes
______
To execute the fol l owi ng functi ons, you must set the RI S Defaul t Schema. These functi ons
requi re a defaul t schema to perform RI S queri es:
RISfrm_display_table_info_form
RISfrm_display_create_table_form
RISfrm_display_drop_table_form
RISfrm_display_alter_table_form

6.6 EraseForms Functions
The functi ons i n thi s secti on erase thei r correspondi ng forms.
extern int RISfrm_erase_alter_table_form(void)
extern int RISfrm_erase_create_schema_form(void)
extern int RISfrm_erase_create_table_form(void)
extern int RISfrm_erase_data_def_form(void)
extern int RISfrm_erase_db2pass_form(void)
extern int RISfrm_erase_dict_access_form(void)
extern int RISfrm_erase_drop_schema_form(void)
extern int RISfrm_erase_drop_table_form(void)
extern int RISfrm_erase_exclude_form(void)
extern int RISfrm_erase_include_form(void)
extern int RISfrm_erase_locate_client_form(void)
extern int RISfrm_erase_node_info_form(void)
extern int RISfrm_erase_ris_dbs_form(void)
extern int RISfrm_erase_schema_access_form(void)
extern int RISfrm_erase_schema_definition_form(void)
extern int RISfrm_erase_schema_file_form(void)
extern int RISfrm_erase_schema_info_form(void)
extern int RISfrm_erase_schema_mgr_form(void)
extern int RISfrm_erase_schpass_form(void)
extern int RISfrm_erase_set_form(void)
extern int RISfrm_erase_table_info_form(void)
Status Returns
______________
RI S_SUCCESS Success defi ned i n ris.h.
Other Error code defi ned i n the utl_err.h i ncl ude fi l e.

6.7 Forms Functions Error Handling
I f an error occurs, al l RI S forms functi ons pl ace i nformati on about the error i n the
RI S_forms_error gl obal vari abl e. I f an I /Forms error occurs, i nformati on about the I /Forms
error i s pl aced i n the RI S_forms_error gl obal vari abl e. RI S_forms_error i s defi ned i n the
risforms.h i ncl ude fi l e as fol l ows:
typedef struct ris_forms_error_info
{
int error;
char error_name[48];
char error_message[256];
int FI_error;
char FI_error_name[48];
char FI_error_message[256];
} ris_forms_error_info;
extern ris_forms_error_info RIS_forms_error;
Notes
______
I f a RI S error occurs, RI S_forms_error.error i s set to RI SUTL_E_RI S_ERROR. Al so, the
gl obal vari abl es SQLCODE and risca contai ns i nformati on about the RI S error. The report
error statement can be executed to retri eve a message resul ti ng from the error.

Embedded Loading and Unloading of RI S Objects 7 - 1

Embedded Loadingand Unloadingof RIS Objects
__________________________________________________________________________________________________________________________________________________
7 - 2 Embedded Loading and Unloading of RI S Objects


__________________________________________________________________________________________________________________________________________________
7.
Embedded Loadingand Unloadingof RIS Objects
RI S provi des an embedded programmi ng functi on i nterface to the rislod and risunlod
uti l i ti es. Thi s embedded programmi ng functi on i nterface passes detai l ed i nformati on about
RI S objects to the ri sl od and ri sunl od uti l i ti es usi ng the risloddes and the risulddes
structures. The semanti cs and constrai nts of these structures are si mi l ar to the command
l i ne versi ons of ri sl od and ri sunl od. Thi s secti on l i sts the i ncl ude fi l es, l i brari es, and exampl e
programs needed for embedded l oadi ng and unl oadi ng. I t al so gi ves di recti ons for usi ng the
risloddes and the risulddes structures as arguments i n the ri sl od and ri sunl od uti l i ti es. See
the risloddes Structures and risulddes Structures secti ons for detai l ed i nformati on about
risloddes and risulddes.

Read the secti ons risunlod and rislod of the RI S Utilities Guidebefore usi ng
risloddes or risulddes.
7.1 Usingrisloddesfor Embedded Loading
The risloddes structure, defi ned i n the rislduld.h i ncl ude fi l e, speci fi es the RI S objects to l oad
from external ASCI I fi l es i nto RI S schemas. You can speci fy fi el ds i n the risloddes structure
to do the fol l owi ng:
Create schemas
Create tabl es
Load data i nto tabl es
Create vi ews
Create i ndexes
Grant pri vi l eges
The risloddes structure i s a two way communi cati on l i nk between an appl i cati on and the
ri sl od uti l i ty. I n addi ti on to l oadi ng RI S objects, the risloddes structure returns the status
i nformati on about:
Schemas
Tabl es
I ndexes

Pri vi l eges
Number of rows l oaded per tabl e
Number of rows rejected by RI S
See the secti on Directions for Usingrisloddes and risulddes for detai l ed i nformati on on usi ng
risloddes.
7.2 Usingrisulddes for Embedded Unloading
The risulddes structure, defi ned i n the rislduld.h i ncl ude fi l e, speci fi es the RI S objects to
unl oad from RI S schemas i nto external ASCI I fi l es. You can speci fy fi el ds i n the risulddes
structure to do the fol l owi ng:
Schemas
Tabl es wi th data
Tabl es wi thout data
Vi ews
I ndexes
Pri vi l eges
The risulddes structure i s a two way communi cati on l i nk between an appl i cati on and the
ri sunl od uti l i ty. I n addi ti on to unl oadi ng RI S objects, the risulddes structure returns the
fol l owi ng status i nformati on about the RI S objects bei ng unl oaded:
Schemas
Tabl es
I ndexes
Pri vi l eges
See the secti on Directions for Usingrisloddes and risulddes for detai l ed i nformati on about
risulddes.
The fol l owi ng are l oad and unl oad i ncl ude fi l es:
rislduld.h
ris.h
utl_err.h

The l oad and unl oad l i brary i s:
rislduld.lib
ris.lib
The fol l owi ng are l oad and unl oad exampl e programs:
lodsamp1.cthrough lodsamp6.c
uldsamp1.cthrough uldsamp3.c
7.4 risloddesStructures
The risloddes structure has 16 fi el ds. Two of these fi el ds, struct risloddbs and struct
rislodsch, are poi nters to other structures. The risloddbs structure hol ds database
i nformati on, and the rislodsch structure hol ds schema i nformati on.
The fol l owi ng graphi cs show the vari ous structure rel ati onshi ps.


The fol l owi ng tabl e l i sts the i nput fi el ds of risloddes structure:
Data Type
__________
Name
______
Description
___________
i nt nonansi mode 0 = ANSI mode on.
1 = ANSI mode off.
i nt preserve_bl anks 1 = preserve_bl anks on.
0 = preserve_bl anks off.
Defaul t i s 0.
char fi l emode Fi l emode for output fi l es such as
badfi l e and l ogfi l e. Fi l emodes
i ncl ude:
w= wri te.
a = append.
e= exi st.
Defaul t i s e.
char [RI S_MAX_PATH_SI ZE] mai nfi l e I nput fi l ename for l oadi ng.
Defaul t i s ris.dmp.
char [RI S_MAX_PATH_SI ZE] badfi l e Bad fi l ename for l oadi ng.
Defaul t i s ris.bad.

char [RI S_MAX_PATH_SI ZE] l ogfi l e Log fi l ename for l oadi ng.
Defaul t i s ris.log.
char del i mi ter Del i mi ter used for fi el ds of char
type. Defaul t i s si ngl e
quotati on().
i nt commi t_i nterval Count i ndi cati ng when to commi t.
I t commi ts after i nserti ng a
speci fi c number of
commi t_i nterval rows.
Defaul t i s 25.
i nt dbs_count Number of risloddbs structures.
struct risloddbs *dbs Poi nter to an array of risloddbs
structures. There i s one structure
for each database type. See
risloddbs Structurefor more
i nformati on.
i nt schema_count Number of schemas to l oad.
struct rislodsch *schemas Poi nter to an array of rislodsch
for each schema. See rislodsch
Structurefor more i nformati on.
The fol l owi ng tabl e l i sts the output fi el ds of the risloddes structure:
Data Type
__________
Name
______
Description
___________
l ong l od_err_code Error code (defi ned i n the
RI Slod_err.h i ncl ude fi l e) returned
by l oader.
l ong ri s_err_code Error code (defi ned i n the RI S
error i ncl ude fi l es) returned by
RI S.
l ong db_err_code Error code returned by underl yi ng
database. Refer to speci fi c
database error messages.
char sql warni ngs[8] Warni ngs set by RI S. Refer to
ris.h.

7.4.1 risloddbs Structure
Access the risloddbs structure through a poi nter i n risloddes. The risloddbs structure has
the fol l owi ng i nput fi el ds:
Data Type
__________
Name
______
Description
___________
char
[RI S_MAX_KEYWORD_SI ZE]
dbsname Database name to enforce. For
exampl e, I NFORMI X or ORACLE.
7.4.2 rislodsch Structure
Access the rislodsch structure through a poi nter i n risloddes. There i s one rislodsch
structure for each schema l oaded. Wi thi n rislodsch, there are four nested structures. Fi el ds
bel ongi ng to these structures are prefi xed by tabinfo, viewinfo, indxtabinfo, and granttabinfo.
The fol l owi ng tabl e l i sts the i nput fi el ds of the rislodsch structure:
Data Type
__________
Name
______
Description
___________
char [RI S_MAX_I D_SI ZE] schname Source schema name to l oad.
char [RI S_MAX_I D_SI ZE] schpass Source schema password.
char [RI S_MAX_I D_SI ZE] osname Operati ng system username.
char [RI S_MAX_I D_SI ZE] ospass Operati ng system password.
char [RI S_MAX_I D_SI ZE] username Database username.
Requi red i f usi ng the defaul t
schema statement i n an
unl oad fi l e to access a secure
schema. Otherwi se, thi s fi el d
i s i gnored.
char [RI S_MAX_I D_SI ZE] userpass Database user password.
char [RI S_MAX_I D_SI ZE] new_schname Desti nati on (an exi sti ng)
schema name.
char [RI S_MAX_I D_SI ZE] new_schpass Desti nati on schema
password.

char [RI S_MAX_I D_SI ZE] new_user Requi red when the
desti nati on schema speci fi ed
i n new_schnamei s a secure
schema. See the declare
schema statement for more
i nformati on.
char [RI S_MAX_I D_SI ZE] new_userpass Requi red when the
desti nati on schema speci fi ed
i n new_schnamei s a secure
schema. See the declare
schema statement for more
i nformati on.
char sel ect_mode I ndi cates how many schema
objects to l oad.
a = l oad al l objects. Al l
fol l owi ng fi el ds i n *info
structure become output
fi el ds.
s = l oad some objects. Al l
structure become i nput fi el ds.
n = l oad no objects. Al l
structure are i gnored.
Fi el ds of the tabinfonested structure:
Data Type
__________
Name
______
Description
___________
char sel ect_mode I ndi cates how many tabl es to
l oad.
a = l oad al l tabl e i nformati on.
s = l oad some tabl e
i nformati on.
n = l oad no tabl e i nformati on.
i nt i gnore_create_error I ndi cates whether or not to
i gnore tabl e error.
1 = i gnore tabl e exi stence
error.
0 = do not i gnore tabl e
exi stence error.

i nt wi th_data I ndi cates whether to l oad
tabl e defi ni ti on or to l oad
tabl e defi ni ti on wi th data.
1 = l oad tabl e defi ni ti on onl y.
0 = l oad both tabl e defi ni ti on
and data.
i nt cl ear_exi st_data I ndi cates whether or not to
cl ear data before l oadi ng.
1 = del ete rows before l oadi ng.
0 = do not del ete rows before
l oadi ng.
i nt tabl e_count Number of tabl es to l oad.
struct rislodtab *tabl es Poi nter to an array of
rislodtabstructures. There i s
one structure for each tabl e.
See rislodtabStructurefor
more i nformati on.
Fi el ds of the viewinfonested structure:
Data Type
__________
Name
______
Description
___________
char sel ect_mode I ndi cates how many vi ews to
l oad.
a = l oad al l vi ew i nformati on.
s = l oad some vi ew
i nformati on.
n = l oad no vi ew i nformati on.
i nt vi ew_count Number of vi ews to l oad.
struct rislodview *vi ews Poi nter to an array of
rislodviewstructures. There
i s one structure for each vi ew.
See rislodviewStructurefor
more i nformati on.
Fi el ds of the indxtabinfonested structure:
Data Type
__________
Name
______
Description
___________
char sel ect_mode I ndi cates how much i ndex
i nformati on to l oad per tabl e.
a = l oad al l i ndex i nformati on.
s = l oad some i ndex
i nformati on.
n = l oad no i ndex i nformati on.

i nt i ndxtab_count Number of tabl es wi th
i ndexes to l oad.
struct rislodindx *i ndxtabs Poi nter to array of rislodindx
structures. There i s one
structure for each tabl e. See
rislodindxStructurefor more
i nformati on.
Fi el ds of the granttabinfonested structure:
Data Type
__________
Name
______
Description
___________
char sel ect_mode I ndi cates how much pri vi l ege
i nformati on to l oad.
a = l oad al l pri vi l ege
i nformati on.
s = l oad some pri vi l ege
i nformati on.
n = l oad no pri vi l ege
i nformati on.
i nt granttab_count Number of rel ati ons whose
pri vi l eges are to be l oaded.
struct rislodgrant *granttabs Poi nter to an array of
rislodgrant structures. There
i s one structure for each
rel ati on (tabl e or vi ew). See
rislodindxStructurefor more
i nformati on.

The fol l owi ng tabl e l i sts the output fi el ds of the rislodsch structure:
Data Type
__________
Name
______
Description
___________
l ong l od_err_code Error code (defi ned i n
RI Slod_err.h i ncl ude fi l e)
returned by l oader.
l ong ri s_err_code Error code (defi ned i n RI S
error i ncl ude fi l es) returned
by RI S.
l ong db_err_code Error code returned by
underl yi ng database. Refer to
speci fi c database error
messages.
char sql warni ngs[8] Warni ngs set by RI S. Refer
to ris.h.

rislodtab Structure
Access the rislodtabstructure through a poi nter i n rislodsch. There i s one rislodtab
structure for each tabl e l oaded. The fol l owi ng tabl e l i sts the fi el ds of thi s structure.
The tabname fi el d i s an i nput and output fi el d. The remai ni ng fi el ds are output
fi el ds onl y.
Data Type
__________
Name
______
Description
___________
char[RI S_MAX_I D_SI ZE] tabname Tabl e name.
i nt rows_l oaded Number of successful l y l oaded
rows.
i nt err_rows Number of rows not l oaded.
l ong l od_err_code Error code (defi ned i n the
by l oader.
RI S.
ris.h.

rislodviewStructure
Access the rislodviewstructure through a poi nter i n rislodsch. There i s one
rislodviewstructure for each vi ew l oaded. The fol l owi ng tabl e l i sts the fi el ds of thi s
structure. The vi ewname fi el d i s an i nput and output fi el d. The remai ni ng fi el ds are
output fi el ds onl y.
Data Type
__________
Name
______
Description
___________
char[RI S_MAX_I D_SI ZE] vi ewname Vi ew name.
by l oader.
l ong ri s_err_code Error code (defi ned i n RI S*_err.h
i ncl ude fi l e) returned by RI S.
ris.h.

rislodindx Structure
Access the rislodindxstructure through a poi nter i n rislodsch. There i s one
rislodindxstructure for each tabl e or vi ew wi th i ndexes l oaded. The tabname fi el d i s
an i nput and output fi el d. The remai ni ng fi el ds are output fi el ds onl y.
Data Type
__________
Name
______
Description
___________
i nt i ndexes_l oaded Number of i ndexes created.
i nt err_i ndexes Number of i ndexes not created.
by l oader.
RI S.
ris.h.

rislodgrant Structure
Access the rislodgrant structure through a poi nter i n rislodsch. There i s one
rislodgrant structure for each tabl e or vi ew wi th pri vi l eges l oaded. The table_owner
and tabnamefi el ds are i nput and output fi el ds. The remai ni ng fi el ds are output
fi el ds onl y.
Data Type
__________
Name
______
Description
___________
char[RI S_MAX_I D_SI ZE] tabl e_owner Schema name that owns the tabl e
(opti onal ).
i nt grants_l oaded Number of pri vi l eges granted.
i nt err_grants Number of errors i ncurred whi l e
granti ng pri vi l eges.
by l oader.
RI S.
ris.h.

7.5 risulddes Structures
The risulddes structure has ni ne fi el ds. One of these fi el ds, struct risuldsch, i s a poi nter to a
structure hol di ng i nformati on about each schema that i s unl oaded.
The fol l owi ng graphi c shows the structural rel ati onshi ps.


The fol l owi ng tabl e l i sts the i nput fi el ds of the risulddes structure:
Data Type
__________
Name
______
Description
___________
char fi l emode Fi l emode for output fi l es such as
mai nfi l e and datafi l e. Fi l emodes
i ncl ude:
w= wri te.
a = append.
e= exi st.
Defaul t i s e.
i nt preserve_bl anks 1 = preserve_bl anks on.
0 = preserve_bl anks off.
Defaul t i s 0.
char [RI S_MAX_PATH_SI ZE] mai nfi l e Output fi l ename for unl oadi ng.
Defaul t i s ris.dmp.
i nt schema_count Number of schemas to unl oad.
struct risuldsch *schemas Poi nter to an array of risuldsch
for each schema. See risuldsch
Structurefor more i nformati on.
The fol l owi ng tabl e l i sts the output fi el ds of the risulddes structure:
Data Type
__________
Name
______
Description
___________
l ong ul d_err_code Error code (defi ned i n
RI Suld_err.h i ncl ude fi l e) returned
by unl oader.
l ong ri s_err_code Error code (defi ned i n RI S error
i ncl ude fi l e) returned by RI S.
ris.h.

7.5.1 risuldsch Structure
Access the risuldsch structure through a poi nter i n risulddes. There i s one risuldsch
structure for each schema unl oaded. Wi thi n risuldsch, there are four nested structures.
Fi el ds bel ongi ng to these structures are prefi xed by tabinfo, viewinfo, indxtabinfo, and
granttabinfo.
The fol l owi ng tabl e l i sts the i nput fi el ds of the risuldsch structure:
Data Type
__________
Name
______
Description
___________
char [RI S_MAX_I D_SI ZE] schname Schema name to unl oad.
char [RI S_MAX_I D_SI ZE] schpass Schema password.
char [RI S_MAX_I D_SI ZE] osname Secure schema username. I f
osnamei s speci fi ed, the schema
i s unl oaded as a secure schema,
even i f the schema i s not a
secure schema i n the current
database.
char [RI S_MAX_I D_SI ZE] ospass Secure schema password.
Requi red i f the osnamefi el d
has a password.
char [RI S_MAX_I D_SI ZE] dbname Database username for secure
schemas requi red by certai n
RDBMSs.
char [RI S_MAX_I D_SI ZE] dbpass Database password for secure
schemas requi red by certai n
RDBMSs.
char sel ect_mode I ndi cates how many schema
objects to unl oad.
a = unl oad al l objects. Al l
structures become output
fi el ds.
s = unl oad some objects. Al l
structures become i nput fi el ds.
n = unl oad no objects. Al l
structures are i gnored.

Fi el ds of the tabinfonested structure:
Data Type
__________
Name
______
Description
___________
char sel ect_mode I ndi cates how many tabl es to
unl oad.
a = unl oad al l tabl e
i nformati on.
s = unl oad some tabl e
i nformati on.
n = unl oad no tabl e
i nformati on.
i nt wi th_data I ndi cates whether to unl oad
tabl e defi ni ti on or to unl oad
tabl e defi ni ti on wi th data.
1 = i gnore tabl e exi stence error.
0 = do not i gnore tabl e
exi stence error.
i nt separate_dfi l e I ndi cates whether data shoul d
be unl oaded i n the same fi l e or
di fferent fi l e than the mai nfi l e.
1 = di fferent dfi l e.
0 = same fi l e as mai nfi l e.
i nt vari abl e_data_format I ndi cates whether data shoul d
be unl oaded i n fi xed or vari abl e
format.
1 = vari abl e.
0 = fi xed.
i nt tabl e_count Number of tabl es to unl oad.
struct risuldtab *tabl es Poi nter to an array of risuldtab
risuldtabStructurefor more
i nformati on.

Fi el ds of viewinfonested structure:
Data Type
__________
Name
______
Description
___________
char sel ect_mode I ndi cates how many vi ews to
unl oad.
a = unl oad al l vi ew
i nformati on.
s = unl oad some vi ew
i nformati on.
i nt vi ew_count Number of vi ews to unl oad.
struct risuldview *vi ews Poi nter to an array of
risuldviewstructures. There i s
one structure for each vi ew.
See risuldviewStructurefor
more i nformati on.
Fi el ds of indxtabinfonested structure:
Data Type
__________
Name
______
Description
___________
char sel ect_mode I ndi cates how much i ndex
i nformati on to unl oad per tabl e.
a = unl oad al l i ndex
i nformati on.
s = unl oad some i ndex
i nformati on.
n = unl oad no i ndex
i nformati on.
i nt i ndxtab_count Number of tabl es whose
i ndexes are unl oaded.
struct risuldindx *i ndxtabs Poi nter to array of risuldindx
risuldindxStructurefor more
i nformati on.

Fi el ds of granttabinfonested structure:
Data Type
__________
Name
______
Description
___________
char sel ect_mode I ndi cates how many pri vi l eges
to unl oad per tabl e/vi ew.
a = unl oad al l pri vi l ege
i nformati on.
s = unl oad some pri vi l ege
i nformati on.
n = unl oad no pri vi l ege
i nformati on.
i nt granttab_count. Number of rel ati ons whose
pri vi l eges are unl oaded.
struct risuldgrant *granttabs Poi nter to an array of
risuldgrant structures. There
i s one structure for each
rel ati on (tabl e or vi ew). See
risuldgrant Structurefor more
i nformati on.
The fol l owi ng tabl e l i sts the output fi el ds of the risuldsch structure:
Data Type
__________
Name
______
Description
___________
RI Suld_err.h i ncl ude fi l es)
returned by unl oader.
error i ncl ude fi l es) returned
by RI S.
l ong db_err_code Error code returned by
underl yi ng database. Refer to
speci fi c database error
messages.
char sql warni ngs[8] Warni ngs set by RI S. Refer
to ris.h.

risuldtab Structure
Access the risuldtabstructure through a poi nter i n risuldsch. There i s one risuldtab
structure for each tabl e unl oaded. The fol l owi ng tabl e l i sts the fi el ds of thi s
structure. The tabname fi el d i s an i nput and output fi el d. The remai ni ng fi el ds are
Data Type
__________
Name
______
Description
___________
char *wherecl ause Opti onal wherecl ause to unl oad
parti al data.
char[RI S_MAX_I D_SI ZE] data_fi l ename Fi el d returni ng the datafi l e i f
separate_dfile=1.
i nt rows_unl oaded Number of successful l y unl oaded
rows.
i nt err_rows Number of rows not unl oaded.
by unl oader.
l ong ri s_err_code Error code (defi ned i n
by RI S.
ris.h.

risuldviewStructure
Access the risuldviewstructure through a poi nter i n risuldsch. There i s one
risuldviewstructure for each vi ew unl oaded. The fol l owi ng tabl e l i sts the fi el ds of
thi s structure. The vi ewname fi el d i s an i nput and output fi el d. The remai ni ng fi el ds
are output fi el ds onl y.
Data Type
__________
Name
______
Description
___________
char[RI S_MAX_I D_SI ZE] vi ewname Vi ew name.
by unl oader.
RI S.
ris.h.

risuldindx Structure
Access the risuldindxstructure through a poi nter i n risuldsch. There i s one
risuldindxstructure for each tabl e or vi ew wi th i ndexes unl oaded. The tabnamefi el d
i s an i nput and output fi el d. The remai ni ng fi el ds are output fi el ds onl y.
Data Type
__________
Name
______
Description
___________
i nt i ndexes_l oaded Number of i ndexes unl oaded.
i nt err_i ndexes Number of i ndexes not unl oaded.
l ong ul d_err_code Error code returned by unl oader i f
any i ndex l evel error encountered.
For exampl e, I nvalid indxtab
selectmode, Tableor viewnot
found, and so forth.
l ong ri s_err_code Error code returned by RI S i f any
error encountered.
database i f any error encountered.
ris.h.

risuldgrant Structure
Access the risuldgrant structure through a poi nter i n risuldsch. One risuldgrant
structure i s al l ocated for each tabl e or vi ew wi th pri vi l eges unl oaded. The
table_owner and tabnamefi el ds are i nput and output fi el ds. The remai ni ng fi el ds are
Data Type
__________
Name
______
Description
___________
char[RI S_MAX_I D_SI ZE] tabl e_owner Schema owner name (opti onal ).
i nt grants_unl oaded Number of pri vi l eges unl oaded.
i nt err_grants Number of errors i ncurred whi l e
granti ng pri vi l eges.
by unl oader.
RI S.
ris.h.

7.6 Directions for Usingrisloddesand risulddes
The fol l owi ng secti ons descri be the necessary steps for usi ng risloddes and risulddes. The
necessary l oader/unl oader functi ons are descri bed i n the secti on RI S_loader and
RI S_unloader Embedded Functions.
7.6.1 Directions for Usingrisloddes
Fol l ow these steps when worki ng wi th the risloddes structure:
1. Defi ne a structure of type risloddes. The fol l owi ng are defaul t val ues for thi s structure:
Field Name
___________
Default Value
_____________
del i mi ter si ngl e quotati on ()
commi t_i nterval 25
nonansi mode ansi mode on (0)
fi l emode e
mai nfi l e ri s.dmp
badfi l e ri s.bad
l ogfi l e ri s.l og
2. I ni ti al i ze the fi el ds of the risloddes structure.
3. Assi gn top-l evel fi el ds such as ansi mode, fi l emode, mai nfi l e, and so forth.
4. Set the schema_count fi el d to a posi ti ve val ue i ndi cati ng number of schemas to l oad.
5. Al l ocate an array of rislodsch structures usi ng schema_count (one per schema).
6. Assi gn schema i nformati on, that i s, set the appropri ate fi el ds of each rislodsch
structure.
a. Set schema sel ect_mode to a (al l objects of the schema) or s (some of the objects
of the schema). There i s no defaul t.
b. I f you set sel ect_mode to a, then i gnore al l the other fi el ds of the rislodsch
structure. Al so i gnore rislodtab, rislodview, rislodindx, and rislodgrant structures.
Appropri ate structure members returni ng status are set by the l oader. Al l
*i nfo.sel ect_mode fi el ds are set to a by the l oader. The fol l owi ng are defaul t
val ues for the rislodtabstructure (when schemas sel ect_mode i s set to a):
Field Name
___________
Default Value
_____________
wi th_data 1
i gnore_create_error 1
cl ear_exi st_data 1

c. I f you set select_modeto s, set the fol l owi ng fi el ds:
tabinfo.select_modeand tablerel ated fi el ds
viewinfo.select_modeand viewrel ated fi el ds
indxtabinfo.select_modeand indexrel ated fi el ds
granttabinfo.select_modeand grant rel ated fi el ds
d. I f you set *info.select_modeto s, then al l ocate an array of rislod* structures for
each object. The array si ze i s *info.*_count.
7. Cal l the fol l owi ng functi on to l oad RI S objects i ndi cated by the risloddes structure:
risloddes my_lod;
RIS_loader(&my_lod);
8. Cal l the fol l owi ng functi on to pri nt the status of the risloddes structure (opti onal ):
RISlod_print_risloddes(&my_lod);
OR
RISlod_fprint_risloddes(stdout, &my_lod);

Thi s functi on shoul d be cal l ed onl y after cal l i ng RI S_l oader().
9. Li nk ris.liband rislduld.libl i brari es to your appl i cati on objects.

Each RI S object has i ts own lod_err_code, ris_err_code, db_err_code, and
sqlwarningto i ndi cate l ast rel ated error codes pertai ni ng to that object.
The risloddes functi on provi des no BLOB support.

7.6.2 Directions for Usingrisulddes
Fol l ow these steps when worki ng wi th the risulddes structure:
1. Defi ne a structure of type risulddes. The fol l owi ng are defaul t val ues for thi s structure:
Field Name
___________
Default Value
_____________
fi l emode e
mai nfi l e ri s.dmp
2. I ni ti al i ze the fi el ds of the risulddes structure.
3. Assi gn top-l evel fi el ds such as fi l emode, mai nfi l e, and so forth.
4. Set the schema_count fi el d to a posi ti ve val ue i ndi cati ng number of schemas to unl oad.
5. Al l ocate an array of risuldsch structures usi ng schema_count (one per schema).
6. Assi gn schema i nformati on, that i s, set the appropri ate fi el ds of the risulddes fi el ds.
a. Set schema select_modeto a or s. There i s no defaul t.
b. I f you set select_modeto a, then i gnore al l the other fi el ds of risuldsch structures.
Appropri ate structure members returni ng schemas are set by the unl oader. Al l
the *info.select_modefi el ds are set to a by the unl oader. The fol l owi ng are defaul t
val ues for fi el ds i n the risuldtabstructure (when schemas select_modei s set to a):
Field Name
___________
Default Value
_____________
wi th_data 1
separate_dfi l e 0
vari abl e_data_format 0
c. I f you set select_modeto s, then set the fol l owi ng vari abl es:
tabinfo.select_modeand tablerel ated fi el ds
viewinfo.select_modeand viewrel ated fi el ds
indxtab.select_modeand indexrel ated fi el ds
granttabinfo.select_modeand grant rel ated fi el ds
d. I f *info.select_modei s set to s, then al l ocate an array of risuld* structures for each
object. The array si ze i s *info.*_count.

7. Cal l the fol l owi ng functi on to pri nt RI S objects i ndi cated by the risulddes structure:
risuldes my_uld;
RIS_unloader(&my_uld);
8. Cal l the fol l owi ng functi on to pri nt RI S objects i ndi cated by the risulddes structure
(opti onal ):
RISuld_print_risulddes(&my_uld);
OR
RISuld_fprint_risulddes(stdout, &my_uld);

Thi s functi on shoul d be cal l ed onl y after cal l i ng RI S_unl oader().
9. Li nk the ris.liband rislduld.libl i brari es to your appl i cati on objects.

Each RI S object has i ts own lod_err_code, ris_err_code, db_err_code, and
sqlwarningto i ndi cate l ast rel ated error codes pertai ni ng to that object.
The risulddes functi on provi des no BLOB support.

7.7 RIS_loader and RIS_unloader Embedded Functions
The risloddes or risulddes structure communi cates between an appl i cati on and the
underl yi ng ri sl od or ri sunl od uti l i ty. The structure i s passed to RI S_l oader or RI S_unl oader
functi ons. The appl i cati on recei ves the necessary i nformati on about l oadi ng or unl oadi ng
RI S objects from the structure. The l oader or unl oader uti l i ty returns the status of RI S
objects l oaded or unl oaded through the same structure. The fol l owi ng embedded functi ons
perform l oadi ng and unl oadi ng operati ons.
RIS_loader
Thi s functi on uses the risloddes structure to i nterface wi th the ri sl od uti l i ty. You
assi gn speci fi c l oad i nformati on for ri sl od usi ng fi el ds of the risloddes structure. The
ri sl od uti l i ty then assi gns speci fi c output to fi el ds of the risloddes structure duri ng
functi on executi on.
#include "rislduld.h"
int RIS_loader (risloddes *risloddes_ptr);
__________________
Description
___________
risloddes_ptr Poi nter to risloddes structure defi ned i n RI Sloduld.h header
fi l e. See the secti on risloddes Structures for more
i nformati on.
Status Returns
______________
Success 0
Fai l ure -1

RIS_unloader
Thi s functi on uses the risulddes structure to i nterface wi th the ri sunl od uti l i ty. You
assi gn speci fi c unl oad i nformati on for ri sunl od usi ng fi el ds of the risulddes structure.
The ri sunl od uti l i ty then assi gns speci fi c output to fi el ds of the risulddes structure
duri ng functi on executi on.
int RIS_unloader (risulddes *risulddes_ptr);
__________________
Description
___________
risulddes_ptr Poi nter to risulddes structure defi ned i n RI Sloduld.h header
fi l e. See the secti on risulddes Structures for more i nformati on.
Status Returns
______________
Success 0
Fai l ure -1
RISlod_fprint_risloddes
Thi s functi on pri nts the fi el ds of the risloddes structure to a user-speci fi ed fi l e.
#include rislduld.h
void RISlod_fprint_risloddes (FILE *fp, risloddes *risloddes_ptr);
__________________
Description
___________
fp Fi l e poi nter to a fi l e opened wi th the fopen functi on.
fi l e. See the secti on risloddes Structures for more i nformati on.
Notes
______
I f you are worki ng i n the Wi ndows NT envi ronment and you are not usi ng the
riscpp.exepreprocessor to compi l e your source code, you must use the </>MD swi tch
i n your compi l e statement.
Because the functi on cal l
RISlod_fprint_risloddes (stdout, *risloddes_ptr)
creates l ess overhead and produces the same resul t as the cal l
RISlod_print_risloddes (*risloddes_ptr),
use the RI Slod_fprint_risloddes functi on when pri nti ng the risloddes structure fi el ds.

RISlod_print_risloddes
Thi s functi on pri nts the fi el ds of the risloddes structure to standard output.
#include rislduld.h
void RISlod_print_risloddes (risloddes *risloddes_ptr);
__________________
Description
___________
fi l e. See the secti on risloddes Structures for more
i nformati on.
Notes
______
Cal l i ng RI Slod_print_risloddes i s the same as cal l i ng RI Slod_fprint_risloddes wi th
the fi l e poi nter set to stdout. Because RI Slod_fprint_risloddes creates l ess overhead,
use RI Slod_fprint_risloddes when pri nti ng the risloddes structure fi el ds. See the
RI Slod_fprint_risloddes functi on descri pti on for further i nformati on.
RISuld_fprint_risulddes
Thi s functi on pri nts the fi el ds of the risulddes structure to a user-defi ned fi l e.
void RIS_fprint_risulddes (FILE *fp, risulddes *risulddes_ptr);
__________________
Description
___________
fp Fi l e poi nter to a fi l e opened wi th the fopen functi on.
fi l e. See the secti on risulddes Structures for more i nformati on.
Notes
______
I f you are worki ng i n the Wi ndows NT envi ronment and you are not usi ng the
riscpp.exepreprocessor to compi l e your source code, you must use the </>MD swi tch
i n your compi l e statement.
Because the functi on cal l
RIS_fprint_risulddes (stdout, *risulddes_ptr)
creates l ess overhead and produces the same resul t as the cal l
RIS_print_risulddes (*risulddes_ptr),
use the RI Suld_fprint_risulddes functi on when pri nti ng the risulddes structure
fi el ds.

RISuld_print_risulddes
Thi s functi on pri nts the fi el ds of the risulddes structure to standard output.
void RISuld_print_risulddes (risulddes *risulddes_ptr);
__________________
Description
___________
fi l e. See the secti on risulddes Structures for more
i nformati on.
Notes
______
Cal l i ng RI Suld_print_risulddes i s the same as cal l i ng RI Suld_fprint_risulddes wi th
the fi l e poi nter set to stdout. Because RI Suld_fprint_risulddes creates l ess overhead,
use RI Suld_fprint_risulddes when pri nti ng the risulddes structure fi el ds. See the
RI Suld_fprint_risulddes functi on descri pti on for further i nformati on.
Appendix A: Changes to This Version of RI S A - 1

Appendix A
__________________________________________________________________________________________________________________________________________________
Changes to This Version of RIS
A - 2 Appendix A: Changes to This Version of RI S


__________________________________________________________________________________________________________________________________________________
Appendix A
Changes to This Version of RIS
Thi s secti on descri bes changes between RI S Versi on 4 and RI S Versi on 5.
A.1 RDBMS Versions

For the most current i nformati on concerni ng RDBMS versi on compati bi l i ty for
supported RI S pl atforms, see the Architectureand Configuration Overview
secti on i n the i nstal l ati on gui de for your pl atform.
A.2 UNION and UNION ALL Supported
RI S Versi on 5 supports UNI ON and UNI ON ALL operators wi th the select statement.
For exampl e:
select * from t1 union select * from t2;
select c1, c2 from t1 union all select c21, c22 from t2;
UNI ON and UNI ON ALL are not supported i n subqueri es. See the RI S SQL Users Guide
for more i nformati on.
A.3 Objects of Different Owners Within a Schema
I n RI S Versi on 4 a schema created by an RDBMS user contai ned onl y objects (tabl es, vi ews,
and i ndexes) owned by that user. I n RI S Versi on 5 a schema can contai n objects owned by
mul ti pl e users. For exampl e, schema S1, created by RDBMS user U1, can contai n objects
owned by RDBMS users U2 and U3, as wel l as those owned by U1. Thi s capabi l i ty:
I s a fundamental redefi ni ti on of a schema to be si mpl y a named col l ecti on of objects i n a
database.
Lets data owned by pri vi l eged accounts be i ncl uded wi thout vi ews or securi ty vi ol ati ons.
Al l ows shari ng of common objects among schemas. For exampl e, tabl e T1, created by
user U1, can be shared by schemas S1, S2, and S3, where S1 was created by user U1,
S2 by user U2, and S3 by user U3.
Lets appl i cati ons easi l y create l ogi cal groupi ngs of tabl es.

Consi derati ons when usi ng thi s capabi l i ty:
Si nce objects owned by di fferent users can be i ncl uded i n the schema, the owner
i nformati on i s mai ntai ned i n the RI S di cti onary. The dbms_owner val ue appl i es to a
tabl e, vi ew, or an i ndex, and can be i n upper or l owercase.
Thi s capabi l i ty cannot be accessed through RI S Versi on 4.
The access restri cti ons of the underl yi ng RDBMS are encountered when usi ng thi s
capabi l i ty.
Most databases l et two di fferent users create tabl es/vi ews/i ndexes wi th the same name.
However the names of tabl es/vi ews/i ndexes wi thi n a schema are uni que, regardl ess of
the dbms_owner. I f both T1 owned by U1, and T1 owned by U2 need to be i ncl uded i n a
schema, one of the tabl es has to be al i ased. See the secti on Object Aliases for more
i nformati on.
A.4 Object Aliases
Wi th RI S Versi on 5, any col umn or tabl e name can be gi ven an al i as. For exampl e, table
abc_123 wi th col umns abc1, abc2, and abc3, can be i ncl uded and referred to as EMPLOYEES
wi th col umns FI RST_NAME, GENDER, and DATE_OF_BI RTH, respecti vel y. Thi s
capabi l i ty:
Lets i denti cal l y-named tabl es owned by di fferent RDBMS users exi st i n a si ngl e
schema. For exampl e, suppose three di fferent users create three di fferent tabl es wi th
the same name:
RDBMS: PROJ1.NAMES, PROJ2.NAMES, PROJ3.NAMES
These tabl es must be al i ased so that they have di sti nct names.
SCHEMA1: NAMES1, NAMES2, NAMES3
Names i n RI S can be l onger than the underl yi ng database supports. See the RI S SQL
Users Guidefor more i nformati on.
Object names and keyword confl i cts can be worked around. For exampl e, i f a col umn
name i s a RI S keyword, such as t1(i nformi x, oracl e, db2), i t can be i ncl uded as t1(col 1,
col 2, col 3).
An excl ude/i ncl ude sequence l oses al l al i ases.
Wi thi n RI S onl y the RI S names (al i ases) are val i d. The external /DBMS name i s not
val i d.

A.5 Multi-User/SecureSchemas
I n RI S Versi on 5 two types of schemas are supported: the standard schema and the secure
schema. The standard schema i s a si ngl e-user schema and the i nformati on necessary for
connecti ng to thi s schema i s stored i n the schema fi l e (thi s i s no di fferent from a RI S Versi on
4 schema). The secure schema has no username/password combi nati on stored for i t. The
RI S Versi on 4 (si ngl e user) schema i s sti l l supported and sti l l the defaul t. Thi s mul ti -
user/secure schema capabi l i ty:
Al l ows no connecti on unti l a user provi des a username/password combi nati on.
Lets you use the same schema, but provi de di fferent RDBMS l og-i ns.
No password i s stored i n any form by RI S.
I ndi vi dual s appear di sti nct to the RDBMS and are subject to RDBMS securi ty tracki ng.
The declareschema statement l ets you speci fy a schema name and password, and
opti onal l y, the user and password of the user who owns the schema, and the operati ng
system user and password i n the RI S i n-memory data di cti onary cache.
Thi s statement must be used to access secure schemas. I t can al so be used to access
standard schemas. See the RI S SQL Users Guidefor more i nformati on. Thi s capabi l i ty
can be used by any si te. I t i s most useful to those i nterested i n hi gh l evel s of securi ty
(usual l y DB2, ORACLE, and so on).
The schema admi ni strator (user who creates the schema) control s authori ty to connect
to a schema and to create tabl es on a schema, usi ng:
GRANT CONNECT TO <rdbms_user>;
REVOKE CONNECT FROM <rdbms_user>;
GRANT RESOURCE TO <rdbms_user>;
REVOKE RESOURCE FROM <rdbms_user>;
A username/password combi nati on shoul d be provi ded before a schema i s open.
There i s case-sensi ti vi ty of the RDBMS username (except i n cases where some
databases accept names i n a parti cul ar case; then RI S does a conversi on).

A.6 Shared Dictionaries
I n RI S Versi on 5 when a schema s1 i s created and creates the di cti onary as i n RI S Versi on 4,
schemas s2, s3, s4, and so on can be created usi ng the di cti onary created by schema s1. Thi s
capabi l i ty:
Al l ows mul ti pl e schemas i n databases that cannot have tabl es of the same name (non-
ANSI I NFORMI X).
Requi res mi ni mal di cti onary creati on when there are many schemas.
Al l ows l i mi ted di cti onary creati on, admi ni strati on, and ownershi p outsi de of RI S for
DB2, SYBASE, and Mi crosoft SQL Server.
The system admi ni strator must grant and revoke an RDBMS user the authori ty to
create a schema on a di cti onary, usi ng:
GRANT SCHEMA TO <rdbms_user>;
REVOKE SCHEMA FROM <rdbms_user>;
Creators of di cti onari es cannot drop al l thei r schemas whi l e there are other schemas i n
the di cti onary.
An appl i cati on based on RI S Versi on 4 must create a di cti onary i n order to use i t.
Addi ti onal schemas can then be added to the di cti onary and used by appl i cati ons based
on RI S Versi on 5. Schemas s2, s3, and so on, cannot be accessed from RI S Versi on 4.
A.7 Dictionary Objects
Di cti onary objects i n RI S Versi on 5 are al l renamed (ri s5*). Thi s capabi l i ty:
Removes the di sti ncti on between ri s* and ri s_*.
Makes RI S di cti onary objects now appear i n the di cti onary vi ews.
Addi ti onal col umns are needed to di sti ngui sh among schemas i n shared di cti onari es, to
di sti ngui sh between user objects and di cti onary objects, and for i nternal /external object
names.
Names may need to be changed i n queri es.
New col umns shoul d be consi dered i n queri es.

A.8 Dictionary Views
I n RI S Versi on 4 the i nternal RI S di cti onary tabl es were documented wi th the note that they
are not i ntended for appl i cati on use, and i nformati on about them was mai ntai ned i n the
di cti onary. I n RI S Versi on 5, the i nternal tabl es are not documented and i nformati on about
them i s not avai l abl e i n the di cti onary. Onl y di cti onary vi ews can be accessed from an
appl i cati on.
I n RI S Versi on 4 the di cti onary vi ews showed i nformati on about onl y the user (or
appl i cati on) objects and the base tabl es contai ned both appl i cati on objects and RI S di cti onary
objects. I n RI S Versi on 5, si nce the base tabl es are not accessi bl e from the appl i cati ons, the
vi ews show both user objects and RI S objects.
Consi derati ons:
I f onl y user objects need to be sel ected, the condi ti on ris_object=N shoul d be used i n the
wherecl ause.
Thi s rul e appl i es to the vi ews ris5columns, ris5column_privs, ris5tables, and
ris5table_privs.
I n RI S Versi on 4 the vi ews risdbms_tables, risdbms_views, and risdbms_indexes, l i sted
the objects, vi ews, and i ndexes, respecti vel y, that were i n the database, but not
i ncl uded i n the schema. Due to the RI S Versi on 5 capabi l i ti es al l owi ng objects of
di fferent users wi thi n a schema and shared di cti onari es, the exact equi val ent of the RI S
Versi on 4 vi ews cannot be provi ded. I n Versi on 5, the ris5dbms_tables vi ew l i sts al l the
tabl es i n the database, al ong wi th the user that owns the database. The ris5dbms_views
vi ew l i sts al l the vi ews i n the database, al ong wi th the user that owns the database.
The ris5dbms_indexes vi ew l i sts al l the i ndexes i n the database, al ong wi th the user
that owns the database. I n some cases, these l i sts may i ncl ude onl y those
tabl es/vi ews/i ndexes accessi bl e to the current l og-i n/user of the database.

These vi ews are not recommended for use by appl i cati ons. I f used, the
query shoul d have some restri cti ve condi ti on (speci fi cal l y, WHERE).
Usi ng select * from these vi ews can l ead to si gni fi cant performance
degradati on. Si nce thi s vi ew i s defi ned to show everythi ng, i t shoul d be
used wi th cauti on. I n some cases these vi ews are accessi bl e onl y for the
di cti onary creator si nce some databases do not al l ow granti ng system
pri vi l eges on catal ogs (where these vi ews are defi ned).

A.9 RIS_BLOB/RIS_TEXT
RI S Versi on 5 al l ows l ong bi nary or l ong text data that l ets you:
Use i t for document or pi cture storage by I NFORMI X OnLi ne and ORACLE. RI S has no
RI S_BLOB/RI S_TEXT support for I NFORMI X Standard Engi ne, SYBASE, Mi crosoft
SQL Server, or DB2.
I nsert, update, or retri eve l arge data.
Access character stri ngs wi th a l ength greater than 249 characters for other RDBMSs
not supporti ng RI S_BLOB.
To use RI S_BLOB/RI S_TEXT data, the cl i ent and data server versi ons must be at l east
05.01.01.xx.
Thi s feature i s avai l abl e onl y through the programmi ng i nterface; no i nteracti ve access
i s avai l abl e.
The appl i cati on shoul d track the data l ength.
The RI S_BLOB data type i s for bi nary data; for exampl e, GI F fi l es, executabl es, and so
forth. RI S makes no attempt to convert or i nterpret the data.
The RI S_TEXT data type i s for text data; for exampl e, ASCI I fi l es. RI S does convert
the text data between di fferent hardware pl atforms as i t woul d for char data.
The text data can be i nserted i nto a RI S_BLOB col umn, but nobl ob data shoul d be
i nserted i nto a RI S_TEXT col umn.
To create a tabl e wi th a col umn of RI S_BLOB/RI S_TEXT data type
create table emp (name char(25), id int, picture ris_blob (50000))
The defaul t si ze of the RI S_BLOB/RI S_TEXT col umn i s 0. The maxi mum l ength of the
data i s dependent on the database. I f the maxi mum data si ze i s set to 0, data can be
retri eved from the database to a memory array and not a fi l e.
The fi l e_used fi el d i s requi red for i nserti ng and retri evi ng. RI S uses the fi l ename or the
memory array as the targeted user vari abl e.
The text data and character data are converted for di fferent hardware pl atforms.
The maxi mum si ze l i mi t cannot be zero when retri evi ng data from the database. The
maxi mum si ze l i mi t i s zero when retri evi ng data from memory.
RI S_BLOB/RI S_TEXT col umns cannot be used i n the SQL WHERE cl ause or GROUP
BY statements, and cannot be i ndexed.

The number of RI S_BLOB/RI S_TEXT col umns al l owed i n one tabl e i s subject to the
restri cti ons of the underl yi ng RDBMS. I NFORMI X al l ows mul ti pl e
RI S_BLOB/RI S_TEXT col umns whi l e ORACLE al l ows one RI S_BLOB/RI S_TEXT
col umn per tabl e.
The si ze of RI S_BLOB/RI S_TEXT i s subject to the restri cti ons and l i mi tati ons of the
underl yi ng RDBMS.
Tabl es wi th RI S_BLOB/RI S_TEXT are created through RI S and data i s i nserted
through RI S.
Currentl y, RI S uses the fi rst 8 bytes (ORACLE onl y) of the RI S_BLOB/RI S_TEXT col umn i n
databases to store the l ength of the data. Exi sti ng tabl es wi th data, when i ncl uded i n a RI S
schema, wi l l resul t i n i ncompl ete data when retri eved from the database. To mani pul ate
RI S_BLOB/RI S_TEXT data, any tabl es wi th RI S_BLOB/RI S_TEXT fi el ds need to be created
through RI S and the data i nserted onl y through RI S.
When the maxi mum si ze l i mi t for a RI S_BLOB/RI S_TEXT col umn i s zero, data cannot be
retri eved from the database to a fi l e. Thi s si tuati on does not appl y when the data i s retri eved
i nto a memory array.
I f a posi ti ve, non-zero val ue i s used, RI S wi l l use thi s val ue as the maxi mum si ze l i mi t for the
RI S_BLOB/RI S_TEXT object. I f the val ue i s zero, or no val ue i s speci fi ed (usi ng defaul t of
zero), then RI S does not i mpose a l i mi t and the maxi mum si ze supported by the underl yi ng
RDBMS can be used.
The l i mi t si ze can be set to zero i n the fol l owi ng si tuati ons:
An exi sti ng tabl e whi ch has RI S_BLOB/RI S_TEXT col umns i s i ncl uded i n a RI S
schema
A tabl e i s excl uded from the RI S schema and l ater i ncl uded back i nto the schema
A tabl e i s created through RI S wi thout speci fyi ng a RI S_BLOB/RI S_TEXT col umn si ze.
To check the val ue of the maxi mum si ze l i mi t:
select char_max_length from ris5columns
where table_name = table and column_name = column;

To reset the maxi mum si ze l i mi t use ri sdtype:
c:\risdtype
Enter schema (<CR> to exit) :sch1
Enter a table or view name (or ? for a list of names):
>blob_table
Pos Column Name type type-string len prec scale null
1 c1 15 ris_blob 10000 null null Yes
Do you wish to modify this column? <y(es), n(o), d(one with table)>>y
0 Unsupported
1 Character
2 RIS_BLOB
3 RIS_TEXT
Choose a datatype from those listed (enter the number) >>2
Current maximum ris_blob length is:0
Current maximum ris_blob length is:10000
Current status for nullable is YES, nulls are allowed
Are null values allowed? <y(es), n(o)> >>y
Column definitions modified for object sch1.blob_table:
Pos Column Name type type-string len prec scale null
1 c1 15 ris_blob 10000 null null Yes
Is this correct? <y(es), n(o), q(uit> >>y
I n the above exampl e, RC01 i s the di cti onary owner as shown i n the schema fi l e, bl ob_tabl e
i s the name of the tabl e wi th a bl ob col umn, set to val ues other than 10000.
RI S l i mi ts the data si ze i nserted i nto a RI S_BLOB/RI S_TEXT col umn i f a si ze i s speci fi ed
when the tabl e i s created.
For exampl e:
create table blob1 (c1 ris_blob(100000))
woul d i mpose a l i mi t of 100,000 bytes. I f the tabl e i s created wi thout speci fyi ng a si ze, then
the underl yi ng RDBMSs maxi mum l i mi t for RI S_BLOB/RI S_TEXT data wi l l be used.
For exampl e:
create table blob2 (c2 ris_blob)

A.10 Interoperability
RI S Versi on 5 l ets mul ti pl e versi ons of RI S products be avai l abl e on most systems. The
fol l owi ng fi gure detai l s i nteroperabi l i ty of RI S Versi on 4 and RI S Versi on 5.

Thi s capabi l i ty:
Lets you conti nue to use RI S Versi on 4 appl i cati ons wi th mi ni mal i mpact. Versi on 4
appl i cati ons shoul d conti nue to run.
RI S Cl i ent and Data Servers shoul d be upgraded to RI S Versi on 5.
Mul ti pl e versi ons are avai l abl e remotel y through TCP onl y.
The ORACLE 7 Data Server requi res the RI S Versi on 5 Cl i ent.
The Sybase SQL Data Server requi res the Versi on 5.02 Cl i ent.
Onl y RI S Versi on 5 appl i cati ons can query RI S Versi on 5 di cti onary objects. Onl y RI S
Versi on 4 appl i cati ons can query RI S Versi on 4 di cti onary objects.
The RI S uti l i ti es are al so appl i cati ons and the previ ous restri cti ons appl y.
The risdtypeuti l i ty of RI S Versi on 4 cannot be used wi th the RI S Cl i ent Versi on 5 or
the RI S Data Server Versi on 5.
Fi l es generated by the RI S Versi on 4 risrecrd uti l i ty cannot be processed by the RI S
Versi on 5 risplbck uti l i ty. I f an appl i cati on i s bui l t wi th RI S Versi on 4, the resul ti ng
record fi l e can be processed onl y by the RI S Versi on 4 risplbck uti l i ty.

A.11 UpgradeUtility
A uti l i ty to convert a schema (di cti onary and schema fi l e) from RI S Versi on 4 to RI S Versi on
5 i s del i vered wi th the RI S Cl i ent.

Whi l e RI S Versi on 4 i s not avai l abl e for Sol ari s, the upgrade uti l i ty can be used
to upgrade a Versi on 4 schema fi l e on another pl atform (for exampl e, CLI X).
Consi derati ons when usi ng thi s uti l i ty:
Thi s conversi on shoul d be appl i ed to every exi sti ng schema when RI S Versi on 5 Data
Servers are i nstal l ed.
The RI S Versi on 4 Data Servers shoul d be removed.
The conversi on of the di cti onary i s i rreversi bl e and i s done i n-pl ace.
The schema fi l e conversi on i s non-destructi ve. The Versi on 5 schema fi l e i s generated
from the Versi on 4 schema fi l e. Thi s feature l ets you mi x Versi on 4 and Versi on 5
cl i ents to access a Versi on 5 data server. The schema fi l e that matches the cl i ent
versi on shoul d be used.
A.12 Utilities
The RI S Versi on 4 ad hoc uti l i ty ris has been renamed risbatch. There i s now an ad hoc
query uti l i ty wi th a graphi c user i nterface (GUI ), cal l ed risgui.
Consi derati ons when usi ng the Versi on 5 l oader/unl oader:
The l oader/unl oader provi des no BLOB support.
The unl oader unl oads (or saves) RI S names (al i ases) onl y, not the underl yi ng object
names.
The unl oader unl oads (or saves) schema ownershi p onl y, not underl yi ng RDBMS
ownershi p.
A.13 Parameters
The parameter fi l e generated by a Versi on 5 appl i cati on or uti l i ty i s compati bl e wi th Versi on
4 appl i cati ons. I n Versi on 4, i f a parameter fi l e exi sted, al l parameters were expected to be
set. Unl i ke Versi on 4, Versi on 5 i s more tol erant wi th respect to parameter fi l es: any number
of parameters can be l eft unspeci fi ed and RI S uses the defaul t val ues.
A new parameter, CLI ENT_VERSI ON, has been added wi th the defaul t val ue set to 0.0,
meani ng that the appl i cati on connects to a compati bl e cl i ent. When future versi ons of RI S
become avai l abl e, Versi on 5 and hi gher appl i cati ons wi l l be abl e to use thi s parameter to
speci fy the cl i ent versi on.

Usi ng thi s parameter causes Versi on 4 appl i cati ons to fail; hence, for now, l eave i t
commented out. When the CLI ENT_VERSI ON parameter i s set, Versi on 4
appl i cati ons can no l onger use that parameter fi l e.
A.14 Internationalization
RI S for 32-bi t appl i cati ons (Versi on 5.3.1 and l ater) support 16-bi t or mul ti -byte l anguages.
Most 16-bi t l anguages are Asi an. I n the RI S documentati on, the maxi mum si ze al l owed for
tabl e names, vi ew names, i ndex names, schema names, col umn wi dths, and character data i s
speci fi ed as x characters, where x i s an i nteger. For those usi ng mul ti -byte l anguages, the
maxi mum number of characters shoul d be i nterpreted as the maxi mum si ze i n bytes.
RI SMGR and RI SGUI i mpl ement mul ti -byte character support.
RI S l i mi tati ons and gui del i nes:
RI S schema and user names can be i nternati onal i zed, but not passwords.
Onl y al pha-numeri c characters can be i nternati onal i zed.
Setup i s not ful l y i nternati onal i zed.
RI S does not l ocal i ze di al ogs, gadgets and error messages.
RI S i s i nternati onal i zed on NT onl y. The RI S appl i cati on, RI S Cl i ent, and RI S Data
Server must be on NT to take advantage of the RI S i nternati onal i zati on.
The peri od (.) used between username and passwords must be 8-bi t Engl i sh.
Al l punctuati on, keywords, col umn datatype defi ni ti ons, ti mestamp data, statements
must be 8-bi t Engl i sh.
Schemas, tabl es, vi ews, col umns, i ndex names can be 8-bi t or 16-bi t characters.
RI S data di cti onary tabl es and vi ews are created usi ng 8-bi t Engl i sh characters.
The fol l owi ng components of a create schema statement are 8-bi t and 16-bi t characters:
create schema 8-bi t Engl i sh
schema name 8-bi t and 16-bi t Engl i sh
schema pass 8-bi t Engl i sh
db type 8-bi t Engl i sh
dbname 8-bi t and 16-bi t Engl i sh
db di r 8-bi t and 16-bi t Engl i sh
osuser 16-bi t Engl i sh
ospass 8-bi t Engl i sh
ostype 8-bi t Engl i sh
db user 8-bi t and 16-bi t Engl i sh
remote cl ause 8-bi t Engl i sh

Character col umns are anal yzed to make sure that they are wi de enough to hol d the data.
For exampl e, a 10 character name i n a 16-bi t l anguage requi res a char(20) col umn.
The maxi mum number of 8-bi t characters i n a col umn i s 240. The maxi mum number of 16-
bi t characters i n a col umn i s 120.
Appendix B: Programming Notes and Performance Considerations B - 1

Appendix B
__________________________________________________________________________________________________________________________________________________
ProgrammingNotes and Performance
Considerations
B - 2 Appendix B: Programming Notes and Performance Considerations


__________________________________________________________________________________________________________________________________________________
Appendix B
ProgrammingNotes and Performance
Considerations
B.1 DeclaringTables/Views
When an appl i cati on fi rst uses a tabl e or vi ew i n an SQL statement, some i ni ti al overhead i s
generated. RI S must l earn the names, data types, and si zes of the col umns (and i f they are
nul l abl e). Thi s i nformati on i s used to veri fy that the statement i s correct and i s used wi th
appropri ate vari abl es. RI S has to query the database to get thi s i nformati on. Thi s i s
overhead. I f the appl i cati on does not know anythi ng about the tabl e or vi ew, thi s overhead
cannot be avoi ded. I f, however, the appl i cati on knows the defi ni ti on of the tabl e, the declare
tableor declareviewstatements can be used to provi de the i nformati on to RI S and avoi d the
overhead.
The sampl e program risdeclarei s del i vered wi th RI SDP. Thi s program easi l y generates
tabl e and vi ew decl arati ons for objects i n schemas.
Use tabl e decl arati ons i n any appl i cati on that has a standard set of tabl es because these
tabl es are general l y used onl y once, ei ther at the start of an appl i cati on or just before a
tabl e/vi ew i s used for the fi rst ti me. I f your appl i cati on uses a vari ety of user-defi ned or
modi fi ed tabl es, consi der i mpl ementi ng a mechani sm for readi ng i n tabl e/vi ew defi ni ti ons
that mi ght be used. For exampl e, keep the l i st of tabl es/vi ews that have been used i n SQL
statements. Then, before usi ng a tabl e, check the l i st to see i f i t has been decl ared.
Compati bi l i ty between the decl arati on and the actual tabl e i s i mportant. A decl arati on wi th
no compati bi l i ty veri fi cati on i s the fastest because i t compl etel y bypasses the database. A
decl arati on wi th parti al veri fi cati on requi res some database i nteracti on, but i s sti l l fai rl y
qui ck. A ful l veri fi cati on decl arati on shoul d be used pri mari l y to veri fy that the l i st of
decl arati ons i s up to date and i denti cal to what i s i n the database system.
Tabl e defi ni ti ons are cached by RI S. The number of tabl e defi ni ti ons cached i s determi ned by
the MAX_TABLES_I N_MEM val ue i n the parameter fi l e. When thi s val ue overfl ows, tabl e
defi ni ti ons are removed. MAX_TABLES_I N_MEM shoul d be l arger than the number of
tabl es the appl i cati on uses. Cachi ng tabl e defi ni ti ons creates a memory versus performance
trade-off.
B.2 Error Handling
RI S returns a status code for each statement executed. Al ways check the status of each
statement. Fai l ure to check the status may resul t i n unexpected fai l ure of other statements.
The gl obal i nteger vari abl e SQLCODE contai ns the status. The val ue RI S_SUCCESS
i ndi cates success, END_OF_DATA i ndi cates end-of-data, and negati ve val ues i ndi cate an
error.

Use the risca and dbca vari abl es to get addi ti onal error i nformati on. The risca vari abl e i s a
poi nter to an rissqlca error structure contai ni ng detai l ed RI S error i nformati on. The dbca
vari abl e i s a poi nter to an rissqlca error structure contai ni ng error i nformati on from the
underl yi ng DBMS. Both structures are defi ned i n ris.h.
Al so use the report error and whenever statements for error handl i ng. The report error
statement obtai ns a stri ng contai ni ng the RI S and underl yi ng DBMS error messages. The
whenever statement defi nes handl ers for error and end-of-data condi ti ons.
B.3 Initializingand TerminatingRIS
RI S automati cal l y i ni ti al i zes when the fi rst RI S statement i s executed. The i ni ti al i zati on
process reads i nformati on from the parms fi l e, al l ocates semaphores and shared memory,
sets up i nternal structures, and then starts the RI S cl i ent process.
RI S al so automati cal l y termi nates when the appl i cati on process termi nates. The RI S cl i ent
checks for the exi stence of the appl i cati on process at fi xed ti me i nterval s. When the RI S
cl i ent process detects that the appl i cati on process i s no l onger runni ng, i t shuts down al l of
i ts RI S servers, frees up resources such as semaphores and shared memory, and then
termi nates.
I t i s possi bl e to expl i ci tl y i ni ti al i ze and termi nate RI S. You can i ni ti al i ze RI S by cal l i ng the
RI Sinitializefuncti on. Cal l i ng thi s functi on prevents del ay of the fi rst RI S statement whi l e
RI S i ni ti al i zes. To avoi d del ay of the fi rst statement, cal l RI Sinitializeduri ng the appl i cati on
i ni ti al i zati on phase. You can termi nate RI S by cal l i ng the RI Sterminatefuncti on. RI S
normal l y termi nates bri efl y after appl i cati on termi nati on. To avoi d del ay i n RI S termi nati on
or to termi nate RI S wi thout termi nati ng the appl i cati on, cal l RI Sterminate. Use of these
functi ons i s hi ghl y recommended.
B.4 Locking
Locki ng i s ei ther expl i ci t or i mpl i ci t. The DBMS i mpl i ci tl y l ocks, but expl i ci t l ocki ng requi res
the lock tables statement.
I mpl i ci t l ocki ng can be probl emati c because each DBMS does i t di fferentl y. Databases di ffer
i n both the scope and type of l ocki ng. A DBMS can l ock at the row, page, or tabl e l evel . You
can modi fy the l ocki ng behavi or of some, but not al l , databases. Al so, a DBMS may
ori gi nal l y l ock at the row or page l evel and escal ate the l ocks to tabl e l evel i f necessary. Thi s
i s because the total number of row and page l ocks i s l i mi ted. Thi s l i mi t al so vari es dependi ng
on the DBMS.
The two basi c l ock types are share and excl usi ve. Use a sharelock when readi ng data. Thi s
prevents other users from updati ng the data bei ng read. Mul ti pl e users can have a share
l ock on the same data. Exclusivelocks prevent users from accessi ng the data i n any way.
Use excl usi ve l ocks when modi fyi ng data to prevent others from modi fyi ng or vi ewi ng the
data. Every DBMS has a share and an excl usi ve l ock, but the l ocks behavi or vari es among
di fferent databases. The DBMS may al so have addi ti onal l ock types.
Expl i ci t l ocki ng ensures that l ocki ng i s performed uni forml y across di fferent DBMSs.
However, expl i ci t l ocki ng has restri cti ons. Fi rst, you can onl y l ock data at the tabl e l evel

usi ng the lock tables statement. Page and row l evel l ocki ng are i mpl i ci t onl y. Next, you
must make the lock tables statement the fi rst statement wi thi n a transacti on. Fi nal l y, you
must speci fy al l tabl es used i n the transacti on when the lock tables statement i s used.
The lock tables statement al l ows si mul taneous l ocki ng of mul ti pl e tabl es i n di fferent modes.
Each tabl e can be l ocked i n ei ther share, excl usi ve, or defaul t mode. The share and excl usi ve
modes correspond to the types of l ocks previ ousl y descri bed. Defaul t mode i nforms the
DBMS to use i mpl i ci t l ocki ng. The expl i ci t and i mpl i ci t l ocks are hel d unti l the transacti on i s
commi tted or rol l ed back.
B.5 ManagingStatements
RI S al l ows preparati on of up to 40 statements (stati c and dynami c). RI S automati cal l y
manages stati c statements. RI S l i mi ts the number of prepared stati c statements to l ess than
or equal to the MAX_STATI C_STMTS parameter. I f preparati on of more than 40 statements
i s needed, RI S cl ears the l east used stati c statement.
You must manage dynami c and cursor statements. The clear statement frees the resources
used by a statement. Cl ear prepared statements when they are no l onger needed.
B.6 Order By Statement
Ordered resul ts are someti mes useful but al ways expensi ve. Database systems do not
al ways sort effi ci entl y and may need extensi ve tuni ng to avoi d usi ng temporary tabl es. For
smal l resul t sets, your appl i cati on may be better abl e to sort i tems more qui ckl y.
I n general , be sure the appl i cati on does not automati cal l y use an order by cl ause i n queri es
when i t i s not needed.
B.7 PreparingStatements
I n si tuati ons where SQL statements are executed repeti ti vel y, you can i ncrease performance
by (1) executi ng the statement stati cal l y, or (2) spl i tti ng the dynami c executi on i nto two
phases, prepare and execute. Prepari ng consi sts of syntacti c checki ng and structure
i ni ti al i zati on. You i ncrease performance by prepari ng the statement once i nstead of mul ti pl e
ti mes. When you use executeimmediate, RI S prepares and executes the statement for each
use.
Wi th stati c statements such as insert, update, delete, and select into, RI S automati cal l y keeps
the most recentl y used stati c statements prepared. The exact number of stati c statements
RI S keeps prepared i s dependent on the MAX_STATI C_STMTS parameter i n the parameters
fi l e.
For more i nformati on about confi guri ng the MAX_STATI C_STMTS parameter, see the RI S
SQL Users Guidefor 32-Bit Applications.
When usi ng the same dynami c C SQL statement repeti ti vel y, you do not have to prepare the
statement for each use. Prepare the statement once, then execute i t mul ti pl e ti mes.
Remember that the schema used to prepare the statement must be the same schema used to

execute the statement.
Wi thi n RI S, i t i s possi bl e to use dynami c Embedded SQL to separate the prepare and execute
phases so that the statement i s prepared onl y once. Ei ther of the fol l owi ng exampl es i nserts
20 numeri c val ues i nto a tabl e, but the second i s more effi ci ent because the i nsert statement
i s prepared onl y once.
Example1
__________
for ( i=0; i<20; i++)
{
exec sql execute immediate "insert into table1 values(1)";
}
Example2
__________
query = "insert into table1 values(1)";
exec sql prepare stmt1 from :query;
for ( i=0; i<20; i++)
{
}
B.8 RIS Direct versus RISNET Connection
When choosi ng between remote RI S connecti ons (usi ng RI S network functi onal i ty) and
RI SNET connecti ons (usi ng DBMS vendor network connecti ons), RI S connecti ons are
general l y faster. Vendor network connecti ons have to be much more generi c and are not as
effi ci ent.
B.9 Schema Files
I nformati on about schemas and databases i s avai l abl e by queryi ng the ris5schemas and
ris5dbs data di cti onary tabl es. The same i nformati on i s avai l abl e much more qui ckl y by
usi ng functi ons. For exampl e, the RI Sget_schema_file() functi on retri eves al l database and
schema i nformati on i n the schema fi l e.
B.10 Set ModeVerify
When tabl e/vi ew decl arati ons are not used, you sti l l have some control over the amount of
fi rst-tabl e-reference overhead. Si nce RI S al l ows some redefi ni ti on of data types for
experi mental use of l ong character stri ngs and unsupported data types, by defaul t there i s
compl ete veri fi cati on of tabl e defi ni ti on i n the database and i n the RI S di cti onary.
I f you set modeverify off, RI S goes to the database system for the tabl e/vi ew defi ni ti on,
but does not check the RI S di cti onary tabl es. Thi s i s a performance versus capabi l i ty trade-
off.

B.11 Temporary Tables
Because tabl e creati on i s usual l y a hi gh-overhead, sl ow operati on, most DBMS desi gners
assume that creati ng a tabl e i nvol ves anal ysi s by a performance tuner to determi ne si ze and
usage characteri sti cs of the tabl e: how i t i s goi ng to be used rel ati ve to other tabl es, whi ch
di sk i t bel ongs on, and so forth.
Any appl i cati on that creates tabl es on the fl y takes severe performance hi ts wi th most
DBMSs and wi l l run i nto other probl ems at si tes wi th system admi ni strators who do not
tol erate uncontrol l ed use of system resources.
Whi l e usi ng the database system to create tabl es as needed may save programmi ng ti me,
eventual l y performance or admi ni strati ve probl ems become i ntol erabl e.
B.12 Transactions
Transacti ons al l ow a seri es of SQL statements to be grouped l ogi cal l y and ensures that al l
database modi fi cati ons are enti rel y commi tted or rol l ed back. A commit or rollback frees al l
l ocks and cl oses al l open cursors. Data defi ni ti on statements such as create, drop, and alter
are al ways automati cal l y commi tted. By defaul t, data mani pul ati on statements such as
select, insert, update, and deleteare al so automati cal l y commi tted. Use the set transaction
statement to turn autocommi t off. Thi s ensures that data mani pul ati on statements are not
automati cal l y commi tted. You must then use the commit and rollback statements to
termi nate a transacti on. Any transacti on i n progress when the program termi nates i s rol l ed
back.
The autocommi t mode makes i t di ffi cul t to have more than one cursor open at a ti me. Thi s i s
because the commit for a select statement i n autocommi t mode i s performed when the cursor
i s cl osed.
Si nce a commit cl oses al l open cursors, al l other open cursors are al so cl osed. To avoi d thi s
probl em, turn autocommi t mode off.
Turni ng autocommi t mode off al so i mproves performance by el i mi nati ng the overhead of
commi tti ng after every statement. However, keep transacti ons as smal l as possi bl e to avoi d
bl ocki ng other users from accessi ng tabl es l ocked duri ng the transacti on.
B.13 UniqueRecord Identifiers
Some appl i cati ons generate uni que, sequenti al numbers to act as record i denti fi ers
(MSLI NK, for exampl e). Some database systems provi de nonstandard mechani sms for thi s
type of operati on, but a generi c mechani sm i s needed.
The fol l owi ng mechani sm has been used, but shoul d not be:
lock table x;
select max(id) + 1 from x;
insert into x values (my_id, my_values);
commit;

Thi s mechani sm demonstrates a coupl e of severe probl ems:
The tabl e i s l ocked for an extensi ve peri od of ti me whi ch severel y l i mi ts concurrent
usage i n a mul ti user envi ronment.
Sel ecti ng max() usual l y i nvol ves checki ng every record of the tabl e. Thi s checki ng
becomes very sl ow as the number of records i n the tabl e i ncreases.
Havi ng a separate tabl e for record i denti fi ers i s much more effi ci ent. The tabl e needs just
one record, but coul d have other records for other i denti fi ers.
create table appl_x_record_ids (table_name char(31), last_id int);
insert into appl_x_record_ids values (states, 0);
insert into appl_x_record_ids values (cities, 0);
insert into appl_x_record_ids values (counties, 0);
To get the next uni que record number, use the fol l owi ng general procedure:
Sel ect the most recent val ue from the tabl e.
select last_id into :old_id from table;
Try to update the tabl e usi ng the retri eved val ue.
update table set last_id = :old_id + 1 where last_id = :old_id;
I f the update succeeds, then the sel ected val ue +1 i s the next number. I f the update fai l s,
then someone el se sel ected the same val ue and has al ready updated the tabl e. Thi s i ndi cates
that your number i s out of date. Do not sel ect agai n. Si mpl y i ncrement your vari abl e and
try the update agai n.
For exampl e, the next uni que record number for the states tabl e can be obtai ned as fol l ows:
int tries = 0;
int my_value;
int old_value;
/*
** Catch and handle all severe errors in the same way.
*/
/*
** Catch a not-found condition for just the initial query.
*/
select last_id into :old_value where table_name = states;
/*
** Catch a not-found condition for the update statement.
*/

exec sql whenever not found goto :increment_and_retry;
To get the next uni que record number for the states tabl e, use the fol l owi ng code segment:
int tries = 0;
int my_value;
int old_value;
/*
** Catch and handle all severe errors in the same way.
*/
/*
** Catch a not-found condition for just the initial query.
*/
select last_id into :old_value where table_name = states;
/*
** Catch a not-found condition for the update statement.
*/
exec sql whenever not found goto :increment_and_retry;
try_again:
if (tries > 50)
{
/*
** Something is probably wrong.
** Place a limit on loop.
*/
return;
}
my_value = old_value + 1;
++tries;
/*
** Try to update the old value based on the old value.
*/
exec sql update last_id set last_id = :my_value
where last_id = :old_value;
/*
** If successful, commit and return; otherwise, it will have jumped.
*/
exec sql commit;
return;
/*
** Try the next value.
*/

increment_and_retry:
++old_value;
goto try_again;
not_found:
/*
** Internal error: This query should not fail.
*/
error:
/*
** Error handling.
*/
B.14 UsingIndexes
The proper use of an i ndex can i mprove the performance of most queri es, but bl i nd usage can
al so hurt an appl i cati on. An i ndex has costs associ ated wi th i t. One of these costs i s space.
I ndexes are separate enti ti es that take up space i n addi ti on to the space requi red for the
tabl e. Pl aci ng an i ndex on every col umn of a tabl e can easi l y take up several ti mes the space
the tabl e requi res.
Large tabl es mean l arge i ndexes. I f an i ndex i s used, di sk I /O wi l l be associ ated wi th
scanni ng the i ndex. I n the worst case, thi s si tuati on can doubl e the normal di sk I /O i ncurred
wi thout the i ndex.
A heavy mai ntenance cost i s another cost of i ndexi ng. Every ti me a new record i s i nserted,
every i ndex i n the tabl e needs to be updated. Every ti me a val ue i s changed i n an i ndexed
col umn, every i ndex on the col umn has to be updated.
These costs shoul d not convi nce you to avoi d an i ndex, but understandi ng the costs i s
i mportant. When you deci de to create an i ndex, be certai n that what i s gai ned outwei ghs the
costs.
I f an i ndex cannot be used, the DBMS must do a ful l -tabl e scan to execute a statement. Thi s
scan i s l i ke sel ecti ng everythi ng from the tabl e. For exampl e, use select count(*) fromtable
wi th no wherecl ause to get a rough i dea of the ti me i t takes to do a ful l -tabl e scan. An i ndex
shoul d i denti fy a parti cul ar record or smal l set of records wi thout havi ng to do a ful l tabl e
scan.
The useful ness of an i ndex i ncreases as the percentage of uni que val ues i n the col umn
i ncreases. For exampl e, i f the MSLI NK fi el d i s uni que for every record, then MSLI NK i s a
perfect candi date for an i ndex because as many queri es as possi bl e shoul d have a where
MSLI NK =? cl ause i n them. The i ndex can be used to i denti fy a uni que row and, even wi th
a mi l l i on records i n the tabl e, a si ngl e record i denti fi ed by MSLI NK i s al ways qui ckl y
avai l abl e.
Conversel y, i f a fi el d such as gender can have onl y two possi bl e val ues (M/F), an i ndex on
gender i s worse than usel ess. Gi ven a fai rl y equal di stri buti on, the wheregender=F cl ause
woul d exami ne the i ndex to i denti fy ful l y hal f of the records i n the tabl e, and then woul d
have to go get the records anyway. Thi s si tuati on demonstrates a query that i n i tsel f i s not

suffi ci entl y speci fi c. The best way to i mprove performance i s to make the query more
speci fi c.
Even i n thi s si tuati on, a case can someti mes (though rarel y) be made for an i ndex. I f you
know that 99% of the val ues are M and that your appl i cati on i s onl y i nterested i n the F
val ues, an i ndex woul d probabl y hel p.
To get an i dea of the uni queness of the val ues i n column_x, try:
select (count(distinct column_x)/count(*))*100 from table_x;
100% i s perfect. Even 50% i s good. When the count starts droppi ng i nto the 10-20% range,
an i ndex becomes l ess and l ess useful . When a concatenated i ndex (two or more col umns)
exi sts, the second col umn i s not i ndexed. For exampl e, i f the concatenated indexphone_idxi s
created on (area_code, phone_number), then the query
select * from phones where phone_number = 123-4567;
does not use the i ndex. A concatenated i ndex cannot be used for a query unl ess the fi rst
col umn of the i ndex i s i n the wherecl ause.
Therefore,
select * from phones where area_code = 205;
i s i neffecti ve because the phone_idxi s used, but the uni queness of area_codei s l ow. The
i ndex just adds overhead to the query.
The query
select * from phones where phone_number = 123-4567;
i s al so i neffecti ve because the i ndex cannot be used.
However, the query
select * from phones where phone_number = 123-4567
and area_code = 205;
i s an effecti ve use of the i ndex.
When consi deri ng a concatenated i ndex, keep the general rul es of an i ndex i n mi nd. For
exampl e, si nce area_codei s not parti cul arl y uni que, i t does not add much to the uni queness
of the record and i s best omi tted from the i ndex.
The fol l owi ng i ndexi ng suggesti ons are al so hel pful .
When a tabl e has onl y smal l amounts of data (up to about 50 smal l records), i ndexes
are usual l y worthl ess.
When l oadi ng many records i nto a tabl e, i t may be faster to drop i ndexes, l oad the data,
and re-create the i ndexes.

When joi ni ng two tabl es, create i ndexes on the joi n col umns. I f your anal ysi s i ndi cates
that an i ndex wi l l not hel p, reconsi der your desi gn and ask why a joi n i s bei ng done
wi th those col umns.
No i ndex i s useful wi thout a wherecl ause. Make your statements as speci fi c as
possi bl e.
B.15 UsingSignals
SI GCLD i s the onl y si gnal that RI S i ntercepts. RI S i ntercepts SI GCLD whi l e the RI S cl i ent
process executes requests from an appl i cati on. Once a request i s compl eted, RI S restores the
handl i ng of SI GCLD to i ts previ ous state. RI S i ntercepts SI GCLD to detect abnormal l y
termi nated RI S cl i ent processes. Thi s i ntercepti on prevents the appl i cati on from l ocki ng
whi l e executi ng a statement.
When an appl i cati on makes a request to the RI S cl i ent process, RI S fi rst veri fi es that the RI S
cl i ent process exi sts. I f i t exi sts, RI S sets up a si gnal handl er to i ntercept any SI GCLD
si gnal s. I f a SI GCLD si gnal i s recei ved i ndi cati ng termi nati on of one of the appl i cati ons
chi l d processes, RI S checks to see i f the termi nated process was the RI S cl i ent. I f i t was, RI S
returns an error. The appl i cati on must termi nate and rei ni ti al i ze i ts connecti on to RI S
before executi ng any other RI S statements. I f the chi l d process that termi nated i s not the
RI S cl i ent process, RI S cal l s a user-defi ned si gnal handl er for SI GCLD i f one exi sts. Once
the cl i ent process has fi ni shed processi ng the appl i cati ons request, RI S restores the handl i ng
of SI GCLD to i ts previ ous handl er.
B.16 UsingSQL Statements Wisely
SQL statements of the form
select xyz from table_x where c1 = 101 or c1 = 102 or c1 = 103
or c1 = 104 or c1 = 105 or c1 = 106 or c1 = 107 or ...
are very i neffi ci ent. Query opti mi zers are not overl y i ntel l i gent. They do not general l y l ook
at the query val ues and real i ze that they coul d be condensed i nto somethi ng l i ke
where c1 between 101 and 300;
OR
c1 > 100 and < 301 and c1 <> 207 and c1 <> 155;
Long statements requi re a l ot of parsi ng. After that, too many OR cl auses make an
opti mi zer deci de that an i ndex does not hel p.
The si mpl er your query, the better the chance of a fast response.
Appendix C: Language Configuration File C - 1

Appendix C
__________________________________________________________________________________________________________________________________________________
LanguageConfiguration File
C - 2 Appendix C: Language Configuration File

Appendix C: Language Configuration File C - 3

__________________________________________________________________________________________________________________________________________________
Appendix C
LanguageConfiguration File
Before usi ng RI S, you can change the l anguage used by RI S. The RI S_get_language_name
functi on cal l i n a RI S appl i cati on sets the l anguage to the speci fi ed val ue. The l anguage map
i nformati on i s l ocated i n the RI S l anguage confi gurati on fi l e langs i n the configdi rectory of
the ri scl i product di rectory:
c:\Program Files\Common Files\Intergraph\ris05.nn\riscli\config\langs
You can al so add new l anguages currentl y not supported by RI S as l ong as they are
supported by the operati ng system and database.
Defi ni ng RI S Language Setti ngs for NT:
1. From the Control Panel , doubl e-cl i ck the I nternati onal i con.
2. Scrol l through the l i st of l anguages avai l abl e under the Language drop-down l i st.
3. Sel ect the l anguage desi red.
4. Cl i ck OK. The system prompts you for the source of the operati ng system l anguage
fi l es.
5. Reboot the system when the process i s compl ete.
The fol l owi ng i s the langs fi l e currentl y supported by RI S. The format of thi s fi l e i s speci fi ed
by si x (6) fi el ds per l i ne separated by a pi pe (| ) del i mi ter. Each l i ne represents one l anguage
mappi ng between RI S and the underl yi ng operati ng system. The format i s:
ri s_l ang_i d| ri s_l ang_name| ri s_l ang_di r| os_l ang_i d| code_page| os_l ang_name
ris_lang_id Uni que RI S l anguage i denti fi er. For every new
l anguage added, thi s i denti fi er i s i ncremented.
ris_lang_name Uni que RI S l anguage name to used by RI S
appl i cati ons duri ng RI Si ni ti al i ze().
ris_lang_dir Di rectory name under the riscli/ configdi rectory. Thi s
di rectory hol ds al l RI S-speci fi c l anguage fi l es
generated by I ntergraphs UMS (User Message
System).
os_lang_id Language i denti fi er used by the underl yi ng operati ng
system for the l anguage you want RI S to use.
code_page Language ANSI code page for the gi ven os_l ang_i d.
C - 4 Appendix C: Language Configuration File

os_lang_name Language name used by the underl yi ng operati ng
system for the l anguage you want RI S to use.
Bel ow i s a sampl e l anguage confi gurati on fi l e. Onl y l anguages wi th the same code page can
i nteroperate. I f the two l anguages do not have the same code page then RI S gi ves an error of
RI S_E_I NCOMPATI BLE_LANGS.
Sample langs file:
0 |english |english |0x0409|1252|U.S. English
1 |korean |korean |0x0412|946|korean
2 |chinese |chinese |0x0404|950|Traditional Chinese
3 |japanese |japanese |0x0411|932|Japanese
4 |german |german |0x0407|1252|German
5 |french |french |0x040C|1252|French
6 |spanish |spanish |0x0C0A|1252|Modern Spanish
7 |italian |italian |0x0410|1252|Italian
8 |arabic |arabic |0x0401|1256|Arabic
9 |bulgarian |bulgaria |0x0402|1251|Bulgarian
10|catalan |catalan |0x0403|1252|catalan
11|traditional chinese |chinese.smp |0x0804|936|Simplified Chinese
12|czech |czech |0x0405|1250|Czech
13|danish |danish |0x0406|1252|Danish
14|swiss german |german.sws |0x0807|1252|Swiss German
15|uk english |english.uk |0x0809|1252|U.K. English
16|australian english |english.aus |0x0C09|1252|Australian English
17|canadian english |english.can |0x1009|1252|Canadian English
18|mexican spanish |spanish.mex |0x080A|1252|Mexican Spanish
19|finnish |finnish |0x040B|1252|Finnish
20|belgian french |french.blg |0x080C|1252|Belgian French
21|canadian french |french.can |0x0C0C|1252|Canadian French
22|swiss french |french.sws |0x100C|1252|Swiss French
23|hebrew |hebrew |0x040D|1255|Hebrew
24|hungarian |hungarian |0x040E|1250|Hungarian
25|icelandic |icelandic |0x040F|1252|Icelandic
26|swiss italian |italian.sws |0x0810|1252|Swiss Italian
27|dutch |dutch |0x0413|1252|Dutch
28|belgian dutch |dutch.blg |0x0813|1252|Belgian Dutch
29|norwegian bokmal |norwegia.bkm|0x0414|1252|Norwegian-Bokmal
30|norwegian nynorsk |norwegia.nyn|0x0814|1252|Norwegian-Nynorsk
31|polish |polish |0x0415|1250|polish
32|brazilian portuguese|portugue.brz|0x0416|1252|Brazilian Portuguese
33|portuguese |portugue |0x0816|1252|Portuguese
34|rhaeto romanic |rhaeto.rom |0x0417|0|Rhaeto-Romanic
35|romanian |romanian |0x0418|1250|Romanian
36|russian |russian |0x0419|1251|Russian
37|croata serbian |croata |0x041A|1250|Croato-Serbian
38|serbo croatian |serbo |0x081A|1250|Serbo-Croatian
39|slovak |slovak |0x041B|1250|Slovak
40|albanian |albanian |0x041C|1250|Albanian
41|swedish |swedish |0x041D|1252|Swedish
42|thai |thai |0x041E|874|Thai
43|turkish |turkish |0x041F|1254|Turkish
44|urdu |urdu |0x0420|0|Urdu
45|bahasa |bahasa |0x0421|1252|Bahasa
Appendix D: Redistribution of RI S Runtime and RI S Utilities D - 1

Appendix D
__________________________________________________________________________________________________________________________________________________
Redistribution of RIS Runtimeand RIS Utilities
D - 2 Appendix D: Redistribution of RI S Runtime and RI S Utilities


__________________________________________________________________________________________________________________________________________________
Appendix D
Redistribution of RIS Runtimeand RIS Utilities
Redi stri buti on ri ghts and l i mi tati ons are descri bed i n the product l i cense agreement for the
RI S Devel opment Pl atform.
When you devel op an appl i cati on wi th the RI S Devel opment Pl atform, the appl i cati on can
run onl y on systems that have the RI S Shared Component; therefore, you must redi stri bute
the RI S Shared Component wi th your appl i cati on.
The fol l owi ng secti ons descri be i ntegrati ng the RI S Shared Component del i very i nto your
del i very procedure.
D.1 Directory Structure
The RI S Shared Component i s del i vered as part of the RI S Devel opment Pl atform to the
c:\ ProgramFiles\ risdp\ shared di rectory. Thi s di rectory i ncl udes fi l es to be del i vered to the
user system, and other setup and packagi ng fi l es as descri bed i n the fol l owi ng secti on.
D.2 Setup Files
Use the fol l owi ng setup fi l es to bui l d the setup medi a for your appl i cati on:
rissetup.lyt Thi s fi l e i s the Mi crosoft Setup layout fi l e for the RI S Shared Component
fi l es. Append your appl i cati ons .lyt fi l e to thi s fi l e.
Use the combi ned .lyt fi l e to create a .inf fi l e wi th the dsklayt2 uti l i ty (whi ch i s part of
the SETUPSDK product). Your setup program uses the .inf fi l e to downl oad the
necessary fi l es to the end-users system.
rissetup.lib The functi ons i n thi s l i brary i nstal l the RI S Shared Component on the
end-users system. You must l i nk your setup program wi th thi s l i brary, and cal l the
fol l owi ng functi ons (i n order):
a. ReadInfFile();
Cal l thi s functi on once before cal l i ng any other setup functi ons for the RI S Shared
Component.

b. SetupRIS();
Thi s functi on determi nes the versi on of the RI S Shared Component that i s al ready
i nstal l ed, i f any. You must use the val ue returned by thi s functi on as i nput to the
RegEdtRI S functi on.
Status Returns
______________
0 Exi sti ng versi on i s newer than your versi on. RI S shared
component i s not l oaded.
1 Exi sti ng versi on i s ol der, or the same date as your versi on.
RI S Shared Component i s l oaded.
2 Exi sti ng versi on not found. RI S Shared Component i s l oaded.
c. CopyFilesInCopyList();
Thi s functi on downl oads your appl i cati on fi l es and the RI S Shared Component
fi l es (i f necessary).
d. RegEdtRIS(int action, char *listEntry);
Thi s functi on edi ts the regi stry for RI S and adds the RI StcpsrServicei nto
Servi ces.
__________________
Description
___________
action Return val ue from the SetupRI S functi on.
listEntry Stri ng that i denti fi es the name and versi on of your
appl i cati on. For exampl e: MYAPP\ \ 01.00.00.00
risrem.lib The functi ons i n thi s l i brary remove the RI S Shared Component from the
system. Li nk your appl i cati on removeprogram wi th thi s l i brary. To remove the RI S
Shared Component i n case of an error, l i nk your setup program wi th thi s l i brary.
a. RegRemoveRIS(HINSTANCE remInstance, char *listEntry);
__________________
Description
___________
remInstance Removal process i nstance for the appl i cati on.
listEntry Entry i n the RefList fi el d for the appl i cati on.
Thi s functi on removes your appl i cati ons entry from the RefList fi el d i n the RI S
Shared Component regi stry key.
Status Returns
______________
0 RefList fi el d i s not empty.
1 RefList fi el d i s empty.
b. RemoveRIS(HINSTANCE remInstance, int flag);

Thi s functi on removes the RI S Shared Component servi ces, fi l es, and regi stry
entri es.
__________________
Description
___________
remInstance Removal process i nstance for the appl i cati on.
flag Return val ue from the RegRemoveRI S functi on.
readme1.txt Thi s uncompressed README fi l e contai ns the RI S product name and
versi on.
The pri mary purpose of thi s fi l e i s to keep track of the RI S Shared Component versi on,
but you can add i nformati on from the RI S README fi l e i f i t woul d be useful to the
end-user.
manifes1.txt Thi s uncompressed ASCI I fi l e l i sts the fi l es that are del i vered wi th the
RI S Shared Component. You must i ntegrate thi s fi l e i nto the mani fest fi l e for your
appl i cati on.
D.3 InstallingtheRIS Shared Component
The i nstal l ati on procedure does the fol l owi ng:
1. I nstal l s the requi red fi l es on the users fi l e system (after fi rst checki ng to make sure
that the versi on bei ng i nstal l ed i s the same or newer than any exi sti ng versi on) and i f
an ol der versi on i s found, i t i s removed.
2. Adds i nformati on to the regi stry.
3. I nstal l s the RI S TCP servi ce, and starts i t. Thi s servi ce l ets remote appl i cati ons and/or
cl i ents connect to other servers on the system.
4. Creates a RIS program group, whi ch contai ns vari ous hel p and executabl e uti l i ti es.
Location on FileSystem
RI S Shared Component i s i nstal l ed to the l ocati on speci fi ed i n the regi stry entry:
Program Files\Common Files\Intergraph\RIS\<Major.Minor>
The i nstal l ati on procedure exami nes the system PATH vari abl e to see i f i t contai ns the
\ ProgramFiles\ Common Files\ I ntergraph di rectory. I f the PATH does not contai n thi s
di rectory, the i nstal l ati on procedure appends \ ProgramFiles\ Common Files\ I ntergraph to
the system PATH.

Registry Information
The RI S Shared Component puts i nformati on i nto the System Regi stry to i ndi cate i ts
presence on the system. The component i nstal l ati on procedure creates the key
HKEY_LOCAL_MACHINE\Software\Intergraph\RIS\<Major.Minor>
and adds the fol l owi ng val ues:
Descri pti on
I nstal l Date
PathName
SoftwareType
I DNumber
Rel Date
Versi on
RefLi st
The RefList entry faci l i tates removal of the shared component. Al l products that use the RI S
Shared Component must add themsel ves to thi s reference l i st (wi th the RegEdtRI S functi on)
duri ng i nstal l ati on, and must remove themsel ves from the l i st (wi th the RemoveRI S functi on)
duri ng removal .
Any product that wants to remove a shared component can do so onl y i f the reference l i st for
the shared component i s empty. The RefList consi sts of a semi col on-separated l i st of
products that use the shared component. The referenci ng product stri ng has the format
<product_name>\ <product_version>where thi s i nformati on i s the same as the name\ version
porti on of the regi stry key for the product.
Glossary GL - 1

Glossary
__________________________________________________________________________________________________________________________________________________
GL - 2 Glossary

Glossary GL - 3

__________________________________________________________________________________________________________________________________________________
Glossary

accept Recei ve i nput, such as characters, i ntegers, or data buttons.
Al so, confi rmi ng an el ement sel ecti on.
access Perform acti ons necessary to use software.
activate Change the state of an object or enti ty so that i t accepts or
di spl ays data.
ad hoc query Query formul ated at runti me by i nput from a user or by the
program i tsel f.
address Label , name, or number that i denti fi es an exact storage
l ocati on i n memory.
alias An al ternate l abel for a command, program, or database
enti ty such as a l i ne added to the start-up fi l e that l ets you
start the software wi thout havi ng to key i n the ful l pathname
each ti me you want to use the software.
ANSI Acronym for Ameri can Nati onal Standards I nsti tute, a
pri vate organi zati on that devel ops, mai ntai ns, and publ i shes
i ndustry standards i n the Uni ted States.
api Acronym for appl i cati on programmers i nterface.
application System of programs or uti l i ti es desi gned to accompl i sh
speci fi c tasks as requested by the user.
array Data structure used to organi ze data i nto conti guous l i sts.
ASCII Ameri can Standard Code for I nformati on I nterchange
character set.
association A rel ati onshi p between two or more objects.
associative Havi ng a rel ati onshi p to another.
attribute Characteri sti c of an el ement. See al so parameter.
bar menu Stri p at the top of the screen that contai ns i cons for sel ecti ng
commands.
bit mask Numeri c val ue i n whi ch each bi t represents an on/off state.
Effi ci ent way to store mul ti pl e bool ean val ues i n a si ngl e
vari abl e, but cumbersome si nce you must mani pul ate
GL - 4 Glossary

i ndi vi dual bi ts to change the val ues. Each bi t i s usual l y
represented by a symbol i c constant.
block Uni t of storage whi ch usual l y equal s the amount of data that
can be read from or wri tten to the storage devi ce. For
exampl e, most di sk dri ves read or wri te a mi ni mum of 512
bytes. Therefore, the bl ock si ze of most di sk dri ves i s 512
bytes.
buffer Data area.
byte Group of bi ts formi ng a uni t of storage i n a di gi tal computer.
A byte usual l y consi sts of 8 bi ts but can contai n more or fewer
dependi ng on the model of computer. Bytes can al so contai n
error recogni ti on i nformati on.
C General -purpose, structured programmi ng l anguage
devel oped at Bel l Labs i n the earl y 1970s.
cache To store frequentl y used i nformati on i n a devi ce that i s faster
than the devi ce i t i s usual l y stored i n to i mprove performance.
For exampl e, frequentl y used i nformati on that i s usual l y
stored on a hard di sk dri ve can be cached i n memory, whi ch i s
consi derabl y faster.
catalog Tabl e of fi l es, arranged systemati cal l y, contai ni ng requi red
and user-defi ned fi l e attri butes.
character Al phabeti c l etter, di gi t, punctuati on, or symbol .
client Porti on of a cl i ent/server-based appl i cati on that requests
servi ces.
collapse Changi ng a form or wi ndow from the normal di spl ay to a
smal l i con representi ng the col l apsed form or wi ndow. Al so
cal l ed mi ni mi ze.
command Software that i nteracts wi th the user, obtai ni ng user i nput
and then acti ng i n a speci fi ed way based on that i nput. Each
i con on the menu accesses a command, al though there coul d
al so be addi ti onal commands accessed onl y by key-i n.
command file ASCI I fi l e contai ni ng the PPL (Parametri c Programmi ng
Language) statements needed to provi de a user-speci fi c
capabi l i ty.
command line Al phanumeri c key-i ns used to i nvoke an executabl e di rectl y
from the operati ng system envi ronment.
command name Al phanumeri c stri ng that corresponds to a gi ven command.
Glossary GL - 5

command string Al phanumeri c stri ng that corresponds to a gi ven command. A
command name.
communication
protocol
Rul es or standards defi ni ng communi cati on and data transfer
between two or more computer devi ces.
compile Transl ate a program wri tten i n some programmi ng l anguage
i nto machi ne l anguage or assembl y l anguage.
configuration file A system defi ned and user confi gurabl e fi l e contai ni ng
setti ngs that control envi ronment vari abl es.
constant Val ue that remai ns unchanged duri ng a programs executi on.
CPU Acronym for Central Processi ng Uni t.
cursor statement Embedded SQL statement requi ri ng a cursor data area; that
i s, a sel ect statement.
Data Definition
Language
(DDL) Subset of the ANSI SQL Standard statements whi ch
defi nes the schemas and rel ati ons of a database.
data dictionary Ei ther a fi l ed object space that contai ns i nformati on about the
cl asses that make up an appl i cati on or a set of ASCI I fi l es
created by a uti l i ty cal l ed a data di cti onary processor (ddp).
Data Manipulation
Language
(DML) Subset of the ANSI SQL Standard statements whi ch
mani pul ate the data contai ned i n a tabl e.
data point Poi nt entered wi th the mouse or wi th a preci si on key-i n,
whi ch speci fi es a posi ti on i n a drawi ng fi l e.
data structure Structure whose components are data objects. Data
structures are used to group l ogi cal l y rel ated data.
data type Cl assi fi cati on of a data i tem as an i nteger, l etter, or real
number.
database Col l ecti on of comprehensi ve i nformati onal fi l es havi ng
predetermi ned structure and organi zati on that can then be
communi cated, i nterpreted, or processed by a speci fi c
program.
database
administrator
User on a database or a schema defi ned on that user whi ch
has compl ete access to al l data defi ned on a database.
databaseprivilege Pri vi l ege granted to a schema regardi ng i ts access to a
database.
DB2 Rel ati onal database management system.
GL - 6 Glossary

DBA Acronym for Database Admi ni strator or DB Access.
DDL Acronym for Data Defi ni ti on Language.
debug Locate and correct errors i n the syntax or l ogi c of program
source code.
DEC Acronym for Di gi tal Equi pment Corporati on.
declaration Programmi ng statement that provi des i nformati on about a
vari abl e, functi on, or data type but does not perform any
operati on.
default schema Schema i n whi ch statements are i ssued unl ess another
schema i s speci fi ed (a RI S concept).
delimiter Separati ng mark or space; a character or sequence of
conti guous characters that mark the end of a stri ng of
characters.
design file Fi l e contai ni ng graphi c and text data. Al so cal l ed a drawi ng
fi l e.
development platform Base or foundati on of software on whi ch appl i cati on programs
can be bui l t.
device Nonaddressabl e component of a network, that i s, a component
onto whi ch a user cannot l og, for exampl e, tape dri ve, di sk
dri ve, and fl oppy di sk.
directory system Di rectory structure that contai ns the i nformati on for a desi gn
fi l e.
disk Round fl at pl ate coated wi th a magneti c substance on whi ch
data i s stored.
DML Acronym of Data Mani pul ati on Language.
doubleprecision Data type whi ch stores a range of fl oati ng poi nt numbers.
The storage requi rement and range of val ues are dependent
on the computer and compi l er.
drawingfile Fi l e i n whi ch you pl ace el ements. Al so cal l ed a desi gn fi l e.
el ement so you can see i t move.
drop To di sconti nue current status or associ ati on; to return to a
previ ous or more pri mi ti ve status or associ ati on; to descend
l evel s.
dynamic SQL
statement
Embedded SQL statement that i s not known unti l the
program i s executed.
Glossary GL - 7

entity Graphi c or descri pti ve component i n a graphi cs fi l e. Can al so
mean a database tabl e.
environment variable Vari abl e defi ned on or across i nvocati ons of a command shel l .
Processes are gi ven access to the i nformati on i n these
vari abl es by the operati ng system.
error handler Subrouti ne or group of statements that are executed when an
error occurs, and are desi gned to react to the error.
error message Descri pti on of an error found i n a program.
Ethernet Popul ar i mpl ementati on of a l ocal area network.
exception Condi ti on caused by an attempt to perform an erroneous
operati on.
exception handler Subrouti ne or group of statements that are executed when an
excepti on occurs, and are desi gned to react to the excepti on.
Al so known as an error handl er.
executable Program that has been wri tten i n or transl ated i nto, a
machi ne l anguage that i s ready for executi on by the
computer.
exit To termi nate a job or process.
field Any of the data grouped together i n a record (al so known as
an attri bute or col umn). Al so, a gadget al l owi ng text entry on
a form.
file Col l ecti on of l ogi cal records stored as a uni t.
filename User-defi ned name gi ven to an i nteracti vel y created fi l e. The
name shoul d be rel evant to the contents of the fi l e.
flag A vari abl e that can be set to i ndi cate the presence or absence
of a certai n condi ti on.
float Data type whi ch stores a range of fl oati ng poi nt numbers.
floatingpoint
notation
Notati on descri bi ng a real number val ue. I t consi sts of a
fracti onal val ue mul ti pl i ed by an exponent.
floatingpoint number Real number val ue i n fl oati ng poi nt notati on.
floppy disk Fl exi bl e magneti c sheet used to store i nformati on.
GL - 8 Glossary

font Compl ete set and styl e of the characters and symbol s of a
typeface used for di spl ayi ng text.
form Rectangul ar di spl ay through whi ch a user and an appl i cati on
can communi cate usi ng gadgets.
formlabel Uni que i nteger i denti fi er for a form, suppl i ed by programmer.
function Smal l segment of code wri tten to compl ete a porti on of a
l arger task.
global variable Programmi ng vari abl e that i s recogni zed everywhere i n a
program.
grant option Rel ati on pri vi l ege whi ch gi ves a schema the abi l i ty to grant
rel ati on pri vi l eges to other schemas.
graphic Any symbol or method of vi sual communi cati on that i s not
text.
group A col l ecti on of i cons that represent documents and
appl i cati ons wi thi n the Program Manager.
homedirectory Di rectory recogni zed by the operati ng system as root of a
users own di rectory system. I n UNI X, the envi ronment
vari abl e HOME i s set to thi s di rectory.
host variable Vari abl e defi ned i n host l anguage source code and used i n an
embedded SQL statement.
icon Symbol that graphi cal l y i denti fi es a command, appl i cati on, or
document.
ID Name composed of numbers or characters gi ven for
i denti fi cati on purposes to a record. A record number.
identify To i ndi cate your sel ecti on on a form or graphi cs by pl aci ng a
data poi nt on the i tem.
IGE Object-based, UNI X-based I ntergraph Graphi cs Envi ronment.
includefile Fi l e that contai ns i nformati on such as symbol i c constants,
structure defi ni ti ons, vari abl e decl arati ons, and some
standard functi ons and macros.
index Storage mechani sm used to provi de faster access to the rows
i n a tabl e.
indicator variable Vari abl e defi ned i n host l anguage source code and used i n an
embedded SQL statement to i ndi cate the usage of a NULL
val ue.
Glossary GL - 9

INFORMIX Rel ati onal database management system.
INGRES Rel ati onal database management system.
initialize To set storage l ocati on, counter, vari abl e, i nternal structures,
or the l i ke to a begi nni ng val ue.
integer Val ue i n the set of al l posi ti ve and negati ve whol e numbers
and zero. Al so, a data type whi ch stores a range of i nteger
val ues. Storage requi rement and range of val ues are
dependent on the computer and compi l er. Of or rel ati ng to
the process of enteri ng data and recei vi ng a response from the
computer.
interactive Of or rel ati ng to the process of enteri ng data and recei vi ng a
response from the computer.
interface Shared boundary through whi ch the user and software
communi cate.
I/ORL I ntergraph On-l i ne Reference Li brary. Provi des easy access
to I ntergraph documentati on on compact di sk.
item Uni t of storage wi thi n a l arger uni t, such as a fi l e i n a
cabi net.
joining Process of rel ati ng the data i n two or more tabl es, possi bl y
restri cted by some condi ti on.
key-in I nformati on or command keyed i n, rather than sel ected usi ng
a mouse.
keyword Word defi ned to have speci al meani ng i n a programmi ng,
command, query l anguage, or i ndexi ng.
LAN Acronym for l ocal area network.
library Col l ecti on of subrouti nes.
linear Havi ng a si ngl e di mensi on; a l i ne.
link Combi ne one or more program segments, subrouti nes, or
l i brary routi ne i nto a si ngl e executabl e program.
local area network Computer networki ng scheme i n whi ch nodes whi ch are
geographi cal l y l ocal are connected to a network through
mul ti pl exers, and networks of geographi cal l y remote nodes
are connected through routers.
login Enter the necessary i nformati on, such as a username and
password, to begi n a sessi on on a termi nal .
GL - 10 Glossary

macro, RIS Mechani sm whi ch al l ows stri ngs to be assi gned symbol i c
names and to be repl aced by thei r ful l val ues at a l ater ti me.
malloc A functi on provi ded wi th the C programmi ng l anguage that
al l ocates space at runti me. The functi ons argument speci fi es
the amount of space requi red. Thi s functi on returns a poi nter
to the fi rst address of the al l ocated memory.
mask Val ue wi th bi ts set on and off to set up certai n attri butes.
memory Devi ce that can store data.
menu Means for stori ng and sel ecti ng commands: i con-based,
functi on key, or paper.
mode Parti cul ar functi oni ng arrangement or condi ti on. Al so, the
behavi or of a gadget.
model Graphi c representati on or schema.
network I nterconnecti on of host computers and workstati ons that l ets
them share data and control . The term network can mean the
devi ces that connect the system, or i t can mean the connected
system.
node Any nonaddressabl e component of a network; that i s, any
component of the network onto whi ch a user can l ocal l y or
remotel y l og.
noncursor statement Embedded SQL statement that does not requi re a cursor data
area; that i s, al l statements other than the sel ect statement.
NULL I ndi cates no val ue.
on-lineHelp Set of on-l i ne, context sensi ti ve fi l es, that provi de i nformati on
to the user about the capabi l i ti es of an appl i cati on.
operatingsystem System programs that control the overal l operati on of a
computer system.
ORACLE Rel ati onal database management system.
ORL See I / ORL.
overview Reduced resol uti on di spl ay of an i mage i n a raster data fi l e.
An overvi ew i s normal l y l ocated i n the raster data fi l e i tsel f.
parameter, RIS Mechani sm for representi ng an unknown val ue i n a
subrouti ne cal l or a host vari abl e i n an embedded SQL
statement.
Glossary GL - 11

password Word that i s entered duri ng l og i n that prevents unauthori zed
peopl e from usi ng the fi l e, software, or computer.
path Sequence of di rectori es l eadi ng to a fi l e or a sequence of
menus l eadi ng to a command.
place To create and posi ti on an el ement or object.
pointing Movi ng the mouse to pl ace the poi nter over a menu command,
button, or an i tem on your screen.
pop-to-bottom Move the speci fi ed form or wi ndow to the bottom of the
di spl ay stack. Al so, the i con used to perform thi s command.
pop-to-top Move the speci fi ed form or wi ndow to the top of the di spl ay
stack. Al so, the i con used to perform thi s command.
portable Desi gnati ng a program that i s easi l y executed (or can be
easi l y modi fi ed to execute) on mul ti pl e computers or software
systems.
preprocessor Program that performs some type of cal cul ati on or
mani pul ati ons on the data i n a fi l e, usual l y i n preparati on for
another process.
privilege Descri bed by the ANSI SQL Standard. A pri vi l ege i s a ri ght
to access. For exampl e: a rel ati on pri vi l ege i s a ri ght to
access a rel ati on (tabl e or vi ew) wi thi n a database.
process Enti ty composed of a program or seri es of programs.
prompt Text di spl ayed by a command that tel l s you the i nputs
expected by that command.
query A search i n a database.
raster Pattern of hori zontal scanni ng l i nes on the screen of a CRT:
i nput data causes the beam of the tube to i l l umi nate the
correct pi xel s on these l i nes to produce the requi red
characters, curves, and so forth.
raster data file Fi l e contai ni ng raster data (pi xel s). Raster data fi l es can be
generated by opti cal scanner, vi deo frame grabber, di gi tal
camera, i nteracti ve pai nt package, and so forth. I ntergraph
raster data fi l es are characteri zed by speci fi c data formats
whi ch are i denti fi ed i n the fi l e headers.
RDBMS Acronym for Rel ati onal Database Management System, the
software that l ets you organi ze, store, and mani pul ate data i n
a database.
GL - 12 Glossary

real Data type whi ch stores a range of fl oati ng poi nt numbers.
record Groupi ng of l ogi cal l y rel ated data whi ch can be mani pul ated
as a si ngl e enti ty. One or more records make up a fi l e or a
tabl e. Al so known as a row or tupl e.
relation Tabl e or vi ew.
relation privilege Pri vi l ege granted to a schema regardi ng i ts access to rel ati ons
i n other schemas.
relational database
management system
Database management system that adheres to concepts
defi ned by the rel ati onal database model .
Relational Interface
System
I ntergraph software system that provi des a generi c i nterface
for appl i cati ons to access many popul ar rel ati onal database
management systems.
report Standard and user-defi nabl e tabl e format for i nformati on
queri ed from the database.
requester See client.
resize To change the si ze and posi ti on of a form or wi ndow.
resolution Number of pi xel s of whi ch a screen i s composed. The greater
the number of pi xel s, the hi gher the resol uti on.
restore To erase al l edi ti ng changes on an i mage, l eavi ng the ori gi nal
i mage compl ete.
RIS Acronym for Rel ati onal I nterface System, the software that
l ets di fferent rel ati onal database management systems
communi cate wi th each other.
root El ement upon whi ch an associ ati ve el ement or macro
depends.
routine Set of functi ons constructed to process speci fi c i nformati on.
row Groupi ng of l ogi cal l y rel ated data whi ch may be mani pul ated
as a si ngl e enti ty. One or more rows make up a fi l e or tabl e.
Al so known as a record or tupl e.
run To execute a program or process.
runtime Ti me at or duri ng whi ch a program or process i s executed.
Glossary GL - 13

scalar data type Si mpl e data type. For exampl e, i nteger, character, real .
scale To enl arge or reduce the si ze of a defi ned el ement, modi fyi ng
onl y the di mensi ons, not the rati o among the pi eces.
scan To l oad a paper document i nto the i mage format usi ng an
i mage scanner.
schema Concept descri bed by the ANSI SQL Standard as a col l ecti on
of tabl es and vi ews. Wi thi n RI S, thi s col l ecti on corresponds to
the col l ecti on of tabl es and vi ews wi thi n a database.
select To acti vate a command. Thi s can be done by the user or
software.
semaphore Fl ag that prevents two or more UNI X processes from
accessi ng the same resource at the same ti me.
server Computer, connected to a network, that provi des servi ces to
one or more devi ces on that network. A server can al so refer
to a process that provi des servi ces to one or more cl i ent
(requester) processes l ocal l y or remotel y.
set Groupi ng of i tems that can be mani pul ated as a si ngl e i tem.
Shamrock I ntergraph graphi cal user-i nterface tool ki t for Wi ndows NT.
shared library Li brary from whi ch several programs can cal l routi nes. The
code for the cal l ed routi nes i s not copi ed i nto the executabl e
program at the ti me the program i s l i nked. I nstead, i t i s read
i n (on demand) at runti me. Thi s resul ts i n smal l er executabl e
programs.
shared memory (shmem) UNI X shared memory; that i s, memory whose
protecti on and access i s gl obal to more than one process.
shell Body of commands provi di ng i nterface to l ow l evel software.
For exampl e, a UNI X shel l provi des an i nterface between
users and the UNI X kernel .
short Data type whi ch stores a range of i nteger val ues. Storage
requi rement and range of val ues are dependent on the
computer and compi l er.
signal Mechani sm provi ded by the UNI X operati ng system for
i nterprocess communi cati on.
signal handler Functi on desi gned to respond to a si gnal .
smallint Data type whi ch stores a range of i nteger val ues. Storage
requi rement and range of val ues are dependent on the
computer and compi l er.
GL - 14 Glossary

sourcefile Fi l e composed of ordi nary C code pl us code whi ch uses some
addi ti onal l anguage features needed to support I ntergraphs
i mpl ementati on of an object-ori ented programmi ng
envi ronment. The object preprocessor (opp) processes source
fi l es to handl e the OM-speci fi c l anguage features.
SQL Acronym for Structured Query Language.
SQL data type Data types defi ned by the ANSI SQL Standard.
SQL terminator Semi col on (;). I t i s used to termi nate an Embedded SQL
statement.
sqlda structure ANSI Standard SQL structure used to represent i nformati on
about the sql var structures i n an Embedded SQL statement.
sqlvar structure ANSI Standard SQL structure used to represent i nformati on
about a parameter (vari abl e) i n an Embedded SQL statement.
stack Ordered l ayer of i tems such that the l ast i n i s fi rst out.
statement Word or group of words that has a speci fi c meani ng i n a
programmi ng l anguage.
static SQL statement Embedded SQL statement that i s known when the program i s
created and i s compi l ed i nto that program.
string Sequence of characters.
Structured Query
Language
Structured l anguage desi gned for accessi ng rel ati onal
database management systems.
symbolic constant Symbol i c name for a val ue that does not change duri ng a
programs executi on. Used to make programs more readabl e.
syntax Rul es governi ng the structure and use of statements i n a
l anguage.
system Col l ecti on of i nformati on and processes desi gned to i nteract to
compl ete a task.
table Col l ecti on of data for qui ck reference, stored i n sequenti al
l ocati ons i n memory or pri nted as an array of rows and
col umns of data i tems of the same type.
table, database Col l ecti on of data rows (al so known as tupl es or records) and
col umns (al so known as attri butes or fi el ds). A uni t of storage
descri bed by the ANSI SQL Standard.
TCP/IP Acronym for Transmi ssi on Control Protocol /I nternet Protocol ;
a network protocol .
Glossary GL - 15

toggle To swi tch; to change between two al ternati ves. Al so, a state
gadget that can be used to change between two al ternati ves.
transaction Concept descri bed by the ANSI SQL Standard. A transacti on
i s a group of SQL Statements that affect the database
si mul taneousl y or can be cancel ed si mul taneousl y.
tuple Record or a row.
type Type of data that a programmi ng vari abl e can contai n.
typeface Desi gn of a text font.
UNIX General purpose operati ng system devel oped at Bel l
Laboratori es i n the l ate 60s and earl y 70s.
user Person who uses a computer.
user interface End users means of communi cati ng wi th the software,
i ncl udi ng any of the means of enteri ng val ues, sel ecti ng
commands, or l ocati ng el ements. The menus and prompts are
exampl es of user i nterfaces.
value Numeri c or character data.
variable Quanti ty that can assume any one of a set of val ues.
VAX/VMS Computer/operati ng system combi nati on. The VAX i s a
fami l y of processors manufactured and sol d by Di gi tal
Equi pment Corporati on. VMS i s an operati ng system for the
VAX fami l y.
version The number associ ated wi th the speci fi c rel ease of a product.
view Concept descri bed by the ANSI SQL Standard, used to
combi ne tabl es or restri ct access to col umns i n a tabl e. A vi ew
l ooks and acts l i ke a tabl e, but does not actual l y store data.
view, database Concept descri bed by the ANSI SQL Standard, used to
combi ne tabl es or restri ct access to col umns i n a tabl e. A vi ew
l ooks and acts l i ke a tabl e, but does not actual l y store data.
virtual declaration Mechani sm i n RI S whi ch l ets compl ex data types and address
expressi ons be used i n Embedded SQL statements.
virtual table Synonym for vi ew.
wildcard Symbol representi ng any stri ng of characters.
XNS Communi cati on protocol used on the Ethernet network.
GL - 16 Glossary

I ndex I N - 1

Index
__________________________________________________________________________________________________________________________________________________
I N - 2 I ndex

I ndex I N - 3

__________________________________________________________________________________________________________________________________________________
Index

A
accessi ng
di cti onary vi ews A-7
al i ases
excl ude/i ncl ude sequences A-4
object A-4
wi thi n RI S A-4
al ter statement B-7
al ter tabl e form 6-3
Ameri can nati onal standards i nsti tute 2-3
ANSI 2-3
api l i brary 2-6
asci i stri ngs 5-8
async statement 4-7
asynchronous executi on
statements 2-24
autocommi t mode B-7
B
before you begi n 1-3
begi n decl are statement 4-8
bi nary data A-8
bi nary data type 3-3
bi ndi ng
host vari abl es 2-12
bi t masks 5-27
bl ob data type 3-3
BLOBS
programmi ng i nterface A-8
buffer poi nter 5-39
C
cauti on symbol 1-5
char[ ] data type 4-8
char* data type 4-8
choose 1-4
cl ear async statement 4-10
cl ear cursor statement 2-21
cl ear statement B-5, 2-16, 2-18, 2-21, 4-9
cl eari ng
cursors 4-9
dynami c statements 4-9
cl i ent process 5-20
cl i ent_parms structure 5-3
cl ose cursor statement 2-21
cl ose statement 2-16, 2-21, 4-11
cl osi ng cursors 4-11
col umns, sel ecti ng 4-30
commi t statement B-7
compi l er di recti ves
preprocessi ng statements 4-13, 4-18,
4-20, 4-24 4-26, 4-34
compi l i ng 2-5
confi gurati on fi l e
l anguage C-3
connecti ng to tabl es
granti ng and revoki ng authori ty A-5
conventi ons, document 1-5
CopyFi l esI nCopyLi st D-4
countp poi nter 5-39
create schema form 6-3
create statement B-7
create tabl e form 6-3
creati ng
tabl es, granti ng and revoki ng authori ty
A-5
creati ng appl i cati ons 2-3
creati ng di cti onari es A-6
cursor statements 2-14
cursors
cl eari ng 2-21, 4-9
cl osi ng 2-21, 4-11
decl ari ng 4-12
fetchi ng 4-23
openi ng 2-21, 4-27
D
data
i ncl udi ng owned by pri vi l eged accounts
A-3
i nserti ng l arge A-8
l ong bi nary A-8
l ong text A-8
retri evi ng l arge A-8
updati ng l arge A-8
data defi ni ti on form 6-3
I N - 4 I ndex

data type
RI S_BLOB A-8
RI S_TEXT A-8
databases
mul ti pl e schemas i n A-6
retri evi ng i nformati on 5-35
dateti me structure 5-3, 5-8 5-9, 5-11
dbca poi nter B-4, 2-10
dbl i stp poi nter 5-32
dbms_owner A-4
dbp poi nter 5-23, 5-35
decl are cursor statement 4-12
decl are schema statement A-5
decl are statement 2-16, 2-21
decl ari ng
cursors 4-12
host vari abl es 4-19
tabl es B-3
vari abl es 4-8, 4-19
vi ews B-3
vi rtual vari abl es 4-19
defi ne statement 4-13
defi ni ti on of schema i n RI S 5 A-3
del ete statement B-5, B-7
descri be statement 2-18, 2-21, 4-14
di cti onary
addi ng schemas to A-6
creati ng A-6
creati on A-6
objects A-6
shared A-6
vi ews
accessi ng from appl i cati on A-7
i nformati on i n A-7
di cti onary access form 6-3
di spl ay form functi ons 6-11
di spl ayed forms functi ons 6-10
document conventi ons 1-3
doubl e data type 4-8
drop schema form 6-3
drop statement B-7
drop tabl e form 6-3
droppi ng schemas A-6
dskl ayt2 D-3
dynami c SQL statements
ANSI standard 2-4
future changes 2-4
dynami c statements 2-14
cl eari ng 4-9
cursor 2-21
executi ng 4-21 4-22
dynami c statements (continued)
noncursor 2-18
parameteri zi ng 2-12, 2-19
prepari ng 4-28
E
el se statement 4-18
embedded l oadi ng
usi ng ri sl oddes for 7-3
usi ng ri sul ddes for 7-4
Embedded SQL statements 2-14, 4-3, 4-21,
4-31
async 4-3, 4-7
begi n decl are 4-3, 4-8
C l anguage source code 2-4
cl ear 4-3, 4-9
cl ear async 4-3, 4-10
cl ose 4-3, 4-11
decl are cursor 4-3, 4-12
defi ne 4-4, 4-13
defi ni ti on 2-4
descri be 4-4, 4-14
el se 4-4, 4-18
end decl are 4-4, 4-19
endi f 4-4, 4-20
execute 4-4
execute i mmedi ate 4-4, 4-22
fetch 4-4, 4-23
i fdef 4-4, 4-24
i fndef 4-4, 4-25
i ncl ude 4-4, 4-26
open 4-4, 4-27
prepare 4-5, 4-28
preprocessor 2-5
qui ck reference 4-3
report error 2-9, 4-5, 4-29
ri scpp.exe 2-5
sel ect i nto 4-5, 4-30
sql 4-5
test compl eti on 4-5, 4-32
UMS l i brary 2-5
undef 4-5, 4-34
wai t compl eti on 4-5, 4-35
whenever 4-5, 4-36
enabl e_dbms 5-27
end decl are statement 4-19
endi f statement 4-20
END_OF_DATA 2-9
envi ronment vari abl e
RI S_LANGUAGE 2-5
I ndex I N - 5

erase form functi ons 6-12
error handl i ng B-3, 2-9
errors
database-speci fi c 2-10
dbca poi nter 2-10
END_OF_DATA 2-9
handl i ng 4-36
report error statement 2-9, 4-29
ri ssql ca structure 2-9
sql ca structure 2-9
sql code fi el d 2-9
SQLCODE vari abl e 2-9
sql errm fi el d 2-9
sql errmc fi el d 2-9
sql errml fi el d 2-9
whenever cl ause 2-9, 4-36
exampl e programs
for forms 6-4
for functi ons 5-7
for l oadi ng and unl oadi ng 7-5
for SQL 4-6
excepti ons 2-9, 4-36
excl ude form 6-3
excl ude/i ncl ude sequences A-4
exec sql prefi x 2-14, 4-31
execute i mmedi ate statement B-5, 2-19,
4-22
execute statement 2-18, 4-21
executi on of SQL statements 4-31
dynami c B-5, 4-21 4-22
stati c B-5
F
fetch statement 2-16, 2-21, 4-23
fetchi ng cursors 4-23
fl oat data type 4-8
forms
al ter tabl e form 6-3
create schema form 6-3
create tabl e form 6-3
data defi ni ti on form 6-3
di cti onary access form 6-3
di spl ay functi ons 6-11
di spl ayed functi ons 6-10
drop schema form 6-3
drop tabl e form 6-3
erase functi ons 6-12
error code 6-11 6-12
exampl e programs 6-4
excl ude form 6-3
i ncl ude fi l e 6-4
forms (continued)
i ncl ude fi l es 6-3
i ncl ude form 6-3
i ni ti al i ze 6-4
l i brari es 6-3
modi fy DB2 password form 6-3
modi fy node i nfo form 6-3
modi fy schema password form 6-3
ri s database form 6-3
RI S schema manager 6-3
RI Sforms.h i ncl ude fi l e 6-4
RI Sfrm_al ter_tabl e_form_di spl ayed 6-10
RI Sfrm_create_schema_form_di spl ayed
6-10
RI Sfrm_create_tabl e_form_di spl ayed
6-10
RI Sfrm_data_def_form_di spl ayed 6-10
RI Sfrm_db2pass_form_di spl ayed 6-10
RI Sfrm_di ct_access_form_di spl ayed 6-10
RI Sfrm_di spl ay_al ter_tabl e_form 6-11
RI Sfrm_di spl ay_create_schema_form
6-11
RI Sfrm_di spl ay_create_tabl e_form 6-11
RI Sfrm_di spl ay_data_def_form 6-11
RI Sfrm_di spl ay_db2pass_form 6-11
RI Sfrm_di spl ay_di ct_access_form 6-11
RI Sfrm_di spl ay_drop_schema_form 6-11
RI Sfrm_di spl ay_drop_tabl e_form 6-11
RI Sfrm_di spl ay_excl ude_form 6-11
RI Sfrm_di spl ay_i ncl ude_form 6-11
RI Sfrm_di spl ay_l ocate_cl i ent_form 6-11
RI Sfrm_di spl ay_node_i nfo_form 6-11
RI Sfrm_di spl ay_ri s_dbs_form 6-11
RI Sfrm_di spl ay_schema_access_form
6-11
RI Sfrm_di spl ay_schema_defi ni ti on_form
6-11
RI Sfrm_di spl ay_schema_fi l e_form 6-11
RI Sfrm_di spl ay_schema_i nfo_form 6-11
RI Sfrm_di spl ay_schema_mgr_form 6-11
RI Sfrm_di spl ay_schpass_form 6-11
RI Sfrm_di spl ay_set_form 6-11
RI Sfrm_di spl ay_tabl e_i nfo_form 6-11
RI Sfrm_drop_schema_form_di spl ayed
6-10
RI Sfrm_drop_tabl e_form_di spl ayed 6-10
RI Sfrm_erase_al ter_tabl e_form 6-12
RI Sfrm_erase_create_schema_form 6-12
RI Sfrm_erase_create_tabl e_form 6-12
RI Sfrm_erase_data_def_form 6-12
RI Sfrm_erase_db2pass_form 6-12
I N - 6 I ndex

forms (continued)
RI Sfrm_erase_di ct_access_form 6-12
RI Sfrm_erase_drop_schema_form 6-12
RI Sfrm_erase_drop_tabl e_form 6-12
RI Sfrm_erase_excl ude_form 6-12
RI Sfrm_erase_i ncl ude_form 6-12
RI Sfrm_erase_l ocate_cl i ent_form 6-12
RI Sfrm_erase_node_i nfo_form 6-12
RI Sfrm_erase_ri s_dbs_form 6-12
RI Sfrm_erase_schema_access_form 6-12
RI Sfrm_erase_schema_defi ni ti on_form
6-12
RI Sfrm_erase_schema_fi l e_form 6-12
RI Sfrm_erase_schema_i nfo_form 6-12
RI Sfrm_erase_schema_mgr_form 6-12
RI Sfrm_erase_schpass_form 6-12
RI Sfrm_erase_set_form 6-12
RI Sfrm_erase_tabl e_i nfo_form 6-12
RI Sfrm_excl ude_form_di spl ayed 6-10
RI Sfrm_i ncl ude_form_di spl ayed 6-10
RI Sfrm_i ni ti al i ze 6-4
RI Sfrm_i ni t_parms data type 6-4
RI Sfrm_l ocate_cl i ent_form_di spl ayed
6-10
RI Sfrm_node_i nfo_form_di spl ayed 6-10
RI Sfrm_ri s_dbs_form_di spl ayed 6-10
RI Sfrm_schema_access_form_di spl ayed
6-10
RI Sfrm_schema_defi ni ti on_form_di spl ayed
6-10
RI Sfrm_schema_fi l e_form_di spl ayed
6-10
RI Sfrm_schema_i nfo_form_di spl ayed
6-10
RI Sfrm_schema_mgr_form_di spl ayed
6-10
RI Sfrm_schpass_form_di spl ayed 6-10
RI Sfrm_set_form_di spl ayed 6-10
RI Sfrm_tabl e_i nfo_form_di spl ayed 6-10
schema defi ni ti on form 6-3
schema fi l e form 6-3
schema i nformati on form 6-3
schema manager 6-3
schema manager form 6-3
secure schema access form 6-3
set form 6-3
Set Functi ons 6-9
tabl e i nformati on form 6-3
Forms Functi ons Error Handl i ng 6-13
free functi on 5-23, 5-35
functi ons 5-3
free 5-35
l i brari es 5-7
l oad 7-31
RI Sasci i _to_dateti me 5-8
RI Sdateti me_to_asci i 5-9
RI Sget_ansi _mode 5-13
RI Sget_app_versi on 5-14
RI Sget_async_stmts 5-15
RI Sget_autocommi t_mode 5-17
RI Sget_autorename_mode 5-18
RI Sget_bl ankstri p_mode 5-19
RI Sget_cl i ent_l ocati on 5-20
RI Sget_current_stmt_schema_name
5-22
RI Sget_dbca 5-25
RI Sget_db_i nfo 5-4, 5-23
RI Sget_defaul t_schema_name 5-26
RI Sget_enabl ed_databases 5-27
RI Sget_l anguage_name 5-29
RI Sget_parameters 5-30
RI Sget_ri sca 5-31
RI Sget_ri s_sql type_code 5-44
RI Sget_ri s_sql type_stri ng 5-45
RI Sget_schema_fi l e 5-32
RI Sget_schema_fi l e_l ocati on 5-37
RI Sget_schema_i nfo 5-35
RI Sget_schema_names 5-39
RI Sget_schema_transacti ons 5-42
RI Sget_sql code 5-46
RI Sget_veri fy_mode 5-47
RI Si ni ti al i ze B-4, 5-48
RI S_l oader 7-31
RI Sl ocate_cl i ent 5-49
RI Sl ocate_schema_fi l e 5-51
ri sl od_fpri nt 7-32
ri sl od_pri nt 7-33
RI Srestore_schema_fi l e_checksum 5-53
RI Sstart_cl i ent 5-54
RI Sstop_cl i ent 5-55
RI Stermi nate B-4, 5-56
ri sul d_fpri nt 7-33
ri sul d_pri nt 7-34
RI S_unl oader 7-31
unl oad 7-32
G
GRANT CONNECT TO A-5
I ndex I N - 7

GRANT RESOURCE TO A-5
GRANT SCHEMA TO A-6
grantee
granteep poi nter 5-32, 5-35
H
handl i ng errors 4-36
Hel p
usi ng on-l i ne 1-5
host vari abl es
bi ndi ng 2-12
decl ari ng 2-11, 4-8, 4-19
exampl es 2-11
I
i denti fi ers
record B-7
i denti fy 1-4
i fdef statement 4-24
i fndef statement 4-25
i ncl ude fi l es
for forms 6-3
for functi ons 5-7
for l oadi ng and unl oadi ng 7-4
for SQL 4-6
ri s.h 5-27
ri sl i mi t.h 5-39
RI Sl i mi ts.h 5-39
i ncl ude form 6-3
i ncl ude sequences A-4
i ncl ude statement 4-26
i ncl udi ng data owned by pri vi l eged accounts
A-3
i ndexes
wi th same name A-4
i ndexi ng
proper use of B-10
i ndi cator vari abl es 2-12
i ni ti al i zi ng B-4
expl i ci t B-4
i nsert statement B-5, B-7, 2-19
i nserti ng l arge data A-8
i nstal l i ng the RI S shared component D-5
i nt data type 4-8
i ntroducti on 2-3
K
key i n 1-4
L
l anguage confi gurati on fi l e C-3
l i brari es 2-5
for forms 6-4
for functi ons 5-7
for l oadi ng and unl oadi ng 7-4 7-5
for SQL 4-6
l i nki ng 2-5
l oad
defi ni ti on 7-3
l oad and unl oad
l i brari es 7-5
l oad and unl oad exampl e programs 7-5
l ock tabl es statement B-4
l ocki ng B-4
expl i ci t B-4
i mpl i ci t B-4
tabl e 2-23
l ocks B-4
excl usi ve B-4
shared B-4
types B-4
l ong bi nary data A-8
l ong text data A-8
M
macros 5-27
mal l oc 4-16, 5-23, 5-32, 5-35
managi ng statements B-5
mani fes1.txt D-5
MAX_STATI C_STMTS parameter B-5
MAX_TRANSACTI ONS 2-24
message boxes 2-6
modes
autocommi t B-7
setti ng veri fy B-6
modi fy DB2 password form 6-3
modi fy node i nfo form 6-3
modi fy schema password form 6-3
mouse 1-3
mul ti pl e transacti ons 2-23
N
names, al i ases A-4
noncursor statements 2-14
not nul l keywords 2-12
note symbol 1-5
NULL val ues 2-12
I N - 8 I ndex

O
object fi l es 2-5
objects
al i ases A-4
di cti onary A-6
of di fferent owners wi thi n a schema A-3
ownershi p A-3
shari ng among schemas A-3
on-l i ne Hel p 1-5
on-l i ne hel p 2-4
open cursor statement 2-21
open statement 2-16, 2-21, 4-27
openi ng
cursors 4-27
operators
UNI ON and UNI ON ALL A-3
order by statements B-5
ownershi p of objects A-3
P
parameteri zi ng dynami c statements 2-19
usi ng a questi on mark (?) 2-12
parameters
MAX_STATI C_STMTS B-5
parameters fi l e B-5, 4-31, 5-37, 5-49, 5-51
parms fi l e 5-51
parts of the Hel p wi ndow 1-5
passwords
RI S A-5
stored for schema A-5
PATH D-6
pc conventi ons 1-5
performance consi derati ons B-3
poi nters
buffer 5-39
countp 5-39
dbca B-4
dbl i stp 5-32
dbp 5-23, 5-35
granteep 5-32, 5-35
ri sca B-4
schemap 5-35
schl i stp 5-32
prepare statement 2-18, 2-21, 4-28
prepari ng dynami c statements 4-28
prepari ng statements B-5
preprocessi ng statements
compi l er di recti ves 4-13, 4-18, 4-20,
4-24 4-26, 4-34
preprocessor 2-5
fi l e extensi on 2-5
preprocessor (continued)
graph 2-7
i nvoki ng 2-5
opti ons 2-5
return val ue 2-5
pri vi l eged accounts
i ncl udi ng data owned by A-3
program i nterface 2-3
programmi ng notes B-3
Q
queri es
changi ng object names A-6
qui ck reference 4-3
R
RDBMS 2-3
l ogi ns A-5
securi ty tracki ng A-5
versi ons, compati bl e wi th RI S 5 A-3
ReadI nfFi l e D-3
readme1.txt D-5
record i denti fi ers B-7
redi stri buti on of RI S runti me and RI S
uti l i ti es D-3
RegEdtRI S D-4
RegRemoveRI S D-5
rel ati onal database management system
2-3
rel ati onal i nterface system 2-3
RemoveRI S D-5
report error statement B-4, 2-9, 4-29
reporti ng errors 4-29
requesti ng i nformati on
errors 4-29
i nput parameters 4-14
output resul ts 4-14
requi red products 2-4
reset 1-4
retri evi ng
l arge data A-8
REVOKE CONNECT FROM A-5
REVOKE RESOURCE FROM A-5
REVOKE SCHEMA FROM A-6
RI S
compati bi l i ty 2-3
defi ni ti on 2-3
embedded SQL 2-3
forms functi ons 6-3
i ni ti al i zi ng B-4
i ntroducti on to 2-3
I ndex I N - 9

RI S (continued)
l oad 7-3
object ownershi p A-3
password storage A-5
preprocessor 2-5
program i nterface 2-3
rel ated documentati on 1-3
schema manager 6-3
shared component di rectory structure
D-3
supported pl atforms 2-4
termi nati ng B-4
unl oad 7-3
versi ons
i nteroperabi l i ty A-11
RI S cl i ent processes B-4
termi nati on of B-12
RI S connecti ons B-6
ri s database form 6-3
RI S Devel opment Pl atform
capabi l i ti es provi ded 2-3
RI S embedded SQL statements 4-6
ri sal pha uti l i ty A-12
RI Sasci i _to_dateti me 5-8
RI S_BLOB A-8
ri s_bl ob 3-3
ri sca poi nter B-4, 2-9
RI SCLI 5-37
ri scpp.exe 2-5
fi l e extensi on 2-5
graph 2-7
i nvoki ng 2-5
l i brari es 2-5
l i nki ng 2-5
object fi l es 2-5
opti ons 2-5
return val ue 2-5
RI Sdateti me_to_asci i 5-9
ri s_db2_i nfo structure 5-4
ri s_db_i nfo structure 5-4
ri sdbms_i ndexes A-7
ri sdbms_tabl es A-7
ri sdbms_vi ews A-7
ri sforms.l i b l i brary 2-6
RI Sfrm_al ter_tabl e_form_di spl ayed 6-10
RI Sfrm_create_schema_form_di spl ayed
6-10
RI Sfrm_create_tabl e_form_di spl ayed 6-10
RI Sfrm_data_def_form_di spl ayed 6-10
RI Sfrm_db2pass_form_di spl ayed 6-10
RI Sfrm_di ct_access_form_di spl ayed 6-10
RI Sfrm_di spl ay_al ter_tabl e_form 6-11
RI Sfrm_di spl ay_create_schema_form 6-11
RI Sfrm_di spl ay_create_tabl e_form 6-11
RI Sfrm_di spl ay_data_def_form 6-11
RI Sfrm_di spl ay_db2pass_form 6-11
RI Sfrm_di spl ay_di ct_access_form 6-11
RI Sfrm_di spl ay_drop_schema_form 6-11
RI Sfrm_di spl ay_drop_tabl e_form 6-11
RI Sfrm_di spl ay_excl ude_form 6-11
RI Sfrm_di spl ay_i ncl ude_form 6-11
RI Sfrm_di spl ay_l ocate_cl i ent_form 6-11
RI Sfrm_di spl ay_node_i nfo_form 6-11
RI Sfrm_di spl ay_ri s_dbs_form 6-11
RI Sfrm_di spl ay_schema_access_form 6-11
RI Sfrm_di spl ay_schema_defi ni ti on_form
6-11
RI Sfrm_di spl ay_schema_fi l e_form 6-11
RI Sfrm_di spl ay_schema_i nfo_form 6-11
RI Sfrm_di spl ay_schema_mgr_form 6-11
RI Sfrm_di spl ay_schpass_form 6-11
RI Sfrm_di spl ay_set_form 6-11
RI Sfrm_di spl ay_tabl e_i nfo_form 6-11
RI Sfrm_drop_schema_form_di spl ayed 6-10
RI Sfrm_drop_tabl e_form_di spl ayed 6-10
RI Sfrm_erase_al ter_tabl e_form 6-12
RI Sfrm_erase_create_schema_form 6-12
RI Sfrm_erase_create_tabl e_form 6-12
RI Sfrm_erase_data_def_form 6-12
RI Sfrm_erase_db2pass_form 6-12
RI Sfrm_erase_di ct_access_form 6-12
RI Sfrm_erase_drop_schema_form 6-12
RI Sfrm_erase_drop_tabl e_form 6-12
RI Sfrm_erase_excl ude_form 6-12
RI Sfrm_erase_i ncl ude_form 6-12
RI Sfrm_erase_l ocate_cl i ent_form 6-12
RI Sfrm_erase_node_i nfo_form 6-12
RI Sfrm_erase_ri s_dbs_form 6-12
RI Sfrm_erase_schema_access_form 6-12
RI Sfrm_erase_schema_defi ni ti on_form 6-12
RI Sfrm_erase_schema_fi l e_form 6-12
RI Sfrm_erase_schema_i nfo_form 6-12
RI Sfrm_erase_schema_mgr_form 6-12
RI Sfrm_erase_schpass_form 6-12
RI Sfrm_erase_set_form 6-12
RI Sfrm_erase_tabl e_i nfo_form 6-12
RI Sfrm_excl ude_form_di spl ayed 6-10
RI Sfrm_i ncl ude_form_di spl ayed 6-10
RI Sfrm_i ni ti al i ze 6-4
RI Sfrm_i ni t_parms data type 6-4
I N - 10 I ndex

RI Sfrm_l ocate_cl i ent_form_di spl ayed 6-10
RI Sfrm_node_i nfo_form_di spl ayed 6-10
RI Sfrm_ri s_dbs_form_di spl ayed 6-10
RI Sfrm_schema_access_form_di spl ayed
6-10
RI Sfrm_schema_defi ni ti on_form_di spl ayed
6-10
RI Sfrm_schema_fi l e_form_di spl ayed 6-10
RI Sfrm_schema_i nfo_form_di spl ayed 6-10
RI Sfrm_schema_mgr_form_di spl ayed 6-10
RI Sfrm_schpass_form_di spl ayed 6-10
RI Sfrm_set_form_di spl ayed 6-10
RI Sfrm_tabl e_i nfo_form_di spl ayed 6-10
RI Sget_ansi _mode 5-13
RI Sget_app_versi on functi on 5-14
RI Sget_async_stmts 5-15
RI Sget_autocommi t_mode 5-17
RI Sget_autorename_mode 5-18
RI Sget_bl ankstri p_mode 5-19
RI Sget_cl i ent_l ocati on 5-20
RI Sget_current_stmt_schema_name 5-22
RI Sget_dbca 5-25
RI Sget_db_i nfo 5-4, 5-23
RI Sget_defaul t_schema_name 5-26
RI Sget_enabl ed_databases 5-27
RI Sget_l anguage_name 5-29
RI Sget_parameters 5-30
RI Sget_ri sca 5-31
RI Sget_ri s_sql type_code 5-44
RI Sget_ri s_sql type_stri ng 5-45
RI Sget_schema_fi l e 5-32
RI Sget_schema_fi l e_l ocati on 5-37
RI Sget_schema_i nfo 5-35
RI Sget_schema_names 5-39
RI Sget_schema_transacti ons 5-42
RI Sget_sql code 5-46
RI Sget_veri fy_mode 5-47
ri s_grantee_i nfo structure 5-6
ri sgui uti l i ty A-12
ri s.h 5-27
ri s_i fx_i nfo structure 5-4
ri s_i gs_i nfo structure 5-4
RI Si ni ti al i ze B-4, 5-48
RI S_LANGUAGE 2-5
ri sl dul d.l i b l i brary 2-6
ri s.l i b l i brary 2-6
ri sl i mi t.h i ncl ude fi l e 5-39
RI Sl i mi ts.h 5-39
RI S_l oader functi ons 7-31
RI Sl ocate_cl i ent 5-49
RI Sl ocate_schema_fi l e 5-51
ri sl od 7-3
i nterfaci ng wi th 7-31
ri sl oddbs structure 7-5, 7-8
i nput fi el ds 7-8
ri sl oddes structure 7-3, 7-5, 7-31
defaul t val ues 7-27
di recti ons for usi ng 7-27
i nput fi el ds 7-6
l oadi ng RI S objects 7-28
output fi el ds 7-7
pri nti ng fi el ds 7-32 7-33
pri nti ng status of 7-28
return i nformati on 7-3
ri sl odgrant structure 7-8, 7-16
i nput fi el ds 7-16
output fi el ds 7-16
ri sl odi ndx structure 7-8, 7-15
ri sl odsch structure 7-5, 7-8
i nput fi el ds 7-8
ri sl odtab structure 7-8, 7-13
defaul t val ues 7-27
ri sl odvi ew structure 7-8, 7-14
RI SNET connecti on B-6
ri s_object A-7
ri s_ora_i nfo structure 5-4
ri s_parameters structure 5-6
ri s_rdb_i nfo structure 5-4
ri srem.l i b D-4
RI Srestore_schema_fi l e_checksum 5-53
ri s_schema_i nfo structure 5-7
ri ssetup.l i b D-3
ri ssetup.l yt D-3
ri ssql ca structure B-4
RI Sstart_cl i ent 5-54
RI Sstop_cl i ent 5-55
RI S_SUCCESS 6-11 6-12
RI Stermi nate B-4, 5-56
RI S_TEXT A-8
ri s_text 3-6
ri sul ddbs structure 7-17
ri sul ddes structure 7-4, 7-17, 7-32
di recti ons for usi ng 7-27
I ndex I N - 11

ri sul ddes structure (continued)
pri nti ng fi el ds 7-33 7-34
return i nformati on 7-4
ri sul dgrant structure 7-19, 7-26
ri sul di ndx structure 7-19, 7-25
ri sul dsch structure 7-17, 7-19
ri sul dtab structure 7-19, 7-23
ri sul dvi ew structure 7-19, 7-24
RI S_unl oader functi ons 7-31
ri sunl od 7-4
i nterfaci ng wi th 7-32
rol l back statement B-7
rows, sel ecti ng 4-30
S
schema
admi ni strator
schema defi ni ti on form 6-3
schema fi l e 5-23, 5-32, 5-35, 5-37 5-39,
5-51 5-53
schema fi l e form 6-3
schema fi l es B-6
schema i nformati on form 6-3
schema manager 6-3
schema manager form 6-3
schema_fi l e_parms 5-6
schemap poi nter 5-35
schemas
addi ng to di cti onary A-6
defi ni ti on i n RI S 5 A-3
di cti onary creati on A-6
droppi ng A-6
mul ti pl e i n databases A-6
mul ti -user A-5
objects of di fferent owners wi thi n A-3
passwords stored for A-5
secure A-5
schemas (continued)
shari ng objects among A-3
usernames stored for A-5
schl i stp poi nter 5-32
secure schema access form 6-3
secure schemas A-5
securi ty A-5
tracki ng, RDBMS A-5
vi ol ati ons, i ncl udi ng data wi thout A-3
sel ect 1-4
sel ect i nto statement B-5, 4-30
sel ect statement A-3, B-7
sel ecti ng rows and col umns 4-30
semaphore sets B-4
sequences, excl ude/i ncl ude A-4
set database statement 5-27
set form 6-3
Set Functi ons 6-9
setti ng veri fy mode B-6
setup fi l es D-3
SetupRI S D-4
SETUPSDK D-3
Shamrock DLL 2-6
shared component D-3
shared component l ocati on D-6
shared component regi stry i nformati on D-7
shared di cti onari es A-6
shared memory segments B-4
short data type 4-8
si gnal s
SI GCLD B-12
usi ng B-12
software changes A-3
software, requi red 2-4
SQL
defi ni ti on 2-3
executi ng stati c statements 4-31
l i brari es 4-6
SQL I nterface 2-24
SQL statement
hi nts B-12
SQL statements
al ter B-7
cl ear B-5
commi t B-7
create B-7
cursor B-5
del ete B-5, B-7
drop B-7
I N - 12 I ndex

SQL statements (continued)
dynami c B-5
excl usi ve B-5
execute i mmedi ate B-5
executi ng B-5
exampl e B-6
i nsert B-5, B-7
l ock tabl es B-4 B-5
managi ng B-5
dynami c B-5
stati c B-5
prepari ng B-5
exampl e B-6
repeti ti ve use of B-5
report error B-4
rol l back B-7
sel ect B-7
sel ect i nto B-5
share B-5
stati c B-5
update B-5, B-7
whenever B-4
sql ca structure 2-9
sql code fi el d 2-9
SQLCODE vari abl e 2-9
sql da structure 4-14
sql da structures 2-19
sql errm fi el d 2-9
sql errmc fi el d 2-9
sql errml fi el d 2-9
sql var structure 4-14 4-15
sql var structures 2-19
statement
decl are schema A-5
sel ect A-3
statements
set database 5-27
statements, executi ng 4-31
stati c cursor statements 2-16
stati c noncursor statements 2-15
stati c statements 2-14
status returns B-3
structured query l anguage 2-3
structures
cl i ent_parms 5-3
dateti me 5-3, 5-8 5-9, 5-11
mi scel l aneous
for RI S functi ons 5-3
ri s_db2_i nfo 5-4
ri s_db_i nfo 5-4
ri s_grantee_i nfo 5-6
structures (continued)
ri s_i fx_i nfo 5-4
ri s_i gs_i nfo 5-4
ri sl oddbs 7-5, 7-8
ri sl oddes 7-3, 7-5, 7-27, 7-31 7-33
ri sl odgrant 7-8, 7-16
ri sl odi ndx 7-8, 7-15
ri sl odsch 7-5, 7-8
ri sl odtab 7-8, 7-13
ri sl odvi ew 7-8, 7-14
ri s_ora_i nfo 5-4
ri s_parameters 5-6
ri s_rdb_i nfo 5-4
ri s_schema_i nfo 5-7
ri ssql ca B-4
ri sul ddbs 7-17
ri sul ddes 7-4, 7-17, 7-32 7-34
ri sul dgrant 7-19, 7-26
ri sul di ndx 7-19, 7-25
ri sul dsch 7-17, 7-19
ri sul dtab 7-19, 7-23
ri sul dvi ew 7-19, 7-24
schema_fi l e_parms 5-6
sql da 4-14
sql var 4-14 4-15
symbol
cauti on 1-5
note 1-5
warni ng 1-5
T
tabl e i nformati on form 6-3
tabl e l ocki ng 2-23
tabl es
creati ng l ogi cal groupi ngs A-3
decl ari ng B-3
prepari ng B-7
temporary B-7
wi th same name A-4
wi th same name i n one schema A-4
termi nati ng B-4
expl i ci t B-4
test compl eti on statement 4-32
text data A-8
text data type 3-3
transacti ons B-7
U
UMS DLL 2-6
UMS l i brary
embedded SQL statements 2-5
I ndex I N - 13

undef statement 4-34
UNI ON A-3
UNI ON ALL A-3
unl oad
defi ni ti on 7-3
update statement B-5, B-7
updati ng l arge data A-8
usernames, stored for schema A-5
usi ng bi nary data 3-3
usi ng cl ause 2-12, 2-19
usi ng i ndexes B-10
usi ng on-l i ne Hel p 1-5
usi ng SQL statement wi sel y B-12
usi ng text data 3-3
uti l i ti es
ri sal pha A-12
ri sgui A-12
V
val ues, dbms_owner A-4
vari abl es
decl ari ng 4-8, 4-19
host 2-11, 4-8, 4-19
vi rtual 4-8, 4-19
veri fy mode B-6
vi ewi ng on-l i ne Hel p 1-5
vi ews
decl ari ng B-3
i ncl udi ng data wi thout A-3
wi th same name A-4
vi rtual vari abl es 4-8, 4-19
W
wai t compl eti on statement 4-35
warni ng symbol 1-5
whenever statement B-4, 2-9, 4-36
WHERE cl ause A-7
ri s_object condi ti on A-7
wi n32api l i brary 2-6
I N - 14 I ndex

Risprogg

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Risprogg

Hochgeladen von

Copyright:

Verfügbare Formate

for 32-Bit Applications

RIS Programmers Guide

Das könnte Ihnen auch gefallen