Risprogg

RIS Programmers Guide
for 32-Bit Applications

August 1996
DNA119040
Version 5.4
Warranties and Liabilities

All warranties given by Intergraph Corporation about equipment or software are set forth in your purchase contract,
and nothing stated in, or implied by, this document or its contents shall be considered or deemed a modification or
amendment of such warranties.
The information and the software discussed in this document are subject to change without notice and should not be
considered commitments by Intergraph Corporation. Intergraph Corporation assumes no responsibility for any
error that may appear in this document.
The software discussed in this document is furnished under a license and may be used or copied only in accordance
with the terms of this license.
No responsibility is assumed by Intergraph for the use or reliability of software on equipment that is not supplied by
Intergraph or its affiliated companies.
Trademarks
InterAct, Intergraph, and RIS are registered trademarks of Intergraph Corporation. DIALOG, InterServe, and TD1
are trademarks of Intergraph Corporation. All other brands and product names are trademarks of their respective
owners.
Copyright
1996 Intergraph Corporation
All Rights Reserved
Including software, file formats, and audiovisual displays; may be used pursuant to applicable software license
agreement; contains confidential and proprietary information of Intergraph and/or third parties which is protected
by copyright and trade secret law and may not be provided or otherwise made available without proper
authorization.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of
The Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c) (1) and
(2) of Commercial Computer Software Restricted Rights at 48 CFR 52.227-19, as applicable.
Unpublished rights reserved under the copyright laws of the United States.
Intergraph Corporation
Huntsville, Alabama 35894-0001
Table of Contents
__________________________________________________________________________________________________________________________________________________
Table of Contents
__________________________________________________________________________________________________________________________________________________
1.
2.
Before You Begin ..................................................................................................
1-3
1.1
1.2
1.3
1.4
Changes to the Software ..............................................................................

Related Documentation ...............................................................................
Document Conventions ................................................................................
Using On-line Help ......................................................................................
1-3
1-3
1-3
1-5
1.4.1
Parts of the Help Window ................................................................
1-5
Creating Applications with RIS ...........................................................................
2-3
2.1
2.2
2.3
2.4
2.5
2.6
2.7
2.8
2.9
Introduction to the RIS Development Platform .........................................

Products Needed to Use the RIS Development Platform ...........................
Changes to the Software ..............................................................................
On-line Help .................................................................................................
Embedded SQL Standard ............................................................................
RIS Preprocessor ..........................................................................................
Error Handling .............................................................................................
Host Variables ..............................................................................................
Categories of Embedded SQL Statements ..................................................
2-3
2-4
2-4
2-4
2-4
2-5
2-9
2 - 11
2 - 14
2.9.1
2.9.2
2.9.3
2.9.4
Static Noncursor SQL Statements ..................................................

Static Cursor SQL Statements ........................................................
Dynamic Noncursor SQL Statements .............................................
Dynamic Cursor SQL Statements ...................................................
2 - 15
2 - 16
2 - 18
2 - 21
Multiple Transactions ................................................................................

Asynchronous Execution of Statements ....................................................
2 - 23
2 - 24
Using Binary and Text Data ................................................................................
3-3
3.1
3.2
RIS_BLOB ....................................................................................................
RIS_TEXT ....................................................................................................
3-3
3-6
Embedded SQL Reference ....................................................................................
4-3
4.1
4.2
4.3
Quick Reference ...........................................................................................

Include Files, Libraries, and Example Programs .......................................
RIS Embedded SQL Statements .................................................................
4-3
4-6
4-6
RIS Functions .......................................................................................................
5-3
2.10
2.11
3.
4.
5.
5.1
5.2
5.3
6.
Reference Structures ....................................................................................

Functions ......................................................................................................
5-3
5-7
5-7
RIS Forms Functions ............................................................................................
6-3
6.1
6.2
6.3
6.4
6.5
6.6
6.7
7.

Initialize Forms Function ............................................................................
Set Functions ...............................................................................................
Displayed Forms Functions .........................................................................
Display Forms Functions .............................................................................
Erase Forms Functions ................................................................................
Forms Functions Error Handling ................................................................
6-3
6-4
6-9
6 - 10
6 - 11
6 - 12
6 - 13
Embedded Loading and Unloading of RIS Objects .............................................
7-3
7.1
7.2
7.3
7.4
Using risloddes for Embedded Loading ......................................................

Using risulddes for Embedded Unloading ..................................................
risloddes Structures .....................................................................................
7-3
7-4
7-4
7-5
7.4.1
7.4.2
risloddbs Structure ...........................................................................

rislodsch Structure ...........................................................................
7-8
7-8
risulddes Structures .....................................................................................
7 - 17
7.5.1
risuldsch Structure ...........................................................................
7 - 19
Directions for Using risloddes and risulddes ..............................................
7 - 27
7.6.1
7.6.2
Directions for Using risloddes ..........................................................

Directions for Using risulddes .........................................................
7 - 27
7 - 29
RIS_loader and RIS_unloader Embedded Functions .................................
7 - 31
7.5
7.6
7.7
Appendix A:
A.1
A.2
A.3
A.4
A.5
A.6
A.7
A.8
A.9
A.10
A.11
A.12
A.13
Changes to This Version of RIS ..........................................................
A-3
RDBMS Versions ...............................................................................................

UNION and UNION ALL Supported ................................................................
Objects of Different Owners Within a Schema .................................................
Object Aliases .....................................................................................................
Multi-User/Secure Schemas ..............................................................................
Shared Dictionaries ...........................................................................................
Dictionary Objects ..............................................................................................
Dictionary Views ................................................................................................
RIS_BLOB/RIS_TEXT .......................................................................................
Interoperability ................................................................................................
Upgrade Utility ................................................................................................
Utilities .............................................................................................................
Parameters .......................................................................................................
A-3
A-3
A-3
A-4
A-5
A-6
A-6
A-7
A-8
A - 11
A - 12
A - 12
A - 12
A.14
Internationalization .........................................................................................
Appendix B:
B.1
B.2
B.3
B.4
B.5
B.6
B.7
B.8
B.9
B.10
B.11
B.12
B.13
B.14
B.15
B.16
A - 13
Programming Notes and Performance Considerations .....................
B-3
Declaring Tables/Views .....................................................................................

Error Handling ...................................................................................................
Initializing and Terminating RIS ......................................................................
Locking ...............................................................................................................
Managing Statements ........................................................................................
Order By Statement ...........................................................................................
Preparing Statements ........................................................................................
RIS Direct versus RISNET Connection ............................................................
Schema Files ......................................................................................................
Set Mode Verify ................................................................................................
Temporary Tables ............................................................................................
Transactions .....................................................................................................
Unique Record Identifiers ................................................................................
Using Indexes ...................................................................................................
Using Signals ...................................................................................................
Using SQL Statements Wisely ........................................................................
B-3
B-3
B-4
B-4
B-5
B-5
B-5
B-6
B-6
B-6
B-7
B-7
B-7
B - 10
B - 12
B - 12
Appendix C:
Language Configuration File ..............................................................
C-3
Appendix D:
Redistribution of RIS Runtime and RIS Utilities ..............................
D-3
Directory Structure ............................................................................................

Setup Files .........................................................................................................
Installing the RIS Shared Component ..............................................................
D-3
D-3
D-5
Glossary .......................................................................................................................
GL - 3
Index ............................................................................................................................
IN - 3
D.1
D.2
D.3
Before You Begin 1 - 1
Before You Begin
__________________________________________________________________________________________________________________________________________________
1-2
Before You Begin
1.
__________________________________________________________________________________________________________________________________________________
Before You Begin

This document gives programmers an overview of how to use RIS in applications and
describes the features supported by RIS. These features include Embedded SQL statements,
functions, and riscpp.
This document is written for applications developers who use the RIS Development Platform
to interact with database systems through Embedded SQL or who want to write their own
database-independent C programs.
1.1 Changes to the Software

If you are currently using an earlier version of RIS, read the section Changes to This Version
of RIS before using RIS 5. Important changes have been made to the software.
1.2 Related Documentation

DNA1116
DNA1117
DNA1151
DNA1003
DNA1009
DNA0016
DNUC074
RIS SQL Users Guide for 32-Bit Applications

RIS Utilities Guide for 32-Bit Applications
RIS Installation Guide for 32-Bit Applications
RIS SQL Commands Quick Reference
RIS Programmers Quick Reference
I/Forms Users Guide
I/Forms Programmers Guide
1.3 Document Conventions

Filenames and directory paths appear in italic typeface. However, the italic typeface is
also used for emphasis of new words or important phrases. For example:
c:\windows
Command names, menu names, tools, system prompts and messages, and keys may
appear in boldface type. For example:
File menu
OR
Press Enter
The word mouse refers to the 2-button or 3-button mouse.
1-4
Before You Begin
The word select means to select a command by pressing the left mouse button over a
menu command or by pressing the Alt key and the underlined character
simultaneously.
The word choose means to choose a button or icon by pressing the left mouse button
over a Toolbar button, or application icon.
The word reset means to terminate a command initiated with the mouse. Reset by
pressing the right mouse button.
The word identify means to define an area or place graphic elements in a graphics file.
For PCs, identify with the left mouse button.
The phrase key in generally means to enter data into a field on a dialog box. To
advance to the next field, use the Tab key.
System key-ins, keywords, and programming code segments, appear in monospaced
type. For example:
main ( )
OR
commit In actual usage, keywords can be in either upper or lowercase.
Words that appear in angle brackets, < >, are identifiers or names that you must
supply, or dynamic information that can change for each error message. For example:
ERROR: Error opening the file <filename>
Phrases in square brackets, [ ], are optional phrases.
Curly braces contain several options (used in conjunction with a logical OR symbol ( | )
or phrases that can be repeated (used in conjunction with [, ...]). A comma followed by a
series of three periods in square brackets ([, ...]) indicates that the last phrase contained
within curly braces ({}), or the last item, can be repeated numerous times (separated by
commas).
For example: { <column> <data type> } [, ...] means that numerous column names and
associated data types can be specified (separated by commas).
The logical or symbol ( | ) separates phrases or keywords within curly braces ({}) that
can be used alone but not together.
For example: { user | database } means that either the user keyword or the
database keyword can be specified, but not both.
This symbol notes important information.
This symbol cautions about operations that can cause limited damage.
This symbol warns about operations that can cause severe damage.
1.4 Using On-line Help

On-line Help is an on-line reference tool accessible at any time the application is in use. The
on-line Help contains a description for each command and tool and step-by-step procedures
for common tasks. For example, if you need to perform a certain task, search and display the
topic. You can move or resize your application and Help windows so that they are next to
each other. This lets you follow the procedures without having to search for the pages in the
documentation.
1-6
Before You Begin
1.4.1 Parts of the Help Window

To view the on-line Help, select Contents from the Help menu. To get more specific
information, select one of the major topics or perform a search on a specific topic.
Use
To
Contents
Display a listing of the table of contents for

the on-line Help file.
Search
Locate information about a certain topic that

you enter in the Search box.
Back
Take you back to the previous Help topics you

have already viewed.
History
Display a sequential list of every Help topic

you have viewed during your current Windows
session.
Find
Display a dialog box used to retrieve partial or

full text strings in the help file. Use the
Hints button for information on constructing
your search query.
<<
View the previous topic in a series of related

topics. The button is dimmed when you reach
the first topic in the series.
>>
View the next topic in a series of related

topics. The button is dimmed when you reach
the last topic in the series.
If the graphics in the on-line Help appear distorted, check your graphics driver.
If you are using an Intergraph TD1 machine, the S3 1024x768 256 color (Large
Font) distorts the graphics slightly. Changing to the (Small Font) version
corrects the display. If you are using other drivers, check with your PC manual
for information about available graphics drivers.
1-8
Before You Begin
Creating Applications with RIS 2 - 1
Creating Applications with RIS
__________________________________________________________________________________________________________________________________________________
2-2
2.
__________________________________________________________________________________________________________________________________________________

2.1 Introduction to the RIS Development Platform
The Intergraph Relational Interface System (RIS) is a generic interface to relational
database management systems (RDBMSs). RIS offers simultaneous connections to RDBMSs
from many vendors on dissimilar hardware platforms using numerous protocols. RIS makes
an entire network of databases available as if there were a single, local database.
RIS is based upon a client/server architecture. The client requests information from the
server. The server then retrieves the information from the database and returns it to the
client.
When you download the RIS Development Platform or any data server, the RIS Client and
RIS Utilities are automatically included as one package.
The RIS Client provides the executable necessary to communicate with the RIS data server,
as well as several other necessary files. The features of the RIS Client are documented in the
RIS SQL Users Guide for 32-Bit Applications.
Several utilities for performing tasks such as schema management, ad hoc queries, and bulk
loading of data are provided by RIS Utilities. The RIS Utilities features are documented in
the RIS Utilities Guide for 32-Bit Applications.
The RIS Development Platform (RISDP) contains an Embedded SQL preprocessor for the C
programming language along with the libraries, include files, and sample programs
necessary for the development of RIS-based applications. The RIS Development Platform
functions and features let you:
Provide the same interface that Intergraph uses to build database-independent
applications.
Embed SQL statements in Microsoft Visual C++ source code. Only standard C code is
acceptable.
Provide a single interface to multiple brands of relational databases.
Provide the remote access built into RIS.
Support numerous network protocols.
Eliminate expensive network products.
2-4
Access IBM/MVS environments.

Provide capabilities across Intergraph, Sun SPARC, and PC platforms.
The RIS interface is based on the American National Standards Institute (ANSI) Structured
Query Language (SQL) standard and is therefore compatible with all RDBMSs that are
compatible with the standard.
2.2 Products Needed to Use the RIS Development Platform

Microsoft Visual C++ 2.0 (or later)
Shamrock (for embedded RIS forms calls) (Win32)
See the RIS Installation Guide for 32-Bit Applications for information on the product
requirements for using the RIS Development Platform.
2.3 Changes to the Software

If you are currently using an earlier version of RIS, read the section Changes to This Version
of RIS before using RIS 5. Several important changes have been made to the software.
2.4 On-line Help

On-line Help is now available for some RIS platforms. For more information see the RIS
Installation Guide for 32-Bit Applications.
2.5 Embedded SQL Standard

RIS uses Embedded SQL as its interface language. The Embedded SQL interface is an ANSI
Standard SQL (X3.135-1989) program interface that permits SQL statements in C language
source code. These statements can directly access program variables to enter and retrieve
data.
The currently adopted SQL standard is deficient in handling dynamic SQL statements
(statements not known until program execution time). Because the proposed revision to the
SQL standard does address these issues, RIS has incorporated some features from the
proposed revision. However, if these features are not adopted as currently proposed, changes
to RIS should conform to the features as they are eventually adopted.
2.6 RIS Preprocessor

To process C source code containing Embedded SQL, run the source code through the RIS
preprocessor riscpp.exe. The environment variable RIS_LANGUAGE specifies the language
that riscpp.exe uses for parsing and error messages. The default language is English. See
the RIS SQL Users Guide for 32-Bit Applications for more information about language
variables.
The RIS Preprocessor provided with the RIS Development Platform is dependent on
Microsoft Visual C++ 2.0 or later and only standard C code is acceptable. You must
load Microsoft Visual C++ and place it in your path before using the preprocessor.
The riscpp.exe preprocessor automatically tries to link with the User Message System (UMS)
library. If the UMS library does not exist, riscpp.exe returns an error. The riscpp.exe
preprocessor also calls the Microsoft Visual C++ compiler to compile and link the program,
unless directed otherwise, and creates an executable.
Files processed by riscpp.exe must end in the suffix .rc (for example, filename.rc). The
preprocessor can be invoked as follows:
riscpp.exe [<flags>] [@command file] <filename>
Flag
_____
Description
___________
-r
Preprocesses the file, but does not compile. The resulting

file has a .c suffix. If you do not specify this option, the .c
file is compiled and then deleted.
-l
Does not place #line directives in the .c file. This makes

the .c file easier to debug.
-I <dir>
Searches for include files in directory <dir>.
-V
Displays the version of RIS.
-ext
Specifies an alternate riscpp.exe file extension. The

default extension is *.rc.
-DWIN32
Required if compiler is called outside riscpp.exe.

Any non-riscpp flags passed to riscpp.exe are further passed on to the compiler.
The riscpp.exe preprocessor returns zero (0) to the shell if the program was processed
successfully and one (1) if unsuccessful. When the -r option is used, the .c file must be
compiled and linked manually.
2-6
Linking Files
The following lists show the order and names of the link files and the products with which
they are associated:
File
_Library/Object
_________________
Description
___________
Users libraries/objects
User created libraries of objects.
<RISDP>\ris.lib
RIS library (required).
<RISDP>\risforms.lib
RIS load/unload library (needed only

when loading/unloading data).
<RISDP>\rislduld.lib
RIS load/unload library (needed only

when loading/unloading data).
<MSVC>\msvcrt.lib
The C runtime library.
<MSVC>\kernel32.lib
Win32api library.
<MSVC>\advapi32.lib
Advanced api library.
<MSVC>\user32.lib
Needed for message boxes.
<SHARE>\i9shamr2.dll
Shamrock DLL, delivered with the

shared component (needed at runtime).
<SHARE>\i9ums2.dll
UMS DLL, delivered with the shared

component (needed at runtime).
The previous table is based on whether the RIS Development Platform product
for 32-bit applications is installed in the directory <RISDP> (the default
directory is c:\Program Files\risdp) and the shared component is installed in
the directory <SHARE> (the default directory is c:\Program Files\Common
Files\Intergraph). The <MSVC> directory is the location of the Microsoft
Visual C++ Tools software (the default directory is c:\msvc20\lib).
The following figure shows the steps taken when processing a 32-bit RIS file.
Examples
Creating an executable .exe file directly from the .rc file:
riscpp.exe -DWIN32 main_app.rc
OR
riscpp.exe -DWIN32 main.rc func1.rc func2.rc -I c:\myapp\include
riscpp.exe preprocesses three files: main.rc, func1.rc, func2.rc. It then produces the
files: main.c, func1.c, and func2.c. The preprocessor invokes the compiler and
automatically compiles the .c files to produce the .obj files. It then invokes the linker to
link the .obj files with the libraries and creates an executable. The -I option directs the
compiler to the directory c:\myapp\include.
Preprocessing the .rc file using riscpp.exe with the -r option:
riscpp.exe -r main_app.rc
After the .c file is generated, compile the .c file and link it with the required libraries
using the Microsoft Visual C++ compiler as follows:
cl -DWIN32 main_app.c
c:\Program Files\risdp\lib\ris.lib
kernel32.lib advapi32.lib user32.lib
2-8
Files
_____
<RISDP>\bin\riscpp.exe
<RISDP>\lib\ris.lib
<RISDP>\include\ris.h
<RISDP>\include\ris_err.h
<RISDP>\include\net_err.h
<RISDP>\include\rislimit.h
<RISDP>\include\ris.prt
<SHARE>\ris<major.minor>\config\english\messages\ris.msg
The major and minor version numbers are determined as follows:
In the product release number 05.01, the major number is 05 and the minor number is 01.
Status
Returns
______________
0
1
Normal termination.
Abnormal termination.
2.7 Error Handling

RIS returns a status code for each statement executed. If a statement generates an error
while the program is running, the global integer variable SQLCODE (uppercase) is set to a
negative value.
Exception handlers are effective for handling errors. RIS provides two devices for
constructing exception handlers.
The whenever clause
Use the whenever clause to define an exception handler to continue, perform a goto, or
define other actions when an error or END_OF_DATA occurs. See the whenever
statement description for more information.
The report error statement can be used to retrieve the message resulting from an error.
For more information, see the report error statement description.
The rissqlca structure
Additional nonstandard error handling capabilities are provided through an sqlca
structure. Although the sqlca structure is not mentioned in either the currently
adopted standard or in the proposed standard, all popular database systems provide
some form of it. Therefore, to give applications more unformatted error information,
RIS provides pointers to two error structures of the type rissqlca.
risca is a pointer to a rissqlca error structure that contains more detailed error
information. Currently, risca gives information only when an error occurs by filling in
the sqlcode and sqlerrm fields with a RIS error code and message. The sqlcode field
always contains the same value as the SQLCODE integer variable.
The rissqlca structure is:
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;
2 - 10
Type
_____
Name
______
Description
___________
char [8]
sqlcaid
SQLCAxxx aid for reading memory dumps.
long
sqlabc
Length (in bytes) of the rissqlca structure.
long
sqlcode
Most recent error code.
char [512]
sqlerrmc
SQL error message corresponding to SQL

code.
short
sqlerrml
Length of the string in the sqlerrmc field.
short
pad
Not used.
char [8]
sqlerrp
Not used.
long [8]
sqlerrd
Internal use only.
char [8]
sqlwarn
SQL Warning Flag.
char [8]
sqlext
Not used.
char *
sqlstmt
Pointer to internal SQL statement buffer.
RIS also provides the pointer dbca that points to a rissqlca structure containing the
error number and message from the underlying DBMS. This structure provides
database-specific error information and can only be accessed through the dbca pointer.
Only the sqlcode and sqlerrm fields are currently supported.
Using the dbca pointer renders your application nonportable because
information contained in the rissqlca structure is specific to a particular
database system and different database systems support different
structure fields. Use the dbca pointer only for informational purposes.
2.8 Host Variables

RIS supports the use of C language host variables within SQL statements. These variables
are passed on to the C compiler. Therefore, they need not be defined anywhere else, but they
must conform to C syntax.
To use host variables, they must:
Be defined (or declared, in the case of an external variable) within an SQL
declarative section.
Conform to C syntax.
Be preceded by a colon (:) when referenced.
The following C data types are supported for host variables:
Integer
2 byte: short
4 byte: int
Floating Point
Single precision: float

Double precision: double
Character
Pointer: char *
String: char[] (NULL terminated by RIS)
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 declared, host variables can be used in the following instances:

Input or output buffers.
Asynchronous statement identifiers.
Insert: values list, select list, or values in the where clause of the select
statement.
Update: assignment expression or values in the where clause.
Delete: values in the where clause.
Select: variables in the into clause, values in the where or having clauses.
2 - 12
Examples
_________
exec sql insert into location (building_name, room_no, location_no)
values (:building_name, :room_no, :location_no);
Host variables cannot be directly referenced from a dynamic SQL string (an SQL statement
not known at compile time). To parameterize a dynamic SQL statement, use a question
mark (?) for the unknown value. The question mark replaces the host variable in the SQL
statement. Later, when the statement is opened or executed, host variables can be bound to
the question mark with the using clause. Dynamic SQL statements are discussed further in
the sections Dynamic Noncursor SQL Statements and Dynamic Cursor SQL Statements.
Indicator Variables
Indicator variables can be used to manage NULL data. These variables are constructed by
following a host variable with the indicator variable (for example, :variable1:indicator1).
Indicator variables are long integers that can optionally be used, with input or output
variables, to indicate if a NULL value is being inserted or retrieved. These variables can also
be checked to see whether data input or output is NULL and are useful in trapping
input/output errors. For example, a host variable used with an indicator variable for data
input would trap NULL data and prevent an attempt to input a NULL value into a column
declared with the not null keywords.
NULL values are indicated as follows:
Value < 0 indicates a NULL
Value >= 0 indicates 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 simple scalar types for host variables, RIS provides a special
variable declaration format to allow complex typing and addressing expressions for host
variables. This format is called a virtual variable declaration. Virtual variable declarations
do not result in any additional C code.
The syntax of the virtual variable declaration is:

virtual <C type> <virtual variable> as <address expression>
Keyword/Identifier
__________________
Description
___________
<virtual variable>
Name to use as a host variable within the SQL statements.

The name is mapped by the preprocessor to the address
expression given in the <address expression> clause. The
virtual variable is essentially a macro for the address
expression.
<C type>
Scalar C language type assigned to the virtual variable. The

preprocessor interprets the virtual variable as being of this
type.
<address
expression>
Address expression for the virtual variable. This clause is

substituted for the virtual variable name whenever it appears
in the Embedded SQL statements. Since this clause is only
used as a string substitution, it is not necessary that the
variables used in the address expression be declared within
the SQL declaration section. However, no checking is done to
ensure that this clause is correct or is of the type specified in
the <C type> identifier. The clause is passed on in the C code.
Examples
_________
The following statements compare the contents of pointer1->array2[5] to column1 when
the SQL statement is executed.
virtual int dummy_var as pointer1->array2[5];
select * from table1 where column1 = :dummy_var;
Incorrect syntax or addressing in the <address expression> clause does not cause the
preprocessor to generate errors, but may cause errors during compilation or at runtime.
In the following section of code, an integer i is declared. In the virtual declaration, the
address expression references i as a pointer to an integer. RIS does not catch this error,
but the C compiler does. The error message is most likely an illegal operation.
int i;
virtual int my_int as *i;
See
Also
________
prepare
2 - 14
2.9 Categories of Embedded SQL Statements

An embedded SQL statement is simply any SQL statement placed directly within C source
code. However, each SQL statement must be prefixed by the keywords exec sql (uppercase or
lowercase) and terminated with the SQL terminator (;).
SQL statements are divided into four categories:
1.
Static statements known at compile time.
2.
Dynamic statements not known until runtime.
3.
Cursor statements all select statements (except the special select into statement).
4.
Noncursor statements all other SQL statements (including the special select into
statement).
2.9.1 Static Noncursor SQL Statements

Static noncursor statements are easy to use. The SQL statement must simply be prefixed by
the SQL prefix and terminated with the SQL terminator.
RIS keeps static, noncursor statements prepared as long as possible and then automatically
clears them. You can set the number of static statements RIS keeps prepared by modifying
the MAX_STATIC_STMTS parameter. For more information on this parameter and other
performance considerations, see the section Programming Notes and Performance
Considerations.
Examples
_________
The following example inserts the values 1 and 2 into col1 and col2 of table1, respectively.
exec sql insert into table1 (col1, col2) values (1, 2);
The following example assigns values to the host variables var1 and var2 and inserts them
into table1.
var1 = 1;
var2 = 2;
exec sql insert into table1 (col1, col2) values (:var1, :var2);
The following example inserts NULL values into col1 and col2 of table1 by using indicator
variables set to a negative number.
ind1 = -1;
ind2 = -1;
exec sql insert into table1 (col1, col2)
values (:var1:ind1, :var2:ind2);
2 - 16
2.9.2 Static Cursor SQL Statements

To use static cursor statements (select statements known at compile time), follow these steps:
1.
Declare a cursor work area for use by the static 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 fetching.
exec sql open <cursor>;
3.
Fetch the information to retrieve one row of results from the cursor. To retrieve
another row of results, issue the fetch statement again. When there are no more result
rows, SQLCODE is set to END_OF_DATA.
loop
exec sql fetch <cursor> into <host variables>;
until END_OF_DATA;
4.
Close the cursor. When a cursor is closed and then reopened, it will be pointing at the
beginning of the data.
exec sql close <cursor>;
5.
Clear the cursor to free all memory used by the static statement and render the cursor
useless. The cursor cannot be reopened once cleared.
exec sql clear cursor <cursor>;
Examples
_________
The following example declares the cursor curs1. When opened, curs1 selects col1 and
col2 from table1. The two columns are then fetched into the host variables result1 and
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 following example declares the cursor curs1. When opened, curs1 selects col1 and
col2 from table1. The two columns are then fetched into the host variables result1 and
result2. The indicator variable is set to a negative value if the column retrieved had a
NULL value in it.
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 - 18
2.9.3 Dynamic Noncursor SQL Statements

RIS provides two ways to use dynamic noncursor statements without input parameters.
Either prepare and then execute the statement, or use the execute immediate statement.
Dynamic noncursor statements with input parameters (specified by a question mark (?) in
the SQL string) require parameter definition for input buffers. The input buffers can be
defined with host variables or with a descriptor. Descriptors permit the number and types of
parameters to be determined at runtime.
Hints:
______
For nonselect statements with no parameters, use execute immediate.
For nonselect statements with parameters, use the prepare and execute statements.
Use host variables if you know the number and types of parameters needed by the
statement.
Use descriptors if the number and types of parameters needed by the statement are
unknown until runtime.
When using host variables in nonselect statements with parameters, these steps are needed:
1.
Prepare the statement.

exec sql prepare <stmt_id> from <host_string>;
2.
Execute the statement using the host variables.

exec sql execute <stmt_id> using <host vars>;
3.
Clear the statement.

exec sql clear <stmt_id>;
When using descriptors, the following steps are needed:

1.

exec sql prepare <stmt_id> from <host_string>;
2.
Describe the SQL descriptor.

exec sql describe input <stmt_id> using descriptor <descriptor>;
3.
Execute the statement using the descriptor.

exec sql execute <stmt_id> using descriptor <descriptor>;
4.
Clear the statement.

exec sql clear <stmt_id>;
Examples
_________
The following examples demonstrate the two ways to dynamically execute an insert
statement. The first way assigns the statement to the character pointer char_ptr,
prepares into statement ID stmt1, executes, and clears. The second way uses the
execute immediate statement 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 following example executes a parameterized insert statement. The values inserted
into the table are specified (in the statement string) using question marks (?). The
using clause in the execute statement substitutes the appropriate host variables var1
and var2 for the two question 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;
2 - 20
The following example executes a noncursor statement that is not known at compilation
time. This statement may or may not have parameters. If it has parameters, allocate a
single sqlda structure and one sqlvar structure for each parameter. These structures
must then be filled with information about the input data buffers being bound to the
parameters. See the statement description and the using clause description for more
information 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 implement a dynamic cursor statement, follow these steps:
1.

exec sql prepare <stmt> from <host select string>;
2.
Describe the SQL descriptor for input.

exec sql describe input <stmt> using descriptor <descriptor>;
3.
Describe the SQL descriptor for output.

exec sql describe output <stmt> using descriptor <descriptor>;
4.
Declare the cursor.

exec sql declare <cursor> for <stmt>;
5.
Open the cursor.

exec sql open <cursor> [using <input information>];
6.
Fetch the information.

loop
exec sql fetch <cursor> [using <output information>];
until END_OF_DATA
7.
Close the cursor.

8.
Clear the cursor.

exec sql clear cursor <cursor>;
The describe, declare, and open statements can be ordered as needed. However, since the
open statement uses input information, all input information must be filled in before this
statement is executed.
Use the describe statement to determine how many sqlda and sqlvar structures are needed
for input or output variables. You must allocate one sqlda for input and one sqlda for output.
Additionally, an sqlvar for each input and output variable must be allocated. For more
information on using the describe statement, see the describe statement description.
2 - 22
Examples
_________
The following example is similar to the previous example for a dynamic noncursor statement.
It differs in that you must allocate and fill in another sqlda structure and a set of sqlvar
structures to define the output buffers for the fetched data. See the describe statement
description and the using clause description for more information.
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 Multiple Transactions

The multiple transactions ability is specified by the MAX_TRANSACTIONS parameter in
the parms file. MAX_TRANSACTIONS specifies the maximum number of statements
executing simultaneously. This limit also specifies the number of asynchronous IDs.
Notes
_ ____
Only one transaction at a time can be in progress for a single schema.
The default value for MAX_TRANSACTIONS is 1.
A new transaction is automatically started each time a new schema is referenced.
The default schema statement can be used to switch between transactions without
affecting their state.
The RISget_schema_transactions function can be used to find the schemas with
transactions in progress.
For more information about multiple transactions, see the section Asynchronous Execution of
Statements.
2 - 24
2.11 Asynchronous Execution of Statements

Formerly, RIS only executed statements synchronously. This meant that each statement
had to execute to completion before control was returned to the application. Now RIS also
supports asynchronous execution of statements. In asynchronous execution, RIS lets
applications start the execution of a statement and then immediately returns control to the
application. The application can then check the status of the statement to determine if it has
completed. A good use of this asynchronous capability is to execute an SQL statement, then,
while that statement is processing, have the application initialize a form or continue other
noncritical processing that does not depend on the outcome of the processing SQL statement.
Notes
_ ____
The interface for asynchronous execution is built around the dynamic SQL interface,
specifically the prepare, execute, declare, open, fetch, and close sequences.
Only one SQL statement can be in progress per schema at any time. If another
asynchronous statement is issued for the same schema, the error The server is already
executing a statement is returned.
If multiple transactions is enabled, statements can be executed in parallel for multiple
schemas.
Test and wait completion can be done for a list of asynchronous identifiers, all
identifiers, any identifier, or using a descriptor.
Test and wait completion statements return one of four conditions:
RIS_SUCCESS
END_OF_DATA
STATEMENT_FAILED
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 RISget_async_stmts function can be used to find all pending asynchronous

statements.
To implement asynchronous processing, follow these steps:

1.
Add the async keyword and a host variable for the asynchronous statement identifier 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.
Determine when the statement completes execution by using a test or wait completion
statement.
exec sql test :async_id completion;
OR
exec sql wait :async_id completion;
3.
Clear the async_id when the statement has completed.

exec sql clear async :async_id;
For more information about multiple transactions, see the section Multiple Transactions.
Examples
_________
The following example executes an insert statement asynchronously.
main()
{
exec sql
int
exec sql
exec sql
begin declare section;

asyncl;
end declare section;
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)
*/
2 - 26
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
Using Binary and Text Data
__________________________________________________________________________________________________________________________________________________
3-2
3.
__________________________________________________________________________________________________________________________________________________

RIS now supports long binary and text data types for use in picture or document storage.
These new data types are RIS_BLOB and RIS_TEXT.
Neither RIS_BLOB nor RIS_TEXT is transportable. Therefore, they cannot be used as
embedded RIS load or unload objects.
To untilize RIS_BLOB and RIS_TEXT data types, the client and server must
both be running at least RIS 5.1.1.
3.1 RIS_BLOB
The RIS_BLOB data type can be used in embedded insert, update, and fetch statements to
manipulate data in a file or character pointer array. It cannot be used in indexing or in
where, order, or group clauses.
The fields of the RIS_BLOB structure are described in the following table. See the ris.h file
for the actual structure declaration.
Data
Type
__________
Name
______
Description
___________
char
*filename
Pointer to the full path for the

filename holding the blob data.
char
*array
Pointer to the character array

holding the blob data.
unsigned int
array_size
Size of the character array.
unsigned int
input_len
Total length of the blob data

inserted. This value is returned
by the server. Use this field only
for insertion.
unsigned int
output_len
Actual length of the blob data

retrieved. This value is returned
for retrieval.
3-4
unsigned int
file_offset
Offset of the file where the blob is

to be appended. Use this field only
for retrieval.
0 = file is to be overwritten.
unsigned char
file_used
1 = a file is to be used.
0 = a character array is to be used.
char
pad[11]
Not used.
The fields in this structure must be set before accessing blob data as input or
output parameters through the sqlvar structure.
Because RIS does not track the data object length, your application must track this length.
Therefore, the array_size field must be sufficiently allocated to hold the entire blob. RIS
makes no attempt to ensure this array is properly allocated.
During an insert, RIS returns an error if the file size is larger than the blob column size.
However, INFORMIX and ORACLE allow the insertion of blob data larger than the specified
blob column size.
During a retrieval, the data is truncated if the array size is smaller than the column size. No
truncation occurs when using a file.
The file_offset field offers a convenient way to fetch multi-blob columns into one file. RIS
appends the blob data to the file by the size specified in the file_offset field. The data is
appended to the end of the file if the file_offset field specifies a length exceeding the current
file size. If the file does not exist, RIS creates the output file and ignores the file_offset field.
To overwrite an existing file, set file_offset to zero.
Examples
_________
#include
#include
#include
#include
<stdio.h>
<fcntl.h>
<errno.h>
"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();
}
3-6
The describe SQL statement does not return the actual length of the blob
column in the sqllen field of the sqlvar structure. RIS sets sqllen to the size of
the ris_blob structure. You must query the ris5columns dictionary table to get
the actual length of the blob column.
3.2 RIS_TEXT
The RIS_TEXT data type can be used in embedded insert, update, and fetch statements to
manipulate data in a file or character pointer array. It cannot be used in indexing or in
where, order, or group clauses.
The fields of the RIS_TEXT structure are described in the following table. See the ris.h file
for the actual structure declaration.
Data
Type
__________
Name
______
Description
___________
char
*filename
Pointer to the full path for the

filename holding the text data.
char
*array
Pointer to the character array

holding the text data.
unsigned int
array_size
Size of the character array.
unsigned int
input_len
Total length of the text data

inserted. This value is returned
for insertion.
unsigned int
output_len
Actual length of the text data

retrieved. This value is returned
for retrieval.
unsigned int
file_offset
Offset of the file where the text is

to be appended. Use this field only
for retrieval.
0 = file is to be overwritten.
unsigned char
file_used
1 = a file is to be used.
0 = a character array is to be used.
char
pad[11]
Not used.
The fields in this structure must be set before accessing text data as input or
accessing output parameters through the sqlvar structure.
Because RIS does not track the data object length, your application must track this length.
Therefore, the array_size field must be sufficiently allocated to hold the entire text file. RIS
makes no attempt to ensure this array is properly allocated.
During an insert, RIS returns an error if the file size is larger than the text column size.
However, INFORMIX and ORACLE allow the insertion of text data larger than the specified
text column size.
During a retrieval, the data is truncated if the array size is smaller than the column size. No
truncation occurs when using a file.
The file_offset field offers a convenient way to fetch multi-text columns into one file. RIS
appends the text data to the file by the size specified in the file_offset field. The data is
appended to the end of the file if the file_offset field specifies a length exceeding the current
file size. If the file does not exist, RIS creates the output file and ignores the file_offset field.
To overwrite an existing file, set file_offset to zero.
Examples
_________
#include
#include
#include
#include
<stdio.h>
<fcntl.h>
<errno.h>
"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));
3-8
/*
** 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 describe SQL statement does not return the actual length of the text
column in the sqllen field of the sqlvar structure. RIS sets sqllen to the size of
the ris_text structure. You must query the ris5columns dictionary table to get
the actual length of the text column.
Dynamic Blob Example

This example can be found in the file blob2.rc.
#include
#include
#include
#include
<stdio.h>
<fcntl.h>
<errno.h>
"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
ris_blob
ris_text
i;
*blobcol;
*textcol;
/*
**
*/
exec sql whenever not found goto :not_found;
3 - 10
/*
** 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)
*/
3 - 12
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;
3 - 14
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
4.
__________________________________________________________________________________________________________________________________________________

This section contains a quick reference and an expanded alphabetical listing of the
Embedded SQL statements supported by RIS. It also lists the include files, libraries, and
example programs for reference when using Embedded SQL. An existing knowledge of the
concepts and the proper usage of an RDBMS is assumed. For more information on the use of
RIS Embedded SQL, see the section Categories of Embedded SQL Statements. For a more
complete description of relational theory and implementation, refer to a textbook and/or user
and reference manuals for the underlying RDBMS. The following quick reference
information can also be found in the RIS SQL Commands Quick Reference card.
Refer to the RIS SQL Users Guide for 32-Bit Applications for a complete listing
of the general SQL statements supported by RIS in both the interactive and
programmatic interfaces.
The notations for syntax used throughout this document are described in the
section Before You 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
declare cursor
exec sql declare <cursor> cursor
for { <select-statement> | <statement-id> };
4-4
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> ];
execute immediate
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-6
4.2 Include Files, Libraries, and Example Programs

The following are SQL include files:
ris_err.h
net_err.h
ris.h
rislimit.h
ris.prt
The SQL library is:
ris.lib
The following are SQL example 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 following alphabetized list gives a detailed description of each Embedded SQL statement
supported by RIS.
async
The async statement executes any RIS SQL statement asynchronously. An async_id
must be associated with 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);
See
Also
________
Asynchronous Execution of Statements
4-8
begin declare
The begin declare statement marks the beginning of the variable declaration section
of the program to the preprocessor. Define and declare all host variables used in SQL
statements within a declaration section. You must terminate a declare section with
the end declare statement.
Examples
_________
struct anystruct sa[10];
int i,j;
char buf[20];
virtual int sa_element as sa[i].element;
begin declare must be specified at the beginning of a block of code before any
executable statements. In the declare section, use only variables in Embedded SQL
statements. Place all other local variables immediately before or after the declare
section.
Notes
_ ____
The RIS preprocessor supports the following C language data types:
int (4 bytes)
short (2 bytes)
float
double
char*
char[ ]
char[ ] is NULL-terminated by RIS if there is enough room in the array.
The RIS preprocessor also supports the following structures:
blob
datetime
sqlda
text
See Also
________
end declare
clear
The clear statement frees all memory for a dynamically prepared statement or a
cursor. The cursor is rendered useless. Once a statement is cleared, it cannot be
used again. Once a cursor has been cleared, it cannot be reopened. Clearing an open
cursor causes the cursor to close and a commit is forced.
exec sql clear { <statement-id> | {cursor <cursor>} };
Examples
_________
exec sql clear cursor c1;
Notes
_ ____
Clearing the statement and clearing the cursor declared for it have the same effect.
It is not necessary to clear both. If an attempt is made to clear both the statement
and the cursor, an error is returned indicating the use of an invalid statement ID.
See
Also
________
close
declare cursor
execute
execute immediate
open
prepare
4 - 10
clear async
The clear async statement frees the additional memory allocated for the
asynchronous ID.
exec sql clear async <:async_id>;
Examples
_________
exec sql clear async :async1;
Notes
_ ____
Clearing async ID is different from clearing a RIS statement. Clearing asynchronous
ID does not clear the RIS statement and vice versa.
close
The close statement closes a cursor. The cursor can be reopened with the open
statement or cleared with the clear statement.
Examples
_________
exec sql close c1;
Notes
_ ____
RIS automatically closes all cursors if a commit or rollback statement is issued or an
error occurs during the execution of any DML statement. In autocommit mode,
closing a cursor causes a commit to occur. This then closes all other cursors.
See
Also
________
clear
declare cursor
fetch
open
4 - 12
declare cursor
The declare cursor statement declares a cursor work area for use by a static or
dynamic select statement.
exec sql declare <cursor> cursor
for { <select-statement> | <statement-id> };
Keyword/Identifier
__________________
Description
___________
<select-statement>
Valid SQL select statement that selects data into the cursor.
Use parameters within the select statement for values in the
where clause or the having clause. For more information, see
the select statement description in the RIS SQL Users Guide.
<statement-id>
Name of a dynamically prepared select statement. For more

information, see the prepare statement.
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 special select into statement.
If the select statement only retrieves one row of data, use the more simple embedded
select into statement instead of the declare, open, and fetch sequence of statements.
See Also
________
clear
close
fetch
open
prepare
select into
define
The define statement assigns a compile-time value to a name. This assignment
occurs during the RIS preprocessing stage. In the statement with a normal C
preprocessor #define.
exec sql define <name> [<integer>];
Examples
_________
exec sql define MAX_ID;
exec sql define MIN_ID 10;
Notes
_ ____
The define statement defines only integer constants. It does not support definition of
string constants or parameterized macros.
See
Also
________
else
endif
ifdef
ifndef
include
undef
4 - 14
describe
The describe statement returns information about the input parameters or the output
results of a dynamic SQL statement. This information is returned in a structure of
type sqlda (defined in the file 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 dynamic SQL statement, you must provide a single sqlda
structure and an array of sqlvar structures (one structure for each input or output
parameter). For example, the following statement needs one sqlda structure for
output and three sqlvar structures for the output variables a, b, and c. The
statement also needs one sqlda structure for input plus one sqlvar structure for the
input variable d.
select a,b,c from t1 where d = ?
For input parameters, the describe statement looks for the question marks in the
value list in the where clause and assignment list in the update statement. For
output parameters, the describe statement looks for the column names in the select
statement.
sqlda Structure
The sqlda structure consists of the following fields:

Data
Type
__________
Field
_____
Description
___________
short
sqln
short
sqld
struct sqlvar
*sqlvar
Number of elements in sqlvar

array. If sqln <= sqld, then RIS
sets the sqld field to the number
of SQL variables. You must
update this field.
Number of SQL variables that
actually exist. If sqln >= sqld,
then this field indicates the
number of SQL variables that
RIS has filled in.
If sqld = 0, a nonselect statement
(insert, update, or delete) was
executed.
Pointer to array of sqlvar
structures, one for each input or
output SQL variable.
sqlvar Structure
The sqlvar structure consists of the following fields:
Data
Type
__________
Field
_____
Description
___________
char
*sqldata
long
*sqlind
short
sqltype
short
sqlnull
short
short
sqllen
sqlscale
see the following table
sqlname
Pointer to the program data

buffer.
Pointer to the program indicator
buffer.
SQL type for the SQL variable:
RIS_BLOB, RIS_CHARACTER,
RIS_DECIMAL, RIS_INTEGER,
RIS_SMALLINT, RIS_REAL,
RIS_DOUBLE, RIS_DATETIME,
RIS_TEXT, RIS_TIMESTAMP.
RIS_UNSUPPORTED_TYPE
identifies unsupported types that
were created outside of RIS.
(These constants are defined in
the ris.h include file).
Set to nonzero if NULLs are
allowed.
Length of the SQL variable.
Precision and scale of a SQL
variable of type DECIMAL.
Name of the SQL variable.
4 - 16
The sqlname field is a nested structure which consists of the following fields:
Data
Type
__________
Field
_____
Description
___________
short
char
sqlnamel
sqlnamec[34]
Length of the name.

Name of the SQL variable not
null terminated.
You can use the describe statement to set up the sqlda and sqlvar structures by
following these steps:
1.
Using malloc, allocate an sqlda structure, but do not fill in the sqld field.
in_sqlda = (sqlda *)malloc(sizeof(sqlda));
out_sqlda = (sqlda *)malloc(sizeof(sqlda));
2.
Issue the describe statement with 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;
RIS sets the sqld field to the number of sqlvar structures needed.
3.
Allocate 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.
Issue the describe statement again.

exec sql describe input my_statement using descriptor in_sqlda;
exec sql describe output my_statement using descriptor out_sqlda;
RIS sets the fields in the sqlvar structures for each of the SQL variables.
If you already know which fields need modifying, skip this step and directly
modify those fields. You can modify the following fields:
sqlnull: set this field to a nonzero value if you want to allow NULL values.
sqlind: if sqlnull is nonzero, set this field to the address of an indicator
variable (long integer). A negative number indicates a NULL value.
sqltype: set this field to a SQL type that is equivalent to the C program
variable type.
sqllen: set this field to the length of the C program variable.

RIS sets sqllen = sizeof(struct ris_blob) for the RIS_BLOB data type and
sqllen = sizeof(struct ris_text) for the RIS_TEXT data type. To determine the
actual size of the RIS_BLOB or RIS_TEXT data type, query the riscolumns
dictionary table. See the section Using Binary and Text Data for more
information about RIS_BLOB and RIS_TEXT data types.
sqldata: set this field to the address of the variable to contain the input or
output value. This variable should be compatible with the type and size
indicated in sqltype and sqllen.
5.
If you have not already, modify the sqldata and sqlind fields in 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 specify the following keywords with the describe statement:
Keyword/Identifier
__________________
Description
___________
output
RIS sets sqltype to the data type, sqllen to the length, and
sqlname to the column name, in the sqlvar structures. You
must set the sqldata and sqlind fields. If the SQL statement
is not a select statement, RIS sets sqld to zero (0).
input
RIS sets sqltype to the expected data type, and sqllen to the
length, in the sqlvar structures. You can use a different type
and length of variable, but this may cause a data conversion
error. Most numeric types are interchangeable, but character
types and numeric types cannot be interchanged.
The value returned in the sqllen field for character columns is the
maximum length of character data. Since C strings are null terminated,
allocate one extra byte to hold the null terminator. Otherwise, the data
may be truncated.
4 - 18
else
The else statement, used with ifdef or ifndef, controls substitution of C code during
the RIS preprocessing stage. If the ifdef or ifndef condition fails, riscpp.exe
substitutes code following the else command with C code for compilation.
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 only one else statement for every ifdef or ifndef statement.
See
Also
________
define
endif
ifdef
ifndef
include
undef
end declare
The end declare statement informs the preprocessor that a variable declaration
section is ending.
See Also
________
begin declare
4 - 20
endif
The endif statement is the required ending for every ifdef or ifndef statement.
exec sql endif;
Examples
_________
exec sql endif;
Notes
_ ____
Use only one endif statement for every ifdef or ifndef statement.
See
Also
________
define
else
ifdef
ifndef
include
undef
execute
The execute statement executes a dynamic noncursor SQL statement against a
database. Use the using clause only if there are input parameters in the prepared
statement. See the describe statement for more information about input parameters.
exec sql execute <statement-id> [ <using clause> ];
Keyword/Identifier
__________________
Description
___________
statement-id
Name of a dynamically prepared select statement. For more

information, see the prepare statement.
using clause
Provides information about input and output buffers. Specify

the variables by using host variable names or by filling in an
sqlda structure with variable information:
using <host variables>
OR
using descriptor <sql descriptor 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 execute statement is valid only on previously prepared statements and must be
used on the same schema used to prepare the statement.
If there are no input parameters, use the execute immediate statement instead.
The execute statement is not valid for dynamic cursor statements. Use the open
statement instead.
See
Also
________
clear
describe
execute immediate
prepare
4 - 22
execute immediate
The execute immediate statement executes a dynamic noncursor SQL statement
against a database. This statement cannot have any input parameters. Use the
prepare and execute statements if input parameters are required. Use the open
statement for dynamic cursor statements.
exec sql execute immediate <string>;
Keyword/Identifier
__________________
Description
___________
<string>
Host variable or string literal.
Examples
_________
exec sql execute immediate :sql_string;
exec sql execute immediate "insert into t1 values (1,2)";
Notes
_ ____
The execute immediate statement is the same as executing the prepare and execute
statements on a dynamic statement without input parameters.
To improve performance of execute immediate statements executed multiple times,
split the statement into the equivalent prepare and execute statements. Next, issue
the prepare statement only once and issue the execute statement multiple times. This
checks the syntactic correctness of the SQL statement only once. For more
information, see the section Preparing Statements.
See
Also
________
clear
execute
prepare
fetch
The fetch statement retrieves one row of results from a cursor select statement.
OR
exec sql fetch <cursor> using <using clause>;
Keyword/Identifier
__________________
Description
___________
<host variables>
Specifies where to place the results of a static select

statement. Specify one or more host variables in the following
form:
{:single_variable[:host_variable] } [, ...]
<using clause>

OR
Examples
_________
fetch c1 into :output1, :output2;
fetch c1 into :output1:ind1, :output2:ind2;
fetch c1 using descriptor out_sqlda;
4 - 24
Notes
_ ____
When retrieving character data (strings), RIS null-terminates the string only if there
is sufficient space in the character data buffer.
RIS automatically closes all cursors if a commit or rollback statement is
issued or an error occurs during the execution of any DML statement.
See Also
________
clear
close
declare cursor
describe
open
ifdef
The ifdef statement controls substitution of C code during the RIS preprocessing
stage. If the ifdef condition succeeds, riscpp.exe substitutes the code between the
ifdef and endif statements with C code for compilation.
exec sql ifdef <name>;
Examples
_________
printf("MAX_ID is defined\n");
exec sql endif;
Notes
_ ____
Every ifdef statement must have a matching endif statement. You can nest the ifdef
statement. You can also have embedded else statements.
See
Also
________
define
else
endif
ifndef
include
undef
4 - 26
ifndef
The ifndef statement controls substitution of C code during the RIS preprocessing
stage. If the ifndef condition succeeds, riscpp.exe substitutes the code between the
ifndef and endif statements with C code for compilation.
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 matching endif statement. You can nest the
ifndef statement. You can also have embedded else statements.
See
Also
________
define
else
endif
ifdef
include
undef
include
The include statement includes a source file at a specified point in the .c file. This
occurs during the RIS preprocessing stage.
If the specified filename does not exist in the local directory, riscpp.exe looks in the
include directory search paths given by the -I option.
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 include statement.
Quotation marks around pathnames are optional.
See
Also
________
define
else
endif
ifdef
ifndef
undef
4 - 28
open
The open statement executes the select statement and sets up a cursor for fetching.
exec sql open <cursor> [ <using clause> ];
Keyword/Identifier
__________________
Description
___________
<using clause>

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 static or dynamic cursor, executing the declared SQL
statement against a database. The open statement is only valid for cursors
previously declared with the declare statement.
RIS automatically closes all cursors if a commit or rollback statement is
issued or an error occurs during the execution of any DML statement.
See Also
________
clear
close
declare cursor
describe
prepare
The prepare statement prepares a dynamic SQL statement for later use. Preparing a
statement checks the statement for proper syntax and initializes the structures to be
used during statement execution.
exec sql prepare <statement-id> from <string>;
Keyword/Identifier
__________________
Description
___________
<statement id>
Name consisting of letters, numbers, and underscores. The

statement IDs scope is limited to the file containing the
prepare statement.
<string>
Character string literal (for example: "a string"), a

character pointer (char *) host variable, or a character array
(char [n]) host variable containing 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 is prepared, it can be executed numerous times. Use the
execute statement to execute it. The same schema used to prepare the statement
must be used to execute the statement.
After a cursor statement is prepared, it must be declared and opened using the
declare and open statements. Once the statement is prepared and declared, it can be
opened numerous times.
Use parameters, designated by a question mark (?), for values in the where clause or
for values in the insert, update, and delete statements.
See
Also
________
clear
execute
execute immediate
4 - 30
report error
The report error statement retrieves the message resulting from the last error. It
returns a pointer to the message buffer in the address specified by the <char_ptr>
identifier. If an asynchronous ID is given then the error message retrieved pertains
to the statement associated with the asynchronous ID.
exec sql report error [for async <:async_id>] into <char_ptr>;
Keyword/Identifier
__________________
Description
___________
<char_ptr>
Pointer set to the address of the message buffer containing

the error message. The buffer is an internal RIS buffer and is
overwritten whenever the report error statement is issued.
Examples
_________
exec sql report error into :ptr;
See
Also
________
whenever
select into
The select into statement is a noncursor version of select. This statement retrieves
one row from a relation in the database. The selection criteria (specified in the where
clause) must match only one row. If more than one match is found, an error is
returned. Executing a select into statement multiple times retrieves the same row
multiple times.
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 select multiple rows from a relation, use a cursor select statement.
Use host variables in the into clause and for values in the where clause or the having
clause.
When retrieving character data (strings), RIS null-terminates the string only if there
is sufficient space in the character data buffer.
If select into statement is executed in autocommit mode, it causes a commit to occur.
This closes all open cursors.
See Also
________
select statement
4 - 32
sql
This statement executes a static SQL statement. The <SQL statement> clause can be
any SQL statement other than the select statement. You must declare, open, and
fetch all select statements using 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 descriptions in the RIS SQL Reference Manual for more
information on the supported SQL statements.
RIS attempts to keep static SQL statements prepared as long as possible. You can
configure the number of static statements RIS keeps prepared in the RIS parameters
file. RIS automatically clears static statements when necessary. For more
information, see the section Preparing Statements.
Host variables can be used in the following Embedded SQL statements:
insert In the values list or in the select list, or values in the where clause of
the select statement.
update In the assignment expressions or for values in the where clause.
delete For values in the where clause.
See
Also
________
execute immediate
test completion
The test completion statement returns the status of a RIS statement being executed
asynchronously. The status can be complete, incomplete, or fail.
exec sql test { <:async1>, <:async2>, ... | all | any | using
The test completion statement can be performed on a specific asynchronous ID, a list
of asynchronous IDs, all the active asynchronous IDs, or by using a descriptor which
can specify a list of asynchronous IDs.
The following is a list of the four possible status states and their descriptions:
Keyword/Identifier
__________________
Description
___________
RIS_SUCCESS
RIS_SUCCESS status returns if the

statement was executed successfully.
SQLCODE is set to RIS_SUCCESS.
END_OF_DATA
END_OF_DATA status is returned while

executing DML statements such as select,
insert, update, or delete if the operation could
not be completed. SQLCODE is set to
END_OF_DATA.
STATEMENT_FAILED
STATEMENT_FAILED status is returned if

the statement fails. SQLCODE is set to
STATEMENT_FAILED.
STATEMENT_NOT_COMPLETE
STATEMENT_NOT_COMPLETE status is
returned if RIS is still processing the
statement. SQLCODE is set to
STATEMENT_NOT_COMPLETE.
The first three states are referred to as complete states while the fourth state is
referred to as an incomplete state.
These options give the application the flexibility to test for specific asynchronous IDs.
The status returned depends upon the option specified.
If one of the statements in the list of asynchronous IDs is incomplete, the test
completion statement returns STATEMENT_NOT_COMPLETE status. If all the
statements are successfully completed (that is RIS_SUCCESS state only), it returns
RIS_SUCCESS. The following is the precedence of status returned:
STATEMENT_NOT_COMPLETE ( highest priority )
STATEMENT_FAILED
END_OF_DATA
RIS_SUCCESS ( lowest priority )
4 - 34
The any clause returns the status of the first statement found in a complete state
(RIS_SUCCESS, END_OF_DATA, or STATEMENT_FAILED). Otherwise it returns
STATEMENT_NOT_COMPLETE. The remaining statements must be tested or an
error is 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
_ ____
Executing test completion on an asynchronous statement that was already
successfully completed (in any one of the complete states), returns the error An
asynchronous statement has not been specified.
undef
The undef statement removes a defined name. This occurs during the RIS
preprocessing stage. In the .c file, riscpp.exe substitutes the undef statement with a
normal C preprocessor #undef.
exec sql undef <name>;
Examples
_________
exec sql undef MAX_ID;
See
Also
________
define
else
endif
ifdef
ifndef
include
4 - 36
wait completion
The wait completion statement waits for the completion of the asynchronous
statements.
exec sql wait { <:async1>, <:async2>, ...| all | any | using
The wait completion statement ID is identical to the test completion statement except
that there is 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
_ ____
Follow the information given for the test completion statement. The same conditions
apply for wait completion.
See Also
________
test completion
whenever
The whenever statement declares an exception (error) handler or an action to perform
when an exception occurs.
exec sql whenever { not found | sqlerror }
{ continue | goto <C label> | go to <C label> };
Keyword/Identifier
__________________
Description
___________
sqlerror
Action to occur after an error occurs. sqlcode is set to a

negative value.
not found
Action to occur when there are no more rows to fetch. sqlcode

is set to END_OF_DATA.
continue
Ignore error and continue processing. This is not equivalent

to the C language continue statement.
goto
Equivalent to the C language goto statement.
Examples
_________
exec sql whenever sqlerror goto:error_label;
exec sql whenever not found goto:end_of_data;
Notes
_ ____
The RIS preprocessor determines the scope of a whenever statement linearly at
compile time. The scope is a function of the statements position in the source file
only.
Use caution when handling an error. Executing a clear statement or close
statement after an error has occurred may generate further errors. If a new
whenever statement has not been executed, an infinite loop may result.
See Also
________
report error
4 - 38
RIS Functions 5 - 1
RIS Functions
__________________________________________________________________________________________________________________________________________________
5-2
RIS Functions
RIS Functions 5 - 3
5.
__________________________________________________________________________________________________________________________________________________
RIS Functions
This section contains an alphabetical listing of functions supported by RIS. It also provides
reference structures to use with these functions, and a list of the include files, libraries, and
example programs needed when using RIS functions.
5.1 Reference Structures

Refer to the following structures when using RIS functions:
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;
5-4
RIS Functions
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 the ris_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;
RIS Functions 5 - 5
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;
5-6
RIS Functions
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 Functions 5 - 7
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 following are include files for RIS functions:
ris_err.h
rislimit.h
net_err.h
rap.prt
ris.prt
ris.h
The library for RIS functions is:

ris.lib
The functions example programs are in the \risdp\disk1 directory of the RIS Development
Platform. This directory contains the following example 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 details about using these example programs, see the readme.spl file in the \risdp\disk1
directory.
5.3 Functions
The following reference section provides detailed descriptions of each RIS function.
5-8
RIS Functions
RISascii_to_datetime
RISascii_to_datetime converts an ASCII string to a datetime structure. It accepts an
ASCII buffer as input and fills in a datetime structure format. Format is interpreted
in the same way as in RISdatetime_to_ascii.
char * RISascii_to_datetime( datetime *date,
char *buffer,
char *format );
Keyword/Identifier
__________________
Description
___________
date
Pointer to datetime structure filled in by

RISascii_to_datetime.
buffer
Character string representing a datetime value.
format
Character string describing the format of the datetime string

in the buffer.
Examples
_________
See examples for RISdatetime_to_ascii.
Status Returns
______________
Success
Failure
See Also
________
RISdatetime_to_ascii
0
Pointer to an error string
RIS Functions 5 - 9
RISdatetime_to_ascii
RISdatetime_to_ascii accepts a datetime structure as input and generates a nullterminated ASCII string in buffer-based format.
int RISdatetime_to_ascii( datetime *date,
char *buffer,
char *format );
Keyword/Identifier
__________________
Description
___________
date
Pointer to a datetime structure containing a datetime value.

See the Notes section on this function for more information.
buffer
Pointer to a character buffer where datetime structure is

generated.
format
Pointer to a character string that specifies the datetime

structures format. See the Notes section on this function for
more information.
Examples
_________
Assume the datetime structure contains the following:
date.year = 1990
date.month = 12
date.day = 5
date.hour = 10
date.minute = 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
format = "Dy, Mon d yyyy"
buffer = "Wed, Dec 5 1990"
1990"
5 - 10
RIS Functions
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
Failure
0
Non-zero value
RIS Functions 5 - 11
Notes
_ ____
The datetime structure is defined as follows:
typedef struct datetime
{
unsigned int
unsigned int
unsigned int
unsigned int
unsigned int
unsigned int
} datetime;
second;
minute;
hour;
day;
month;
year;
The format is interpreted as follows:

ASCII string
____________
Unit
_____
Format
_______
Padding
________
yyyy
Year
Four digits.
Leading zeros.
yy
Year
Last two digits.
Leading zeros.
Year
One to four digits.
None.
mm
Month
Two digits.
Leading zeros.
Month
One or two digits.
No padding.
month
Name of month
One to nine characters.
None.
mon
Name of month
Three character
abbreviation.
None.
ddd
Day of year
One to three digits.
None.
dd
Day of month
Two digits.
Leading zeros.
Day of month
One to two digits.
None.
day
Day of week
name
One to nine characters.
None.
dy
Day of week
name
Three character
abbreviation.
None.
hh24
24 hour mode
Two digits.
Leading zeros.
h24
24 hour mode
One to two digits.
None.
h12 or hh
12 hour mode
Two digits.
Leading zeros.
5 - 12
RIS Functions
h12 or h
12 hour mode
One to two digits.
None.
nn
Minute
Two digits.
Leading zeros.
Minute
One to two digits.
None.
ss
Second
Two digits.
Leading zeros.
Second
One to two digits.
None.
am or pm
Meridian
indicator
Two characters.
None.
ASCII
string
____________
Unit
_____
Format
_______
Padding
________
a.m. or p.m.
Meridian
indicator with
periods
Four characters.
None.
text
Single
quotation
string
Reproduced in destination
string.
None.
Single
quotation
string.
None.
default
Any other
character
string.
None.
Capitalization in a word or abbreviation follows capitalization in the

corresponding format element.
RISdatetime_to_ascii assumes buffer is large enough to hold the
resulting string. No size checking is performed.
See
Also
________
RISascii_to_datetime
RISget_ansi_mode
RISget_ansi_mode checks if ANSI mode flag is on or off. If it is on, ANSI mode is set
to one. Otherwise, it is zero. If ANSI mode is on, RIS restricts user-supplied names
for schemas, tables, columns, views, and indexes to a maximum of 18 characters
while they are created. If ANSI mode is off, the RIS limit is extended to 31
characters. ANSI mode is set using the set mode statement.
void RISget_ansi_mode( int *ansi_mode );
Keyword/Identifier
__________________
Description
___________
ansi_mode
Pointer to integer representing ansi_mode flag.

1 = ANSI mode on.
0 = ANSI mode off.
Default is 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
Failure
SQLCODE = RIS_SUCCESS
SQLCODE = Error number
If RIS client process has terminated, an
RIS_E_CLIENT_DEAD error is returned.
Notes
_ ____
Not every DBMS can handle names longer than 18 characters.
5 - 14
RIS Functions
RISget_app_version
RISget_app_version gets the current version of RIS. The pointer arguments: maj,
min, and rel are set by RIS.
void RISget_app_version( int *maj,
int *min,
int *rel );
Keyword/Identifier
__________________
Description
___________
maj
Pointer to integer representing major number of the version.
min
Pointer to integer representing minor number of the version.
rel
Pointer to integer representing release number of the version.
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
______________
Success
Failure
RISget_async_stmts
RISget_async_stmts gets the number of asynchronous statements and their IDs. The
buffer is an array of asynchronous IDs. To determine the size of the buffer, call
RISget_async_stmts with *countp equal to zero. On input, *countp sets the number of
async IDs to return. On output, *countp contains the number of async IDs that exist.
You can call RISget_async_stmts a second time with *countp set to the number of
async IDs. This retrieves the async IDs.
void RISget_async_stmts( int *buffer,
int *countp );
Keyword/Identifier
__________________
Description
___________
buffer
Pointer to an integer containing the asynchronous IDs.
countp
Pointer to an integer containing the number of asynchronous

IDs.
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;
5 - 16
RIS Functions
/*
** 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
RISget_autocommit_mode checks if autocommit mode is on or off. If it is on,
autocommit is set to one. Otherwise, it is zero. When autocommit is on, data
manipulation statements such as select, insert, update, and delete are automatically
committed. The set transaction statement sets the transaction state.
void RISget_autocommit_mode( int *autocommit );
Keyword/Identifier
__________________
Description
___________
autocommit
Pointer to integer representing autocommit flag.

1 = autocommit on.
0 = autocommit off.
Default is 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
______________
Success
Failure
5 - 18
RIS Functions
RISget_autorename_mode
RISget_autorename_mode checks if the autorename mode is on or off. If it is on,
autorename is set to one and RIS regenerates the column and table names (greater
than the ten characters) originally supplied by the user. If it is off, autorename is set
to zero and RIS will not regenerate column and table names. The autorename mode
is set using the set mode statement.
void RISget_autorename_mode( int *autorename );
Keyword/Identifier
__________________
Description
___________
autorename
Pointer to an integer representing the autorename mode flag.

1 = On.
0 = Off.
Default is 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
______________
Success
Failure
RISget_blankstrip_mode
RISget_blankstrip_mode checks if the blankstrip mode is on or off. If it is on,
blankstrip_mode is set to one and RIS strips trailing blanks from character data. If it
is off, blankstrip_mode is set to zero and RIS does not strip trailing blanks. The
blankstrip mode is set using the set mode statement.
void RISget_blankstrip_mode( int *blankstrip_mode );
Keyword/Identifier
__________________
Description
___________
blankstrip_mode
Pointer to an integer representing the blankstrip mode flag.

1 = On.
0 = Off.
Default is 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
______________
Success
Failure
5 - 20
RIS Functions
RISget_client_location
RISget_client_location retrieves the location of the RIS client process specified in the
parameters file.
void RISget_client_location( client_parms *parms );
Keyword/Identifier
__________________
Description
___________
parms
Pointer to client_parms structure that specifies the location of

the RIS client process. See the section Reference Structures
for detailed information about this 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
______________
Success
Failure
Notes
_ ____
The protocol field in the client_parms structure specifies the protocol interacting with
the node where the RIS client process resides. The protocols and their corresponding
codes are:
Protocol
Code
xns
tcp/ip
decnet
memory(local)
X
T
D
M
The address field specifies the address of the node. The protocols and their
corresponding address formats are:
Protocol
Code
xns
tcp/ip
decnet
memory(local)
name or XXXXXXXX.XX-XX-XX-XX-XX-XX
name or XXX.XXX.XXX.XXX
name or XX.XXXX
INVALID
Use the major field in the client_parms structure to specify the major version of the
client and the feature field to specify the feature version of the client. The major
version of the client should be greater than or equal to the major version of the
application.
The major client version default and the feature client default is zero. Use these
defaults when the client version is the same as the application version.
RIS for Windows NT currently supports only the TCP/IP protocol.
5 - 22
RIS Functions
RISget_current_stmt_schema_name
RISget_current_stmt_schema_name retrieves the schema name associated with the
last RIS statement executed but not cleared. The buffer is an array of character
strings of size RIS_MAX_ID_SIZE, defined in the rislimit.h include file, with the
schema name.
void RISget_current_stmt_schema_name( char (buffer) [RIS_MAX_ID_SIZE] );
Keyword/Identifier
__________________
Description
___________
buffer
Pointer to a character buffer used to retrieve 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
______________
Success
Failure
RISget_db_info
RISget_db_info gets database information from the RIS schema file. It takes a
database ID as input and places this database information into the ris_db_info
structure. The dbp pointer points to this structure. If dbp is nonzero, the structures
are allocated automatically through malloc. Otherwise, the structure is not
allocated. You must free the structures after use by calling free.
void RISget_db_info( int dbid,
ris_db_info **dbp );
Keyword/Identifier
__________________
Description
___________
dbid
Database ID of a database structure in the schema file.
dbp
Address of the pointer to the ris_db_info structure. For more

information on this and related structures, see the section
Reference Structures.
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);
}
5 - 24
RIS Functions
Sample 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
______________
Success
Failure
If RIS client process has terminated, a
RIS_E_CLIENT_DEAD error is returned. If database is not
found, a RISapp_UNKNOWN_DB error is returned.
RISget_dbca
RISget_dbca returns a pointer to the risca variable (rissqla structure) containing a
copy of the vendor databases sqlca structure. For more information, see the section
Error Handling.
rissqla *RISget_dbca( void );
Keyword/Identifier
__________________
Description
___________
dbca
Structure of type rissqlca to hold error information.
Examples
_________
main()
{
rissqlca *DBCA;
if(RISget_sqlcode() != RIS_SUCCESS)
{
DBCA = RISget_dbca();
printf("Database SQLCODE = %d\n", DBCA -> sqlcode);
}
}
Status Returns
______________
Success
Failure
5 - 26
RIS Functions
RISget_default_schema_name
RISget_default_schema_name returns the current default schema name into the
buffer variable.
void RISget_default_schema_name( char (buffer) [RIS_MAX_ID_SIZE] );
Keyword/Identifier
__________________
Description
___________
buffer
Pointer to a character buffer to retrieve default 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
RISget_enabled_databases determines which RIS-supported DBMSs are enabled. If
all the databases are enabled, the bit mask RIS_ENABLE_ALL is set in
enable_dbms. If only some of the databases are enabled, the bit masks corresponding
to the enabled databases are set in enable_dbms. These bit masks are defined in
ris.h. The ris.h include file also defines macros. These macros return zero or one if
the appropriate bit is set in the bit mask. The macro names are
IS_XXX_ENABLED(mask) where XXX is the DBMS name in uppercase. For
example, IS_INFORMIX_ENABLED is the integer bit mask variable.
The set database statement specifies the types of underlying databases you can use.
This causes verification of user-supplied names against the reserved words of the
specified databases.
void RISget_enabled_databases( int *enable_dbms );
Keyword/Identifier
__________________
Description
___________
enable_dbms
Pointer to an integer with bits representing enabled

databases.
Examples
_________
main()
{
int enable_dbms;
RISget_enabled_databases(&enable_dbms);
if (IS_INFORMIX_ENABLED(enable_dbms))
printf("Informix database is enabled\n");
}
The following figure represents the integer to which enable_dbms points. The bit
masks in this graphic match those in ris.h.
5 - 28
RIS Functions
enable_dbms Bit Masks as Defined in ris.h

Status
Returns
______________
Success
Failure
RISget_language_name
RISget_language_name retrieves the language name currently set by RIS. The RISsupported languages are listed in the RIS language configuration file. See the
section Language Configuration File in the RIS SQL Users Guide for 32-Bit
Applications for more information about selecting languages.
RISget_language_name( char *name );
Keyword/Identifier
__________________
Description
___________
name
Pointer to a character buffer that holds the language string of

size RIS_MAX_LANGNAME_SIZE.
Examples
_________
main()
{
char language [RIS_MAX_LANGNAME_SIZE];
RISinitialize("english");
RISget_language_name(language);
printf("Language is set to %s\n", language);
}
Status Returns
______________
Success
Failure
Notes
_ ____
If RIS is not initialized, the input variable is set to the null string.
5 - 30
RIS Functions
RISget_parameters
RISget_parameters retrieves the RIS parameters currently set by RIS. The
parameters pointer points to the RIS parameter information structure.
void RISget_parameters( ris_parameters *parameters );
Keyword/Identifier
__________________
Description
___________
parameters
Pointer to ris_parameter structure used to receive parameters

information. See the section Reference Structures for detailed
information about this 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
______________
Success
Failure
Notes
_ ____
Each field corresponds to a field specified in the parameters file.
RISget_risca
RISget_risca returns a pointer to the risca variable (rissqla structure), which
provides consistent error and other information regardless of the database system.
For detailed information on the risca variable, see the section Error Handling.
rissqla *RISget_risca( void );
Keyword/Identifier
__________________
Description
___________
risca
Structure of type rissqlca to hold error information.
Examples
_________
main()
{
rissqlca *RISCA;
if(RISget_sqlcode()!= RIS_SUCCESS)
{
RISCA = RISget_risca();
printf("SQLCODE=%d\n", RISCA -> sqlcode);
}
}
Status Returns
______________
Success
Failure
5 - 32
RIS Functions
RISget_schema_file
RISget_schema_file retrieves schema filename, schema, database, and grantee
information from the RIS schema file. It returns a list of information about every
schema filename, database, schema, and grantee using the schema_filenamep,
dblistp, schlistp, and granteep pointers. The structures related to these pointers are
automatically allocated through malloc. However, you must deallocate them after
use by calling free. If any of the parameters are zero, the corresponding structures
are not allocated.
void RISget_schema_file( char **schema_filenamep
ris_db_info **dblistp,
ris_schema_info **schlistp,
ris_grantee_info **granteep );
Keyword/Identifier
__________________
Description
___________
schema_filenamep
Address of schema_filenamep to receive schema filename.
dblistp
Address of ris_db_info pointer, which is a structure for

receiving database information. See the section Reference
Structures for detailed information about this structure.
schlistp
Address of ris_schema_info pointer, which is a structure for

receiving schema information. See the section Reference
granteep
Address of ris_grantee_info pointer, which is a structure for

receiving grantee information. See the section 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;
}
}
Sample
Output:
______________
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>
5 - 34
RIS Functions
Status
Returns
______________
Success
Failure
If RIS client process has terminated, a
RISget_schema_info
RISget_schema_info accepts a schema name as input and retrieves the schema
information, database information, and grantee information corresponding to
schname from the schema file. The schemap, dbp, and granteep pointers point to
schema information, database information, and a list of accessible grantees.
If schemap, dbp, or granteep is nonzero, the structure is allocated through malloc and
information is filled into its fields. If any of the parameters is zero, the structure is
not allocated. After usage, you must deallocate the structures by calling free.
void RISget_schema_info( char *schname,
ris_schema_info **schemap,
ris_db_info **dbp,
ris_grantee_info **granteep );
Keyword/Identifier
__________________
Description
___________
schname
Schema name.
schemap
Address of ris_schema_info pointer, which is a structure for

receiving schema information. See the section Reference
dbp
Address of ris_db_info pointer, which is a structure for

receiving database information. See the section Reference
granteep
Address of ris_grantee_info pointer, which is a structure for

receiving grantee information. See the section 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)
{
5 - 36
RIS Functions
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
______________
Success
Failure
If RIS client process has terminated, RIS_E_CLIENT_DEAD
error is returned. If schema is not found,
RISapp_UNKNOWN_SCHEMA is returned.
RISget_schema_file_location
RISget_schema_file_location retrieves the location of the RIS schema file specified in
the parameters file. The default location is in the directory where the RISCLI
product is installed.
void RISget_schema_file_location( schema_file_parms *parms );
Keyword/Identifier
__________________
Description
___________
parms
Pointer to a schema_file_parms structure, specifying the

location of the RIS schema file. See the section 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
______________
Success
Failure
Notes
_ ____
The protocol field in the schema_file_parms structure specifies the protocol
interacting with the node where the RIS schema file resides. The protocols and their
corresponding codes are:
Protocol
Code
tcp/ip
memory(local)
T
M
Protocol
Code
tcp/ip
memory(local)
INVALID
5 - 38
RIS Functions

RISget_schema_file_location does not use the password field. The username field
specifies a valid username on the node. The filename field specifies the name of the
RIS schema file.
In RIS for Windows NT, if the filename does not specify a path, then the RIS schema
file is assumed to be on the node where the RIS shared component resides, in the
\Program Files\Common Files\Intergraph\ris05.xx directory.
RISget_schema_names
RISget_schema_names retrieves the list of schema names from the RIS schema file.
RISget_schema_names reads the RIS schema file and fills in the buffer. The buffer is
an array of character strings of size RIS_MAX_ID_SIZE, defined in the rislimit.h
include file, with the names of the schemas defined in the schema file.
To determine the size of the buffer, call RISget_schema_names with *countp equal to
zero. On input, *countp sets the number of schema names to return. On output,
*countp contains the number of schemas that exist. You can then call
RISget_schema_names a second time with *countp set to the number of schema
names. This retrieves the schema names.
void RISget_schema_names( char (*buffer)[RIS_MAX_ID_SIZE],
int *countp );
Keyword/Identifier
__________________
Description
___________
buffer
Pointer to a character array containing the schema names.
countp
Pointer to integer containing 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);
5 - 40
RIS Functions
/*
** Retrieve the schema names
*/
{
printf("%s", ptr);
return SQLCODE;
}
/*
*/
for (i = 0; i < count; i++)
printf("buffer[%d]:<%s>\n", i, buffer[i]);
}
Using the following typedef can simplify the declaration and malloc of the schema
name array.
typedef char risschema_name[RIS_MAX_ID_SIZE];
The following example is the same as the previous example, except that it 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;
}
/*
**
*/
Allocate the space to hold the schema names

buffer = (risschema_name *)malloc(count * sizeof(risschema_name));
/*
**
*/
Retrieve the schema names

{
printf("%s", ptr);
return SQLCODE;
}
/*
**
*/
Output the results

for (i = 0; i < count; i++)
}
Status
Returns
______________
Success
Failure
If *countp is less than the number of schema names,
SQLCODE is set to RIS_E_NOT_ENOUGH_SPACE.
5 - 42
RIS Functions
RISget_schema_transactions
RISget_schema_transactions gets the number and names of schemas involved in the
uncommitted transactions. The buffer is an array of character strings of size
RIS_MAX_ID_SIZE, defined in the rislimit.h include file, with the names of the
schemas.
To determine the size of the buffer, call RISget_schema_transactions with *countp
equal to zero. On input, *countp sets the number of schema names to return. On
output, *countp contains the number of schemas that exist. You can call
RISget_schema_transactions a second time with *countp set to the number of schema
names to retrieve the schema names currently in transaction.
void RISget_schema_transactions( char (*buffer)[RIS_MAX_ID_SIZE],
int *countp );
Keyword/Identifier
__________________
Description
___________
buffer
Pointer to a character array containing

the schema names.
countp
Pointer to integer containing 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;
}
/*
** Allocate the space to hold the schema names
*/
buffer = (char (*)[RIS_MAX_ID_SIZE])malloc(count * RIS_MAX_ID_SIZE);
/*
** Retrieve the schema names
*/
RISget_schema_transactions(buffer, &count);
{
return SQLCODE;
}
/*
*/
for(i = 0; i < count; i++)
{
}
exec sql commit;
exec sql default schema
exec sql commit;
stwo;
not_found:
printf("No more data");
exit();
error:
puts(err_ptr);
exit();
}
Status Returns
______________
Success
Failure
If *countp is less than the number of schema
names, SQLCODE is set to RIS_E_NOT_ENOUGH_SPACE.
5 - 44
RIS Functions
RISget_ris_sqltype_code
RISget_ris_sqltype_code retrieves the RIS SQL data type code for a given RIS SQL
data type string. The RIS data type codes and their corresponding strings are listed
in the ris.h file.
void RISget_ris_sqltype_code( int *code,
char *str );
Keyword/Identifier
__________________
Description
___________
code
Pointer to integer type to hold RIS SQL data type code.
str
Pointer to character string to pass RIS SQL data type string.
Examples
_________
main()
{
int code;
RISget_ris_sqltype_code (&code,"int");
}
Status Returns
______________
Success
Failure
RISget_ris_sqltype_string
RISget_ris_sqltype_string retrieves the RIS SQL data type string for a given RIS SQL
data type code. All data types are listed in the ris.h file.
void RISget_ris_sqltype_string( char *str,
int *code );
Keyword/Identifier
__________________
Description
___________
str
Pointer to character string to retrieve RIS SQL data type

string.
code
Integer variable indicating RIS SQL data type code.
Examples
_________
main()
{
char str[RIS_MAX_ID_SIZE]
RISget_ris_sqltype_string(str, 2);
}
Status Returns
______________
Success
Failure
5 - 46
RIS Functions
RISget_sqlcode
RISget_sqlcode returns the last RIS error code (sqlcode). The sqlcode returned is the
most recent error code set by the previous RIS SQL statement or function call.
An application should call this function immediately after a RIS SQL statement or
RIS function call to determine the success or failure of that statement or call.
The error codes are integer size values. An sqlcode of RIS_SUCCESS (value 0)
indicates a success. Any negative value indicates a failure.
int RISget_sqlcode( void );
Examples
_________
main()
{
if(RISget_sqlcode != RIS_SUCCESS)
{
printf("Default schema failed.\n");
}
}
Status Returns
______________
Success
Failure
RISget_verify_mode
RISget_verify_mode checks to see if the verify mode switch is on or off. If it is on,
verify_mode is set to one and the table and view definitions are retrieved from the
underlying database and validated against definitions stored in the RIS dictionary
tables. If it is off, verify_mode is set to zero and the validation phase is omitted. The
validation phase ensures consistency between the RIS dictionary tables and the
underlying database. The verify_mode is set using the set mode statement.
void RISget_verify_mode( int *verify_mode );
Keyword/Identifier
__________________
Description
___________
verify_mode
Pointer to integer representing verify mode flag.

1 = On.
0 = Off.
Default is 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
______________
Success
Failure
5 - 48
RIS Functions
RISinitialize
RISinitialize initializes the RIS system in the following order:
1.
Initializes the language file based on the language value passed through the
language_name variable. If NULL is passed as the language, RIS uses english
as the default language. The valid languages currently supported by RIS are
listed in the RIS language configuration file. See the section Language
Configuration File in the RIS SQL Users Guide for 32-Bit Applications for more
information about selecting languages.
2.
Reads the parameters file and configures RIS according to the parameter
specifications.
3.
Allocates the necessary global memory to run RIS.
Calling RISinitialize is optional. The first RIS statement executed automatically

invokes RISinitialize with the default language set to the language Windows NT is
using. Thus, if Windows NT is set to German, the default language is set to German.
void RISinitialize( char *language_name );
Keyword/Identifier
__________________
Description
___________
language_name
Pointer to the character string representing the language

name to be used by RIS.
Examples
_________
main()
{
RISinitialize(NULL);
if(SQLCODE != RIS_SUCCESS)
{
printf("Could not initialize\n");
}
}
Status Returns
______________
Success
Failure
RISlocate_client
RISlocate_client stores the location of the RIS client executable in the parameters
file.
void RISlocate_client( client_parms *parms );
Keyword/Identifier
__________________
Description
___________
parms
Pointer to client_parms structure, specifying the location of

the RIS client process. See the section Reference Structures
for detailed information about this 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
______________
Success
Failure
Notes
_ ____
The protocol field in client_parms structure specifies the protocol interacting with the
node where the RIS client executable resides. The protocols and their corresponding
codes are:
Protocol
Code
xns
tcp/ip
decnet
memory (local)
X
T
D
M
Use the memory protocol when the RIS client resides on the local machine.
5 - 50
RIS Functions
Protocol
Code
xns
tcp/ip
decnet
memory (local)
name or XX.XXXX
invalid
It is invalid to specify an address with the memory protocol. Use the username field
to specify a valid username on the node. It is invalid to specify a user with the
memory protocol. If the username specified requires a password, specify it in the
password field.
Use the major field in the client_parms structure to specify the major version of the
client and the feature field to specify the feature version of the client. The major
version of the client should be greater than or equal to the major version of the
application.
The major client version default and the feature client default is zero. Use these
defaults when the client version is the same as the application version.
RISlocate_schema_file
RISlocate_schema_file stores the location of the RIS schema file in the parameters
file. You must specify the location of the RIS schema file on a particular node in the
parms file. You must call RISlocate_schema_file to modify the location specified in
the parms file.
void RISlocate_schema_file( schema_file_parms *parms );
Keyword/Identifier
__________________
Description
___________
parms
Pointer to a schema_file_parms structure, specifying the

location of the RIS schema file. See the section Reference
Status Returns
______________
Success
Failure
If the memory protocol is specified, and address, username, or
password is also specified, then error code
RIS_E_INCONSISTENT_SCHFILE_SPEC is returned.
If other protocols (X, T, and D) are specified, but address and
username are not, the same error code is returned. If the file
name is not specified, the error code
RIS_E_MISSING_SCH_FILE_NAME is returned.
Notes
_ ____
The protocol field in schema_file_parms structure specifies the protocol interacting
with the node where the RIS schema file resides. The protocols and their
corresponding codes are:
Protocol
Code
xns
tcp/ip
decnet
memory(local)
X
T
D
M

Use the memory protocol when the RIS for Windows NT schema file
resides on the local machine.
5 - 52
RIS Functions
Protocol
Code
xns
tcp/ip
decnet
memory(local)
name or XX.XXXX
INVALID
You cannot specify an address with the memory protocol. Use the
username field to specify a valid username on the node. You also
cannot specify a user with the memory protocol.
If the username specified requires a password, specify it in the password
field.
The filename field specifies the name of the RIS schema file. If the file resides on a
remote node, you must locate it in a directory that can be read and written by the
specified username. If the file resides on the local machine, you must locate it in a
directory that can be read and written by the user running RIS. If the filename does
not specify a path, then the RIS schema file is assumed to be in the directory where
RIS is installed (for CLIX), or in the shared component directory (for Windows 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
RISrestore_schema_file_checksum reads the RIS schema file, calculates the
checksum, and updates the checksum value in the RIS schema file.
You must recalculate the checksum value if you update the RIS schema file directly,
or when the RIS schema file is corrupted.
void RISrestore_schema_file_checksum( void );
Examples
_________
main()
{
RISrestore_schema_file_checksum( );
}
Status
Returns
______________
Success
Failure
5 - 54
RIS Functions
RISstart_client
RISstart_client starts the RIS client process specified in the client parameters of RIS
parameters file.
void RISstart_client( void );
Examples
_________
main
{
RISstart_client();
{
printf("could not start client\n");
}
}
Status Returns
______________
Success
Failure
Notes
_ ____
See function RISlocate_client to set previously mentioned RIS client parameters.
RISstop_client
RISstop_client clears all prepared statements, clears all asynchronous statements,
and stops the RIS client process.
void RISstop_client( void );
Examples
_________
main
{
RISstop_client();
{
printf("could not stop client\n");
}
}
Status Returns
______________
Success
Failure
Notes
_ ____
If any asynchronous statements are in incomplete state, then RISstop_client fails.
5 - 56
RIS Functions
RISterminate
RISterminate terminates the RIS client process and any RIS servers it is using.
RISterminate also frees resources such as shared memory segments and semaphore
sets. Calling RISterminate is optional. RIS automatically terminates when the
application process exits.
void RISterminate( void );
Examples
_________
main()
{
RISinitialize("english");
{
printf("Could not initialize\n");
}
RISterminate();
{
printf("Could not terminate\n");
}
}
Status
Returns
______________
Success
Failure
RIS Forms Functions 6 - 1
RIS Forms Functions
__________________________________________________________________________________________________________________________________________________
6-2
RIS Forms Functions
6.
__________________________________________________________________________________________________________________________________________________
RIS Forms Functions

The functions in this section control the forms of the RIS Schema Manager. To use
embedded RIS forms functions in your applications, you must install the Shamrock.dll. The
RIS Schema Manager is a standalone utility that creates, displays, alters, or drops RIS
schemas. For more information on this utility, refer to the RIS SQL Users Guide for 32-Bit
Applications. The forms functions perform the following:
Initialize Initialize the RIS forms.
Set Change the functions defined RISfrm_initialize.
Displayed Check to see if a form is currently displayed.
Display Display a form.
Erase Erase a form.
You must call the initialize function (RISfrm_initialize) before calling the other
RIS forms functions.
The functions can control the following forms:
Alter Table Form
Create Schema Form
Create Table Form
Data Definition Form
Dictionary Access Form
Drop Schema Form
Drop Table Form
Exclude Form
Include Form
Locate Client Form
Modify DB2 Password Form
Modify Node Info Form

Modify Schema Password Form
RIS Database Form
Schema Definition Form
Schema File Form
Schema Information Form
Schema Manager Form
Secure Schema Access Form
Set Form
Table Information Form

The following are include files for forms functions:
utl_err.h
risforms.h
risforms.prt
ris.h
6-4
RIS Forms Functions
The following are libraries for forms functions:

ris.a
risforms.a
xrisforms.a
The following are example programs for forms functions:

frmsample1.c
frmsample2.c
xfrmsample1.c
xfrmsample2.c
6.2 Initialize Forms Function

You must call the RISfrm_initialize function before calling the other RIS forms
functions.
extern int RISfrm_initialize(RISfrm_init_parms *init_parms);
Data
Type
__________
Argument
_ ________
RISfrm_init_parms
*init_parms
I/O
____
I
Description
___________
Pointer to a structure which
contains pointers to userdefined functions.
Notes
_ ____
The RISfrm_init_parms data type is defined in the risforms.h include file as follows:
typedef struct RISfrm_init_parms_s
{
/*
**
Notification routines
*/
void (*pre_notification_routine)();
void (*post_notification_routine)();
/*
**
*/
void
void
void
void
void
void
void
void
void
void
void
void
void
Initialization routines
(*alter_table_init_routine)();
(*create_schema_init_routine)();
(*create_table_init_routine)();
(*data_definition_init_routine)();
(*db2pass_init_routine)();
(*dict_access_init_routine)();
(*drop_schema_init_routine)();
(*drop_table_init_routine)();
(*exclude_init_routine)();
(*include_init_routine)();
(*locate_client_init_routine)();
(*node_info_init_routine)();
(*ris_dbs_init_routine)();
void
void
void
void
void
void
void
void
/*
**
*/
int
int
int
int
int
int
int
int
int
int
int
int
int
/*
**
*/
int
(*schema_access_init_routine)();
(*schema_definition_init_routine)();
(*schema_file_init_routine)();
(*schema_info_init_routine)();
(*schema_mgr_init_routine)();
(*schema_password_init_routine)();
(*set_init_routine)();
(*table_info_init_routine)();
Execution routines
(*alter_table_exec_routine)();
(*create_schema_exec_routine)();
(*create_table_exec_routine)();
(*db2pass_exec_routine)();
(*dict_access_exec_routine)();
(*drop_schema_exec_routine)();
(*drop_table_exec_routine)();
(*exclude_exec_routine)();
(*include_exec_routine)();
(*node_info_exec_routine)();
(*schema_access_exec_routine)();
(*schema_password_exec_routine)();
(*set_exec_routine)();
Error Handler
(*error_handler_routine)();
/*
**
Display Help Buttons
*/
char
display_help_buttons;
} RISfrm_init_parms;
These fields, except display_help_buttons, are pointers to your functions. RIS automatically
calls the functions after various events, as described in the following list. To ignore an event,
set the corresponding field to NULL. To ignore all events, set the init_parms argument to
NULL. To display Help buttons on the forms set display_help_buttons to 1, otherwise set it
to 0.
If you provide the following functions, RIS calls them immediately before or after any
user input to any of the RIS forms.
void (*pre_notification_routine)()
void (*post_notification_routine)()
Define these functions as follows:

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
*/
6-6
RIS Forms Functions
double
Form
value;
fp;
/* value of the gadget

/* pointer to the form
*/
*/
The risforms.h include file contains the form and gadget labels. For more information
about form notification routines, see the I/Forms Programmers Guide.
If you provide the following functions, RIS calls each one immediately before its
respective form displays.
void
void
void
void
void
void
void
void
void
void
void
void
void
void
void
void
void
void
void
void
void
(*alter_table_init_routine)()
(*create_schema_init_routine)()
(*create_table_init_routine)()
(*data_definition_init_routine)()
(*db2pass_init_routine)()
(*dict_access_init_routine)()
(*drop_schema_init_routine)()
(*drop_table_init_routine)()
(*exclude_init_routine)()
(*include_init_routine)()
(*locate_client_init_routine)()
(*node_info_init_routine)()
(*ris_dbs_init_routine)()
(*schema_access_init_routine)()
(*schema_definition_init_routine)()
(*schema_file_init_routine)()
(*schema_info_init_routine)()
(*schema_mgr_init_routine)()
(*schema_password_init_routine)()
(*set_init_routine)()
(*table_info_init_routine)()

void alter_table_init_routine( fp )
Form fp; /* pointer to the form */
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 )
Form 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 )
Form fp;
void node_info_init_routine( fp )
void ris_dbs_init_routine( fp )
void schema_access_init_routine( fp )
Form 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 )
If you provide the following functions, RIS calls each one when the user selects the
execute button on the respective form.
int
int
int
int
int
int
int
int
int
int
int
int
int
(*alter_table_exec_routine)()
(*create_schema_exec_routine)()
(*create_table_exec_routine)()
(*db2pass_exec_routine)()
(*dict_access_exec_routine)()
(*drop_schema_exec_routine)()
(*drop_table_exec_routine)()
(*exclude_exec_routine)()
(*include_exec_routine)()
(*node_info_exec_routine)()
(*schema_access_exec_routine)()
(*schema_password_exec_routine)()
(*set_exec_routine)()

int alter_table_exec_routine( fp, str )
char *str;
/* pointer to the RIS command string to be executed */
6-8
RIS Forms Functions
int create_schema_exec_routine( fp, str )

char *str;
int create_table_exec_routine( fp, str )

char *str;
int drop_table_exec_routine( fp, str )

char *str;
int db2pass_exec_routine( fp, str )
char *str;
int dict_access_exec_routine( fp, str )

Form fp;
char *str; /* pointer to the RIS command string to be executed */
int drop_schema_exec_routine( fp, str )

char *str;
int exclude_exec_routine( fp, str )
char *str;
int include_exec_routine( fp, str )
char *str;
int node_info_exec_routine( fp, str )
char *str;
int schema_access_exec_routine( fp, str )
char *str;
int schema_password_exec_routine( fp, str )
char *str;
int set_exec_routine( fp, str )
char *str;
These functions must return an integer value. If they return a zero (0), RIS does not
execute the RIS command string. If they return a nonzero, RIS attempts to execute the
RIS command string.
The argument str points to a static variable which contains the actual RIS command
string to execute. If you alter the contents of str, you also alter the command that RIS
attempts to execute.
If you provide this function, RIS calls it whenever a RIS error occurs.
int (*error_handler_routine)();
Define this function as follows:

int error_handler_routine( ris_error, ris_error_str )
int
ris_error;
char *ris_error_str;
This function must return an integer value. If it returns a zero (0), RIS does not display
the RIS error string. If it returns a nonzero, RIS displays the RIS error string.
The argument ris_error_str points to a static variable which contains the actual RIS
error string to display. If you alter the contents of ris_error_str, you also alter the error
message that RIS displays.
Before using these routines with I/Forms, you must call the Enter_tools,
Enable_events, and FI_enter functions. You must also load the fixed VLT.
Before using these routines with I/XForms, you must call the XOpenDisplay,
FSEnter, and FI_enter functions.
6.3 Set Functions

These functions alter the user-defined functions called by RIS.
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 alter the prenotification, postnotification, and error-handler routines, call

RISfrm_set_pre_notification_routine, RISfrm_set_post_notification_routine, and
RISfrm_set_error_handler_routine, passing the address of the new function as the argument.
These functions should be defined as described in the Initialize Forms Function section.
To alter the form_init and form_exec routines for a specific form, call
RISfrm_set_form_init_routine and RISfrm_set_form_exec_routine, passing the form_label and
the address of the new function as the arguments.
6 - 10
RIS Forms Functions
Notes
_ ____
It is valid to pass NULL as a function address. This cancels any previously defined
functions.
6.4 Displayed Forms Functions

The functions in this section determine if their corresponding forms are currently displayed.
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
RISfrm_alter_table_form_displayed(void)
RISfrm_create_schema_form_displayed(void)
RISfrm_create_table_form_displayed(void)
RISfrm_data_def_form_displayed(void)
RISfrm_db2pass_form_displayed(void)
RISfrm_dict_access_form_displayed(void)
RISfrm_drop_schema_form_displayed(void)
RISfrm_drop_table_form_displayed(void)
RISfrm_exclude_form_displayed(void)
RISfrm_include_form_displayed(void)
RISfrm_locate_client_form_displayed(void)
RISfrm_node_info_form_displayed(void)
RISfrm_ris_dbs_form_displayed(void)
RISfrm_schema_access_form_displayed(void)
RISfrm_schema_definition_form_displayed(void)
RISfrm_schema_file_form_displayed(void)
RISfrm_schema_info_form_displayed(void)
RISfrm_schema_mgr_form_displayed(void)
RISfrm_schpass_form_displayed(void)
RISfrm_set_form_displayed(void)
RISfrm_table_info_form_displayed(void)
Status Returns
______________
0
non-zero
Form is not currently displayed.

Form is currently displayed.
6.5 Display Forms Functions

The functions in this section display their corresponding forms.
You must call the function RISfrm_initialize before calling these functions.
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
RISfrm_display_alter_table_form(void)
RISfrm_display_create_schema_form(void)
RISfrm_display_create_table_form(void)
RISfrm_display_data_def_form(void)
RISfrm_display_db2pass_form(void)
RISfrm_display_dict_access_form(void)
RISfrm_display_drop_schema_form(void)
RISfrm_display_drop_table_form(void)
RISfrm_display_exclude_form(void)
RISfrm_display_include_form(void)
RISfrm_display_locate_client_form(void)
RISfrm_display_node_info_form(void)
RISfrm_display_ris_dbs_form(void)
RISfrm_display_schema_access_form(void)
RISfrm_display_schema_definition_form(void)
RISfrm_display_schema_file_form(void)
RISfrm_display_schema_info_form(void)
RISfrm_display_schema_mgr_form(void)
RISfrm_display_schpass_form(void)
RISfrm_display_set_form(void)
RISfrm_display_table_info_form(void)
Status Returns
______________
RIS_SUCCESS
Other
Success defined in ris.h.

Error code defined in the utl_err.h include file.
Notes
_ ____
To execute the following functions, you must set the RIS Default Schema. These functions
require a default schema to perform RIS queries:
RISfrm_display_table_info_form
RISfrm_display_create_table_form
RISfrm_display_drop_table_form
RISfrm_display_alter_table_form
6 - 12
RIS Forms Functions
6.6 Erase Forms Functions

The functions in this section erase their corresponding forms.
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
int
RISfrm_erase_alter_table_form(void)
RISfrm_erase_create_schema_form(void)
RISfrm_erase_create_table_form(void)
RISfrm_erase_data_def_form(void)
RISfrm_erase_db2pass_form(void)
RISfrm_erase_dict_access_form(void)
RISfrm_erase_drop_schema_form(void)
RISfrm_erase_drop_table_form(void)
RISfrm_erase_exclude_form(void)
RISfrm_erase_include_form(void)
RISfrm_erase_locate_client_form(void)
RISfrm_erase_node_info_form(void)
RISfrm_erase_ris_dbs_form(void)
RISfrm_erase_schema_access_form(void)
RISfrm_erase_schema_definition_form(void)
RISfrm_erase_schema_file_form(void)
RISfrm_erase_schema_info_form(void)
RISfrm_erase_schema_mgr_form(void)
RISfrm_erase_schpass_form(void)
RISfrm_erase_set_form(void)
RISfrm_erase_table_info_form(void)
Status
Returns
______________
RIS_SUCCESS
Other
Success defined in ris.h.

Error code defined in the utl_err.h include file.
6.7 Forms Functions Error Handling

If an error occurs, all RIS forms functions place information about the error in the
RIS_forms_error global variable. If an I/Forms error occurs, information about the I/Forms
error is placed in the RIS_forms_error global variable. RIS_forms_error is defined in the
risforms.h include file as follows:
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
_ ____
If a RIS error occurs, RIS_forms_error.error is set to RISUTL_E_RIS_ERROR. Also, the
global variables SQLCODE and risca contains information about the RIS error. The report
error statement can be executed to retrieve a message resulting from the error.
6 - 14
RIS Forms Functions
Embedded Loading and Unloading of RIS Objects 7 - 1
Embedded Loading and Unloading of RIS Objects
__________________________________________________________________________________________________________________________________________________
7-2
7.
__________________________________________________________________________________________________________________________________________________

RIS provides an embedded programming function interface to the rislod and risunlod
utilities. This embedded programming function interface passes detailed information about
RIS objects to the rislod and risunlod utilities using the risloddes and the risulddes
structures. The semantics and constraints of these structures are similar to the command
line versions of rislod and risunlod. This section lists the include files, libraries, and example
programs needed for embedded loading and unloading. It also gives directions for using the
risloddes and the risulddes structures as arguments in the rislod and risunlod utilities. See
the risloddes Structures and risulddes Structures sections for detailed information about
risloddes and risulddes.
Read the sections risunlod and rislod of the RIS Utilities Guide before using
risloddes or risulddes.
7.1 Using risloddes for Embedded Loading

The risloddes structure, defined in the rislduld.h include file, specifies the RIS objects to load
from external ASCII files into RIS schemas. You can specify fields in the risloddes structure
to do the following:
Create schemas
Create tables
Load data into tables
Create views
Create indexes
Grant privileges
The risloddes structure is a two way communication link between an application and the
rislod utility. In addition to loading RIS objects, the risloddes structure returns the status
information about:
Schemas
Tables
Indexes
7-4
Privileges
Number of rows loaded per table
Number of rows rejected by RIS
See the section Directions for Using risloddes and risulddes for detailed information on using
risloddes.
7.2 Using risulddes for Embedded Unloading

The risulddes structure, defined in the rislduld.h include file, specifies the RIS objects to
unload from RIS schemas into external ASCII files. You can specify fields in the risulddes
structure to do the following:
Schemas
Tables with data
Tables without data
Views
Indexes
Privileges
The risulddes structure is a two way communication link between an application and the
risunlod utility. In addition to unloading RIS objects, the risulddes structure returns the
following status information about the RIS objects being unloaded:
Schemas
Tables
Indexes
Privileges
See the section Directions for Using risloddes and risulddes for detailed information about
risulddes.

The following are load and unload include files:
rislduld.h
ris.h
utl_err.h
The load and unload library is:

rislduld.lib
ris.lib
The following are load and unload example programs:
lodsamp1.c through lodsamp6.c
uldsamp1.c through uldsamp3.c
7.4 risloddes Structures

The risloddes structure has 16 fields. Two of these fields, struct risloddbs and struct
rislodsch, are pointers to other structures. The risloddbs structure holds database
information, and the rislodsch structure holds schema information.
The following graphics show the various structure relationships.
7-6
The following table lists the input fields of risloddes structure:

Data
Type
__________
Name
______
Description
___________
int
nonansimode
0 = ANSI mode on.

1 = ANSI mode off.
int
preserve_blanks
1 = preserve_blanks on.
0 = preserve_blanks off.
Default is 0.
char
filemode
Filemode for output files such as

badfile and logfile. Filemodes
include:
w = write.
a = append.
e = exist.
Default is e.
char [RIS_MAX_PATH_SIZE]
mainfile
Input filename for loading.

Default is ris.dmp.
badfile
Bad filename for loading.

Default is ris.bad.
logfile
Log filename for loading.

Default is ris.log.
char
delimiter
Delimiter used for fields of char

type. Default is single
quotation().
int
commit_interval
Count indicating when to commit.

It commits after inserting a
specific number of
commit_interval rows.
Default is 25.
int
dbs_count
Number of risloddbs structures.
struct risloddbs
*dbs
Pointer to an array of risloddbs

structures. There is one structure
for each database type. See
risloddbs Structure for more
information.
int
schema_count
Number of schemas to load.
struct rislodsch
*schemas
Pointer to an array of rislodsch

for each schema. See rislodsch
Structure for more information.
The following table lists the output fields of the risloddes structure:
Data
Type
__________
Name
______
Description
___________
long
lod_err_code
Error code (defined in the

RISlod_err.h include file) returned
by loader.
long
ris_err_code
Error code (defined in the RIS

error include files) returned by
RIS.
long
db_err_code
Error code returned by underlying

database. Refer to specific
database error messages.
char
sqlwarnings[8]
Warnings set by RIS. Refer to

ris.h.
7-8
7.4.1 risloddbs Structure

Access the risloddbs structure through a pointer in risloddes. The risloddbs structure has
the following input fields:
Type
_Data
_________
Name
______
Description
___________
char
[RIS_MAX_KEYWORD_SIZE]
dbsname
Database name to enforce. For

example, INFORMIX or ORACLE.
7.4.2 rislodsch Structure

Access the rislodsch structure through a pointer in risloddes. There is one rislodsch
structure for each schema loaded. Within rislodsch, there are four nested structures. Fields
belonging to these structures are prefixed by tabinfo, viewinfo, indxtabinfo, and granttabinfo.
The following table lists the input fields of the rislodsch structure:
Type
_Data
_________
Name
______
Description
___________
char [RIS_MAX_ID_SIZE]
schname
Source schema name to load.
schpass
Source schema password.
osname
Operating system username.
ospass
Operating system password.
username
Database username.
Required if using the default
schema statement in an
unload file to access a secure
schema. Otherwise, this field
is ignored.
userpass
Database user password.
new_schname
Destination (an existing)

schema name.
new_schpass
Destination schema
password.
new_user
Required when the

destination schema specified
in new_schname is a secure
schema. See the declare
schema statement for more
information.
new_userpass
Required when the

destination schema specified
in new_schname is a secure
schema. See the declare
schema statement for more
information.
char
select_mode
Indicates how many schema

objects to load.
a = load all objects. All
following fields in *info
structure become output
fields.
s = load some objects. All
structure become input fields.
n = load no objects. All
structure are ignored.
Fields of the tabinfo nested structure:

Data
Type
__________
Name
______
Description
___________
char
select_mode
Indicates how many tables to

load.
a = load all table information.
s = load some table
information.
n = load no table information.
int
ignore_create_error
Indicates whether or not to

ignore table error.
1 = ignore table existence
error.
0 = do not ignore table
existence error.
7 - 10
int
with_data
Indicates whether to load

table definition or to load
table definition with data.
1 = load table definition only.
0 = load both table definition
and data.
int
clear_exist_data
Indicates whether or not to

clear data before loading.
1 = delete rows before loading.
0 = do not delete rows before
loading.
int
table_count
Number of tables to load.
struct rislodtab
*tables
Pointer to an array of
rislodtab structures. There is
one structure for each table.
See rislodtab Structure for
more information.
Fields of the viewinfo nested structure:

Data
Type
__________
Name
______
Description
___________
char
select_mode
Indicates how many views to

load.
a = load all view information.
s = load some view
information.
n = load no view information.
int
view_count
Number of views to load.
struct rislodview
*views
rislodview structures. There
is one structure for each view.
See rislodview Structure for
more information.
Fields of the indxtabinfo nested structure:

Data
Type
__________
Name
______
Description
___________
char
select_mode
Indicates how much index

information to load per table.
a = load all index information.
s = load some index
information.
n = load no index information.
int
indxtab_count
Number of tables with

indexes to load.
struct rislodindx
*indxtabs
Pointer to array of rislodindx

structures. There is one
structure for each table. See
rislodindx Structure for more
information.
Fields of the granttabinfo nested structure:

Data
Type
__________
Name
______
Description
___________
char
select_mode
Indicates how much privilege

information to load.
a = load all privilege
information.
s = load some privilege
information.
n = load no privilege
information.
int
granttab_count
Number of relations whose

privileges are to be loaded.
struct rislodgrant
*granttabs
rislodgrant structures. There
is one structure for each
relation (table or view). See
rislodindx Structure for more
information.
7 - 12
The following table lists the output fields of the rislodsch structure:
Data
Type
__________
Name
______
Description
___________
long
lod_err_code
Error code (defined in

RISlod_err.h include file)
returned by loader.
long
ris_err_code
Error code (defined in RIS

error include files) returned
by RIS.
long
db_err_code
Error code returned by

underlying database. Refer to
specific database error
messages.
char
sqlwarnings[8]
Warnings set by RIS. Refer

to ris.h.
rislodtab Structure
Access the rislodtab structure through a pointer in rislodsch. There is one rislodtab
structure for each table loaded. The following table lists the fields of this structure.
The tabname field is an input and output field. The remaining fields are output
fields only.
Data
Type
__________
Name
______
Description
___________
char[RIS_MAX_ID_SIZE]
tabname
Table name.
int
rows_loaded
Number of successfully loaded

rows.
int
err_rows
Number of rows not loaded.
long
lod_err_code
Error code (defined in the

by loader.
long
ris_err_code

RIS.
long
db_err_code

char
sqlwarnings[8]

ris.h.
7 - 14
rislodview Structure
Access the rislodview structure through a pointer in rislodsch. There is one
rislodview structure for each view loaded. The following table lists the fields of this
structure. The viewname field is an input and output field. The remaining fields are
output fields only.
Data
Type
__________
Name
______
Description
___________
viewname
View name.
long
lod_err_code

by loader.
long
ris_err_code
Error code (defined in RIS*_err.h

include file) returned by RIS.
long
db_err_code

char
sqlwarnings[8]

ris.h.
rislodindx Structure
Access the rislodindx structure through a pointer in rislodsch. There is one
rislodindx structure for each table or view with indexes loaded. The tabname field is
an input and output field. The remaining fields are output fields only.
Data
Type
__________
Name
______
Description
___________
tabname
Table name.
int
indexes_loaded
Number of indexes created.
int
err_indexes
Number of indexes not created.
long
lod_err_code

by loader.
long
ris_err_code

RIS.
long
db_err_code

char
sqlwarnings[8]

ris.h.
7 - 16
rislodgrant Structure
Access the rislodgrant structure through a pointer in rislodsch. There is one
rislodgrant structure for each table or view with privileges loaded. The table_owner
and tabname fields are input and output fields. The remaining fields are output
fields only.
Data
Type
__________
Name
______
Description
___________
table_owner
Schema name that owns the table

(optional).
tabname
Table name.
int
grants_loaded
Number of privileges granted.
int
err_grants
Number of errors incurred while

granting privileges.
long
lod_err_code

by loader.
long
ris_err_code

RIS.
long
db_err_code

char
sqlwarnings[8]

ris.h.
7.5 risulddes Structures

The risulddes structure has nine fields. One of these fields, struct risuldsch, is a pointer to a
structure holding information about each schema that is unloaded.
The following graphic shows the structural relationships.
7 - 18
The following table lists the input fields of the risulddes structure:
Data
Type
__________
Name
______
Description
___________
char
filemode
Filemode for output files such as

mainfile and datafile. Filemodes
include:
w = write.
a = append.
e = exist.
Default is e.
int
preserve_blanks
1 = preserve_blanks on.
0 = preserve_blanks off.
Default is 0.
mainfile
Output filename for unloading.

Default is ris.dmp.
int
schema_count
Number of schemas to unload.
struct risuldsch
*schemas
Pointer to an array of risuldsch

for each schema. See risuldsch
Structure for more information.
The following table lists the output fields of the risulddes structure:
Data
Type
__________
Name
______
Description
___________
long
uld_err_code

RISuld_err.h include file) returned
by unloader.
long
ris_err_code
Error code (defined in RIS error

include file) returned by RIS.
long
db_err_code

char
sqlwarnings[8]

ris.h.
7.5.1 risuldsch Structure

Access the risuldsch structure through a pointer in risulddes. There is one risuldsch
structure for each schema unloaded. Within risuldsch, there are four nested structures.
Fields belonging to these structures are prefixed by tabinfo, viewinfo, indxtabinfo, and
granttabinfo.
The following table lists the input fields of the risuldsch structure:
Type
_Data
_________
Name
______
Description
___________
schname
Schema name to unload.
schpass
Schema password.
osname
Secure schema username. If

osname is specified, the schema
is unloaded as a secure schema,
even if the schema is not a
secure schema in the current
database.
ospass
Secure schema password.

Required if the osname field
has a password.
dbname
Database username for secure

schemas required by certain
RDBMSs.
dbpass
Database password for secure

schemas required by certain
RDBMSs.
char
select_mode
Indicates how many schema

objects to unload.
a = unload all objects. All
structures become output
fields.
s = unload some objects. All
structures become input fields.
n = unload no objects. All
structures are ignored.
7 - 20
Fields of the tabinfo nested structure:

Data
Type
__________
Name
______
Description
___________
char
select_mode
Indicates how many tables to

unload.
a = unload all table
information.
s = unload some table
information.
n = unload no table
information.
int
with_data
Indicates whether to unload

table definition or to unload
table definition with data.
1 = ignore table existence error.
0 = do not ignore table
existence error.
int
separate_dfile
Indicates whether data should

be unloaded in the same file or
different file than the mainfile.
1 = different dfile.
0 = same file as mainfile.
int
variable_data_format
Indicates whether data should

be unloaded in fixed or variable
format.
1 = variable.
0 = fixed.
int
table_count
Number of tables to unload.
struct risuldtab
*tables
Pointer to an array of risuldtab

risuldtab Structure for more
information.
Fields of viewinfo nested structure:

Data
Type
__________
Name
______
Description
___________
char
select_mode
Indicates how many views to

unload.
a = unload all view
information.
s = unload some view
information.
int
view_count
Number of views to unload.
struct risuldview
*views
risuldview structures. There is
one structure for each view.
See risuldview Structure for
more information.
Fields of indxtabinfo nested structure:

Data
Type
__________
Name
______
Description
___________
char
select_mode
Indicates how much index

information to unload per table.
a = unload all index
information.
s = unload some index
information.
n = unload no index
information.
int
indxtab_count
Number of tables whose

indexes are unloaded.
struct risuldindx
*indxtabs
Pointer to array of risuldindx

risuldindx Structure for more
information.
7 - 22
Fields of granttabinfo nested structure:

Data
Type
__________
Name
______
Description
___________
char
select_mode
Indicates how many privileges

to unload per table/view.
a = unload all privilege
information.
s = unload some privilege
information.
n = unload no privilege
information.
int
granttab_count.
Number of relations whose

privileges are unloaded.
struct risuldgrant
*granttabs
risuldgrant structures. There
is one structure for each
relation (table or view). See
risuldgrant Structure for more
information.
The following table lists the output fields of the risuldsch structure:
Data
Type
__________
Name
______
Description
___________
long
uld_err_code

RISuld_err.h include files)
returned by unloader.
long
ris_err_code

error include files) returned
by RIS.
long
db_err_code
Error code returned by

underlying database. Refer to
specific database error
messages.
char
sqlwarnings[8]
Warnings set by RIS. Refer

to ris.h.
risuldtab Structure
Access the risuldtab structure through a pointer in risuldsch. There is one risuldtab
structure for each table unloaded. The following table lists the fields of this
structure. The tabname field is an input and output field. The remaining fields are
output fields only.
Data
Type
__________
Name
______
Description
___________
tabname
Table name.
char
*whereclause
Optional where clause to unload

partial data.
data_filename
Field returning the datafile if

separate_dfile = 1.
int
rows_unloaded
Number of successfully unloaded

rows.
int
err_rows
Number of rows not unloaded.
long
lod_err_code

by unloader.
long
ris_err_code

by RIS.
long
db_err_code

char
sqlwarnings[8]

ris.h.
7 - 24
risuldview Structure
Access the risuldview structure through a pointer in risuldsch. There is one
risuldview structure for each view unloaded. The following table lists the fields of
this structure. The viewname field is an input and output field. The remaining fields
are output fields only.
Data
Type
__________
Name
______
Description
___________
viewname
View name.
long
uld_err_code

by unloader.
long
ris_err_code

RIS.
long
db_err_code

char
sqlwarnings[8]

ris.h.
risuldindx Structure
Access the risuldindx structure through a pointer in risuldsch. There is one
risuldindx structure for each table or view with indexes unloaded. The tabname field
is an input and output field. The remaining fields are output fields only.
Data
Type
__________
Name
______
Description
___________
tabname
Table name.
int
indexes_loaded
Number of indexes unloaded.
int
err_indexes
Number of indexes not unloaded.
long
uld_err_code
Error code returned by unloader if

any index level error encountered.
For example, Invalid indxtab
selectmode, Table or view not
found, and so forth.
long
ris_err_code
Error code returned by RIS if any

error encountered.
long
db_err_code

database if any error encountered.
char
sqlwarnings[8]

ris.h.
7 - 26
risuldgrant Structure
Access the risuldgrant structure through a pointer in risuldsch. One risuldgrant
structure is allocated for each table or view with privileges unloaded. The
table_owner and tabname fields are input and output fields. The remaining fields are
output fields only.
Data
Type
__________
Name
______
Description
___________
table_owner
Schema owner name (optional).
tabname
Table name.
int
grants_unloaded
Number of privileges unloaded.
int
err_grants
Number of errors incurred while

granting privileges.
long
uld_err_code

by unloader.
long
ris_err_code

RIS.
long
db_err_code

char
sqlwarnings[8]

ris.h.
7.6 Directions for Using risloddes and risulddes

The following sections describe the necessary steps for using risloddes and risulddes. The
necessary loader/unloader functions are described in the section RIS_loader and
RIS_unloader Embedded Functions.
7.6.1 Directions for Using risloddes

Follow these steps when working with the risloddes structure:
1.
Define a structure of type risloddes. The following are default values for this structure:
Field Name
___________
Default Value
_____________
delimiter
commit_interval
nonansimode
filemode
mainfile
badfile
logfile
single quotation ()
25
ansi mode on (0)
e
ris.dmp
ris.bad
ris.log
2.
Initialize the fields of the risloddes structure.
3.
Assign top-level fields such as ansimode, filemode, mainfile, and so forth.
4.
Set the schema_count field to a positive value indicating number of schemas to load.
5.
Allocate an array of rislodsch structures using schema_count (one per schema).
6.
Assign schema information, that is, set the appropriate fields of each rislodsch
structure.
a.
Set schema select_mode to a (all objects of the schema) or s (some of the objects
of the schema). There is no default.
b.
If you set select_mode to a, then ignore all the other fields of the rislodsch
structure. Also ignore rislodtab, rislodview, rislodindx, and rislodgrant structures.
Appropriate structure members returning status are set by the loader. All
*info.select_mode fields are set to a by the loader. The following are default
values for the rislodtab structure (when schemas select_mode is set to a):
Field Name
___________
with_data
ignore_create_error
clear_exist_data
Default Value
_____________
1
1
1
7 - 28
c.
If you set select_mode to s, set the following fields:

tabinfo.select_mode and table related fields
viewinfo.select_mode and view related fields
indxtabinfo.select_mode and index related fields
granttabinfo.select_mode and grant related fields
d.
7.
If you set *info.select_mode to s, then allocate an array of rislod* structures for

each object. The array size is *info.*_count.
Call the following function to load RIS objects indicated by the risloddes structure:
risloddes my_lod;
RIS_loader(&my_lod);
8.
Call the following function to print the status of the risloddes structure (optional):
RISlod_print_risloddes(&my_lod);
OR
RISlod_fprint_risloddes(stdout, &my_lod);
This function should be called only after calling RIS_loader().
9.
Link ris.lib and rislduld.lib libraries to your application objects.

Each RIS object has its own lod_err_code, ris_err_code, db_err_code, and
sqlwarning to indicate last related error codes pertaining to that object.
The risloddes function provides no BLOB support.
7.6.2 Directions for Using risulddes

Follow these steps when working with the risulddes structure:
1.
Define a structure of type risulddes. The following are default values for this structure:
Field Name
___________
Default Value
_____________
filemode
mainfile
e
ris.dmp
2.
Initialize the fields of the risulddes structure.
3.
Assign top-level fields such as filemode, mainfile, and so forth.
4.
Set the schema_count field to a positive value indicating number of schemas to unload.
5.
Allocate an array of risuldsch structures using schema_count (one per schema).
6.
Assign schema information, that is, set the appropriate fields of the risulddes fields.
a.
Set schema select_mode to a or s. There is no default.
b.
If you set select_mode to a, then ignore all the other fields of risuldsch structures.
Appropriate structure members returning schemas are set by the unloader. All
the *info.select_mode fields are set to a by the unloader. The following are default
values for fields in the risuldtab structure (when schemas select_mode is set to a):
Field Name
___________
with_data
separate_dfile
variable_data_format
c.
Default Value
_____________
1
0
0
If you set select_mode to s, then set the following variables:

tabinfo.select_mode and table related fields
viewinfo.select_mode and view related fields
indxtab.select_mode and index related fields
granttabinfo.select_mode and grant related fields
d.
If *info.select_mode is set to s, then allocate an array of risuld* structures for each

object. The array size is *info.*_count.
7 - 30
7.
Call the following function to print RIS objects indicated by the risulddes structure:
risuldes my_uld;
RIS_unloader(&my_uld);
8.
Call the following function to print RIS objects indicated by the risulddes structure
(optional):
RISuld_print_risulddes(&my_uld);
OR
RISuld_fprint_risulddes(stdout, &my_uld);
This function should be called only after calling RIS_unloader().
9.
Link the ris.lib and rislduld.lib libraries to your application objects.

Each RIS object has its own lod_err_code, ris_err_code, db_err_code, and
sqlwarning to indicate last related error codes pertaining to that object.
The risulddes function provides no BLOB support.
7.7 RIS_loader and RIS_unloader Embedded Functions

The risloddes or risulddes structure communicates between an application and the
underlying rislod or risunlod utility. The structure is passed to RIS_loader or RIS_unloader
functions. The application receives the necessary information about loading or unloading
RIS objects from the structure. The loader or unloader utility returns the status of RIS
objects loaded or unloaded through the same structure. The following embedded functions
perform loading and unloading operations.
RIS_loader
This function uses the risloddes structure to interface with the rislod utility. You
assign specific load information for rislod using fields of the risloddes structure. The
rislod utility then assigns specific output to fields of the risloddes structure during
function execution.
#include "rislduld.h"
int RIS_loader (risloddes *risloddes_ptr);
Keyword/Identifier
__________________
Description
___________
risloddes_ptr
Pointer to risloddes structure defined in RISloduld.h header

file. See the section risloddes Structures for more
information.
Status Returns
______________
Success
Failure
0
-1
7 - 32
RIS_unloader
This function uses the risulddes structure to interface with the risunlod utility. You
assign specific unload information for risunlod using fields of the risulddes structure.
The risunlod utility then assigns specific output to fields of the risulddes structure
during function execution.
int RIS_unloader (risulddes *risulddes_ptr);
Keyword/Identifier
__________________
Description
___________
risulddes_ptr
Pointer to risulddes structure defined in RISloduld.h header

file. See the section risulddes Structures for more information.
Status Returns
______________
Success
Failure
0
-1
RISlod_fprint_risloddes
This function prints the fields of the risloddes structure to a user-specified file.
#include rislduld.h
void RISlod_fprint_risloddes (FILE *fp, risloddes *risloddes_ptr);
Keyword/Identifier
__________________
Description
___________
fp
File pointer to a file opened with the fopen function.
risloddes_ptr

file. See the section risloddes Structures for more information.
Notes
_ ____
If you are working in the Windows NT environment and you are not using the
riscpp.exe preprocessor to compile your source code, you must use the </>MD switch
in your compile statement.
Because the function call
RISlod_fprint_risloddes (stdout, *risloddes_ptr)
creates less overhead and produces the same result as the call
RISlod_print_risloddes (*risloddes_ptr),
use the RISlod_fprint_risloddes function when printing the risloddes structure fields.
RISlod_print_risloddes
This function prints the fields of the risloddes structure to standard output.
#include rislduld.h
void RISlod_print_risloddes (risloddes *risloddes_ptr);
Keyword/Identifier
__________________
Description
___________
risloddes_ptr

file. See the section risloddes Structures for more
information.
Notes
_ ____
Calling RISlod_print_risloddes is the same as calling RISlod_fprint_risloddes with
the file pointer set to stdout. Because RISlod_fprint_risloddes creates less overhead,
use RISlod_fprint_risloddes when printing the risloddes structure fields. See the
RISlod_fprint_risloddes function description for further information.
RISuld_fprint_risulddes
This function prints the fields of the risulddes structure to a user-defined file.
void RIS_fprint_risulddes (FILE *fp, risulddes *risulddes_ptr);
Keyword/Identifier
__________________
Description
___________
fp
File pointer to a file opened with the fopen function.
risulddes_ptr

file. See the section risulddes Structures for more information.
Notes
_ ____
If you are working in the Windows NT environment and you are not using the
riscpp.exe preprocessor to compile your source code, you must use the </>MD switch
in your compile statement.
Because the function call
RIS_fprint_risulddes (stdout, *risulddes_ptr)
creates less overhead and produces the same result as the call
RIS_print_risulddes (*risulddes_ptr),
use the RISuld_fprint_risulddes function when printing the risulddes structure

fields.
7 - 34
RISuld_print_risulddes
This function prints the fields of the risulddes structure to standard output.
void RISuld_print_risulddes (risulddes *risulddes_ptr);
Keyword/Identifier
__________________
Description
___________
risulddes_ptr

file. See the section risulddes Structures for more
information.
Notes
_ ____
Calling RISuld_print_risulddes is the same as calling RISuld_fprint_risulddes with
the file pointer set to stdout. Because RISuld_fprint_risulddes creates less overhead,
use RISuld_fprint_risulddes when printing the risulddes structure fields. See the
RISuld_fprint_risulddes function description for further information.
Appendix A: Changes to This Version of RIS A - 1
Appendix A
__________________________________________________________________________________________________________________________________________________
Changes to This Version of RIS
A-2
Appendix A: Changes to This Version of RIS
Appendix A
__________________________________________________________________________________________________________________________________________________
Changes to This Version of RIS

This section describes changes between RIS Version 4 and RIS Version 5.
A.1 RDBMS Versions

For the most current information concerning RDBMS version compatibility for
supported RIS platforms, see the Architecture and Configuration Overview
section in the installation guide for your platform.
A.2 UNION and UNION ALL Supported

RIS Version 5 supports UNION and UNION ALL operators with the select statement.
For example:
select * from t1 union select * from t2;
select c1, c2 from t1 union all select c21, c22 from t2;
UNION and UNION ALL are not supported in subqueries. See the RIS SQL Users Guide
for more information.
A.3 Objects of Different Owners Within a Schema

In RIS Version 4 a schema created by an RDBMS user contained only objects (tables, views,
and indexes) owned by that user. In RIS Version 5 a schema can contain objects owned by
multiple users. For example, schema S1, created by RDBMS user U1, can contain objects
owned by RDBMS users U2 and U3, as well as those owned by U1. This capability:
Is a fundamental redefinition of a schema to be simply a named collection of objects in a
database.
Lets data owned by privileged accounts be included without views or security violations.
Allows sharing of common objects among schemas. For example, table 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 applications easily create logical groupings of tables.
A-4
Considerations when using this capability:

Since objects owned by different users can be included in the schema, the owner
information is maintained in the RIS dictionary. The dbms_owner value applies to a
table, view, or an index, and can be in upper or lowercase.
This capability cannot be accessed through RIS Version 4.
The access restrictions of the underlying RDBMS are encountered when using this
capability.
Most databases let two different users create tables/views/indexes with the same name.
However the names of tables/views/indexes within a schema are unique, regardless of
the dbms_owner. If both T1 owned by U1, and T1 owned by U2 need to be included in a
schema, one of the tables has to be aliased. See the section Object Aliases for more
information.
A.4 Object Aliases

With RIS Version 5, any column or table name can be given an alias. For example, table
abc_123 with columns abc1, abc2, and abc3, can be included and referred to as EMPLOYEES
with columns FIRST_NAME, GENDER, and DATE_OF_BIRTH, respectively. This
capability:
Lets identically-named tables owned by different RDBMS users exist in a single
schema. For example, suppose three different users create three different tables with
the same name:
RDBMS: PROJ1.NAMES, PROJ2.NAMES, PROJ3.NAMES
These tables must be aliased so that they have distinct names.
SCHEMA1: NAMES1, NAMES2, NAMES3
Names in RIS can be longer than the underlying database supports. See the RIS SQL
Users Guide for more information.
Object names and keyword conflicts can be worked around. For example, if a column
name is a RIS keyword, such as t1(informix, oracle, db2), it can be included as t1(col1,
col2, col3).
An exclude/include sequence loses all aliases.
Within RIS only the RIS names (aliases) are valid. The external/DBMS name is not
valid.
A.5 Multi-User/Secure Schemas

In RIS Version 5 two types of schemas are supported: the standard schema and the secure
schema. The standard schema is a single-user schema and the information necessary for
connecting to this schema is stored in the schema file (this is no different from a RIS Version
4 schema). The secure schema has no username/password combination stored for it. The
RIS Version 4 (single user) schema is still supported and still the default. This multiuser/secure schema capability:
Allows no connection until a user provides a username/password combination.
Lets you use the same schema, but provide different RDBMS log-ins.
No password is stored in any form by RIS.
Individuals appear distinct to the RDBMS and are subject to RDBMS security tracking.
The declare schema statement lets you specify a schema name and password, and
optionally, the user and password of the user who owns the schema, and the operating
system user and password in the RIS in-memory data dictionary cache.
This statement must be used to access secure schemas. It can also be used to access
standard schemas. See the RIS SQL Users Guide for more information. This capability
can be used by any site. It is most useful to those interested in high levels of security
(usually DB2, ORACLE, and so on).
The schema administrator (user who creates the schema) controls authority to connect
to a schema and to create tables on a schema, using:
GRANT CONNECT TO <rdbms_user>;
REVOKE CONNECT FROM <rdbms_user>;
GRANT RESOURCE TO <rdbms_user>;
REVOKE RESOURCE FROM <rdbms_user>;
A username/password combination should be provided before a schema is open.
There is case-sensitivity of the RDBMS username (except in cases where some
databases accept names in a particular case; then RIS does a conversion).
A-6
A.6 Shared Dictionaries

In RIS Version 5 when a schema s1 is created and creates the dictionary as in RIS Version 4,
schemas s2, s3, s4, and so on can be created using the dictionary created by schema s1. This
capability:
Allows multiple schemas in databases that cannot have tables of the same name (nonANSI INFORMIX).
Requires minimal dictionary creation when there are many schemas.
Allows limited dictionary creation, administration, and ownership outside of RIS for
DB2, SYBASE, and Microsoft SQL Server.
The system administrator must grant and revoke an RDBMS user the authority to
create a schema on a dictionary, using:
GRANT SCHEMA TO <rdbms_user>;
REVOKE SCHEMA FROM <rdbms_user>;
Creators of dictionaries cannot drop all their schemas while there are other schemas in
the dictionary.
An application based on RIS Version 4 must create a dictionary in order to use it.
Additional schemas can then be added to the dictionary and used by applications based
on RIS Version 5. Schemas s2, s3, and so on, cannot be accessed from RIS Version 4.
A.7 Dictionary Objects

Dictionary objects in RIS Version 5 are all renamed (ris5*). This capability:
Removes the distinction between ris* and ris_*.
Makes RIS dictionary objects now appear in the dictionary views.
Additional columns are needed to distinguish among schemas in shared dictionaries, to
distinguish between user objects and dictionary objects, and for internal/external object
names.
Names may need to be changed in queries.
New columns should be considered in queries.
A.8 Dictionary Views

In RIS Version 4 the internal RIS dictionary tables were documented with the note that they
are not intended for application use, and information about them was maintained in the
dictionary. In RIS Version 5, the internal tables are not documented and information about
them is not available in the dictionary. Only dictionary views can be accessed from an
application.
In RIS Version 4 the dictionary views showed information about only the user (or
application) objects and the base tables contained both application objects and RIS dictionary
objects. In RIS Version 5, since the base tables are not accessible from the applications, the
views show both user objects and RIS objects.
Considerations:
If only user objects need to be selected, the condition ris_object=N should be used in the
where clause.
This rule applies to the views ris5columns, ris5column_privs, ris5tables, and
ris5table_privs.
In RIS Version 4 the views risdbms_tables, risdbms_views, and risdbms_indexes, listed
the objects, views, and indexes, respectively, that were in the database, but not
included in the schema. Due to the RIS Version 5 capabilities allowing objects of
different users within a schema and shared dictionaries, the exact equivalent of the RIS
Version 4 views cannot be provided. In Version 5, the ris5dbms_tables view lists all the
tables in the database, along with the user that owns the database. The ris5dbms_views
view lists all the views in the database, along with the user that owns the database.
The ris5dbms_indexes view lists all the indexes in the database, along with the user
that owns the database. In some cases, these lists may include only those
tables/views/indexes accessible to the current log-in/user of the database.
These views are not recommended for use by applications. If used, the
query should have some restrictive condition (specifically, WHERE).
Using select * from these views can lead to significant performance
degradation. Since this view is defined to show everything, it should be
used with caution. In some cases these views are accessible only for the
dictionary creator since some databases do not allow granting system
privileges on catalogs (where these views are defined).
A-8
A.9 RIS_BLOB/RIS_TEXT
RIS Version 5 allows long binary or long text data that lets you:
Use it for document or picture storage by INFORMIX OnLine and ORACLE. RIS has no
RIS_BLOB/RIS_TEXT support for INFORMIX Standard Engine, SYBASE, Microsoft
SQL Server, or DB2.
Insert, update, or retrieve large data.
Access character strings with a length greater than 249 characters for other RDBMSs
not supporting RIS_BLOB.
To use RIS_BLOB/RIS_TEXT data, the client and data server versions must be at least
05.01.01.xx.
This feature is available only through the programming interface; no interactive access
is available.
The application should track the data length.
The RIS_BLOB data type is for binary data; for example, GIF files, executables, and so
forth. RIS makes no attempt to convert or interpret the data.
The RIS_TEXT data type is for text data; for example, ASCII files. RIS does convert
the text data between different hardware platforms as it would for char data.
The text data can be inserted into a RIS_BLOB column, but no blob data should be
inserted into a RIS_TEXT column.
To create a table with a column of RIS_BLOB/RIS_TEXT data type
create table emp (name char(25), id int, picture ris_blob (50000))
The default size of the RIS_BLOB/RIS_TEXT column is 0. The maximum length of the
data is dependent on the database. If the maximum data size is set to 0, data can be
retrieved from the database to a memory array and not a file.
The file_used field is required for inserting and retrieving. RIS uses the filename or the
memory array as the targeted user variable.
The text data and character data are converted for different hardware platforms.
The maximum size limit cannot be zero when retrieving data from the database. The
maximum size limit is zero when retrieving data from memory.
RIS_BLOB/RIS_TEXT columns cannot be used in the SQL WHERE clause or GROUP
BY statements, and cannot be indexed.
The number of RIS_BLOB/RIS_TEXT columns allowed in one table is subject to the

restrictions of the underlying RDBMS. INFORMIX allows multiple
RIS_BLOB/RIS_TEXT columns while ORACLE allows one RIS_BLOB/RIS_TEXT
column per table.
The size of RIS_BLOB/RIS_TEXT is subject to the restrictions and limitations of the
underlying RDBMS.
Tables with RIS_BLOB/RIS_TEXT are created through RIS and data is inserted
through RIS.
Currently, RIS uses the first 8 bytes (ORACLE only) of the RIS_BLOB/RIS_TEXT column in
databases to store the length of the data. Existing tables with data, when included in a RIS
schema, will result in incomplete data when retrieved from the database. To manipulate
RIS_BLOB/RIS_TEXT data, any tables with RIS_BLOB/RIS_TEXT fields need to be created
through RIS and the data inserted only through RIS.
When the maximum size limit for a RIS_BLOB/RIS_TEXT column is zero, data cannot be
retrieved from the database to a file. This situation does not apply when the data is retrieved
into a memory array.
If a positive, non-zero value is used, RIS will use this value as the maximum size limit for the
RIS_BLOB/RIS_TEXT object. If the value is zero, or no value is specified (using default of
zero), then RIS does not impose a limit and the maximum size supported by the underlying
RDBMS can be used.
The limit size can be set to zero in the following situations:
An existing table which has RIS_BLOB/RIS_TEXT columns is included in a RIS
schema
A table is excluded from the RIS schema and later included back into the schema
A table is created through RIS without specifying a RIS_BLOB/RIS_TEXT column size.
To check the value of the maximum size limit:
select char_max_length from ris5columns
where table_name = table and column_name = column;
A - 10
To reset the maximum size limit use risdtype:

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
1
c1
15
ris_blob
10000 null
null
null
Yes
Is this correct? <y(es), n(o), q(uit> >>y
In the above example, RC01 is the dictionary owner as shown in the schema file, blob_table
is the name of the table with a blob column, set to values other than 10000.
RIS limits the data size inserted into a RIS_BLOB/RIS_TEXT column if a size is specified
when the table is created.
For example:
create table blob1 (c1 ris_blob(100000))
would impose a limit of 100,000 bytes. If the table is created without specifying a size, then
the underlying RDBMSs maximum limit for RIS_BLOB/RIS_TEXT data will be used.
For example:
create table blob2 (c2 ris_blob)
A.10 Interoperability
RIS Version 5 lets multiple versions of RIS products be available on most systems. The
following figure details interoperability of RIS Version 4 and RIS Version 5.
This capability:
Lets you continue to use RIS Version 4 applications with minimal impact. Version 4
applications should continue to run.
RIS Client and Data Servers should be upgraded to RIS Version 5.
Multiple versions are available remotely through TCP only.
The ORACLE 7 Data Server requires the RIS Version 5 Client.
The Sybase SQL Data Server requires the Version 5.02 Client.
Only RIS Version 5 applications can query RIS Version 5 dictionary objects. Only RIS
Version 4 applications can query RIS Version 4 dictionary objects.
The RIS utilities are also applications and the previous restrictions apply.
The risdtype utility of RIS Version 4 cannot be used with the RIS Client Version 5 or
the RIS Data Server Version 5.
Files generated by the RIS Version 4 risrecrd utility cannot be processed by the RIS
Version 5 risplbck utility. If an application is built with RIS Version 4, the resulting
record file can be processed only by the RIS Version 4 risplbck utility.
A - 12
A.11 Upgrade Utility

A utility to convert a schema (dictionary and schema file) from RIS Version 4 to RIS Version
5 is delivered with the RIS Client.
While RIS Version 4 is not available for Solaris, the upgrade utility can be used
to upgrade a Version 4 schema file on another platform (for example, CLIX).
Considerations when using this utility:

This conversion should be applied to every existing schema when RIS Version 5 Data
Servers are installed.
The RIS Version 4 Data Servers should be removed.
The conversion of the dictionary is irreversible and is done in-place.
The schema file conversion is non-destructive. The Version 5 schema file is generated
from the Version 4 schema file. This feature lets you mix Version 4 and Version 5
clients to access a Version 5 data server. The schema file that matches the client
version should be used.
A.12 Utilities
The RIS Version 4 ad hoc utility ris has been renamed risbatch. There is now an ad hoc
query utility with a graphic user interface (GUI), called risgui.
Considerations when using the Version 5 loader/unloader:
The loader/unloader provides no BLOB support.
The unloader unloads (or saves) RIS names (aliases) only, not the underlying object
names.
The unloader unloads (or saves) schema ownership only, not underlying RDBMS
ownership.
A.13 Parameters
The parameter file generated by a Version 5 application or utility is compatible with Version
4 applications. In Version 4, if a parameter file existed, all parameters were expected to be
set. Unlike Version 4, Version 5 is more tolerant with respect to parameter files: any number
of parameters can be left unspecified and RIS uses the default values.
A new parameter, CLIENT_VERSION, has been added with the default value set to 0.0,
meaning that the application connects to a compatible client. When future versions of RIS
become available, Version 5 and higher applications will be able to use this parameter to
specify the client version.
Using this parameter causes Version 4 applications to fail; hence, for now, leave it
commented out. When the CLIENT_VERSION parameter is set, Version 4
applications can no longer use that parameter file.
A.14 Internationalization
RIS for 32-bit applications (Version 5.3.1 and later) support 16-bit or multi-byte languages.
Most 16-bit languages are Asian. In the RIS documentation, the maximum size allowed for
table names, view names, index names, schema names, column widths, and character data is
specified as x characters, where x is an integer. For those using multi-byte languages, the
maximum number of characters should be interpreted as the maximum size in bytes.
RISMGR and RISGUI implement multi-byte character support.
RIS limitations and guidelines:
RIS schema and user names can be internationalized, but not passwords.
Only alpha-numeric characters can be internationalized.
Setup is not fully internationalized.
RIS does not localize dialogs, gadgets and error messages.
RIS is internationalized on NT only. The RIS application, RIS Client, and RIS Data
Server must be on NT to take advantage of the RIS internationalization.
The period (.) used between username and passwords must be 8-bit English.
All punctuation, keywords, column datatype definitions, timestamp data, statements
must be 8-bit English.
Schemas, tables, views, columns, index names can be 8-bit or 16-bit characters.
RIS data dictionary tables and views are created using 8-bit English characters.
The following components of a create schema statement are 8-bit and 16-bit characters:
create schema
schema name
schema pass
db type
dbname
db dir
osuser
ospass
ostype
db user
remote clause
8-bit English
8-bit and 16-bit English
8-bit English
8-bit English
16-bit English
8-bit English
8-bit English
8-bit English
A - 14
Character columns are analyzed to make sure that they are wide enough to hold the data.
For example, a 10 character name in a 16-bit language requires a char(20) column.
The maximum number of 8-bit characters in a column is 240. The maximum number of 16bit characters in a column is 120.
Appendix B: Programming Notes and Performance Considerations B - 1
Appendix B
__________________________________________________________________________________________________________________________________________________
Programming Notes and Performance

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

Considerations
B.1
Declaring Tables/Views
When an application first uses a table or view in an SQL statement, some initial overhead is
generated. RIS must learn the names, data types, and sizes of the columns (and if they are
nullable). This information is used to verify that the statement is correct and is used with
appropriate variables. RIS has to query the database to get this information. This is
overhead. If the application does not know anything about the table or view, this overhead
cannot be avoided. If, however, the application knows the definition of the table, the declare
table or declare view statements can be used to provide the information to RIS and avoid the
overhead.
The sample program risdeclare is delivered with RISDP. This program easily generates
table and view declarations for objects in schemas.
Use table declarations in any application that has a standard set of tables because these
tables are generally used only once, either at the start of an application or just before a
table/view is used for the first time. If your application uses a variety of user-defined or
modified tables, consider implementing a mechanism for reading in table/view definitions
that might be used. For example, keep the list of tables/views that have been used in SQL
statements. Then, before using a table, check the list to see if it has been declared.
Compatibility between the declaration and the actual table is important. A declaration with
no compatibility verification is the fastest because it completely bypasses the database. A
declaration with partial verification requires some database interaction, but is still fairly
quick. A full verification declaration should be used primarily to verify that the list of
declarations is up to date and identical to what is in the database system.
Table definitions are cached by RIS. The number of table definitions cached is determined by
the MAX_TABLES_IN_MEM value in the parameter file. When this value overflows, table
definitions are removed. MAX_TABLES_IN_MEM should be larger than the number of
tables the application uses. Caching table definitions creates a memory versus performance
trade-off.
B.2
Error Handling
RIS returns a status code for each statement executed. Always check the status of each
statement. Failure to check the status may result in unexpected failure of other statements.
The global integer variable SQLCODE contains the status. The value RIS_SUCCESS
indicates success, END_OF_DATA indicates end-of-data, and negative values indicate an
error.
B-4
Use the risca and dbca variables to get additional error information. The risca variable is a
pointer to an rissqlca error structure containing detailed RIS error information. The dbca
variable is a pointer to an rissqlca error structure containing error information from the
underlying DBMS. Both structures are defined in ris.h.
Also use the report error and whenever statements for error handling. The report error
statement obtains a string containing the RIS and underlying DBMS error messages. The
whenever statement defines handlers for error and end-of-data conditions.
B.3
Initializing and Terminating RIS
RIS automatically initializes when the first RIS statement is executed. The initialization
process reads information from the parms file, allocates semaphores and shared memory,
sets up internal structures, and then starts the RIS client process.
RIS also automatically terminates when the application process terminates. The RIS client
checks for the existence of the application process at fixed time intervals. When the RIS
client process detects that the application process is no longer running, it shuts down all of
its RIS servers, frees up resources such as semaphores and shared memory, and then
terminates.
It is possible to explicitly initialize and terminate RIS. You can initialize RIS by calling the
RISinitialize function. Calling this function prevents delay of the first RIS statement while
RIS initializes. To avoid delay of the first statement, call RISinitialize during the application
initialization phase. You can terminate RIS by calling the RISterminate function. RIS
normally terminates briefly after application termination. To avoid delay in RIS termination
or to terminate RIS without terminating the application, call RISterminate. Use of these
functions is highly recommended.
B.4
Locking
Locking is either explicit or implicit. The DBMS implicitly locks, but explicit locking requires
the lock tables statement.
Implicit locking can be problematic because each DBMS does it differently. Databases differ
in both the scope and type of locking. A DBMS can lock at the row, page, or table level. You
can modify the locking behavior of some, but not all, databases. Also, a DBMS may
originally lock at the row or page level and escalate the locks to table level if necessary. This
is because the total number of row and page locks is limited. This limit also varies depending
on the DBMS.
The two basic lock types are share and exclusive. Use a share lock when reading data. This
prevents other users from updating the data being read. Multiple users can have a share
lock on the same data. Exclusive locks prevent users from accessing the data in any way.
Use exclusive locks when modifying data to prevent others from modifying or viewing the
data. Every DBMS has a share and an exclusive lock, but the locks behavior varies among
different databases. The DBMS may also have additional lock types.
Explicit locking ensures that locking is performed uniformly across different DBMSs.
However, explicit locking has restrictions. First, you can only lock data at the table level
using the lock tables statement. Page and row level locking are implicit only. Next, you
must make the lock tables statement the first statement within a transaction. Finally, you
must specify all tables used in the transaction when the lock tables statement is used.
The lock tables statement allows simultaneous locking of multiple tables in different modes.
Each table can be locked in either share, exclusive, or default mode. The share and exclusive
modes correspond to the types of locks previously described. Default mode informs the
DBMS to use implicit locking. The explicit and implicit locks are held until the transaction is
committed or rolled back.
B.5
Managing Statements
RIS allows preparation of up to 40 statements (static and dynamic). RIS automatically

manages static statements. RIS limits the number of prepared static statements to less than
or equal to the MAX_STATIC_STMTS parameter. If preparation of more than 40 statements
is needed, RIS clears the least used static statement.
You must manage dynamic and cursor statements. The clear statement frees the resources
used by a statement. Clear prepared statements when they are no longer needed.
B.6
Order By Statement
Ordered results are sometimes useful but always expensive. Database systems do not
always sort efficiently and may need extensive tuning to avoid using temporary tables. For
small result sets, your application may be better able to sort items more quickly.
In general, be sure the application does not automatically use an order by clause in queries
when it is not needed.
B.7
Preparing Statements
In situations where SQL statements are executed repetitively, you can increase performance
by (1) executing the statement statically, or (2) splitting the dynamic execution into two
phases, prepare and execute. Preparing consists of syntactic checking and structure
initialization. You increase performance by preparing the statement once instead of multiple
times. When you use execute immediate, RIS prepares and executes the statement for each
use.
With static statements such as insert, update, delete, and select into, RIS automatically keeps
the most recently used static statements prepared. The exact number of static statements
RIS keeps prepared is dependent on the MAX_STATIC_STMTS parameter in the parameters
file.
For more information about configuring the MAX_STATIC_STMTS parameter, see the RIS
SQL Users Guide for 32-Bit Applications.
When using the same dynamic C SQL statement repetitively, you do not have to prepare the
statement for each use. Prepare the statement once, then execute it multiple times.
Remember that the schema used to prepare the statement must be the same schema used to
B-6
execute the statement.

Within RIS, it is possible to use dynamic Embedded SQL to separate the prepare and execute
phases so that the statement is prepared only once. Either of the following examples inserts
20 numeric values into a table, but the second is more efficient because the insert statement
is prepared only once.
Example
1
__________
for ( i=0; i<20; i++)
{
exec sql execute immediate "insert into table1 values(1)";
}
Example
2
__________
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 choosing between remote RIS connections (using RIS network functionality) and
RISNET connections (using DBMS vendor network connections), RIS connections are
generally faster. Vendor network connections have to be much more generic and are not as
efficient.
B.9
Schema Files
Information about schemas and databases is available by querying the ris5schemas and
ris5dbs data dictionary tables. The same information is available much more quickly by
using functions. For example, the RISget_schema_file() function retrieves all database and
schema information in the schema file.
B.10 Set Mode Verify

When table/view declarations are not used, you still have some control over the amount of
first-table-reference overhead. Since RIS allows some redefinition of data types for
experimental use of long character strings and unsupported data types, by default there is
complete verification of table definition in the database and in the RIS dictionary.
If you set mode verify off, RIS goes to the database system for the table/view definition,
but does not check the RIS dictionary tables. This is a performance versus capability tradeoff.
B.11 Temporary Tables

Because table creation is usually a high-overhead, slow operation, most DBMS designers
assume that creating a table involves analysis by a performance tuner to determine size and
usage characteristics of the table: how it is going to be used relative to other tables, which
disk it belongs on, and so forth.
Any application that creates tables on the fly takes severe performance hits with most
DBMSs and will run into other problems at sites with system administrators who do not
tolerate uncontrolled use of system resources.
While using the database system to create tables as needed may save programming time,
eventually performance or administrative problems become intolerable.
B.12 Transactions
Transactions allow a series of SQL statements to be grouped logically and ensures that all
database modifications are entirely committed or rolled back. A commit or rollback frees all
locks and closes all open cursors. Data definition statements such as create, drop, and alter
are always automatically committed. By default, data manipulation statements such as
select, insert, update, and delete are also automatically committed. Use the set transaction
statement to turn autocommit off. This ensures that data manipulation statements are not
automatically committed. You must then use the commit and rollback statements to
terminate a transaction. Any transaction in progress when the program terminates is rolled
back.
The autocommit mode makes it difficult to have more than one cursor open at a time. This is
because the commit for a select statement in autocommit mode is performed when the cursor
is closed.
Since a commit closes all open cursors, all other open cursors are also closed. To avoid this
problem, turn autocommit mode off.
Turning autocommit mode off also improves performance by eliminating the overhead of
committing after every statement. However, keep transactions as small as possible to avoid
blocking other users from accessing tables locked during the transaction.
B.13 Unique Record Identifiers

Some applications generate unique, sequential numbers to act as record identifiers
(MSLINK, for example). Some database systems provide nonstandard mechanisms for this
type of operation, but a generic mechanism is needed.
The following mechanism has been used, but should not be:
lock table x;
select max(id) + 1 from x;
insert into x values (my_id, my_values);
commit;
B-8
This mechanism demonstrates a couple of severe problems:

The table is locked for an extensive period of time which severely limits concurrent
usage in a multiuser environment.
Selecting max() usually involves checking every record of the table. This checking
becomes very slow as the number of records in the table increases.
Having a separate table for record identifiers is much more efficient. The table needs just
one record, but could have other records for other identifiers.
create
insert
insert
insert
table appl_x_record_ids (table_name char(31), last_id int);

into appl_x_record_ids values (states, 0);
into appl_x_record_ids values (cities, 0);
into appl_x_record_ids values (counties, 0);
To get the next unique record number, use the following general procedure:
Select the most recent value from the table.
select last_id into :old_id from table;
Try to update the table using the retrieved value.

update table set last_id = :old_id + 1 where last_id = :old_id;
If the update succeeds, then the selected value +1 is the next number. If the update fails,
then someone else selected the same value and has already updated the table. This indicates
that your number is out of date. Do not select again. Simply increment your variable and
try the update again.
For example, the next unique record number for the states table can be obtained as follows:
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 unique record number for the states table, use the following 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.
*/
B - 10
increment_and_retry:
++old_value;
goto try_again;
not_found:
/*
** Internal error:
*/
This query should not fail.
error:
/*
** Error handling.
*/
B.14 Using Indexes

The proper use of an index can improve the performance of most queries, but blind usage can
also hurt an application. An index has costs associated with it. One of these costs is space.
Indexes are separate entities that take up space in addition to the space required for the
table. Placing an index on every column of a table can easily take up several times the space
the table requires.
Large tables mean large indexes. If an index is used, disk I/O will be associated with
scanning the index. In the worst case, this situation can double the normal disk I/O incurred
without the index.
A heavy maintenance cost is another cost of indexing. Every time a new record is inserted,
every index in the table needs to be updated. Every time a value is changed in an indexed
column, every index on the column has to be updated.
These costs should not convince you to avoid an index, but understanding the costs is
important. When you decide to create an index, be certain that what is gained outweighs the
costs.
If an index cannot be used, the DBMS must do a full-table scan to execute a statement. This
scan is like selecting everything from the table. For example, use select count(*) from table
with no where clause to get a rough idea of the time it takes to do a full-table scan. An index
should identify a particular record or small set of records without having to do a full table
scan.
The usefulness of an index increases as the percentage of unique values in the column
increases. For example, if the MSLINK field is unique for every record, then MSLINK is a
perfect candidate for an index because as many queries as possible should have a where
MSLINK = ? clause in them. The index can be used to identify a unique row and, even with
a million records in the table, a single record identified by MSLINK is always quickly
available.
Conversely, if a field such as gender can have only two possible values (M/F), an index on
gender is worse than useless. Given a fairly equal distribution, the where gender=F clause
would examine the index to identify fully half of the records in the table, and then would
have to go get the records anyway. This situation demonstrates a query that in itself is not
sufficiently specific. The best way to improve performance is to make the query more
specific.
Even in this situation, a case can sometimes (though rarely) be made for an index. If you
know that 99% of the values are M and that your application is only interested in the F
values, an index would probably help.
To get an idea of the uniqueness of the values in column_x, try:
select (count(distinct column_x)/count(*))*100 from table_x;
100% is perfect. Even 50% is good. When the count starts dropping into the 10-20% range,
an index becomes less and less useful. When a concatenated index (two or more columns)
exists, the second column is not indexed. For example, if the concatenated index phone_idx is
created on (area_code, phone_number), then the query
select * from phones where phone_number = 123-4567;
does not use the index. A concatenated index cannot be used for a query unless the first
column of the index is in the where clause.
Therefore,
select * from phones where area_code = 205;
is ineffective because the phone_idx is used, but the uniqueness of area_code is low. The
index just adds overhead to the query.
The query
select * from phones where phone_number = 123-4567;
is also ineffective because the index cannot be used.

However, the query
select * from phones where phone_number = 123-4567
and area_code = 205;
is an effective use of the index.

When considering a concatenated index, keep the general rules of an index in mind. For
example, since area_code is not particularly unique, it does not add much to the uniqueness
of the record and is best omitted from the index.
The following indexing suggestions are also helpful.
When a table has only small amounts of data (up to about 50 small records), indexes
are usually worthless.
When loading many records into a table, it may be faster to drop indexes, load the data,
and re-create the indexes.
B - 12
When joining two tables, create indexes on the join columns. If your analysis indicates
that an index will not help, reconsider your design and ask why a join is being done
with those columns.
No index is useful without a where clause. Make your statements as specific as
possible.
B.15 Using Signals

SIGCLD is the only signal that RIS intercepts. RIS intercepts SIGCLD while the RIS client
process executes requests from an application. Once a request is completed, RIS restores the
handling of SIGCLD to its previous state. RIS intercepts SIGCLD to detect abnormally
terminated RIS client processes. This interception prevents the application from locking
while executing a statement.
When an application makes a request to the RIS client process, RIS first verifies that the RIS
client process exists. If it exists, RIS sets up a signal handler to intercept any SIGCLD
signals. If a SIGCLD signal is received indicating termination of one of the applications
child processes, RIS checks to see if the terminated process was the RIS client. If it was, RIS
returns an error. The application must terminate and reinitialize its connection to RIS
before executing any other RIS statements. If the child process that terminated is not the
RIS client process, RIS calls a user-defined signal handler for SIGCLD if one exists. Once
the client process has finished processing the applications request, RIS restores the handling
of SIGCLD to its previous handler.
B.16 Using SQL 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 inefficient. Query optimizers are not overly intelligent. They do not generally look
at the query values and realize that they could be condensed into something like
where c1 between 101 and 300;
OR
c1 > 100 and < 301 and c1 <> 207 and c1 <> 155;
Long statements require a lot of parsing. After that, too many OR clauses make an
optimizer decide that an index does not help.
The simpler your query, the better the chance of a fast response.
Appendix C: Language Configuration File C - 1
Appendix C
__________________________________________________________________________________________________________________________________________________
Language Configuration File
C-2
Appendix C: Language Configuration File
Appendix C: Language Configuration File C - 3
Appendix C
__________________________________________________________________________________________________________________________________________________
Language Configuration File

Before using RIS, you can change the language used by RIS. The RIS_get_language_name
function call in a RIS application sets the language to the specified value. The language map
information is located in the RIS language configuration file langs in the config directory of
the riscli product directory:
c:\Program Files\Common Files\Intergraph\ris05.nn\riscli\config\langs
You can also add new languages currently not supported by RIS as long as they are
supported by the operating system and database.
Defining RIS Language Settings for NT:
1.
From the Control Panel, double-click the International icon.
2.
Scroll through the list of languages available under the Language drop-down list.
3.
Select the language desired.
4.
Click OK. The system prompts you for the source of the operating system language
files.
5.
Reboot the system when the process is complete.
The following is the langs file currently supported by RIS. The format of this file is specified
by six (6) fields per line separated by a pipe (|) delimiter. Each line represents one language
mapping between RIS and the underlying operating system. The format is:
ris_lang_id|ris_lang_name|ris_lang_dir|os_lang_id|code_page|os_lang_name
ris_lang_id
Unique RIS language identifier. For every new

language added, this identifier is incremented.
ris_lang_name
Unique RIS language name to used by RIS

applications during RISinitialize().
ris_lang_dir
Directory name under the riscli/config directory. This

directory holds all RIS-specific language files
generated by Intergraphs UMS (User Message
System).
os_lang_id
Language identifier used by the underlying operating

system for the language you want RIS to use.
code_page
Language ANSI code page for the given os_lang_id.
C-4
Appendix C: Language Configuration File
os_lang_name
Language name used by the underlying operating

system for the language you want RIS to use.
Below is a sample language configuration file. Only languages with the same code page can
interoperate. If the two languages do not have the same code page then RIS gives an error of
RIS_E_INCOMPATIBLE_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 RIS Runtime and RIS Utilities D - 1
Appendix D
__________________________________________________________________________________________________________________________________________________
Redistribution of RIS Runtime and RIS Utilities
D-2
Appendix D: Redistribution of RIS Runtime and RIS Utilities
Appendix D
__________________________________________________________________________________________________________________________________________________
Redistribution of RIS Runtime and RIS Utilities

Redistribution rights and limitations are described in the product license agreement for the
RIS Development Platform.
When you develop an application with the RIS Development Platform, the application can
run only on systems that have the RIS Shared Component; therefore, you must redistribute
the RIS Shared Component with your application.
The following sections describe integrating the RIS Shared Component delivery into your
delivery procedure.
D.1 Directory Structure

The RIS Shared Component is delivered as part of the RIS Development Platform to the
c:\Program Files\risdp\shared directory. This directory includes files to be delivered to the
user system, and other setup and packaging files as described in the following section.
D.2 Setup Files

Use the following setup files to build the setup media for your application:
rissetup.lyt This file is the Microsoft Setup layout file for the RIS Shared Component
files. Append your applications .lyt file to this file.
Use the combined .lyt file to create a .inf file with the dsklayt2 utility (which is part of
the SETUPSDK product). Your setup program uses the .inf file to download the
necessary files to the end-users system.
rissetup.lib The functions in this library install the RIS Shared Component on the
end-users system. You must link your setup program with this library, and call the
following functions (in order):
a.
ReadInfFile();
Call this function once before calling any other setup functions for the RIS Shared
Component.
D-4
b.
SetupRIS();
This function determines the version of the RIS Shared Component that is already
installed, if any. You must use the value returned by this function as input to the
RegEdtRIS function.
Status
Returns
______________
0
1
2
c.
Existing version is newer than your version. RIS shared

component is not loaded.
Existing version is older, or the same date as your version.
RIS Shared Component is loaded.
Existing version not found. RIS Shared Component is loaded.
CopyFilesInCopyList();
This function downloads your application files and the RIS Shared Component
files (if necessary).
d.
RegEdtRIS(int action, char *listEntry);

This function edits the registry for RIS and adds the RIStcpsrService into
Services.
Keyword/Identifier
__________________
Description
___________
action
listEntry
Return value from the SetupRIS function.

String that identifies the name and version of your
application. For example: MYAPP\\01.00.00.00
risrem.lib The functions in this library remove the RIS Shared Component from the
system. Link your application remove program with this library. To remove the RIS
Shared Component in case of an error, link your setup program with this library.
a.
RegRemoveRIS(HINSTANCE remInstance, char *listEntry);

Keyword/Identifier
__________________
Description
___________
remInstance
listEntry
Removal process instance for the application.

Entry in the RefList field for the application.
This function removes your applications entry from the RefList field in the RIS
Shared Component registry key.
Status
Returns
______________
0
1
b.
RefList field is not empty.

RefList field is empty.
RemoveRIS(HINSTANCE remInstance, int flag);
This function removes the RIS Shared Component services, files, and registry
entries.
Keyword/Identifier
__________________
Description
___________
remInstance
flag
Removal process instance for the application.

Return value from the RegRemoveRIS function.
readme1.txt This uncompressed README file contains the RIS product name and
version.
The primary purpose of this file is to keep track of the RIS Shared Component version,
but you can add information from the RIS README file if it would be useful to the
end-user.
manifes1.txt This uncompressed ASCII file lists the files that are delivered with the
RIS Shared Component. You must integrate this file into the manifest file for your
application.
D.3 Installing the RIS Shared Component

The installation procedure does the following:
1.
Installs the required files on the users file system (after first checking to make sure
that the version being installed is the same or newer than any existing version) and if
an older version is found, it is removed.
2.
Adds information to the registry.
3.
Installs the RIS TCP service, and starts it. This service lets remote applications and/or
clients connect to other servers on the system.
4.
Creates a RIS program group, which contains various help and executable utilities.
Location on File System

RIS Shared Component is installed to the location specified in the registry entry:
Program Files\Common Files\Intergraph\RIS\<Major.Minor>
The installation procedure examines the system PATH variable to see if it contains the
\Program Files\Common Files\Intergraph directory. If the PATH does not contain this
directory, the installation procedure appends \Program Files\Common Files\Intergraph to
the system PATH.
D-6
Registry Information
The RIS Shared Component puts information into the System Registry to indicate its
presence on the system. The component installation procedure creates the key
HKEY_LOCAL_MACHINE\Software\Intergraph\RIS\<Major.Minor>
and adds the following values:

Description
InstallDate
PathName
SoftwareType
IDNumber
RelDate
Version
RefList
The RefList entry facilitates removal of the shared component. All products that use the RIS
Shared Component must add themselves to this reference list (with the RegEdtRIS function)
during installation, and must remove themselves from the list (with the RemoveRIS function)
during removal.
Any product that wants to remove a shared component can do so only if the reference list for
the shared component is empty. The RefList consists of a semicolon-separated list of
products that use the shared component. The referencing product string has the format
<product_name>\<product_version> where this information is the same as the name\version
portion of the registry key for the product.
Glossary GL - 1
Glossary
__________________________________________________________________________________________________________________________________________________
GL - 2
Glossary
Glossary GL - 3
Glossary
__________________________________________________________________________________________________________________________________________________
accept
Receive input, such as characters, integers, or data buttons.

Also, confirming an element selection.
access
Perform actions necessary to use software.
activate
Change the state of an object or entity so that it accepts or

displays data.
ad hoc query
Query formulated at runtime by input from a user or by the

program itself.
address
Label, name, or number that identifies an exact storage

location in memory.
alias
An alternate label for a command, program, or database

entity such as a line added to the start-up file that lets you
start the software without having to key in the full pathname
each time you want to use the software.
ANSI
Acronym for American National Standards Institute, a

private organization that develops, maintains, and publishes
industry standards in the United States.
api
Acronym for application programmers interface.
application
System of programs or utilities designed to accomplish

specific tasks as requested by the user.
array
Data structure used to organize data into contiguous lists.
ASCII
American Standard Code for Information Interchange

character set.
association
A relationship between two or more objects.
associative
Having a relationship to another.
attribute
Characteristic of an element. See also parameter.
bar menu
Strip at the top of the screen that contains icons for selecting
commands.
bit mask
Numeric value in which each bit represents an on/off state.

Efficient way to store multiple boolean values in a single
variable, but cumbersome since you must manipulate
GL - 4
Glossary
individual bits to change the values. Each bit is usually

represented by a symbolic constant.
block
Unit of storage which usually equals the amount of data that

can be read from or written to the storage device. For
example, most disk drives read or write a minimum of 512
bytes. Therefore, the block size of most disk drives is 512
bytes.
buffer
Data area.
byte
Group of bits forming a unit of storage in a digital computer.

A byte usually consists of 8 bits but can contain more or fewer
depending on the model of computer. Bytes can also contain
error recognition information.
General-purpose, structured programming language

developed at Bell Labs in the early 1970s.
cache
To store frequently used information in a device that is faster

than the device it is usually stored in to improve performance.
For example, frequently used information that is usually
stored on a hard disk drive can be cached in memory, which is
considerably faster.
catalog
Table of files, arranged systematically, containing required

and user-defined file attributes.
character
Alphabetic letter, digit, punctuation, or symbol.
client
Portion of a client/server-based application that requests

services.
collapse
Changing a form or window from the normal display to a

small icon representing the collapsed form or window. Also
called minimize.
command
Software that interacts with the user, obtaining user input

and then acting in a specified way based on that input. Each
icon on the menu accesses a command, although there could
also be additional commands accessed only by key-in.
command file
ASCII file containing the PPL (Parametric Programming

Language) statements needed to provide a user-specific
capability.
command line
Alphanumeric key-ins used to invoke an executable directly

from the operating system environment.
command name
Alphanumeric string that corresponds to a given command.
Glossary GL - 5
command string
Alphanumeric string that corresponds to a given command. A

command name.
communication
protocol
Rules or standards defining communication and data transfer

between two or more computer devices.
compile
Translate a program written in some programming language

into machine language or assembly language.
configuration file
A system defined and user configurable file containing

settings that control environment variables.
constant
Value that remains unchanged during a programs execution.
CPU
Acronym for Central Processing Unit.
cursor statement
Embedded SQL statement requiring a cursor data area; that

is, a select statement.
Data Definition
Language
(DDL) Subset of the ANSI SQL Standard statements which

defines the schemas and relations of a database.
data dictionary
Either a filed object space that contains information about the

classes that make up an application or a set of ASCII files
created by a utility called a data dictionary processor (ddp).
Data Manipulation
Language
(DML) Subset of the ANSI SQL Standard statements which

manipulate the data contained in a table.
data point
Point entered with the mouse or with a precision key-in,

which specifies a position in a drawing file.
data structure
Structure whose components are data objects. Data

structures are used to group logically related data.
data type
Classification of a data item as an integer, letter, or real

number.
database
Collection of comprehensive informational files having

predetermined structure and organization that can then be
communicated, interpreted, or processed by a specific
program.
database
administrator
User on a database or a schema defined on that user which

has complete access to all data defined on a database.
database privilege
Privilege granted to a schema regarding its access to a

database.
DB2
Relational database management system.
GL - 6
Glossary
DBA
Acronym for Database Administrator or DB Access.
DDL
Acronym for Data Definition Language.
debug
Locate and correct errors in the syntax or logic of program

source code.
DEC
Acronym for Digital Equipment Corporation.
declaration
Programming statement that provides information about a

variable, function, or data type but does not perform any
operation.
default schema
Schema in which statements are issued unless another

schema is specified (a RIS concept).
delimiter
Separating mark or space; a character or sequence of

contiguous characters that mark the end of a string of
characters.
design file
File containing graphic and text data. Also called a drawing

file.
development platform
Base or foundation of software on which application programs

can be built.
device
Nonaddressable component of a network, that is, a component

onto which a user cannot log, for example, tape drive, disk
drive, and floppy disk.
directory system
Directory structure that contains the information for a design

file.
disk
Round flat plate coated with a magnetic substance on which

data is stored.
DML
Acronym of Data Manipulation Language.
double precision
Data type which stores a range of floating point numbers.

The storage requirement and range of values are dependent
on the computer and compiler.
drawing file
File in which you place elements. Also called a design file.

element so you can see it move.
drop
To discontinue current status or association; to return to a

previous or more primitive status or association; to descend
levels.
dynamic SQL
statement
Embedded SQL statement that is not known until the

program is executed.
Glossary GL - 7
entity
Graphic or descriptive component in a graphics file. Can also

mean a database table.
environment variable
Variable defined on or across invocations of a command shell.

Processes are given access to the information in these
variables by the operating system.
error handler
Subroutine or group of statements that are executed when an

error occurs, and are designed to react to the error.
error message
Description of an error found in a program.
Ethernet
Popular implementation of a local area network.
exception
Condition caused by an attempt to perform an erroneous

operation.
exception handler
Subroutine or group of statements that are executed when an

exception occurs, and are designed to react to the exception.
Also known as an error handler.
executable
Program that has been written in or translated into, a

machine language that is ready for execution by the
computer.
exit
To terminate a job or process.
field
Any of the data grouped together in a record (also known as

an attribute or column). Also, a gadget allowing text entry on
a form.
file
Collection of logical records stored as a unit.
filename
User-defined name given to an interactively created file. The

name should be relevant to the contents of the file.
flag
A variable that can be set to indicate the presence or absence

of a certain condition.
float

floating point
notation
Notation describing a real number value. It consists of a

fractional value multiplied by an exponent.
floating point number
Real number value in floating point notation.
floppy disk
Flexible magnetic sheet used to store information.
GL - 8
Glossary
font
Complete set and style of the characters and symbols of a

typeface used for displaying text.
form
Rectangular display through which a user and an application

can communicate using gadgets.
form label
Unique integer identifier for a form, supplied by programmer.
function
Small segment of code written to complete a portion of a

larger task.
global variable
Programming variable that is recognized everywhere in a

program.
grant option
Relation privilege which gives a schema the ability to grant

relation privileges to other schemas.
graphic
Any symbol or method of visual communication that is not

text.
group
A collection of icons that represent documents and

applications within the Program Manager.
home directory
Directory recognized by the operating system as root of a

users own directory system. In UNIX, the environment
variable HOME is set to this directory.
host variable
Variable defined in host language source code and used in an

embedded SQL statement.
icon
Symbol that graphically identifies a command, application, or

document.
ID
Name composed of numbers or characters given for

identification purposes to a record. A record number.
identify
To indicate your selection on a form or graphics by placing a

data point on the item.
IGE
Object-based, UNIX-based Intergraph Graphics Environment.
include file
File that contains information such as symbolic constants,

structure definitions, variable declarations, and some
standard functions and macros.
index
Storage mechanism used to provide faster access to the rows

in a table.
indicator variable
Variable defined in host language source code and used in an

embedded SQL statement to indicate the usage of a NULL
value.
Glossary GL - 9
INFORMIX
INGRES
initialize
To set storage location, counter, variable, internal structures,

or the like to a beginning value.
integer
Value in the set of all positive and negative whole numbers

and zero. Also, a data type which stores a range of integer
values. Storage requirement and range of values are
dependent on the computer and compiler. Of or relating to
the process of entering data and receiving a response from the
computer.
interactive
Of or relating to the process of entering data and receiving a

response from the computer.
interface
Shared boundary through which the user and software

communicate.
I/ORL
Intergraph On-line Reference Library. Provides easy access

to Intergraph documentation on compact disk.
item
Unit of storage within a larger unit, such as a file in a

cabinet.
joining
Process of relating the data in two or more tables, possibly

restricted by some condition.
key-in
Information or command keyed in, rather than selected using

a mouse.
keyword
Word defined to have special meaning in a programming,

command, query language, or indexing.
LAN
Acronym for local area network.
library
Collection of subroutines.
linear
Having a single dimension; a line.
link
Combine one or more program segments, subroutines, or

library routine into a single executable program.
local area network
Computer networking scheme in which nodes which are

geographically local are connected to a network through
multiplexers, and networks of geographically remote nodes
are connected through routers.
log in
Enter the necessary information, such as a username and

password, to begin a session on a terminal.
GL - 10
Glossary
macro, RIS
Mechanism which allows strings to be assigned symbolic

names and to be replaced by their full values at a later time.
malloc
A function provided with the C programming language that

allocates space at runtime. The functions argument specifies
the amount of space required. This function returns a pointer
to the first address of the allocated memory.
mask
Value with bits set on and off to set up certain attributes.
memory
Device that can store data.
menu
Means for storing and selecting commands: icon-based,

function key, or paper.
mode
Particular functioning arrangement or condition. Also, the

behavior of a gadget.
model
Graphic representation or schema.
network
Interconnection of host computers and workstations that lets

them share data and control. The term network can mean the
devices that connect the system, or it can mean the connected
system.
node
Any nonaddressable component of a network; that is, any

component of the network onto which a user can locally or
remotely log.
noncursor statement
Embedded SQL statement that does not require a cursor data

area; that is, all statements other than the select statement.
NULL
Indicates no value.
on-line Help
Set of on-line, context sensitive files, that provide information

to the user about the capabilities of an application.
operating system
System programs that control the overall operation of a

computer system.
ORACLE
ORL
See I/ORL.
overview
Reduced resolution display of an image in a raster data file.

An overview is normally located in the raster data file itself.
parameter, RIS
Mechanism for representing an unknown value in a

subroutine call or a host variable in an embedded SQL
statement.
Glossary GL - 11
password
Word that is entered during log in that prevents unauthorized

people from using the file, software, or computer.
path
Sequence of directories leading to a file or a sequence of

menus leading to a command.
place
To create and position an element or object.
pointing
Moving the mouse to place the pointer over a menu command,

button, or an item on your screen.
pop-to-bottom
Move the specified form or window to the bottom of the

display stack. Also, the icon used to perform this command.
pop-to-top
Move the specified form or window to the top of the display

stack. Also, the icon used to perform this command.
portable
Designating a program that is easily executed (or can be

easily modified to execute) on multiple computers or software
systems.
preprocessor
Program that performs some type of calculation or

manipulations on the data in a file, usually in preparation for
another process.
privilege
Described by the ANSI SQL Standard. A privilege is a right

to access. For example: a relation privilege is a right to
access a relation (table or view) within a database.
process
Entity composed of a program or series of programs.
prompt
Text displayed by a command that tells you the inputs

expected by that command.
query
A search in a database.
raster
Pattern of horizontal scanning lines on the screen of a CRT:

input data causes the beam of the tube to illuminate the
correct pixels on these lines to produce the required
characters, curves, and so forth.
raster data file
File containing raster data (pixels). Raster data files can be

generated by optical scanner, video frame grabber, digital
camera, interactive paint package, and so forth. Intergraph
raster data files are characterized by specific data formats
which are identified in the file headers.
RDBMS
Acronym for Relational Database Management System, the

software that lets you organize, store, and manipulate data in
a database.
GL - 12
Glossary
real

record
Grouping of logically related data which can be manipulated

as a single entity. One or more records make up a file or a
table. Also known as a row or tuple.
relation
Table or view.
relation privilege
Privilege granted to a schema regarding its access to relations

in other schemas.
relational database
management system
Database management system that adheres to concepts

defined by the relational database model.
Relational Interface
System
Intergraph software system that provides a generic interface

for applications to access many popular relational database
management systems.
report
Standard and user-definable table format for information

queried from the database.
requester
See client.
resize
To change the size and position of a form or window.
resolution
Number of pixels of which a screen is composed. The greater

the number of pixels, the higher the resolution.
restore
To erase all editing changes on an image, leaving the original

image complete.
RIS
Acronym for Relational Interface System, the software that

lets different relational database management systems
communicate with each other.
root
Element upon which an associative element or macro

depends.
routine
Set of functions constructed to process specific information.
row
Grouping of logically related data which may be manipulated

as a single entity. One or more rows make up a file or table.
Also known as a record or tuple.
run
To execute a program or process.
runtime
Time at or during which a program or process is executed.
Glossary GL - 13
scalar data type
Simple data type. For example, integer, character, real.
scale
To enlarge or reduce the size of a defined element, modifying

only the dimensions, not the ratio among the pieces.
scan
To load a paper document into the image format using an

image scanner.
schema
Concept described by the ANSI SQL Standard as a collection

of tables and views. Within RIS, this collection corresponds to
the collection of tables and views within a database.
select
To activate a command. This can be done by the user or

software.
semaphore
Flag that prevents two or more UNIX processes from

accessing the same resource at the same time.
server
Computer, connected to a network, that provides services to

one or more devices on that network. A server can also refer
to a process that provides services to one or more client
(requester) processes locally or remotely.
set
Grouping of items that can be manipulated as a single item.
Shamrock
Intergraph graphical user-interface toolkit for Windows NT.
shared library
Library from which several programs can call routines. The

code for the called routines is not copied into the executable
program at the time the program is linked. Instead, it is read
in (on demand) at runtime. This results in smaller executable
programs.
shared memory
(shmem) UNIX shared memory; that is, memory whose

protection and access is global to more than one process.
shell
Body of commands providing interface to low level software.

For example, a UNIX shell provides an interface between
users and the UNIX kernel.
short
Data type which stores a range of integer values. Storage

requirement and range of values are dependent on the
computer and compiler.
signal
Mechanism provided by the UNIX operating system for

interprocess communication.
signal handler
Function designed to respond to a signal.
smallint
Data type which stores a range of integer values. Storage

requirement and range of values are dependent on the
computer and compiler.
GL - 14
Glossary
source file
File composed of ordinary C code plus code which uses some

additional language features needed to support Intergraphs
implementation of an object-oriented programming
environment. The object preprocessor (opp) processes source
files to handle the OM-specific language features.
SQL
Acronym for Structured Query Language.
SQL data type
Data types defined by the ANSI SQL Standard.
SQL terminator
Semicolon (;). It is used to terminate an Embedded SQL

statement.
sqlda structure
ANSI Standard SQL structure used to represent information

about the sqlvar structures in an Embedded SQL statement.
sqlvar structure
ANSI Standard SQL structure used to represent information

about a parameter (variable) in an Embedded SQL statement.
stack
Ordered layer of items such that the last in is first out.
statement
Word or group of words that has a specific meaning in a

programming language.
static SQL statement
Embedded SQL statement that is known when the program is

created and is compiled into that program.
string
Sequence of characters.
Structured Query
Language
Structured language designed for accessing relational

database management systems.
symbolic constant
Symbolic name for a value that does not change during a

programs execution. Used to make programs more readable.
syntax
Rules governing the structure and use of statements in a

language.
system
Collection of information and processes designed to interact to

complete a task.
table
Collection of data for quick reference, stored in sequential

locations in memory or printed as an array of rows and
columns of data items of the same type.
table, database
Collection of data rows (also known as tuples or records) and

columns (also known as attributes or fields). A unit of storage
described by the ANSI SQL Standard.
TCP/IP
Acronym for Transmission Control Protocol/Internet Protocol;

a network protocol.
Glossary GL - 15
toggle
To switch; to change between two alternatives. Also, a state

gadget that can be used to change between two alternatives.
transaction
Concept described by the ANSI SQL Standard. A transaction

is a group of SQL Statements that affect the database
simultaneously or can be canceled simultaneously.
tuple
Record or a row.
type
Type of data that a programming variable can contain.
type face
Design of a text font.
UNIX
General purpose operating system developed at Bell

Laboratories in the late 60s and early 70s.
user
Person who uses a computer.
user interface
End users means of communicating with the software,

including any of the means of entering values, selecting
commands, or locating elements. The menus and prompts are
examples of user interfaces.
value
Numeric or character data.
variable
Quantity that can assume any one of a set of values.
VAX/VMS
Computer/operating system combination. The VAX is a

family of processors manufactured and sold by Digital
Equipment Corporation. VMS is an operating system for the
VAX family.
version
The number associated with the specific release of a product.
view
Concept described by the ANSI SQL Standard, used to

combine tables or restrict access to columns in a table. A view
looks and acts like a table, but does not actually store data.
view, database
Concept described by the ANSI SQL Standard, used to

combine tables or restrict access to columns in a table. A view
looks and acts like a table, but does not actually store data.
virtual declaration
Mechanism in RIS which lets complex data types and address

expressions be used in Embedded SQL statements.
virtual table
Synonym for view.
wildcard
Symbol representing any string of characters.
XNS
Communication protocol used on the Ethernet network.
GL - 16
Glossary
Index IN - 1
Index
__________________________________________________________________________________________________________________________________________________
IN - 2
Index
Index IN - 3
Index
__________________________________________________________________________________________________________________________________________________
A
accessing
dictionary views A-7
aliases
exclude/include sequences A-4
object A-4
within RIS A-4
alter statement B-7
alter table form 6-3
American national standards institute 2-3
ANSI 2-3
api library 2-6
ascii strings 5-8
async statement 4-7
asynchronous execution
statements 2-24
autocommit mode B-7
B
before you begin 1-3
begin declare statement 4-8
binary data A-8
binary data type 3-3
binding
host variables 2-12
bit masks 5-27
blob data type 3-3
BLOBS
programming interface A-8
buffer pointer 5-39
C
caution symbol 1-5
char[ ] data type 4-8
char* data type 4-8
choose 1-4
clear async statement 4-10
clear cursor statement 2-21
clear statement B-5, 2-16, 2-18, 2-21, 4-9
clearing
cursors 4-9
dynamic statements 4-9
client process 5-20
client_parms structure 5-3

close cursor statement 2-21
close statement 2-16, 2-21, 4-11
closing cursors 4-11
columns, selecting 4-30
commit statement B-7
compiler directives
preprocessing statements 4-13, 4-18,
4-20, 4-24 4-26, 4-34
compiling 2-5
configuration file
language C-3
connecting to tables
granting and revoking authority A-5
conventions, document 1-5
CopyFilesInCopyList D-4
countp pointer 5-39
create schema form 6-3
create statement B-7
create table form 6-3
creating
tables, granting and revoking authority
A-5
creating applications 2-3
creating dictionaries A-6
cursor statements 2-14
cursors
clearing 2-21, 4-9
closing 2-21, 4-11
declaring 4-12
fetching 4-23
opening 2-21, 4-27
D
data
including owned by privileged accounts
A-3
inserting large A-8
long binary A-8
long text A-8
retrieving large A-8
updating large A-8
data definition form 6-3
IN - 4
Index
data type
RIS_BLOB A-8
RIS_TEXT A-8
databases
multiple schemas in A-6
retrieving information 5-35
datetime structure 5-3, 5-8 5-9, 5-11
dbca pointer B-4, 2-10
dblistp pointer 5-32
dbms_owner A-4
dbp pointer 5-23, 5-35
declare cursor statement 4-12
declare schema statement A-5
declare statement 2-16, 2-21
declaring
cursors 4-12
host variables 4-19
tables B-3
variables 4-8, 4-19
views B-3
virtual variables 4-19
define statement 4-13
definition of schema in RIS 5 A-3
delete statement B-5, B-7
describe statement 2-18, 2-21, 4-14
dictionary
adding schemas to A-6
creating A-6
creation A-6
objects A-6
shared A-6
views
accessing from application A-7
information in A-7
dictionary access form 6-3
display form functions 6-11
displayed forms functions 6-10
document conventions 1-3
double data type 4-8
drop schema form 6-3
drop statement B-7
drop table form 6-3
dropping schemas A-6
dsklayt2 D-3
dynamic SQL statements
ANSI standard 2-4
future changes 2-4
dynamic statements 2-14
clearing 4-9
cursor 2-21
executing 4-21 4-22
dynamic statements (continued)

noncursor 2-18
parameterizing 2-12, 2-19
preparing 4-28
E
else statement 4-18
embedded loading
using risloddes for 7-3
using risulddes for 7-4
Embedded SQL statements 2-14, 4-3, 4-21,
4-31
async 4-3, 4-7
begin declare 4-3, 4-8
C language source code 2-4
clear 4-3, 4-9
clear async 4-3, 4-10
close 4-3, 4-11
declare cursor 4-3, 4-12
define 4-4, 4-13
definition 2-4
describe 4-4, 4-14
else 4-4, 4-18
end declare 4-4, 4-19
endif 4-4, 4-20
execute 4-4
execute immediate 4-4, 4-22
fetch 4-4, 4-23
ifdef 4-4, 4-24
ifndef 4-4, 4-25
include 4-4, 4-26
open 4-4, 4-27
prepare 4-5, 4-28
preprocessor 2-5
quick reference 4-3
report error 2-9, 4-5, 4-29
riscpp.exe 2-5
select into 4-5, 4-30
sql 4-5
test completion 4-5, 4-32
UMS library 2-5
undef 4-5, 4-34
wait completion 4-5, 4-35
whenever 4-5, 4-36
enable_dbms 5-27
end declare statement 4-19
endif statement 4-20
END_OF_DATA 2-9
environment variable
RIS_LANGUAGE 2-5
Index IN - 5
erase form functions 6-12

error handling B-3, 2-9
errors
database-specific 2-10
dbca pointer 2-10
END_OF_DATA 2-9
handling 4-36
report error statement 2-9, 4-29
rissqlca structure 2-9
sqlca structure 2-9
sqlcode field 2-9
SQLCODE variable 2-9
sqlerrm field 2-9
sqlerrmc field 2-9
sqlerrml field 2-9
whenever clause 2-9, 4-36
example programs
for forms 6-4
for functions 5-7
for loading and unloading 7-5
for SQL 4-6
exceptions 2-9, 4-36
exclude form 6-3
exclude/include sequences A-4
exec sql prefix 2-14, 4-31
execute immediate statement B-5, 2-19,
4-22
execute statement 2-18, 4-21
execution of SQL statements 4-31
dynamic B-5, 4-21 4-22
static B-5
F
fetch statement 2-16, 2-21, 4-23
fetching cursors 4-23
float data type 4-8
forms
alter table form 6-3
create schema form 6-3
create table form 6-3
data definition form 6-3
dictionary access form 6-3
display functions 6-11
displayed functions 6-10
drop schema form 6-3
drop table form 6-3
erase functions 6-12
error code 6-11 6-12
example programs 6-4
exclude form 6-3
include file 6-4
forms (continued)
include files 6-3
include form 6-3
initialize 6-4
libraries 6-3
modify DB2 password form 6-3
modify node info form 6-3
modify schema password form 6-3
ris database form 6-3
RIS schema manager 6-3
RISforms.h include file 6-4
RISfrm_alter_table_form_displayed 6-10
RISfrm_create_schema_form_displayed
6-10
RISfrm_create_table_form_displayed
6-10
RISfrm_data_def_form_displayed 6-10
RISfrm_db2pass_form_displayed 6-10
RISfrm_dict_access_form_displayed 6-10
RISfrm_display_alter_table_form 6-11
RISfrm_display_create_schema_form
6-11
RISfrm_display_create_table_form 6-11
RISfrm_display_data_def_form 6-11
RISfrm_display_db2pass_form 6-11
RISfrm_display_dict_access_form 6-11
RISfrm_display_drop_schema_form 6-11
RISfrm_display_drop_table_form 6-11
RISfrm_display_exclude_form 6-11
RISfrm_display_include_form 6-11
RISfrm_display_locate_client_form 6-11
RISfrm_display_node_info_form 6-11
RISfrm_display_ris_dbs_form 6-11
RISfrm_display_schema_access_form
6-11
RISfrm_display_schema_definition_form
6-11
RISfrm_display_schema_file_form 6-11
RISfrm_display_schema_info_form 6-11
RISfrm_display_schema_mgr_form 6-11
RISfrm_display_schpass_form 6-11
RISfrm_display_set_form 6-11
RISfrm_display_table_info_form 6-11
RISfrm_drop_schema_form_displayed
6-10
RISfrm_drop_table_form_displayed 6-10
RISfrm_erase_alter_table_form 6-12
RISfrm_erase_create_schema_form 6-12
RISfrm_erase_create_table_form 6-12
RISfrm_erase_data_def_form 6-12
RISfrm_erase_db2pass_form 6-12
IN - 6
Index
forms (continued)
RISfrm_erase_dict_access_form 6-12
RISfrm_erase_drop_schema_form 6-12
RISfrm_erase_drop_table_form 6-12
RISfrm_erase_exclude_form 6-12
RISfrm_erase_include_form 6-12
RISfrm_erase_locate_client_form 6-12
RISfrm_erase_node_info_form 6-12
RISfrm_erase_ris_dbs_form 6-12
RISfrm_erase_schema_access_form 6-12
RISfrm_erase_schema_definition_form
6-12
RISfrm_erase_schema_file_form 6-12
RISfrm_erase_schema_info_form 6-12
RISfrm_erase_schema_mgr_form 6-12
RISfrm_erase_schpass_form 6-12
RISfrm_erase_set_form 6-12
RISfrm_erase_table_info_form 6-12
RISfrm_exclude_form_displayed 6-10
RISfrm_include_form_displayed 6-10
RISfrm_initialize 6-4
RISfrm_init_parms data type 6-4
RISfrm_locate_client_form_displayed
6-10
RISfrm_node_info_form_displayed 6-10
RISfrm_ris_dbs_form_displayed 6-10
RISfrm_schema_access_form_displayed
6-10
RISfrm_schema_definition_form_displayed
6-10
RISfrm_schema_file_form_displayed
6-10
RISfrm_schema_info_form_displayed
6-10
RISfrm_schema_mgr_form_displayed
6-10
RISfrm_schpass_form_displayed 6-10
RISfrm_set_form_displayed 6-10
RISfrm_table_info_form_displayed 6-10
schema definition form 6-3
schema file form 6-3
schema information form 6-3
schema manager 6-3
schema manager form 6-3
secure schema access form 6-3
set form 6-3
Set Functions 6-9
table information form 6-3
Forms Functions Error Handling 6-13
free function 5-23, 5-35
functions 5-3
free 5-35
include files 5-7
libraries 5-7
load 7-31
RISascii_to_datetime 5-8
RISdatetime_to_ascii 5-9
RISget_ansi_mode 5-13
RISget_app_version 5-14
RISget_async_stmts 5-15
RISget_autocommit_mode 5-17
RISget_autorename_mode 5-18
RISget_blankstrip_mode 5-19
RISget_client_location 5-20
RISget_current_stmt_schema_name
5-22
RISget_dbca 5-25
RISget_db_info 5-4, 5-23
RISget_default_schema_name 5-26
RISget_enabled_databases 5-27
RISget_language_name 5-29
RISget_parameters 5-30
RISget_risca 5-31
RISget_ris_sqltype_code 5-44
RISget_ris_sqltype_string 5-45
RISget_schema_file 5-32
RISget_schema_file_location 5-37
RISget_schema_info 5-35
RISget_schema_names 5-39
RISget_schema_transactions 5-42
RISget_sqlcode 5-46
RISget_verify_mode 5-47
RISinitialize B-4, 5-48
RIS_loader 7-31
RISlocate_client 5-49
RISlocate_schema_file 5-51
rislod_fprint 7-32
rislod_print 7-33
RISrestore_schema_file_checksum 5-53
RISstart_client 5-54
RISstop_client 5-55
RISterminate B-4, 5-56
risuld_fprint 7-33
risuld_print 7-34
RIS_unloader 7-31
unload 7-32
G
GRANT CONNECT TO A-5
Index IN - 7
GRANT RESOURCE TO A-5

GRANT SCHEMA TO A-6
grantee
granteep pointer 5-32, 5-35
H
handling errors 4-36
Help
using on-line 1-5
host variables
binding 2-12
declaring 2-11, 4-8, 4-19
examples 2-11
I
identifiers
record B-7
identify 1-4
ifdef statement 4-24
ifndef statement 4-25
include files
for forms 6-3
for functions 5-7
for loading and unloading 7-4
for SQL 4-6
ris.h 5-27
rislimit.h 5-39
RISlimits.h 5-39
include form 6-3
include sequences A-4
include statement 4-26
including data owned by privileged accounts
A-3
indexes
with same name A-4
indexing
proper use of B-10
indicator variables 2-12
initializing B-4
explicit B-4
insert statement B-5, B-7, 2-19
inserting large data A-8
installing the RIS shared component D-5
int data type 4-8
introduction 2-3
K
key in 1-4
L
language configuration file C-3
libraries 2-5
for forms 6-4
for functions 5-7
for loading and unloading 7-4 7-5
for SQL 4-6
linking 2-5
load
definition 7-3
load and unload
include files 7-4
libraries 7-5
load and unload example programs 7-5
lock tables statement B-4
locking B-4
explicit B-4
implicit B-4
table 2-23
locks B-4
exclusive B-4
shared B-4
types B-4
long binary data A-8
long text data A-8
M
macros 5-27
malloc 4-16, 5-23, 5-32, 5-35
managing statements B-5
manifes1.txt D-5
MAX_STATIC_STMTS parameter B-5
MAX_TRANSACTIONS 2-24
message boxes 2-6
modes
autocommit B-7
setting verify B-6
modify DB2 password form 6-3
modify node info form 6-3
modify schema password form 6-3
mouse 1-3
multiple transactions 2-23
N
names, aliases A-4
noncursor statements 2-14
not null keywords 2-12
note symbol 1-5
NULL values 2-12
IN - 8
Index
O
object files 2-5
objects
aliases A-4
dictionary A-6
of different owners within a schema A-3
ownership A-3
sharing among schemas A-3
on-line Help 1-5
on-line help 2-4
open cursor statement 2-21
open statement 2-16, 2-21, 4-27
opening
cursors 4-27
operators
UNION and UNION ALL A-3
order by statements B-5
ownership of objects A-3
P
parameterizing dynamic statements 2-19
using a question mark (?) 2-12
parameters
MAX_STATIC_STMTS B-5
parameters file B-5, 4-31, 5-37, 5-49, 5-51
parms file 5-51
parts of the Help window 1-5
passwords
RIS A-5
stored for schema A-5
PATH D-6
pc conventions 1-5
performance considerations B-3
pointers
buffer 5-39
countp 5-39
dbca B-4
dblistp 5-32
dbp 5-23, 5-35
granteep 5-32, 5-35
risca B-4
schemap 5-35
schlistp 5-32
prepare statement 2-18, 2-21, 4-28
preparing dynamic statements 4-28
preparing statements B-5
preprocessing statements
compiler directives 4-13, 4-18, 4-20,
4-24 4-26, 4-34
preprocessor 2-5
file extension 2-5
preprocessor (continued)
graph 2-7
invoking 2-5
options 2-5
return value 2-5
privileged accounts
including data owned by A-3
program interface 2-3
programming notes B-3
Q
queries
changing object names A-6
quick reference 4-3
R
RDBMS 2-3
logins A-5
security tracking A-5
versions, compatible with RIS 5 A-3
ReadInfFile D-3
readme1.txt D-5
record identifiers B-7
redistribution of RIS runtime and RIS
utilities D-3
RegEdtRIS D-4
RegRemoveRIS D-5
relational database management system
2-3
relational interface system 2-3
RemoveRIS D-5
report error statement B-4, 2-9, 4-29
reporting errors 4-29
requesting information
errors 4-29
input parameters 4-14
output results 4-14
required products 2-4
reset 1-4
retrieving
large data A-8
REVOKE CONNECT FROM A-5
REVOKE RESOURCE FROM A-5
REVOKE SCHEMA FROM A-6
RIS
compatibility 2-3
definition 2-3
embedded SQL 2-3
forms functions 6-3
initializing B-4
introduction to 2-3
Index IN - 9
RIS (continued)
load 7-3
object ownership A-3
password storage A-5
preprocessor 2-5
program interface 2-3
related documentation 1-3
schema manager 6-3
shared component directory structure
D-3
supported platforms 2-4
terminating B-4
unload 7-3
versions
interoperability A-11
RIS client processes B-4
termination of B-12
RIS connections B-6
ris database form 6-3
RIS Development Platform
capabilities provided 2-3
RIS embedded SQL statements 4-6
risalpha utility A-12
RISascii_to_datetime 5-8
RIS_BLOB A-8
ris_blob 3-3
risca pointer B-4, 2-9
RISCLI 5-37
riscpp.exe 2-5
file extension 2-5
graph 2-7
invoking 2-5
libraries 2-5
linking 2-5
object files 2-5
options 2-5
return value 2-5
RISdatetime_to_ascii 5-9
ris_db2_info structure 5-4
ris_db_info structure 5-4
risdbms_indexes A-7
risdbms_tables A-7
risdbms_views A-7
risforms.lib library 2-6
RISfrm_alter_table_form_displayed 6-10
RISfrm_create_schema_form_displayed
6-10
RISfrm_create_table_form_displayed 6-10
RISfrm_data_def_form_displayed 6-10
RISfrm_db2pass_form_displayed 6-10
RISfrm_dict_access_form_displayed 6-10
RISfrm_display_alter_table_form 6-11
RISfrm_display_create_schema_form 6-11
RISfrm_display_create_table_form 6-11
RISfrm_display_data_def_form 6-11
RISfrm_display_db2pass_form 6-11
RISfrm_display_dict_access_form 6-11
RISfrm_display_drop_schema_form 6-11
RISfrm_display_drop_table_form 6-11
RISfrm_display_exclude_form 6-11
RISfrm_display_include_form 6-11
RISfrm_display_locate_client_form 6-11
RISfrm_display_node_info_form 6-11
RISfrm_display_ris_dbs_form 6-11
RISfrm_display_schema_access_form 6-11
RISfrm_display_schema_definition_form
6-11
RISfrm_display_schema_file_form 6-11
RISfrm_display_schema_info_form 6-11
RISfrm_display_schema_mgr_form 6-11
RISfrm_display_schpass_form 6-11
RISfrm_display_set_form 6-11
RISfrm_display_table_info_form 6-11
RISfrm_drop_schema_form_displayed 6-10
RISfrm_drop_table_form_displayed 6-10
RISfrm_erase_alter_table_form 6-12
RISfrm_erase_create_schema_form 6-12
RISfrm_erase_create_table_form 6-12
RISfrm_erase_data_def_form 6-12
RISfrm_erase_db2pass_form 6-12
RISfrm_erase_dict_access_form 6-12
RISfrm_erase_drop_schema_form 6-12
RISfrm_erase_drop_table_form 6-12
RISfrm_erase_exclude_form 6-12
RISfrm_erase_include_form 6-12
RISfrm_erase_locate_client_form 6-12
RISfrm_erase_node_info_form 6-12
RISfrm_erase_ris_dbs_form 6-12
RISfrm_erase_schema_access_form 6-12
RISfrm_erase_schema_definition_form 6-12
RISfrm_erase_schema_file_form 6-12
RISfrm_erase_schema_info_form 6-12
RISfrm_erase_schema_mgr_form 6-12
RISfrm_erase_schpass_form 6-12
RISfrm_erase_set_form 6-12
RISfrm_erase_table_info_form 6-12
RISfrm_exclude_form_displayed 6-10
RISfrm_include_form_displayed 6-10
RISfrm_initialize 6-4
RISfrm_init_parms data type 6-4
IN - 10
Index
RISfrm_locate_client_form_displayed 6-10
RISfrm_node_info_form_displayed 6-10
RISfrm_ris_dbs_form_displayed 6-10
RISfrm_schema_access_form_displayed
6-10
RISfrm_schema_definition_form_displayed
6-10
RISfrm_schema_file_form_displayed 6-10
RISfrm_schema_info_form_displayed 6-10
RISfrm_schema_mgr_form_displayed 6-10
RISfrm_schpass_form_displayed 6-10
RISfrm_set_form_displayed 6-10
RISfrm_table_info_form_displayed 6-10
RISget_ansi_mode 5-13
RISget_app_version function 5-14
RISget_async_stmts 5-15
RISget_autocommit_mode 5-17
RISget_autorename_mode 5-18
RISget_blankstrip_mode 5-19
RISget_client_location 5-20
RISget_current_stmt_schema_name 5-22
RISget_dbca 5-25
RISget_db_info 5-4, 5-23
RISget_default_schema_name 5-26
RISget_enabled_databases 5-27
RISget_language_name 5-29
RISget_parameters 5-30
RISget_risca 5-31
RISget_ris_sqltype_code 5-44
RISget_ris_sqltype_string 5-45
RISget_schema_file 5-32
RISget_schema_file_location 5-37
RISget_schema_info 5-35
RISget_schema_names 5-39
RISget_schema_transactions 5-42
RISget_sqlcode 5-46
RISget_verify_mode 5-47
ris_grantee_info structure 5-6
risgui utility A-12
ris.h 5-27
ris_ifx_info structure 5-4
ris_igs_info structure 5-4
RISinitialize B-4, 5-48
RIS_LANGUAGE 2-5
rislduld.lib library 2-6
ris.lib library 2-6
rislimit.h include file 5-39
RISlimits.h 5-39
RIS_loader functions 7-31
RISlocate_client 5-49
RISlocate_schema_file 5-51
rislod 7-3
interfacing with 7-31
risloddbs structure 7-5, 7-8
input fields 7-8
risloddes structure 7-3, 7-5, 7-31
default values 7-27
directions for using 7-27
input fields 7-6
loading RIS objects 7-28
output fields 7-7
printing fields 7-32 7-33
printing status of 7-28
return information 7-3
rislodgrant structure 7-8, 7-16
input fields 7-16
output fields 7-16
rislodindx structure 7-8, 7-15
input fields 7-15
output fields 7-15
rislodsch structure 7-5, 7-8
input fields 7-8
output fields 7-12
rislodtab structure 7-8, 7-13
default values 7-27
input fields 7-13
output fields 7-13
rislodview structure 7-8, 7-14
input fields 7-14
output fields 7-14
RISNET connection B-6
ris_object A-7
ris_ora_info structure 5-4
ris_parameters structure 5-6
ris_rdb_info structure 5-4
risrem.lib D-4
RISrestore_schema_file_checksum 5-53
ris_schema_info structure 5-7
rissetup.lib D-3
rissetup.lyt D-3
rissqlca structure B-4
RISstart_client 5-54
RISstop_client 5-55
RIS_SUCCESS 6-11 6-12
RISterminate B-4, 5-56
RIS_TEXT A-8
ris_text 3-6
risulddbs structure 7-17
risulddes structure 7-4, 7-17, 7-32
directions for using 7-27
input fields 7-18
Index IN - 11
risulddes structure (continued)

output fields 7-18
printing fields 7-33 7-34
return information 7-4
risuldgrant structure 7-19, 7-26
input fields 7-26
output fields 7-26
risuldindx structure 7-19, 7-25
input fields 7-25
output fields 7-25
risuldsch structure 7-17, 7-19
input fields 7-19
output fields 7-22
risuldtab structure 7-19, 7-23
input fields 7-23
output fields 7-23
risuldview structure 7-19, 7-24
input fields 7-24
output fields 7-24
RIS_unloader functions 7-31
risunlod 7-4
interfacing with 7-32
rollback statement B-7
rows, selecting 4-30
S
schema
administrator
schema definition form 6-3
schema file 5-23, 5-32, 5-35, 5-37 5-39,
5-51 5-53
schema file form 6-3
schema files B-6
schema information form 6-3
schema manager 6-3
schema manager form 6-3
schema_file_parms 5-6
schemap pointer 5-35
schemas
adding to dictionary A-6
definition in RIS 5 A-3
dictionary creation A-6
dropping A-6
multiple in databases A-6
multi-user A-5
objects of different owners within A-3
passwords stored for A-5
secure A-5
schemas (continued)
sharing objects among A-3
usernames stored for A-5
schlistp pointer 5-32
secure schema access form 6-3
secure schemas A-5
security A-5
tracking, RDBMS A-5
violations, including data without A-3
select 1-4
select into statement B-5, 4-30
select statement A-3, B-7
selecting rows and columns 4-30
semaphore sets B-4
sequences, exclude/include A-4
set database statement 5-27
set form 6-3
Set Functions 6-9
setting verify mode B-6
setup files D-3
SetupRIS D-4
SETUPSDK D-3
Shamrock DLL 2-6
shared component D-3
shared component location D-6
shared component registry information D-7
shared dictionaries A-6
shared memory segments B-4
short data type 4-8
signals
SIGCLD B-12
using B-12
software changes A-3
software, required 2-4
SQL
definition 2-3
executing static statements 4-31
include files 4-6
libraries 4-6
SQL Interface 2-24
SQL statement
hints B-12
SQL statements
alter B-7
clear B-5
commit B-7
create B-7
cursor B-5
delete B-5, B-7
drop B-7
IN - 12
Index
SQL statements (continued)

dynamic B-5
exclusive B-5
execute immediate B-5
executing B-5
example B-6
insert B-5, B-7
lock tables B-4 B-5
managing B-5
dynamic B-5
static B-5
preparing B-5
example B-6
repetitive use of B-5
report error B-4
rollback B-7
select B-7
select into B-5
share B-5
static B-5
update B-5, B-7
whenever B-4
sqlca structure 2-9
sqlcode field 2-9
SQLCODE variable 2-9
sqlda structure 4-14
sqlda structures 2-19
sqlerrm field 2-9
sqlerrmc field 2-9
sqlerrml field 2-9
sqlvar structure 4-14 4-15
sqlvar structures 2-19
statement
declare schema A-5
select A-3
statements
set database 5-27
statements, executing 4-31
static cursor statements 2-16
static noncursor statements 2-15
static statements 2-14
status returns B-3
structured query language 2-3
structures
client_parms 5-3
datetime 5-3, 5-8 5-9, 5-11
miscellaneous
for RIS functions 5-3
ris_db2_info 5-4
ris_db_info 5-4
ris_grantee_info 5-6
structures (continued)
ris_ifx_info 5-4
ris_igs_info 5-4
risloddbs 7-5, 7-8
risloddes 7-3, 7-5, 7-27, 7-31 7-33
rislodgrant 7-8, 7-16
rislodindx 7-8, 7-15
rislodsch 7-5, 7-8
rislodtab 7-8, 7-13
rislodview 7-8, 7-14
ris_ora_info 5-4
ris_parameters 5-6
ris_rdb_info 5-4
ris_schema_info 5-7
rissqlca B-4
risulddbs 7-17
risulddes 7-4, 7-17, 7-32 7-34
risuldgrant 7-19, 7-26
risuldindx 7-19, 7-25
risuldsch 7-17, 7-19
risuldtab 7-19, 7-23
risuldview 7-19, 7-24
schema_file_parms 5-6
sqlda 4-14
sqlvar 4-14 4-15
symbol
caution 1-5
note 1-5
warning 1-5
T
table information form 6-3
table locking 2-23
tables
creating logical groupings A-3
declaring B-3
preparing B-7
temporary B-7
with same name A-4
with same name in one schema A-4
terminating B-4
explicit B-4
test completion statement 4-32
text data A-8
text data type 3-3
transactions B-7
U
UMS DLL 2-6
UMS library
embedded SQL statements 2-5
Index IN - 13
undef statement 4-34

UNION A-3
UNION ALL A-3
unload
definition 7-3
update statement B-5, B-7
updating large data A-8
usernames, stored for schema A-5
using binary data 3-3
using clause 2-12, 2-19
using indexes B-10
using on-line Help 1-5
using SQL statement wisely B-12
using text data 3-3
utilities
risalpha A-12
risgui A-12
V
values, dbms_owner A-4
variables
declaring 4-8, 4-19
host 2-11, 4-8, 4-19
virtual 4-8, 4-19
verify mode B-6
viewing on-line Help 1-5
views
declaring B-3
including data without A-3
with same name A-4
virtual variables 4-8, 4-19
W
wait completion statement 4-35
warning symbol 1-5
whenever statement B-4, 2-9, 4-36
WHERE clause A-7
ris_object condition A-7
win32api library 2-6
IN - 14
Index

Risprogg

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Risprogg

Загружено:

Авторское право:

Доступные форматы

RIS Programmers Guide

for 32-Bit Applications

Warranties and Liabilities

Before You Begin ..................................................................................................

Changes to the Software ..............................................................................

Parts of the Help Window ................................................................

Creating Applications with RIS ...........................................................................

Introduction to the RIS Development Platform .........................................

Static Noncursor SQL Statements ..................................................

Multiple Transactions ................................................................................

Using Binary and Text Data ................................................................................

Embedded SQL Reference ....................................................................................

Quick Reference ...........................................................................................

RIS Functions .......................................................................................................

Reference Structures ....................................................................................

RIS Forms Functions ............................................................................................

Include Files, Libraries, and Example Programs .......................................

Embedded Loading and Unloading of RIS Objects .............................................

Using risloddes for Embedded Loading ......................................................

risloddbs Structure ...........................................................................

risulddes Structures .....................................................................................

risuldsch Structure ...........................................................................

Directions for Using risloddes and risulddes ..............................................

Directions for Using risloddes ..........................................................

RIS_loader and RIS_unloader Embedded Functions .................................

Changes to This Version of RIS ..........................................................

RDBMS Versions ...............................................................................................

Programming Notes and Performance Considerations .....................

Declaring Tables/Views .....................................................................................

Language Configuration File ..............................................................

Redistribution of RIS Runtime and RIS Utilities ..............................

Directory Structure ............................................................................................

Before You Begin 1 - 1

Before You Begin

Before You Begin

Before You Begin 1 - 3

Before You Begin

1.1 Changes to the Software

1.2 Related Documentation

RIS SQL Users Guide for 32-Bit Applications

1.3 Document Conventions

Before You Begin

Before You Begin 1 - 5

1.4 Using On-line Help

Before You Begin

1.4.1 Parts of the Help Window

Before You Begin 1 - 7

Display a listing of the table of contents for

Locate information about a certain topic that

Take you back to the previous Help topics you

Display a sequential list of every Help topic

Display a dialog box used to retrieve partial or

View the previous topic in a series of related

View the next topic in a series of related

Before You Begin

Creating Applications with RIS 2 - 1

Creating Applications with RIS

Creating Applications with RIS

Creating Applications with RIS 2 - 3

Creating Applications with RIS

Creating Applications with RIS

Access IBM/MVS environments.

2.2 Products Needed to Use the RIS Development Platform