Guia Oficial N°07. Vel30RM

Velocis
Reference Manual
20-7203-1001
Trademarks
Centura, the Centura logo, Centura net.db, Centura Web Developer, Gupta, the Gupta
logo, Gupta Powered, the Gupta Powered logo, Fast Facts, Object Nationalizer, Quest,
QuickObjects, SQL/API, SQLBase, SQLBase Exchange, SQLConsole, SQLGateway,
SQLHost, SQLNetwork, SQLRouter, SQLTalk, and Team Object Manager, RDM, ROM,
and Velocis are trademarks of Centura Software Corporation and may be registered in the
United States of America and/or other countries. SQLWindows is a registered trademark
and TeamWindows, ReportWindows and EditWindows are trademarks exclusively used
and licensed by Centura Software Corporation.
Adobe is a trademark of Adobe Systems, Incorporated.
IBM, OS/2, NetBIOS, and AIX are registered trademarks of International Business
Machines Corporation.
UNIX is a registered trademark licensed exclusively by The Open Group.
SCO UNIX is a trademark of Santa Cruz Operation, Incorporated.
Microsoft is a registered trademark, and DOS, Windows, Windows NT, and Windows 95
are trademarks, of Microsoft Corporation.
Java and Solaris are trademarks of Sun Microsystems, Incorporated.
Microsoft, Internet Explorer, Internet Information Server, DOS, Win 32, Windows,
Windows NT, Windows 95 and Visual Basic are either registered trademarks or
trademarks of Microsoft Corporation in the United States of America and/or other
countries.
Novell is a registered trademark, and NetWare is a trademark, of Novell Incorporated.
All other product or service names mentioned herein are trademarks or registered
trademarks of their respective owners.
Copyright
Copyright  1999 by Centura Software Corporation. All rights reserved.
Velocis 3.0 Installation and Administration Guide
20-7301-1002
November 1999
Contents
Chapter 1 Introduction
1.1 Velocis Documentation................................................................................................ 1-1
1.1.1 About This Manual................................................................................................. 1-1
1.1.2 About the Function References in this Manual................................................... 1-3
1.1.3 Related Velocis Documents ................................................................................... 1-4
1.1.4 Document Conventions ......................................................................................... 1-5
1.2 Other Helpful Resources ............................................................................................. 1-5
Chapter 2 Velocis Utilities
admin................................................................................................................................... 2-2
dbcheck................................................................................................................................ 2-3
dbdefrag .............................................................................................................................. 2-5
dbfix ..................................................................................................................................... 2-7
dbimp................................................................................................................................... 2-9
dbreplay ............................................................................................................................ 2-13
dbstat ................................................................................................................................. 2-15
dchain ................................................................................................................................ 2-17
ddlproc .............................................................................................................................. 2-19
instodbc ............................................................................................................................. 2-22
instrds ................................................................................................................................ 2-23
keybuild............................................................................................................................. 2-24
prdbd ................................................................................................................................. 2-26
rds....................................................................................................................................... 2-27
rdsadm............................................................................................................................... 2-28
rsql...................................................................................................................................... 2-29
sddlp .................................................................................................................................. 2-37
vping .................................................................................................................................. 2-39
Chapter 3 SQL Decimal Value Manipulation Functions (BCD Prefix)
BCDAdd .............................................................................................................................. 3-2
BCDAllocEnv...................................................................................................................... 3-3
BCDAllocZBuf .................................................................................................................... 3-4
BCDCompare...................................................................................................................... 3-5
BCDDivide .......................................................................................................................... 3-6
BCDFreeEnv ....................................................................................................................... 3-7
BCDFreeZBuf...................................................................................................................... 3-8
BCDMultiply....................................................................................................................... 3-9
BCDPack............................................................................................................................ 3-10
BCDStatus ......................................................................................................................... 3-11
Contents i
BCDSubtract ..................................................................................................................... 3-12
BCDUnpack ...................................................................................................................... 3-13
Chapter 4 Dictionary Access API Functions (c_ Prefix)
(Alphabetical listing by function name).......................................................................... 4-2
Chapter 5 Customized Comparison Function Module Functions
(cmp Prefix)
cmpDescribeFcns................................................................................................................ 5-2
cmpFunction ....................................................................................................................... 5-4
cmpShutdown .................................................................................................................... 5-6
Chapter 6 Core API Functions (d_ Prefix)
(Alphabetical listing by function name).......................................................................... 6-2
Chapter 7 Extension Module Functions (em_ and Mod Prefix)
em_attach ............................................................................................................................ 7-2
em_call................................................................................................................................. 7-4
em_detach ........................................................................................................................... 7-7
em_getContext.................................................................................................................... 7-9
em_getHandle .................................................................................................................. 7-11
em_load ............................................................................................................................. 7-12
em_unload ........................................................................................................................ 7-14
ModCleanup ..................................................................................................................... 7-15
ModDescribeFcns............................................................................................................. 7-16
ModFunction .................................................................................................................... 7-18
ModInit.............................................................................................................................. 7-20
Chapter 8 Import and Export Filter Module Functions (ief Prefix)
iefCheck............................................................................................................................... 8-2
iefCleanup ........................................................................................................................... 8-4
iefDescribeFcns................................................................................................................... 8-5
iefFetch ................................................................................................................................ 8-7
iefInit.................................................................................................................................... 8-9
iefStore............................................................................................................................... 8-12
Chapter 9 Parameter List Functions (pl_ Prefix)
pl_alloc................................................................................................................................. 9-2
pl_count............................................................................................................................... 9-4
pl_del ................................................................................................................................... 9-5
pl_free .................................................................................................................................. 9-6
pl_get ................................................................................................................................... 9-8
pl_peek .............................................................................................................................. 9-10
ii Centura Velocis Reference Manual

pl_printf............................................................................................................................. 9-12
pl_put................................................................................................................................. 9-14
pl_putStruct ...................................................................................................................... 9-17
pl_seek ............................................................................................................................... 9-20
Chapter 10 Engine Resource Manager Functions (rm_ Prefix)
(Alphabetical listing by function name)........................................................................ 10-2
Chapter 11 Administration API Functions (s_ Prefix)
Chapter 12 SQL API Functions (SQL Prefix)
Chapter 13 SQL UDF Support Functions (SYS Prefix)
Chapter 14 UDF Module Functions (udf Prefix)
udfCheck ........................................................................................................................... 14-2
udfCleanup ....................................................................................................................... 14-4
udfDescribeFcns ............................................................................................................... 14-5
udfFunc ............................................................................................................................. 14-7
udfInit ................................................................................................................................ 14-9
udfReset........................................................................................................................... 14-11
Chapter 15 UDP Module Functions (udp Prefix)
udpCheck .......................................................................................................................... 15-2
udpCleanup ...................................................................................................................... 15-4
udpDescribeFcns .............................................................................................................. 15-5
udpExecute ....................................................................................................................... 15-7
udpInit ............................................................................................................................. 15-10
udpMoreResults ............................................................................................................. 15-12
Chapter 16 SQL Date/Time Manipulation Functions (VAL Prefix)
VALPackDate ................................................................................................................... 16-2
VALPackTime................................................................................................................... 16-3
VALPackTimestamp........................................................................................................ 16-4
VALUnpackDate .............................................................................................................. 16-5
VALUnpackTime ............................................................................................................. 16-6
VALUnpackTimestamp .................................................................................................. 16-7
Contents iii
Chapter 17 Server Extension Toolkit Functions (C++ API)
17.1 Class Reference ........................................................................................................... 17-1
class DataDescriptor : public SeBase ............................................................................. 17-1
Constructor and Destructor ...................................................................................... 17-2
Member Functions...................................................................................................... 17-2
class ParmReceive : public SeBase ................................................................................. 17-4
Operators..................................................................................................................... 17-4
Member Functions...................................................................................................... 17-6
class ParmSend : public SeBase...................................................................................... 17-9
Operators..................................................................................................................... 17-9
Member Functions.................................................................................................... 17-10
class SeBase ..................................................................................................................... 17-12
Constructor and Destructor .................................................................................... 17-13
Operators................................................................................................................... 17-13
class ServerExtension : public SeBase.......................................................................... 17-17
Constructor and Destructor .................................................................................... 17-17
17.2 Macro Reference ....................................................................................................... 17-26
Macros ............................................................................................................................. 17-26
BEGIN_RPC_MAP ................................................................................................... 17-26
CREATE_EXPORTS ................................................................................................. 17-26
DECLARE_RPC_MAP............................................................................................. 17-29
END_RPC_MAP....................................................................................................... 17-29
ON_RPC .................................................................................................................... 17-29
Chapter 18 Velocis Data Types
18.1 Low-Level Database Programming ......................................................................... 18-1
18.2 SQL Programming ..................................................................................................... 18-3
18.3 Compound Velocis Data Types ................................................................................ 18-8
(Alphabetical listing by type name)............................................................................... 18-8
Chapter 19 Return Codes and Error Messages
19.1 Standard Return Codes ............................................................................................. 19-1
19.2 SQL-Specific Return Codes ..................................................................................... 19-25
19.2.1 General Codes Returned by SQL Functions................................................. 19-25
19.2.2 Detailed Codes Retrieved by the SQLError Function................................. 19-26
19.2.3 Codes Returned by SQL Value Manipulation Functions ........................... 19-48
19.3 Error Messages Returned by the sddlp Utility..................................................... 19-49
iv Centura Velocis Reference Manual

Tables
Table 1-1. Document Notational Conventions................................................................. 1-5
Table 2-1. Available Commands in the rsql Testing Utility ......................................... 2-31
Table 2-2. rsql Interface Control Commands ................................................................. 2-32
Table 10-1. Locations Where Certain Resource Manager Functions Can Be Called... 10-1
Table 12-1. Result Set Columns for SQLCDataColumn................................................ 12-13
Table 12-2. Result Set Columns for SQLColumns ......................................................... 12-20
Table 12-3. SQL Statement Type Indicators ................................................................... 12-31
Table 12-4. Result Set Columns for SQLForeignKeys................................................... 12-48
Table 12-5. Unsupported ODBC 2.0 Scalar Functions .................................................. 12-60
Table 12-6. Result Set Columns for SQLPrimaryKeys .................................................. 12-74
Table 12-7. Result Set Columns for SQLProcedures ..................................................... 12-77
Table 12-8. Result Set Columns for SQLShowPlan ....................................................... 12-93
Table 12-9. Access Methods for SQLShowPlan ............................................................. 12-94
Table 12-10. Result Set Columns for SQLSpecialColumns............................................. 12-97
Table 12-11. Result Set Columns for SQLStatistics.......................................................... 12-99
Table 12-12. Result Set Columns for SQLTables............................................................ 12-102
Table 17-1. Status Codes Defined by the SeStatus Enumeration................................... 17-1
Table 17-2. Correlation Between C++ Integral Types and DPL Types......................... 17-5
Table 18-1. Low-Level Data Type Definitions ................................................................. 18-2
Table 18-2. Low-Level Constant Definitions.................................................................... 18-3
Table 18-3. Low-Level Macro Definitions ........................................................................ 18-3
Table 18-4. ODBC C Function Argument Types ............................................................. 18-4
Table 18-5. SQL Support API Types.................................................................................. 18-4
Table 18-6. ODBC Core Data Type Definitions ............................................................... 18-5
Table 18-7. ODBC Extended Data Type Definitions ....................................................... 18-6
Table 18-8. Velocis-Specific Data Type Definitions......................................................... 18-6
Table 18-9. Mapping of Velocis SQL/ODBC Constants to C Data Types.................... 18-7
Table 18-10. Data Types for Parameter Items .................................................................. 18-20
Table 19-1. Standard (S_*) Return Codes Listed Numerically....................................... 19-1
Table 19-2. SQLError Detailed (err*) Return Codes Listed Alphabetically ............... 19-27
Table 19-3. sddlp Utility Error Messages ....................................................................... 19-49
Contents v
Chapter 1
Introduction
This book is the reference manual for Centura Velocis Database Server. It provides
complete descriptions of all Velocis utilities, functions, complex data types, and return
codes. Information on use of the functions and utilities can be found in the Velocis User’s
Guide.
1.1 Velocis Documentation

Velocis documentation is a four-manual set and includes this Reference Manual, the Velocis
User’s Guide, Velocis Language Guide and the Installation/Administration Guide.
1.1.1 About This Manual

The Reference Manual is organized as described below. Related Velocis documents are
discussed in section 1.1.3.
Chapter 2, "Velocis Utilities," contains descriptions of all standard Velocis utility
programs. Note that the actual name of the administration utility is admin, while it
appears as "Velocis Administrator" on the GUI interface.
Chapter 3, "SQL Decimal Value Manipulation Functions," contains descriptions of the
Velocis SQL functions that begin with a BCD prefix. Applications using the Velocis
runtime application programming interface (API) for database access can call the decimal
value manipulation functions for handling Velocis SQL-specific, binary-coded decimal
(BCD) data values.
Chapter 4, "Dictionary Access API Functions," contains descriptions of the Velocis
functions that begin with a c_ prefix. Your application calls these functions to obtain
record, field, and other database definitions from the database dictionary.
Chapter 5, "Customized Comparison Function Module Functions," describes the
functions that you can use in an extension module to create sorting routines for use in a
Core DDL or Velocis SQL schema. These functions have a cmp prefix.
Chapter 6, "Core API Functions," contains descriptions of the Velocis functions that begin
with a d_ prefix. These functions include the fundamental access primitives that your
application calls to query, insert, update, or delete data in the database. The Core API,
formerly known as the runtime API, also includes the database open and close functions,
and functions for transaction handling, locking, and currency management.
Introduction 1-1
Chapter 7, "Extension Module Functions," describes the functions that provide access
between Velocis client applications and extension modules, which reside on the Velocis
server. These functions begin with an em_ prefix. The chapter also describes the
functions that you can use in an extension module to extend server capabilities. These
functions begin with a Mod prefix and appear after the em_ function summaries.
Chapter 8, "Import and Export Filter Module Functions," describes the functions that you
can use in an extension module to create filters for use in transferring data between
Velocis SQL databases and outside resources. These functions begin with an ief prefix.
Chapter 9, "Parameter List Functions," describes the functions that are used to package
the data sent between Velocis client applications and Velocis server extension modules.
These functions begin with a pl_ prefix.
Chapter 10, "Engine Resource Manager Functions," contains descriptions of functions that
begin with an rm_ prefix. Your extension module can call these functions for use in
resource management.
Chapter 11, "Administration API Functions," contains descriptions of the functions that
begin with an s_ prefix. Your application can call these functions for server
administration tasks, but they are most often accessed by the system administrator
through the Velocis administration utilities.
Chapter 12, "SQL API Functions," describes the functions that begin with an SQL prefix.
Your application calls them for communication with the Velocis SQL support module.
The functions provide full relational access to the server engine and database. Additional
Velocis SQL functions are provided in Chapters 3, 13, and 16.
Chapter 13, "SQL UDF Support Functions," contains descriptions of the Velocis SQL
user-defined support functions, represented with a SYS prefix. Your server-based UDF
or import/export filter module can call these functions to extend the functionality of the
server.
Chapter 14, "UDF Module Functions," describes the functions that you can use in a UDF
module to extend server functionality. The function names begin with a udf prefix,
which you can replace with a module-specific prefix.
Chapter 15, "UDP Module Functions," describes the functions used in a user-defined
procedure module. The function names begin with a udp prefix, which you can replace
with a module-specific prefix.
Chapter 16, "SQL Date/Time Manipulation Functions," contains descriptions of the
Velocis SQL date/time manipulation functions, which begin with a VAL prefix.
1-2 Centura Velocis Reference Manual

Chapter 17, "Server Extension Toolkit Functions," contains descriptions of the C++ classes
and functions that you can use within a server to exchange information and execute
methods with extension modules.
Chapter 18, "Velocis Data Types," describes the simple and complex data types that
Velocis uses.
Chapter 19, "Return Codes and Error Messages," describes all Velocis status and error
codes, with cross-referencing so that you can look them up by code or by number.
1.1.2 About the Function References in this Manual

For each function described in this reference manual, the reference page header tells you
the function name. The first entry on the page is a quick description of the function. This
is followed by a Syntax section that gives a synopsis of the actual function declaration
(C-style).
In many Syntax sections for the functions in this book, you will find references to the
hSess parameter, specifying a session handle, and to the hDb parameter, specifying a
database handle. Note that your application obtains the session handle when it logs into
a server (via s_login). The functions that apply to the current session can then make use
of the session handle. Examples of these functions are d_open, d_trbegin, and
d_grplock.
Your application obtains a database handle (hDb) when it opens a database (via d_open
and d_iopen). The handle is then used by functions that operate on the database (for
example, d_fillnew, d_delete, d_findfm).
Right after the Syntax section for each section, you will find the Parameters section, which
lists and defines the function parameters introduced in the syntax declaration. Note that
the parameters for file IDs and record, field, and set types are provided in uppercase.
Uppercase indicates that the corresponding constant created by ddlproc in dbname.h is
normally passed to the function by the caller.
A Description section follows the parameter definitions. In this section, we explain
operational details of the function.
After the function is described, the next section in the function reference is Return Values.
This section contains the error/status codes for the function, listed in alphabetical order.
Detailed definitions of the codes are provided in Chapter 19.
For functions that can cause currency changes, the function reference includes the
Currency Changes section, which lists assignment statements in the order in which
changes occur. You can interpret the notation curr_own[SET] as "current owner of the
specified set." In case of a user error, the function does not make changes.
Introduction 1-3
After the Currency Changes section, the function reference presents the Locking
Requirements section, which lists locking requirements for any function that accesses the
database. If your application has opened the database in a nonshared mode, locking is
not required.
The next section of the function reference is See Also, which lists related functions,
complex data types, etc.
For many of the functions in this manual, an Example section is included. An example
illustrates how the application calls the function, but not necessarily how the application
uses it. For examples showing application use of Velocis API functions, see the Velocis
User’s Guide.
1.1.3 Related Velocis Documents

Velocis User’s Guide provides a detailed description of Velocis and in-depth instructions
for the application developer.
Velocis Installation/Administration Guide contains installation instructions and details for
running Velocis on the server and client platforms. This guide also includes procedures
for the system administrator, including server configuration, routine maintenance,
diagnostic, and corrective maintenance procedures.
Velocis Language Guide provides language specifics for the Database Definition Language
(DDL), which is used with the Velocis Core API. Additionally the manual furnishes a
complete statement and function reference for Velocis SQL.
Note: The trademarked name of this product is Velocis Database Server and is reflected in
the actual titles of the manuals. For ease of reference within the manuals, the simpler
form of Velocis is used.
Velocis system components are furnished on a CD. The CD includes a readme.txt file
that contains the release notes for your particular operating environment. Be sure to read
this file carefully. It provides detailed information about:
• Recent changes to the system that are not documented in the current manuals.
• Issues specific to your particular operating system or compiler.

1.1.4 Document Conventions
Table 1-1 describes the notational conventions used in this guide.
Table 1-1. Document Notational Conventions
Convention Description
Bold Text Indicates the names of functions, data structures,

statements, databases, utilities, utility options, files,
etc. Note that the case distinctions used in the names
are not significant for all operating systems.
Italic Text Represents the names of variables, such as function or
utility parameters. Additionally, the Velocis
documents use italics for the names of books.
Courier Text Indicates a programming example or a command-line
entry. Programming examples in this book are
enclosed in boxes.
Brackets ([ ]) Indicate optional fields or parameters in command
lines or in syntax statements of database schema.
Bar Symbol (|) Separates alternative selections. You should enter one
of the items separated by the bar.
Ellipsis (...) Indicates that you can repeat the preceding item. Both
horizontal and vertical ellipses are used in
programming examples to indicate code that has been
omitted.
Arrow Symbols (< >) Indicate information that you must supply. For
example, <filename>.h represents a header file that
you name. Arrow symbols are also used in text to set
off keyboard key names.
1.2 Other Helpful Resources

Centura offers various options for additional information on Velocis.
• Centura Books Online
The Centura Velocis document set is available online. This document collection lets
you perform full-text indexed searches across the product document set, navigate the
table of contents using the expandable/collapsible browser, or print any chapter.
Introduction 1-5
Access the collection by going to the CD, navigating to the Book Set folder, and
opening the PDF file listed in that directory.
• Worldwide Web
The Centura Worldwide Web home page is located at http://www.centurasoft.com.
The Centura web server provides access to a wealth of information about Centura
products and services.

Chapter 2
Velocis Utilities
This chapter describes the utility programs that are included with Velocis. They are
listed alphabetically by their executable file names. Each utility summary contains
sections showing the syntax, a summary of the command-line options, a general
description, and a section that mentions related topics.
The utilities in this chapter can be found in the bin subdirectory of your Velocis
installation. The instrds and rds utilities are only available to the server; the other
utilities are only available to the client.
The chapter contains five database repair utilities, which are collectively called the
dbrepair toolkit. This toolkit can be used to diagnose and repair the server database
from a client. With the dbrepair toolkit, you can check database consistency (dbcheck
utility), repair a corrupted database (dbfix), rebuild key files (keybuild), compress
fragmented databases (dbdefrag), and rebuild delete chains (dchain).
All utilities, with the exception of admin, use a command-line interface. Most of the
utilities are available for each platform; the ones that are specific to a platform are noted
in their descriptions. You can display the command syntax for most Velocis utilities by
entering the name of the utility, followed by the -? or -h option.
For client utilities that require the user to log into a server, you can define an
environment variable that allows the user to log in automatically with the required
parameters when the utility is invoked. To do this, define an RDSLOGIN environment
variable in your shell environment, using this string format: "serverID;userID;password"
(quotation marks inclusive). The server ID can be the server name, or it can be an alias
that is defined in the client configuration file (connect.ini).
You can also log in automatically in a utility by using the -L option, which overrides the
RDSLOGIN variable setting. That option uses the same string format as the RDSLOGIN
environment variable. If you omit the -L option, and RDSLOGIN is undefined, the
utility prompts for the login information.
Velocis Utilities 2-1

admin
admin Windows-based administration utility
Command admin
Syntax
Command None
Options
Description The admin utility invokes Velocis Administrator, which performs
most system administration operations necessary for configuration,
testing, and maintenance of Velocis. With this utility, you can view,
create, modify, or delete server objects (such as users, databases,
database devices, and extension modules). You can also use the
utility to modify velocis.ini configuration parameters.
The utility makes use of the administration API functions detailed in
Chapter 11 of this manual. See Chapter 5 of the Velocis
Installation/Administration Guide for instructions on running this
utility. Alternatively, you can write your own system
administration code, making calls directly to the administration API
(s_ functions).
Note: Velocis Administrator is a GUI-based utility that is available

only on the Windows platform. The command-line alternative to
this utility is rdsadm, which is available on all platforms.
See Also rdsadm

dbcheck
dbcheck Database consistency check utility
Command dbcheck [-? | -h] [-a] [-b ["bname[;bname]..."]] [-f file] [-i secs]
Syntax [-k ["kname[;kname]..."]] [-L "serverID;userID;password"] [-m type]
[-p pages] [-q] [-r ["rname[;rname]..."]] [-s ["sname[;sname]..."]]
dbname
Command -? | -h Displays the usage information for the utility.

Options -a Performs a complete consistency check of the
database. This option is equivalent to the
combination of -r -s -k -b.
-b ["bname[;bname]..."]
Performs a consistency check of the BLOBs whose
names are in the specified list. If no list is present,
the utility performs a check on all BLOBs.
-f file Specifies the file that contains information for
additional checked database elements such as
records, sets, keys, and BLOBs. When you create
such a file, each line must be in the form "r rname",
"s sname", "k kname", or "b bname". These elements
are added to those specified in the options.
-i secs Determines the accumulation period, in seconds,
before report messages are flushed into the console
(standard output). The default is 10.
-k ["kname[;kname]..."]
Performs a consistency check of the keys whose
the utility performs a check on all keys.
-L "serverID;userID;password"
Specifies the user login information. If this option is
omitted, the utility looks for the information in the
RDSLOGIN environment variable. Then, if the
variable is undefined, the utility prompts you for
the login information.
-m type Specifies the user and system report types, and
reports as follows:
1 = Summary user and system reports
2 = Detailed system report and summary user report
3 = Detailed user report and summary system report
4 = Detailed user and system reports (default)

dbcheck
-p pages Defines the number of pages in the dbrepair server

cache. Use a value between 8 and 1000. The default
is 64.
-q Performs a quick scan check of the database sets.
For details of this mode, see s_dbcheckBegin.
-r ["rname[;rname]..."]
Performs a consistency check of the records whose
the utility performs a check on all records.
-s ["sname[;sname]..."]
Performs a consistency check of the sets whose
the utility performs a check on all sets.
dbname Specifies the name of the database.
Description This utility examines the consistency of the files in the physical
database specified by dbname. For this purpose, it calls the
s_dbcheckBegin function. The utility translates the command
options into the function parameters. The recIDs, setIDs, keyfldIDs,
and blobfldIDs parameters are formed from the names directly
specified in the command line (explicitly or implicitly) and from the
names in the file that is specified in the -f option. Duplicate
specifications of the same element are accepted.
After starting the consistency checking process (and until its
termination), the utility fetches the next portion of the user report
after every secs seconds and puts it into the standard output file.
The utility displays progress by polling the status of the running
dbrepair operation. Status is polled by one or more calls to
s_dbrGetStatus.
See Also s_dbcheckBegin

dbdefrag
dbdefrag Data file compression utility
Command dbdefrag [-? | -h] [-a] [-b ["bname[;bname]..."]] [-f file] [-i secs]
Syntax [-L "serverID;userID;password"] [-m type] [-n] [-p pages] [-q]
[-r ["rname[;rname]..."]] dbname

Options -a Compresses all database data and BLOB files. This
option is equivalent to the combination of -r -b.
Compresses the BLOB files containing BLOBs with
the names in the specified list. If no list is present,
the utility compresses all BLOB files.
-f file Specifies the file containing the specifications for
additional compressed database elements. When
you create such a file, each line must be in the form
of "k kname" or "b bname". These names are added
to those specified in the options.
-m type Specifies the user and system report types and
reports as follows:
-n Produces a report of all modifications, without
actually changing the database.
is 64.

dbdefrag
-q Specifies quick mode, in which the utility does not

attempt to adjust user-defined fields of type
DB_ADDR. Adjustment may be necessary when
those fields refer to records in other databases.
Compresses the data files containing records with
the names in the specified list. If no list is present,
the utility compresses all data files.
Description This utility compresses files in the dbname database by using the
s_dbdefragBegin function. The utility extracts the parameters for
the call from the values of the command options. The recIDs and
blobfldIDs parameters are formed from the names directly specified
in the command line (explicitly or implicitly) and from the names in
the file that is specified in the -f option. Duplicate specifications of
the same element are accepted.
s_dbrGetStatus.
See Also s_dbdefragBegin

dbfix
dbfix Database repair utility
Command dbfix [-? | -h] [-a] [-b ["bname[;bname]..."]] [-d dumpfile] [-f file]
Syntax [-i secs] [-k ["kname[;kname]..."]] [-L "serverID;userID;password"]
[-m type] [-n] [-p pages] [-r ["rname[;rname]..."]]
[-s ["sname[;sname]..."]] dbname

Options -a Repairs all database elements. Equivalent to the
combination of -r -s -k -b.
Repairs the BLOBs whose names are in the specified
list. If no list is present, the utility repairs all
BLOBs.
-d dumpfile Specifies the name of the dump file. All records
found corrupted by dbfix and put into delete chains
are dumped into this file.
-f file Specifies the file containing specifications for
additional repaired database elements such as
records, sets, keys, and BLOBs. When you create
such a file, each line must be in the form "r rname",
"s sname", "k kname", or "b bname". These elements
are added to those specified in the options.
Repairs the keys whose names are in the specified
list. If no list is present, the utility repairs all keys.
-m type Specifies the user and system report types, and
reports as follows:

dbfix

-n Specifies simulation mode, in which dbfix produces
the report of the repair actions without executing
them.
is 64.
Repairs the records whose names are in the
specified list. If no list is present, the utility repairs
all records.
-s ["sname[;sname]..."]
Repairs the sets whose names are in the specified
list. If no list is present, the utility repairs all sets.
Description This utility performs the consistency check of the dbname database
and repairs the database if corruption is detected. The utility
accomplishes this by a call of the s_dbfixBegin function. The utility
extracts the parameters for the call from the values of the command
options. The recIDs, setIDs, keyfldIDs, and blobfldIDs parameters are
formed from the names directly specified in the command line
(explicitly or implicitly) and from the names in the file that is
specified in the -f option. Duplicate specifications of the same
element are accepted.
s_dbrGetStatus.
See Also s_dbfixBegin

dbimp
dbimp Database import utility
Command dbimp [-? | -h] [-e "ch"] [-L "serverID;userID;password"] [-n] [-s "ch"]
Syntax impspec

Options -e "ch" Changes the escape character from a backslash ("\")
to the character ch.
-n Prevents dbimp from echoing its input data to
standard output.
-s "ch" Changes the field separator character from a comma
(",") to the character ch.
impspec Specifies the import specification file which
contains the commands used to import data into
Velocis.
Description This utility imports data to a Velocis database from ASCII text files
according to commands contained in an import specification file,
impspec. It logs in to the server and opens the database in exclusive
mode with no transactions ("xn"). Refer to Chapter 9 of the Velocis
User’s Guide for complete information.
The dbimp error message format, which is shown below, can be
interpreted by some text editors.
filename line col : message
The Language Summary section describes the commands that can

be used with the dbimp utility. The ASCII files that are inputted to
dbimp have limits of 4,300 bytes per line, 1,024 bytes per field, and
128 fields per line.

dbimp
Language Import Specification:

Summary
database dbname {
for_loop
...
}
for_loop:
foreach [ascii | unicode] input_file {
import_statement
...
}
import_statement:
for_loop | record_statement | connect_statement
record_statement:
record recname {
[handling | field_statement]
...
}
handling:
{create | update | find} on fldnum;
field_statement:
field fldname = [input_file.]fldnum;
connect_statement:
connect setname;

dbimp
Language dbname The name of the database that is the target of the
Parameters import. The database must be initialized and
registered in the catalog.
input_file The full name, optionally including a full path, of an
ASCII (the default) or Unicode text file to be used as
input. The name of the file must be enclosed in
quotation marks. An input file may be opened
more than once during an import.
recname A record type as defined in the DDL schema for the
database.
fldnum An integer that identifies a field within the input
file. The first input field is number 1, the second is
2, etc.
fldname A field type as defined in the DDL schema for the
database, within the record type created by the
record statement that encloses this statement.
setname A set type as defined in the DDL schema for the
database.
See Also Chapter 9, Velocis User’s Guide

dbimp
Example From tims.imp, the database import file for the example
tims database:
database tims;
foreach "author.txt" {
record author {
create on 1;
field name = 3;
}
}
foreach "info.txt" {
record info {
create on 1;
field id_code = 4;
field info_title = 5;
field publisher = 6;
field pub_date = 7;
field info_type = 8;
}
record author {
find on 2;
}
connect has_published;
}
foreach "text.txt" {
record text {
field line = 3;
}
record info {
find on 2;
}
connect abstract;
}
foreach "key_word.txt" {
record key_word {
create on 1;
field word = 2;
}
}
foreach "intersct.txt" {
record intersect {
field int_type = 4;
}
record info {
find on 3;
}
record key_word {
find on 2;
}
connect info_to_key;
connect key_to_info;
}
end;

dbreplay
dbreplay Backup restore and roll-forward utility
Command dbreplay [-? | -h] [-b] [-c] [-L "user;pw"] [-n] [-q]
Syntax [-s "mm/dd/yyyy hh:mm:ss"] [-v] [logfilename]

Options -b Prevents the display of the program startup banner.
-c Requires prompting for confirmation of each
transaction.
-L "user;pw" Logs in as (admin) user with password. If this
option is omitted, the utility will prompt you for
this information.
-n Prevents the replay, but displays log information.
-q Invokes quiet mode, disabling user prompts.
-s "mm/dd/yyyy hh:mm:ss"
Specifies that the processing stop on the first
transaction later than the specified timestamp.
-v Invokes verbose mode, displaying the timestamp,
transaction ID string, and the name of the issuing
user for each transaction to be reprocessed.
logfilename Specifies the name of starting log file. It only needs
to be specified if both the checkpoint indicator file
(rdm.chi) and the backup indicator log file
(rdm.bil) are not present.
Description This utility is used to reprocess all committed transactions that were
recorded in change log files after a server backup. It performs what
is called roll-forward recovery. The utility must be executed
immediately after a server backup has been restored.
Roll-forward recovery works in conjunction with hot backup mode.
After the server is placed into hot backup mode (using an
administrative utility), all database files should be backed up. If a
roll-forward recovery becomes necessary, the dbreplay utility must
be used.
This utility runs in a standalone (non-server) mode, and the server
cannot be running when you use this utility. To perform the
recovery, database files that were backed up must be restored to

dbreplay
their original positions. Log files which were created when hot
backup mode was entered need to be present. Then run this utility.
Note: If recovery is necessary because of media failure, you can

only recover up to the end of the last archived log file, so remember
to archive log files regularly.
See Also s_backupBegin

dbstat
dbstat Database analysis utility
Command dbstat [-? | -h] [-b num] [-k num] [-L "serverID;userID;password"]
Syntax [-nb] [-nd] [-nk] [-v] [dbname]

Options -b num Specifies the maximum block size, in bytes (default
is 8,192), for comparing different page sizes. The
utility creates a statistical table that applies the
specified limit to help you choose an optimal page
size.
-k num Specifies the block size increment, in bytes (default
is 1,024), for comparing different page sizes. In
verbose mode (see the -v option below), the utility
creates a statistical table that applies the specified
increment to help you choose an optimal page size.
-nb Skips files that contain BLOBs. Significant runtime
performance hits can be incurred when using
verbose mode (see the -v option below) to analyze
BLOB files.
-nd Skips files that contain record data.
-nk Skips files that contain indexes.
-v Activates verbose mode. In this mode, the utility
looks at the actual state of the database and then
retrieves information about the data currently
stored. This mode causes the database to go into
hot online backup mode while the actual data, key,
and BLOB files are being analyzed.
Description The dbstat utility is a Velocis extension module that helps

developers analyze the design of their Velocis database schema. If a
database name (dbname) is not specified, dbstat generates

dbstat
information for all databases registered in the catalog. The utility

reports the following items:
• The slot and page sizes of each database file
• The number of slots and pages in each database file
• The amount of unused space in each database file
• The amount of deleted space in each database file
• Information about modifying the page size of a database file
The dbstat utility gathers information on the size of all data, BLOB,
and key files for a certain page size. If the verbose option (-v) is
specified, the report will also contain information about the actual
contents of the specified database. Otherwise, the report only
contains information about the database’s structure.
For an existing database, the information includes exactly how much
space is wasted, deleted, and unused. A table is generated for each
database file, listing file sizes and wasted space under different page
sizes, with the current page size marked by an asterisk ("*"). The
end of the report includes a summary of the information from each
of the files.
Unused space can come from the following:
• Pages not fully used (i.e., wasted space at the ends of pages)
• Slots not completely filled (if a file contains more than one
record or key of different sizes)
• Slots not yet used at the end of the last page of a data file
• Slots not yet used within all the pages of a key file
Note: Use the numbers in the generated table to determine how

best to optimize disk space. Key pages are generally half full, so the
key file sizes reported are about half the size of each key file.
Deleted space can come from the following:
• Deleted record slots in data files
• Deleted pages in key files
• Deleted pages in BLOB files
See Also s_dbstat

dchain
dchain Delete chain repair utility
Command dchain [-? | -h] [-a] [-b ["bname[;bname]..."]] [-f file] [-i secs]
Syntax [-k ["kname[;kname]..."]] [-L "serverID;userID;password"] [-m type]
[-n] [-p pages] [-r ["rname[;rname]..."]] dbname

Options -a Rebuilds all delete chains in the database files. This
option is equivalent to the combination of -r -k -b.
Rebuilds the delete chains of the BLOB files
containing BLOBs with the names in the specified
list. If no list is present, the utility rebuilds the
delete chains of all BLOB files.
-f file Specifies the file, containing specifications for
additional database elements, that lists the delete
chains that must be rebuilt. When you create such a
file, each line in this file must be in the form
"r rname", "k kname", or "b bname". These names are
added to those specified in the options.
Rebuilds the delete chains of the key files
containing key names in the specified list. If no list
is present, the utility rebuilds the delete chains of all
key files.
-m type Specifies the user and system report types as
follows:

dchain
-n Produces the report of all modifications, without

actually changing the database.
is 64.
Rebuilds the delete chains of the data files
containing records with the names in the specified
list. If no list is present, the utility rebuilds the
delete chains of all data files.
Description This utility rebuilds delete chains in the dbname database by calling
the s_dchainBegin function. The utility extracts the parameters for
the call from the values of the command options. The recIDs,
keyfldIDs, and blobfldIDs parameters are formed from the names
directly specified in the command line (explicitly or implicitly) and
from the names in the file that is specified in the -f option.
Duplicate specifications of the same element are accepted.
After starting the consistency checking process and until its
termination, the utility fetches the next portion of the user report
s_dbrGetStatus.
See Also s_dchainBegin

ddlproc
ddlproc Core DDL database schema compiler
Command ddlproc [-? | -h] [-d] [-L "serverID;userID;password"] [-r] [-s]

Syntax [-t device] [-x] [-z] ddlfile

Options -d Allows duplicate names, so fields and structures in
different record types can have the same name.
Record structures generated by ddlproc contain the
name as specified in the schema. Constant
definitions for the fields are concatenations of
record type and field type, separated by an
underscore. For example, the following schema
results in the constant definitions shown at the end
of the example block.
record ticket {
.
.
float unit_cost;
}
.
.
record invoice {
.
.
float unit_cost
}
#define TICKET_UNIT_COST 4005

#define INVOICE_UNIT_COST 6014
-r Displays a file structure report in standard output
(stdout). See Chapter 5 of the Velocis User’s Guide.
-s Turns off case sensitivity. The utility defaults to
case sensitivity.
-t device Specifies the device on which to place the dictionary
file. If this option is not specified, the user’s default
device is used.

ddlproc
-x Displays (in standard output) a cross-reference

listing of record, set, and field names. The names
are listed in alphabetical order, with the associated
type and line numbers in the schema file where the
name is referenced. The following is an example
cross-reference report.
Velocis Version 1.0
DDL X-Ref Listing of File: ckngacct.ddl
Thu May 13 13:38:24 1993
allocation field 13
amount field 20
balance field 14
budget record 7 10 24
cat_desc field 12
check record 7 16 25
check_date field 918
check_no field 917
code field 811
paid_to field 19
transactions set 22
-z Prevents the generation of SIZEOF_ defines in the

header file.
ddlfile Specifies the text file containing the database
schema.
Description The ddlproc utility compiles the schema contained in the text file
ddlfile. It generates a database dictionary file (<dbname>.dbd) to
run on the server in a default device, or in the device specified for
the -t option. The processor also generates a C database header file
named <dbname>.h.
The ddlproc utility reports any processing errors to standard output
in the following format, which some text editors interpret.
filename line col : message
Note: Sometimes the reported error line number is the line

following the place where the actual error occurs. Be sure to check
the lines preceding the reported line if you cannot find the error in
the reported line.
See Chapter 6 of the Velocis Language Guide for descriptions of the

various DDL statements you can use in ddlfile.

ddlproc
ddlproc The following are ddlproc keywords. Note that they are not case-
Keywords sensitive.
asc desc long records
ascending descending member set
blob_id double next sets
by file nocase short
char first opt static
compound float optional struct
contains int order timestamp
data key owner unique
database last readonly unsigned
db_addr local record wchar
See Also Chapters 5 and 13, Velocis User’s Guide

Chapter 6, Velocis Language Guide

instodbc
instodbc ODBC installation utility
Command instodbc [-? | -h] [-a] [-d database [database] ...] [-f] [-q] [-s] [-u]
Syntax binpath servername

Options -a Install all data sources to the existing ODBC
installation. If no options are specified, this option
is automatically used.
-d database [database] ...
Associates one or more databases with the data
source.
-f Installs the data source name (DSN) of the file.
-q Invokes quiet mode.
-s Installs the data source name of the system.
-u Installs the data source name of the user.
binpath Specifies the path to the Velocis ODBC driver
(Codrv32.dll). This file is usually located in the
Velocis client’s bin directory or in the Windows
directory (on Windows platforms).
servername Specifies the server name.
Description A system administrator can use this utility to add the Velocis ODBC
driver and a data source to an existing ODBC installation. The
utility enables the ODBC driver manager. The use of this utility is
illustrated in the Velocis Installation and Administration Guide.
Note: To run instodbc on Windows platforms, your user name

must have administrator privilege.
See Also instrds
Example For the command line below, instodbc creates a driver with the
name "Velocis" and a data source named "Velocis VEL3". The 32-bit
ODBC Administrator Data Sources screen will display a "Velocis
VEL3(Velocis)" entry.
instodbc c:\velocis\bin VEL3

instrds
instrds Velocis server installation utility (Windows NT)
Command instrds [-? | -h] [-q] -s name path catpath

Syntax instrds start name
instrds remove name

Options -q Sets the system quotas for the Windows registry.
-s Installs Velocis as a Windows NT service.
name Specifies the server name. The name can be up to
127 characters in length.
path Specifies the device for the server (path of
containing directory).
catpath Specifies the device for the system catalog.
Description A system administrator can use this utility to install or remove

Velocis as a service on Windows NT.
To install Velocis as a Windows NT service on the server, use the
-s option of this utility. With this option, you need to specify a
server name, the server path, and the path to the system catalog. To
start the Velocis service (that is, actually putting it into operation as
a service), use the instrds start form of the utility. To remove
(de-install) Velocis from the server, use the instrds remove form the
utility. This form of the utility is the opposite of the -s option form.
After running instrds, the administrator needs to shut down and
restart Windows NT.
Note: To run instrds on Windows platforms, your user name must

have administrator privilege.
See Also instodbc, rds
Example
instrds -s VEL3 c:\velocis\bin\rds.exe c:\velocis\catalog

keybuild
keybuild Key file rebuild utility
Command keybuild [-? | -h] [-f file] [-i secs] [-k ["kname[;kname]..."]]
Syntax [-L "serverID;userID;password"] [-m type] [-p pages] dbname

Options -f file Specifies the file containing specifications for
additional rebuilt keys. When you create such a file,
each line in this file must be in the form "k kname".
These names are added to those specified in the
options.
Rebuilds the keys whose names are in the specified
list. If no list is present, the utility rebuilds all keys.
-m type Specifies the user and system report types as
follows:
is 64.
Description This utility rebuilds indexes in the dbname database by calling the
s_keybuildBegin function. The utility extracts the parameters for
the call from the values of the command options. The keyfldIDs
parameter is formed from the names directly specified in the
command line (explicitly or implicitly) and from the names in the

keybuild
file that is specified in the -f option. Duplicate specifications of the

same element are accepted.
s_dbrGetStatus.
See Also s_keybuildBegin

prdbd
prdbd Dictionary printing utility
Command prdbd [-? | -h] [-c] dbname

Syntax

Options -c Omits symbolic names from the report.
Description This utility displays the contents of the database dictionary (.dbd)
file for the dbname database. It reports the default database page
size and each entry in the file table, record table, field table, set table,
member table, sort field table, and key table that constitutes the
internal form of the database dictionary. This report is written to
standard output (stdout) and can be redirected as desired.
The utility normally prints symbolic names wherever possible. If
you want the record, set, and field numbers only, use the -c option.
See Also Dictionary access API functions (c_ prefix)

rds
rds Velocis database server utility
Command rds [-c path] [-d [-ph | -pi | -pn]] [-r threads] [servername]
Syntax
Command -c path Specifies the path of the catalog (CATPATH).

Options -d [-ph | -pi | -pn]
Runs the server as a background process. You can
optionally set the process priority level to idle (-pi),
normal (-pn), or high (-ph). If the process priority
level is omitted, normal priority is used.
-r threads Specifies the number of RPC threads for the server
to start.
servername Specifies the name of the server, which overrides
the name in the catalog. The name can be up to
12 characters in length. If a server name is not
specified, the server name in the velocis.ini
configuration file will be used.
Description A system administrator can use this utility to put the database
server into operation. You can operate the server in the background
by using the -d option, with the ability to set the level of process
priority. If you are running the Velocis server on Windows NT, you
can install and run Velocis as a Windows NT service by using the
instrds utility.
See Also instrds

rdsadm
rdsadm Command-line administration utility
Command rdsadm [-? | -h] [-L "serverID;userID;password"]

Syntax

Options -L "serverID;userID;password"
Description The rdsadm utility is an administration utility to use on UNIX

platforms or as an alternative to admin (Velocis Administrator) on
Windows platforms. This utility basically provides the same
functions as admin, but for a non-Windows environment. The
functions are accessible from a simple user interface consisting of
several menus.
See Also admin

rsql
rsql Interactive Velocis SQL utility
Command rsql [-? | -h] [-c num] [-e] [-H num] [-l num] [-n] [-o output_file]
Syntax [-s num] [-w num] [startup [arg]...]

Options -c num Specifies the maximum number of connections that
can be opened. The default is 5.
-e Disables the echo of the commands contained in a
script file (see the .r command).
-H num Sets the size of the statement history list that rsql
maintains. This list contains the number (num) of
the most recently entered statements. The default is
25.
-l num Specifies the number of display lines per output
page. The default is 25.
-n Prevents the display of the copyright notice.
-o output_file Outputs statements and error messages to the
specified output file.
-s num Specifies the maximum number of statement
handles per connection that can be used. The
default is 5.
-w num Specifies the page width of the display, in columns.
The default is 80.
startup [arg]... Specifies a file containing commands or statements
to execute on startup. An optional parameter list
can be specified. Each parameter is referenced by
position within this file using a percent sign ("%"),
followed by the parameter number, beginning at 1.
For example, "%1" references the first parameter,
"%2" the second, and so on.
Description This utility allows you to execute Velocis SQL statements

interactively. The utility is provided to simplify use of Velocis SQL.
Note: The rsql utility is simply a testing aid. No security

precautions have been implemented for its use. For example, the
password is not blanked out by the program.

rsql
Once you have started rsql, you can enter utility commands or
Velocis SQL statements at the prompt ("1 rsql>"). Each statement is
terminated by a semicolon (";") at the end of the line. You can enter
multi-line statements by pressing <Enter> at the end of each line.
An example of a multi-line statement is shown below.
1 rsql> select sale_name, sum(amount), max(amount), min(amount), avg(amount)
1+ rsql> from path salesperson to customer to sales_order
1+ rsql> group by sale_name;
When you have completed your rsql session, enter .q to quit.
The rsql Utility The rsql utility has a set of commands to select and edit previously
Commands entered Velocis SQL statements, open and close connections to
Velocis servers, control use of statement handles, read and store
statements in text files, etc. These commands are listed in the table
below. Each rsql utility command begins with a special character in
the first column of the entered statement and is terminated by
pressing the <Enter> key. Only Velocis SQL statements are
remembered in the statement history list. Utility commands are not
remembered.

rsql
Table 2-1. Available Commands in the rsql Testing Utility

Command Syntax Description
!oscmd Executes the specified operating system command
(oscmd). For example, !dir *.tst lists the files with the
.tst extension in the current directory.
<Enter> Displays the current statement.
? Displays a syntax of all utility commands.
; Resends the current statement to the Velocis SQL
server.
* Displays the statement history list.
-[num] Repositions the current statement backward by num
(default 1) statements.
+[num] Advances the current statement num (default 1)
statements.
#num Makes statement number num the current statement.
Specifying a number too low or too high positions the
current statement to the start or the end of the list,
respectively.
@[pattern] Searches down the statement history list to the first
statement that matches pattern. If no pattern is
specified, the last pattern is used. The pattern is a
string containing "*" (match all characters) and/or "?"
(match a single character).
/oldtext/newtext/[g] Replaces the first occurrence (or all occurrences, if "g"
is specified) of oldtext with newtext in the current
statement.
. command Activates the specified interface control command
used to control interaction with the Velocis SQL
support module. The syntax for these commands is
given in the next table.
Note: The current statement is the last statement entered, unless

you have changed the current statement by entering a "-", "+", "#", or
"@" command.
The "@" command searches down the list for a statement that
matches the specified text pattern with the wild card characters "*"
(match zero or more characters) and "?" (match any single
character). The search starts from the current statement and

rsql
proceeds through the list until it returns to the current statement. If

pattern is omitted, the pattern of the last "@" command is used.
The current statement can be modified by using the "/" command.
The "/" command replaces the first occurrence of oldtext with
newtext. To replace all occurrences, include a "g" (for global change)
just after the ending "/". After you enter the text substitution, the
modified statement is assigned the next statement number,
re-displayed, and followed by a "+ rsql>" prompt. At this point,
you can enter another "/" command to modify the statement further,
enter ";" to submit the statement, or simply press <Enter> to cancel
the command.
A summary of the interface control command syntax is shown
below.
Table 2-2. rsql Interface Control Commands

.a [num [extension]] Displays all extension modules that are currently
attached, if no parameters are given. If an extension
module number alone is specified, the utility switches
to that extension module. If the name of an extension
module is also given, the utility attaches it to the
specified number.
.b Toggles binary result mode implemented by the
s_dbaddr system function. Using this command
displays the decimal value of a database address.
.C Commits all transactions for the current server
connection.
.c [num [srv usr pw]] Switches to server connection number num; if login
information is specified, the utility logs in to the
Velocis named server, srv, with user name usr and
password pw. Connections are numbered between 1
and the limit specified by the -c command-line
option. The .c command by itself displays a list of all
connections and the names of the servers accessed by
them. You can open a connection to any Velocis
server that is active on the network. You can also
open multiple connections to the same Velocis server.
.d {* | num Disconnects either all connections (.d *) or the
[, num] ...} specified connection numbers.
.e Toggles the statement echo flag. When the flag is
turned on, each command or statement processed by
an .r command is displayed.

rsql
Table 2-2. rsql Interface Control Commands (continued)

.F [f | l | n | p | Fetches the first, last, next, prior, absolute, relative, or
{a | r | b} num] bookmarked rowset, respectively. For the last three
options, num is equivalent to the row number to use
in the SQLExtendedFetch function’s rowNum
parameter.
.f getcursor Calls SQLGetCursorName to get the system-
generated cursor name associated with the current
statement handle.
.f setcursor name Calls SQLSetCursorName to set the cursor name
associated with the current statement handle to name.
.f speccols tnm Calls SQLSpecialColumns.
[dnm [onm]]
.f statistics tnm Calls SQLStatistics.
[dnm [onm]]
.g num [param] ... Runs the extension module function that is
represented by the number, with the specified
parameters as input.
.h [num] Switches to statement handle number num.
Statement handles are numbered between 1 and the
limit specified by the -s command-line option (default
is 5 per connection). The .h command by itself
displays the most recently compiled and executed
statement for each statement handle in the current
connection.
.i Inquires about the status of a transaction.
.j [file] Toggles/saves the query results to file.
.K Fetches the bookmark for the current row.
.k num Sets the size of a rowset to the specified number.
.L Views the bookmarks on the current statement.
.l num Sets the amount of lines in an output page to the
specified number.
.log message Logs a message to the server console.

rsql

.M Sets the cursor mode. Toggles between
SQL_CURSOR_FORWARD_ONLY (default) and
SQL_CURSOR_STATIC. Toggling this mode frees all
currently allocated statement handles on the current
connection. You must have the mode set to
SQL_CURSOR_STATIC before using the other new
options listed here.
.m [message] Displays a message on the server console with the
source file and line number.
.n Fetches the next select statement result row when
table mode is off.
.o Toggles the auto-commit mode option. When this
mode is on, all changes are automatically committed.
.P message Displays a message and pauses until you press
<Enter>.
.p par1 [par2] ... Specifies value for the 1st parameter marker, 2nd
parameter marker, and so on.
.q Exits the program. This closes all statement handles
and connections and then terminates the program.
.R Rolls back all transactions on the current server
connection.
.r file [par] ... Processes all commands and Velocis SQL statements
contained in the specified script file. Both interface
utility commands and Velocis SQL statements can be
contained in the script file, including other
.r commands. Any listed parameters (par) must be
separated by spaces and passed to file. They are
referenced by position within file, using a percent
sign ("%") followed by the parameter number,
beginning at 1 (for example, "%1" references the first
parameter, "%2" the second, and so on).
.S rownum Calls SQLSetPos to position the cursor to the
specified row number in the current rowset.
.s [file] Toggles save statement mode. If file is specified,
subsequent statements are saved (appended) in the
named file. If file is not specified, and save mode is
on, save mode will be turned off. Otherwise,
statements are saved in rsql.txt.

rsql

.T {start | stop} Starts and stops the timer.
.t Toggles the select statement output display mode
between table mode and row-at-a-time mode. Row-
at-a-time mode is used for cursor-based retrieval and
positioned updates and deletes.
.u {* | Unloads either all extension modules (if ".u *" is used)
num [, num]...} or only those extension modules whose
representative numbers are specified.
.w num Sets the width of the output page to the specified
number of columns.
.X num Displays the executive plan for the specified
statement handle.
.x Re-executes the compiled statement associated with
the current statement handle. Calls SQLExecute
directly; the statement was compiled (through a call
to SQLPrepare) when it was first submitted.
.y Toggles the compile-only flag. When turned on, each
SQL statement is compiled but not executed.
.z Calls SQLFreeStmt to close the active cursor when
table mode is off.
.. comments Adds comments, which are ignored by the utility.
Some of these commands were implemented specifically to test

positioned updates and deletes. The following example illustrates
how it works.

rsql
Example
1 rsql> .t
*** table mode is off
1 rsql> select * from salesperson;
SALE_ID: BNF
SALE_NAME: Flores, Bob
COMMISSION: 0.135000
REGION: 0
OFFICE: 1
MGR_ID: **NULL**
2 rsql> .n
SALE_ID: JBW
SALE_NAME: Warner, John
COMMISSION: 0.115000
REGION: 1
OFFICE: 1
MGR_ID: **NULL**
2 rsql> .f getcursor
*** cursor = SQL_CUR_3_1
2 rsql> .h 2
*** using statement handle 2 of connection 1
2 rsql> update salesperson set commission = 0.10
2 rsql+ >where current of sql_cur_3_1;
*** 1 rows affected
3 rsql> commit;

sddlp
sddlp Velocis SQL database schema compiler
Command sddlp [-? | -h] [-b] [-c] [-d "ddlproc_opts"] [-f] [-i] [-k]
Syntax [-L "serverID;userID;password"] [-n] [-o] [-p] [-R] [-r] [-u] [-w]
ddlfile

Options -b Prevents the display of the sddlp copyright banner.
-c Returns a checksum brand only, and does not
process the schema. Do not use this option with
other options.
-d "ddlproc_opts"
Specifies ddlproc command-line options for sddlp
to pass to ddlproc. (For Windows platforms, do not
use the quotation marks to delimit the command-
line options.)
-f Provides the Velocis DDL file (<dbname>.ddl) and
the header file created by ddlproc (either
<dbname>.h or <dbname>.hpp) to the client. This
option is for applications that use the Velocis Core
(d_) API. Do not use this option with the
preprocess-only option (-p).
-i Initializes the database.
-k Prevents the Velocis SQL creation of virtual foreign
key columns.
-n Prevents the creation of null column value indicator
fields.
-o Accepts the database definition even if the Velocis
server has already registered the database. By
default, sddlp prohibits the definition a database
that does not exist in the SQL system catalog
(syscat) but was registered with Velocis.

sddlp
Note: The -o option alone no longer initializes the database. The -i

option must also be specified if the database requires initialization.
-p Preprocesses the Velocis SQL DDL specification,

reporting any errors. With this option, sddlp stores
no information in syscat and does not register the
database with the Velocis server.
-R Creates the database files but does not register the
database with the server.
-r Prevents the creation and use of reference counts
when they are not being used for an application.
-u Specifies that the new schema is an update of an
existing one.
-w Displays warnings when the utility encounters non-
standard DDL statements (such as create join) in
the schema.
ddlfile Specifies the name and path of the text file
containing the Velocis SQL DDL schema. The
database name is the name specified in the
create database statement.
Description The sddlp utility compiles a text file containing a Velocis SQL DDL
database schema. Compilation generates the corresponding Core
DDL schema and automatically invokes the internal ddlproc
program to compile the Core schema for use under Velocis.
The utility reports errors in the schema on the standard error stream
(stderr). It only updates the system catalog when it encounters no
errors and the -p option has not been specified.
Note: Full ANSI 1989 SQL referential integrity checking requires the
existence of every row referenced by each foreign key in the
database. To enforce this integrity condition in the processing of a
delete statement, Velocis SQL maintains a reference count data field
in each Velocis record type that is referenced by a foreign key.
Velocis then allows deletions of referenced rows when the reference
count is zero. Extra overhead is incurred to maintain these reference
counts.
See Also ddlproc

vping
vping Velocis testing utility
Command vping [-? | -h] [-c Packets] [-i TestTime] [-s PacketSize] [-w WaitTime]
Syntax [servername]

Options -c Packets Specifies the number of packets to send (the default
is 10).
-i TestTime Specifies the period, in seconds, that is used to
measure the average speed in which packets are
sent. If this option is omitted, average packet-
sending speeds are not calculated.
-s PacketSize Specifies the packet size, in bytes. To have a
randomly selected size for each packet, specify 0
(the default).
-w WaitTime Specifies the delay time, in seconds, between ping
packets. The default is 0, which means that there is
no delay between sent packets.
servername Specifies the name of the server to test. If the server
name is omitted, the utility lists transport and other
client configuration information.
Description The vping utility determines whether a server is "listening" on the

network by issuing a "ping". When you run vping without any
command options, it produces a list of all enabled transports in the
client NCP module. It also prints the list of aliases defined in client
configuration file (connect.ini) and the details of their definitions.
See Also s_ping

Chapter 3
SQL Decimal Value Manipulation
Functions (BCD Prefix)
This chapter describes the functions that are used to work with binary-coded decimal
(BCD) values in SQL. Status and error codes for these functions have a VAL_ prefix;
they are listed in valerrs.h.
Most of the functions in this chapter have a return type of RETCODE (a short integer).
Other required data types include the BCD environment handle type BCD_HENV (a
generic pointer) and the packed BCD type BCD_Z, which is a structure defined as
follows:
typedef struct _bcd_z {
unsigned char prec; /* precision of DECIMAL */
unsigned char scale; /* scale of DECIMAL */
unsigned char flags; /* BCD_PACKED | BCD_POSITIVE */
char val[1]; /* bcd digits: 2 per byte */
} BCD_Z; /* Z => packed */
Some BCD functions involve converting BCD values to and from character strings. The
character string buffers must be large enough to contain the entire decimal value.
Therefore, the number of bytes to allocate to a string buffer should be at least the
maximum allowable precision of the allocated BCD handle, plus three (for the sign,
decimal point, and null-terminating character).
SQL Decimal Value Manipulation Functions (BCD Prefix) 3-1

BCDAdd
BCDAdd Add two decimal strings
Syntax RETCODE BCDAdd (BCD_HENV hBCD, char *leftValue,

char *rightValue, char *result, size_t resultLen)
Parameters hBCD [Input] The BCD handle.

leftValue [Input] The left operand decimal string.
rightValue [Input] The right operand decimal string.
result [Output] A pointer to the character buffer
containing the results of the addition.
resultLen [Input] The length, in bytes, of the character buffer.
Description This function performs a BCD addition of two decimal strings,

storing the resulting numeric string in a character array.
Return Values VAL_BADENV VAL_OKAY

VAL_INVALID VAL_OVERFLOW
VAL_NOMEM VAL_PRECLOSS
See Also BCDDivide, BCDMultiply, BCDSubtract

BCDAllocEnv
BCDAllocEnv Allocate a BCD environment handle
Syntax RETCODE BCDAllocEnv (unsigned char max_precision,

unsigned char max_scale, BCD_HENV *hBCDp)
Parameters max_precision [Input] The maximum precision allowed, in number

of digits.
max_scale [Input] The maximum scale allowed, in number of
digits.
hBCDp [Output] A pointer to the allocated BCD handle.
Description This function allocates a BCD environment handle to use for other
BCD functions. To allocate the BCD environment handle, your
application must specify the maximum precision and scale for the
BCD values that it is manipulating. These values can be set to
anything you want. However, to directly store (through the Core
API) any BCD values in the database, the maximum precision and
scale specified in this function must match the values specified in
Velocis SQL.
Return Values VAL_INVALID

VAL_NOMEM
VAL_OKAY
See Also BCDFreeEnv

BCDAllocZBuf
BCDAllocZBuf Allocate memory for a packed decimal buffer
Syntax BCD_Z *BCDAllocZBuf (short prec, RM_MEMTAG tag)
Parameters prec [Input] The precision of the requested buffer.

tag [Input] The memory tag. (Use NULL if there is no
memory tag or if this function is called on the client
side.)
Description This function allocates a packed decimal buffer with a size indicated
by the prec parameter. Packed decimals store two digits of data to a
byte, plus three additional bytes for the scale, precision, and flags.
You can use the BCDZLEN(precision) macro to calculate the size, in
bytes, of a packed decimal buffer.
See Also BCDFreeZBuf
Example
#include "velocis.h"
#include "sqlrds.h"
BCD_Z *pBcd;
...
/* Allocate buffer for commission */

pBcd = BCDAllocZBuf(4, 0);
/* Pack commission value, note the 0 len argument can be used when
the BCD_Z * value was allocated using BCDAllocZBuf.
*/
BCDPack(hBcd, "0.025", 4, 3, pBcd, 0);
/* Store the commission value */

d_crwrite(SALESPERSON_COMMISSION, pBcd, hSales);
/* Free the packed BCD buffer */

BCDFreeZBuf(pBcd, 0);
...

BCDCompare
BCDCompare Compare two decimal strings
Syntax RETCODE BCDCompare (BCD_HENV hBCD, char *leftValue,

char *rightValue, short *cmp)

cmp [Output] A pointer to the result of the comparison.
Possible values are -1, 0, or +1, depending on
whether leftValue is less than, equal to, or greater
than rightValue, respectively.
Description This function performs a BCD comparison of two decimal strings.

See Also BCDAdd, BCDDivide, BCDMultiply, BCDSubtract

BCDDivide
BCDDivide Divide one decimal string by another
Syntax RETCODE BCDDivide (BCD_HENV hBCD, char *leftValue,


result [Output] A pointer to the character array containing
the division result.
resultLen [Input] The length, in bytes, of the result buffer.
Description This function divides the left operand decimal string by the right
decimal string. It then writes the resulting decimal string to a
character array.

See Also BCDAdd, BCDMultiply, BCDSubtract

BCDFreeEnv
BCDFreeEnv Free a BCD handle
Syntax RETCODE BCDFreeEnv (BCD_HENV hBCD)
Description This function frees all dynamically allocated memory associated

with a BCD handle. Your application calls this function after all
desired BCD operations have been performed.
Return Values VAL_OKAY
See Also BCDAllocEnv

BCDFreeZBuf
BCDFreeZBuf Free memory used for a packed decimal buffer
Syntax void BCDFreeZBuf (BCD_Z *zBuf, RM_MEMTAG tag)
Parameters zBuf [Input] The packed decimal buffer to free.

tag [Input] The memory tag. (Use NULL if there is no
memory tag or if this function is called on the client
side.)
Description This function frees an allocated, packed decimal buffer. It should be

called to clean up buffers allocated with BCDAllocZBuf.
Return Values None
See Also BCDAllocZBuf
Example
#include "sqlrds.h"
BCD_Z *pBcd;
...
/* Allocate buffer for commission */

pBcd = BCDAllocZBuf(4, 0);
/* Pack commission value, note the 0 len argument can be used when
the BCD_Z * value was allocated using BCDAllocZBuf.
*/
BCDPack(hBcd, "0.025", 4, 3, pBcd, 0);
/* Store the commission value */

d_crwrite(SALESPERSON_COMMISSION, pBcd, hSales);
/* Free the packed BCD buffer */

BCDFreeZBuf(pBcd, 0);
...

BCDMultiply
BCDMultiply Multiply two decimal strings
Syntax RETCODE BCDMultiply (BCD_HENV hBCD, char *leftValue,


containing the multiplication result.
resultLen [Input] The length, in bytes, of the character buffer.
Description This function multiplies two decimal strings and stores the resulting
decimal string in a character array.

See Also BCDAdd, BCDDivide, BCDSubtract

BCDPack
BCDPack Convert a numeric character string to BCD format
Syntax RETCODE BCDPack (BCD_HENV hBCD, char *cp,

unsigned char precision, unsigned char scale, BCD_Z *rv,
size_t len)

cp [Input] A pointer to the decimal string to pack.
precision [Input] The decimal precision.
scale [Input] The decimal scale.
rv [Output] A pointer to the character buffer
containing the packed BCD results.
len [Input] The length, in bytes, of the character buffer.
This length is the size of the data field in the Core
DDL record.
Description This function converts a numeric character string into a decimal that
is in the internal BCD format of SQL for storage (through the Core
API) in a particular column of the database.
Extremely Important: The precision and scale used in the
conversion must match the declared precision and scale for the
database column. You can obtain this information for any database
column by calling the SQLColumns function.
Return Values VAL_BADENV VAL_OVERFLOW

VAL_INVALID VAL_PRECLOSS
VAL_NOMEM VAL_TOOSMALL
VAL_OKAY
See Also BCDUnpack, SQLColumns

BCDStatus
BCDStatus Check the status of a BCD value
Syntax RETCODE BCDStatus (BCD_HENV hBCD, BCD_Z *bcd)

bcd [Input/Output] A pointer to the decimal value.
Description This function checks the status of a decimal value for overflow and
loss of precision.
Return Values VAL_OVERFLOW

VAL_OVERLOSS
VAL_PRECLOSS
See Also BCDPack

BCDSubtract
BCDSubtract Subtract one decimal string from another
Syntax RETCODE BCDSubtract (BCD_HENV hBCD, char *leftValue,


containing the results.
resultLen [Input] The length, in bytes, of the result buffer.
Description This function subtracts the right decimal string from the left decimal
string, and stores the resulting numeric string in a character array.

See Also BCDAdd, BCDDivide, BCDMultiply

BCDUnpack
BCDUnpack Convert a decimal from BCD format to a character string
Syntax RETCODE BCDUnpack (BCD_HENV hBCD, BCD_Z *bv, char *cp,

size_t len)

bv [Input] A pointer to the BCD value to unpack.
cp [Output] A pointer to the character buffer
containing the results.
len [Input] The length, in bytes, of the character buffer.
This buffer must be large enough to contain the
result value.
Description This function converts a decimal value from the internal BCD
format of Velocis SQL to a character string.
Return Values VAL_BADENV VAL_OVERFLOW

VAL_INVALID VAL_PRECLOSS
VAL_NOMEM VAL_TOOSMALL
VAL_OKAY
See Also BCDPack, SQLColumns

Chapter 4
Dictionary Access API Functions
(c_ Prefix)
This chapter contains descriptions of the dictionary access functions (c_ prefix), which
provide convenient retrieval and caching of database dictionary information to client
applications. These functions are important only when it is necessary to find out
structural and content information about a database. (This situation is rare, because
most applications will already know the structure of their database definitions and use
the database header file definitions for record and field manipulation.)
Note: You can use the d_dict function to access the database dictionary, but it always
generates a call to the server. The c_ functions are more efficient, because they cache any
requested data, and they only make calls to the server when it is necessary. You can also
use the prdbd utility to print the contents of the database dictionary.
A database dictionary contains an information table for each of these categories: files,
sets, set members, records, compound keys, fields (which also include compound keys),
and sort fields (fields that are referenced in an order by clause in a set definition). For
each table, there is an entry for each database item of that category, which contains the
details for that item. (To get the number of items of a certain category, use the
appropriate c_size_* function.) When the database schema is processed, the database
dictionary is created and stored in a server file that is named after the database and has a
.dbd suffix.
When using many of the c_ functions and all Core API (d_) functions that take
parameters for these database items, the indexed form of the item must be used. An
indexed category of database items is numbered sequentially from 0 to the number of
items that are in the category. Because offsets may be used in the database header file
constant defintions, you can obtain the index number from the constants for sets,
records, and fields by using the c_st_idx, c_rt_idx, and c_fd_idx functions, respectively.
Note: File indexes are identical to their constant definitions in the database header file,
so a conversion function is not necessary. Indexes for compound keys, set members, and
sort fields are not used in Core API functions.
When you have finished using these functions, call c_freedict to free the cached database
tables and perform other cleanup.
Dictionary Access API Functions (c_ Prefix) 4-1

c_db_name
c_db_name Get the name of a database
Syntax char *c_db_name (RDM_DB hDb)
Parameters hDb [Input] The database handle.
Description This function retrieves the name of the specified database.
Return Values A pointer to the database name

c_fd_dim
c_fd_dim Get the number of elements in a field dimension
Syntax short c_fd_dim (short fd_number, short dim_elem, RDM_DB hDb)
Parameters fd_number [Input] A field table index (see c_fd_idx).

dim_elem [Input] An element of the dimension array for a
field. The element can be 0, 1, or 2 (MAXDIMS). If
a field has no dimensions, all array elements are 0.
hDb [Input] The database handle.
Description This function retrieves a dimension for the field element represented
by the fd_number and dim_elem parameters. Every field can have up
to three dimensions. If a field has no dimensions, all elements are
zero.
Return Values The size of the specified field element dimension
See Also c_fd_idx

c_fd_flags
c_fd_flags Get the attribute flags of a field
Syntax short c_fd_flags (short fd_number, RDM_DB hDb)
Parameters fd_number [Input] The field table index for the field (see
c_fd_idx).
Description This function retrieves field attribute flags associated with the
specified field. Possible values of flags are:
SORTFLD Field is used in by clause of a set specification
STRUCTFLD Field is a member of a structure field
UNSIGNEDFLD Field is unsigned
STATIC Field is static
COMKEYED Field is included in a compound key
Return Values The field attribute flags for the field
See Also c_fd_idx

c_fd_idx
c_fd_idx Convert a field type to a field table index
Syntax short c_fd_idx (long fld, RDM_DB hDb)
Parameters fld [Input] The field type.

Description This function converts a field type (defined in a database header

file) to a field table index.
Return Values The field table index
See Also c_rt_idx

c_fd_key
c_fd_key Get the key field type
Syntax short c_fd_key (short fd_number, RDM_DB hDb)

Description This function retrieves a key field type. Possible values are:
NOKEY Not a key field
DUPLICATES A non-unique key field (duplicates allowed)
UNIQUE A unique key field
Return Values The key field type
See Also c_fd_idx

c_fd_keyfile
c_fd_keyfile Get the file table index for a key file
Syntax short c_fd_keyfile (short fd_number, RDM_DB hDb)

Description This function retrieves the file table entry for the key file containing
the specified field. If fd_number does not specify a key field, the
function returns a value of -1.
Return Values The file table entry
See Also c_fd_idx, c_fd_key

c_fd_keyno
c_fd_keyno Get prefix number of a key
Syntax short c_fd_keyno (short fd_number, RDM_DB hDb)

Description This function retrieves the prefix number of the specified key. A
key prefix is used in key files to distinguish between two different
keys in the same key file. If fd_number does not specify a key field,
the function returns a value of -1.
Return Values The key prefix number
See Also c_fd_idx, c_fd_key

c_fd_len
c_fd_len Get the length of a field
Syntax short c_fd_len (short fd_number, RDM_DB hDb)

Description This function retrieves the length, in bytes, of the specified field.
The length is the total length of the field, even if the field is grouped
or dimensioned.
Return Values The length of the field
See Also c_fd_idx, c_rec_len

c_fd_name
c_fd_name Get the name of a field
Syntax char *c_fd_name (short fd_number, RDM_DB hDb)

Description This function retrieves the name of the specified field.
Return Values A pointer to the field name
See Also c_fd_idx

c_fd_rec
c_fd_rec Get the record table entry of the record containing the specified field
Syntax short c_fd_rec (short fd_number, RDM_DB hDb)

Description This function retrieves the record table index for the record
containing the specified field.
Return Values The record table index
See Also c_fd_idx, c_rt_fields, c_rt_index

c_fd_size
c_fd_size Get the size of a field
Syntax short c_fd_size (long field, RDM_DB hDb)
Parameters field [Input] A field table index (see c_fd_idx).

Description This function retrieves the size, in bytes, of the specified field.
Return Values The field size
See Also c_fd_idx

c_fd_type
c_fd_type Get the field type
Syntax unsigned char c_fd_type (short fd_number, RDM_DB hDb)

Description This function retrieves the type of the specified field. Possible
values are:
CHARACTER Character
SHORTINT Short integer
REGINT Integer
LONGINT Long integer
FLOAT Floating point
DOUBLE Double floating point
DBADDR Database address
GROUPED Grouped
COMKEY Compound key
Return Values The field type
See Also c_fd_idx, c_fd_len

c_field_offset
c_field_offset Get the offset of a field within a record
Syntax short c_field_offset (short fd_number, RDM_DB hDb)

Description This function retrieves the offset of a field within a record.
Return Values The field offset
See Also c_fd_idx, c_fd_len

c_freedict
c_freedict Free the cached tables in a database
Syntax short c_freedict (RDM_DB hDb)
Description This function frees the cached tables for the specified database. Call
this function when you are finished using the dictionary access
functions.
Return Values S_OKAY

c_ft_name
c_ft_name Get the name of a file
Syntax char *c_ft_name (short element, RDM_DB hDb)
Parameters element [Input] A file table index.

Description This function retrieves a file name for the specified file.
Return Values A pointer to the file name
See Also c_rt_file

c_ft_slots
c_ft_slots Get the number of record slots per page of a file
Syntax short c_ft_slots (short element, RDM_DB hDb)

Description This function retrieves the number of record slots per page for the
specified file.
Database pages are divided into slots, where each slot contains one
record. If there are records of different sizes in the data file, the slot
size must be large enough to accommodate the size of the largest
record.
Return Values The number of slots

c_ft_type
c_ft_type Get the file type
Syntax short c_ft_type (short element, RDM_DB hDb)

Description This function retrieves the file type for the specified file. The
possible types are:
DATA Data file
KEY Key file
BLOB BLOB file
Return Values The file type

c_kt_field
c_kt_field Get the number of a field contained in compound key
Syntax short c_kt_field (short kt_number, RDM_DB hDb)
Parameters kt_number [Input] A compound key table index.

Description This function retrieves the field table index of a field contained in a
compound key.
Return Values The compound key field table index

c_kt_key
c_kt_key Get the field number of a compound key
Syntax short c_kt_key (short kt_number, RDM_DB hDb)

Description This function retrieves the field table index for the specified
compound key.
Return Values The field table index for the compound key

c_kt_ptr
c_kt_ptr Get the field offset of a compound key
Syntax short c_kt_ptr (short kt_number, RDM_DB hDb)

Description This function retrieves the offset to the start of field data in the
specified compound key.
Return Values The compound key field offset

c_mt_record
c_mt_record Get the record table entry for a member
Syntax short c_mt_record (short mt_number, RDM_DB hDb)
Parameters mt_number [Input] A member table index.

Description This function retrieves the record table index for the specified
member.

c_mt_sort_fld
c_mt_sort_fld Get the table entry for the first sort field
Syntax short c_mt_sort_fld (short mt_number, RDM_DB hDb)
Parameters mt_number [Input] A member table index for a set.

Description This function retrieves the sort field table index for the first sort
field.
Return Values The sort table index
See Also c_se_fld

c_mt_totsf
c_mt_totsf Get the total number of sort fields
Syntax short c_mt_totsf (short mt_number, RDM_DB hDb)
Parameters mt_number [Input] A member table index for a set.

Description This function retrieves the total number of sort field table entries for
the specified member.
Return Values The total number of sort fields
See Also c_se_fld

c_rec_len
c_rec_len Get the length of a record
Syntax short c_rec_len (short record, RDM_DB hDb)
Parameters record [Input] A record table index.

Description This function retrieves the length, in bytes, of the specified record.
Return Values The record length

c_rt_fdtot
c_rt_fdtot Get the total number of record fields
Syntax short c_rt_fdtot (short record, RDM_DB hDb)

Description This function retrieves the total number of fields contained in the
specified record. Use the returned value in a loop in conjunction
with c_rt_fields to loop over all the field entries for a record.
Compound key definitions follow the field definitions in the field
table, for a given record. This value is -1 if the record is a system
record.
Return Values The number of fields in the record

c_rt_fields
c_rt_fields Get the index of the first field
Syntax short c_rt_fields (short record, RDM_DB hDb)

Description This function retrieves the index of the first field in the field table for
the specified record.
Return Values The field index
See Also c_rt_fdtot

c_rt_file
c_rt_file Get the file table index for a record
Syntax short c_rt_file (short record, RDM_DB hDb)

Description This function retrieves the file table index for the file containing the
specified record.
Return Values The file table index

c_rt_flags
c_rt_flags Get the flags for a record table
Syntax short c_rt_flags (short record, RDM_DB hDb)
Parameters record [Input] The record table index.

Description This function retrieves flags associated with the specified record.
The possible flag settings are STATIC and COMKEYED.
Return Values The record flags

c_rt_idx
c_rt_idx Convert a record type to a record table index
Syntax short c_rt_idx (short rec)
Parameters rec [Input] The record type from a database header file.
Description This function converts the specified record type to a record table
index.

c_rt_name
c_rt_name Get the name of a record
Syntax char *c_rt_name (short record, RDM_DB hDb)

Description This function retrieves the name of the specified record.
Return Values A pointer to the record name

c_se_fld
c_se_fld Get the field table index for a sort field
Syntax short c_se_fld (short srt_number, RDM_DB hDb)
Parameters srt_number [Input] A sort table index.

Description This function retrieves the field table index for a field used in a
sorted set.
Return Values The sort field table index

c_size_fd
c_size_fd Get the size of a field table
Syntax short c_size_fd (RDM_DB hDb)
Description This function retrieves the size of a field table, listing references to
fields of records included in the database. The ddlproc utility uses
this size to determine table numbering when it creates the field table
and stores it in the database dictionary file.
Return Values The field table size, in bytes

c_size_ft
c_size_ft Get the size of a file table
Syntax short c_size_ft (RDM_DB hDb)
Description This function retrieves the size of a file table, listing references to
files included in the database. The ddlproc utility uses this size to
determine table numbering when it creates the file table and stores
it in the database dictionary file.
Return Values The file table size, in bytes

c_size_kt
c_size_kt Get the size of a compound key table
Syntax short c_size_kt (RDM_DB hDb)
Description This function retrieves the size of a compound key table, listing
references to compound keys used in the database. The ddlproc
utility uses this size to determine table numbering when it creates
the compound key table and stores it in the database dictionary file.
Return Values The compound key table size, in bytes

c_size_mt
c_size_mt Get the size of a set member table
Syntax short c_size_mt (RDM_DB hDb)
Description This function retrieves the size of a set member table, listing
references to member records of sets used in the database. The
ddlproc utility uses this size to determine table numbering when it
creates the set member table and stores it in the database dictionary
file.
Return Values The member table size, in bytes

c_size_rt
c_size_rt Get the size of a record table
Syntax short c_size_rt (RDM_DB hDb)
Description This function retrieves the size of a record table, listing references to
records in the database. The ddlproc utility uses this size to
determine table numbering when it creates the record table and
stores it in the database dictionary file.
Return Values The record table size, in bytes

c_size_srt
c_size_srt Get the size of a sort table
Syntax short c_size_srt (RDM_DB hDb)
Description This function retrieves the size of a sort table, listing references to
fields used to order a set member. The ddlproc utility uses this size
to determine table numbering when it creates the sort table and
stores it in the database dictionary file.
Return Values The sort table size, in bytes

c_size_st
c_size_st Get the size of a set table
Syntax short c_size_st (RDM_DB hDb)
Description This function retrieves the size of a set table, listing references to sets
in the database. The ddlproc utility uses this size to determine table
numbering when it creates the set table and stores it in the database
dictionary file.
Return Values The set table size, in bytes

c_st_flags
c_st_flags Get the flags for a set table
Syntax short c_st_flags (short st_number, RDM_DB hDb)
Parameters st_number [Input] The set table index.

Description This function retrieves flags associated with the specified set table.
There are currently no used values for this variable.
Return Values The set table flags

c_st_idx
c_st_idx Convert a set type to a set table index
Syntax short c_st_idx (short set)
Parameters set [Input] The set from a database header file.
Description This function converts the set type for the specified set to a set table
index.
Return Values The set table index

c_st_members
c_st_members Get the member table index for the first set member
Syntax short c_st_members (short st_number, RDM_DB hDb)
Parameters st_number [Input] A set table index.

Description This function retrieves the member table index for the first member
record in the specified set. Use this value in conjunction with
c_st_memtot to set up a loop that retrieves all member table entries
for a given set.
Return Values The member table index
See Also c_st_memtot

c_st_memtot
c_st_memtot Get the number of member records in a set
Syntax short c_st_memtot (short st_number, RDM_DB hDb)

Description This function retrieves the number of member records in the

specified set. Use this value in conjunction with c_st_members to
set up a loop that retrieves all member table entries for a given set.
Return Values The number of member records
See Also c_st_members

c_st_name
c_st_name Get the name of a set
Syntax char *c_st_name (short st_number, RDM_DB hDb)

Description This function retrieves the name of the specified set.
Return Values A pointer to the set name

c_st_order
c_st_order Get ordering method of a set
Syntax short c_st_order (short st_number, RDM_DB hDb)

Description This function retrieves the ordering method for the specified set.
The function returns one of these values:
FIRST Order first
LAST Order last
ASCENDING Order ascending
DESCENDING Order descending
NEXT Order next
Return Values The set ordering method

c_st_own_rt
c_st_own_rt Get the record table index for an owner record
Syntax short c_st_own_rt (short st_number, RDM_DB hDb)

Description This function retrieves the record table index for the owner record
of the specified set.

Chapter 5
Customized Comparison Function
Module Functions (cmp Prefix)
This chapter describes the functions that are used in a shared library to create
customized comparison functions for sorting fields or columns in a Velocis SQL or Core
DDL schema. The names of these module functions have a cmp prefix. To use these
module functions, you must implement them in the usercmp.c module file and include
the usercmp.h header file. When declaring and defining these functions, you have to
include the REXTERNAL macro between the function type and the function name.
To register the customized comparison functions with the Velocis server, you need to
use a comparison function load table. The load table contains a structure element for
each comparison function. The structure, which includes members for the name and
address of each comparison routine, is defined as follows:
typedef struct cmploadtable {
char cmpName[33]; /* name of the comparison routine */
CMPFUNCTION *cmpFunction; /* address of the compare function */
} CMPLOADTABLE;
The function address member of the structure is a pointer to the function that you
implement to create the comparison routine. Use the cmpFunction function interface to
create this function.
For more information about these functions, see Chapter 9 of the Velocis User's Guide.
Customized Comparison Function Module Functions (cmp Prefix) 5-1

cmpDescribeFcns
cmpDescribeFcns Return a list of all customized comparison functions
Syntax void REXTERNAL cmpDescribeFcns (unsigned short *NumFcns,

CMPLOADTABLE **cmpLoadTable, char **descr)
Parameters NumFcns [Output] A pointer to the number of functions

specified in the comparison function load table.
cmpLoadTable [Output] A pointer to the comparison function load
table, which contains one entry per function. Each
entry maps the function address to the function
name string.
descr [Output] A pointer to the module description
string, which is displayed on server console log
when the module is loaded.
Description Velocis loads the user comparison shared library and calls the
cmpDescribeFcns function when the server is started. As with the
ModDescribeFcns function in extension modules, this function
returns the names of the customized comparison routines and the
addresses of their respective comparison functions. You must
implement every function listed in the comparison function table.
Any attempt to open a database that references missing comparison
routines (that is, routines not returned from cmpDescribeFcns) will
fail, and an explanatory error message will be displayed.
The format of the comparison function load table is specified by the
following type definitions:
/* Comparison Function Load Table */
typedef struct cmploadtable {
char cmpName[33]; /* name of comparison routine */
CMPFUNCTION *cmpFunction; /* address of compare function */
} CMPLOADTABLE;
You must define this function in the usercmp.c module file. The
data types and constants used in usercmp.c are declared in the
usercmp.h header file.
Return Values None
See Also cmpFunction, cmpShutdown

cmpDescribeFcns
Example
/* table of customized comparison functions */
static CMPLOADTABLE CmpFcnTable[] = {
/* cmpName cmpFunction */
/* --------- ----------- */
{ "cmpSoundex", cmpSoundex }
};
/* ==================================================================
Called once to initialize module. Called during Server startup.
*/
void REXTERNAL cmpDescribeFcns(
unsigned short *NumFcns, /* out: num. of fcns in module */
CMPLOADTABLE **cmpLoadTable, /* out: addr of CmpFcnTable */
char **descr) /* out: description string */
{
*NumFcns = sizeof(CmpFcnTable)/sizeof(CmpFcnTable[0]);
*cmpLoadTable = CmpFcnTable;
*fcn_descr = "Sample of customized comparison function";
}

cmpFunction
cmpFunction Perform a customized comparison between two values
Syntax short REXTERNAL cmpFunction (const void *leftVal, size_t leftLen,

const void *rightVal, size_t rightLen)
Parameters leftVal [Input] A pointer to the left value.

leftLen [Input] The length, in bytes, of the left value.
rightVal [Input] A pointer to the right value.
rightLen [Input] The length, in bytes, of the right value.
Description Whenever a comparison is required on a particular column or field,

the runtime system or Velocis SQL automatically calls the
customized comparison function associated with that column or
field. The runtime system calls the comparison function whenever a
key operation is performed and when the d_connect function is
called on a sorted set. Velocis SQL calls the comparison function
whenever the column is referenced in a conditional expression.
Each comparison function that you define can have any name you
like. The function name does not have to match the customized
comparison name referenced in the DDL specification. The
comparison function load table returned by the cmpDescribeFcns
function specifies the mapping between the DDL name and the C
function. The customized comparison function must operate in the
same way as the standard C functions strcmp and memcmp (see
Return Values below).
You must implement all customized comparison functions in the
usercmp.c module file.
Return Values Negative (< 0) if leftVal < rightVal

Zero (0) if leftVal = rightVal
Positive (> 0) if leftVal > rightVal
See Also cmpDescribeFcns, cmpShutdown

cmpFunction
Example
#define SNDXLEN 4
/* ==================================================================
Soundex conversion routine.
*/
static void GenSoundex(
const char *name, /* in: pointer to name string */
const char *code) /* out: pointer to result code */
{
static short soundex_code[26] = {
/* a b c d e f g h i j k l m n o p q r s t u v w x y z */
0,1,2,3,0,1,2,0,0,2,2,4,5,5,0,1,2,6,2,3,0,1,0,2,0,2
};
char c;
short l, thisCode, lastCode;
code[0] = (char) toupper(*name++);

for (lastCode = 0, l = 1; l < SNDXLEN && (c = *name++);) {
thisCode = soundex_code[(short)(toupper(c) - 'A')];
if (thisCode != lastCode) {
lastCode = thisCode;
if (thisCode)
code[l++] = (char) (thisCode + '0');
}
}
while (l < SNDXLEN)
code[l++] = '0';
}
/* =============================================================
Customized soundex comparison routine.
*/
short REXTERNAL cmpSoundex(
void *leftVal, /* in: pointer to left value */
unsigned short leftLen, /* in: size of left value */
void *rightVal, /* in: pointer to right value */
unsigned short rightLen) /* in: size of right value */
{
char lSndx[SNDXLEN], rSndx[SNDXLEN];
GenSoundex(leftVal, lSndx);
GenSoundex(rightVal, rSndx);
return (short) memcmp(lSndx, rSndx, SNDXLEN);
}

cmpShutdown
cmpShutdown Shut down the customized comparison module
Syntax void REXTERNAL cmpShutdown (void)
Parameters None
Description Velocis calls this function when the Velocis server shuts down. You
can define this function to perform any necessary cleanup
operations. Typically, no cleanup will be required.
You must define this function in the usercmp.c module file.
Return Values None
See Also cmpDescribeFcns, cmpFunction

Chapter 6
Core API Functions (d_ Prefix)
This chapter contains descriptions of the functions that are used to manipulate a Core
DDL database. The functions return status and error codes that are listed in rdserrs.h.
For more information about these functions, see Chapters 8 and 9 of the Velocis User’s
Guide.
Note: These functions were formerly referred to as the runtime API functions.
Core API Functions (d_ Prefix) 6-1

d_blobdelete
d_blobdelete Delete BLOB data
Syntax short d_blobdelete (long field, RDM_DB hDb)
Parameters field [Input] The BLOB ID field.

Description This function deletes BLOB data associated with the specified BLOB
ID field of the current record. The function sets the contents of field
to NULL_BLOB.
Return Values S_DELETED S_NOCR

S_INVFLD S_NOTFOUND
S_INVREC S_OKAY
Currency None
Changes
Locking Write lock on the current record.

Requirements
See Also d_blobread, d_blobwrite

d_bloblog
d_bloblog Enable/disable the logging of BLOB data
Syntax short d_bloblog (long field, short enable, RDM_DB hDb)

enable [Input] An indicator of whether to enable BLOB
data logging. Possible values are:
0 Disable blob data logging.
1 Enable blob data logging.
Description This function enables or disables logging of BLOB data associated

with the field specified by field. When logging is enabled, the
change log will record all BLOB additions, changes, or deletions. If
BLOBs are large, this may require excessive space in the change log.
Return Values S_INVFLD

S_OKAY
Currency None
Changes
Locking None
Requirements
See Also d_blobdelete, d_blobwrite

d_blobread
d_blobread Read BLOB data
Syntax short d_blobread (long field, void *buf, long len, long *size,
RDM_DB hDb)

buf [Output] A pointer to the buffer into which the
BLOB data will be placed. This buffer must be at
least len bytes long.
len [Input] The length, in bytes, of the buffer indicated
by buf.
size [Output] A pointer to the number of bytes actually
read.
Description This function reads data into a buffer from the position of the
specified BLOB data in the current record. If the call to this function
is the first BLOB data operation for the current record, the function
reads from the start of the BLOB data. If d_blobseek has been
called to set the current position for field, reading will commence
from there. Otherwise, it reads from the point where the last read
stopped. The d_blobtell function may be used to determine the
current position.
If the BLOB data is shorter than the amount indicated in the len
parameter, the function writes the actual number of bytes it has read
to the size parameter. Following a successful call to d_blobread, the
current position in the record is advanced by size bytes.
The d_blobread function returns S_BADBLOB if Velocis indicates
that the BLOB data is corrupted. The function returns
S_NOTFOUND when it is called for the first time after it has
encountered data that is shorter than the specified length. Then, for
the next call after d_blobread returns S_NOTFOUND, the function
reads from the start of the indicated BLOB data.
Return Values S_BADBLOB S_NOCR

S_DELETED S_NOTFOUND
S_INVFLD S_OKAY
S_INVREC

d_blobread
Currency None
Changes
Locking If dirty reads are not enabled, a read lock on the current record.
Requirements
See Also d_blobseek, d_blobtell, d_blobwrite

d_blobseek
d_blobseek Find a position in BLOB data
Syntax short d_blobseek (long field, long offset, SEEK_TYPE origin,

RDM_DB hDb)

offset [Input] The byte offset in the BLOB data. The offset
is the number of bytes from the point of origin
(origin parameter).
origin [Input] The origin indicator for the seek operation.
To place the origin at the current position, specify
B_CURRENT. To place the origin at the beginning
or end of the BLOB data, specify B_START or
B_END, respectively.
Description This function adjusts the current byte offset in BLOB data according
to the specified point of origin. If the origin parameter is set to
B_START, the offset must be greater than or equal to zero and
d_blobseek sets the position from the start of the BLOB data. If
origin contains B_CURRENT, d_blobseek sets the position to offset
bytes from the current position. Finally, if origin contains B_END,
the offset must be less than or equal to zero, and d_blobseek sets
the position from the end of the BLOB data. The d_blobseek
function returns S_BLOBPOS if the offset sets the position beyond
the boundaries of the BLOB data.
Return Values S_BLOBPOS S_NOCR

S_INVFLD S_OKAY
S_INVREC
Currency None
Changes
Requirements
See Also d_blobread, d_blobtell, d_blobwrite

d_blobsize
d_blobsize Retrieve the size of BLOB data
Syntax short d_blobsize (long field, long *size, RDM_DB hDb)

size [Output] A pointer to the size, in bytes, of the BLOB
data.
Description This function retrieves the size of the specified BLOB data associated
with the indicated field identifier (field) in the current record.

S_INVFLD S_OKAY
S_INVREC
Currency None
Changes
Requirements
See Also d_blobseek, d_blobtell

d_blobtell
d_blobtell Retrieve the current byte offset position of BLOB data
Syntax short d_blobtell (long field, long *offset, RDM_DB hDb)

offset [Output] A pointer to the current byte offset
position in the BLOB data.
Description This function retrieves the current byte offset position from the start
of the BLOB data associated with the specified field identifier (field)
in the current record.
The current byte offset is affected by the d_blobread, d_blobseek,
and d_blobwrite functions.

S_INVFLD S_OKAY
S_INVREC
Currency None
Changes
Requirements
See Also d_blobread, d_blobseek, d_blobwrite

d_blobwrite
d_blobwrite Write BLOB data
Syntax short d_blobwrite (long field, void *buf, long size, RDM_DB hDb)

buf [Input] A pointer to the buffer containing the BLOB
data.
size [Input] The size, in bytes, of the buffer indicated by
buf.
Description This function writes BLOB data from the indicated buffer, starting at
the current position of the specified BLOB in the current record. If
the application is calling d_blobwrite as the first operation for the
current record, the function begins the write at the start of the BLOB
data. If the value stored in field is NULL_BLOB, the function creates
the BLOB.
Note: By using this function in conjunction with d_blobseek, you

can insert data into the middle of a BLOB without causing
truncation. You can also make consecutive calls to d_blobwrite to
write data from different sources to the same BLOB; the successive
calls to d_blobwrite append the data to the end of the BLOB, and
positioning calls to d_blobseek are not necessary in this case.
Return Values S_NOSPACE
Currency None
Changes

Requirements
See Also d_blobread, d_blobseek, d_blobtell

d_checkpoint
d_checkpoint Force a checkpoint on the server
Syntax short d_checkpoint (RDM_SESS hSess)
Parameters hSess [Input] The session handle.
Description This function forces a checkpoint to occur at a convenient time

during database processing. Note that forcing a checkpoint does not
increase database recoverability, which is ensured through change
logging.
Database checkpointing is a process that occurs when the Velocis
server determines that it needs to clear space in the cache for new
database pages. It is a controlled, safe update of modified pages in
the cache to the database files. Data is recoverable, regardless of the
stage of the checkpoint should a crash occur. For this to be possible,
the checkpoint operation must "sync" the files it is writing (make
sure they are physically on the disk) before proceeding. This can
cause a checkpoint to take several seconds. During a checkpoint,
clients can detect noticeable pauses (especially in standalone
configurations).
If used too frequently, the d_checkpoint function can decrease the
overall throughput of a server. Unless a smoother server response is
needed, it is best to let the server decide when to perform
checkpoints.
Currency None
Changes
Locking None
Requirements

d_close
d_close Close all opened databases in a server session
Syntax short d_close (RDM_SESS hSess)
Description This function closes all databases that have been opened in a server
session. If a transaction is active, the function aborts it (see
d_trabort). The user remains logged into the server and can issue
subsequent d_open calls.
Return Values S_DBOPEN

S_UNAVAIL
Currency Once the database has been closed, the currency (current record,
Changes owner, and members of a set) is no longer relevant or accessible.
Locking None. All locks held by the application are freed.

Requirements
See Also d_iclose, d_iopen, d_open, d_trabort, s_login, s_logout
Example
main()
{
/* A Velocis Database Server application program */
...
s_login("dbServer","myname","secret",&hSess);
d_open("tims", "s", hSess, &hDb);
... /* Access "tims" database */
d_close(hSess);
s_logout(hSess);
}

d_cmfree
d_cmfree Free the record instance lock on the current member
Syntax short d_cmfree (short set, RDM_DB hDb)
Parameters set [Input] The set type that includes the member
record.
Description This function frees the record instance lock on the current member
of the specified set. You must establish a valid owner and member
for the set before the application can call this function.
The S_TRFREE error code is returned if the application tries to free a
read lock within a transaction but has not enabled the freeing of
read locks (see d_rdlockmodes). The d_cmfree function returns
S_NOTLOCKED if the application tries to free a record with no
record instance locks.
Return Values S_DELETED S_NOCM S_NOTLOCKED

S_INVNULL S_NOCR S_TRFREE
S_INVSET S_NOLOCK
Currency None
Changes
Locking None
Requirements
See Also d_cmlock, d_cofree, d_colock, d_crfree, d_crlock, d_crslock,

d_csfree, d_cslock, d_dbafree, d_dbalock, d_grplock,
d_rdlockmodes, d_release
Example
... /* Do a safe read of all members of set*/
d_setro(SET1, hDb);
d_cslock(SET1, "r", hDb);
for (stat = d_findfm(SET1, hDb); stat == S_OKAY;
stat = d_findnm(SET1, hDb) ) {
d_cmlock(SET1, "r", hDb);
d_recread(REC1, &rec1, hDb);
...
d_cmfree(SET1, hDb);
}

d_cmlock
d_cmlock Request a record instance lock on the current member
Syntax short d_cmlock (short set, char *ltype, RDM_DB hDb)
Parameters set [Input] The set type that includes the member
record.
ltype [Input] The lock type indicator. To apply a read
lock, specify "r". To apply a write lock, specify "w".
Description This function requests a record instance lock of the specified type for
the current member of the indicated set. You must establish a valid
owner and member for the set before the application can call
d_cmlock.
Note that locking a set member only allows access to the member
record. The application must separately lock the owner if it needs to
access the owner. It must also separately lock the set if it needs to
access the set connection.
Your application can upgrade or downgrade an existing lock.
However, it cannot downgrade a write lock within a transaction.
Return Values S_ILLDOWNG S_NOTGRANTED

S_LOCKED S_OKAY
Currency None
Changes
Locking None
Requirements
See Also d_cmfree, d_cofree, d_colock, d_crfree, d_crlock, d_crslock,


d_cmlock
Example
... /* Update member with new value */
d_findfm(SET1, hDb);
d_trbegin("upd", hSess);
d_cmlock(SET1, "r", hDb);
d_recread(REC1, rec1, hDb);
...
d_cmlock(SET1, "w", hDb);
d_recwrite(REC1, &rec1, hDb);
d_trend(hSess);

d_cmtype
d_cmtype Get the record type of the current member
Syntax short d_cmtype (short set, short *cmtype, RDM_DB hDb)
Parameters set [Input] The set that includes the member record.
cmtype [Output] A pointer to the record type.
Description This function retrieves the record type for the current member
record in the specified set. The d_cmtype function is particularly
useful in determining the current member record type of a multi-
member set.
Return Values S_DELETED S_INVSET

S_INVNULL S_NOCM
Currency None
Changes
Locking Locking is optional. However, if your application does not provide

Requirements record locking, another user might be able to modify or delete the
current member record.
See Also d_cotype, d_crtype
Example
short rtype; /* Record type */
long fld; /* Field type */
char txt[80]; /* Comment text */
...
d_cmtype(COMMENTS, &rtype, hDb);
switch ( rtype ) {
case TEXT30:
fld = T30_LINE;
break;
case TEXT55:
fld = T55_LINE;
break;
case TEXT80:
fld = T80_LINE;
}
d_csmread(COMMENTS, fld, txt, hDb);

d_cofree
d_cofree Free the record instance lock on the current owner
Syntax short d_cofree (short set, RDM_DB hDb)
Parameters set [Input] The set owned by the owner record.

Description This function frees the record instance lock on the current owner of
the specified set. You must establish a valid owner for the set before
the application can call d_cofree.
Return Values S_INVSET S_NOLOCK

S_NOCO S_TRFREE
Currency None
Changes
Locking None
Requirements
See Also d_cmfree, d_cmlock, d_colock, d_crfree, d_crlock, d_crslock,

Example
/* Read owner of a set */
d_colock(SET1, "r", hDb);
d_csoread(SET1, FLD1, &fld1, hDb);
d_cofree(SET1, hDb);

d_colock
d_colock Request a record instance lock on the current owner
Syntax short d_colock (short set, char *ltype, RDM_DB hDb)
Parameters set [Input] The set type that includes the owner record.
lock, specify "r".To apply a write lock, specify "w".
the current member of the indicated set. You must establish a valid
owner for the set before the application can call d_colock.
Note that locking a set owner only allows access to the owner
record. The application must separately lock the members if it
needs to access them. It must also separately lock the set if it needs
to access the set connection.
Return Values S_BADTYPE S_INVDB S_OKAY

S_CONFLICT S_INVSET S_STATIC
S_DBPERM S_LOCKED S_UNAVAIL
S_DELETED S_NOCO S_UPGDEN
S_ILLDOWNG S_NOTGRANTED
Currency None
Changes
Locking None
Requirements
See Also d_cmfree, d_cmlock, d_cofree, d_crfree, d_crlock, d_crslock,

Example
d_trbegin("updown", hSess); /* Update owner of a set */
d_colock(SET1, "w", hDb);
d_recwrite(REC1, &rec1, hDb);
d_trend(hSess);

d_connect
d_connect Connect the current record to a set
Syntax short d_connect (short set, RDM_DB hDb)
Parameters set [Input] The set to which the current record is

connected.
Description This function connects the current record to the current owner of the
specified set. The record is placed in the set in the order specified in
the schema for the database. Upon successful completion of
d_connect, the connected record becomes the current member of the
specified set.
Return Values S_DELETED S_NOCO

S_INVMEM S_NOCR
S_INVSET S_SETCLASH
S_ISOWNED S_UNCOMMITED
Currency curr_mem[set] = curr_rec;

Changes
Locking The set (instance or type) must be write-locked.

Requirements
See Also d_discon, d_disdel
Example
struct info irec; /* Tech. info record */
...
/* Make author record current owner of has_published */
d_setor(HAS_PUBLISHED, hDb);
...
/* Create new info record */
if ( d_fillnew(INFO, &irec, hDb) == S_OKAY ) {
/* Connect new info record to has_published set */
d_connect(HAS_PUBLISHED, hDb);
}

d_cotype
d_cotype Get the record type of the current owner
Syntax short d_cotype (short set, short *cotype, RDM_DB hDb)
Parameters set [Input] The set owned by the owner record.

cotype [Output] A pointer to the owner record type.
Description This function retrieves the record type for the current owner record
in the specified set.

S_INVNULL S_NOCO
Currency None
Changes
Locking This function does not require locks. However, if there is no lock on
Requirements the record, there is no guarantee that another user will not modify
or delete this record.
See Also d_cmtype, d_crtype
Example
short rtype;
...
/* Check consistency of database */
d_cotype(HAS_PUBLISHED, &rtype, hDb);
if ( rtype != AUTHOR )
pr_dberror();

d_crfree
d_crfree Free the record instance lock on the current record
Syntax short d_crfree (RDM_DB hDb)
Description This function frees the record instance lock on the current record.
You must establish a valid current record before the application can
call d_crfree.
The d_crfree function returns S_TRFREE if the application attempts
to free a write lock within a transaction. The application receives the
same error if it attempts to free a read lock within a transaction, but
has not enabled the freeing of read locks (see d_rdlockmodes). The
d_crfree function returns an S_NOLOCK error code if the
application attempts to free a record that has no record instance
lock.
Return Values S_DELETED S_NOLOCK

S_INVNULL S_NOTLOCKED
S_INVSET S_TRFREE
S_NOCM
Currency None
Changes
Locking None
Requirements
See Also d_cmfree, d_cmlock, d_cofree, d_colock, d_crlock, d_crslock,

d_rdlockmodes, d_release, d_trabort, d_trend, d_trrollback
Example
/* Display record on screen */
...
d_keyfind(key1, usrval, hDb);
d_crlock("r", hDb);
...
... /* Display field */
...
d_crfree(hDb);

d_crget
d_crget Get the database address of the current record
Syntax short d_crget (DB_ADDR *dba, RDM_DB hDb)
Parameters dba [Output] A pointer to the database address of the

current record.
Description This function retrieves the database address of the current record
and copies the address into the location specified by dba. If the
current record is null (NULL_DBA), the d_crget function returns
S_NOCR and sets the dba parameter to NULL_DBA. Use the
d_crget function with the d_crset function to save and restore the
current record.

S_INVNULL
S_NOCR
Currency None
Changes
Locking None
Requirements
See Also d_crset, d_csmget, d_csmset, d_csoget, d_csoset
Example
DB_ADDR save_dba;
...
/* Save current record for later retrieval */
d_crget(&save_dba, hDb);
...
/* Later, retrieve saved record */
d_crset(&save_dba, hDb);
d_recread(REC1, &irec, hDb);

d_crlock
d_crlock Request a record instance lock on the current record
Syntax short d_crlock (char *ltype, RDM_DB hDb)
Parameters ltype [Input] The lock type indicator. To apply a read

the current record. You must establish a valid current record before
the application can use d_crlock.
Return Values S_CONFLICT S_INVDB S_NOCM

S_DBPERM S_INVMEM S_NOCO
S_DELETED S_INVNULL S_NOTGRANTED
S_EOS S_INVREC S_STATIC
S_ILLDOWNG S_INVSET S_UNAVAIL
S_INVADDR S_LOCKED S_UPGDEN
Currency None
Changes
Locking None
Requirements
See Also d_cmfree, d_cmlock, d_cofree, d_colock, d_crfree, d_crslock,

Example
/* Display record on screen */
...
d_keyfind(key1, usrval, hDb);
d_crlock("r", hDb);
...
... /* Display field */
...
d_crfree(hDb);

d_crread
d_crread Read data from a field in the current record
Syntax short d_crread (long field, void *data, RDM_DB hDb)
Parameters field [Input] The field type to read from the current
record.
data [Output] A pointer to the field contents.
Description This function copies the contents of the specified field from the
current record to the area indicated by the data parameter. If field
specifies an array, d_crread reads the entire array (elements of an
array cannot be read individually). In the case of BLOB data, this
function retrieves the BLOB ID, a long integer that indicates the
page number in the BLOB ID file where the BLOB data begins.
Note: You must be sure that the data area is at least as long as the
field. A good practice is to use the defined constants from the
header file that is generated by the ddlproc utility (for example,
"char name[SIZEOF_NAME];").

S_INVFLD S_NOTLOCKED
S_INVNULL
Currency None
Changes
Locking If dirty reads are not enabled, the current record requires a lock.
Requirements
See Also d_csmread, d_csoread
Example
char name[SIZEOF_NAME]; /* Author name */
...
/* Find author of info record */
d_findco(HAS_PUBLISHED, hDb);
d_crread(NAME, name, hDb);

d_crset
d_crset Set the database address of the current record
Syntax short d_crset (DB_ADDR *dba, RDM_DB hDb)
Parameters dba [Input] A pointer to the new database address

value.
Description This function sets the current record to the database address
specified by dba. Use the d_crset function in conjunction with the
d_crget function to save and restore the current record.

S_DELETED
S_INVADDR
Currency curr_rec = *dba;

Changes
Locking None
Requirements
See Also d_crget, d_csmget, d_csmset, d_csoget, d_csoset
Example
DB_ADDR save_dba;
...
/* Save current record for later retrieval */
d_crget(&save_dba, hDb);
...
/* Later, retrieve saved record */
d_crset(&save_dba, hDb);

d_crslock
d_crslock Request a set instance lock based on the current record
Syntax short d_crslock (short set, char *ltype, RDM_DB hDb)
Parameters set [Input] The set that includes the current record.
Description This function requests a set instance lock of the specified type based
on the current member record of the specified set, instead of the
owner record. You must establish a valid current record before
your application can call d_crslock.
This function allows safe "upward navigation" from a member to its
owner. This single function performs the equivalent of d_setmr
followed by d_colock. The d_crslock function is required in this
situation because a d_setmr requires a set instance lock.
If the record is not currently connected to an instance of set type set,
d_crslock returns S_EOS. If the request is for a lock that is identical
to the existing set instance lock, d_crslock ignores the request and
returns S_OKAY.
Note that locking the set instance only allows access to the set
connection. The application must separately lock the owner if it
needs to access this record. It must separately lock the set members
if it needs to access them.

Currency None
Changes

d_crslock
Locking None
Requirements
See Also d_cmfree, d_cmlock, d_cofree, d_colock, d_crfree, d_crlock,

Example
d_crslock (SET1, "r", hDb); /* Safely find owner of current record */
d_findco (SET1, hDb)

d_crtype
d_crtype Get the record type of the current record
Syntax short d_crtype (short *crtype, RDM_DB hDb)
Parameters crtype [Output] A pointer to the record type.

Description This function retrieves the record type of the current record and
writes the type in the location indicated by the crtype parameter.
Return Values S_DBOPEN S_INVNULL

S_DELETED S_NOCR
Currency None
Changes
Locking This function does not require locks. However, if there is no lock on
Requirements the specified record, there is no guarantee that another user will not
modify or delete the record.
See Also d_cmtype, d_cotype
Example
SHORT rtype;
...
d_crtype(&rtype, hDb);
if ( rtype == AUTHOR )
pr_author();
else if ( rtype == INFO )
pr_info();

d_crwrite
d_crwrite Write to a field in the current record
Syntax short d_crwrite (long field, void *data, RDM_DB hDb)
Parameters field [Input] The field type within the current record.
data [Input] A pointer to the value to write for the
specified field.
Description This function writes the value specified by the data parameter to the
indicated field in the current record. If field indicates a key field,
d_crwrite automatically updates the key. If field indicates a sort
field of a set arranged in ascending or descending order, the
d_crwrite function automatically adjusts the position of the record
in the set to reflect the order indicated. (In this case, a set instance or
set type lock is required.) If field indicates an array field, d_crwrite
writes the entire array (elements of an array cannot be written
individually).
Your application cannot use the d_crwrite function to modify a
compound key field, but you may modify the component fields of a
compound key. When a component field is modified, the key is
repositioned. If you intend to modify more than one component
field of the same compound key, it may be more efficient to use
d_recwrite, because the key will be repositioned only once.
The application cannot use the d_crwrite function to modify a BLOB
ID field. If the function is called for this type of data, it returns
S_BLOBUPD.
Return Values S_BLOBUPD S_INVFLD S_NOSPACE

S_DBPERM S_INVFLOAT S_NOTLOCKED
S_DELETED S_INVNULL S_TRNOTACT
S_DUPLICATE S_ISCOMKEY S_UNCOMMITED
S_INVDOUB S_NOCR

d_crwrite
Currency None
Changes
Locking Write lock on the current record. If the specified field is used as a
Requirements sort field in a set, and it is being changed, a write lock is required on
the set as well.
See Also d_csmwrite, d_csowrite, d_recwrite
Example
/* Change info record id_code*/
chg_id(char *old_id, char *new_id)
{
if ((stat = d_keyfind(ID_CODE, old_id, hDb)) == S_OKAY )
d_crwrite(ID_CODE, new_id, hDb);
else if ( stat == S_NOTFOUND )
printf("id_code %s not found\n", old_id);
return;
}

d_csfree
d_csfree Free the set instance lock on a set
Syntax short d_csfree (short set, RDM_DB hDb)
Parameters set [Input] The set type on which to free the lock.
Description This function frees the set instance lock on the specified set. You
must establish a valid owner for the set before the application can
call d_csfree.
The d_csfree function returns S_TRFREE if the application attempts
to free a write lock within a transaction. The same error code is
returned if the application tries to free a read lock within a
transaction but has not enabled the freeing of read locks (see
d_rdlockmodes). The d_csfree function returns an S_NOLOCK
code if your application attempts to free a set that has no set
instance locks.
Return Values S_INVSET S_NOLOCK

S_NOCO S_TRFREE
Currency None
Changes
Locking None
Requirements

d_crslock, d_cslock, d_dbafree, d_dbalock, d_grplock,
Example
/* Safely navigate a set */
d_setor(SET1, hDb);
stat = d_findnm(SET1, hDb))
{ ... }
d_csfree(SET1, hDb);

d_cslock
d_cslock Request a set instance lock on a set
Syntax short d_cslock (short set, char *ltype, RDM_DB hDb)
Parameters set [Input] The set type to lock.

Description This function requests a set instance lock of the specified type for the
current set. You must establish a valid current owner for the set
before the application can call d_cslock.
Note that locking a set only allows access to the set connection. The
application must separately lock the owner if it needs to access the
owner’s contents. It must also separately lock the set members if it
needs to access them.

Currency None
Changes
Locking None
Requirements

d_crslock, d_csfree, d_dbafree, d_dbalock, d_grplock,

d_cslock
Example
/* Safely navigate a set */
d_setor(SET1, hDb);
stat = d_findnm(SET1, hDb))
{
...
}
d_csfree(SET1, hDb);

d_csmget
d_csmget Get the database address of the current set member
Syntax short d_csmget (short set, DB_ADDR *dba, RDM_DB hDb)
Parameters set [Input] The set containing the current member.

dba [Output] A pointer to the database address of the
current record.
Description This function retrieves the database address of the current member
of the specified set and copies the address into the location specified
by dba. If the current member is null (NULL_DBA), the d_csmget
function returns S_NOCM and sets the dba parameter to
NULL_DBA. Your application uses the d_csmget function with the
d_csmset function to save and restore the current member of a set.
Return Values S_INVNULL

S_INVSET
S_NOCM
Currency None
Changes
Locking None
Requirements
See Also d_crget, d_crset, d_csmset, d_csoget, d_csoset, d_rdcurr, d_wrcurr
Example
/* Print key words for info record */
DB_ADDR dba;
...
/* Save current member of key_to_info set in
case info record was retrieved from a key word scan */
d_csmget(KEY_TO_INFO, &dba, hDb);
... /* Print key words thru info_to_key */
/* Restore current member */
d_csmset(KEY_TO_INFO, &dba, hDb);

d_csmread
d_csmread Read data from a field in the current member
Syntax short d_csmread (short set, long field, void *data, RDM_DB hDb)

field [Input] The field in the current member to read.
Description This function copies the contents of field from the current member of
the specified set and places it in the area indicated by the data
parameter. The amount of data read is determined by the dictionary
length. If the field is an array field, the d_csmread function reads
the entire array (elements of an array cannot be read individually).

S_INVFLD S_NOCM
Currency None
Changes
Locking If dirty reads are not enabled, a lock is required on the current
Requirements member of the indicated set.
See Also d_crread, d_csoread
Example
char name[32]; /* Author name /
...
/* Print all authors in the database */
for ( stat = d_findfm(AUTHOR_LIST, hDb); stat == S_OKAY;
stat = d_findnm(AUTHOR_LIST, hDb) ) {
d_csmread(AUTHOR_LIST, NAME, name, hDb);
printf("%s\n", name);
}

d_csmset
d_csmset Set the database address of the current set member
Syntax short d_csmset (short set, DB_ADDR *dba, RDM_DB hDb)
Parameters set [Input] The set containing the current member

record.
dba [Input] A pointer to the new database address.
Description This function sets the database address of the current member of the
specified set to the value specified by dba. It also sets the current
owner of the set to the record that owns the current member. Use
this function with d_csmget to save and restore the current member
of a set. You can also use d_csmset with d_crget or d_csoget.
Normally, a set instance lock is required before this function is
called (unless dirty reading is enabled). If the set is not locked and
the owner is not known, use d_crslock.

S_INVADDR S_NOTCON
S_INVMEM S_NOTLOCKED
Currency curr_mem[set] = *dba;

Changes curr_own[set] = owner of *dba through set;
Locking If dirty reading is not enabled, a lock is required on set.

Requirements
See Also d_crget, d_crset, d_crslock, d_csmget, d_csoget, d_csoset, d_rdcurr,

d_wrcurr
Example
/* Print key words for info record */
DB_ADDR dba;
...
/* Save current member of key_to_info set
in case info record was retrieved from a key word scan */
d_csmget(KEY_TO_INFO, &dba, hDb);
... /* Print key words thru info_to_key */
/* Restore current member */
d_csmset(KEY_TO_INFO, &dba, hDb);

d_csmwrite
d_csmwrite Write to a field in the current set member
Syntax short d_csmwrite (short set, long field, void *data, RDM_DB hDb)

field [Input] The field in the member record.
specified field.
indicated field in the current member of the specified set. If field
indicates a key field, d_csmwrite automatically updates the key. If
field indicates a sort field of a set arranged in ascending or
descending order, the d_csmwrite function automatically adjusts
the position of the record in the set to reflect the order indicated. If
field indicates an array field, d_csmwrite writes the entire array
(elements of an array cannot be written individually).
Your application cannot use the d_csmwrite function to modify a
The application cannot use the d_csmwrite function to modify a
BLOB ID field. If the function is called for this type of data, it
returns S_BLOBUPD. Use d_blobdelete or d_blobwrite instead.
Return Values S_BLOBUPD S_INVFLD S_ISCOMKEY

S_DBPERM S_INVFLOAT S_NOCM
S_DELETED S_INVMEM S_NOSPACE
S_DUPLICATE S_INVNULL S_NOTLOCKED
S_INVDOUB S_INVSET S_TRNOTACT

d_csmwrite
Currency None
Changes
Locking Write lock on the current member of the specified set. If the field
Requirements being updated is also used in a sort by clause for a sorted set, the set
must also be write-locked.
See Also d_crwrite, d_csowrite, d_recwrite
Example
char name[SIZEOF_NAME]; /* Author name */
...
/* Change author "Worth" to "Wirth" */
d_csmread(AUTHOR_LIST, NAME, name, hDb);
if ( strcmp(name, "Worth") == 0 )
d_csmwrite(AUTHOR_LIST, NAME, "Wirth", hDb);
}

d_csoget
d_csoget Get the database address of the current set owner
Syntax short d_csoget (short set, DB_ADDR *dba, RDM_DB hDb)
Parameters set [Input] The set containing the current owner.

dba [Output] A pointer to the database address of the
current owner record.
Description This function retrieves the database address of the current owner of
the specified set and copies the address into the location specified by
dba. If the current owner is null (NULL_DBA), the function returns
S_NOCO and sets the dba parameter to NULL_DBA. Use this
function with the d_csoset function to save and restore the current
owner of a set.

S_INVSET
S_NOCO
Currency None
Changes
Locking None
Requirements
See Also d_crget, d_crset, d_csmget, d_csmset, d_csoset
Example
DB_ADDR dba;
...
/* Save current author on stack for later processing */
d_csoget(HAS_PUBLISHED, &dba, hDb);
...
/* Restore saved author as owner of has_published */
d_csoset(HAS_PUBLISHED, &dba, hDb)

d_csoread
d_csoread Read data from a field in the current set owner
Syntax short d_csoread (short set, long field, void *data, RDM_DB hDb)

field [Input] The field in the current owner to read.
Description This function copies the contents of field from the current owner of
the specified set and places it in the area indicated by the data
parameter. The amount of data read is determined by the dictionary
length. If the field is an array field, the d_csoread function reads the
entire array (elements of an array cannot be read individually).
Return Values S_DBPERM S_INVSET

S_DELETED S_NOCO
S_INVNULL
Currency None
Changes
Locking If dirty reads are not enabled, a lock is required on the current
Requirements owner of the specified set.
See Also d_crread, d_csmread
Example
char name[SIZEOF_NAME]; /* Author name /
...
/* Print author name associated with info record */
d_csoread(HAS_PUBLISHED, NAME, name, hDb);
printf("author: %s\n", name);

d_csoset
d_csoset Set the database address of the current set owner
Syntax short d_csoset (short set, DB_ADDR *dba, RDM_DB hDb)
Parameters set [Input] The set containing the current owner record.
dba [Input] A pointer to the value to which to set the
database address.
Description This function sets the database address of the current owner of the
specified set to the value specified by dba. It also sets the current
member of the set to NULL. If the current owner is null
(NULL_DBA), the function sets the current owner and current
member of the set to NULL_DBA. Use this function with d_csoget
to save and restore the current owner of a set.
Return Values S_DELETED S_INVOWN

S_INVADDR S_INVSET
Currency curr_own[set] = *dba (NULL_DBA if dba==NULL);

Changes curr_mem[set] = NULL_DBA;
Locking None
Requirements
See Also d_crget, d_crset, d_csmget, d_csmset, d_csoget, d_rdcurr, d_wrcurr
Example
DB_ADDR dba;
...
/* Save current author on stack for later processing */
d_csoget(HAS_PUBLISHED, &dba, hDb);
...
/* Restore saved author as owner of has_published */
d_csoset(HAS_PUBLISHED, &dba, hDb);

d_csowrite
d_csowrite Write to a field in the current set owner
Syntax short d_csowrite (short set, long field, void *data, RDM_DB hDb)

field [Input] The field within the current owner to write.
specified field.
indicated field in the current owner of the specified set. If field
indicates a key field, d_csowrite automatically updates the key. If
field indicates a sort field of a set arranged in ascending or
descending order, the d_csowrite function automatically adjusts the
position of the record in the set to reflect the order indicated. If field
indicates an array field, d_csowrite writes the entire array (elements
of an array cannot be written individually).
Your application cannot use the d_csowrite function to modify a
The application cannot use the d_csowrite function to modify a
BLOB ID field. If the function is called for this type of data, it
returns S_BLOBUPD.
Return Values S_BLOBUPD S_INVFLD S_NOCO

S_DBPERM S_INVFLOAT S_NOSPACE
S_DELETED S_INVNULL S_NOTLOCKED
S_DUPLICATE S_INVSET S_TRNOTACT
S_INVDOUB S_ISCOMKEY

d_csowrite
Currency None
Changes
Locking Write lock on the current owner of set. If the field being updated is
Requirements also used in a sort by clause for a sorted set, the set must also be
write-locked.
See Also d_crwrite, d_csmwrite, d_recwrite
Example
/* Change author to "Wirth, N." */
d_csowrite(HAS_PUBLISHED, NAME, "Wirth, N.", hDb);

d_curkey
d_curkey Set the key position for keys in the current record
Syntax short d_curkey (RDM_DB hDb)
Description This function sets the current key stack position for every key in the
current record from the field values in the current record. Thus, a
subsequent d_keynext call for any of these key fields will return the
next key value (either the next instance of a duplicate, or the next
higher value).

S_DELETED
S_NOCR
Currency None
Changes
Locking None. However, since the record is not locked, the application
Requirements might get an S_DELETED error, indicating that the record
containing these keys (the current record) has been deleted by
another user.
Example
char sea_zip[6], cust_zip[6];
char id[4];
...
/* Locate some customers with same zip code as "SEA" */
if ( d_keyfind(CUST_ID, "SEA", hDb) == S_OKAY ) {
d_crread(ZIP_CODE, &sea_zip, hDb);
d_curkey(hDb);
while ( d_keynext(ZIP_CODE, hDb) == S_OKAY ) {
d_crread(ZIP_CODE, &cust_zip, hDb);
if ( strcmp(sea_zip, cust_zip) ! = 0)
break;
d_crread(CUST_ID, id, hDb);
printf("cust_id = %s\n", cust_id);
}
}

d_dbafree
d_dbafree Free the record instance lock on the specified record
Syntax short d_dbafree (DB_ADDR dba, RDM_DB hDb)
Parameters dba [Input] The database address of the record for

which to free the instance lock.
Description This function frees the record instance lock on a record with the
database address specified in the dba parameter. The d_dbafree
function returns S_TRFREE if the application attempts to free a
write lock within a transaction. The application receives the same
error if the application attempts to free a read lock within a
transaction, but has not enabled the freeing of read locks (see
d_rdlockmodes). The d_dbafree function returns an S_NOLOCK
error code if the application attempts to free a record that has no
record instance locks.
Return Values S_DELETED S_NOLOCK

S_INVADDR S_TRFREE
Currency None
Changes
Locking None
Requirements

d_crslock, d_csfree, d_cslock, d_dbalock, d_grplock,
Example
/* Free lock on previously saved and locked record */
...
d_crlock("r", hDb);
d_crget(&savedba, hDb);
...
d_dbafree(savedba, hDb);

d_dbalock
d_dbalock Request a record instance lock on a record
Syntax short d_dbalock (DB_ADDR dba, char *ltype, RDM_DB hDb)
Parameters dba [Input] The database address of the record to lock.

the record with the specified database address (dba parameter).
Return Values S_BADTYPE S_INVADDR S_NOTGRANTED

S_CONFLICT S_INVDB S_UNAVAIL
S_DBPERM S_INVNULL S_UPGDEN
S_DELETED S_INVREC S_STATIC
S_ILLDOWNG S_LOCKED
Currency None
Changes
Locking None
Requirements

d_crslock, d_csfree, d_cslock, d_dbafree, d_grplock,

d_dbalock
Example
DB_ADDR lockarry[MAXLOCKS]
...
.... /* Setup lockarray */
...
/* Step through array and lock records */
...
for (i = 0; i < max; i++)
d_dbalock(lockarray[i], "r", hDb);

d_decode_dba
d_decode_dba Decode a database address
Syntax short d_decode_dba (DB_ADDR dba, short *file, long *slot)
Parameters dba [Input] The database address to be decoded.

file [Output] A pointer to the retrieved file number.
slot [Output] A pointer to the retrieved slot number.
Description This function extracts the file number and slot number from the
specified database address. When finished processing, the function
writes the file number and the slot number for use by your
application. The Velocis User’s Guide explains the use of
d_decode_dba in Chapter 9.
Currency None
Changes
Locking None
Requirements
See Also d_encode_dba
Example
DB_ADDR dba; /* Database address of current record */
short file; /* File number */
long slot; /* Slot number */
...
/* Record to be displayed is current record */
d_crget(&dba, hDb);
d_decode_dba(dba, &file, &slot);
printf("id number: %d-%Id\n", file, slot);

d_delete
d_delete Delete the current record
Syntax short d_delete (RDM_DB hDb)
Description This function deletes the current record from the database. All keys
associated with the record are removed from their respective key
files. Then the record is marked as deleted and placed on the delete
chain for the file in which it resides. Before calling the d_delete
function, the application must have removed the record from all sets
of which it is an owner or a member.
Note: For a record that contains BLOB fields, this function

automatically deletes all BLOB contents.
Return Values S_DBOPEN S_HASMEM S_NOTLOCKED

S_DBPERM S_ISMEM S_TRNOTACT
S_DELETED S_NOCR S_UNCOMMITED
S_DELSYS S_NOSPACE
Currency curr_rec = NULL_DBA;

Changes
Locking Write lock on the current record or table. The function

Requirements automatically frees the record instance lock (if there is one). If
transactions are being used, the write lock is held until the end of
transactions. Otherwise, the lock is freed immediately.
See Also d_disdel
Example
/* Disconnect and delete abstract */
d_setom(ABSTRACT, HAS_PUBLISHED, hDb);
while ( d_findfm(ABSTRACT, hDb) == S_OKAY ) {
d_discon(ABSTRACT, hDb);
d_delete(hDb);
}

d_dict
d_dict Access the database dictionary
Syntax short d_dict (short item, short element, void *values, char objname[],
RDM_DB hDb)
Parameters item [Input] A flag indicating the particular item (file,

record, etc.) for which dictionary information is
desired. Possible values (defined in rdm.h) are:
DICT_FD Field table
DICT_FT File table
DICT_KT Compound key table
DICT_MT Member table
DICT_RT Record table
DICT_SIZES Sizes of all tables
DICT_SRT Sort table
DICT_ST Set table
element [Input] One single element of the table.
values [Output] A pointer to the dictionary information.
objname [Output] A pointer to the buffer where the name of
the set, field, or record entry will be copied. The
name buffer needs to be able to hold a name of at
least OBJNAMELEN bytes in length.
Description This function allows the application to access the database

dictionary. It is called by the c_ dictionary access API functions to
obtain dictionary information. Your application should use the c_
functions instead of d_dict, because they provide a higher level of
database dictionary access.
Return Values S_INVELEM

S_INVNULL
Currency None
Changes
Locking None
Requirements

d_discon
d_discon Disconnect the current member from a set
Syntax short d_discon (short nset, RDM_DB hDb)
Parameters nset [Input] The set type from which to disconnect the
current member.
Description This function disconnects the current member record from the
specified set. The disconnected record becomes the current record,
and the next member of the set becomes the new current member.
The d_discon function returns S_EOS when it has disconnected the
last set member (that is, the one at the end of the set).
Note: The d_discon function does not delete the record.
Return Values S_DBPERM S_INVSET S_NOTLOCKED

S_DELETED S_NOCM S_SETCLASH
S_EOS S_NOCO S_TRNOTACT
S_INVMEM S_NOSPACE S_UNCOMMITED
S_INVOWN S_NOTCON
Currency curr_rec = curr_mem[set];

Changes curr_mem[set] = next member of set;
Locking Write lock on the set.

Requirements
See Also d_connect, d_disdel
Example
while ( d_findfm(ABSTRACT, hDb) == S_OKAY ) {
d_discon(ABSTRACT, hDb);
d_delete(hDb);
}

d_disdel
d_disdel Disconnect and delete the current record
Syntax short d_disdel (RDM_DB hDb)
Description This function disconnects all members from the sets owned by the
current record. It also disconnects the current record from all sets of
which it is a member. Then d_disdel deletes the current record.
Write locks are required on all affected sets and the current record.
Return Values S_DBPERM S_NOTLOCKED

S_NOCR S_TRNOTACT
S_NOSPACE
Currency Currency is preserved except when the current record is a current

Changes owner or member. In those cases, the function sets the current
owner or member to NULL_DBA.
Locking Write lock on all sets to which the current record is connected (is a
Requirements member or owner), and write lock on the current record. The
function automatically frees the record instance lock when it deletes
the current record. If transactions are being used, the record
instance lock is held until the end of transactions. Otherwise, it is
freed immediately.
See Also d_crtype, d_csmset, d_delete, d_discon, d_findfm, d_ismember, d_

members, d_setor, d_setro
Example
while ( d_findfm(ABSTRACT, hDb) == S_OKAY )
d_disdel(hDb);

d_encode_dba
d_encode_dba Encode a database address
Syntax short d_encode_dba (short file, long slot, DB_ADDR *dba)
Parameters file [Input] The file number of the database address to

encode.
slot [Input] The slot number of the database address to
encode.
dba [Output] A pointer to the encoded database
address.
Description This function forms a database address from the specified file
number and slot number. The use of d_encode_dba is explained in
Chapter 9 of the Velocis User’s Guide.
Currency None
Changes
Locking None
Requirements
See Also d_decode_dba
Example
DB_ADDR dba; /* Database address */
short file; /* File number */
long slot; /* Slot number */
struct record rec; /* Record buffer */
...
/* Extract file number of slot number from id number string */
/* Form database address */

d_encode_dba(file, slot, &dba);
/* Set current record and read record contents */

d_crset(&dba, hDb);
d_recread(REC1, &rec, hDb);
/* Display record */
...

d_errinfo
d_errinfo Retrieve error information
Syntax short d_errinfo (char *errbuf, short length, RDM_SESS hSess)
Parameters errbuf [Output] A pointer to the error information.

length [Input] The length, in bytes, of the buffer associated
with errbuf.
hSess [Input] The session handle.
Description This function returns additional error information about a failed

Core API (d_) function. The d_errinfo function builds a text string
of the following format in the buffer pointed to by errbuf.
** description [errnum] (location)
In this string, description is a short English description of the error.
The errnum value represents the actual numeric return code (for
example, -4), as described in Chapter 19 of this manual. The location
value indicates the Velocis module and line number where the error
has been reported, in the following format:
modulename\filename:line_num - modulename\filename:line_num
The first part of the string indicates the module name, file name, and
line number of the entry API function that returned the error. The
second part indicates the internal location where the error actually
occurred.
Currency None
Changes
Locking None
Requirements
Example
char errbuf[80];
...
if ((stat = d_grplock(glock, numglock, hSess) != S_OKAY) {
d_errinfo(errbuf, sizeof(errbuf), hSess);
printf("d_grplock failed: %s\n", errbuf);
}

d_fillnew
d_fillnew Create and fill a new record
Syntax short d_fillnew (short nrec, void *recval, RDM_DB hDb)
Parameters nrec [Input] The record type to create.

recval [Input] A pointer to the contents of the new record.
Description This function creates a new record occurrence of the specified type
(nrec) in the database and fills it with the data pointed to by recval. If
the record contains key fields, the d_fillnew function automatically
inserts them in the correct key files. If any key field is unique and
the data in the field is not unique, the function returns
S_DUPLICATE and fails to create the record. If record type nrec
contains BLOB fields, each BLOB ID field must contain zero
(NULL_BLOB). BLOB contents may be written to the BLOB ID
fields following the creation of the record.
The d_fillnew function does not make any set connections or create
optional key fields. Your application can only create optional key
fields by calling d_keystore.
Return Values S_DBPERM S_INVFLOAT S_NOTLOCKED

S_DELSYS S_INVNULL S_TRNOTACT
S_DUPLICATE S_INVREC S_UNCOMMITED
S_INVDOUB S_NOSPACE
Currency curr_rec = database address of created record

Changes
Locking None. The function automatically write-locks the newly created

Requirements record. However, if another user has the record type locked (read
or write), the function is not able to create the record, and it
immediately returns with an S_NOTLOCKED error code.
See Also d_keyfind, d_keystore, d_makenew, d_setkey

d_fillnew
Example
struct info irec;
...
d_trbegin("ins", hSess);
/* Create new tech info record */
if(d_fillnew(INFO, &irec, hDb) == S_DUPLICATE)
printf("duplicate id_code: %s\n", irec.id_code);
else {
... /* Connect to appropriate sets */
}
d_trend(hSess);

d_findco
d_findco Find the owner of the current record
Syntax short d_findco (short nset, RDM_DB hDb)
Parameters nset [Input] The set type in which to search.

Description This function finds the owner of the current record in the specified
set (nset). The function sets the current owner of the set to the
record found. The function sets the current member of the set from
the current record. The current record is then set to the new current
owner.
Note: If the application needs to determine whether the current

record is connected to the specified set, it should first call
d_ismember. Then, if the record is connected, the application calls
d_findco to retrieve the owner. This call sequence prevents the
return of an S_NOTCON error code.
Return Values S_NOTCON
Currency curr_own[nset] = owner of current record through set;

Changes curr_mem[nset] = curr_rec;
curr_rec = owner of current record through set;
Locking If dirty reads are not enabled, the set must be locked.
Requirements
See Also d_findfm, d_findlm, d_findnm, d_findpm
Example
/* Print key words associated with tech. info */
while ( d_findnm(INFO_TO_KEY, hDb) == S_OKAY ) {
d_findco(KEY_TO_INFO, hDb);
d_crread(WORD, key, hDb);
printf("%s\n", key);
}

d_findfm
d_findfm Find the first member of a set
Syntax short d_findfm (short nset, RDM_DB hDb)

Description This function finds the first member of the specified set (nset). The
d_findfm function sets the current member of the set and the
current record to the found record. The function returns S_EOS if it
finds no members for the set.

S_EOS S_NOTLOCKED
S_INVSET
Currency curr_mem[nset] = first member; (NULL_DBA when S_EOS)

Changes curr_rec = first member; (unchanged when S_EOS)
Locking If dirty reads are not enabled, the specified set must be locked.
Requirements
See Also d_findco, d_findlm, d_findnm, d_findpm
Example
char name[32]; /* Author name */
...
/* Print author list in ascending order */
}

d_findlm
d_findlm Find the last member of a set
Syntax short d_findlm (short nset, RDM_DB hDb)

Description This function finds the last member of the specified set (nset). The
d_findlm function sets the current member of the set and the
finds no members for the set. See the description of d_findpm.

S_EOS S_NOTLOCKED
S_INVSET
Currency curr_mem[nset] = last member; (NULL_DBA when S_EOS)

Changes curr_rec = last member; (unchanged when S_EOS)
Requirements
See Also d_findco, d_findfm, d_findnm, d_findpm
Example
...
/* Print author list in descending order */
for ( stat = d_findlm(AUTHOR_LIST, hDb); stat == S_OKAY;
stat = d_findpm(AUTHOR_LIST, hDb) ) {
}

d_findnm
d_findnm Find the next member of a set
Syntax short d_findnm (short nset, RDM_DB hDb)

Description This function finds the next member of the specified set (nset). The
d_findnm function sets the current member of the set and the
does not find a next member. If there is no current member of the
specified set, d_findnm behaves like d_findfm.

S_EOS S_NOTLOCKED
S_INVMEM S_SETCLASH
S_INVSET
Currency curr_mem[nset] = next member; (NULL_DBA when S_EOS)

Changes curr_rec = next member; (unchanged when S_EOS)
Requirements
See Also d_findco, d_findfm, d_findlm, d_findpm
Example
...
/* Print author list in ascending order */
}

d_findpm
d_findpm Find the previous member of a set
Syntax short d_findpm (short nset, RDM_DB hDb)

Description This function finds the previous member of the specified set (nset).
The d_findpm function sets the current member of the set and the
does not find a previous member. If there is no current member of a
set, d_findpm behaves like d_findlm.

S_EOS S_NOTLOCKED
S_INVMEM S_SETCLASH
S_INVSET
Currency curr_mem[nset] = previous member; (NULL_DBA when S_EOS)

Changes curr_rec = previous member; (unchanged when S_EOS)
Requirements
See Also d_findco, d_findfm, d_findlm, d_findnm
Example
...
/* Print author list in descending order */
for ( stat = d_findlm(AUTHOR_LIST, hDb); stat == S_OKAY;
stat = d_findpm(AUTHOR_LIST, hDb) ) {
}

d_fldcmp
d_fldcmp Compare two values according to the field’s compare rules
Syntax short d_fldcmp (long field_id, const void *value1, const void *value2,
short *result, RDM_DB hDb)
Parameters field_id [Input] The field type.

value1 [Input] A pointer to the first value to compare.
value2 [Input] A pointer to the second value to compare.
result [Output] A pointer to the comparison result. The
result can be +1 (if value1 is greater than value2), 0
(if value1 is equal to value2), or -1 (if value1 is less
than value2).
Description This function compares two values stored in the field identified by
field_id. The result of the comparison returned is identical to that
obtained by the runtime while performing operations such as
building index trees, performing SQL queries where the order is
specified, etc. This function aids custom sorting within client
applications and extension modules, while remaining consistent
with sorting performed by the server runtime.
If field_id identifies a character or Unicode field, Velocis compares
the values according to the Locale or country table settings, if any.

S_OKAY
Example
char str1[] = "Warren, Anita";
char str2[] = "warren, anita";
short cmpres;
/* compare two values for field NAME */

if (d_fldcmp(NAME, str1, str2, &cmpres, hDb) != S_OKAY)
goto invalid_id;
/* cmpres = -1 if no locale is set in VELOCIS.INI,

cmpres = 1 if locale is set */

d_getDD
d_getDD Get the RPC parameter data descriptor for a field or record type
Syntax short d_getDD (short itemType, long itemId, short *count,

size_t *length, PL_ITEM **ppItemDesc, RDM_DB hDb)
Parameters itemType [Input] An indicator of the item type to return. To

return a record type, specify DICT_RT. To return a
data field, specify DICT_FD.
itemId [Input] The identifier for the record or field
constant.
count [Output] A pointer to the number of fields in the
item.
length [Output] A pointer to the size, in bytes, of the item.
ppItemDesc [Output] A pointer to the item descriptor pointer
retrieved by the function.
hDb [Input] The handle of the database containing the
specified item.
Description This function retrieves an item descriptor in an RPC parameter list

for a data field or record type defined in a database. To get the item
descriptor for a record type, set the item identifier to the constant
associated with the record type you are requesting.
The function returns the number of fields, the size, and a pointer to
the parameter descriptor, for the item you want to retrieve. If the
item is a record type or a structure field, the function will return the
number of fields declared in it in the value pointed to by count;
otherwise, the value will be 1.
Return Values S_INVELEM

S_INVNULL
S_OKAY
Currency None
Changes
Locking None
Requirements

d_getDD
See Also pl_putStruct

PL_ITEM (structure)
Example
/* ===================================================================
Envelope function for d_recread
*/
short REXTERNAL Ed_recread(
PL_DATADESC *inParms,
PL_DATADESC *outParms)
{
short rc;
short fcnRet;
size_t length;
short count;
short rec;
RDM_DB hDb;
PL_ITEM *pSI;
char *data;
char *funcName = "d_recread";
rc = pl_getInParms(inParms, funcName, &rec, &hDb, NULL);

if ( rc != S_OKAY )
return rc;
rc = d_getDD(DICT_RT, (long) rec, &count, &length, &pSI, hDb);

if ( rc != S_OKAY )
return rc;
data = rm_getMemory(length, 0);

fcnRet = d_recread(rec, data, hDb);
rc = pl_putStruct(outParms, pSI, PL_FLAG_FREE, data, 0);

if (rc != S_OKAY)
return ModRPCError(funcName, 2, rc);
return fcnRet;
}
(continued)

d_getDD
(continued)
/* ===================================================================
Envelope function for d_keyread
*/
short REXTERNAL Ed_keyread(
{
short rc;
short fcnRet;
size_t length;
short count;
long field;
RDM_DB hDb;
PL_ITEM *pSI;
char *key_val;
char *funcName = "d_keyread";
rc = pl_getInParms(inParms, funcName, &field, &hDb, NULL);

if ( rc != S_OKAY )
return rc;
rc = d_getDD(DICT_FD, field, &count, &length, &pSI, hDb);

if ( rc != S_OKAY )
return rc;
key_val = rm_getMemory(length, 0);

fcnRet = d_keyread(field, key_val, hDb);
if (count == 1)
rc = pl_put(outParms, pSI->type, PL_FLAG_FREE, key_val, length);
else
rc = pl_putStruct(outParms, pSI, PL_FLAG_FREE, key_val, 0);
if (rc != S_OKAY)
return fcnRet;
}

d_grplock
d_grplock Request a group lock
Syntax short d_grplock (GROUPLOCK *glock, unsigned short num,

RDM_SESS hSess)
Parameters glock [Input] A pointer to a GROUPLOCK structure that

holds group lock requests.
num [Input] The number of elements in the structure
indicated by glock.
Description This function allows the application to make multiple lock requests
with one call. Any number and kind of locks can be requested. The
application can use this function to minimize, or even eliminate,
deadlock potential. If d_grplock cannot grant any of the lock
requests, it grants none of them.
You must correctly establish the currency (current record, owner,
and members of a set) for any lock request that depends on
currency. An existing lock can be upgraded or downgraded,
although a write lock cannot be downgraded within a transaction.
Note: Since a lock can be requested against an item that the

application has already locked, duplicate requests in the
GROUPLOCK structure are not of great concern.

Currency None
Changes
Locking None
Requirements

d_grplock

d_crslock, d_csfree, d_cslock, d_dbafree, d_dbalock,
GROUPLOCK (structure)
Example
GROUPLOCK glock[3];
...
/* Lock the first 3 members of set */
d_setor(SET1, hDb);
stat = d_findfm(SET1, hDb);
for (i = 0; stat == S_OKAY && i < 3; i++) {
glock[i].ftype = DBALOCK;
glock[i].lmode = ’r’;
d_crget(&dba, hDb);
glock[i].dba = dba;
glock[i].hdb = hDb;
stat = d_findnm(SET1, hDb);
}
d_grplock(glock, 3, hSess);

d_iclose
d_iclose Close a database incrementally
Syntax short d_iclose (RDM_DB hDb)
Parameters hDb [Input] The handle of database to close.
Description This function closes one database, selected by its database handle
(hDb). If a transaction is active when the application calls d_iclose,
the transaction is aborted. If only one database has been opened in
the same session as hDb, this function behaves like d_close.
Return Values S_DBOPEN S_INVSESS

S_INVDB S_UNAVAIL
Currency None
Changes
Locking None
Requirements
See Also d_close, d_iopen, d_open
Example
d_open("sales", "s", hSess, &hSales);
d_iopen("invntory", "s", hSess, &hInv);
...
/* Eliminate sales and add payroll */
d_iclose(hSales);
d_iopen("payroll", "s", hSess, &hPay);
/* Close all databases */
d_close(hSess);

d_iopen
d_iopen Open a database incrementally
Syntax short d_iopen (const char *dbname, const char *openmode,

RDM_SESS hSess, RDM_DB *hDb)
Parameters dbname [Input] The name of the database to open.

openmode [Input] A string indicating the mode in which to
open the database. See d_open for a list of possible
open modes.
hDb [Output] A pointer to the opened database handle.
Description This function opens the specified database (dbname) with the type of
database access indicated by the openmode parameter. Your
application calls this function to open additional databases after
opening the first database in a call to d_open. If no databases are
already open within session hSess, this function works like d_open.
Return Values S_BADTYPE S_DBUNAVAIL S_INVNULL

S_CATERR S_EXOPENED S_OPENED
S_DBNOTREG S_INCMODE S_UNAVAIL
Currency curr_rec = system record; (NULL_DBA if no system record)

Changes curr_own[system owned sets] = system record;
curr_own[all other sets] = NULL_DBA;
curr_mem[of all sets] = NULL_DBA;
Locking None
Requirements
See Also d_close, d_iclose, d_open
Example
d_open("sales", "s", hSess, &hSales);
d_iopen("invntory", "s", hSess, &hInv);
...
/* Eliminate sales and add payroll */
d_iclose(hSales);
d_iopen("payroll", "s", hSess, &hPay);
/* Close all databases */
d_close(hSess);

d_ismember
d_ismember Determine whether the current record is a member of a set
Syntax short d_ismember (short set, RDM_DB hDb)
Parameters set [Input] The set type to check.

Description This function determines whether the current record is connected as

a member of the specified set. If it is, the function returns S_OKAY.
If the record is not a member of the set, the function returns S_EOS.
Note: If the current record is not of a legal member record type for
the indicated set, d_ismember calls dberr with the S_INVMEM
error code.

S_EOS S_NOCR
S_INVMEM S_OKAY
Currency None
Changes
Locking The d_ismember function does not require locks. However, it

Requirements might read old data if the specified set is not locked.
See Also d_isowner
Example
/* Annual corporate awards */
while ( d_keynext(EMPLOYEE_ID, hDb) == S_OKAY ) {
if ( d_ismember(DIVISION_MANAGER, hDb) == S_OKAY ) {
/* Award large dividend */
...
}
else if ( d_ismember(DEPT_MANAGER, hDb) == S_OKAY ) {
/* Award raise */
...
}
else {
/* Give commendation */
...
}
}

d_isowner
d_isowner Determine whether the current record is the owner of a set
Syntax short d_isowner (short set, RDM_DB hDb)
Parameters set [Input] The set type to check.

Description This function determines whether the current record has any
members connected to it through the specified set. If the function
finds that the record is an owner of one or more members, the
function returns S_OKAY. If the record is an owner of an empty set,
the d_isowner function returns S_EOS.
Note: If the current record is not of a legal owner record type for the
specified set, d_isowner calls the application error handler function,
specified by d_set_dberr, with the S_INVOWN error code.

S_EOS S_NOCR
S_INVOWN S_OKAY
Currency None
Changes
Locking This function does not require locks. However, it might read old
Requirements data if the specified set is not locked.
See Also d_ismember
Example
if ( d_isowner(ALTERNATE_SET_1, hDb) == S_OKAY ) {
/* Process set 1 records */
...
}
else if ( d_isowner(ALTERNATE_SET_2, hDb) == S_OKAY ) {
...
}
else if ( d_isowner(ALTERNATE_SET_3, hDb) == S_OKAY ) {
...
}

d_keydel
d_keydel Delete an optional key
Syntax short d_keydel (long field, RDM_DB hDb)
Parameters field [Input] The optional key field type.

Description This function deletes the key entry associated with the specified
optional key field in the current record.
Return Values S_BADFIELD S_INVFLD S_NOTFOUND

S_DBOPEN S_INVNULL S_NOTLOCKED
S_DBPERM S_NOCR S_NOTOPTKEY
S_DELETED S_NOSPACE S_TRNOTACT
Currency None
Changes

Requirements
See Also d_keyexist, d_keystore
Example
if ( d_keyfind(EMP_ID, "8505", 4, hDb) ) == S_OKAY ) {
/* Upgrade employee to manager */
d_keydel(EMP_ID, hDb);
d_keystore(MGR_ID, hDb);
}

d_keydir
d_keydir Set the search direction for a key
Syntax short d_keydir (long field, short dir, RDM_DB hDb)
Parameters field [Input] The key field for which to set search
direction.
dir [Input] A flag indicating the direction of the search.
To search forward, specify 0. To search backward,
specify 1.
Description This function sets the direction for all subsequent key searching and
navigation for the specified key. If the dir parameter is zero, key
search and navigation functions behave normally. However, if the
dir parameter is 1, the normal behavior of the search and navigation
functions changes.
The Navigation Function Changes section below describes the
changes that take place in the navigation functions when the search
direction is 1. Note especially the change in behavior of d_keyfind
and d_pkeyfind. The primary purpose of d_keydir is to make
d_keyfind and d_pkeyfind navigate to the last of a group of
duplicate keys, to make it easy to scan a key in reverse order.

d_keydir
Navigation d_keyfind Positions on the last of a group of duplicate keys

Function matching the given application key. If the key is
Changes not found, the function positions so that
d_keynext (navigating backward) will position to
the key preceding the closest match to the
specified one.
d_keyfrst Acts as d_keylast.
d_keylast Acts as d_keyfrst.
d_keynext Acts as d_keyprev.
d_keyprev Acts as d_keynext.
d_pkeyfind Positions on the last of a group of duplicate keys
matching the partial key for the application (as
limited by the parameters nFields and
partialStrLen). If the function does not find the
partial key, it positions so that d_keynext
(navigating backward) will position to the key
preceding the closest match to the specified one.
d_pkeynext Acts as d_pkeyprev.
d_pkeyprev Acts as d_pkeynext.

S_NOTKEY
Currency None
Changes
Locking None
Requirements
See Also d_keyfind, d_keyfrst, d_keylast, d_keynext, d_keyprev,

d_pkeyfind, d_pkeynext, d_pkeyprev
Example
/* Scan a key find in reverse order */
d_keydir(NAME, 1, hDb);
for (rv = d_keyfrst(NAME, hDb); rv == S_OKAY;
rv = d_keynext (NAME, hDb)) {
... /* Here if another key has been found */
}

d_keyexist
d_keyexist Check for the existence of an optional key
Syntax short d_keyexist (long field, RDM_DB hDb)
Parameters field [Input] The optional key field type.

Description This function determines whether the key for an optional key field
in the current record is stored. The d_keyexist function returns
S_OKAY if the key is stored. If the key is not stored, the function
returns S_NOTFOUND.
Return Values S_BADFIELD S_INVNULL S_NOTOPTKEY

S_DBOPEN S_NOCR S_OKAY
Currency None
Changes
Locking If dirty reads are not enabled, the current record must be locked.
Requirements
See Also d_keydel, d_keystore
Example
if ( d_keyexist(EMP_ID, hDb) == S_NOTFOUND ) {
/* Store employee id */
d_keystore(EMP_ID, hDb);
}

d_keyfind
d_keyfind Find a record by its key
Syntax short d_keyfind (long field, const void *fldval, RDM_DB hDb)
Parameters field [Input] The key field type on which to search.

fldval [Input] A pointer to the value to find.
Description This function finds a record occurrence based on the specified key
(fldval parameter). Regardless of whether the function finds the key,
the key stack remains positioned so that a subsequent d_keynext (or
d_keyprev) call will retrieve the record with the next higher (or
lower) key value. If the value of fldval is NULL, the d_keyfind
function positions the key stack at the beginning so that d_keynext
will return the first key on file.
Return Values S_INVFLD S_NOTFOUND S_NOTKEY
Currency curr_rec = found record; (or NULL_DBA if S_NOTFOUND)

Changes
Locking None. However, if the record is not locked, your application might
Requirements receive an S_DELETED error code when it later attempts to read the
record found by d_keyfind. Also, another application might change
the record so that its key field no longer matches the value specified
to d_keyfind.
See Also d_keyfrst, d_keylast, d_keynext, d_keyprev
Example
char id[16];
...
/* Display all database related info records
(those for which id begins with "db") */
d_keyfind(ID_CODE, "db", hDb); /* Position to start of "db"s */
do {
d_keyread(id, hDb);
if ( strncmp(id, "db", 2) )
break; /* No more "db"s */
... /* Print info records contents */
} while ( d_keynext(ID_CODE, hDb) == S_OKAY);

d_keyfrst
d_keyfrst Find the record associated with the first occurrence of a key
Syntax short d_keyfrst (long field, RDM_DB hDb)

Description This function finds the record occurrence associated with the first
occurrence of the specified key (field parameter).

S_NOTFOUND
S_NOTKEY
Currency curr_rec = record with first key; (or NULL_DBA if S_NOTFOUND)

Changes
Requirements receive S_DELETED when it later attempts to read the record found
by d_keyfrst. This code indicates that another application deleted
the record.
See Also d_keyfind, d_keylast, d_keynext, d_keyprev
Example
/* Display all info records in id_code order */
for ( stat = d_keyfrst(ID_CODE, hDb); stat == S_OKAY;
stat = d_keynext(ID_CODE, hDb) ) {
... /* Print info record contents */
}

d_keylast
d_keylast Find the record associated with the last occurrence of a key
Syntax short d_keylast (long field, RDM_DB hDb)
Parameters field [Input] The key field type for which to search.
Description This function finds the record occurrence associated with the last
occurrence of the specified key (field parameter).

S_NOTFOUND
S_NOTKEY
Currency curr_rec = record with last key; (or NULL_DBA if S_NOTFOUND)

Changes
by d_keylast. This code indicates that another application deleted
the record.
See Also d_keyfind, d_keyfrst, d_keynext, d_keyprev
Example
/* Display all info records in reverse id_code order */
for ( stat = d_keylast(ID_CODE, hDb); stat == S_OKAY;
stat = d_keyprev(ID_CODE, hDb) ) {
}

d_keynext
d_keynext Find the record associated with the next key
Syntax short d_keynext (long field, RDM_DB hDb)
Parameters field [Input] The key field type to find.

Description This function finds the record occurrence associated with the next
occurrence of the specified key (field parameter). The d_keynext
function returns S_NOTFOUND if it finds no more keys. Because
Velocis keeps track of the relative position of each key field in a key
stack, the application can intersperse d_keynext calls for multiple
key fields.
Note: The first call to d_keynext (or the first call after a return of
S_NOTFOUND) finds the first key on file.

S_NOTFOUND
S_NOTKEY
Currency curr_rec = record with next key; (or NULL_DBA if S_NOTFOUND)

Changes
by d_keynext. This code indicates that another application has
deleted the record.
See Also d_keyfind, d_keyfrst, d_keylast, d_keyprev
Example
}

d_keyprev
d_keyprev Find the record associated with the previous key
Syntax short d_keyprev (long field, RDM_DB hDb)
Parameters field [Input] The key field type to find.

Description This function finds the record occurrence associated with the
previous occurrence of the specified key (field parameter). The
d_keyprev function returns S_NOTFOUND if it finds no more keys.
Because Velocis keeps track of the relative position of each key field
in a key stack, the application can intersperse d_keyprev calls for
multiple key fields.
Note: The first call to d_keyprev (or the first call after a return of
S_NOTFOUND) finds the last key on file.

S_NOTFOUND
S_NOTKEY
Currency curr_rec = record with previous key; (or NULL_DBA if

Changes S_NOTFOUND)
record found by d_keyprev. This code indicates that another
application has deleted the record.
See Also d_keyfind, d_keyfrst, d_keylast, d_keynext
Example
/* Display all info records in reverse id_code order */
while ( d_keyprev(ID_CODE, hDb) == S_OKAY ) {
}

d_keyrdstate
d_keyrdstate Read the key state information
Syntax short d_keyrdstate (long field, void *buf, RDM_DB hDb)
Parameters field [Input] The key field type for which to read the
state.
buf [Output] A pointer to the key state information.
Description This function copies state information for the position of the
specified key into the buffer indicated by buf. Your application uses
the d_keyrdstate function with d_keyszstate and d_keywrstate to
save and restore the current position of a key in a key file.

S_INVNULL
S_NOTKEY
Currency None
Changes
Locking None
Requirements
See Also d_keyszstate, d_keywrstate
Example
void *buf; /* Buffer to hold state information */
unsigned short bufLen; /* Size of buffer needed to hold this key’s
state information */
...
d_keyszstate(ID_CODE, &bufLen, hDb); /* Get required buffer size */
buf = rm_getMemory(bufLen, 0); /* Allocate a buffer */
d_keyrdstate(ID_CODE, buf, hDb); /* Save key state in buffer */
... /* Do some other processing */
d_keywrstate(ID_CODE, buf, hDb); /* Restore key state */

d_keyread
d_keyread Read the value of the last key found
Syntax short d_keyread (long field, void *key_val, RDM_DB hDb)
Parameters field [Input] The type of key field to read.

key_val [Output] A pointer to the value of the last scanned
key.
Description This function reads the value of the last key found by a key retrieval
function. The application can use the d_keyread function to check
the value of a key without having to read its associated record.
Thus, a list of key values can be produced without reading the data
file by using a combination of the d_keyfrst, d_keynext, and
d_keyread functions.
Return Values S_DELETED S_KEYSEQ

S_INVFLD S_NOTKEY
S_INVNULL
Currency None
Changes
Locking None. However, if the record is not locked, the application might
Requirements receive the S_DELETED error code, indicating that another
application deleted the record. Another application might also
change the key fields of the current record.
See Also d_keyfind, d_keyfrst, d_keylast, d_keynext, d_keyprev
Example
char id[16]:
...
d_keyfind(ID_CODE, "db", hDb); /* Position to start of "db"s */
while ( d_keynext(ID_CODE, hDb) == S_OKAY ) {
d_keyread(ID_CODE, id, hDb);
if ( strncmp(id, "db", 2) ) ! = 0)
break; /* No more "db"s */
}

d_keystore
d_keystore Store an optional key
Syntax short d_keystore (long field, RDM_DB hDb)
Parameters field [Input] The optional key field type for which to
store a value.
Description This function creates a key entry from the data contained in the
current record for the specified optional key (field parameter). Your
application can only call the d_keystore function after the record is
created. Once the application stores an optional key, the key is
automatically modified any time its field contents are modified (for
example, by d_recwrite).
Return Values S_BADFIELD S_INVFLD S_NOTLOCKED

S_DBOPEN S_INVNULL S_NOTOPKEY
S_DBPERM S_NOCR S_TRNOTACT
S_DELETED S_NOSPACE
Currency None
Changes

Requirements
See Also d_keydel, d_keyexist
Example
/* Batch load key for daily stock tracking record */
for ( stat = d_recfrst(STOCK, hDb); stat == S_OKAY;
stat = d_recnext(STOCK, hDb) )
d_keystore(ID_CODE, hDb);

d_keyszstate
d_keyszstate Retrieve the size of the key state buffer
Syntax short d_keyszstate (long field, unsigned short *pSize, RDM_DB hDb)
Parameters field [Input] The key field type for which to get the state
size.
pSize [Output] A pointer to the size, in bytes, of the buffer
to store key state information.
Description This function retrieves the size of a buffer to store state information
for the specified key field, regardless of the key state. The retrieved
size does not change during execution of the application. Your
application uses the d_keyszstate function with d_keyrdstate and
d_keywrstate to save and restore the state of a key file.
Return Values S_INVFLD S_NOTKEY S_INVNULL
Currency None
Changes
Locking None
Requirements
See Also d_keyrdstate, d_keywrstate
Example
unsigned short bufLen; /* Size of buffer needed to hold
this key’s state information */
...

d_keywrstate
d_keywrstate Restore the key state information
Syntax short d_keywrstate (long field, void *buf, RDM_DB hDb)
Parameters field [Input] The key field type for which to restore the
state.
buf [Input] A pointer to a buffer that contains key state
information, as obtained using the d_keyrdstate
function.
Description This function restores the key state information from the buffer
indicated by buf. Your application uses the d_keywrstate function
with d_keyszstate and d_keyrdstate to save and restore the state of
the key file.
Caution: Your application must not call d_keywrstate unless it has

first called d_keyrdstate to obtain the value of buf. Severe damage
to the database could result if the function writes the contents of an
incorrect buffer into the state of a key.
Return Values S_INVFLD S_INVNULL S_NOTKEY
Currency The position of the current key.

Changes
Locking None
Requirements
See Also d_keyrdstate, d_keyszstate
Example
unsigned short bufLen; /* Size of buffer needed to hold
this key’s state information */
...

d_makenew
d_makenew Create a new (empty) record
Syntax short d_makenew (short nrec, RDM_DB hDb)
Parameters nrec [Input] The record type to create.

Description This function creates a new record occurrence of the specified type
(nrec). If the record contains key fields, the application must first
call d_setkey to set up those field’s values. The d_makenew
function automatically stores the key fields in the key file and in the
record. If any key field is unique and the data in the field is not
unique, d_makenew returns S_DUPLICATE and fails to create the
record.
Your application cannot call d_makenew to create records that
contain compound keys. For these, the application must use
d_fillnew.
Return Values S_COMKEY S_INVFLOAT S_NOTLOCKED

S_DBPERM S_INVREC S_TRNOTACT
S_DUPLICATE S_KEYREQD S_UNCOMMITED
S_INVDOUB S_NOSPACE
Currency curr_rec = database address of new record;

Changes
Locking Velocis automatically applies a record instance write lock to the

Requirements newly created record. If another application has the record type
locked (read or write), d_makenew cannot create the record, and it
immediately returns S_NOTLOCKED as an error code.
See Also d_fillnew, d_keystore, d_setkey
Example
/* Create intersection record */
d_makenew(INTERSECT, hDb);
d_connect(KEY_TO_INFO, hDb);
d_connect(INFO_TO_KEY, hDb);

d_members
d_members Retrieve a count of the current set members
Syntax short d_members (short set, long *tot, RDM_DB hDb)
Parameters set [Input] The current set type.

tot [Output] A pointer to the total member count.
Description This function retrieves a member count for the specified current set.

S_INVNULL S_NOCO
S_INVOWN S_NOTLOCKED
Currency None
Changes
Locking If dirty reads are not enabled, the set must be locked.
Requirements
See Also d_isowner
Example
long num; /* Number of pubs. */
...
/* Print list of authors with total number of
associated publications in database */
d_setor(HAS_PUBLISHED, hDb);
d_members(HAS_PUBLISHED, &num, hDb);
printf("author %s has %ld publications on file\n", name, num);
}

d_nullset
d_nullset Set the SQL null value flag for a data field in the current record
Syntax short d_nullset (long field, void *bitmap, short isnull, RDM_DB hDb)
Parameters field [Input] The identifier of the field for which to set
the null value flag.
bitmap [Input] A pointer to the sysnulls_ field value for the
current record. If you have not previously read this
value, specify NULL; the function will
automatically read in the current value.
isnull [Input] The null flag. Specify TRUE (1) to set the
field to null or FALSE (0) to set the field to non-null.
Description This function is used to set the SQL null indicator bit associated with
the specified field in the sysnulls_ field of the current record.
If you have previously read the current record (e.g., d_recread) or
the sysnulls_ field (e.g., d_crread), you can pass a pointer to the
sysnulls_ value by using the bitmap parameter. If bitmap is NULL,
the value of sysnulls_ will automatically be read from the current
record by d_nullset.
An SQL null value is controlled by the bit in the sysnulls_ data field
corresponding to the data field specified by field. When the field is
null, the bit will be on (1), and the value of field will be set to either
the minimum possible value (for scalar numeric types) or all zeros
(for all other types). When the field is not null, the bit will be off (0).
A TRUE (1 or nonzero) value for the isnull parameter will set field to
null. A FALSE (0) value for isnull will set field to non-null.
For more information about how SQL null values are implemented
in the Core DDL associated with an SQL database, see Chapter 6 of
the Velocis User’s Guide.

S_INVFLD S_NOSYSNULLS
Currency None
Changes

d_nullset

Requirements
See Also d_nulltest
Example
...
/* scan through all salespersons */
for ( stat = d_recfrst(SALESPERSON, hSales);
stat == S_OKAY; stat = d_recnext(hSales) ) {
d_crget(&curdba, hSales);
if ( !DB_ADDR_EQ(curdba, vpdba) ) {
d_nulltest(SALESPERSON_MGR_ID, NULL, &is_null, hSales);
if ( is_null ) {
/* connect to manages */
d_connect(MANAGES, hSales);
/* turn off null indicator bit */

d_nullset(SALESPERSON_MGR_ID, NULL, 0, hSales);
/* increment reference count */
++vp.sysrefs_[0];
}
}
}

d_nulltest
d_nulltest Read the SQL null value flag for a data field in the current record
Syntax short d_nulltest (long field, void *bitmap, short *pIsnull,

RDM_DB hDb)
Parameters field [Input] The identifier of the field for which to read
the null value flag.
bitmap [Input] A pointer to the sysnulls_ field value for the
current record. If you have not previously read this
value, specify NULL; the function will
automatically read in the current value.
pIsnull [Output] A pointer to a short variable that will
contain TRUE (1) if field is null or FALSE (0) if field
is not null.
Description This function is used to read from the sysnulls_ field of the current
record the SQL null indicator bit associated with the specified field.
If you have previously read the current record (e.g., d_recread) or
the sysnulls_ field (e.g., d_crread), you can pass a pointer to the
sysnulls_ value using the bitmap parameter. If bitmap is NULL, the
current value of sysnulls_ will automatically be read from the
current record by d_nullset.
An SQL null value is controlled by the bit in the sysnulls_ data field
corresponding to the data field specified by field. When the field is
null, the bit will be on (1), and the value of field will be set to either
the minimum possible value (for scalar numeric types) or all zeros
(for all other types). When the field is not null, the bit will be off (0).
The current null indicator bit value (1 or 0) is returned in the short
variable pointed to by pIsnull.
For more information about how SQL null values are implemented
in the Core DDL associated with an SQL database, see Chapter 6 of

S_INVFLD S_NOSYSNULLS

d_nulltest
Currency None
Changes
Locking If dirty reads are not enabled, the current record requires a lock.
Requirements
See Also d_nullset
Example
...
/* scan through all salespersons */
for ( stat = d_recfrst(SALESPERSON, hSales);
stat == S_OKAY; stat = d_recnext(hSales) ) {
d_crget(&curdba, hSales);
if ( !DB_ADDR_EQ(curdba, vpdba) ) {
d_nulltest(SALESPERSON_MGR_ID, NULL, &is_null, hSales);
if ( is_null ) {
/* connect to manages */
d_connect(MANAGES, hSales);
/* turn off null indicator bit */

d_nullset(SALESPERSON_MGR_ID, NULL, 0, hSales);
/* increment reference count */

++vp.sysrefs_[0];
}
}
}

d_open
d_open Open a database
Syntax short d_open (const char *dbname, const char *openmode,

RDM_SESS hSess, RDM_DB *hDb)
Parameters dbname [Input] The name of the database to open.

openmode [Input] A string containing the open mode for the
database. Possible values are:
"r" Read-only mode. Locking is required.
Transactions are illegal.
"s" Normal shared (multi-user) mode.
Transactions and write locks are
required to modify the database.
"t" Temporary open mode. The database
only exists while it is open. Locks are
ignored and transactions are ignored,
for this database only.
"x" Normal exclusive (single-user) mode.
Locks are optional, but transactions are
required to modify the database.
"xn" Exclusive mode with no transactions.
Locks are optional and transactions are
ignored for this database only.
hDb [Output] A pointer to the handle for the new
database. The application passes this handle in all
subsequent function calls that reference the
database.
Description This function opens the database specified by dbname. To open

multiple databases, the application should call d_iopen. The only
difference between d_open and d_iopen is that d_open closes all
previously opened databases in the session hSess before it opens the
requested database. The d_iopen function does not close the
databases.
Note: If you use SQL databases, calling the d_open function can
inadvertently end all active transactions in those databases, because
the function closes all databases before opening a database. To
avoid this problem, use the d_iopen function.

d_open
Return Values S_BADTYPE S_INVNULL

S_DBNOTREG S_OPENED
S_EXOPENED S_UNAVAIL
S_INCMODE
Currency curr_recxn = system record (NULL_DBA, if no system record);

Changes curr_own[system-owned sets] = system record;
curr_own[all other sets] = NULL_DBA;
curr_mem[of all sets] = NULL_DBA;
Locking None
Requirements
See Also d_close, d_iclose, d_iopen
Example
stat = d_open("tims", "x", srv, &hDb);
if (stat ==S_UNAVAIL) {
user_message("database unavailable");
terminate();
}

d_pkeyfind
d_pkeyfind Find a record by its partial key
Syntax short d_pkeyfind (long field, short nFields,

unsigned short partialStrLen, const void *fldval,
RDM_DB hDb)

nFields [Input] The number of fields. If this parameter is
zero, the function searches all fields. If this
parameter is a non-zero value, the function uses
only the number of fields indicated. This parameter
applies only to compound keys.
partialStrLen [Input] The partial string length, in bytes. If this
parameter is a non-zero value, the function uses
only this many characters of the last field being
considered (depending on nFields above).
fldval [Input] A pointer to the data to be searched.
Description This function finds a record occurrence based on the specified key
(field parameter). The area to search is restricted to the specified
fields and characters of the last considered value of the key (that is,
the last field of the key, unless restricted using nFields). The
d_pkeyfind function with nFields equal to zero and partialStrLen
equal to zero is equivalent to d_keyfind.
Regardless of whether d_pkeyfind finds the record it seeks, the key
stack remains positioned so that a subsequent call to d_keynext (or
d_keyprev, d_pkeynext, or d_pkeyprev) retrieves the record with
the next higher (or lower) key value. If field is set to NULL, the
d_pkeyfind function positions the key stack at the beginning so that
d_keynext will retrieve the first key on file.
Note: Used in conjunction with the d_pkeynext function,

d_pkeyfind provides a particularly easy method for retrieving a
range of records by key.

S_NOTFOUND
S_NOTKEY

d_pkeyfind
Currency curr_rec = found record; (or NULL_DBA if S_NOTFOUND)

Changes
record found by d_pkeyfind. Another application can also change
the record so that its key field no longer matches the value specified
to d_pkeyfind.
See Also d_keyfind, d_keynext, d_pkeynext, d_pkeyprev
Example
/* Given a compound key on last and first name, find all records
matching R Miller (for example Ralph Miller, Rich Miller). */
struct name_index NI;
strcpy(NI.last_name, "Miller");
strcpy(NI.first_name, "R");
for (rv = d_pkeyfind(NAME_INDEX, 2, 1, &NI, hDb); rv == S_OKAY;
rv = d_pkeynext(NAME_INDEX, 2, 1, &NI, hDb)) {
... /* Process this "R Miller" record */
}

d_pkeynext
d_pkeynext Find the record occurrence associated with the next key
Syntax short d_pkeynext (long field, short nFields,

RDM_DB hDb)
Parameters field [Input] The key field type for which to search.
nFields [Input] The number of fields. If this parameter is
set to zero, the function searches all fields. If this
parameter specifies a non-zero value, the function
uses only the number of fields indicated. This
parameter applies only to compound keys.
partialStrLen [Input] The partial string length, in bytes. If this
parameter specifes a non-zero value, the function
uses only this many characters of the last field being
Description This function finds the record occurrence associated with the next
occurrence of the specified key (field parameter). The d_pkeynext
function with nFields equal to zero and partialStrLen equal to zero is
equivalent to d_keynext.
The d_pkeynext function returns S_NOTFOUND if it finds no more
keys or a key that is greater than the key specified by fldval (as
restricted by nFields and partialStrLen). Because Velocis keeps track
of the relative position of each key field in a key stack, the
application can intersperse d_pkeynext and d_keynext calls for

S_NOTFOUND
S_NOTKEY
Currency curr_rec = record with next key; (or NULL_DBA if S_NOTFOUND)

Changes

d_pkeynext
record found by d_pkeynext. This code indicates that another

application has deleted the record. Also, another application might
change the record so that its key field no longer matches the value
specified to d_pkeynext.
See Also d_keyfind, d_keynext, d_keyprev, d_pkeyfind, d_pkeyprev
Example
/* Given a compound key on last and first name, find all records
matching R Miller (for example Ralph Miller, Rich Miller). */
struct name_index NI;
strcpy(NI.last_name, "Miller");
strcpy(NI.first_name, "R");
for (rv = d_pkeyfind(NAME_INDEX, 2, 1, &NI, hDb); rv == S_OKAY;
rv = d_pkeynext(NAME_INDEX, 2, 1, &NI, hDb)) {
... /* Process this "R Miller" record */
}

d_pkeyprev
d_pkeyprev Find the record occurrence associated with the previous key
Syntax short d_pkeyprev (long field, short nFields,

RDM_DB hDb)
Parameters field [Input] The field type of the key field for which the
previous key will be found.
nFields [Input] The number of fields. If this parameter has
a value of zero, the function searches all fields. If
this parameter specifies a non-zero value, the
function uses only the number of fields indicated.
This parameter applies only to compound keys.
partialStrLen [Input] The partial string length. If this parameter
specifes a non-zero value, the function uses only
this many characters of the last field being
Description This function finds the record occurrence associated with the
previous occurrence of the specified key (field parameter). The
d_pkeyprev function with nFields equal to zero and partialStrLen
equal to zero is equivalent to d_keyprev.
The d_pkeyprev function returns S_NOTFOUND if it finds no more
keys, or a key whose value is less than that specified by fldval (as
restricted by nFields and partialStrLen). Because Velocis keeps track
of the relative position of each key field in a key stack, the
application can interleave d_pkeyprev and d_keyprev calls for

S_NOTFOUND
S_NOTKEY
Currency curr_rec = record with previous key (or NULL_DBA if

Changes S_NOTFOUND)

d_pkeyprev
record found by d_pkeyprev. This code indicates that another
application has deleted the record. Also, another application might
change the record so that its key field no longer matches the value
specified to d_pkeyprev.
See Also d_keyfind, d_keyprev, d_pkeyfind, d_pkeynext
Example
/* Given a key on NUMBER (a ’short’), print all records with
NUMBER> = 25, in order of highest to lowest number. */
short minToPrint = 25;
for (rv = d_keylast(NUMBER hDb); rv == S_OKAY;
rv = d_pkeyprev(NUMBER, 0, 0, (void *)&minToPrint, hDb)) {
d_recread(...); /* Read this record */
... /* ... and print it */
}

d_rdcurr
d_rdcurr Read the currency tables
Syntax short d_rdcurr (DB_ADDR *currbuff, short buflen, short *currsize,

RDM_DB hDb)
Parameters currbuff [Output] A pointer to the currency table.

buflen [Input] The size of the buffer indicated by currbuff.
currsize [Output] A pointer to the currency table buffer’s
actual size (bytes).
Description This function copies the contents of the currency table to the buffer
pointed to by currbuff. It writes the size of the currency table buffer
to the currsize parameter, which must not be NULL. If currbuff is set
to NULL, or buflen is set to zero, d_rdcurr writes no currency
information and places in currsize the size, in bytes, of the buffer
required to store the currency. Your application can use this
information in allocating buffer for subsequent calls to d_rdcurr. If
buflen is non-zero, but less than the currency size, d_rdcurr writes
the required size in currsize and returns an S_BUFLEN error code
without writing to currbuff.
The currency table is returned as an array of DB_ADDRs. The first
in the table is the current record, followed by the current set owners,
and then the current set members. If the application knows the
number of sets in the database, the length of curbuff can be
calculated as:
buflen = ((numSets * 2) + 1) * sizeof(DB_ADDR)
Note: Your application uses the d_rdcurr function with d_wrcurr to

save and restore the state of a database currency.
Return Values S_BUFLEN

S_INVNULL
Currency None
Changes
Locking None
Requirements

d_rdcurr
See Also d_wrcurr
Example
DB_ADDR ctab[128]; /*Save currency table*/
short csize; /*Size of saved currency table*/
...
d_rdcurr(ctab, sizeof(ctab), &csize, hDb); /*Save currency tables*/
... /*Do other processing*/
d_wrcurr(ctab, sizeof(ctab), hDb); /*Restore currency tables*/

d_rdlockmodes
d_rdlockmodes Set read lock modes
Syntax short d_rdlockmodes (short dirty_reads, short freeable,

RDM_SESS hSess)
Parameters dirty_reads [Input] A flag indicating whether to permit dirty

reads. A zero value disables dirty reads (default).
A non-zero value indicates that dirty reads are
permitted.
freeable [Input] A flag indicating whether read locks can be
freed within a transaction. A zero value disables
freeing read locks (default). A non-zero value
indicates read locks can be freed.
Description This function sets the current level of transaction isolation for multi-
user database environments. In a call to this function, the
application enables dirty reads and freeable read locks within a
transaction. The d_rdlockmodes function returns S_ILLMODE if
the application attempts to loosen transaction isolation (for example,
enable dirty reads) while a transaction is active. See Chapter 3 of the
Velocis User’s Guide for more about transaction isolation in
multi-user database environments.
Note: When Velocis starts, the default level of transaction isolation

is the highest. In other words, dirty reads are not allowed and
freeing of read locks within transactions is disabled.
Return Values S_ILLMODE
Currency None
Changes
Locking None
Requirements
See Also d_cmlock, d_cmfree, d_cofree, d_colock, d_crfree, d_crlock,

d_crslock, d_csfree, d_cslock, d_dbafree, d_dbalock, d_grplock,
d_release

d_rdlockmodes
Example
/* Configure this instance to permit dirty reads */
d_rdlockmodes(1, 0, hSess);
...
/* Now configure for dirty reads and
freeable read locks within transaction */
...
/* Now go back to highest (default) level of isolation */

d_recfrst
d_recfrst Find the first record occurrence of a record type
Syntax short d_recfrst (short rec, RDM_DB hDb)
Parameters rec [Input] The record type sought.

Description This function finds the first record occurrence of the specified record
type (rec) in the related data file. The d_recfrst function searches
records in database address order, skipping any deleted records or
records of a different type. Thus, this function retrieves the record
occurrence with the lowest database address. Your application uses
this function with the d_recnext and d_recprev functions to provide
sequential record access capability.
Note: If the data file contains multiple record types, or large blocks
of deleted records, the d_recfrst function might require substantial
amounts of time to scan the file until it finds a record of type rec.
Return Values S_INVREC

S_NOTFOUND
Currency curr_rec = record found; (unchanged if S_NOTFOUND)

Changes
Requirements receive an S_DELETED error code when it attempts a subsequent
read operation. This code indicates another application deleted the
record.
See Also d_reclast, d_recnext, d_recprev, d_recset
Example
int info_total;
/* Compute total number of info records in database */

for (info_total = 0, stat = d_recfrst(INFO, hDb);
stat == S_OKAY; stat = d_recnext(hDb))
++info_total;
printf("total of %d info records in database\n",info_total);

d_reclast
d_reclast Find the last record occurrence of a record type
Syntax short d_reclast (short rec, RDM_DB hDb)
Parameters rec [Input] The record type sought.

Description This function finds the last record occurrence of the specified record
type (rec) in the related data file. The d_reclast function searches
records in database address order, skipping any deleted records or
records of a different type. Thus, this function retrieves the record
occurrence with the highest database address. Your application
uses this function with the d_recprev and d_recnext functions to
provide sequential record access capability.
of deleted records, the d_reclast function might require substantial

S_NOTFOUND
Currency curr_rec = found record; (unchanged if S_NOTFOUND)

Changes
record.
See Also d_recfrst, d_recnext, d_recprev, d_recset
Example
int info_total;

for (info_total = 0, stat = d_reclast(INFO, hDb);
stat == S_OKAY; stat = d_recprev(hDb))
++info_total;
printf("Total of %d info records in database\n", info_total);

d_recnext
d_recnext Find the next record occurrence of the current record type
Syntax short d_recnext (RDM_DB hDb)
Description This function finds the next occurrence of the record with the same
type (rec) that was found with a previous call to d_recfrst, d_reclast,
d_recprev, or d_recset. The d_reclast function searches records in
database address order, skipping any deleted records or records of a
different type. The function returns S_NOTFOUND when it finds
no more records. It provides sequential record access capability.
of deleted records, the d_recnext function might require substantial

S_NOTFOUND
S_NOTYPE

Changes
record.
See Also d_recfrst, d_reclast, d_recprev, d_recset
Example
int info_total;

for (info_total = 0, stat = d_recfrst(INFO, hDb);
stat == S_OKAY; stat = d_recnext(hDb))
++info_total;

d_recprev
d_recprev Find the previous record occurrence of the current record type
Syntax short d_recprev (RDM_DB hDb)
Description This function finds the previous occurrence of the record with the
same type record (rec) found with a previous call to d_recnext,
d_reclast, d_recfrst, or d_recset. The d_recprev function retrieves
records in descending database address order, skipping any deleted
records or records of a different type. The function returns
S_NOTFOUND when it finds no more records. It provides
sequential record access capability.
of deleted records, the d_recprev function might require substantial

S_NOTFOUND
S_NOTYPE

Changes
record.
See Also d_recfrst, d_reclast, d_recnext, d_recset
Example
int info_total;
for (info_total = 0, stat = d_reclast(INFO, hDb);
stat == S_OKAY; stat = d_recprev(hDb))
++info_total;

d_recread
d_recread Read the contents of the current record
Syntax short d_recread (short rec, void *data, RDM_DB hDb)
Parameters rec [Input] The record type to read.

data [Output] A pointer to the record contents.
Description This function verifies that the current record is of type rec. It then
copies the contents of the current record into the data area pointed
to by data. The rec parameter is used for validation of the type of the
current record, and it does not imply that Velocis supports a current
of record type. There is only one current record.
record. A good practice is to use the structure definitions from the
header generated by ddlproc (for example, "struct info infoData;").

S_INVREC
Currency None
Changes
Locking If dirty reads are not enabled, a lock is required for the current
Requirements record.
See Also d_crread
Example
struct info irec;
...
d_recread(INFO, &irec, hDb);
}

d_recset
d_recset Set the current record for a record type scan
Syntax short d_recset (short rec, RDM_DB hDb)
Parameters rec [Input] The record type.

Description This function verifies that the current record is of type rec and sets
the current scan position to the position of the current record. Your
application uses d_recset to establish the current position for
sequential record access scans from the current record, via
d_recnext or d_recprev. The function enables sequential scans
regardless of how the current record was established.
Currency None
Changes
Locking None
Requirements
See Also d_recfrst, d_reclast, d_recnext, d_recprev
Example
/* Scan sequentially from key, starting with key */
d_keyfind(INFO_TYPE,&info_key, hDb);
for (stat = d_recset(INFO, hDb); stat == S_OKAY;stat = d_recnext(hDb))
{
d_recread(INFO, &info, hDb);
print_record(&info);
}

d_recsetat
d_recsetat Set the record type and database address to reflect the current
record
Syntax short d_recsetat (short rec, DB_ADDR dba, RDM_DB hDb)
Parameters rec [Input] The record type to set.

dba [Input] The database address of the record.
Description This function is the same as d_recset except that dba is used instead
of the current record.

S_OKAY
Currency None
Changes
Locking None
Requirements
See Also d_recset

d_recseqno
d_recseqno Get the next file sequence number for the specified record type
Syntax short d_recseqno (short rec, unsigned long *pSeqno, RDM_DB hDb)
Parameters rec [Input] The record type.

pSeqno [Output] A pointer to the sequence number
variable.
Description This function can be used to acquire a monotonically increasing,

non-negative long value associated with the file that contains the
specified record type. Each time d_recseqno is called, a new value
is generated; this value is at least one greater than the value
returned from the prior call for the specified record type, rec. The
next unsigned long value is stored in page zero of each data file,
along with the last slot and delete chain values. If a file contains
more than one record type, all of those record types will share the
same sequence number.

d_rectot
d_rectot Get the current total of record occurrences
Syntax short d_rectot (short rec, unsigned long *pTot, RDM_DB hDb)
Parameters rec [Input] The record type to count.

pTot [Output] A pointer to an unsigned long variable
where the function returns the total.
Description The d_rectot function returns the current total number of

occurrences of record type rec. The returned total includes any
newly created or deleted records that have yet to be committed. If
you want to count only the occurrences for committed transactions,
you must lock the record type by calling d_rtlock before calling this
function.
Note: A total that excludes uncommitted transactions is rarely

necessary. In addition, calling d_rtlock may reduce performance for
multiple users.
Currency None
Changes
Locking None, although a record type lock will ensure a transaction-

Requirements consistent result value.
See Also d_rtlock
Example
unsigned long total;
...
d_rectot(CUSTOMER, &total, hDb);
printf("there are %lu customers in the database\n", total);

d_recwrite
d_recwrite Write the contents of the current record
Syntax short d_recwrite (short rec, void *data, RDM_DB hDb)
Parameters rec [Input] The current record type.

data [Input] A pointer to the data to copy into the
current record.
Description This function copies the data from the location pointed to by data
into the current record. The write operation automatically updates
key fields and sorted sets with sort fields contained in the current
record. However, when multiple fields in the record are used as
sort fields in the same set, your application obtains better results if it
calls d_discon to disconnect the current record from all sorted sets
before calling d_recwrite. After the call to d_recwrite, the
application should reconnect the record with the sets by calling
d_connect.
The application cannot use the d_recwrite function to modify a
BLOB field. If the function is called for this type of data, it returns
S_BLOBUPD.
record. A good practice is to use the structure definitions from the
header generated by ddlproc (for example, "struct info infoData;").
Return Values S_BLOBUPD S_INVDOUB S_NOCR

S_DBPERM S_INVFLOAT S_NOSPACE
S_DELETED S_INVNULL S_NOTLOCKED
S_DUPLICATE S_INVREC S_TRNOTACT
Currency None
Changes
Locking Write lock on the current record. If the function modifies a field
Requirements used in a sort by clause for a sorted set, the set must also be write-
locked.
See Also d_connect, d_crwrite, d_csmwrite, d_csowrite, d_discon

d_recwrite
Example
/* Modify info record */
mod_info(id)
char *id; /* id code of info rec to modify */
{
if ( stat = d_keyfind(ID_CODE, id, hDb) == S_OKAY ) {
if ( edit_info(&irec) ) { /* User edits info data */
d_recwrite(REC1, &irec, hDb); /* Okay to update */
}
else
... /* Edit canceled */
}
else if ( stat == S_NOTFOUND )
usermsg("id code not found");
}

d_release
d_release Free all locks
Syntax short d_release (short freeFlag, RDM_SESS hSess)
Parameters freeFlag [Input] A flag indicating the type locks to free.

Possible values are:
0 Free no locks
RDLOCKS Free read locks
WRLOCKS Free write locks
RWLOCKS Free all locks
Description This function frees all instance and table locks for your application.
The function returns S_TRFREE if the application tries to illegally
free locks within a transaction. It is always illegal to free write locks
within a transaction. If the application has not enabled the freeing
of read locks, it is also illegal to free read locks within a transaction.
Return Values S_TRFREE
Currency None
Changes
Locking None
Requirements

d_rdlockmodes, d_rtfree, d_rtlock, d_stfree, d_stlock, d_trabort,
d_trend, d_trrollback
Example
/* Freeing locks in no-trans application */
d_open("dbase1", "sn", hSess); /* Open db in shared, no-trans mode */
...
d_crlock("r", hDb);
d_crslock(SET1, "w", hDb);
d_dbalock(savedba, "r", hDb);
d_stlock(SET2, "w", hDb);
...
d_release(RWLOCKS, hSess); /* Free all locks */

d_reset_dberr
d_reset_dberr Reset the error handler stack to the specified function
Syntax short d_reset_dberr (ERRORPROC func, RDM_SESS hSess)
Parameters func [Input] The error handler function for the

application. The function must have this prototype:
void REXTERNAL ErrorHandler
(short ReturnCodeNumber, RDM_SESS hSess,
void *PointerToServiceInfo)
Description This function resets the error handler stack to place the error
handling function specified by func at the top of the stack. Before
calling d_reset_dberr, your application must provide the name of its
error handler in a call to d_set_dberr.
In effect, d_reset_dberr pops the error handler stack until the
application error handler is uncovered. If it does not find the error
handler specified by the application on the stack, the function
returns S_NODBERR and leaves the error handler stack unchanged.
Return Values S_NODBERR
Currency None
Changes
Locking None
Requirements
See Also d_set_dberr, d_unset_dberr

d_rtfree
d_rtfree Free a record type lock
Syntax short d_rtfree (short rec, RDM_DB hDb)
Parameters rec [Input] The record type for which to free locks.
Description This function frees the record type lock on the specified record type.
The d_rtfree function returns S_TRFREE if the application attempts
to free a write lock within a transaction. The same error code is
returned if the application tries to free a read lock within a
transaction, but has not enabled the freeing of read locks (see
d_rdlockmodes). The d_rtfree function returns an S_NOTLOCKED
error code if the application attempts to free a record that has no
record type locks.

S_NOTLOCKED
S_TRFREE
Currency None
Changes
Locking None
Requirements

d_rdlockmodes, d_release, d_rtlock, d_stfree, d_stlock, d_trabort,
Example
d_open("dbase2", "sn", hSess);
...
/* Allow app to update any record for REC1 */
d_rtlock(REC1, "w", hDb);
...
d_recwrite(REC1, val1, hDb);
d_recwrite(REC1, val2, hDb);
...
d_delete(hDb);
d_rtfree(REC1, hDb);

d_rtlock
d_rtlock Request a record type lock
Syntax short d_rtlock (short rec, char *ltype, RDM_DB hDb)
Parameters rec [Input] The record type to lock.

Description This function requests a record type lock of the type specified by rec.
If the d_rtlock function finds the requested lock identical to the
existing lock for the record, it ignores the application request and
returns S_OKAY.
Once the application locks a record type, all instances of the record
are implicitly given the same kind of lock. Thus the application can
freely access the record instances without setting up record instance
locks. Note that locking the record type does not provide any access
to set connections. The application must separately lock the set
(instance or type).
Caution: Your application should use record type locks carefully.

Improper use of d_rtlock can result in lower concurrency and
decreased performance.
Return Values S_BADTYPE S_INVDB S_NOCO

S_CONFLICT S_INVMEM S_NOTGRANTED
S_DBPERM S_INVNULL S_STATIC
S_DELETED S_INVREC S_UNAVAIL
S_EOS S_INVSET S_UPGDEN
S_ILLDOWNG S_LOCKED
S_INVADDR S_NOCM
Currency None
Changes
Locking None
Requirements

d_rtlock

d_rdlockmodes, d_release, d_rtfree, d_stfree, d_stlock, d_trabort,
Example
...
/* Allow app to update any record for REC1 */
d_rtlock(REC1, "w", hDb);
...
d_recwrite(REC1, val1, ...);
d_recwrite(REC1, val2, ...);
...
d_delete(hDb);
d_rtfree(REC1, hDb);

d_set_dberr
d_set_dberr Replace the default error handler
Syntax short d_set_dberr (ERRORPROC func, void *svcptr,

RDM_SESS hSess)
Parameters func [Input] The application error handler function. The

function must have this prototype:
svcptr [Input] A pointer to information for the error
handler function (func parameter) to service. The
application can use this parameter to pass
additional information to its error handler.
Description This function sets the default application error handler function
(func parameter) that Velocis can call when it detects an error while
processing a Core API (d_) function. The specified error handler
supersedes the current error handler or the default error handler
dberr. In effect, the previous error handler is "pushed" into the
stack by the new error handler. See Chapter 7 of the Velocis User’s
Guide for help in writing an error handler for your application.
Currency None
Changes
Locking None
Requirements
See Also d_reset_dberr, d_unset_dberr

d_set_dberr
Examples Note: The Windows version of the d_set_dberr function expects a

procedure instance address returned from MakeProcInstance as in
the Windows example below. This function must be exported in the
definitions (.def) file for the application.
Windows Your application:

void REXTERNAL MyDberr(short, RDM_SESS, void far*);
FARPROC fp;
fp = MakeProcInstance((FARPROC)MyDberr, hInstance);
d_set_dberr((ERRORPROC)fp, NULL, hSess);
The .def file for the application:

EXPORTS
MyDberr @1
Non-Windows
#include "rds.h"
void REXTERNAL my_dberr(short, RDM_SESS, void*);

...
main()
{
...
d_set_dberr(my_dberr, NULL, hSess);
...
}
void REXTERNAL my_dberr(
short err_no, /* Return code # */
RDM_SESS hSess, /* Client’s session handle */
void *svcptr) /* Can point to anything you want */
{
/* Special handling of some error codes here */
if ( err_no <= 0 ) {
/* Take care in calling d_close, as it may call dberr again */
PrintError(err_no);
return;
}
...
/* You may choose to ignore some codes */
if ( err_no == S_NOCM )
return;
/* Report errors */
if ( err_no == S_DUPLICATE)
printf("Duplicates not allowed\n");
return;
}

d_setkey
d_setkey Set the value of a key field
Syntax short d_setkey (long field, void *fldvalue, RDM_DB hDb)
Parameters field [Input] The key field type.

fldvalue [Input] A pointer to the value of the field to set.
Description This function sets the specified key field to the value specified by
fldvalue. Your application must call this function for each key field
in a record that will subsequently be created by a call to
d_makenew. Velocis can then create the keys during preparation of
the record by d_makenew.
Note: The application cannot use d_setkey to process optional or

compound key fields.

S_INVNULL
S_NOTKEY
Currency None
Changes
Locking None
Requirements
See Also d_fillnew, d_makenew, d_keystore
Example
/* Create a new info record */
d_setkey(ID_CODE, "db022", hDb);
d_makenew(INFO);

d_setmm
d_setmm Set the current member from the current member of another set
Syntax short d_setmm (short sett, short sets, RDM_DB hDb)
Parameters sett [Input] The set type to which the function assigns
the current member from sets.
sets [Input] The set type containing the current member
to assign.
Description This function assigns the current member of sets as the current
member of sett. The current member of sets must be a legal member
of sett and must be connected to a sett occurrence. The new current
owner of sett is obtained from the new current member of sett.
Return Values S_DELETED S_NOCM

S_INVNULL S_INVMEM
S_INVSET S_NOTCON
Currency curr_mem[sett] = curr_mem[sets];

Changes curr_own[sett] = owner of curr_mem[sets] via sett;
Locking If dirty reads are not enabled, sett must be locked. Your application
Requirements can use the d_crslock function to lock the set.
See Also d_crslock, d_setmo, d_setmr, d_setom, d_setoo, d_setor, d_setrm,

d_setro
Example
/* Print key words associated with tech. info */
d_setmm(KEY_TO_INFO, INFO_TO_KEY, hDb);
d_csoread(INFO_TO_KEY, WORD, key, hDb);
printf("%s\n", key);
}

d_setmo
d_setmo Set the current member from the current owner
Syntax short d_setmo (short setm, short seto, RDM_DB hDb)
Parameters setm [Input] The set type to which this function assigns a
new current member.
seto [Input] The set type containing the current owner to
assign as current member of setm.
Description This function assigns the current owner of seto as the current
member of setm. The current owner of seto must be a legal member
of setm and must be connected to a setm occurrence. The new
current owner of setm is obtained from the new current member of
setm.
Return Values S_INVMEM S_NOCO

S_INVSET S_NOTCON
Currency curr_mem[setm] = curr_own[seto];

Changes curr_own[setm] = owner of curr_own[seto] via setm;
Locking If dirty reads are not enabled, setm must be locked. Your application
See Also d_crslock, d_setmm, d_setmr, d_setom, d_setoo, d_setor, d_setrm,

d_setro
Example
long count;
...
/* Delete author, if he has no pubs. */
d_members(HAS_PUBLISHED, &count, hDb);
if ( count == 0L ) {
d_setmo(AUTHOR_LIST, HAS_PUBLISHED, hDb);
d_discon(AUTHOR_LIST, hDb);
d_delete(hDb);
}

d_setmr
d_setmr Set the current member from the current record
Syntax short d_setmr (short set, RDM_DB hDb)
Parameters set [Input] The set type for which this function assigns
the current member from the current record.
Description This function assigns the current member of set from the current
record. The current record must be a legal member of set and must
be connected to a set occurrence. The new current owner of set is
obtained from the new current member of set.
Return Values S_DBOPEN S_INVSET

S_DELETED S_NOCR
S_INVMEM S_NOTCON
S_INVNULL
Currency curr_mem[set] = curr_rec;

Changes curr_own[set] = owner of curr_rec via set;
Locking If dirty reads are not enabled, set must be locked. Your application
See Also d_crslock, d_crtype, d_setmm, d_setmo, d_setom, d_setoo, d_setor,

d_setrm, d_setro
Example
/* Disconnect and delete intersect and (possibly) key word */
d_setom(INFO_TO_KEY, HAS_PUBLISHED, hDb);
d_discon(INFO_TO_KEY, hDb);
d_setmr(KEY_TO_INFO, hDb);
d_discon(KEY_TO_INFO, hDb);
d_delete(hDb);
d_members(KEY_TO_INFO, &count, hDb);
/* Delete key word */
d_setro(KEY_TO_INFO, hDb);
d_delete(hDb);
}
}

d_setom
d_setom Set the current owner from the current member
Syntax short d_setom (short nseto, short nsetm, RDM_DB hDb)
Parameters nseto [Input] The set type for which this function assigns
the current owner from the current member of
nsetm.
nsetm [Input] The set type containing the current member
to assign as current owner of nseto.
Description This function assigns the current member of nsetm as the current
owner of nseto. The current member of nsetm must be a legal owner
of nseto. The d_setom function sets the current member of nseto to
NULL_DBA.

S_INVNULL S_NOCM
S_INVOWN
Currency curr_own[nseto] = curr_mem[nsetm];

Changes curr_mem[nseto] = NULL_DBA;
Locking None
Requirements
See Also d_setmm, d_setmo, d_setmr, d_setoo, d_setor, d_setrm, d_setro
Example
d_delete(hDb);
d_delete(hDb);
}
}

d_setoo
d_setoo Set the current owner from the current owner of another set
Syntax short d_setoo (short nsett, short nsets, RDM_DB hDb)
Parameters nsett [Input] The set type for which this function assigns
the current owner from the current owner of nsets.
nsets [Input] The set type that contains the current owner
to assign as the current owner of nsett.
Description This function assigns the current owner of nsets as the current owner
of nsett. The current owner of nsets must be a legal owner of nsett.
The d_setoo function sets the current member of nsett to
NULL_DBA.
Return Values S_INVOWN

S_INVSET
S_NOCO
Currency curr_own[nsett] = curr_own[nsets];

Changes curr_mem[nsett] = NULL_DBA;
Locking None
Requirements
See Also d_setmm, d_setmo, d_setmr, d_setom, d_setor, d_setrm, d_setro
Example
/* Make curr_member of AUTHOR_LIST null */
d_setoo(AUTHOR_LIST, AUTHOR_LIST, hDb);
/* Print list of author names */

while ( d_findnm(AUTHOR_LIST, hDb) == S_OKAY) {
}

d_setor
d_setor Set the current owner from the current record
Syntax short d_setor (short nset, RDM_DB hDb)
Parameters nset [Input] The set type for which this function assigns
the current record as current owner.
Description This function assigns the current record as the current owner of nset.
The current record must be a legal owner of nset. The d_setor
function sets the current member of nset to NULL_DBA.
Return Values S_DBOPEN S_INVOWN

S_DELETED S_INVSET
S_INVNULL S_NOCR
Currency curr_own[nset] = curr_rec;

Changes curr_mem[nset] = NULL_DBA;
Locking None
Requirements
See Also d_setmm, d_setmo, d_setmr, d_setom, d_setoo, d_setrm, d_setro
Example
/* List "database technology" publications */
if (d_keyfind(KEYWORD, "database technology", hDb) == S_OKAY) {
d_setor(KEY_TO_INFO, hDb);
while ( d_findnm(KEY_TO_INFO, hDb) == S_OKAY ) {
d_findco(INFO_TO_KEY, hDb);
pr_info();
}

d_setrm
d_setrm Set the current record from the current member
Syntax short d_setrm (short set, RDM_DB hDb)
Parameters set [Input] The set type for which this function assigns
the current member as the current record.
hDb Input] The database handle.
Description This function assigns the current member of set as the current
record.
Return Values S_INVSET

S_NOCM
Currency curr_rec = curr_mem[set];

Changes
Locking None
Requirements
See Also d_setmm, d_setmo, d_setmr, d_setom, d_setoo, d_setor, d_setro
Example
d_setrm(HAS PUBLISHED, hDb);
pr_info(); /* Print info record */

d_setro
d_setro Set the current record from the current owner
Syntax short d_setro (short set, RDM_DB hDb)
Parameters set [Input] The set type whose current owner will be
assigned as current record.
Description This function assigns the current record from the current owner of
set.
Return Values S_INVSET

S_NOCO
Currency curr_rec = curr_own[set];

Changes
Locking None
Requirements
See Also d_setmm, d_setmo, d_setmr, d_setom, d_setoo, d_setor, d_setrm
Example
d_delete(hDb);
d_delete(hDb);
}
}

d_showLocks
d_showLocks Show the lock status
Syntax short d_showLocks (short locktype, short obtype,

LOCKLIST_ENTRY *pLockList, long maxelems,
long *actualelem, RDM_DB hDb)
Parameters locktype [Input] The lock type indicator. To return

information on instance or table locks, specify
LOCK_INSTANCE or LOCK_TABLE, respectively.
obtype [Input] The object type (record or set ID) to be
searched for current locks.
pLockList [Output] A pointer to the lock information. The
LOCKLIST_ENTRY structure, defined in rdm.h,
contains the following information:
DB_ADDR dba
The database address of this lock (used only for
instance locks).
long NumOwners
The number of owners with this lock.
long NumQueued
The number of locks waiting to be granted.
char LockMode
The lock mode (’r’ = read lock, ’w’ = write lock).
char LockOwner[USERNAMELEN]
The Velocis user name of the first owner of this
lock. If NumOwners is greater than 1, call
d_showOwners to get a complete owner list.
maxelems [Input] The maximum number of locks to retrieve.
If a value of zero is specified, this function returns
the number of locks in actualelem.
actualelem [Output] A pointer to the number of locks found.
Description This function returns a list of locks (of locktype) within a database. If
more than one owner for a lock (actualelem > 1) exists, you can call
d_showOwners to retrieve the list of all users with this lock.
See Also d_showOwners

d_showOwners
d_showOwners Show a list of lock owners
Syntax short d_showOwners (short locktype, short obtype, DB_ADDR dba,

void *pOwnList, short sBufLen, long maxelems,
long *actualelem, RDM_DB hDb)
Parameters locktype [Input] The lock type indicator. To return

information on instance or table locks, specify
LOCK_INSTANCE or LOCK_TABLE, respectively.
obtype [Input] The object type (record or set ID) to be
searched for current locks.
dba [Input] The database address of the lock. This
parameter is used only for instance locks. Use the
corresponding value returned from d_showLocks.
pOwnList [Output] A pointer to the list of lock owners. This
list is stored as an array of strings, each with a
length of USERNAMELEN.
sBufLen [Input] The size of the result buffer. The product of
maxelems and USERNAMELEN should be used.
maxelems [Input] The maximum number of lock owners to
retrieve. If zero is specified, this function returns
the number of lock owners in actualelem.
actualelem [Output] A pointer to the actual number of lock
owners found.
Description This function returns a list of all owners of a particular lock type
(locktype) within a database. It is useful if there are locks with more
than one owner, since d_showLocks can only retrieve one owner
per lock.
See Also d_showLocks

d_stfree
d_stfree Free the set type lock
Syntax short d_stfree (short set, RDM_DB hDb)
Parameters set [Input] The set type on which to free locks.

Description This function frees the set type lock on the specified set. The
d_stfree function returns S_TRFREE if the application attempts to
free a write lock within a transaction. The same error code returns if
the application tries to free a read lock within a transaction, but has
not enabled the freeing of read locks (see d_rdlockmodes). The
d_stfree function returns an S_NOTLOCKED error code if the
application attempts to free a set for which it has no set type locks.
Return Values S_INVSET S_NOTLOCKED

S_NOLOCK S_TRFREE
Currency None
Changes
Locking None
Requirements

d_rdlockmodes, d_release, d_rtfree, d_rtlock, d_stlock, d_trabort,
Example
...
/* Allow app to freely modify any set connect in SET1 */
...
d_discon(SET1, hDb);
...
d_connect(SET1, hDb);
...
d_stfree(SET1, hDb);

d_stlock
d_stlock Request a set type lock
Syntax short d_stlock (short set, char *ltype, RDM_DB hDb)
Parameters set [Input] The set type to lock.

Description This function requests a set type lock for the specified set. If the
d_stlock function finds that the requested lock is identical to the
existing lock for the set type, it ignores the application request and
returns S_OKAY.
Once the application locks a set type, all instances of the set are
implicitly given the same kind of lock. Thus the application can
freely access the set instances without setting up set instance locks.
Note that locking the set type does not provide any access to the
contents of records that are owners or members of the set. The
application must separately lock the records (instance or type).
Caution: Your application should use set type locks carefully.

Improper use of d_stlock can result in lower concurrency and
decreased performance.
Return Values S_BADTYPE S_INVDB S_NOTGRANTED

S_CONFLICT S_INVNULL S_UNAVAIL
S_DBPERM S_INVREC S_UPGDEN
S_DELETED S_INVSET
S_ILLDOWNG S_LOCKED
Currency None
Changes
Locking None
Requirements


d_stlock
d_rdlockmodes, d_release, d_rtfree, d_rtlock, d_stfree, d_trabort,

Example
...
/* Allow app to freely modify any set connect in SET1 */
...
d_discon(SET1, hDb);
...
d_connect(SET1, hDb);
...
d_stfree(SET1, hDb);

d_taskinfo
d_taskinfo Retrieve information about each session currently logged into

Velocis
Syntax short d_taskinfo (short pos, RDM_SESS *sessHandle,

TASK_INFO *taskinfo, RDM_SESS hSess)
Parameters pos [Input] A specifier to select the session on which to

retrieve information. To retrieve task information
for the first, next, or current session, specify
FETCHFIRST, FETCHNEXT, or FETCHTHIS,
respectively.
sessHandle [Output] The session handle for the task.
taskinfo [Output] The task information.
hSess [Input] The current session handle.
Description The d_taskinfo function returns information about each session that
is currently logged into the Velocis server. The session handle for
the task is returned in sessHandle. The task information is returned
in the TASK_INFO structure pointed to by taskinfo. Of the
information in this structure, only the name of the logged-in user is
useful to an application program. This user name is stored in the
TASK_INFO structure’s usname field (a character array with a length
of USERNAMELEN bytes).

d_timeout
d_timeout Set the lock request timeout value
Syntax short d_timeout (short sec, RDM_SESS hSess)
Parameters sec [Input] The number of seconds to wait before

timing out (the default is 10 seconds). A value of
zero for the sec parameter causes lock requests to
time out immediately if they cannot be granted. A
negative value for the sec parameter indicates that
no lock requests will time out (that is, they will wait
indefinitely).
Description This function sets the timeout period for pending lock requests for
your application. The lock request functions return S_UNAVAIL
when a timeout occurs.
Your application must call d_timeout after calling d_open. Since
timeouts are the only means of detecting potential deadlock
situations, the application should take care in turning off a timeout.
Note: The amount of time required to service a lock request varies

with system load. A timeout can mean that the server is very busy,
but not deadlocked.
Return Values S_OKAY S_UNAVAIL
Currency None
Changes
Locking None
Requirements

d_rdlockmodes, d_release, d_rtfree, d_rtlock, d_stfree, d_stlock
Example
d_open("tims", "s");
d_timeout(30, hSess); /* Set a 30 second timeout value */

d_trabort
d_trabort Abort a transaction
Syntax short d_trabort (RDM_SESS hSess)
Description This function aborts a database transaction. An abort operation

discards all database changes made between the call to d_trbegin
and the call to d_trabort. All locks held by your application are
freed.
Note: To commit all changes, the application should call d_trend

instead of d_trabort.
Return Values S_TRNOTACT

S_VOIDTX
Currency Currency might be in an undefined state following completion of

Changes d_trabort. The application should always explicitly re-establish the
currency.
Locking None
Requirements
See Also d_trbegin, d_trend, d_trmark, d_trrollback
Example
d_trbegin("orderentry", hSess);
... /* Enter customer info */
... /* Enter order info */
... /* Check inventory */
if ( items_requested > items_available ) {
d_trabort(hSess);
... /* Inform user */
}
else {
... /* Complete update */
d_trend(hSess);
}

d_tractive
d_tractive Determine whether a transaction is active
Syntax short d_tractive (short *bool, RDM_SESS hSess)
Parameters bool [Output] A pointer to the transaction state flag. The

flag has a non-zero value if the transaction is active,
and a zero value if the transaction is not active.
Description This function determines if a database transaction is active in the

session specified by hSess. Since Velocis does not allow nested
transactions, the application might call d_tractive within
subfunctions to determine whether to begin and end a transaction.
If a transaction is already active, the application can leave calls to
d_trbegin and d_trend to higher levels in the code.
Currency None
Changes
Locking None
Requirements
See Also d_trabort, d_trbegin, d_trmark, d_trrollback
Example
/* If a transaction has not been started, begin one now.
Otherwise, "nest" within the caller’s transaction. */
short inTrans;
d_tractive(&inTrans, hSess);
if (!inTrans)
d_trbegin("orderentry");
... /* Update the database */
/* If this routine started a transaction, end it */

if (inTrans)
d_trend(hSess);

d_trbegin
d_trbegin Begin a transaction
Syntax short d_trbegin (const char *tid, RDM_SESS hSess)
Parameters tid [Input] The transaction identification string. The

contents of this string are arbitrary, provided that it
is nonempty. The significant length is eight bytes.
Description This function marks the beginning of a new database transaction.

All database changes made between the call to d_trbegin and a
subsequent call to d_trend are grouped as a single transaction and
committed to the database as a unit by d_trend. The application can
discard all changes made after it calls d_trbegin by calling
d_trabort. The application can also abort portions of the transaction
by calling d_trmark and d_trrollback.
A transaction is associated with a session, and it controls the
changes for all databases that are opened in the session.
Note: If you want to modify both SQL and Core databases in the
same transaction, we recommend that you use the SQLTransact
function instead and make the changes to the SQL database before
changing the Core database. The transaction will be committed
upon the next call to SQLTransact.
The transaction identification string (tid) can be used as a

d_trrollback target, which causes cancellation of all updates in the
transaction. However, the transaction is still active, and locks still
exist.
Return Values S_DBOPEN S_TRACTIVE S_TXTIMEOUT

S_NOSPACE S_TRANSID
Currency None
Changes
Locking None
Requirements
See Also d_trabort, d_tractive, d_trend, d_trmark, d_trrollback

d_trbegin
Example
char tr_id[25]; /* Transaction id string */
int tr_tot = 0; /* Total number of transactions */
...
sprintf(tr_id, "tr# %4d", ++tr_tot);
d_trbegin(tr_id, hSess);
... /* 1.Enter cust info, 2.Enter order info, 3.Check inventory */
if ( items_requested > items_available ) {
d_trabort(hSess);
... /* inform user */
}
else {
... /* Complete update */
d_trend(hSess);
}

d_trend
d_trend End a transaction
Syntax short d_trend (RDM_SESS hSess)
Description This function ends a database transaction by committing to the

database all changes made since the most recent call to d_trbegin.
The function frees all locks held by your application. When d_trend
returns, all changes made within the transaction are permanent.
Note: To discard changes made within a transaction, the application

should call d_trabort instead of d_trend.
Return Values S_TRNOTACT
Currency None
Changes
Locking None
Requirements
See Also d_trabort, d_tractive, d_trbegin, d_trmark, d_trrollback
Example
d_trbegin("orderentry");
... /* Enter order info */
d_trend(hSess);

d_trmark
d_trmark Mark a transaction
Syntax short d_trmark (const char *mtag, RDM_SESS hSess)
Parameters mtag [Input] A pointer to the current position in the

transaction.
Description This function marks the specified position within the current
transaction. Later, your application can roll back (via d_trrollback)
to this point in the transaction. The application uses d_trmark and
d_trrollback to discard portions of a transaction without
terminating the transaction or discarding locks.

S_TRANSID
S_TRNOTACT
Currency None
Changes
Locking None
Requirements
See Also d_trabort, d_tractive, d_trbegin, d_trend, d_trrollback
Example
d_trbegin("rollback", hSess);
...
d_trmark("mark1", hSess); /* 1st mark */
...
d_trmark("mark2", hSess); /* 2nd mark */
...
d_trrollback("mark2", hSess); /* Rollback to mark2 */
...
d_trmark("mark3", hSess); /* 3rd mark */
...
d_trrollback("mark1", hSess); /* Rollback to mark1
(mark3 wiped out as well) */
...
d_trrollback("missing", hSess); /* Undo all work */

d_trrollback
d_trrollback Roll a transaction back to a mark
Syntax short d_trrollback (const char *mtag, RDM_SESS hSess)
Parameters mtag [Input] A pointer to the marker within the

transaction to which this function rolls back.
Description This function rolls back within a transaction to the position

indicated by mtag (previously set via d_trmark or d_trbegin). The
comparison of mtag with mark tags is case-sensitive. If mtag is set to
NULL, d_trrollback calls d_trabort. If d_trrollback cannot find the
marker (mtag), it rolls back to the beginning of the transaction,
which remains active. The d_trrollback function does not free locks
on existing records and sets obtained in a transaction.
Note: Your application can use d_trbegin, d_trmark, and

d_trrollback to discard portions or all of a transaction.
Return Values S_NOMARK

S_TRNOTACT
S_VOIDTX
Currency The state of the currency can be undefined following completion of

Changes the d_trrollback function. The application should always explicitly
re-establish the currency.
Locking None
Requirements
See Also d_trabort, d_trbegin, d_trend, d_trmark

d_trrollback
Example
d_trbegin("rollback", hSess);
...
d_trmark("mark1", hSess); /* 1st mark */
...
d_trmark("mark2", hSess); /* 2nd mark */
...
d_trrollback("mark2", hSess); /* Rollback to mark2 */
...
d_trmark("mark3", hSess); /* 3rd mark */
...
d_trrollback("mark1", hSess); /* Rollback to mark1
(mark3 wiped out as well) */
...
d_trrollback("missing", hSess); /* Undo all work */

d_unset_dberr
d_unset_dberr Remove an error handler function
Syntax short d_unset_dberr (ERRORPROC func, RDM_SESS hSess)
Parameters func [Input] The application error handler function. The

Description This function removes the specified error handler function (func)
from the top of the error handler stack. If d_unset_dberr does not
find the function on the stack, it returns S_NODBERR and leaves the
error handler stack unchanged.
Return Values S_NODBERR
Currency None
Changes
Locking None
Requirements
See Also d_reset_dberr, d_set_dberr

d_wrcurr
d_wrcurr Restore the currency tables
Syntax short d_wrcurr (DB_ADDR *currbuff, unsigned short buflen,

RDM_DB hDb)
Parameters currbuff [Input] A pointer to an allocated buffer that

contains the currency tables.
buflen [Input] The length, in bytes, of the buffer specified
by currbuff.
Description This function restores the currency tables from currbuff. The length
of the buffer, indicated by buflen, must be large enough to store the
entire currency. If the buffer length is too small, d_wrcurr returns
S_BUFLEN and makes no change to the currency.
Note: Your application can use the d_wrcurr function with d_rdcurr
to save and restore the state of a database currency.
Return Values S_BUFLEN
Currency All currency

Changes
Locking None
Requirements
See Also d_rdcurr
Example
DB_ADDR ctab[128]; /* Save currency table */
short csize; /* Size of saved currency table */
...
d_rdcurr(&ctab, sizeof(ctab), &csize, hDb); /* Save currency tables */
d_wrcurr(ctab, sizeof(ctab), hDb); /* Restore currency tables */

Chapter 7
Extension Module Functions
(em_ and Mod Prefix)
This chapter includes descriptions of the Velocis extension module access functions
(em_ prefix) and the functions that are used to create a extension module (Mod prefix).
The em_ functions provide access between Velocis client applications and Velocis server
extension module functions and are used in conjunction with the parameter list
functions (pl_ prefix). The Mod functions are used in an extension module to add
functionality that can be called from a Velocis client application to execute on a Velocis
server.
The extension module access functions are called either exclusively from a client
application (em_attach, em_call, em_detach, em_load, and em_unload) or from a
server extension module (em_getContext and em_getHandle). The Mod functions are
stubs of functions that you implement for identifying extension module functions
(ModDescribeFcns), initializing the module (ModInit), and cleaning up after an
application is finished with the module (ModCleanup). They also include a function
interface (ModFunction) for implementing the actual extension module routines.
To register the extension module routines with the Velocis server, you need to use an
extension module load table. The load table contains a structure element for each
extension module routine. The structure, which includes members for the address and
identifier number of each module routine, is defined as follows:
typedef struct {
EMFCN fcn; /* The address of your extension module function */
short id; /* The function identifier number */
} EMLOADTABLE;
The fcn member of the structure is a pointer to one of your extension module functions.
Each extension module function declaration must conform to the ModFunction function
prototype. The id member is the function identifier number, which must be a unique
positive integer; typically, it starts at 0 and increases incrementally in the load table.
No additional header files (other than velocis.h) need to be included to use these
functions. When declaring and defining the Mod functions, however, you have to
include the REXTERNAL macro between the function type and the function name.
For more information about the em_ and Mod functions, see Chapter 11 of the Velocis
User's Guide.
Extension Module Functions (em_ and Mod Prefix) 7-1

em_attach
em_attach Attach a client program to an extension module
Syntax short em_attach (char *emName, short *pEmHandle,

RDM_SESS hSess)
Parameters emName [Input] The name of the extension module to attach.

pEmHandle [Output] A pointer to the extension module handle.
Description This function attaches a Velocis client program to an extension

module. Before calling this function, the extension module must
already be loaded. To load the extension module, call the em_load
function from any Velocis client program currently logged into the
specified server session. The call to em_attach initializes the
extension module by invoking its ModInit function. The server
session handle specified in em_attach is passed to the ModInit
function.
If the attachment is successful, the em_attach function retrieves a
handle to the extension module. The client program must use this
handle in all subsequent em_ function calls for this particular
extension module. When finished, the application must call
em_detach to detach it from the extension module.
Return Values The ModInit return value or any of these codes:

S_INVNULL S_NOEM
S_INVSESS S_NOT_STARTED
S_LONGNAME S_OKAY
See Also em_detach, em_load, ModInit

em_attach
Example
...
short emh;
short stat;
stat = em_load("_sddlp", &emh, hSess);

if ( stat != S_OKAY ) {
printf("unable to load sddlp extension module, status = %d\n",
stat);
return -1;
}
stat = em_attach("_sddlp", &emh, hSess);
printf("unable to attach sddlp extension module, status = %d\n",
stat);
return -1;
}
...

em_call
em_call Call an extension module function
Syntax short em_call (short emHandle, short fcnId,

PL_DATADESC *inParms, PL_DATADESC **outParms,
short *fcnRetCode, RDM_SESS hSess)
Parameters emHandle [Input] The extension module handle (assigned by

em_attach).
fcnId [Input] The identifier number for the extension
module function. This number must match the
function identifier in the id field of the
EMLOADTABLE structure declared in the
extension module.
inParms [Input] The descriptor for an input parameter list.
outParms [Output] The descriptor for an output parameter
list. If no output parameters are expected, specify
NULL.
fcnRetCode [Output] A pointer to the return code for the
extension module function.
Description This function calls another function contained in the specified

extension module whose handle is specified by emHandle (the
handle being assigned by a required prior call to em_attach). It
passes an input parameter list to the extension module function and
receives the results from the extension module function in the
output parameter list. The extension module function must reside,
and will be executed on, the server associated with the specified
session handle.
The input parameter list must be allocated and prepared before
calling this function. To allocate the list, call the pl_alloc function.
To prepare the list, use the pl_put, pl_printf, and pl_putStruct
functions. The input parameter list is deallocated by the call to
em_call, so there is no need to do it manually.
Once the input parameter list is ready, em_call can be used to call
the extension module and retrieve the output parameter list (if
necessary). Parameter values from the output list can be extracted
by calling the pl_get function. When the output parameter list is no
longer needed, use the pl_free function to deallocate the list. If the
outParms value is NULL, no output parameters will be returned.

em_call
Return Values S_INVNULL S_NOEM

S_INVSESS S_NOT_STARTED
S_LONGNAME S_OKAY
See Also ModFunction, pl_alloc, pl_free, pl_get, pl_printf, pl_put,

pl_putStruct
EMLOADTABLE (structure)
Example
From the application header file included in both the client program and the
extension module:
...
#define TXCLIENTINIT 0
#define TXRESET 1
#define TXTRANSACTION 2
#define TXREPORT 3
#define TXCLIENTCLOSE 4
...
From the extension module:

static EMLOADTABLE EmTable[] = {
{ TXClientInit, TXCLIENTINIT },
{ TXReset, TXRESET },
{ TXTransaction, TXTRANSACTION },
{ TXReport, TXREPORT },
{ TXClientClose, TXCLIENTCLOSE }
};

em_call
From the client program:

/* =====================================================================
Call server extension module function to perform
*/
unsigned long do_trans( void )
{
PL_DATADESC *inParms;
PL_DATADESC *outParms;
unsigned long start, stop;
short stat, rc;
/* call the extension module and fetch the return value */

start = clock();
inParms = pl_alloc();
pl_printf(inParms, "%hd%hd%hd%ld%f%hd", hSess, branch_id,
teller_id, acct_id, amount, AbortFlag);
stat = em_call(hEM, TXTRANSACTION, inParms, &outParms, &rc, hSess);
if ( stat ) {
printf( "\nProblem executing EM <%d>.\n", rc );
quitting = 1;
return( 0 );
}
if ( rc == S_OKAY ) {
/* getting new account balance */
pl_get(outParms, &tracking);
pl_get(outParms, &balance);
pl_get(outParms, &hrow);
pl_free(outParms);
}
else if ( rc == S_TXTIMEOUT )
printf("\nTransaction timed-out\n");
else
printf("\nStatus %d returned from EM\n", rc);
stop = clock();
return( tracking ? stop-start : 0 );
}

em_detach
em_detach Detach from an extension module
Syntax short em_detach (short emHandle, RDM_SESS hSess)

em_attach).
Description This function detaches an extension module from a server

associated with session hSess. Call the function from a Velocis client
application program after the program has finished using the
extension module. When em_detach is called, the server also
performs any cleanup needed for the client session by calling
ModCleanup, a user-implemented function in the extension
module.
Return Values The ModCleanup return value or any of these codes:

S_BADEMH S_NOT_STARTED
S_INVSESS S_OKAY
See Also em_attach, em_unload
Example
From the client application program:
/* =====================================================================
Closes & logs out, frees RPC stuff, and all that clean up work.
*/
void tx_close( void )
{
PL_DATADESC *sessParm;
short stat, rc;
/* call TPCBClientClose to close out client driver */

sessParm = pl_alloc();
pl_put(sessParm, PL_SHORT, 0, &hSess, 0);
stat = em_call( hEM, TXCLIENTCLOSE, sessParm, NULL, &rc, hSess );
if ( stat == S_OKAY ) {
em_detach( hEM, hSess );
em_unload( hEM, hSess );
s_logout( hSess );
}
}

em_detach
From the server extension module:

/* =====================================================================
When a client logs out, free this client's context data.
*/
short REXTERNAL ModCleanup( RDM_SESS hSess )
{
void **context;
GLOBALS *ctx;
d_unset_dberr(ReportError, hSess);
context = em_getContext( hSess, ModHandle );

ctx = (GLOBALS *)*context;
rm_freeMemory(*context, 0);
*context = NULL;
return S_OKAY;
}

em_getContext
em_getContext Get the session-specific context for this extension module
Syntax void **em_getContext (RDM_SESS hSess, short emHandle)

emHandle [Input] The extension module handle (assigned by
em_attach).
Description This function returns the location of a pointer to the session's task
context maintained by the Velocis server. It is called from an
extension module function and/or the ModInit and ModCleanup
functions.
Each extension module has a separate entry in a session's task
context that can be used to store a pointer to any user-allocated
context buffer. The extension module can use the context buffer to
store data that must persist between multiple calls to the extension
module. Using the buffer also allows you to write an extension
module that is re-entrant.
After initial allocation of the user context buffer, store the pointer to
the allocated buffer in the location pointed to by the return value of
em_getContext. To retrieve the buffer, use em_getContext in
subsequent calls to the extension module.
Note: The initial allocation of a user context buffer is normally
performed in the extension module by the ModInit function. The
buffer is normally freed by the ModCleanup function.
Return Values A pointer to the session's context pointer for this extension module
See Also ModCleanup, ModInit

em_getContext
Example
/* Data specific to each client caller */
typedef struct {
... /* contains "global" data used by EM for a particular session */
RDM_DB hDb;
} GLOBALS;
...
/* =====================================================================
Initialization for EM. Called by Velocis for each client on em_attach
*/
short REXTERNAL ModInit( RDM_SESS hSess )
{
short stat;
void **context;
GLOBALS *ctx;
/* obtain the pointer to the context pointer */

/* initialize the context pointer */

*context = ctx = (GLOBALS *)rm_cGetMemory( sizeof(GLOBALS), 0 );
/* initialize context variables */

stat = d_iopen("mydb", "s", hSess, &ctx->hDb);
if ( stat == S_OKAY ) {
... /* fetch other ctx data */
}
return stat;
}
...
/* =====================================================================
When a client logs out, free this client's context data.
*/
short REXTERNAL ModCleanup( RDM_SESS hSess )
{
void **context;
GLOBALS *ctx;

ctx = (GLOBALS *)*context;
d_iclose(ctx->hDb);
rm_freeMemory(ctx, 0);
*context = NULL;
return S_OKAY;
}

em_getHandle
em_getHandle Get the handle for this extension module
Syntax short em_getHandle (char *emname, short *pEmHandle,

RDM_SESS hSess)
Parameters emname [Input] The name of the extension module.

pEmHandle [Output] A pointer to the extension module handle
returned.
Description This function can be called from an extension module to obtain its
own handle.
Return Values S_INVNULL S_NOEM

S_INVSESS S_NOTATTACHED
S_LONGNAME
See Also em_attach

em_load
em_load Load an extension module
Syntax short em_load (char *emName, short *pEmHandle, RDM_SESS hSess)
Parameters emName [Input] The name of the extension module to load.

pEmHandle [Output] A pointer to the extension module handle
returned.
Description This function causes a Velocis server to load an extension module.

Before the extension module can be called, however, the em_attach
function must also be called. When the client program has finished
using the extension module, it must call em_detach and then
em_unload.
To load the extension module, the em_load function needs to be
called only once for all clients. However, additional calls to
em_load and em_unload are tracked by the system so that the
extension module remains loaded until that last call to em_unload.
The typical usage for accessing an extension module is for each
client application program to first call em_load and then em_attach,
issue the needed calls to em_call, and finally call em_detach
followed by em_unload.
Alternatively, you could develop a program that runs from a single
client to load the extension module first, before any standard client
application programs have started. This special program would
perform the em_load call, and the other programs would only call
em_attach. The program would typically be invoked by an
administrator and would probably include application-specific
administration features. Otherwise, it could be your own
application server that automatically loads the application's
extension modules upon startup.
Return Values S_CATTIME S_NOT_STARTED

S_INVNULL S_OKAY
S_INVSESS S_UNREGEM
S_LONGNAME
See Also em_attach, em_unload

em_load
Example
...
short emh;
short stat;
stat = em_load("_sddlp", &emh, hSess);

printf("unable to load sddlp extension module, status = %d\n",
stat);
return -1;
}
stat = em_attach("_sddlp", &emh, hSess);
printf("unable to attach sddlp extension module, status = %d\n",
stat);
return -1;
}
...

em_unload
em_unload Unload an extension module
Syntax short em_unload (short emHandle, RDM_SESS hSess)

em_attach).
Description This function unloads an extension module after your application

has detached it with a call to em_detach. Unloading removes the
extension module from memory, making it unavailable for use. If
more than one login session had previously issued a call to
em_load, only the last one to call em_unload actually unloads the
extension module. If other sessions are still using the extension
module, a call to em_unload returns S_DUPLICATE.
Return Values S_BADEMH S_NOT_STARTED

S_DUPLICATE S_OKAY
S_INVSESS
See Also em_detach, em_load
Example
RDM_SESS hSess;
short emHandle;
/* log into server */

s_login("Velocis", "admin", "secret", &hSess);
...
/* Load and attach extension module */
em_load("MyExtMod", &emHandle, hSess);
em_attach("MyExtMod", &emHandle, hSess);
...
/* We're finished -- now detach and unload extension module */
em_detach(emHandle, hSess);
em_unload(emHandle, hSess);
...

ModCleanup
ModCleanup Clean up a session
Syntax short REXTERNAL ModCleanup (RDM_SESS hSess)
Parameters hSess [Input] The session handle of the application

detaching from the extension module.
Description This function performs session-specific cleanup after an application

has finished using the extension module. This function is called
when the application calls em_detach to discontinue use of the
module.
If the application stores persistent data in the extension module (see
ModInit), the module should always clean up (free) the data.
Failure to do this can cause memory leakage, which degrades server
performance and eventually causes the server to shut down. Your
implementation of ModCleanup should clean up everything set up
by ModInit or other extension functions.
Return Values This function may return any of the Velocis error codes, which
becomes the return value of em_detach.
See Also em_detach, em_getContext
Example
short REXTERNAL ModCleanup (
RDM_SESS hSess)
{
void **context;
GLOBALS *ctx;
context = em_getContext(hSess, emsql_id);

ctx = (GLOBALS *) *context;
d_iclose(ctx->hDb);
*context = NULL;
return S_OKAY;
}

ModDescribeFcns
ModDescribeFcns Register an extension module
Syntax void REXTERNAL ModDescribeFcns (short hMod,

unsigned short *NumFcns, EMLOADTABLE **emLoadTable,
char **loadStr)
Parameters hMod [Input] The extension module handle.

NumFcns [Output] A pointer to the number of extension
module functions defined in the load table for the
extension module. This number does not include
the ModDescribeFcns, ModInit, and ModCleanup
functions.
emLoadTable [Output] A pointer to the extension module load
table. The table defines a function address and
function identifier pair for each client-callable
function in the extension module.
loadStr [Output] A pointer to a character string that Velocis
displays in the server log when the extension
module is loaded.
Description This function supplies information about the extension module to

Velocis. It is called by Velocis after the extension module shared
library has been loaded on execution of the first client program call
to the em_load function. Alternatively, if the extension module has
been identified as an auto-load module, it is called directly by
Velocis upon startup. When your application calls em_call to access
a function in the extension module, Velocis examines emLoadTable to
find the corresponding extension module function and resolve the
call.
Return Values None
See Also em_call, em_getContext, ModInit

ModDescribeFcns
Example
short hMyApp = 0;
static char modDescr[] = "MyApp extensions V3.0";
static EMLOADTABLE emTable[] = {
{ MA_Add, 0 }
{ MA_Delete, 1 }
{ MA_Update, 2 }
{ MA_Read, 3 }
};
void REXTERNAL ModDescribeFcns (

short mod_id, /* in: module id */
unsigned short *NumFcns, /* out: num. of functions in module */
EMLOADTABLE **emLoadTable, /* out: points to emTable above */
char **fcn_descr) /* out: optional description string */
{
hMyApp = mod_id; /* save the mod_id */
*NumFcns = RLEN(emTable);
*emLoadTable = emTable;
if (fcn_descr)
*fcn_descr = modDescr;
return;
}

ModFunction
ModFunction Provide an extension module service (function) to client applications
Syntax short REXTERNAL ModFunction (PL_DATADESC *pInParamList,

PL_DATADESC *pOutParamList);
Parameters pInParamList [Input] A pointer to the input parameter values to

send to the extension module function.
pOutParamList [Output] A pointer to the output parameter values
that resulted from execution of the extension
module function.
Description This function specifies a prototype for each of your extension

module functions. The name ModFunction is replaced with your
own function name, which is specified as the first field in its
corresponding EMLOADTABLE structure entry. An extension
module function is called from the client by using the em_call
function. The extension module function can receive input
parameter values from the client and send output parameter values
back to the client. Use the parameter list (pl_) functions to put
values into and get values from these input and output parameter
lists.
Return Values User-defined
See Also em_call, ModCleanup, ModDescribeFcns, ModInit, parameter list

functions (pl_ prefix)
EMLOADTABLE (structure)

ModFunction
Example
/* ===================================================================
Envelope function for fetchBlock function
*/
short REXTERNAL EfetchBlock(
PL_DATADESC *pInParms,
PL_DATADESC *pOutParms )
{
short rv;
/* input arguments */
short bufsize;
RDM_SESS hSess;
/* output argument */
short nbytes;
void *buf;
rv = pl_get(pInParms, (void*) &bufsize);

if (rv == S_OKAY)
rv = pl_get(pInParms, (void*) &hSess);
if (rv != S_OKAY)
return DB_RPCERR;
/* Allocate the buffer. Must use rm_getMemory */

buf = rm_getMemory((unsigned short) bufsize, 0);
rv = fetchBlock(bufsize, buf, &nbytes, hSess);

if (rv == DB_OKAY) {
rv = pl_put(pOutParms, PL_OPAQUE, PL_FLAG_FREE, buf, nbytes);
if (rv == S_OKAY)
rv = pl_put(pOutParms, PL_SHORT, 0, &nbytes, 0);
if (rv != S_OKAY)
rv = DB_RPCERR;
}
return rv;
}

ModInit
ModInit Initialize an extension module
Syntax short REXTERNAL ModInit (RDM_SESS hSess)
Parameters hSess [Input] The session handle of the application

attaching to the extension module.
Description This function performs session-specific initialization of the extension

module. It is an optional function called by em_attach.
If the application needs to store persistent data in the extension
module, your implementation of ModInit may allocate a context
structure. To allow parameter list (pl_) functions to read or update
the structure, your implementation must include an em_getContext
call to obtain the pointer to this structure.
Return Values This function returns any of the Velocis error codes, which becomes
the return value of em_attach.
See Also em_getContext
Example
typedef struct {
short rec_type;
short rec_size;
short last_stat;
RDM_DB hDb;
} CTX;
...
/* =================================================================
Module initialization (per em_attach)
*/
short REXTERNAL ModInit(
RDM_SESS hSess )
{
void **ctxPtrPtr = em_getContext(hSess, ModHandle);
/* allocate the context memory */

/* NOTE: the rm_getMemory function (with tag 0) must be used to
allocate context. If the client is abnormally terminated,
Velocis uses rm_freeMemory to clean up the memory.
*/
*ctxPtrPtr = rm_cGetMemory(sizeof(CTX), 0);
((CTX *) (*ctxPtrPtr))->hDb = NO_DB;
return S_OKAY;
}

Chapter 8
Import and Export Filter Module
Functions (ief Prefix)
This chapter contains interfaces of the functions that you implement in an extension
module to create import and export filters for use in SQL schemas. With filters, you can
transfer data between Velocis SQL databases and outside sources or targets, such as
other files or Internet web pages. Filters are not available in Core databases. See
Chapter 12 of the Velocis User's Guide for more information.
With the functions in this chapter, you can create multiple import and export filters in a
module. All of the listed functions, except for the filter registration function
(iefDescribeFcns), are interfaces that you can name and define for each filter. The
iefDescribeFcns function is provided as a prototype, so you have to implement the
function. You cannot change its name, however, because only one registration function
is needed in each filter module.
Two structures are used specially with filters: an import/export filter load table and a
value descriptor. The load table structure is used to describe the functions that do the
work for a filter. To register a filter module, you need to create a load table that includes
an entry for each filter in the module. The value descriptor structure is used in filter
initialization to describe the column values that are being imported or exported through
the filter. The structures are defined as follows:
typedef struct iefloadtable {
char iefName[33]; /* The filter name */
PIEFFETCH iefFetch; /* The row-fetch function (import only) */
PIEFSTORE iefStore; /* The row-store function (export only) */
PIEFCHECK iefCheck; /* The parameter type-check function */
PIEFINIT iefInit; /* The filter initialization function */
PIEFCLEANUP iefCleanup; /* The filter cleanup function */
} IEFLOADTABLE, *PIEFLOADTABLE;
typedef struct value_descr {

char *name; /* The column name */
short type; /* The column's SQL data type */
short prec; /* The column's precision or maximum display width */
short scale; /* The column's scale (for SQL_DECIMAL data types) */
} VALUE_DESCR;
When declaring and defining these functions, you must add the REXTERNAL macro
between the function return type and the function name.
Import and Export Filter Module Functions (ief Prefix) 8-1

iefCheck
iefCheck Perform type checking on import and export filter parameters
Syntax short REXTERNAL iefCheck (HSYS hSys, short numArgs,

VALUE *args, VALUE *error)
Parameters hSys [Input] The SQL system handle associated with the
statement invoking the filter.
numArgs [Input] The number of arguments or elements in the
args array.
args [Input] A pointer to an array of VALUE entries, one
for each specified filter argument.
error [Output] A pointer to a VALUE variable to contain
error information when an error is detected.
Description This function is called by SQL when an insert statement that

invokes a filter defined in the IEF module is compiled. The function
name, iefCheck, can be any name you choose. It is associated with
a specific import or export filter name through the iefCheck field in
the IEF load table, which contains this function's address and is
returned by the iefDescribeFcns function.
The SQL system handle can be used with any of the SQL server-side
module support functions (e.g., SYSMemoryTag) to access
statement-specific information that might be needed in the function.
The arguments to the filter are contained in the args array. For type
checking, you should only verify that the correct number (numArgs)
and types (args[i].type) are specified. If an error is detected, set error-
>type to SQL_CHAR, set error->vt.cv to a static character string that
describes the error, and return SQL_ERROR. If no errors are found,
the function should return SQL_SUCCESS.
Return Values SQL_ERROR

SQL_SUCCESS
See Also iefCleanup, iefDescribeFcns, iefFetch, iefInit, iefStore

VALUE (structure)

iefCheck
Example
/* =====================================================================
Type-checking for (up to) one date argument
*/
short REXTERNAL bbCheck (
HSYS hSys, /* in: system handle */
short noargs, /* in: number of arguments to function */
VALUE *args, /* in: array of arguments */
VALUE *error) /* out: container for error value */
{
short status = SQL_SUCCESS;
if (noargs != 1 || args->type != SQL_DATE ) {

error->type = SQL_CHAR;
error->vt.cv = "usage: bbscores(date 'YYYY-MM-DD')";
status = SQL_ERROR;
}
return status;
}

iefCleanup
iefCleanup Clean up after IEF execution
Syntax void REXTERNAL iefCleanup (HSYS hSys, void **cxtp)
statement that is invoking the filter.
ctxp [Input] A pointer to the IEF statement context
pointer.
Description SQL calls this function after complete execution of an insert

statement that invokes an IEF module filter. The function name,
iefCleanup, can be any name you choose. It is associated with a
specific import or export filter name through the iefCleanup field in
the IEF load table, which contains the function's address and is
returned by the iefDescribeFcns function.
The hSys parameter can be used with any of the SQL server-side
The cxtp parameter points to the location.
Return Values None
See Also iefCheck, iefDescribeFcns, iefFetch, iefInit, iefStore

VALUE (structure)
Example
/* =====================================================================
Filter cleanup
*/
void REXTERNAL bbCleanup (
void **cxtp) /* in: statement context pointer */
{
BB_CTX *ctx = *cxtp;
RM_MEMTAG mTag;
SYSMemoryTag(hSys, &mTag);
rm_freeMemory(ctx->webpg, mTag);
rm_freeMemory(ctx, mTag);
*cxtp = NULL;
}

iefDescribeFcns
iefDescribeFcns Describe the import or export filters defined in this IEF module
Syntax void REXTERNAL iefDescribeFcns (unsigned short *NumFilters,

PIEFLOADTABLE *IEFLoadTable, char **iefDescr)
Parameters NumFilters [Output] A pointer to the variable into which the

number of filters must be returned.
IEFLoadTable [Output] A pointer into which the address of the
IEFLOADTABLE array must be returned.
iefDescr [Output] A pointer into which a pointer to a IEF
module string can be returned.

invokes a filter defined in the IEF module is compiled/executed.
There is only one per IEF module and the function must be named
iefDescribeFcns. The function must return a pointer to the
IEFLOADTABLE array containing an entry for each filter defined in
the IEF module. Each entry in the IEF load table contains the filter
name and the addresses of the iefFetch, iefStore, iefCheck, iefInit,
and iefCleanup functions that implement each filter defined in the
module.
The following example shows the iefDescribeFcns implementation
for the ASCII and Unicode file filters provided with Velocis. Note
from the example that two header files, sqlrds.h and sqlsys.h, are
included. The sqlsys.h header file includes the IEF type definitions
(e.g., IEFFETCH and IEFLOADTABLE).
Return Values None
See Also iefCheck, iefCleanup, iefFetch, iefInit, iefStore

IEFLOADTABLE (structure)

iefDescribeFcns
Example
#include "sqlrds.h"
#include "sqlsys.h"
/* user defined filters for ascii files */

IEFCHECK ascCheck;
IEFFETCH ascFetch;
IEFSTORE ascStore;
IEFINIT ascInit;
IEFCLEANUP ascCleanup;
IEFCHECK uniCheck;
IEFFETCH uniFetch;
IEFSTORE uniStore;
IEFINIT uniInit;
IEFCLEANUP uniCleanup;
static IEFLOADTABLE IefTable[] = {

/* filter name FETCH STORE CHECK INIT CLEANUP */
/* --------------- --------- --------- --------- -------- -------- */
{"s_ascii_filter", ascFetch, ascStore, ascCheck, ascInit, ascCleanup},
{"s_unicode_filter",uniFetch, uniStore, uniCheck, uniInit, uniCleanup}
};
/* =====================================================================
Ascii/Unicode file import/export filters
*/
void REXTERNAL iefDescribeFcns (
unsigned short *NumFltrs, /* out: number of filters in module */
IEFLOADTABLE **pIEFLoadTable, /* out: points to IefTable above */
char **modDesc) /* out: optional description string */
{
*NumFltrs = sizeof(IefTable)/sizeof(IEFLOADTABLE);
*pIEFLoadTable = IefTable;
*modDescr = "built-in ascii/unicode file filters";
}

iefFetch
iefFetch Fetch the next row of values from an import filter
Syntax short REXTERNAL iefFetch (HSYS hSys, void **cxtp, short numVals,
VALUE *vals, VALUE *error)
statement that is invoking the filter.
ctxp [Input] A pointer to IEF statement context pointer.
numVals [Input] The number of column values or elements
in the vals array.
vals [Input/Output] A pointer to an array of VALUE
entries, one for each column value to be returned.
error [Output] A pointer to a variable containing
iefFetch, error information when an error is
detected.

invokes the filter is being executed to fetch the next row of column
values from the filter. The function name, iefFetch, can be any
name you choose. It is associated with a specific import or export
filter name through the iefFetch field in the IEF load table, which
contains the function's address and is returned by the
iefDescribeFcns function.
The column values from the filter are to be returned in the vals
array. The values must be returned in the proper format for the
data type specified for each vals entry (e.g., vals[0].type).
The function must return SQL_NO_DATA_FOUND, when there are
no more rows available from the filter source.
If an error is detected, set error->type to SQL_CHAR, set error->vt.cv
to a static character string that describes the error, and return
SQL_ERROR. If no errors are found, the function should return
SQL_SUCCESS.

SQL_NO_DATA_FOUND
SQL_SUCCESS

iefFetch
See Also iefCheck, iefCleanup, iefDescribeFcns, iefInit, iefStore

VALUE (structure)
Example
/* =====================================================================
Import filter
*/
short REXTERNAL bbFetch (
void **cxtp, /* in: statement context pointer */
short novals, /* in: number of values to fetch */
VALUE *vals, /* in: array of value containers */
{
BB_CTX *ctx = *cxtp;
vals[0].vt.tsv.date = ctx->game_date;
status = FetchNextGame(ctx);
if ( status == SQL_SUCCESS ) {
vals[1].vt.cv = ctx->visitor;
vals[2].vt.cv = ctx->home;
vals[3].vt.sv = ctx->v_runs;
vals[4].vt.sv = ctx->h_runs;
}
return status;
}

iefInit
iefInit Initialize import and export filter processing
Syntax short REXTERNAL iefInit (HSYS hSys, void **cxtp, short type,
short numArgs, VALUE *args, short numVals,
VALUE_DESCR *vdescr, VALUE *error)
ctxp [Input] A pointer to the IEF statement context
pointer.
type [Input] Identifies the filter type (SQL_IMPORT or
SQL_EXPORT).
numArgs [Input] The number of arguments or elements in
args array.
args [Input] A pointer to an array of VALUE entries, one
for each specified filter argument.
numVals [Input] The number of column description entries in
the vdescr array.
vdescr [Input] A pointer to an array of column description
entries.
error [Output] A pointer to a VALUE variable containing

invokes a filter defined in the IEF module is executed. The function
name, iefInit, can be any name you choose. It is associated with a
specific import or export filter name through the iefInit field in the
IEF load table, which contains the function's address and is returned
by the iefDescribeFcns function.
The arguments to the filter are contained in the args array. The
vdescr array contains type and length information for each column
value to be processed by the filter.
Typically, you will use this function to allocate a statement context
buffer containing data to be used by the filter. The pointer to the
allocated context buffer should be assigned to *cxtp. A pointer to
this same location is passed into the other IEF function associated

iefInit
with the filter, allowing access to the filter's statement context

information. Note that this function is called after iefCheck.
Function iefCheck is called when the statement is compiled; iefInit
is called when the statement is executed.
SQL_ERROR. If no errors are found, the function should return
SQL_SUCCESS.

SQL_SUCCESS
See Also iefCheck, iefCleanup, iefDescribeFcns, iefFetch, iefStore

VALUE, VALUE_DESCR (structures)

iefInit
Example
/* =====================================================================
Filter initialization
*/
short REXTERNAL bbInit (
short type, /* in: SQL_IMPORT / SQL_EXPORT */
short *novals, /* in/out: number of value */
VALUE_DESCR **vdescr, /* in/out: value description array */
{
RDM_DB hDb;
RM_MEMTAG mTag;
BB_CTX *ctx;
char uri[30];
DATE_STRUCT dsv;
/* allocate context & web page buffer*/

ctx = *cxtp = rm_cGetMemory(sizeof(BB_CTX), mTag);
ctx->webpg = rm_getMemory(MAX_WEBPG_SZ, mTag);
ctx->pNext = ctx->webpg;
ctx->game_date = args->vt.tsv.date;
/* make sure this date's games are not already in database */

SYSDBHandle(hSys, "mlbgames", &hDb);
if ( d_keyfind(GAME_GAME_DATES, &ctx->game_date, hDb) == S_OKAY ) {
error->type = SQL_CHAR;
error->vt.cv = "this date's games have already been loaded";
return SQL_ERROR;
}
VALUnpackDate(&ctx->game_date, &dsv);
/* form uri to get scores for spec'd date */

sprintf(uri, "/mlb/%4d/%02d%02d%02d/sco.html",
dsv.year, dsv.year%100, dsv.month, dsv.day );
/* fetch web page */

status = FetchWebPage(ctx, HostServerName, uri, error);
return status;
}

iefStore
iefStore Store the next row of values in an export filter
Syntax short REXTERNAL iefStore (HSYS hSys, void **cxtp, short numVals,
VALUE *vals, VALUE *error)
ctxp [Input] A pointer to IEF statement context pointer.
numVals [Input] The number of column values to store.
vals [Input/Output] A pointer to an array of VALUE
entries, one for each column value to be stored.
error [Output] A pointer to a VALUE variable containing

invokes a filter defined in the IEF module is being executed to store
the next row of column values in the export filter. The function
name, iefStore, can be any name you choose. It is associated with a
specific import or export filter name through the iefStore field in the
IEF load table, which contains the function's address and is returned
by the iefDescribeFcns function.
The column values exported through the filter are contained in the
vals array.
SQL_ERROR. If no errors are found, the function will return
SQL_SUCCESS.

SQL_NO_DATA_FOUND
SQL_SUCCESS
See Also iefCheck, iefCleanup, iefDescribeFcns, iefFetch, iefInit

VALUE (structure)

iefStore
Example
/* =====================================================================
ASCII Export filter
*/
short REXTERNAL ascStore (
short novals, /* in: number of values to store */
VALUE *vals, /* in: array of value containers */
{
ASC_CTX *ctx = *cxtp;

char *cp;
short i, quote;
for (i = 0; i < novals; ++i) {

switch (vals[i].type) {
case SQL_CHAR:
case SQL_VARCHAR:
case SQL_DATE:
case SQL_TIME:
case SQL_TIMESTAMP: quote = 1; break;
default: quote = 0; break;
}
if (vals[i].type == SQL_NOVAL || vals[i].type == SQL_NULL ) {
if (i < novals - 1)
PutChar(ctx->delim, ctx);
continue;
}
ConvertToString(ctx, &vals[i]);
cp = ctx->buf;
if (quote)
PutChar('"', ctx);
while (*cp) {
if ( *cp == '"' || *cp == '\\' )
PutChar('\\', ctx);
PutChar(*cp++, ctx);
}
if (quote)
PutChar('"', ctx);
if (i < novals - 1)
PutChar(ctx->delim, ctx);
}
PutChar('\n', ctx);
return SQL_SUCCESS;
}

Chapter 9
Parameter List Functions (pl_ Prefix)
This chapter includes descriptions of the Velocis parameter list manipulation functions.
These functions are used to package data that will be sent between Velocis client
applications and Velocis server extension module functions. The Velocis Remote
Procedure Call (RPC) subsystem automatically converts the data being sent between
disparate systems by using the Velocis Data Portability Layer (DPL). Thus, both the
client application code and the server code process data in the format native to the
particular hardware platform on which each is running. No DPL conversion is required
when the client and server computers have the same hardware profile.
The data types handled by these functions map directly into Core DDL data types. An
SQL-specific data type must be manipulated based on its Core representation. See
Chapter 6 of the Velocis User’s Guide for detailed information regarding Core DDL
representation of SQL data types.
The pl_ functions use a PL_DATADESC data type, which is a structure that serves as a
handle to a single packet of input or output parameters. Once the handle is allocated,
parameters are added to a parameter list packet one at a time. You do not need to access
the structure members of the handle. If you are packaging data structures, you also need
to use the PL_ITEM data type; for information on this structure, see Chapter 18 of this
manual.
For more information about these functions, see Chapter 11 of the Velocis User’s Guide.
Parameter List Functions (pl_ Prefix) 9-1

pl_alloc
pl_alloc Allocate a parameter list
Syntax PL_DATADESC *pl_alloc (void)
Parameters None
Description This function allocates a handle to the data descriptor for a

parameter list. This handle is used in subsequent calls to parameter
list functions that provide parameter data to send between a client
and a server.
For a client application in which em_call is called, the input
parameter needs to be allocated, but it will be freed by the system in
em_call. The output parameter list will be allocated by em_call, but
it needs to be freed by the client when it is no longer needed.
For an extension module, the Velocis server allocates both the input
and output parameter lists, and the server frees these lists when the
extension module has finished processing.
To place simple scalar and array parameters in the allocated
parameter list, use pl_put or, to place multiple parameters at once,
use pl_printf. To place structure parameters in the list, use
pl_putStruct.
Values for output parameters can be retrieved by using pl_get.
Return Values A pointer to the structure containing the allocated parameter list
(NULL if not enough memory to allocate)
See Also pl_free

pl_alloc
Example
#include "tims.h"
PL_DATADESC *inParm; /* Input parameter list */

struct author author; /* The author record */
...
/* First allocate and initialize the input parameter list */

inParm = pl_alloc();
if (inParm == NULL) {
printf("ERROR: Insufficient memory to create input param list\n");
return 1;
}
/* Now place the AUTHOR record into the input parameter list */
pl_put(inParm, PL_ASCIZ, 0, (void *)author.name, 0);

pl_count
pl_count Count the number of items in a parameter list
Syntax long pl_count (PL_DATADESC *ParmList)
Parameters ParmList [Input] A pointer to the structure containing the

parameter list.
Description This function returns the total number of parameters in the specified
parameter list.
Return Values The count of parameters in the parameter list

pl_del
pl_del Delete the current data item from a parameter list
Syntax void pl_del (PL_DATADESC *ParmList)

parameter list.
Description This function deletes the current data item in a parameter list. The
current data item is normally the most recently added parameter,
but you can use pl_seek to make another item the current one.
Return Values None
See Also pl_seek

pl_free
pl_free Free a parameter list
Syntax void pl_free (PL_DATADESC *ParmList)

parameter list to free.
Description This function frees an input parameter list allocated by pl_alloc or

an output parameter list returned from em_call.
Once an input parameter list is allocated with a call to pl_alloc, you
normally free it by calling em_call. In situations where em_call is
not called, you must include a call to pl_free to free the packet. (For
example, this situation might occur if an error was detected.)
With output parameter lists, call pl_free to free a list returned from
em_call when you have finished extracting the output parameter
values from the packet. Do not free the output parameter list
prematurely. The list contains data structures, arrays, and opaque
data that are referenced by a pointer following a call to pl_get
(pl_get retrieves the next parameter in the list). If you free this list
before you are finished using the data, a memory violation may
occur.
Return Values None
See Also em_call, pl_alloc, pl_get

pl_free
Example
#include "tims.h"
short con_author (
author Author, /* Author to create and connect */
char *prev_author, /* Will hold previous author name */
short hSvc, /* Extension module handle */
RDM_DB hDb, /* Database handle of tims */
RDM_SESS hSess) /* Our session with the server */
{
/* Example assumes extension module has been loaded and attached */
PL_DATADESC *inParm; /* I/P Parm list */
PL_DATADESC *outParm; /* O/P Parm List */
char *pPrev; /* ptr to prev author in PL packet */
short retcode; /* Return status from extension module */
short stat; /* Return code from rpc calls */
pl_put(inParm, PL_ULONG, 0, &hDb, 0);
pl_put(inParm, PL_ASCIZ, 0, Author.name, 0);
stat = em_call(hSvc, CON_AUTH, inParm, &outParm, &retcode, hSess);
/* fetch pointer to prev author name */

pl_get(outParm, &pPrev);
/* retrieve prev author name before freeing outParm */

strcpy(prev_author, pPrev);
pl_free(outParm);
return 0;
}

pl_get
pl_get Get the next parameter from a parameter list
Syntax short pl_get (PL_DATADESC *ParmList, void *dest)

parameter list.
dest [Output] A pointer to the value of the next
parameter.
Description This function retrieves a parameter from the specified parameter

list. The first call to this function returns the parameter at the
beginning of the list, and successive calls continue to extract
parameters until the end of the list is reached. Upon reaching the
end of the parameter list, the function returns S_PARMEND.
The pl_get function copies the parameter to the specified location if
it is retrieving a scalar data type (for example, short, int, or long).
Otherwise, it copies a pointer to the structure, array, or opaque data
associated with the parameter. Calling pl_free to deallocate the
parameter list automatically frees the memory occupied by the
structure, array, or opaque data.
Note: To extract information about a parameter without extracting

the parameter itself, call pl_peek.

S_PARMEND
S_PARMINTERR
See Also pl_free, pl_peek, pl_put

pl_get
Example
#include "tims.h"
short REXTERNAL con_author(

PL_DATADESC *inParm, /* Will contain the hSess and author record */
PL_DATADESC *outParm) /* Will contain previous author record */
{
RDM_SESS hSess; /* Copy of client session */
char *newAuthor; /* Will point to new author record */
char *prevAuthor; /* Will point to previous author */
short stat; /* Return status codes */
/* First extract the input parameters */

stat = pl_get(inParm, &hSess);
if (stat = S_RPCENDOFPARMS)
return EM_NODATA; /* Client forgot to send data */
pl_get(inParm, &newAuthor);
/* Now create this author record and connect it */

if ((stat = d_fillnew(AUTHOR, newAuthor, hSess)) != S_OKAY)
return EM_FILLERR; /* fillnew failed */
/* Assume locks are not needed */

d_connect(AUTHOR_LIST, hSess);
/* Now extract previous author and return it */

prevAuthor = rm_getMemory(sizeof(AUTHOR), 0); /* use untagged mem */
if (prevAuthor == NULL)
return EM_NOMEM; /* Ran out of memory */
if (d_findpm(AUTHOR_LIST, hSess) == S_OKAY)
d_recread(AUTHOR, (void *)prevAuthor, hSess);
else {
/* There is no previous author */
prevAuthor[0] = ‘\0’;
}
pl_put(outParm, PL_ASCIZ, PL_FLAG_FREE, prevAuthor, 0);
return 0; /* We’re finished - Return */
}

pl_peek
pl_peek Extract information about the next parameter
Syntax void pl_peek (PL_DATADESC *ParmList, PL_DATATYPE *type,

PL_ITEM **structDesc, unsigned short *flags,
unsigned long *size)

parameter list.
type [Output] A pointer to the data type indicator for the
parameter. See the PL_ITEM structure for the list
of indicators that can be returned. If you do not
need this value, specify NULL.
structDesc [Output] A pointer to an array of PL_ITEM
structures that defines the structure of the data. If
type is not equal to PL_STRUCT, then structDesc is
assigned NULL.
flags [Output] A pointer to a bit map of returned
parameter flags. Any combination of the flags that
are described below can be returned. If you do not
need this value, specify NULL.
PL_FLAG_ARRAY
The item is an array of elements.
PL_FLAG_FREE
The item must be freed by Velocis, because the item
was previously allocated using the Velocis resource
memory allocation functions (rm_ prefix) with a
NULL tag.
PL_FLAG_NULL
The item is equal to NULL.
size [Output] A pointer to the size, in bytes, returned for
the parameter. If you do not need this value,
specify NULL.
Description This function extracts information about the next parameter in the
specified parameter list without actually retrieving the parameter
itself.
The function retrieves three things associated with the parameter
item: an indicator of the data type, the values of the data modifier
flags, and a size value, in bytes. If the parameter is opaque, the size
returned is the amount of bytes in the data. If the parameter is an

pl_peek
array, the size is the number of elements in the array. Otherwise,

the size value is unimportant.
Return Values None
See Also pl_get, pl_put
Example
/* ====================================================================
Envelope function for d_crwrite
*/
short REXTERNAL Ed_crwrite(
{
short rc;
long *data;
unsigned short flags;
long field;
RDM_DB hDb;
PL_DATATYPE type;
char *funcName = "d_crwrite";
UNREF_PARM(outParms)
if ((rc = pl_get(inParms, &field)) != S_OKAY)

return rc;
pl_peek(inParms, &type, NULL, &flags, NULL);

if (type != PL_LONG || !(flags & PL_FLAG_ARRAY))
return S_RPCPARMMISMATCH;
if ((rc = pl_get(inParms, &data)) != S_OKAY)

return rc;
if ((rc = pl_get(inParms, &hDb)) != S_OKAY)

return d_crwrite(field, data, hDb);

}

pl_printf
pl_printf Put multiple parameters in a parameter list
Syntax short pl_printf (PL_DATADESC *ParmList, char *format, ...)

parameter list.
format [Input] A C printf-like specifier string based on
ANSI standard data types. Possible data type codes
are:
c char
C double-byte character
hd short
hu unsigned short
d int
u unsigned int
ld long
lu unsigned long
f double
s string (char *)
S double-byte string pointer
a database address pointer (DB_ADDR)
... [Input] A list of one or more parameter values.
Description This function puts one or more parameters in a parameter list. It

places parameters by performing one or more pl_put calls, using a
specifier string to represent the parameter types. The parameters
themselves follow the format string as a variable-length argument
list. All parameters will be put into the specified parameter list.
Each parameter passed to pl_printf is represented in the following
format.
%[*|digits]type
Each parameter description begins with a percent sign ("%"). If an

asterisk or number appears before the type, the parameter is
assumed to be an array. A preceding asterisk means that the next
argument in the variable list is the number of elements in the array
and is followed by the actual array data. A preceding number
means that it is the number of elements.

pl_printf
Using an asterisk or a number before a string parameter ("s" or "S")

converts the string to an array of characters or double-byte
characters ("c" or "C"). String parameters without specified lengths
use the strlen and wcslen functions to get the size.
The function ignores white space separating entries in the specifier
string. See the Example section below for an example of the way
this function interprets parameters.
Return Values S_RPCINVDATATYPE
See Also pl_put, pl_putStruct
Example
DB_ADDR dba;
short set;
char flags[2], msg[20];
RDM_SESS hSess;
strcpy(msg, "Update");
...
pl_printf(pInParms, "%a %hd %*s %s %hu",

&dba, set, 2, flags, msg, hSess);

pl_put
pl_put Put a parameter in a parameter list
Syntax short pl_put (PL_DATADESC *ParmList, PL_DATATYPE type,

unsigned short flags, const void *data, unsigned long count)

parameter list.
type [Input] The data type indicator for the parameter.
Specify one of these values:
PL_CHAR ASCII character
PL_UCHAR Unsigned, ASCII character
PL_WCHAR Unicode character
PL_SHORT Short integer
PL_USHORT Unsigned, short integer
PL_INT Integer
PL_UINT Unsigned integer
PL_LONG Long integer
PL_ULONG Unsigned, long integer
PL_FLOAT Single-precision, floating-point number
PL_DOUBLE Double-precision, floating-point number
PL_DB_ADDR Database address
PL_ASCIZ Null-terminated, ASCII character string
PL_WSCZ Null-terminated, Unicode character string
PL_OPAQUE Binary or unstructured data
flags [Input] A bit map of data modifiers associated with
this parameter. Specify any combination of these
indicators:
PL_FLAG_ARRAY
The item is an array of elements. (For bound
parameters, this is the only flag that should ever be
used.)
PL_FLAG_FREE
NULL tag. Specify this flag only from an extension
module call that does not have the chance to free the
data after it returns.
PL_FLAG_NULL
data [Input] A pointer to the parameter data to put in the
parameter list.

pl_put
count [Input] Either the total number of elements of an

array parameter or the size, in bytes, of the data for
an opaque parameter. If the parameter is not an
array and is not opaque, this value is ignored. For
multi-dimensional arrays, specify the product of the
dimension sizes.
Description This function adds a simple parameter to the specified parameter

list in first-in, first-out (FIFO) order. To add a structure parameter,
you must use the pl_putStruct function instead.
The way that parameter data is handled depends on the data type.
If the parameter data is scalar, the function stores a copy of the data.
If the data is opaque (when type is equal to PL_OPAQUE), is an
array (when flags has PL_FLAG_ARRAY set), or is a string (type is
equal to PL_ASCIZ or PL_WSCZ), the function stores a pointer to
the data. (For opaque data and arrays, you must also specify in
count the size of the opaque data or the number of array elements,
respectively.) When your application calls em_call to pass the input
parameter list to the module, the function copies the data indicated
by the pointer.
Note: Avoid reuse of the same buffer in subsequent calls to pl_put.

The data is not copied and cannot be replaced after pl_put returns.
When pl_put is called from an extension module, arrays must be

static or allocated. Stack-based (automatic) arrays cannot be used.
If the extension module allocates an array, it must use
rm_getMemory with a NULL tag to get the memory, and specify the
PL_FLAG_FREE modifier as one of the flags to pl_put. The
memory will be freed by the system after the parameter packet has
been sent.
Caution: Specifying PL_FLAG_FREE is only necessary from an

extension module. Specifying this flag from the client can cause
data corruption.
Return Values S_RPCINVDATATYPE
See Also em_call, pl_printf, pl_putStruct

pl_put
Example
#include "tims.h"
short con_author (
author Author, /* Author to create and connect */
char *prev_author, /* Will hold previous author name */
short hSvc, /* Extension module handle */
RDM_DB hDb, /* Database handle of tims */
RDM_SESS hSess) /* Our session with the server */
{
/* Example assumes extension module has been loaded and attached */
PL_DATADESC *inParm; /* I/P Parm list */
PL_DATADESC *outParm; /* O/P Parm List */
short retcode; /* Return status from extension module */
short stat; /* Return code from rpc calls */
pl_put(inParm, PL_ULONG, 0, &hDb, 0);
pl_put(inParm, PL_ASCIZ, 0, Author.name, 0);
stat = em_call(hSvc, CON_AUTH, inParm, &outParm, &retcode, hSess);
pl_get(outParm, prev_author);
pl_free(outParm);
return 0;
}

pl_putStruct
pl_putStruct Put a structure in a parameter list
Syntax short pl_putStruct (PL_DATADESC *ParmList, PL_ITEM *DataItem,

unsigned short flags, const void *data, unsigned long elems)

parameter list.
DataItem [Input] A pointer to an array of structures that
describes the data items in the structure pointed to
by data.
flags [Input] A bit map of data modifiers associated with
this parameter. Specify any combination of these
indicators:
PL_FLAG_ARRAY
The item is an array of elements.
PL_FLAG_FREE
NULL tag. Specify this flag only from an extension
module call that does not have the chance to free the
data after it returns.
PL_FLAG_NULL
data [Input] A pointer to the value of the structure.
elems [Input] The number of array elements in the
structure parameter. For a multi-dimensional array,
multiply the size of each dimension and specify that
number. If the parameter is not an array (i.e., the
array flag is not set), this value is ignored.
Description This function places a structure in a parameter list and stores a

pointer to the structure data. Your application only needs to call
this function once to place an entire structure in the parameter list.
The structure that goes into the parameter list must be expressed as
an array of PL_ITEM structures. The definition of the PL_ITEM
structure appears below. A full description can be found in
Chapter 18 of this manual.

pl_putStruct
typedef struct {
unsigned long size;
PL_DATATYPE type;
} PL_ITEM;
In this structure, the size field contains the number of array

elements, if the parameter is an array; otherwise, it is ignored. The
type field indicates the data type of the parameter item. (For
example, to indicate a long integer field, specify PL_LONG in this
field.) See the PL_ITEM structure for the list of values that can be
specified. The flags field contains a bit map of data modifier flags.
(For example, to indicate that the parameter is an array, specify
PL_FLAG_ARRAY as part of the bitmap.)
Note: The flags and elems parameters in this function apply to the
entire structure being placed in the parameter list. As to their
counterparts in the PL_ITEM structure, the flags and size fields, each
field applies only to its specific item in the PL_ITEM structure
element.
The array of PL_ITEM structures must contain entries for each field
of the structure that is being placed in the parameter list, in the
order in which the fields are declared. Items that are themselves
structures are indicated by the PL_STRUCT data type indicator.
(Structures can be nested within other structures in the parameter
item.) The first and last entries in the array of data items must have
the type field equal to PL_STRUCT. The first entry must have a flags
field in which PL_FLAG_OPEN is set, and the last entry must have a
flags field in which PL_FLAG_CLOSE is set. The items that
constitute the structure are specified between these two entries.
Note: The data type indicator PL_STRUCT and the data modifier
flags PL_FLAG_OPEN and PL_FLAG_CLOSE can only be specified
within a PL_ITEM structure. They cannot be specified directly as
arguments in pl_putStruct or any other parameter list function.
Return Values S_INVPARM S_NOMEMORY
See Also pl_put

PL_ITEM (structure)

pl_putStruct
Example
struct userinf {
char username[SIZEOF_USERNAME];
char userpass[SIZEOF_USERPASS];
char userpriv;
};
typedef struct {
struct userinf us;
char usdevice[SIZEOF_DEVNAME];
} USERINF_CHG;
PL_ITEM userinf_chg_items[8] = {
{0, PL_STRUCT, PL_FLAG_OPEN}, /*start USERINF_CHG */
{0, PL_STRUCT, PL_FLAG_OPEN}, /*start struct userinf*/
{SIZEOF_USERNAME, PL_CHAR, PL_FLAG_ARRAY},
{SIZEOF_USERPASS, PL_CHAR, PL_FLAG_ARRAY},
{0, PL_CHAR, 0},
{0, PL_STRUCT, PL_FLAG_CLOSE},/*end struct userinf*/
{SIZEOF_DEVNAME, PL_CHAR, PL_FLAG_ARRAY},
{0, PL_STRUCT, PL_FLAG_CLOSE} /*end USERINF_CHG*/
};
/* This is part of an extension module function. Note that the */

/* structure is allocated (and must not be stack-based). */
/* Therefore, the PL_FLAG_FREE flag is passed into pl_putStruct. */
...
USERINF_CHG *pUserInfo;
pUserInfo = rm_getMemory(sizeof(USERINF_CHG), 0);

sFcnRetCode = s_userGet( "Anita", pUserInfo, hSess );
/* send structure to the client */

pl_putStruct(outParms, userinf_chg_items,
PL_FLAG_FREE, pUserInfo, 0);

pl_seek
pl_seek Change the current parameter in a parameter list
Syntax short pl_seek (PL_DATADESC *ParmList, long pos, int origin)

parameter list.
pos [Input] The position relative to origin that should be
set as the current parameter. A positive number
means further forward in the list, and a negative
number means further back in the list.
origin [Input] The location from which to start. This uses
the same values that the C function seek does. The
values are as follows.
SEEK_SET
Go to location pos offset from the beginning of the
parameter list.
SEEK_CUR
Go to location pos offset from the current location in
the parameter list.
SEEK_END
Go to location pos offset from the end of the
parameter list.
Description This function allows parameter lists to be accessed in a non-

sequential manner. Using this function, parameter lists can be
generated out of order. The function can also be used in conjunction
with pl_del to remove a parameter after it has been added.
Return Values S_PARMINTERR
See Also pl_del, pl_get, pl_put

pl_seek
Example
typedef struct {
PL_DATAVAL type;
void *data;
} PARM_INFO;
/* send a bunch of scalar types to the extension module. */

short send_misc(
PARM_INFO *parmInfo,
short hSvc,
RDM_SESS hSess)
{
short i = 0;
short stat;
short retcode;
PL_DATADESC *inParm;
while (parmInfo[i].data) {
pl_put(inParm, parmInfo[i].type, 0, parmInfo[i].data, 0);
i++;
}
pl_seek(inParm, 0, SEEK_SET);
pl_put(inParm, PL_SHORT, 0, &i, 0);
stat = em_call(hSvc, SEND_MISC, inParm, NULL, &retcode, hSess);

if (stat != S_OKAY) {
printf("Failed calling SEND_MISC, error = %hd\n", stat);
return stat;
}
return retcode;
}

Chapter 10
Engine Resource Manager Functions
(rm_ Prefix)
The Velocis Resource Manager (RM) provides a rich, platform-independent function
interface to sophisticated operating system tasks, such as thread management,
concurrency control, message queuing, dynamic memory allocation, and file
management. All of the RM functions are designed to operate in a single-process,
multiple-thread application environment.
This chapter contains detailed descriptions of the Velocis RM functions. All of these
functions can be called from the server, but only some of them can be called from the
client. Here is a detailed breakdown of where the functions can be used.
Table 10-1. Locations Where Certain Resource Manager Functions Can Be Called
Callable Functions From the Server Only Callable Functions From both Client and Server
rm_allocPool rm_resetTag rm_cExtendMemory rm_fileStreamPuts
rm_allocTag rm_sleep rm_cGetMemory rm_fileStreamRewind
rm_cleanup rm_startup rm_extendMemory rm_fileSync
rm_createTag rm_syncCreate rm_fileClose rm_fileValidate
rm_filePrintf rm_syncDelete rm_fileCopy rm_fileWrite
rm_fileSeekRead rm_syncDisableQ rm_fileLength rm_freeMemory
rm_fileSeekWrite rm_syncEnableQ rm_fileMove rm_getenv
rm_freeTagMemory rm_syncEnterExcl rm_fileOpen rm_getLocalEnv
rm_getFromPool rm_syncExitExcl rm_filePosition rm_getMemory
rm_log rm_syncReceiveQ rm_fileRead rm_iniGet
rm_memoryAllocated rm_syncResume rm_fileRemove rm_iniGetPrivate
rm_memoryAvail rm_syncSendQ rm_fileRename rm_iniSet
rm_putInPool rm_syncStart rm_fileSeek rm_iniSetPrivate
rm_queueCreate rm_syncWait rm_fileStreamClose rm_putLocalEnv
rm_queueDelete rm_syncWaitQ rm_fileStreamGetLine rm_Strdup
rm_queuePurge rm_threadBegin rm_fileStreamGets rm_zFreeMemory
rm_queueRead rm_threadEnd rm_fileStreamOpen
rm_queueWrite rm_zFreePool
Engine Resource Manager Functions (rm_ Prefix) 10-1

rm_allocPool
rm_allocPool Allocate a dynamic memory pool handle
Syntax RM_POOL *rm_allocPool (RM_MEMTAG tag, short static_size,

char *semName)
Parameters tag [Input] The memory tag to use when allocating a

new pool buffer.
static_size [Input] A flag indicating whether buffers allocated
from this pool will all be the same size. To require
buffers to be the same size, specify a nonzero value.
To allow buffers of varying size, specify 0.
semName [Input] A string containing the name of a mutex
semaphore that will be created and used to serialize
access to the pool. If synchronization is not needed,
specify NULL.
Description This function is used to allocate a dynamic memory pool handle.

Memory pools minimize the overhead associated with allocating and
freeing heavily used, but short-lived, buffers. Instead of freeing the
memory associated with a buffer, it can be put into a pool for reuse
the next time a buffer of the same type is needed. Although a pool
can contain buffers of varying size, it is more efficient for the buffers
in a pool to be the same size.
If calls to rm_putInPool and rm_getFromPool using this pool will be
made from separate threads, you must specify the name of a mutex
semaphore that will be created and used for serializing access to the
pool. Otherwise, no semaphore name should be specified.
Return Values The pool handle pointer
See Also rm_getFromPool, rm_putInPool, rm_zFreePool
Example
RM_POOL *qPool;
...
/* allocate pool for queue messages */

qPool = rm_allocPool(mTag, 1, "qPool");

rm_allocTag
rm_allocTag Allocate a dynamic memory tag
Syntax RM_MEMTAG rm_allocTag (int *jb, long segsz, short flags)
Parameters jb [Input] A pointer to a jump buffer assigned by an

earlier call to setjmp. The jump buffer is the target
of a longjmp call if the server runs out of memory.
If you do not want to use a jump buffer, specify
NULL.
segsz [Input] The memory segment size. Specify 0 to use
the default segment size (8,192).
flags [Input] Tag allocation flags. Possible values are:
RM_NOSEM
No multithreading protection.
RM_USESEM
Semaphore protect the tag. Use when the tag is
referenced from multiple threads.
Description This function is used in an extension module to return a memory tag

that can be used in other resource manager functions to allocate or
free memory.
Return Values A memory tag to the extension module
See Also rm_cGetMemory, rm_freeMemory, rm_freeTagMemory,

rm_getMemory, rm_resetTag
Example
short REXTERNAL ModInit (
RDM_SESS hSess) /* in: RDM session id */
{
void **context;
EM_CONTEXT *ctx;
context = emGetContext(hSess, emsql_id);

ctx = *context = rm_getMemory(sizeof(EM_CONTEXT), 0);
ctx->memTag = rm_allocTag(NULL, 0, 0L);
SQLAllocEnv(&ctx->hEnv);
SQLAllocConnect(ctx->hEnv, &ctx->hDbc);

rm_cExtendMemory
rm_cExtendMemory Extend or reallocate a memory block, and clear the new portion
Syntax void *rm_cExtendMemory (void *ptr, size_t newsize,

RM_MEMTAG tag)
Parameters ptr [Input] A pointer to the currently allocated block to

be extended. If the pointer is NULL, the function
simply calls rm_cGetMemory.
newsize [Input] The new size, in bytes, of the memory block.
tag [Input] The memory tag. To use a default system
tag, specify NULL.
Description This function extends the previously allocated block of memory to a

specified length and clears the contents of the any additional section
in the block. The memory tag must be the same one used in the
original memory allocation of ptr.
If the new block size is larger than the original size, Velocis attempts
to extend the block in place. If in-place extension is not possible,
Velocis allocates a new block, copies in the data from the old block,
and clears the remaining portion of the block.
The new size can be smaller than the original size. In this case, the
unused memory from the original block will be put into the memory
pool for reuse.
Velocis maintains a system tag, which you may use. If there is
insufficient memory available, however, the server will shut down.
We recommend that you always create and use your own memory
tag.
Return Values A pointer to the extended and cleared memory block
See Also rm_cGetMemory, rm_extendMemory
Example
/* add new column reference entry */
if ( sdp->nocolrefs == sdp->maxcolrefs ) {
sdp->maxcolrefs += cr_chunk;
newsize = sdp->maxcolrefs*sizeof(CRL_ENTRY);
sdp->crbuf = rm_cExtendMemory(sdp->crbuf, newsize, psp->compiletag);
}

rm_cGetMemory
rm_cGetMemory Allocate and clear a memory block
Syntax void *rm_cGetMemory (size_t size, RM_MEMTAG tag)
Parameters size [Input] The size, in bytes, of the memory block to

allocate.
tag, specify NULL.
Description This function allocates a block of contiguous memory of a certain

length and associates it with a tag. The contents of the allocated
block are cleared (set to zero) by the standard C function memset.
If there is insufficient memory available, control will be transferred
to the error location specified in the jump buffer parameter to
rm_createTag or the most recent call to rm_resetTag for the specified
tag. If there is no active jump buffer, a NULL pointer is returned.
tag.
Return Values A pointer to the allocated block, or NULL
See Also rm_cExtendMemory, rm_createTag, rm_extendMemory,

rm_freeMemory, rm_freeTagMemory, rm_getMemory,
rm_resetTag
Example
sqlCtx = rm_cGetMemory(sizeof(SQLCTXT), userTag);

rm_cleanup
rm_cleanup Clean up and shut down the Velocis resource manager
Syntax void rm_cleanup (void)
Parameters None
Description This function is used to clean up all operational data and shut down
the resource manager. Call the function only if rm_startup has been
called to initiate the resource manager interface. You should instead
use the administration API functions s_startup and s_terminate to
start and shut down the Velocis database engine (which includes
that interface). Use of rm_startup and rm_cleanup are confined to
applications that only use the resource manager functions.
Return Values None
See Also rm_startup, s_startup, s_terminate
Example
...
main()
{
...
/* startup Velocis resource manager */
stat = rm_startup(NULL, MessageConsole, LOG_ERROR|LOG_WARN|LOG_INFO);
... /* use RM API functions only */
rm_cleanup();
}

rm_createTag
rm_createTag Create a dynamic memory tag
Syntax RM_MEMTAG rm_createTag (char *name, long limit, jmp_buf errloc,

RM_MEMFCN *fcnAddr, long segsize, short flags)
Parameters name [Input] The name of the tag. This name is used to
report any errors for the tag. If you do not need a
name for the tag, specify NULL.
limit [Input] The maximum amount of memory that can
be allocated. For no limit (other than the system
physical limit), specify 0.
errloc [Input] The jump buffer of an out-of-memory
handler. To have the memory allocation functions
simply return NULL for out-of-memory situations,
specify NULL.
fcnAddr [Input] The address of the memory-finding function,
which tries to make extra memory available if the
first allocation attempt fails. To bypass this feature,
specify NULL; otherwise, the function must have
the following prototype:
void REXTERNAL MemoryFindingFunctionName
(RM_MEMTAG MemoryTag,
size_t AmountOfMemoryRequested);
segsize [Input] The size, in bytes, of the memory allocation
segment. To use the default value (8,192), specify 0.
flags [Input] The serialized (one at a time) allocation flag.
If threads are allowed to allocate and to free
memory at the same time, you must specify
RM_USESEM to provide mutual exclusion;
otherwise, you may specify RM_NOSEM.
Description This function creates a dynamic memory allocation tag. Use of

tagged memory allows you to specify different handling
characteristics for classes of dynamic memory. A single call to
rm_freeTagMemory can quickly and efficiently free all memory
allocated on a given tag. This key feature reduces the risk of
memory leaks.
The errloc parameter is the value of a C jump buffer, which you
establish by calling setjmp. Control will be passed to that location
(via a call to longjmp) when there is not enough memory to satisfy

rm_createTag
an allocation request (for example, a call to rm_getMemory) on the

tag. An errloc value of NULL indicates that NULL will be returned
by memory allocation functions when there is insufficient memory.
You can specify the address of a function for Velocis to call when
there is insufficient memory to satisfy a memory allocation request
on the tag. (If you do not need this feature, specify NULL.) The
function is passed two arguments: a memory tag, and the requested
amount of memory. The purpose of the function is to free memory
from other sources (for example, some paging methodology) to use
to satisfy the original request. Upon return from the function, the
allocation attempt is retried. If the request still cannot be satisfied,
control is passed to errloc, if provided; otherwise, NULL is returned.
The Velocis resource manager uses a memory allocation method that
allocates segments of 8,192 bytes. Specifying 0 causes Velocis to use
that default segment size. You may wish to change this if it leads to
inefficient space management. We recommend that the segment size
be a power of 2.
The flags value must be either RM_USESEM or RM_NOSEM. This
flag controls whether memory allocations and deallocations are
serialized using a mutex semaphore. If all allocations and
deallocations will be from a single thread (or are already serialized
through an outside method), specifying RM_NOSEM will improve
performance. If allocations and deallocations can occur
simultaneously from multiple threads, you must specify
RM_USESEM.
Return Values The memory allocation tag
See Also rm_freeTagMemory, rm_resetTag

rm_createTag
Example
/* Free up memory by swapping statement code to disk */
void REXTERNAL SwapStmt(
RM_MEMTAG tag,
size_t size)
{
while ( size > 0 ) {
/* find least recently used statement */
...
/* save to swap file */
...
/* free statement buffer */
...
size -= /* buffer length */
}
}
...
jmp_buf memjmp;
RM_MEMTAG compileTag;
if ( setjmp(memjmp) ) {
/* free any previously allocated memory and return error */
rm_freeTagMemory(compileTag, 1);
return errSRVMEMORY;
}
...
compileTag = rm_createTag("compile", 0, memjmp, SwapStmt, 0, RM_NOSEM);

rm_extendMemory
rm_extendMemory Extend or reallocate a memory block
Syntax void *rm_extendMemory (void *ptr, size_t newsize,

RM_MEMTAG tag)
Parameters ptr [Input] A pointer to the currently allocated block to

be extended. If this pointer is NULL, the function
simply calls rm_getMemory.
newsize [Input] The new size, in bytes, of the memory block.
tag, specify NULL.
Description This function extends the previously allocated block of memory to a

specified length. The contents of the existing block are unchanged.
The memory tag must be the same one used in the original memory
allocation of ptr.
If the new block size is larger than the original size, Velocis attempts
to extend the block in place. If in-place extension is not possible,
Velocis allocates a new block and copies the contents of the current
block into it.
The new size can be smaller than the original size. In this case, the
unused memory from the original block will be put into the memory
pool for reuse.
tag.
Return Values A pointer to the extended memory block
See Also rm_getMemory
Example
/* add new column reference entry */
if ( sdp->nocolrefs == sdp->maxcolrefs ) {
sdp->maxcolrefs += cr_chunk;
newsize = sdp->maxcolrefs*sizeof(CRL_ENTRY);
sdp->crbuf = rm_extendMemory(sdp->crbuf, newsize, psp->compiletag);
}

rm_fileClose
rm_fileClose Close a resource manager file
Syntax void rm_fileClose (RM_PFILE hFile)
Parameters hFile [Input] The handle of the resource manager file to

close.
Description This function closes the resource manager file associated with the
specified file handle.
Return Values None
See Also rm_fileOpen
Example
RM_PFILE dbdFile;
...
rm_fileClose(dbdFile);

rm_fileCopy
rm_fileCopy Copy a file
Syntax short rm_fileCopy (char *srcName, char *destName)
Parameters srcName [Input] The name of the source file.

destName [Input] The name of the destination file.
Description This function will create a new file in the path identified by destName
and copy the contents of the file at srcName into it.
The file paths must be in the local operating system’s format. They
may be absolute or relative paths.
Return Values S_FILEOPERR
See Also rm_fileMove

rm_fileLength
rm_fileLength Get the length of a file
Syntax unsigned long rm_fileLength (RM_PFILE hFile)
Parameters hFile [Input] The handle to a resource manager file.
Description This function returns the current length, in bytes, of a resource

manager file.
Return Values The length of the file
Example
unsigned long filelen;
...
/* get length of file */
filelen = rm_fileLength(hInFile);

rm_fileMove
rm_fileMove Move a file
Syntax short rm_fileMove (char *srcName, char *destName)
Parameters srcName [Input] The name of the source file.

destName [Input] The name of the destination file.
Description This function will attempt to rename a file from srcName to destName.
If that fails, srcFile will be copied to destFile and srcFile will be
removed.
Return Values S_FILEOPERR
See Also rm_fileCopy, rm_fileDelete

rm_fileOpen
rm_fileOpen Open a resource manager file
Syntax RM_PFILE rm_fileOpen (char *name, unsigned int oflags,

short xflags, unsigned long crelen, unsigned long extlen)
Parameters name [Input] The file name, including the directory path.
oflags [Input] A bit map of file open characteristics.
Specify a combination of either O_BINARY or
O_TEXT, one of O_RDONLY, O_RDWR, or
O_WRONLY (O_RDONLY is the default), and any
combination of O_APPEND, O_CREATE, and
O_TRUNC. These flags are described below.
O_BINARY
Binary file. No interpretation is performed.
O_TEXT
Text file. The end-of-file marker is <Ctrl+D> (UNIX)
or <Ctrl+Z>+<Enter> (Windows).
O_RDONLY
Read-only mode. Write requests result in errors.
O_RDWR
Read/write mode.
O_WRONLY
Write-only mode.
O_APPEND
Append mode. New writes are added to the end of
the file.
O_CREAT
Create mode. A new file is created. If the file already
exists and O_TRUNC and O_APPEND are not
specified, an error is returned.
O_TRUNC
Truncate mode. Implies O_CREAT.
xflags [Input] A bit map of extended characteristics of
resource manager file operation. Specify any
combination of these flags:
RM_DIRECTIO
Causes file writes to be immediately written to disk.
RM_EXIT_ON_FAIL
Ends the program in the event of a file error.
RM_FPRINTF
Uses rm_filePrintf to write to the file.

rm_fileOpen
RM_NOGROW
Ignores the creation and extension lengths (crelen and
extlen), increases the file size only when data is
appended to it, and increases it only by the length of
the data added. This flag is generally used with
RM_FPRINTF.
RM_NOSYNC
Allows the file to be available to multiple threads, but
does no synchronization itself. This flag assumes that
the user is doing whatever synchronization is
necessary.
RM_SHARE
Makes the file available to multiple threads.
RM_STICKY
Forces the resource manager to keep this file open.
Under certain circumstances, the resource manager
may close files to free up file handles. When the file is
needed again, it is reopened. This flag makes sure
that the resource manager does not close the file until
rm_fileClose is called.
crelen [Input] The amount of memory, in bytes, allocated
for the file when it is created.
extlen [Input] The amount of memory, in bytes, to extend
the file whenever a write beyond the end of the file
occurs.
Description This function opens a file. A Velocis resource manager (RM) file
handle pointer is returned. If the file cannot be opened, NULL is
returned.
If the file is to be used by more than one thread, you must specify
RM_SHARE or RM_NOSYNC in the extended characteristics
parameter (xflags). You should only use rm_fileSeekRead and
rm_fileSeekWrite to perform the I/O operations on shared files. If
you call rm_fileSeek, rm_fileRead, or rm_fileWrite on a shared file,
a warning message will be reported to the Velocis message log.
Return Values The RM file handle pointer, or NULL
See Also rm_fileClose

rm_fileOpen
Example
RM_PFILE hInFile, hOutFile;
...
/* open files */
hInFile = rm_fileOpen(inFileName, O_RDONLY|O_BINARY, RM_SHARE, 0, 0);
hOutFile = rm_fileOpen(outFileName, O_CREAT|O_RDWR|O_BINARY,
RM_SHARE|RM_DIRECTIO, 0, 0);
if ( ! hInFile || !hOutFile )
printf("Unable to open files\n");

rm_filePosition
rm_filePosition Get the current position of a file
Syntax long rm_filePosition (short handle)
Parameters handle [Input] The file handle, as returned by rm_fileOpen.
Description This function returns the current position of the file (the position
where the next read or write would occur).
Return Values The file position (the number of bytes from the beginning of the file);
if the handle is invalid, 0 is returned
See Also rm_fileLength, rm_fileSeek

rm_filePrintf
rm_filePrintf Print formatted text to a file
Syntax unsigned short rm_filePrintf (RM_PFILE hFile, char *format, ...)
Parameters hFile [Input] The resource manager file handle.

format [Input] A printf-style format specifier.
... [Input] Variables referenced in the format specifier.
Description This function writes the text formatted by the format printf specifier
to the file. The resource manager file must be a file opened (using
rm_fileOpen) with the RM_FPRINTF attribute specified. Any
variables referenced in the format specifier must be listed following
the format string in the order in which they are referenced. Any
standard printf format specification may be used.
Return Values The number of bytes written
Example
RM_PFILE traceFile;
...
traceFile = rm_fileOpen("c:\debug\trace.out", O_TEXT|O_RDWR, RM_FPRINTF);
...
rm_filePrintf(traceFile, "MyFunction(%s, %ld)\n", dbname, seqno);

rm_fileRead
rm_fileRead Read from the current position in a file
Syntax unsigned int rm_fileRead (RM_PFILE hFile, void *buf,

unsigned int length)
Parameters hFile [Input] The resource manager file handle.

buf [Output] A pointer to the buffer into which the block
will be read.
length [Input] The length, in bytes, of the block to be read
from the file.
Description This function reads a block of bytes from the current position in a file
into a specified buffer. This function should not be used with files
that are shared between multiple threads. A warning message will
be written to the Velocis message log whenever rm_fileRead is
called with a file that was opened with the RM_SHARE attribute.
The conflict occurs because, in the time between the call to
rm_fileSeek and the subsequent call to rm_fileRead, another thread
could have issued a call to rm_fileSeek, changing the file position.
Use rm_fileSeekRead for shared, multi-threaded file access.
The function returns the number of bytes actually read. The end of
the file is detected when the return value is less than the specified
length.
Return Values The number of bytes that were read
See Also rm_fileSeek, rm_fileSeekRead

rm_fileRead
Example
RM_PFILE hFile;
char buf[4096];
unsigned int len, bufsize;
...
hFile = rm_fileOpen("somefile.xyz", O_BINARY|O_RDONLY, 0, 0, 0);
if ( !hFile ) {
printf("unable to open file\n");
exit(1);
}
/* sequentially read through file */
for (filelen = rm_fileLength(hFile); filelen > 0; filelen -= bufsize ) {
bufsize = filelen > 4096 ? 4096 : filelen;
len = rm_fileRead(hFile, buf, bufsize);
if ( len != bufsize ) {
printf("error reading file!\n");
break;
}
}
...

rm_fileRemove
rm_fileRemove Remove (delete) a file
Syntax short rm_fileRemove (char *name)
Parameters name [Input] The name of the file to delete.
Description This function deletes a file. If the file resides in the current working
directory, you need to specify only a base file name. Otherwise, the
full path name is required.
Return Values 0 = success, -1 = failure
Example
char filename[500];
...
printf("enter fully-qualified name of file to be deleted: ");
gets(filename);
if ( rm_fileRemove(filename) )
printf("unable to delete file %s\n", filename);

rm_fileRename
rm_fileRename Rename a file
Syntax short rm_fileRename (char *oldname, char *newname)
Parameters oldname [Input] The current name of a file.

newname [Input] The new name for the file.
Description This function renames a file. If the file resides in the current working
directory, you need to specify only a base file name. Otherwise, the
full path name is required.
Return Values 0 = success, nonzero = failure
Example
char oldName[500], newName[500];
printf("enter file to be renamed: ");

gets(oldName);
printf("enter new file name: ");
gets(newName);
if ( rm_fileRename(oldName, newname) )
printf("unable to rename file %s to %s\n", oldName, newName);

rm_fileSeek
rm_fileSeek Seek to a byte offset position in a file
Syntax void rm_fileSeek (RM_PFILE hFile, unsigned long addr)
Parameters hFile [Input] The handle of a resource manager file.

addr [Input] The offset position (address) within the file,
relative to the beginning of the file.
Description This function sets the position of a file to the specified address. The
address is the byte offset from the beginning of the file. This
function should not be used with files shared between multiple
threads. A warning message will be written to the Velocis message
log whenever rm_fileSeek is called for a file opened with the
RM_SHARE attribute. The conflict occurs because, in the time
between the call to rm_fileSeek and the subsequent call to
rm_fileRead or rm_fileSeekWrite, another thread could have issued
a call to rm_fileSeek, changing the file position. Use
rm_fileSeekRead or rm_fileSeekWrite for shared, multi-threaded
file access.
Return Values None
See Also rm_fileRead, rm_fileSeekRead, rm_fileSeekWrite
Example
RM_PFILE datFile;
char reply[81], buf[1024];
unsigned long addr, len;
...
datFile = rm_fileOpen(filename, O_BINARY|O_RDONLY, 0, 0, 0);
...
while ( printf("enter file offset: ", gets(reply) ) {
addr = (unsigned long)atol(reply);
rm_fileSeek(datFile, addr);
len = rm_fileRead(datFile, buf, 1024);
dump_file(buf, len);
}

rm_fileSeekRead
rm_fileSeekRead Read from a specified location in a file
Syntax unsigned int rm_fileSeekRead (RM_PFILE hFile, unsigned long addr,

void *buf, unsigned int length)
Parameters hFile [Input] The handle to the resource manager file.

addr [Input] The position within the file from which to
read.
buf [Output] A pointer to the buffer into which the block
will be read.
length [Input] The length, in bytes, of the block to be read
from the file.
Description This function reads a certain number of bytes into a buffer,

beginning at a specified position within a file. The number of bytes
actually read is returned. The end-of-file is detected when the return
value is less than the length specified.
Return Values The number of bytes that were read
See Also rm_fileSeekWrite
Example
while ( ! end_of_dump ) {
rm_queueRead(dumpQueue, &pMsg,NULL, &end_of_dump, RM_INDEFINITE_WAIT);
if ( pMsg ) {
/* read block to be dumped */
len=rm_fileSeekRead(hInFile,pMsg->startpos,inBuff, pMsg->blocklen);
if ( len != pMsg->blocklen )
rm_log(LOG_ERROR, "error reading input file");
else
DumpBlock(inBuff, pMsg->startpos, pMsg->blocklen, outBuff);

rm_fileSeekWrite
rm_fileSeekWrite Write to a specified location in a file
Syntax short rm_fileSeekWrite (RM_PFILE hFile, unsigned long addr,

void *buf, unsigned int length, short waitFlag)

addr [Input] The position within the file at which to begin
the writing.
buf [Input] A pointer to the buffer containing the data to
be written.
length [Input] The length, in bytes, of the block to be
written.
waitFlag [Input] A flag indicating whether to wait for the
write to complete before exiting the function. To
wait for completion of the write, specify 1. To have
the function return immediately (an asynchronous
write), specify 0.
Description This function writes a block of bytes from a buffer into a resource
manager file, beginning at the specified byte offset position. If your
writes are asynchronous, ensure that all writes have finished by
calling the file synchronization function (rm_fileSync) after
completing all of the required writes. You cannot reuse the buffer
until the write is completed.
Return Values 0 = success, -1 = write error occurred
See Also rm_fileSeekRead, rm_fileSync

rm_fileSeekWrite
Example
/* =====================================================================
Dump block to hex output file
*/
static void DumpBlock(
unsigned char *i_buf,
unsigned long i_pos,
size_t i_len,
char *o_buf)
{
unsigned long o_pos = 77*(i_pos/16);
size_t o_len = 77*(i_len/16);
...
while ( i_len > 0 ) {
... /* format hex dump of block */
}
rm_fileSeekWrite(hOutFile, o_pos, o_buf, o_len, 1);
}

rm_fileStreamClose
rm_fileStreamClose Close a streaming file
Syntax void rm_fileStreamClose (RMF_STREAM rmf)
Parameters rmf [Input] A pointer to a stream control block.
Description This function closes the streaming file represented by rmf. Allocated
memory is released.
Return Values None
See Also rm_fileStreamOpen

rm_fileStreamGetLine
rm_fileStreamGetLine Read a line of any length from a streaming file
Syntax char *rm_fileStreamGetLine (RMF_STREAM rmf, char **buf,

size_t *len)

buf [Output] A pointer to a pointer to the destination of
the read.
len [Output] A pointer to the length of the line.
Description This function reads any number of characters from the file
represented by rmf and points *buf to the allocated space. A line is
defined as all characters from the current position in the stream to
and including the first newline character.
The line must be freed by using rm_freeMemory and the default tag
(0 or NULL).
Return Values The pointer to the line, or NULL if an error has occurred or if an end-
of-file has been reached
See Also rm_fileStreamGets

rm_fileStreamGets
rm_fileStreamGets Read a line of a fixed length from a streaming file
Syntax char *rm_fileStreamGets (RMF_STREAM rmf, char *buf, int len)

buf [Output] A pointer to the destination of the read.
len [Input] The maximum length of the read.
Description This function reads up through the first newline character or to len-1
characters, whichever is shorter. The resulting line will always be
null-terminated.
Return Values A pointer to the line, or NULL if an error has occurred or if an end-
of-file has been reached
See Also rm_fileStreamGetLine

rm_fileStreamOpen
rm_fileStreamOpen Open a streaming file
Syntax RMF_STREAM rm_fileStreamOpen (char *fname, char *mode)
Parameters fname [Input] The name of the file to open.

mode [Input] The standard flags to be used in opening the
file.
Description This function opens the file named by fname. It may be an absolute
or relative page. The mode flags are passed into the ANSI standard
open function and must be defined in fcntl.h. Flags such as
O_CREAT and O_RDWR are commonly used.
A file opened by this function must be used by the other
rm_fileStream* functions. These functions implement a streaming
buffer on top of the rm_file* functions.
Within an extension module, these functions should be used instead
of the standard C/C++ open/close/read/write functions, because
Velocis needs to remain in control of the number of OS file handles
that are open at once.
The return value from this function is a handle to other functions. It
is a pointer to a structure that keeps stream information and a buffer.
You must use rm_fileStreamClose to properly close the file and free
the memory that has been allocated.
Return Values A handle of type RMF_STREAM, or NULL if the open fails
See Also rm_fileStreamClose

rm_fileStreamPuts
rm_fileStreamPuts Write one line to a streaming file
Syntax int rm_fileStreamPuts (RMF_STREAM rmf, char *buf)

buf [Input] A pointer to the string to be written.
Description This function writes one line to a streaming file. It must be a null-
terminated string. The ending null-byte will be changed to a
newline character before the string is written.
Return Values The total number of bytes written

rm_fileStreamRewind
rm_fileStreamRewind Reset the position of a streaming file to be the start
Syntax void rm_fileStreamRewind (RMF_STREAM rmf)
Description This function performs the equivalent of a seek to address 0 of the

file. Since this is a streaming file, there is no seeking to a specific
byte offset.
Return Values None
See Also rm_fileStreamOpen

rm_fileSync
rm_fileSync Synchronize a file/wait for all writes to complete
Syntax void rm_fileSync (RM_PFILE hFile)
Description This function commits all writes on a resource manager file to disk.
All pending writes issued by the calling thread are guaranteed to be
on the disk once the function has returned.
Note: This function must be called from each thread that has issued
asynchronous write calls (see rm_fileSeekWrite).
Return Values None
See Also rm_fileSeekWrite
Example
rm_fileSync(hOutFile);

rm_fileValidate
rm_fileValidate Check whether a file exists
Syntax int rm_fileValidate (char *pszFileName)
Parameters pszFileName [Input] A pointer to the path name of the file to

validate.
Description This function looks for the named file on the local file system. The
path to the file may be absolute or relative.
Return Values 0 if the file exists, and -1 if it does not
See Also rm_fileOpen, rm_fileRead, rm_fileSeek

rm_fileWrite
rm_fileWrite Write to the current position in a file
Syntax unsigned int rm_fileWrite (RM_PFILE hFile, void *buf,

unsigned int length)

buf [Input] A pointer to the buffer containing the data to
write.
length [Input] The length, in bytes, of the data block to
write.
Description This function writes a certain number of bytes to the current position
in a file from a specified buffer. It returns the number of bytes
actually written. An error is detected when the return value is less
than the specified length.
Do not use this function with files shared between multiple threads.
Use rm_fileSeekWrite for shared, multi-threaded file access.
Note: A warning is written to the Velocis message log whenever

rm_fileWrite is called with a file opened by the RM_SHARE
attribute. If rm_fileSeek and then rm_ fileWrite are called, another
thread could call rm_fileSeek between those calls, which changes
the file position and causes a conflict.
Return Values The number of bytes that were written
See Also rm_fileSeek, rm_fileSeekWrite

rm_fileWrite
Example
RM_PFILE hInFile, hOutFile;
char buf[4096];
unsigned int len, bufsize;
...
hInFile = rm_fileOpen(inFileName, O_BINARY|O_RDONLY, 0, 0, 0);
hOutFIle = rm_fileOpen(outFileName, O_CREAT|O_BINARY|O_WRONLY, 0, 0, 0);
/* sequentially read through file */

for (filelen = rm_fileLength(hInFile); filelen>0; filelen -= bufsize ) {
bufsize = filelen > 4096 ? 4096 : filelen;
len = rm_fileRead(hInFile, buf, bufsize);
printf("error reading file!\n");
break;
}
len = rm_fileWrite(hOutFile, buf, bufsize);
printf("error writing file!\n");
break;
}
}
...

rm_freeMemory
rm_freeMemory Free a memory block
Syntax void rm_freeMemory (void *ptr, RM_MEMTAG tag)
Parameters ptr [Input] A pointer to the memory block to be freed.

tag [Input] The memory tag for which the pointer to the
memory block is allocated.
Description This function frees a block of memory. The pointer specified must
point to a block of memory previously allocated under the specified
tag. If the pointer was not previously allocated under that tag, an
error message is logged, and the function returns without freeing the
block.
Return Values None
See Also rm_cExtendMemory, rm_ cGetMemory, rm_extendMemory,

rm_freeTagMemory, rm_getMemory
Example
char *tempBuf;
tempBuf = rm_getMemory(tempBufLen, compileTag);
... /* use temporary buffer */
rm_freeMemory(tempBuf, compileTag);

rm_freeTagMemory
rm_freeTagMemory Free all memory associated with a tag
Syntax void rm_freeTagMemory (RM_MEMTAG tag, short freetag)
Parameters tag [Input] The memory tag.

freetag [Input] A flag indicating whether to also free the
memory tag. To free the tag, specify 1. To allow use
of the tag for future memory allocations, specify 0.
Description This function frees all of the memory that was allocated under a
memory tag. It also allows you to specify whether to free the tag or
leave it for future memory allocations.
Return Values None
See Also rm_createTag, rm_freeMemory
Example
jmp_buf memjmp;
}
rm_resetTag(memjmp, compileTag);

rm_getenv
rm_getenv Get the definition string for a specified environment variable
Syntax char *rm_getenv (char *envVar)
Parameters envVar [Input] The name of an environment variable.
Description This function returns the definition string for the environment
variable specified. If the environment variable is not defined, the
function returns NULL. An environment variable can be set either in
the system environment or in the [ENVIRONMENT] section of
velocis.ini.
Return Values A pointer to the environment variable definition, or NULL
Example
char *catpath;
...
catpath = rm_getenv("CATPATH");

rm_getFromPool
rm_getFromPool Get a buffer from a pool
Syntax void *rm_getFromPool (size_t bufsize, RM_POOL *hPool)
Parameters bufsize [Input] The size, in bytes, of the buffer to return.

hPool [Input] The handle of the pool from which to fetch
the buffer.
Description This function fetches the next available buffer from the buffer pool.
If there are no buffers in the pool, a new buffer is allocated. If the
static_size flag was 0 in the rm_allocPool call creating the pool, and
the first available buffer is smaller than the specified buffer size, the
buffer will be expanded to the specified size. The size of the
returned buffer will always be at least bufsize in length.
If there is insufficient memory available, the action taken will be the
same as what was specified for the memory tag passed into
rm_allocPool. Buffer pools are most efficient when the sizes of the
buffers are equal, since this reduces the amount of memory
allocation calls required.
Return Values A pointer to the buffer, or NULL
See Also rm_allocPool, rm_putInPool, rm_zFreePool
Example
Main Thread
/* send dump messages to threads */
for (pos = 0; filelen > 0; pos += buffSize) {
pMsg = rm_getFromPool(sizeof(DUMPMSG), qPool);
pMsg->startpos = pos;
pMsg->blocklen = filelen >= buffSize ? buffSize : filelen;
rm_queueWrite(dumpQueue, pMsg, sizeof(DUMPMSG), 0, 0);
filelen -= buffSize;
}

rm_getFromPool
Dump Thread
if ( pMsg ) {
...
/* free queue message */

rm_putInPool(pMsg, qPool);
}

rm_getLocalEnv
rm_getLocalEnv Get a local variable value
Syntax char *rm_getLocalEnv (char *varname)
Parameters varname [Input] The name of the environment variable.
Description This function searches through the local Velocis environment for a
variable with name varname.
See rm_getenv for a description of how local Velocis variables are
loaded into the environment.
Return Values A pointer to the variable’s value, or NULL if not found
See Also rm_getenv, rm_putLocalEnv

rm_getMemory
rm_getMemory Allocate a block of memory
Syntax void *rm_getMemory (size_t size, RM_MEMTAG tag)
Parameters size [Input] The size, in bytes, of the memory block to

allocate.
tag, specify NULL.
Description This function allocates a block of contiguous memory of a certain

length and associates the block with a memory tag. The contents of
the allocated block are left unchanged.
If there is insufficient memory available, program control passes to
the location where the jump buffer associated with the tag is set. If
there is no active jump buffer, the function returns NULL.
Note: A jump buffer can be associated with a memory tag in the

rm_createTag call creating that tag. To change the jump buffer
associated with a tag, call rm_resetTag.
tag.
Return Values A pointer to the allocated block, or NULL
See Also rm_cExtendMemory, rm_cGetMemory, rm_createTag,

rm_extendMemory, rm_freeMemory, rm_freeTagMemory,
rm_resetTag
Example
char *inBuff;
char *outBuff;
...
/* allocate input buffer for 1 dump block */

inBuff = rm_getMemory(buffSize, mTag);
/* allocate output buffer for each formatted dump line */

outBuff = rm_getMemory(77*(buffSize/16)+1, mTag);

rm_iniGet
rm_iniGet Get an entry from velocis.ini
Syntax short rm_iniGet (char *section, char *entry, char *buffer, short length,
short flag)
Parameters section [Input] The configuration file section in which to

look for the entry.
entry [Input] The name of the configuration variable being
read.
buffer [Output] The storage location at which to place the
results.
length [Input] The length, in bytes, of the storage buffer.
flag [Input] An indicator of whether to read the whole
line.
Description This function retrieves the setting for a server configuration variable
into an output string. To do this, the function passes all its
parameters to the rm_iniGetPrivate function and supplies the
velocis.ini file name as the last parameter.
See Also rm_iniGetPrivate, rm_iniSetPrivate

rm_iniGetPrivate
rm_iniGetPrivate Get an entry from a configuration file
Syntax short rm_iniGetPrivate (char *section, char *entry, char *buffer,

short length, short flag, char *iniName)
Parameters section [Input] The configuration file section in which to

look for the entry.
read.
buffer [Output] The storage location at which to place the
results.
length [Input] The length, in bytes, of the storage buffer.
flag [Input] An indicator of whether to read the whole
line.
iniName [Input] The name of the configuration file.
Description This function searches a configuration file identified by iniName for a

section identified by section and an entry identified by entry. If it
finds the identified entry, it returns the value in buffer.
If section is NULL, the function searches within all section names.
The section names will be placed into buffer with null-byte
separators. A final double null-byte indicates the end of the list. The
entry and flag parameters are ignored.
If entry is NULL, the function searches within all entries in the
section. If flag is TRUE, the function returns both the entry names
and their values, separated by an equal ("=") sign. If flag is FALSE,
only the names are returned. The results are placed into buffer with
null-byte separators. A final double null-byte indicates the end of
the list.
When requesting all section names or all entries in a section, be sure
that the buffer is longer than the anticipated length of the result.
Return Values S_NOTFOUND

S_OKAY
See Also rm_iniGet, rm_iniSetPrivate

rm_iniSet
rm_iniSet Set an entry in velocis.ini
Syntax short rm_iniSet (char *section, char *entry, char *value)
Parameters section [Input] The configuration file section in which to put

the entry.
set.
value [Input] The value of the configuration variable being
set.
Description This function sets the value of a server configuration variable. To do

this, the function passes all its parameters to the rm_iniSetPrivate
function and supplies the velocis.ini file name as the last parameter.
If you are setting an entry in the [ENVIRONMENT] section, the
entry/value pair will also be added to the Velocis local environment.
See Also rm_iniGet, rm_iniSetPrivate, rm_putLocalEnv

rm_iniSetPrivate
rm_iniSetPrivate Set an entry in a configuration file
Syntax short rm_iniSetPrivate (char *section, char *entry, char *value,

char *iniName)
Parameters section [Input] The configuration file section in which to put

the entry.
set.
value [Input] The value of the configuration variable being
set.
iniName [Input] The name of the configuration file.
Description This function changes the contents of a configuration file identified

by iniName.
If the entry parameter is NULL, the section will be deleted.
If the value parameter is NULL, the entry will be deleted (provided
that the section is found).
When section, entry and value are supplied, this function adds an
"entry=value" entry to the configuration file. The entry is added to
the section identified by section.
If section does not yet exist in the file, it will be added.
This function creates a new temporary file with the changed
contents. It then removes the old file and rename the temporary file
to the name in iniName.
Return Values S_FILEWRERR

S_INVNULL
S_NOFILE

rm_log
rm_log Output a message to the Velocis message log
Syntax void rm_log (short msgType, char *format, ...)
Parameters msgType [Input] The message type indicator. The parameter

can be any combination of these message types:
LOG_ALL All messages
LOG_CYCLE Change log cycle message
LOG_EM Extension module load message
LOG_ERROR Error message
LOG_INFO General purpose information message
LOG_LOGIN User login message
LOG_RECOV Message generated by recovery process
LOG_STARTUP Startup message
LOG_USER User generated message
LOG_WARN Warning message
format [Input] A printf-style format specification string.
... [Input] Variables referenced in the format specifier.
Description This function can be called to output a message to the Velocis

message log. It operates similarly to the standard printf function.
The format string consists of a printf format specifier. The
referenced variables must be passed into rm_log following the
format string in the order in which they occur within that string.
Return Values None
Example
rm_log(LOG_INFO, "Dump complete: %ld %d-byte blocks written to file %s.",
blockCount, buffSize, outFileName);

rm_memoryAllocated
rm_memoryAllocated Return the total bytes allocated to a tag
Syntax long rm_memoryAllocated (RM_MEMTAG tag)
Description This function returns the total number of bytes that have been
allocated to a tag.
Return Values The total number of bytes allocated to the tag
See Also rm_createTag, rm_memoryAvail

rm_memoryAvail
rm_memoryAvail Return the number of bytes still available on a tag
Syntax long rm_memoryAvail (RM_MEMTAG tag)
Description This function returns the number of bytes that may still be allocated
to a tag. If no limit has been specified, then -1 will be returned.
To set a limit on the memory used by a tag, the rm_createTag
function must be used.
Return Values The number of bytes available, or -1 if no limit has been specified
See Also rm_createTag, rm_memoryAllocated

rm_putInPool
rm_putInPool Put a buffer into a pool
Syntax void rm_putInPool (void *buf, RM_POOL *hPool)
Parameters buf [Input] A pointer to the buffer to return to the pool.

hPool [Input] The handle of the pool into which to put the
buffer.
Description This function puts a buffer into the buffer pool. The buffer must
have been returned from a previous call to rm_getFromPool or have
been allocated using the memory tag specified in the rm_allocPool
call that created the pool.
Return Values None
See Also rm_allocPool, rm_getFromPool, rm_zFreePool
Example
Main Thread
/* send dump messages to threads */
for (pos = 0; filelen > 0; pos += buffSize) {
pMsg = rm_getFromPool(sizeof(DUMPMSG), qPool);
pMsg->startpos = pos;
pMsg->blocklen = filelen >= buffSize ? buffSize : filelen;
rm_queueWrite(dumpQueue, pMsg, sizeof(DUMPMSG), 0, 0);
filelen -= buffSize;
}
Dump Thread
if ( pMsg ) {
...
/* free queue message */
rm_putInPool(pMsg, qPool);
}

rm_putLocalEnv
rm_putLocalEnv Put a local variable value
Syntax void rm_putLocalEnv (char *sp)
Parameters sp [Input] A pointer to a string containing a

name/value pair.
Description This function parses sp to obtain a variable name and variable value.
The form of the string must be:
name=value
The name may be used in rm_getLocalEnv or rm_getenv to find the
value.
Return Values None
See Also rm_getenv, rm_getLocalEnv

rm_queueCreate
rm_queueCreate Create an interthread message queue
Syntax short rm_queueCreate (char *name)
Parameters name [Input] The name of the queue to create. This name
is reported in any error messages generated.
Description This function creates an interthread message queue. The returned

queue handle is required by other resource manager queue functions
(rm_queue prefix) to identify the queue. These queueing functions
are only for sending messages between threads in the same process.
Interprocess message queueing is not supported.
The number of queues is limited to 15. The Velocis database engine
uses 1, and the RPC subsystem uses 2, leaving a maximum of 12
additional queues.
Return Values The handle to the message queue
See Also rm_queueDelete, rm_queuePurge, rm_queueRead, rm_queueWrite
Example
short dumpQueue;
...
/* Create message queue for sending dump instructions to threads */
dumpQueue = rm_queueCreate("dumpQueue");

rm_queueDelete
rm_queueDelete Delete an interthread message queue
Syntax void rm_queueDelete (short handle)
Parameters handle [Input] The handle of the queue to delete.
Description This function deletes a queue and any messages that are currently on
the queue.
Return Values None
See Also rm_queueCreate, rm_queuePurge, rm_queueRead, rm_queueWrite
Example
short dumpQueue;
...
rm_queueDelete(dumpQueue);

rm_queuePurge
rm_queuePurge Purge (remove) a message queue of a message matching an identifier
Syntax void rm_queuePurge (short handle, long msgid)
Parameters handle [Input] The handle of the queue to purge.

msgid [Input] The identifier value of the message to be
removed.
Description This function looks for all messages matching a message identifier
and removes them from a queue. If the message identifier is equal to
-1, the function removes all messages from the queue.
Return Values None
See Also rm_queueCreate, rm_queueDelete, rm_queueRead,

rm_queueWrite
Example
/* forced system shutdown, purge and delete queue */
rm_queuePurge(dioQueue, -1);
rm_queueDelete(dioQueue);

rm_queueRead
rm_queueRead Read a message from a queue
Syntax short rm_queueRead (short handle, void **pMsgbuf,

unsigned long *pBuflen, long *pMsgid, long timeout)
Parameters handle [Input] The handle to the queue.

pMsgbuf [Output] A pointer to the message buffer pointer.
pBuflen [Output] A pointer to the buffer length. If you do
not need to retrieve this value, specify NULL.
pMsgid [Output] A pointer to the message identifier. If you
do not need to retrieve this value, specify NULL.
timeout [Input] The maximum time, in milliseconds, to wait
for the message. To have an unlimited wait time,
specify RM_INDEFINITE_WAIT. To return
immediately, if there are no messages in the queue,
specify 0.
Description This function reads a message from a specified queue. Once the
message has been read, the function stores a pointer to the message
buffer, the size of the buffer, and the message identifier. Note that
the pointer returned by rm_queueRead is identical to the pointer
passed into rm_queueWrite by the sending thread.
If no message is available on the queue, the call will suspend until
either a message is sent or the maximum wait time has elapsed. A
status of RM_TIMEOUT is returned if the function returns and there
are no messages available.
Return Values RM_OKAY

RM_TIMEOUT
See Also rm_queueCreate, rm_queueDelete, rm_queuePurge,

rm_queueWrite

rm_queueRead
Example
/* process cache manager request messages */
for ( msgCount = 0; ; ++msgCount ) {
rm_queueRead( dioQueue, &pMsg, NULL, &msgid, RM_INDEFINITE_WAIT );
switch ( msgid ) {
case DIO_GET:
... /* get request cache page */
...
}

rm_queueWrite
rm_queueWrite Write a message to a queue
Syntax void rm_queueWrite (short handle, void *msgbuf,

unsigned short buflen, long msgid, short flag)
Parameters handle [Input] The handle of the queue.

msgbuf [Input] A pointer to the message buffer.
buflen [Input] The length, in bytes, of the message buffer.
msgid [Input] A message identifier (can be anything you
like).
flag [Input] The message priority indicator. To write the
message at the front of the queue, specify
RM_QUEUE_PRIORITY. To write the message at
the end of the queue, specify
RM_QUEUE_NORMAL.
Description This function places a message of specified length into a queue. The
message can be placed at the beginning or at the end of the queue.
You may include an identifier number with the message.
Return Values None
See Also rm_queueCreate, rm_queueDelete, rm_queuePurge,

rm_queueRead
Example
/* session thread’s request to cache manager to read a page */
rm_syncStart(pMsg->dioSem);
rm_queueWrite(dioQueue, pMsg, sizeof(DIO_MSG), DIO_GET, 0);
/* wait for cache manager to tell us he’d done */

rm_syncWait(pMsg->dioSem, RM_INDEFINITE_WAIT);

rm_resetTag
rm_resetTag Reset the jump buffer associated with a tag
Syntax void rm_resetTag (jmp_buf errloc, RM_MEMTAG tag)
Parameters errloc [Input] The jump buffer of an out-of-memory

handler. To disable jumping, specify NULL.
tag [Input] The memory tag.
Description This function modifies the location of the out-of-memory error jump
buffer. The errloc parameter is the value of a C jump buffer, which
you establish by calling setjmp. Control will be passed to that
location (via a call to longjmp) when there is not enough memory to
satisfy an allocation request (for example, a call to rm_getMemory)
on the tag. An errloc value of NULL indicates that NULL will be
returned by memory allocation functions when there is insufficient
memory.
Return Values None
See Also rm_createTag
Example
jmp_buf memjmp;
}
rm_resetTag(memjmp, compileTag);

rm_sleep
rm_sleep Suspend a thread for a specified period of time
Syntax void rm_sleep (unsigned long msecs)
Parameters msecs [Input] The time, in milliseconds, for which to

suspend the thread.
Description This function causes the executing thread to suspend (allowing other
threads to run), until at least the specified period of time has elapsed.
The function is typically used by a thread waiting for some activity
to be completed.
Return Values None
See Also rm_syncWait
Example
while ( ! done ) {
/* check it once each second */
rm_sleep(1000);
}

rm_startup
rm_startup Start the Velocis resource manager (in lieu of the Velocis database
engine)
Syntax short rm_startup (char *catpath, RMLOGFCN *logFcn,

short msgTypes)
Parameters catpath [Input] The name of the path to the catalog

directory. If this parameter is NULL, Velocis
determines the directory from the CATPATH
system environment variable. If CATPATH is not
defined, Velocis uses the current working directory.
logFcn [Input] A pointer to a function that handles log
messages. To simply output all log messages to
rds.log and standard output (stdout), specify NULL;
otherwise, specify a pointer to a function having the
following prototype:
void LogFunctionName
(RDSLOG_CTRL ActionTypeIndicator,
short MessageTypeIndicator, char *Message);
msgTypes [Input] A bit map of message types to be logged.
Specify any combination of the type indicators listed
below:
LOG_CYCLE Change log cycle messages
LOG_EM Extension module load messages
LOG_ERROR Error messages
LOG_INFO General purpose information messages
LOG_LOGIN User login messages
LOG_RECOV Messages generated by recovery process
LOG_STARTUP Startup messages
LOG_USER User generated messages
LOG_WARN Warning messages
Description This function starts the Velocis resource manager. Use this function
only when your application will not be using any of the Velocis
database functions.
The function for handling log messages can have any valid function
name. It requires three parameters: an indicator of the type of action
being taken, an indicator of the type of message, and the message
string itself. The action type indicator can be one of the following
values:

rm_startup
RMLOG_CLOSE Specifies a close message log. This is

passed once, at shutdown, to allow the
function to close any files or windows
associated with the message log.
RMLOG_MESSAGE Indicates that a message is to be logged.
This is passed whenever Velocis
generates a message matching a
message type specified in the
rm_startup call.
RMLOG_OPEN Specifies an open message log. This is
passed once, at startup, to allow the
function to open any files or windows to
which subsequent log messages will be
output.
In rm_startup and in the specified log function, the message type
indicator indicates what type of messages to log. Multiple message
types can be combined by using the bitwise OR operator ("|"). You
can specify LOG_ALL to request logging of all message types.
Return Values S_CATERR S_NOCATALOG

S_CATLOCKED S_OKAY
See Also rm_log, rm_terminate, s_startup

rm_startup
Example
static RDSLOGFCN MessageConsole;

static short shutdown_flag;
...
stat = rm_startup(NULL, MessageConsole, LOG_ALL);
printf("Unable to start Velocis resource manager, status = %d\n",
stat);
exit(1);
}
...
/* Log Velocis console message

*/
void MessageConsole(
short fcn, /* call type: open, close, message */
short type, /* message type */
char *msg) /* message to be logged */
{
static FILE *errlog;
switch ( fcn ) {
case RDSLOG_OPEN:
errlog = fopen("velocis.log", "w");
break;
case RDSLOG_MESSAGE:
if ( type == LOG_ERROR ) {
/* make sure this gets noticed */
fprintf(errlog, "******* ERROR! ******* ");
printf("******* ERROR! ******* ");
}
fprintf(errlog, "%s\n", msg);
printf("%s\n", msg);
break;
case RDSLOG_CLOSE:
fclose(errlog);
break;
}
}

rm_Strdup
rm_Strdup Make an allocated copy of a string
Syntax char *rm_Strdup (const char *cp, RM_MEMTAG tag)
Parameters cp [Input] A pointer to the string to duplicate.

tag [Input] The memory tag.
Description This function allocates a block of memory to tag, which is long

enough to contain the string pointed to by cp. The contents of cp are
then copied to the new block.
Return Values A pointer to the newly allocated string

rm_syncCreate
rm_syncCreate Create a synchronization object
Syntax RM_SEM rm_syncCreate (char *name, short type, short flag)
Parameters name [Input] The name of the synchronization object. This

name is only used for reporting any errors
encountered.
type [Input] The semaphore type indicator. Specify one
of these indicators:
RM_EVENT_SEM
An event semaphore. This semaphore signals any
threads that are waiting for it. The initial state for an
event semaphore is "signalled."
RM_MUTEX_SEM
A mutex (mutual exclusion) semaphore. This
semaphore is used to serialize access to shared data,
so that only one thread at a time can modify the
shared data.
RM_QUIES_SEM
A quiescent semaphore. This type allows multiple
readers access to shared data but only one writer. If
the semaphore is "disabled," the writer has control
and the readers must wait. If the semaphore is
"enabled" (the default state), the writer is finished and
the readers all have access.
flag [Input] A flag indicating whether the object is
shared. To indicate that the object can be shared,
specify RM_SHAREABLE; otherwise, specify
RM_EXCLUSIVE.
Description This function creates a synchronization object. Three types of

synchronization objects (semaphores) are available: event, mutex,
and quiescent (see the type parameter above).
Only mutex semaphores can be shared. A mutex is shared when it is
used to synchronize access to two or more unrelated data structures.
Specifying that a mutex can be shared gives the Velocis resource
manager the freedom to share the object. A shared mutex just means
that access to any data controlled by the mutex will be serialized,
which may reduce system throughput.

rm_syncCreate
Note: The only reason to share a mutex is to reduce the number of

system semaphores being consumed by the Velocis application.
Some systems already limit the amount of available semaphores.
Return Values The synchronization object handle to be used in subsequent

rm_sync* calls
See Also Mutex: rm_syncEnterExcl, rm_syncExitExcl

Event: rm_syncResume, rm_syncStart, rm_syncWait
Quiescent: rm_syncDisableQ, rm_syncEnableQ,
rm_syncReceiveQ, rm_syncSendQ, rm_syncWaitQ
Example
RM_SEM mSem, eSem, qSem;
...
mSem = rm_syncCreate("task table", RM_MUTEX_SEM, RM_SHAREABLE);
eSem = rm_syncCreate("chkpt done", RM_EVENT_SEM, RM_EXCLUSIVE);
qSem = rm_syncCreate("log cycle", RM_QUIES_SEM, RM_EXCLUSIVE);

rm_syncDelete
rm_syncDelete Delete a synchronization object
Syntax void rm_syncDelete (RM_SEM handle)
Parameters handle [Input] The handle of the synchronization object to

delete.
Description This function deletes a mutex, event, or quiescent semaphore. The

semaphore handle is a value returned from rm_syncCreate.
Return Values None
See Also rm_syncCreate
Example
rm_syncDelete(mSem);
rm_syncDelete(eSem);
rm_syncDelete(qSem);

rm_syncDisableQ
rm_syncDisableQ Disable a quiescent semaphore
Syntax void rm_syncDisableQ (RM_SEM handle)
Parameters handle [Input] The handle to a quiescent semaphore.
Description This function disables a quiescent semaphore, which prevents any

new reader threads from gaining access to the shared data controlled
by that semaphore. Threads calling rm_syncReceiveQ to receive
access permission to the semaphore will hang until the semaphore is
re-enabled through a subsequent call to rm_syncEnableQ.
After calling rm_syncDisableQ, the writer thread (which may or
may not be the same thread that called rm_syncDisableQ) must call
rm_syncWaitQ to wait for all reader threads that currently have
access to exit. The shared data can then be modified, after which the
writer thread can call rm_syncEnableQ to restore reader access to
the shared data.
Return Values None
See Also rm_syncEnableQ, rm_syncReceiveQ, rm_syncSendQ,

rm_syncWaitQ
Example
Writer Thread
/* prevent new readers from gaining access */
rm_syncDisableQ(qSem);
/* wait for all current readers to exit */
rm_syncWaitQ(qSem, RM_INDEFINITE_WAIT);
... /* update shared data */
/* release any waiting reader threads */

rm_syncEnableQ(qSem);

rm_syncDisableQ
Reader Thread
/* gain access to shared data */
rm_syncReceiveQ(qSem);
... /* access shared data */

/* exit shared data access */
rm_syncSendQ(qSem);

rm_syncEnableQ
rm_syncEnableQ Enable a quiescent semaphore
Syntax void rm_syncEnableQ (RM_SEM handle)
Description This function is called from the writer thread to enable reader access
to the shared data controlled by a quiescent semaphore. The writer
thread calls this function after it has completed making the needed
changes to the shared data.
Reader threads must call rm_syncReceiveQ to receive access
permission to the semaphore. These threads are left hanging,
however, if the semaphore is in a disabled state. The
rm_syncEnableQ function releases these threads, allowing access
from the threads to occur.
Return Values None
See Also rm_syncDisableQ, rm_syncReceiveQ, rm_syncSendQ,

rm_syncWaitQ
Example
Writer Thread

Reader Thread

rm_syncSendQ(qSem);

rm_syncEnterExcl
rm_syncEnterExcl Enter an exclusive access section
Syntax void rm_syncEnterExcl (RM_SEM handle)
Parameters handle [Input] The handle to a mutex semaphore.
Description This function grants exclusive access to shared data controlled by a

mutex semaphore. If another thread has control of the semaphore at
the time of the call, the calling thread will wait. If multiple threads
are waiting, they will be granted access on a first-come, first-served
basis. Control is released through a call to rm_syncExitExcl.
Return Values None
See Also rm_syncExitExcl
Example
/* update count of dumped blocks */
rm_syncEnterExcl(countSem);
++blockCount;
rm_syncExitExcl(countSem);

rm_syncExitExcl
rm_syncExitExcl Exit an exclusive access section
Syntax void rm_syncExitExcl (RM_SEM handle)
Parameters handle [Input] The handle to a mutex semaphore.
Description This function exits an exclusive access section controlled by a mutex

semaphore. The next thread that is waiting on a call to
rm_syncEnterExcl will be given control.
Return Values None
See Also rm_syncEnterExcl
Example
/* update count of dumped blocks */
rm_syncEnterExcl(countSem);
++blockCount;
rm_syncExitExcl(countSem);

rm_syncReceiveQ
rm_syncReceiveQ Receive access permission for a quiescent semaphore
Syntax void rm_syncReceiveQ (RM_SEM handle)
Description This function is called by a reader thread to gain access to the shared
data controlled by a quiescent semaphore. If the semaphore is
disabled (that is, a writer thread currently has access), the calling
thread will be suspended until the semaphore is re-enabled. After
the function returns, the thread may access (safely read but not
safely modify) the shared data. The thread then calls
rm_syncSendQ to signal that it has completed its access.
Return Values None
See Also rm_syncDisableQ, rm_syncEnableQ, rm_syncSendQ,

rm_syncWaitQ
Example
Writer Thread

Reader Thread

rm_syncSendQ(qSem);

rm_syncResume
rm_syncResume Resume an event (signal event semaphore)
Syntax void rm_syncResume (RM_SEM handle)
Parameters handle [Input] The handle to an event semaphore.
Description This function sets the state of an event semaphore to signalled. All
threads that are hanging on a call to rm_syncWait will be released.
Return Values None
See Also rm_syncStart, rm_syncWait
Example
/* =====================================================================
Example thread
*/
static void RTHREAD Example(void *pTestQueue)
{
short testQueue;
RM_SEM doneSem;
void *pMsg;
unsigned long msgCount;
testQueue = *(short *)pTestQueue;

/* get next message */
rm_queueRead( testQueue, &pMsg, NULL, NULL, RM_QUEUE_WAIT );
... /* process message */
rm_syncResume(doneSem);
if ( ! pMsg )
break;
}
rm_threadEnd();
}

rm_syncSendQ
rm_syncSendQ Send reader exit notification for a quiescent semaphore
Syntax void rm_syncSendQ (RM_SEM handle)
Description This function is called by a reader thread when it has completed its
access to the shared data controlled by the quiescent semaphore. It
sends its exit notification status to the semaphore. If this is the only
reader thread and the semaphore is disabled, the writer thread
hanging on a call to rm_syncWaitQ will be released.
Return Values None
See Also rm_syncDisableQ, rm_syncEnableQ, rm_syncReceiveQ,

rm_syncWaitQ
Example
Writer Thread

Reader Thread

rm_syncSendQ(qSem);

rm_syncStart
rm_syncStart Start a new event (set the event semphore to non-signalled)
Syntax void rm_syncStart (RM_SEM handle)
Parameters handle [Input] The handle to an event semaphore.
Description This function starts an event by placing the event semaphore into a
non-signalled state. This means that any other thread calling
rm_syncWait will hang until some thread calls rm_syncResume.
Return Values None
See Also rm_syncResume, rm_syncWait
Example


rm_syncWait
rm_syncWait Wait for an event semaphore to be resumed
Syntax short rm_syncWait (RM_SEM handle, long timeout)
Parameters handle [Input] The handle to the event semaphore.

timeout [Input] The maximum wait time, in milliseconds. To
have an unlimited wait time, specify
RM_INDEFINITE_WAIT.
Description This function waits for the event semaphore to be signalled. If the
semaphore is already in a signalled state, the function returns
immediately. The semaphore remains signalled until some thread
calls rm_syncStart. Calling rm_syncResume signals the semaphore.
If the semaphore is not signalled, the calling thread will wait,
pausing up to the amount of time specified in the rm_syncWait call.
(If RM_INDEFINITE_WAIT is specified, the thread will wait
indefinitely.) If a timeout occurs, the function returns
RM_TIMEOUT.
Note: The initial state for an event semaphore is signalled.
Return Values RM_OKAY RM_TIMEOUT
See Also rm_syncResume, rm_syncStart
Example


rm_syncWaitQ
rm_syncWaitQ Wait for all readers to exit for a quiescent semaphore
Syntax short rm_syncWaitQ (RM_SEM handle, long timeout)

timeout [Input] The maximum wait time, in milliseconds. To
have an unlimited wait time, specify
RM_INDEFINITE_WAIT.
Description This function is called by a writer thread to wait for all currently
executing reader threads to complete. This function can be called
when the quiescent semaphore is not yet disabled. In that case, no
new rm_syncReceiveQ calls are blocked, but if the number of
readers drops to zero, the quiescent semaphore automatically
becomes disabled, and the call to rm_syncWaitQ returns.
Return Values RM_OKAY RM_TIMEOUT
See Also rm_syncDisableQ, rm_syncEnableQ, rm_syncReceiveQ,

rm_syncSendQ
Example
Writer Thread

Reader Thread

rm_syncSendQ(qSem);

rm_threadBegin
rm_threadBegin Initiate a new operating system thread
Syntax short rm_threadBegin (THREADFCN fcnAddr,

unsigned int stackSize, void *arg, short priority)
Parameters fcnAddr [Input] A pointer to the thread function. The

function must have the following prototype:
void RTHREAD ThreadFunctionName (void *arg);
stackSize [Input] The size, in bytes, of the stack allocated to
the thread.
arg [Input] A pointer to a value that is passed into the
thread function.
priority [Input] The thread priority indicator. Specify one of
the following values:
RM_THREAD_LOW
The thread yields to all waiting, normal or high-
priority threads.
RM_THREAD_NORMAL
The thread yields to all waiting, high-priority threads.
RM_THREAD_HIGH
The thread is serviced before threads of lower
priority.
Description This function can be used to launch a new thread. Your use of this
function is platform-independent and allows you to develop Velocis
application servers that are independent of platform.
The size of the stack allocated for the thread is typically a multiple of
1,024 bytes. (Velocis assigns a stack size of "2048 * sizeof(int)".) Be
careful to assign an ample amount, because a stack overwrite can
cause the server to fail with a general protection fault.
The thread priority values only affect scheduling behavior on
operating systems that support thread priorities, such as Windows.
Unless special requirements indicate otherwise, it is recommended
that you use normal priority (RM_THREAD_NORMAL).
Return Values 0 The thread was successfully launched

-1 The thread could not be launched
See Also rm_threadEnd

rm_threadBegin
Example
/* =====================================================================
Example thread
*/
{
short testQueue;
RM_SEM doneSem;
void *pMsg;

if ( ! pMsg )
break;
}
rm_threadEnd();
}
/* =====================================================================
Multi-threaded Velocis Standalone Test Program
*/
void main()
{
...
stat = rm_threadBegin(Example, 1024, &threadQueue, RM_THREAD_NORMAL);

if ( stat < 0 )
... /* error exit */
... /* call thread through threadQueue */

}

rm_threadEnd
rm_threadEnd Terminate thread execution
Syntax void rm_threadEnd (void)
Parameters None
Description This function terminates the calling thread.
Return Values None
See Also rm_threadBegin
Example
/* =====================================================================
Example thread
*/
{
short testQueue;
RM_SEM doneSem;
void *pMsg;

if ( ! pMsg )
break;
}
rm_threadEnd();
}

rm_zFreeMemory
rm_zFreeMemory Free allocated memory and clear its pointer
Syntax void rm_zFreeMemory (void *ptr, RM_MEMTAG tag)
Parameters ptr [Input] A pointer to the memory buffer to free.

tag [Input] The memory tag allocated in the original call
to rm_getMemory or rm_cGetMemory.
Description This function frees a block of memory allocated by rm_getMemory

or rm_cGetMemory. The rm_zFreeMemory function also sets the
memory pointer to NULL. This function is equivalent to the
following:
rm_freeMemory (ptr, 0);
ptr = NULL;
Note: The extension module must call rm_zFreeMemory instead of

free.
Return Values None
See Also rm_cGetMemory, rm_freeMemory, rm_getMemory

rm_zFreePool
rm_zFreePool Free a memory buffer pool
Syntax void rm_zFreePool (RM_POOL **pHPool)
Parameters pHPool [Input/Output] A pointer to the handle of the pool

to be freed.
Description This function frees all of the buffers contained in the buffer pool.
Any control information is also freed. The function sets the pool
handle to NULL.
Return Values None
See Also rm_allocPool
Example
RM_POOL *qPool;
...
/* free the message pool */
rm_zFreePool(&qPool);

Chapter 11
Administration API Functions
(s_ Prefix)
This chapter contains descriptions of the administration API functions, which are used in
server administration tasks. These functions have an s_ prefix.
Most administration API functions contain a parameter for a session identification
number, or session handle. This parameter has a data type of RDM_SESS (an unsigned,
short integer).
The administration API includes a programming interface the dbrepair toolkit, which
you can use to repair and perform maintenance on a database that is corrupted or
performing poorly. The dbrepair programming interface contains these functions:
• Five asynchronously run functions: s_dbcheckBegin, s_dbfixBegin,
s_keybuildBegin, s_dbdefragBegin, and s_dchainBegin. These functions perform
the same tasks as the dbrepair command-line utilities dbcheck, dbfix, keybuild,
dbdefrag, and dchain, respectively.
• The s_dbrGetStatus function, which returns the status of an asynchronously
executed dbrepair operation.
• The s_dbrEnd function, which terminates an asynchronously started function.
You can run several dbrepair operations during a session, but each operation can be
started only after the previous one has been terminated by a call to s_dbrEnd. Without
the termination function call, the operation is considered incomplete.
All functions in this chapter return short integers. The possible return codes have an
S_ prefix and are defined in rdserrs.h. These codes are described in Chapter 19 of this
manual.
Administration API Functions (s_ Prefix) 11-1

s_backupAttach
s_backupAttach Change from persistent to regular hot backup mode
Syntax short s_backupAttach (RDM_SESS hBackup, RDM_SESS hSess)
Parameters hBackup [Input] The handle to the detached backup session.

This value is obtained from an earlier call to
s_backupDetach.
hSess [Input] A session handle.
Description The s_backupAttach function moves the server from persistent hot
backup mode to regular hot backup mode. Only after a successful
call to this function can hot backup mode be terminated in the
normal way (through s_backupEnd or s_logout). (Alternatively, a
single function call to s_backupKill can end persistent hot backup
mode.)
The hBackup session handle must identify an internal session created
by an earlier call to s_backupDetach. The s_backupAttach function
transfers the internal session’s backup status to the session identified
by hSess, which can be different than the session handle passed
earlier to s_backupDetach. The session can then terminate hot
backup mode as if it had previously called s_backupBegin only.
Return Values S_INVSESS
See Also s_backupDetach, s_backupEnd, s_backupKill

s_backupBegin
s_backupBegin Start hot backup mode
Syntax short s_backupBegin (RDM_SESS hSess)
Description This function places the server in hot backup mode.

When s_backupBegin returns, the application can safely read any or
all database files controlled by the server. The database files are not
changed in any manner that affects the logical consistency of the
data. Other server files are changed, such as the last change log
(rXXXXXXX.chg), the checkpoint image file (rdm.chk), the hot
backup file (rdm.hot), and the swap file (rdm.swp); these files
should not be assumed to be in a logically consistent state.
Applications cannot use "quick" database open mode during hot
backup. The s_backupBegin function returns S_BUQUICK if any
databases are currently opened in quick mode, and d_open or
d_iopen returns S_BUACTIVE if a quick mode open is requested
while hot backup is active.
Return Values S_BUACTIVE S_DBACCESS S_NOMEMORY

S_BUQUICK S_FILEOPERR S_OKAY
S_BUTIMEOUT S_FILEWRERR S_PRIV
S_CATERR S_INVSESS
Privilege Required Administrator
See Also s_backupEnd, s_showBackupFiles

s_backupCacheGet
s_backupCacheGet Get the maximum number of hot file index pages for caching
Syntax short s_backupCacheGet (unsigned short *nopgs, RDM_SESS hSess)
Parameters nopgs [Output] A pointer to the number of cached index

pages.
Description This function retrieves the current value that specifies the maximum
number of hot file index pages that the Velocis server will cache
during hot backup.

S_PRIV
See Also s_backupCacheSet

s_backupCacheSet
s_backupCacheSet Set the maximum number of hot file index pages for caching
Syntax short s_backupCacheSet (unsigned short nopgs, RDM_SESS hSess)
Parameters nopgs [Input] The number of cached index pages to set.

Description This function allows you to change, before starting hot backup, the
size of the cache for the hot file index pages. Velocis allocates and
caches this amount in memory at the start of backup mode. If this
function is not called, Velocis uses the value of the
HotIndexCachePages configuration parameter in velocis.ini. To
retrieve the current cache size, use the s_backupCacheGet function.
Return Values S_BUACTIVE

S_OKAY
S_PRIV
See Also s_backupBegin, s_backupCacheGet

s_backupDetach
s_backupDetach Change from regular to persistent hot backup mode
Syntax short s_backupDetach (RDM_SESS *hBackup, RDM_SESS hSess)
Parameters hBackup [Output] The handle to the detached backup

session. This handle must be saved and used with
s_backupAttach to end persistent hot backup.
Description For a server currently in regular hot backup mode, the

s_backupDetach function changes that mode to persistent hot
backup. This change allows hot backup to continue after the last
client has logged out of Velocis. To end persistent hot backup
mode, you must return to regular hot backup mode (by calling
s_backupAttach) before ending hot backup in the normal manner
(by calling s_backupEnd). Alternatively, you can simply call
s_backupKill to end any hot backup mode unconditionally.
Regular hot backup mode is terminated when the Velocis database
engine shuts down. Therefore, if the only client is an administrator
that just initiated a hot backup (by calling s_backupBegin), the
client must remain logged in to prevent an engine shutdown.
Otherwise, Velocis may end regular hot backup mode when the
administrator logs out. To allow all clients to log out while keeping
hot backup mode active, s_backupDetach must be called to cause
the backup mode to persist.
The hBackup handle is the session handle of an internal Velocis
session that "owns" the backup. The session calling
s_backupDetach must already have started hot backup mode. To
terminate hot backup mode, any administrator session may use
hBackup in the s_backupAttach call to gain ownership from the
internal session. Then s_backupEnd (or s_logout) will cause the hot
backup to end. Note that if multiple clients have started hot backup
mode, the mode is not actually terminated until all of those clients
have terminated the mode.
Return Values S_BUNOTACTIVE
See Also s_backupAttach, s_backupBegin, s_backupEnd, s_backupKill,

s_logout

s_backupEnd
s_backupEnd Turn off hot backup mode
Syntax short s_backupEnd (RDM_SESS hSess, short flush)

flush [Input] The flush action flag. To skip the flushing of
changes, specify 0. To flush all changes to database
files, specify 1.
Description This function ends hot backup mode. If the flush flag is set, this
function calls s_backupFlush to flush the hot file. If the flush flag is
not set, the modified pages stored in the hot file will be written
gradually to the database files and removed from the hot file, as
they are read during normal server operation. Note that if multiple
clients have called s_backupBegin, all of them have to call
s_backupEnd before the backup mode is terminated.

S_OKAY
S_PRIV
See Also s_backupBegin, s_backupFlush

s_backupFlush
s_backupFlush Flush the hot file after backup is done
Syntax short s_backupFlush (RDM_SESS hSess)
Description This function flushes all changes made during the most recent
backup from the hot file to the database files. It can only be called
outside of backup mode (that is, after s_backupEnd has been
called).
Calling s_backupFlush is optional, because Velocis gradually writes
hot file changes back to the database files as they are accessed from
the hot file after the latest backup. However, calling this function
returns the system to normal operational mode as soon as possible.
Note that s_backupFlush forces the hot pages to migrate by reading
all hot pages into the database files and marking them as modified.
Velocis then uses its normal checkpoint process to write the hot
pages back to the database files.
Return Values S_BUACTIVE

S_OKAY
S_PRIV
See Also s_backupBegin, s_backupEnd

s_backupFreeFile
s_backupFreeFile Free the backup files
Syntax short s_backupFreeFile (long fileid, unsigned long addr,

RDM_SESS hSess)
Parameters fileid [Input] The ID of the file to free. This ID is assigned

by the s_showBackupFiles function.
addr [Input] The end address of the free region.
Description An application in backup mode may call this function to inform

Velocis that the file backup has been completed up to the address
addr within the file. The fileid parameter, which you obtain by
calling s_showBackupFiles, contains the file ID number for the
database file to be freed. If addr is zero, the entire file is freed. This
function allows Velocis to begin writing changed database pages for
the specified file directly to the database file (and migrating pages
already written to the hot file) before the backup has completed.
This minimizes the performance impact and the size of the hot file.
Return Values S_BUBADFILEID S_OKAY

S_BUNOTACTIVE S_PRIV
See Also s_showBackupFiles

s_backupKill
s_backupKill Terminate hot backup mode unconditionally
Syntax short s_backupKill (RDM_SESS hSess, short flush)

flush [Input] The flush flag. If this value is equal to 1, the
function flushes all changes to database files
immediately (by calling s_backupFlush). If flush is
equal to 0, s_backupKill flushes the changes
gradually during normal server operation.
Description This function is required when it is necessary to end hot backup

mode, regardless of the status of any client that started the mode.
An alternative to using this function is to shut down the server,
which also ends hot backup mode.
See Also s_backupAttach, s_backupDetach

s_dbAdd
s_dbAdd Add a database to the system catalog
Syntax short s_dbAdd (const DBD_DBF *regdbase, FILEDEV *filedev,

unsigned long bufflen, RDM_SESS hSess)
Parameters regdbase [Input] A pointer to a DBD_DBF structure (see

Chapter 18) holding the database definition. This
structure comprises a character pointer (dbdfiledev
field) and a dbase structure (db). The dbdfiledev field
contains the name of the device that stores the
database dictionary. The db structure contains two
pertinent fields: the database name (dbname) and a
flag for the database access level (dbaccess), where 0
means global access, and 1 means access that is
limited to a database access list.
filedev [Input] A pointer to an array of FILEDEV structures
defining the devices for the database files.
fname fdevice
bufflen [Input] The length, in bytes, of the device
information (filedev) buffer. Set this value to the
product of sizeof(FILEDEV) and the total number
of data and key files.
Description This function adds the specified database to the system catalog. It
also registers the data and key files that belong to the database,
which is required before any application can access the database.
Return Values S_DBEXISTS S_NODEV

S_INVSESS S_OKAY
Privilege Required None
See Also s_dbInit, s_dbUserAdd, s_dbUserDel, s_devAdd

DBD_DBF, dbase, FILEDEV (structures)

s_dbcheckBegin
s_dbcheckBegin Check database consistency asynchronously
Syntax short s_dbcheckBegin (char *dbname, short options,

short *recIDs, short *setIDs, long *keyfldIDs, long *blobfldIDs,
short cachepages, char *filename, RDM_SESS hSess)
Parameters dbname [Input] The name of the database to be checked for

consistency.
options [Input] The option flags. This parameter is a bit
map of the following values:
DBR_REPORT_SUMMARY
Sends only a summary report to the output file.
Otherwise, sends additional statistical
information.
DBR_SYSLOG_SUMMARY
Sends nothing to the system log except internal
error messages. Otherwise, reports on the start
and termination of the major steps of the
consistency checking process.
DBR_QUICKCHECK
Performs a quick scan check of the specified
database sets.
recIDs [Input] A pointer to a null-terminated array of
record type IDs. Only those database files
containing the records of the specified types will be
checked for consistency. The last element of the
array must be NULL_RECID. If your application
passes NULL in this parameter, all data files in the
database will be checked.
setIDs [Input] A pointer to a null-terminated array of set
type IDs. Only the database sets of the specified
types will be checked for consistency. The last
element of the array must be NULL_SETID. If your
application passes NULL in this parameter, all sets
in the database will be checked. If, in this
parameter, your application passes a pointer to an
array containing only the terminating element, no
sets will be checked for consistency.
keyfldIDs [Input] A pointer to a null-terminated array of key
field IDs. These IDs specify which keys will be
checked for consistency. If the ID of a key field is

s_dbcheckBegin
encountered in the array, then the key file

containing keys for this field will be checked for
consistency. The last element of the array must be
NULL_FLDID. If your application passes NULL in
this parameter, all key files in the database will be
checked. If, in this parameter, your application
passes a pointer to an array containing only the
terminating element, no keys will be checked for
consistency.
blobfldIDs [Input] A pointer to a null-terminated array of
BLOB field IDs. These IDs specify which BLOB files
will be checked for consistency. If the ID of a BLOB
field is encountered in the array, the BLOB file
containing BLOBs for this field will be checked for
consistency. The last element of the array must be
this parameter, all BLOB files in the database will be
checked. If, in this parameter, your application
terminating element, no BLOBs will be checked for
consistency.
cachepages [Input] The number of pages to be allocated in the
internal dbrepair cache for the operation. The
default is 64.
filename [Input] The name of the file on the user device
where the report containing the results of the
database checking will be sent. If your application
passes NULL in this parameter, no user report is
produced.
Description This function checks the consistency of the physical database

specified by dbname. Because the function switches the dbname
database to hot online mode, it does not require exclusive access to
the database. The function is executed asynchronously; it returns
immediately after the consistency check process has started.
You can obtain information about the current status of the
consistency checking process by calling the s_dbrGetStatus
function. You can abort this process at any time with a call to the
s_dbrEnd function. If the process is already complete, you still

s_dbcheckBegin
must call the s_dbrEnd function to make the session available for
the next dbrepair operation.
You can limit the check if you specify particular database elements
in the null-terminated arrays recIDs, setIDs, keyfldIDs, and blobfldIDs.
If these are not NULL, only records, sets, keys, and BLOBs of the
types specified in these parameters will be checked for consistency.
The consistency check performs the following:
• Validates the database address and type for each record of the
specified record types
• Checks the integrity of the delete chains
• Checks the integrity of sets
• Checks the integrity of BLOBs
• Checks for consistency between keys and their corresponding
field values in records
The database checking procedure scans the specified database to be
sure the record headers (containing the record ID, database address,
etc.) are valid, the key files are correct and are consistent with the
data files, and the set linkages and BLOB linkages are valid. During
its scan, the procedure validates the position of each record
occurrence and verifies the integrity of the delete chains. The set
consistency cannot be ascertained without record type and delete
chain validation. Therefore, the owner and the member records of
the checked sets are always verified for consistency, even if their
types are not explicitly specified in recIDs. The procedure reports
each inconsistency with a message indicating the nature of the
inconsistency and the file and location of the offending record, key,
or BLOB. It also can report some statistics on the scanned files. The
output is the user report sent to the output file specified by filename
on the user device. The system report is printed in the system log.
If DBR_QUICKCHECK is specified, the check operation is
performed in quick mode. In this mode, the check procedure does
not traverse sets for details of the corruption. Instead, for each set
type, it adds the member count in each owner record and counts the
total number of non-orphan member records. In a consistent
database, the totals must match. If a database is corrupted, there is a
good chance of a mismatch, and the utility reports an error. This
mode significantly reduces set verification time and is designed for
routine consistency checking, but it does not guarantee 100%
detection of all possible database corruption.

s_dbcheckBegin
Return Values S_DBRACTIVE S_DBRNOREPORT S_INVSESS

S_DBRBADDB S_INVFLD S_INVSET
S_DBRERROR S_INVREC S_OKAY
See Also dbcheck (utility)

s_dbClone
s_dbClone Create an instance (clone) from the existing database
Syntax short s_dbClone (const char *dbToClone, const char *cloneName,

const char *devname, short copyFiles, RDM_SESS hSess)
Parameters dbToClone [Input] The name of the existing database.

cloneName [Input] The name of the new database instance.
devname [Input] The name of the Velocis device where the
files associated with the new database instance will
be stored.
copyFiles [Input] The operation type indicator. To initialize
new database files automatically, use 0. To copy
old database files to the new database, use 1.
Description Calling this function from an administrative user’s session creates a

new instance of an existing database. A database instance shares the
database definition of the source database but has separate database
files. You can set the copyFiles flag to indicate that the new database
(cloneName) is to be initially created from a copy of the original
(dbToClone) database files. To copy the database files, s_dbClone
opens the database in exclusive access mode. If the function returns
S_DBINUSE, the database is open to other users, which means that
the database cannot be open in exclusive mode, and the new
instance will not be created. If copyFiles is not set, the new database
files are initialized.
Each instance of the same schema must be contained in a separate
device. To place particular files in different devices, run the rdsadm
utility (or Velocis Administrator on Windows) after creating the
new database instance.
Note: You can use s_dbClone to create database instances of a Core

database. For SQL databases, you must use the create database
instance SQL statement.
Return Values S_DBEXISTS S_NODB

S_DBINUSE S_NODEV
S_FILEOPERR S_OKAY
S_INVSESS S_PRIV

s_dbClone
See Also s_dbAdd

s_dbdefragBegin
s_dbdefragBegin Compress database files asynchronously
Syntax short s_dbdefragBegin (char *dbname, short options, short *recIDs,

long *blobfldIDs, short cachepages, char *filename,
RDM_SESS hSess)
Parameters dbname [Input] The name of the database whose files are to
be compressed.
DBR_REPORT_SUMMARY
Otherwise, sends extra statistical information.
DBR_SYSLOG_SUMMARY
and termination of the major steps of the
compression process.
DBR_SIMULATE
Produces only a report of the modifications
necessary to compress the specified files,
without performing the modifications.
DBR_IGNORE_DBA
Instructs the module to ignore defined fields of
type DB_ADDR. Use this mode when these
fields contain references to records in other
databases.
record type IDs. Only the database files containing
the records of the specified types are to be
compressed. The last element of the array must be
NULL_RECID. If your application passes NULL in
this parameter, all data files in the database will be
compressed. If, in this parameter, your application
terminating element, no data files are compressed.
will be compressed. If the ID of a BLOB field is
encountered in the array, the BLOB file containing
BLOBs for this field will be compressed. The last

s_dbdefragBegin
element of the array must be NULL_FLDID. If your

application passes NULL in this parameter, all
BLOB files in the database will be compressed. If,
in this parameter, your application passes a pointer
to an array containing only the terminating element,
no BLOB files will be compressed.
cachepages [Input] The number of pages (default 64) to allocate
in the internal dbrepair cache for the operation.
where the report about the compression process
will be sent. If your application passes NULL in
this parameter, no user report is produced.
Description This function opens the dbname database in exclusive mode and
compresses the database by removing the delete chain slots from the
data files and BLOB files. The function is executed asynchronously;
it returns immediately after the repairing process has started.
You can obtain information on the current status of the compression
process by calling the s_dbrGetStatus function. You can abort this
process at any time with a call to the s_dbrEnd function. If the
process has already terminated, you must call s_dbrEnd to make the
session available for the next dbrepair operation.
Normally, whenever a record is deleted from the database, it is
marked for reuse and put on the delete chain, but not physically
removed from the file. The database file compression procedure
moves records from the end of the file into the places occupied by
the deleted records, adjusting all pointers referring to the moved
records. It leaves no unused slots between valid records in the file.
A similar technique is used for BLOB files. By default, the operation
adjusts all values of type DB_ADDR in the database that refer to
moved records. However, if some record fields of type DB_ADDR
are considered database addresses in another database, you should
use the DBR_IGNORE_DBA option.

See Also dbdefrag (utility)

s_dbDel
s_dbDel Delete a database definition
Syntax short s_dbDel (const char *dbname, RDM_SESS hSess)
Parameters dbname [Input] The name of the database to delete.

Description This function removes the specified database from the system
catalog. Note that the function does not delete the associated
database files.
Return Values S_INVSESS S_OPENED

S_NODB S_PRIV
S_OKAY
See Also s_dbAdd, s_dbModify

s_dbfixBegin
s_dbfixBegin Repair a database asynchronously
Syntax short s_dbfixBegin (char *dbname, short options,

short *recIDs, short *setIDs, long *keyfldIDs, long *blobfldIDs,
short cachepages, char *dumpname, char *filename,
RDM_SESS hSess)
Parameters dbname [Input] The name of the database to be repaired.

DBR_REPORT_SUMMARY
information.
DBR_SYSLOG_SUMMARY
Sends only internal error messages to the system
log. Otherwise, reports on the start and
termination of the major steps of the repair
process.
DBR_SIMULATE
Produces only a report of the repair actions
without executing them.
record type IDs. Only the database files containing
the records of the specified types will be repaired.
The last element of the array must be
NULL_RECID. If your application passes NULL in
this parameter, all data files in the database will be
repaired.
setIDs [Input] A pointer to a null-terminated array of set
type IDs. Only the set pointers of the specified
types will be repaired. The last element of the array
must be NULL_SETID. If your application passes
NULL in this parameter, all set pointers in the
database will be repaired. If, in this parameter,
your application passes a pointer to an array
containing only the terminating element, no set
pointers will be repaired.
field IDs. These IDs specify which keys will be
repaired. If the ID of a key field is encountered in

s_dbfixBegin
the array, the key file containing keys for this field
will be repaired. The last element of the array must
be NULL_FLDID. If your application passes NULL
in this parameter, all key files in the database will
be repaired. If, in this parameter, your application
terminating element, no keys will be repaired.
are to be repaired. If the ID of a BLOB field is
encountered in the array, then the BLOB file
containing BLOBs for this field will be repaired.
The last element of the array must be
this parameter, all BLOB files in the database will be
repaired. If, in this parameter, your application
terminating element, no BLOBs will be repaired.
default is 64.
dumpname [Input] The name of the file on the user device
containing the dump of the corrupted records that
were removed from the database by the
s_dbfixBegin function. If your application passes
NULL in this parameter, no dump of the removed
records is produced.
filename [Input] The name of the file where the report
containing the results of the database consistency
check and the description of the database repairs is
to be sent. If your application passes NULL in this
parameter, no user report is produced.
performs the following actions:
• Runs the full consistency check of the database (equivalent to
dbcheck) to obtain detailed information on all cases of the
database’s corruption.

s_dbfixBegin
• Repairs the database using the information about the database’s

corruption obtained during the check phase.
The function is executed asynchronously. It returns immediately
after the repairing process has started.
You can obtain information on the current status of the repair
process by calling the s_dbrGetStatus function. You can abort this
process at any time with a call to the s_dbrEnd function. If the
process has already terminated, you must call the s_dbrEnd
function to make the session available for the next dbrepair
operations.
This function restores database integrity by deleting damaged
elements and adjusting the relationships between the remaining
valid records to take into account the deletion. Thus, the repair run
typically results in some loss of data, which can be saved in a dump
file.
The utility’s operation consists of three phases. In phase one
(diagnostics), the utility invokes the database consistency check
procedure in exclusive mode to obtain the database consistency
diagnostics (stored in an internal database).
In phase two (analysis), the utility analyzes the consistency report
and determines the appropriate repair actions. The repairs consist
of deleting unreliable records, repairing inconsistent sets, and
rebuilding corrupted indices and indices containing keys for
unreliable records. The following types of records are considered
unreliable:
• Records containing invalid set or member pointers
• Records with an invalid record ID or an incorrect value in the
database address field
• Records marked as deleted but not included in the delete chain
After removing the unreliable records, the procedure adjusts the
sets to account for the deleted records and eliminates other
inconsistencies detected in the sets.
In phase three (modification), the utility executes in a single pass the
stored repair actions. The utility also invokes the key build
procedure to rebuild the keys. Note that in simulation mode, phase
three does not actually modify anything in the database.

s_dbfixBegin
If the owner or a member of some set is specified among those to be

repaired in recIDs, the set itself will be repaired, regardless of
whether it is explicitly specified in setIDs.

See Also dbfix (utility)

s_dbGet
s_dbGet Retrieve a database definition
Syntax short s_dbGet (const char *dbname, DBD_DBF *dbase,

RDM_SESS hSess)
Parameters dbname [Input] The name of the database for which this
function retrieves a definition.
dbase [Output] A pointer to the DBD_DBF structure
containing the database definition.
Description This function retrieves a database definition for the specified

database. Your application can call s_showDbFiles to retrieve
information about the data and key files in the database.

S_NODB
S_OKAY
See Also s_dbAdd, s_showDbFiles

DBD_DBF (structure)

s_dbInit
s_dbInit Initialize a database
Syntax short s_dbInit (const char *dbname, RDM_SESS hSess)
Parameters dbname [Input] The name of a registered database to

initialize.
Description This function causes the server to initialize the specified registered
database. It first tries to open the database in exclusive access mode.
If this action is successful, the function calls s_dbInitfile to initialize
the data and key files associated with the database.
The s_dbInit function returns S_BUACTIVE if it is called during hot
backup mode. (In previous versions of Velocis, database files could
be changed whenever Velocis was in backup mode.)
Return Values S_DBINUSE S_NODB

S_FILEOPERR S_OKAY
S_INVSESS S_PRIV
S_BUACTIVE
See Also s_dbAdd, s_dbInitfile, s_login

s_dbInitfile
s_dbInitfile Initialize a database file
Syntax short s_dbInitfile (FILE_NO fileID, RDM_DB hDb)
Parameters fileID [Input] The file ID of the database file to initialize.

Description This function causes the server to initialize the specified database
file. Because this function initializes only one file, use s_dbInit if
you want initialize an entire database.
Return Values S_NOFILE

S_OKAY
S_PRIV
See Also s_dbAdd, s_dbInit

s_dbModify
s_dbModify Modify a database definition
Syntax short s_dbModify (const DBD_DBF *regdbase,

const FILEDEV *filedev, unsigned long bufflen,
RDM_SESS hSess)
Parameters regdbase [Input] A pointer to a DBD_DBF structure holding

the database definition.
filedev [Input] A pointer to an array of FILEDEV structures
defining the devices for the database files.
bufflen [Input] The length, in bytes, of the structure
indicated in the filedev parameter.
Description This function modifies the database definition. The function

changes the dbdfiledev and dbaccess fields in the dbase structure
included in the specified DBD_DBF structure in the system catalog.
It also modifies the fdevice fields of the FILEDEV structures.
Modifications are limited to the following:
regdbase.dbdfiledev The database device where dbname.dbd is
stored.
regdbase.db.dbaccess The database access flag. Set the flag to 1 if
database has a database access list. 0
indicates global access.
filedev[i].fdevice The name of the device for the file.
Return Values S_CATERR S_NODBEXISTS

S_FILEOPERR S_NODEV
S_INVSESS S_OKAY
S_NODB S_PRIV
See Also s_dbAdd, s_dbDel

s_dbrEnd
s_dbrEnd End a dbrepair operation
Syntax short s_dbrEnd (RDM_SESS hSess)
Description This function ends the dbrepair operation started in the session by
any of the following operations: s_dbcheckBegin, s_dbfixBegin,
s_keybuildBegin, s_dbdefragBegin, or s_dchainBegin. If the
operation is still in progress, the s_dbrEnd call aborts it. The
function closes the database processed in the operation and makes
the session handle available for new dbrepair operations.
Return Values S_DBRERROR S_INVSESS

S_DBRIDLE S_OKAY
See Also s_dbcheckBegin, s_dbdefragBegin, s_dbfixBegin, s_dchainBegin,

s_keybuildBegin

s_dbrGetStatus
s_dbrGetStatus Get the status of the current dbrepair operation
Syntax short s_dbrGetStatus (DBR_STATUS *status, void *buf,

unsigned long *buflen, RDM_SESS hSess)
Parameters status [Output] A pointer to a structure of the type

DBR_STATUS containing information on the
current status of the asynchronous dbrepair
process. The process must have been started
previously in the session with a call to
s_dbcheckBegin, s_dbfixBegin, s_keybuildBegin,
s_dbdefragBegin, or s_dchainBegin.
buf [Output] A pointer to the buffer of data
accumulated in the file. The file is the filename
parameter in the current asynchronously started
dbrepair operation.
buflen [Input/Output] A pointer to the length of the
buffer, buf. The function returns the actual size of
the data put into the buffer.
Description This function returns in the status structure the details of the current
status of the active dbrepair operation started in the session (with
hSess) by any of the following functions: s_dbcheckBegin,
s_dbfixBegin, s_keybuildBegin, s_dbdefragBegin, or
s_dchainBegin. The structure is defined as follows:
typedef struct _DBR_STATUS {
short terminated; /* contains 0 if the process is in
progress, 1 if completed normally, 2 if
terminated prematurely. Negative value
indicates an error and contains the
error code */
char fname[FILELEN]; /* contains name of the file currently
being processed */
unsigned long items; /* number of the file items
(records/nodes/pages) already processed */
short passno; /* number of the pass of the file currently
being executed */
unsigned long errors; /* number of errors found in the database */
} DBR_STATUS;
In addition, if the parameter buf is not equal to NULL, this function

will put into buf the next buflen bytes of data accumulated in the
report file filename specified in the related call of the current

s_dbrGetStatus
dbrepair operation. If the dbrepair operation is still in progress, the

terminated field contains 0. The positive value in terminated indicates
that the process has completed normally or has been aborted. A
negative value indicates an error and contains the error code.
Return Values S_DBRERROR S_INVSESS

S_DBRIDLE S_OKAY
See Also s_dbcheckBegin, s_dbdefragBegin, s_dbfixBegin, s_dchainBegin,

s_keybuildBegin

s_dbstat
s_dbstat Implement the dbstat utility
Syntax short s_dbstat (char *dbName, short optFlags, long maxBlock,

long blockSize, char *outFileName, RDM_SESS hSess)
Parameters dbName [Input] The name of the database to be analyzed.

optFlags [Input] A bit map of the on/off options. The option
indicators, preceded by the equivalent option
specifiers for the dbstat utility, are as follows:
-nb SKIP_BLOBS
Skips files that contain blobs.
-nd SKIP_DATA
Skips files that contain record data.
-nk SKIP_KEYS
Skips files that contain indexes.
-v VERBOSE_MODE
Activates the verbose mode.
maxBlock [Input] The maximum block size to consider for
page size modifications.
blockSize [Input] The increment size for the different page
size considerations.
outFileName [Input/Output] The name of the file containing the
results of the database analysis.
Description This function checks the physical allocation of records, indexes, and
blobs in database files. It determines the number of items per
database page for each database file and the amount of unused
space per file based on slack space between the record/slot sizes
and the slot/page sizes.
To implement the dbstat utility, s_dbstat loads and attaches the
internal extension module that performs the analysis. It also
detaches and unloads the module when it is finished processing.
Return Values S_OKAY S_PRIV
See Also dbstat (utility)

s_dbUserAdd
s_dbUserAdd Add a user to the database access list
Syntax short s_dbUserAdd (const char *user, const char *dbname,

short ownerdb, short permaccess, RDM_SESS hSess)
Parameters user [Input] The name of the database user.

dbname [Input] The name of the database.
ownerdb [Input] A flag indicating whether the user is the
database owner. If the user is the owner, specify 1;
otherwise, use 0.
permaccess [Input] A bit map indicating which access
permissions that a user has. Use the bitwise OR
("|") operator or addition to specify any
combination of these values:
1 Allow user to modify database records.
2 Allow user to create database records.
4 Allow user to delete database records.
Description This function adds a user to the access list for the specified database,
which has previously been designated "private" (see s_dbAdd).
Only users connected to the database access list can open the
database. All database users have a default of read access
(permaccess = 0) to the database, but only one user can be designated
as the owner of the database (ownerdb = 1).
Return Values S_INVSESS S_OWNEXIST

S_NOUSER S_PRIV
S_OKAY
See Also s_dbUserDel

s_dbUserDel
s_dbUserDel Delete a user from the database access list
Syntax short s_dbUserDel (const char *user, const char *dbname,

RDM_SESS hSess)
Parameters user [Input] The name of the database user to delete.

dbname [Input] The database name.
Description This function removes a user from the database access list for the
indicated database.

S_OKAY
S_PRIV
See Also s_dbUserAdd

s_dbUserGet
s_dbUserGet Retrieve the database access record for a user
Syntax short s_dbUserGet (const char *user, const char *dbname,

struct dbaccrec *dbaccrec, RDM_SESS hSess)
Parameters user [Input] The user name.

dbname [Input] The name of the database.
dbaccrec [Output] A pointer to the dbaccrec structure
containing the access record. See catalog.h for the
structure definition.
Description This function retrieves a database access record for the specified
user (user). The dbaccrec structure has two short integer fields,
permaccess and ownerdb, containing the values specified in the
s_dbUserAdd function call.
Return Values S_INVNULL S_NOTONLIST

S_INVSESS S_NOUSER
S_LONGNAME S_OKAY
See Also s_dbUserAdd, s_dbUserDel

s_dchainBegin
s_dchainBegin Repair delete chains asynchronously
Syntax short s_dchainBegin (char *dbname, short options,

short *recIDs, long *keyfldIDs, long *blobfldIDs,
Parameters dbname [Input] The name of the database whose files are to
be processed for delete chain repair.
DBR_REPORT_SUMMARY
information.
DBR_SIMULATE
Produces only a report of the modifications
necessary to repair the delete chains of the
specified files without actually performing these
modifications.
DBR_SYSLOG_SUMMARY
and termination of the major steps of the delete
chain repair process.
record type IDs. Only the delete chains of the data
files containing the records of the specified types
will be repaired. The last element of the array must
be NULL_RECID. If your application passes NULL
in this parameter, delete chains in all the data files
will be repaired. If, in this parameter, your
application passes a pointer to an array containing
only the terminating element, no delete chains in
the data files will be repaired.
field IDs. These IDs specify the key files where the
delete chains are to be repaired. If the ID of a key
field is encountered in the array, then the delete
chain of the key file containing that key will be
repaired. The last element of the array must be

s_dchainBegin
this parameter, the delete chains of all key files in

the database will be repaired. If, in this parameter,
your application passes a pointer to the array
containing only the terminating element, no delete
chain in the database key files will be repaired.
BLOB field IDs. These IDs specify the BLOB files
where the delete chains will be repaired. If the ID
of a BLOB field is encountered in the array, then the
delete chain of the BLOB file containing BLOBs for
this field will be repaired. The last element of the
array must be NULL_FLDID. If your application
passes NULL in this parameter, the delete chains of
all BLOB files in the database will be repaired. If, in
this parameter, your application passes a pointer to
an array containing only the terminating element,
no delete chain in the database BLOB files will be
repaired.
default is 64.
where the report about the repair process will be
sent. If your application passes NULL in this
rebuilds delete chains in the database files. The function is executed
asynchronously; it returns immediately after the repairing process
has started.
You can obtain information on the current status of the delete chain
rebuilding process by calling the s_dbrGetStatus function. You can
abort this process at any time with a call to the s_dbrEnd function.
If the process has already terminated, you have to call the s_dbrEnd
operation.
The delete chain rebuilding procedure creates a new chain by
connecting all records marked as deleted in the order of their
database addresses. The main purpose is to ensure that all records

s_dchainBegin
marked as deleted are included in the delete chain. A second

purpose is to reorder the delete chain so that the deleted records are
in database address order. This can make inserts more efficient, as
the same page with two contiguous deleted records is more likely to
be in memory if the delete chain is so ordered. This can reduce the
amount of swapping from the disk to the cache and thus increase
performance on inserts which reuse the deleted slots. The extent of
any performance improvement will depend upon the application. A
common use for s_dchainBegin is after a periodic purge of
particular record types that tend to be entered together, since these
would leave many contiguous record slots on the delete chain.

See Also dchain (utility)

s_devAdd
s_devAdd Add a device
Syntax short s_devAdd (struct device *dev, RDM_SESS hSess)
Parameters dev [Input] A pointer to a device structure (see

Chapter 18) containing the device definition. This
structure must contain a unique database device
name (devname) and the operating system’s path for
that database device (devpath).
Description This function adds (registers) a single device in the system catalog.
Devices are used to provide logical names for locations of files.
Caution: The path associated with a database device can optionally

contain a physical device. This path can be an absolute path or a
path that is relative to the current directory for the server. Relative
paths can be dangerous and should be used with caution.
Return Values S_BADPATH S_OKAY

S_DEVEXISTS S_PATHEXISTS
S_INVSESS S_PRIV
S_NOSPACE
See Also s_devModify, s_devDel

device (structure)

s_devAddEx
s_devAddEx Add (register) a logical device
Syntax short s_devAddEx (struct device *dev, short fCdrom,

RDM_SESS hSess)
Parameters dev [Input] A pointer to a device structure containing

the external device definition (see Chapter 18).
See s_devAdd for details of the use of this
structure.
fCdrom [Input] A flag indicating whether the device is
read-only (TRUE means the device is read-only).
Description This function adds (registers) a logical device in the system catalog.
If the fCdrom parameter is set to TRUE, the device is read-only (for
example, a CD-ROM device).
Return Values S_BADPATH S_OKAY

S_DEVEXISTS S_PATHEXISTS
S_INVSESS S_PRIV
S_NOSPACE
See Also s_devAdd

device (structure)

s_devDel
s_devDel Delete a device definition
Syntax short s_devDel (char *devname, RDM_SESS hSess)
Parameters devname [Input] The name of the device.

Description This function removes the definition of a device from the system
catalog. The function can only delete the device definition if it has
no associated items (for example, database files or extension
modules) connected to it. To disconnect associated items, the
application should use s_dbDel, s_userDel, and s_emDel.
Return Values S_DBASEMEMS S_NODEV

S_EMMEMS S_OKAY
S_FILEMEMS S_PRIV
S_INVSESS S_USERMEMS
See Also s_dbDel, s_devAdd, s_emDel, s_userDel

s_devGet
s_devGet Retrieve a device definition
Syntax short s_devGet (const char *devname, struct device *device,

RDM_SESS hSess)

device [Output] A pointer to the device structure, which
contains the device definition retrieved from the
system catalog. See s_devAdd for details.
Description This function retrieves the definition of the specified device from the
system catalog.

S_NODEV
S_OKAY
See Also s_devAdd, s_devDel, s_devModify

device (structure)

s_devGetEx
s_devGetEx Retrieve the definition of a logical device
Syntax short s_devGetEx (const char *devname, struct device *device,

short *pfCdrom, RDM_SESS hSess)

device [Output] A pointer to the device structure
containing the device definition retrieved from the
system catalog. See s_devAddEx for details.
pfCdrom [Output] A pointer to a flag indicating whether the
device is read-only (for example, a CD-ROM device
would return TRUE).
Description This function retrieves the definition of the specified logical device
from the system catalog.

S_NODEV
S_OKAY
See Also s_devAddEx, s_devModifyEx

device (structure)

s_devModify
s_devModify Change a device definition
Syntax short s_devModify (struct device *device, RDM_SESS hSess)
Parameters device [Input] A pointer to a device structure (see

Chapter 18) containing the device definition. See
s_devAdd for details.
Description This function changes the physical path associated with the
specified logical database device. Your application cannot use this
function to change the device name in the system catalog. To do
this, the application should call s_devDel to delete the device, then
add the new name with a call to s_devAdd.
Return Values S_BADPATH S_NODEV

S_CATERR S_NOSPACE
S_DBINUSE S_OKAY
S_FILEOPERR S_PATHEXISTS
S_INVSESS S_PRIV
See Also s_devAdd, s_devDel

device (structure)

s_devModifyEx
s_devModifyEx Change a logical device
Syntax short s_devModifyEx (struct device *device, short fCdrom,

RDM_SESS hSess)
Parameters device [Input] A pointer to the device structure (see

Chapter 18) containing the device definition. See
s_devAdd for details.
fCdrom [Input] A flag that indicates whether the device is
read-only (TRUE means that the device is
read-only).
Description This function changes the physical path associated with the
specified logical device. Your application cannot use this function to
change the device name in the system catalog. To do this, the
application should call s_devDel to delete the device, then add the
new name with a call to s_devAddEx.
Return Values S_BADPATH S_NODEV

S_CATERR S_NOSPACE
S_DBINUSE S_OKAY
S_FILEOPERR S_PATHEXISTS
S_INVSESS S_PRIV
See Also s_devAdd, s_devAddEx

device (structure)

s_emAdd
s_emAdd Add an extension module definition
Syntax short s_emAdd (EM_CHG *extmod, RDM_SESS hSess)
Parameters extmod [Input] A pointer to an EM_CHG structure that

contains the extension module definition. This
structure includes fields for a detailed module
description and the name of the device that holds
the extension module.
Description This function registers (adds) an extension module definition in the

system catalog. You must register an extension module before
accessing it from your application. When the application issues an
s_emGet call to the module, Velocis locates the module in the device
specified in the extmod parameter of this function.
Registration by s_emAdd does not include copying the extension
module file into the device named in the extmod parameter. You
must use the host operating system to do the actual file copy.
Return Values S_EMEXISTS S_OKAY

S_INVSESS S_PRIV
S_NODEV
See Also s_emDel, s_emGet, s_emModify

EM_CHG (structure)

s_emDel
s_emDel Delete an extension module definition
Syntax short s_emDel (char *extmod, RDM_SESS hSess)
Parameters extmod [Input] The name of the extension module to delete.

Description This function deletes an extension module definition from the

system catalog. Note, however, that the function does not delete the
extension module file.
Return Values S_INVSESS S_OKAY

S_NOEM S_PRIV
See Also s_emAdd

s_emGet
s_emGet Retrieve an extension module definition
Syntax short s_emGet (char *emkey, EM_CHG *extmod, RDM_SESS hSess)
Parameters emkey [Input] A pointer to a key to the name of the

extension module for which to retrieve information.
extmod [Output] A pointer to the EM_CHG structure
containing extension module information.
Description This function retrieves the definition of the specified extension

module from the system catalog.

S_NOEM
S_OKAY
See Also s_emAdd, s_emDel

s_emModify
s_emModify Change an extension module definition
Syntax short s_emModify (EM_CHG *extmod, RDM_SESS hSess)
Parameters extmod [Input] A pointer to the EM_CHG structure

containing the extension module definition. See
s_emAdd for a description of this parameter.
Description This function changes the device designated for the extension
module. Note that your application cannot call s_emModify to
change the extension module name. To make a name change, you
must first delete the extension module with a call to s_emDel and
then add it back with a new name (via s_emAdd).

S_NODEV S_PRIV
S_NOEM
See Also s_emAdd, s_emDel

EM_CHG (structure)

s_endRPCThreads
s_endRPCThreads Shut down the Velocis RPC/NCP subsystem
Syntax void s_endRPCThreads (void)
Parameters None
Description This function shuts down the Velocis remote procedure call (RPC)
and network control processor (NCP) subsystems. You must call
this function from your application server before calling
s_terminate, which shuts down the Velocis database engine.
Return Values None
See Also s_startRPCThreads, s_terminate
Example
...
stat = s_startRPCThreads("VELOCIS", 4, &shutdown_flag);

printf("Unable to start Velocis RPC server, status = %d\n", stat);
exit(1);
}
while ( ! shutdown_flag )
rm_sleep(5000L);
s_endRPCThreads();
s_terminate();
...

s_errinfo
s_errinfo Interpret an error code
Syntax short s_errinfo (short error, char *errbuf, short length,

RDM_SESS hSess)
Parameters error [Input] The value of the error code.

errbuf [Output] A detailed error message.
length [Input] The length, in bytes, of the error message
buffer.
Description This function returns the error message associated with the specified
Velocis error code. The location of the error code’s description is
returned by the errbuf parameter.

s_fileAddExt
s_fileAddExt Add an extension file
Syntax short s_fileAddExt (char *basedev, char *basefile, char *extdev,

char *extfile, RDM_SESS hSess)
Parameters basedev [Input] The name of the device containing the base
file.
basefile [Input] The name of the base file.
extdev [Input] The name of the device on which to store
the extension file.
extfile [Input] The name of the extension file to add.
Description This function adds an extension file to the specified base file, which
is contained on the Velocis device basedev. The new file will be
named extfile and will be located on the device extdev. The extension
file will be created once the base file has grown to the size equal to
its maximum file size limit. You can change the default base file size
limit as well as the extension file size limit by calling function
s_fileSetSizes.
Note: The s_fileAddExt function requires that there be no access to

the database when the function is called. If the database is open at
the time of the call, the function returns S_LOCKED.
Return Values S_FILEDEVICE S_OKAY

S_INVSESS S_PRIV
S_NODEV
See Also s_fileSetSizes

s_fileInfo
s_fileInfo Retrieve information about a single base/extension file
Syntax short s_fileInfo (char *basedev, char *basefile, short extno,

FILEINFO *pFileinfo, RDM_SESS hSess)
file.
extno [Input] The extension file number. Use 0 to specify
the base file.
pFileinfo [Output] A pointer to the FILEINFO structure that
contains the base/extension file parameters.
Description This function retrieves information about a specific extension file.

The extension file is specified by the extno parameter, although an
extno value of 0 actually requests information on the base file.
The base/extension file information is returned as a structure of the
type FILEINFO, defined in the adm.h header file as follows:
typedef struct {
char devname[SIZEOF_DEVNAME]; /* device name */
char filename[SIZEOF_RDS_FILENAME]; /* file name */
unsigned long maxsize; /* max file size (0=>OS limit) */
unsigned long cresize; /* initial (creation) size */
unsigned long extsize; /* file extend size */
unsigned long totsize; /* current total size of file */
} FILEINFO;
Return Values S_BADEXTNO S_NOTBASEFILE

S_BADEXTLIMIT S_OKAY
S_NODEV S_PRIV
S_NOFILE
See Also s_fileAddExt, s_fileSetSizes

s_fileMove
s_fileMove Move a file
Syntax short s_fileMove (char *olddev, char *filename, char *newdev,

RDM_SESS hSess)
Parameters olddev [Input] The name of the source device containing

the file.
filename [Input] The name of the file.
newdev [Input] The name of the target device
Description This function moves the specified file (either a base file or an
extension file) from its current device to the new one.
Return Values S_DBINUSE S_NODEV

S_FILEOPERR S_OKAY
S_INVSESS S_PRIV
See Also s_fileInfo

s_fileRecv
s_fileRecv Receive a file from the server
Syntax short s_fileRecv (char *filename, char *device, RDM_SESS hSess)
Parameters filename [Input] The name of the file to receive.

device [Input] The name of the database device containing
the file.
Description This function receives the specified file from the server database
device. The function places the retrieved file in the current
directory of the application, unless a path is also specified in the
filename.
Return Values S_FILEOPERR S_RPCINTERR

S_FILEWRERR S_RPCINVDATATYPE
S_NOLOGIN S_RPCINVFCN
S_NOMEMORY S_RPCINVSESSID
S_RPCENDOFPARMS S_SESDISCON
S_RPCINSERVICE
See Also s_fileSend

s_fileSend
s_fileSend Send a file to the server
Syntax short s_fileSend (char *filename, char *device, RDM_SESS hSess)
Parameters filename [Input] The name of the file to send.

device [Input] The name of the database device that
receives the file.
Description This function sends the specified file to the server database device.
The function retrieves the file to be sent from the current directory
of the application, unless a path is also specified in the filename.
Return Values S_FILEOPERR S_RPCINTERR

S_FILEWRERR S_RPCINVDATATYPE
S_NOLOGIN S_RPCINVFCN
S_NOMEMORY S_RPCINVSESSID
S_RPCENDOFPARMS S_SESDISCON
S_RPCINSERVICE
See Also s_fileRecv

s_fileSetSizes
s_fileSetSizes Modify the size settings of a file
Syntax short s_fileSetSizes (char *basedev, char *basefile, short extno,

unsigned long maxsize, unsigned long cresize,
unsigned long extsize, RDM_SESS hSess)
file.
extno [Input] The extension file number. Use 0 to specify
the base file.
maxsize [Input] The new maximum size of the extension file.
cresize [Input] The new creation size of the extension file.
extsize [Input] The new extension size of the extension file.
Description This function allows you to modify the maximum, creation, or

extension size of a base file (extno == 0) or an extension file
(extno > 0). If maxsize is less than the current amount of allocated
space on the file, or if the file is fully allocated to its current
maximum, the request is denied. The new extsize value takes effect
the next time the file is extended. The new cresize value is used the
next time the file is initialized.
Return Values S_BADEXTNO S_NOTBASEFILE

S_BADEXTLIMIT S_OKAY
S_NODEV S_PRIV
S_NOFILE
See Also s_fileAddExt, s_fileInfo

s_fileTotals
s_fileTotals Retrieve cumulative information on the base/extension file
Syntax short s_fileTotals (char *basedev, char *basefile, short *noexts,

double *maxsize, double *totsize, RDM_SESS hSess)
file.
noexts [Output] A pointer to the total number of extension
files.
maxsize [Output] A pointer to the maximum size, in bytes,
of the base file plus the extension files.
totsize [Output] A pointer to the current allocated size, in
bytes, of the base file plus the extension files.
Description This function returns the total number of extension files that were
attached to basefile on device basedev. It also returns the maximum
size and the total space used (in bytes) on basedev by basefile and its
extension files. The values that are returned in totused and maxsize
are exact double values (an 8-byte double has 15 significant digits).
NULL values can be specified for any of the output arguments.
Return Values S_CATERR S_OKAY

S_INVSESS S_PRIV
See Also s_fileAddExt, s_fileSetSizes

s_getDiskFreeSpace
s_getDiskFreeSpace Get the amount of free disk space
Syntax short s_getDiskFreeSpace (double *pAvail, char *devname,

RDM_SESS hSess)
Parameters pAvail [Output] A pointer to the amount of free space

more or less than the minimum threshold.
devname [Output] The name of the device that has the least
space available.
Description This function retrieves the minimum amount of free disk space that
is currently available and the name of the device that has the least
space. When more than one Velocis device is located on the same
physical device, all the devices have the same amount of free disk
space available at any time.
The s_getDiskFreeSpace function returns S_OKAY if the amount of
free disk space is above the minimum threshold. The function
returns S_NOSPACE if the amount of available disk space on a
Velocis device has fallen below the minimum threshold and the
server is now in read-only mode. In this case, s_getDiskFreeSpace
writes the amount of disk space below the threshold in the pAvail
parameter.
If the server has been in read-only mode (out of disk space) when
the application calls s_getDiskFreeSpace, but all Velocis devices are
currently above the minimum threshold, the server re-enables
updates. For example, the application might call
s_getDiskFreeSpace if it has just freed some disk space.

S_OKAY
See Also s_setMinFreeSpace

s_getTimeout
s_getTimeout Get the total minutes of inactive time allowed on a connection

before the server assumes that the client has disconnected
Syntax short s_getTimeout (unsigned short *timeout, RDM_SESS hSess)
Parameters timeout [Output] The time, in minutes, before the client is

aborted.
Description This function retrieves the number of minutes of inactivity that the
server allows on a client connection before assuming it is dead and
disconnecting it. This value is used whenever the server is unable to
detect a dead client. By default, Velocis does not timeout a
connection. See s_setTimeout for details on setting a timeout limit.
See Also s_setTimeout

s_iniGet
s_iniGet Get parameters from velocis.ini
Syntax short s_iniGet (char *section, char *entry, char *buffer, short length,
short flag, RDM_SESS hSess)
Parameters section [Input] The name, excluding the enclosing brackets,

of the velocis.ini section containing the parameters
to retrieve. Pass NULL if your application is
requesting a list of all section names in velocis.ini.
entry [Input] The name of the velocis.ini parameter to
retrieve. Pass NULL if your application is
requesting a list of all parameter names in section
that are defined in velocis.ini.
buffer [Output] Points to a character array to which the
parameter or parameters specified by entry are
copied. If section or entry is NULL, each parameter
is terminated with a null byte and an extra NULL is
appended to indicate the end of the list.
length [Input] The length, in bytes, of buffer.
flag [Input] A flag indicating whether to include the
values of the retrieved parameters. To retrieve only
the parameter names, specify 0; to retrieve a string
containing the names and their values (for example,
"MaxCachePages=700"), specify 1.
Description This function retrieves configuration parameters, a list of all

configuration parameters and their values, or a list of the names of
sections contained in velocis.ini. If your application needs to list
just the parameter names specified in velocis.ini, its call to s_iniGet
should specify NULL for the entry parameter. If the application
wants to list the velocis.ini sections only, the call to s_iniGet should
specify NULL for the section parameter. Each parameter in the list is
terminated with a null byte. Then the entire list is terminated by an
additional null byte.

s_iniGet
Return Values S_NOTFOUND S_OKAY
See Also s_iniGetPrivate, s_iniSet, s_iniSetPrivate

s_iniGetPrivate
s_iniGetPrivate Get parameters from a private initialization file
Syntax short s_iniGetPrivate (char *section, char *entry, char *buffer,

short length, short flag, char *devName, char *iniName,
RDM_SESS hSess)
Parameters section [Input] The name of the initialization file section

containing the parameters to retrieve. Note that the
section name does not include the brackets that are
used to specify the name in the initialization file.
Pass NULL if your application is requesting a list of
all section names in the initialization file.
entry [Input] The names of the initialization file
parameter to retrieve. Pass NULL if your
application is requesting a list of all parameter
names in section that are defined in the initialization
file.
buffer [Output] A pointer to a character array to which the
parameter or parameters specified by entry are
copied. If entry is NULL, each parameter is
terminated with a null byte.
length [Input] The length, in bytes, of buffer.
flag [Input] A flag indicating whether to include the
values of the retrieved parameters. To retrieve only
the parameter names, specify 0; to retrieve a string
containing the names and their values (for example,
"MaxCachePages=700"), specify 1.
devName [Input] The name of the Velocis device on which the
initialization file is stored.
iniName [Input] The name of the initialization file.
Description This function retrieves configuration parameters, a list of all

configuration parameters and their values, or a list of the names of
sections contained in a private initialization file. This function
works just like s_iniGet, except that it allows your application to
specify the name and location of the initialization file. The name of
the file specified in the iniName parameter can have any file
extension, although .ini is the usual convention.

s_iniGetPrivate
If your application needs to list just the parameter names specified

in the initialization file, its call to s_iniGetPrivate should specify
NULL for the entry parameter. If the application wants to list the
initialization file sections only, the call to s_iniGet should specify
NULL for the section parameter. Each parameter in the list is
terminated with a null byte. Then the entire list is terminated by an
additional null byte.
Return Values S_NOTFOUND

S_OKAY
See Also s_iniGet, s_iniSetPrivate

s_iniSet
s_iniSet Set parameters in velocis.ini
Syntax short s_iniSet (char *section, char *entry, char *value,

RDM_SESS hSess)
Parameters section [Input] The name of the velocis.ini section that

contains the parameter. Note that the section name
does not include the brackets that are used to
specify the name in the velocis.ini text file.
entry [Input] The name of the velocis.ini parameter to set.
This parameter can point to NULL or an empty
string.
value [Input] The value string (for example, "700") to set
for the specified parameter. This parameter can be
NULL.
Description This function adds, changes, or removes parameters in a particular

section of the velocis.ini file. If entry is NULL, the function deletes
the entire section from velocis.ini. If entry points to an empty
string, the function deletes all parameters defined in the section but
retains the section name in the velocis.ini file. If value is NULL, the
parameter is written as an empty assignment, which is basically a
placeholder for the parameter. An example of an empty assignment
is "MaxCachePages=".
Return Values S_FILEWRERR S_NOMEMORY

S_INVNULL S_OKAY
S_NODEV S_PRIV
S_NOFILE
See Also s_iniGet, s_iniGetPrivate, s_iniSetPrivate

s_iniSetPrivate
s_iniSetPrivate Set parameters in a private initialization file
Syntax short s_iniSetPrivate (char *section, char *entry, char *value,

char *devName, char *iniName, RDM_SESS hSess)
Parameters section [Input] The name of the initialization file section

that contains the parameter. Note that the section
name does not include the brackets that are used
to specify the initialization file name.
entry [Input] The name of the initialization file
parameter to set. This parameter can be NULL or
point to an empty string.
value [Input] The value string (for example, "700") to set
for the specified parameter. This parameter can
be NULL.
devName [Input] The name of the Velocis device on which
the initialization file is stored.
iniName [Input] The name of the initialization file.
Description This function adds, changes, or removes parameters in a particular

section of a private initialization file. This function works just like
s_iniSet, except that it allows your application to specify the name
and location of the initialization file. The name of the file specified
in the iniName parameter can have any file extension, although .ini
is the usual convention.
If entry is NULL, the function deletes the entire section from the
initialization file. If entry points to an empty string, the function
deletes all parameters defined in the section but retains the section
name in the file. If value is NULL, the parameter is written as an
empty assignment (for example, "MaxCachePages="), which is
basically a placeholder for the parameter.
Return Values S_FILEWRERR S_NOFILE S_PRIV

S_INVNULL S_NOMEMORY
S_NODEV S_OKAY
See Also s_iniGetPrivate, s_iniSet

s_keybuildBegin
s_keybuildBegin Build asynchronous key files
Syntax short s_keybuildBegin (char *dbname, short options, long *keyfldIDs,

Parameters dbname [Input] The name of the database whose indexes

(key files) are to be rebuilt.
DBR_REPORT_SUMMARY
information.
DBR_SYSLOG_SUMMARY
and termination of the major steps of the key
rebuilding process.
field IDs. These IDs specify which indexes (B-trees)
are to be rebuilt. If the ID of a key field is
encountered in the array, then the indexes
containing keys for this field will be rebuilt. The
last element of the array must be NULL_FLDID. If
your application passes NULL in this parameter, all
indexes in the database will be rebuilt. If, in this
parameter, your application passes a pointer to an
array containing only the terminating element, no
indexes will be rebuilt.
default is 64.
where the report about the rebuilding process will
be sent. If your application passes NULL in this
rebuilds indexes contained in the database key files. The function is

s_keybuildBegin
executed asynchronously; it returns immediately after the repairing

process has started.
You can obtain information on the current status of the key build
process by calling the s_dbrGetStatus function. At any time you
can abort this process with a call to the s_dbrEnd function. If the
process has already been terminated, you must call the s_dbrEnd
operation.
Rebuilding indexes is a two-step process. First, the key file is
reinitialized. Then each record is sequentially read from each data
file record and each key is re-created from the record contents as an
entry in the corresponding index. You can do a rebuild of only
specific indexes.
The s_keybuildBegin function can be used to re-create indexes
when the consistency check procedure reports a database
inconsistency. It can also construct new indexes after you add or
remove key attributes from fields in your DDL specification. For
example, if you make an existing key field a non-key and change a
non-key to a key field in your DDL, you can run s_keybuildBegin
to rebuild indexes for the new schema. You can also use the
function to reassign key fields to different key files.

See Also keybuild (utility)

s_log
s_log Write a message to the system log
Syntax short s_log (short type, char *msg, RDM_SESS hSess)
Parameters type [Input] The message type indicator. Specify one of

the following.
LOG_EM Extension module load/unload messages
msg [Input] The text message.
Description This function sends the message to the server’s (or application
server’s) log function. The default log function writes the specified
message to the console and the system log (RDS.log).

s_login
s_login Log into a server
Syntax short s_login (char *ConnName, char *userName, char *userPW,

RDM_SESS *hSess)
Parameters ConnName [Input] The connection alias name.

userName [Input] The name of the database user.
userPW [Input] The user’s password.
hSess [Output] A pointer to the session handle.
Description This function logs into the server through the Core API
(d_ functions). Note that user names and passwords are case-
sensitive. When the login is complete, s_login returns the session
handle for the application to use in subsequent calls. Connection
aliases must be defined in the connect.ini file on the client machine.
See Chapter 2 of the Velocis Installation and Administration Guide.
Return Values S_CATTIME S_OKAY

S_INVNULL S_PASSWORD
S_NOLOGIN S_USERNAME
See Also s_logout

s_logout
s_logout Log out from a server
Syntax short s_logout (RDM_SESS hSess)
Description This function logs out the application from the server associated
with the session indicated by the hSess parameter. The hSess server
handle will no longer be valid (that is, it can no longer be used to
access the server).
If the hSess session holds active transactions or open databases, they
will be cleaned up. Uncommitted transactions will be aborted.

S_OKAY
See Also s_login

s_ping
s_ping Check for an available Velocis server
Syntax short s_ping (char *server, unsigned long count, unsigned long pktsz,
pPING_CALLBACK pingBack, void *ptr)
Parameters server [Input] The name of a Velocis server to ping.

count [Input] The number of pings to issue.
pktsz [Input] The size of the network message packet to
send with each ping. If pktsz is 0, s_ping uses a
random packet size.
pingBack [Input] A pointer to a callback function that s_ping
must call after each attempt to ping the server. You
may specify NULL if you do not want to use a
callback function.
ptr [Input] A pointer that will be passed by s_ping to
the callback function. You may specify NULL.
Description This function determines whether a particular Velocis server is

available on the network. The function returns S_NOTFOUND if
the server is not found.
You can pass to s_ping a pointer to a callback function (pingBack),
which s_ping will call after each attempt to ping the server. The
s_ping function repeatedly calls the callback function until count
iterations or the callback function returns FALSE. A function
prototype for this callback function is as follows:
short REXTERNAL pingBack (short n_stat, short cnt,
unsigned short sndsz, unsigned short rcvsz, void *ptr);
The n_stat parameter is the status code returned from the Velocis
Network Communications Processor (NCP). Typical return values
are:
S_INVSVRNAME S_OKAY
S_NINTERR S_SVRUNAVAIL
The cnt parameter contains the current s_ping iteration count. The
size of the send and receive message packets are contained in sndsz
and rcvsz. The pointer (ptr) is the same ptr value that was originally
passed to s_ping. This can be used to store context information (for
example, s_ping result statistics).

s_ping
Return Values S_NOTFOUND S_OKAY
See Also s_shutdown

s_setMinFreeSpace
s_setMinFreeSpace Set the minimum amount of free disk space
Syntax short s_setMinFreeSpace (double minFree, RDM_SESS hSess)
Parameters minFree [Input] A new value, in bytes, for the minimum free
disk space threshold. The default is 5 MB.
Description This function dynamically sets the minimum amount of free disk
space threshold value. If the amount of available disk space for any
device falls below the server-wide threshold set in this parameter,
Velocis enters read-only mode. In this mode, Velocis returns
S_NOSPACE from all database create, modify, and delete function
calls.
The free disk space threshold set by your application must be large
enough to accommodate the largest checkpoint. If the threshold is
too low for a checkpoint to occur, the server shuts down. To find
out the current free disk space threshold value, your application can
call s_getDiskFreeSpace.
As an alternative to calling s_setMinFreeSpace in your application,
if you have administrative privileges, you can change the free disk
space threshold through admin or rdsadm. Procedures for doing
this are provided in the Velocis Installation and Administration Guide.
Note: All Velocis devices that are stored on the same physical
device have the same amount of free space available at any time.

S_OKAY
See Also s_getDiskFreeSpace

s_setTimeout
s_setTimeout Set the total amount of inactive time allowed on a connection before
the server assumes that the client has disconnected
Syntax short s_setTimeout (unsigned short timeout, RDM_SESS hSess)
Parameters timeout [Input] The time, in minutes, before the client is

aborted.
Description This function sets the number of minutes of inactivity that the server
allows on a client connection before disconnecting it. ("Inactivity" is
the total time elapsed since the server received a message from the
client.) By default, the server waits until the network informs it of a
client disconnection. If you want to set the timeout with this
function, you must call s_login before calling s_setTimeout. (If
multiple sessions are started, a separate timeout may be established
for each.)
Velocis depends on the network transport layer to inform the server
of a client disconnection (because of premature exit, power loss, or
abnormal termination). Under some circumstances, the transport
fails to inform the Velocis server, and although the client program
no longer exists, the server still maintains a session for the client.
Velocis does not automatically specify a timeout limit, so there are
no default restrictions on inactive time. To set a default value, you
may add a parameter to the connect.ini file used by the client. In
the [Configuration] section, add the following:
[Configuration]
ClientTimeout=XX
The XX parameter is the default number of minutes of inactivity

that any session started by this client has before the server
automatically aborts it. Calling s_setTimeout will override this
default only for the session for which the function is called.
See Also s_getTimeout

s_showBackupFiles
s_showBackupFiles Return a list of all Velocis backup files
Syntax short s_showBackupFiles (short pos, unsigned long nelems,

char **flist, char *fbuf, unsigned long buflen, long *fileids,
unsigned long *outelems, RDM_SESS hSess)
Parameters pos [Input] A flag that indicates how to show the

backup files. Possible values are:
FETCHFIRST Always set on the first call.
FETCHNEXT Set for successive calls to the function.
nelems [Input] The number of elements to retrieve.
flist [Output] A pointer to an array of nelems pointers to
the retrieved file names.
fbuf [Output] A pointer to the file names.
buflen [Input] The length, in bytes, of the buffer specified
by fbuf.
fileids [Output] A pointer to an array of nelems file ID
numbers. Each file ID number is a composite of the
database ID and the file number.
outelems [Output] A pointer to the actual number of
elements retrieved (<= nelems).
Description This function is used to retrieve the fully-qualified names of all

database files associated with the Velocis server and connected
through hSess. The function must be called after the s_backupBegin
function. To retrieve all the information, successive calls to
s_showBackupFiles may be required.
The flist parameter is an array of size nelems of char pointers. This
function will assign each pointer to point to a file name string
contained in fbuf, which is a character array of length buflen. Up to
nelems number of file names will be stored until either fbuf is full or
there are no more files. The outelems parameter will contain the
actual number of file names stored in fbuf.
The buflen parameter should be set to (nelems * FULLPATHLEN).
The fileids array contains a corresponding file ID number for each
file returned in flist. This value may be passed to the
s_backupFreeFile function to identify the file being freed.

s_showBackupFiles
Successive calls should be made until s_showBackupFiles returns

S_NOTFOUND. The pos parameter should be set to FETCHFIRST
on the first call, and set to FETCHNEXT for each subsequent call.
Return Values S_BUNOTACTIVE S_OKAY

S_NOTFOUND S_PRIV
See Also s_backupBegin, s_backupFreeFile

s_showDbFiles
s_showDbFiles Show a list of database files
Syntax short s_showDbFiles (char *dbname, short pos, unsigned long nelems,
void *buf, unsigned long buflen, unsigned long *actualelem,
RDM_SESS hSess)
Parameters dbname [Input] The database name.

pos [Input] A flag indicating which set of database files
to be retrieved. Specify FETCHFIRST or
FETCHNEXT to fetch the first or the next set of
files, respectively.
buf [Output] A pointer to an array of FILEDEV
structures containing the retrieved information.
buflen [Input] The length, in bytes, of the structure array
buffer. Set this value to (nelems * sizeof(FILEDEV)).
actualelem [Output] A pointer to the number of elements
actually retrieved.
Description This function retrieves the names of files and devices that are
associated with the database dbname. If the value of actualelem is
equal to the value of nelems, indicating that there is more
information to gather, your application needs to make additional
calls to retrieve all the information. For each of these follow-up
calls, the application needs to set pos to FETCHNEXT.
Return Values S_INVNULL S_NODB

S_INVSESS S_OKAY
See Also s_dbGet

s_showDbFiles
Example
FILEDEV dbarrayfiles[50];
void *buf;
buf = (void *) dbarrayfiles;

istat = s_showDbFiles(dbname, FETCHFIRST, 50, buf,
(50*sizeof(FILEDEV)), &actualelem, hSess);

s_showDbs
s_showDbs Show a list of registered databases
Syntax short s_showDbs (short pos, unsigned long nelems, void *buf,
unsigned long buflen, unsigned long *actualelem,
RDM_SESS hSess)
Parameters pos [Input] The set of registered databases to be

retrieved. Specify FETCHFIRST or FETCHNEXT to
fetch the first or the next set of databases,
respectively.
buf [Output] A pointer to an array of character strings
containing the database names.
buflen [Input] The length, in bytes, of the database name
buffer. Set this value to
(nelems * SIZEOF_DBNAME).
actually retrieved.
Description This function retrieves the names of databases registered in the

system catalog. If the value of actualelem is equal to the value of
nelems, indicating that there is more information to gather, your
application needs to make additional calls to retrieve them. On
these follow-up calls, the application should set pos to FETCHNEXT.
See Also s_dbGet
Example
void *buf;
char dbarray[50][SIZEOF_DBNAME];
/* Can hold up to 50 database names */
buf = (void *)dbarray;

istat = s_showDbs(FETCHFIRST, 50, buf,
(50 * SIZEOF_DBNAME), &actualelem, hSess);

s_showDbUsers
s_showDbUsers Show a list of users registered to a private database
Syntax short s_showDbUsers (char *dbname, short pos,

unsigned long nelems, void *buf, unsigned long buflen,
unsigned long *actualelem, RDM_SESS hSess)
Parameters dbname [Input] A private database name.

pos [Input] The set of database users to be retrieved.
Specify FETCHFIRST or FETCHNEXT to fetch the
first or the next set of user names, respectively.
containing the names of the database users.
buflen [Input] The length, in bytes, of the user name
(nelems * SIZEOF_USERNAME).
actually retrieved.
Description This function retrieves the names of users registered to a private

database. Only users added via s_dbUserAdd can have access to a
private database. If the value of actualelem is equal to the value of
application needs to make additional calls to retrieve them. On
these follow-up calls, the application should set pos to FETCHNEXT.
Return Values S_INVNULL S_NODB

S_INVSESS S_OKAY
See Also s_dbUserAdd

s_showDbUsers
Example
void *buf;
char *dbname = "tims";
char userarray[50][SIZEOF_USERNAME]; /* Can hold up to 50 users */
buf = (void *) userarray;

istat = s_showDbUsers(dbname, FETCHFIRST, 50, buf,
(50 * SIZEOF_USERNAME), &actualelem, hSess);

s_showDevs
s_showDevs Show a list of registered devices
Syntax short s_showDevs (short pos, unsigned long nelems, void *buf,
RDM_SESS hSess)
Parameters pos [Input] The set of registered devices to be retrieved.

first or the next set of devices, respectively.
containing the device names.
buflen [Input] The length, in bytes, of the device name
(nelems * SIZEOF_DEVNAME).
actually retrieved.
Description This function retrieves the names of registered devices in the system
catalog. If the value of actualelem is equal to the value of nelems,
indicating that there is more information to gather, your application
needs to make several calls to retrieve all the information. On these
follow-up calls, the application should set pos to FETCHNEXT.
See Also s_devGet
Example
void *buf;
char devarray[50][SIZEOF_DEVNAME]; /* Holds up to 50 device names */
buf = (void *) devarray;

istat = s_showDevs(FETCHFIRST, 50, buf,
(50 * SIZEOF_DEVNAME), &actualelem, hSess);

s_showEms
s_showEms Show a list of registered extension modules
Syntax short s_showEms (short pos, unsigned long nelems, void *buf,
RDM_SESS hSess)
Parameters pos [Input] The set of registered extension modules to

be retrieved. Specify FETCHFIRST or FETCHNEXT
to fetch the first or the next set of extension module
names, respectively.
buf [Output] A pointer to an array character strings
containing the extension module names.
buflen [Input] The length, in bytes, of the buffer containing
the names of the extension modules. Set this value
to (nelems * SIZEOF_EMNAME).
actually retrieved.
Description This function retrieves the names of extension modules registered in

the system catalog. If the value of actualelem is equal to the value of
application needs to make additional calls to retrieve all the
information. On these follow-up calls, the application should set pos
to FETCHNEXT.
See Also s_emAdd
Example
void *buf;
char extmodarray[50][SIZEOF_EMNAME];
/* Can hold up to 50 extension module names */
buf = (void *) extmodarray;.

istat = s_showEms(FETCHFIRST, 50, buf,
(50 * SIZEOF_EMNAME), &actualelem, hSess);

s_showUserDbs
s_showUserDbs Show a list of private databases accessible to a specific user
Syntax short s_showUserDbs (char *usrname, short pos,

unsigned long nelems, void *buf, unsigned long buflen,
unsigned long *actualelem, RDM_SESS hSess)
Parameters usrname [Input] The user name.

pos [Input] A flag that indicates how to show the
registered private databases accessible to the user.
first or the next set of private database names,
respectively.
containing the database names.
buflen [Input] The length, in bytes, of the database name
buffer (buf). Set this value to
(nelems * SIZEOF_DBNAME).
actually retrieved.
Description This function retrieves the names of private databases accessible to

the specified user. Only the users that were added via
s_dbUserAdd can have access to a private database. If the value of
actualelem is equal to the value of nelems, indicating that there is
more information to gather, your application needs to make
additional calls to retrieve all the information. On these follow-up
calls, the application should set pos to FETCHNEXT.
Return Values S_INVNULL S_NOUSER

S_INVSESS S_OKAY
See Also s_dbUserAdd, s_showDbUsers

s_showUserDbs
Example
void *buf;
char dbarray[50][SIZEOF_DBNAME];
/* Can hold up to 50 database names */
buf = (void *) dbarray;

istat = s_showDbs(FETCHFIRST, 50, buf,
(50 * SIZEOF_DBNAME), &actualelem, hSess);

s_showUsers
s_showUsers Show a list of registered users
Syntax short s_showUsers (short pos, unsigned long nelems, void *buf,
RDM_SESS hSess)
Parameters pos [Input] A flag indicating that indicates the set of

user names to be retrieved. Specify FETCHFIRST
or FETCHNEXT to fetch the first or the next set of
user names, respectively.
containing the user names.
buflen [Input] The length, in bytes, of the user name
(nelems * SIZEOF_USERNAME).
actually retrieved.
Description This function retrieves the names of database users registered in the
system catalog. If the number of elements retrieved matches the
number requested, there is more information to gather, and your
application needs to make additional calls (with pos set to
FETCHNEXT) to retrieve the remaining information.
See Also s_userGet
Example
void *buf;
char userarray[50][SIZEOF_USERNAME]; /* Holds up to 50 user names */
buf = (void *) serverarray;.

istat = s_showUsers(FETCHFIRST, 50, buf,
(50 * SIZEOF_USERNAME), &actualelem, hSess);

s_shutdown
s_shutdown Shut down the Velocis server
Syntax short s_shutdown (char *serverName, char *userName, char *userPW)
Parameters serverName [Input] The name of server to shut down.

userName [Input] The user name for the system administrator.
userPW [Input] The password for the administrator.
Description This function allows an application with administrative privileges to

shut down the identified server. The server shuts down without
notice to other client applications using the server. The return of
S_OKAY from s_shutdown indicates that the shutdown request has
been successfully processed, but it not necessarily indicate that the
server is actually shut down. Your application can call s_ping to
verify that the shutdown is complete.
Return Values S_CATTIME S_PASSWORD

S_LOCKED S_PRIV
S_NOLOGIN S_USERNAME
S_OKAY
See Also s_ping

s_startRPCThreads
s_startRPCThreads Start the Velocis RPC/NCP subsystem and initiate session threads
Syntax short s_startRPCThreads (char *servername, short numSessThreads,

short *shutdownFlag)
Parameters servername [Input] The name of the server to start.

numSessThreads [Input] The number of threads in the session thread
pool.
shutdownFlag [Input] A pointer to the shutdown flag. This
parameter is required for the s_shutdown function
to work. To disable the use of s_shutdown, specify
NULL.
Description This function is called from an application server to start the Velocis
remote procedure call (RPC) and network control processor (NCP)
subsystems. This allows standard Velocis client programs,
including third-party ODBC tools that use the Velocis ODBC driver,
to access the Velocis database controlled by your application server.
Velocis maintains a pool of threads to process calls from the user
login sessions. There can be many more user sessions than session
threads. You need to specify the number of session threads in the
pool.
The function can be passed a pointer to a shutdown flag, which
Velocis sets to 1 when a system shutdown has been requested. A
system shutdown is requested when some administrative user has
called the s_shutdown function or used the shutdown command on
the admin or rdsadm utility. Initialize the flag to 0 before calling
s_startRPCThreads. Specifying NULL for the shutdown flag will
disable the s_shutdown function and the shutdown commands in
the admin and rdsadm utilities.
Return Values S_INVPARM S_OKAY
See Also s_endRPCThreads, s_shutdown, s_startup

s_startRPCThreads
Example
static short shutdown_flag; /* static, so it’s initialized to 0 */
...
stat = s_startRPCThreads("VELOCIS", 4, &shutdown_flag);

exit(1);
}
rm_sleep(5000L);
s_endRPCThreads();
...

s_startup
s_startup Start the Velocis database engine
Syntax short s_startup (char *catpath, RMLOGFCN *logFcn, short msgTypes)
Parameters catpath [Input] The path name of the catalog directory. If

NULL is specified, the catalog directory is
determined from the CATPATH environment
variable. If CATPATH is undefined, the catalog is
assumed to be in the current directory.
logFcn [Input] A pointer to a function that handles Velocis
log messages. To simply output all log messages to
RDS.log and to standard output (stdout), specify
NULL. Otherwise, the function must have the
following prototype:
void REXTERNAL LogFunctionName
(RDSLOG_CTRL ActionTypeIndicator,
short MessageTypeIndicator,
char *LogMessage);
msgTypes [Input] A bit map of indicators that show which
message types to log. Specify any combination of
the indicators listed below:
LOG_EM Extension module load/unload messages
Description This function starts the Velocis database engine. It must be the first
Velocis function called from a server-based application program
that uses Velocis (that is, the application server). It is not necessary
to call this function from a standard Velocis client-based program.
An alternative directory path for the Velocis catalog may be
specified.
You may choose to have a custom function to handle Velocis log
messages. The custom function requires three things: an indicator
for the type of action being done, indicators for the types of

s_startup
messages to log, and the message itself. It must be able to handle

these action type indicators:
RMLOG_CLOSE Specifies a close message log. This is
passed once, at shutdown, to allow the
function to close any files or windows
associated with the message log.
RMLOG_MESSAGE Indicates that a message is to be logged.
This is passed whenever Velocis generates a
message matching a message type specified
in the s_startup call.
RMLOG_OPEN Specifies an open message log. This is
passed once, at startup, to allow the
function to open any files or windows to
which subsequent log messages will be
output.
The message type indicators that can be passed to the custom
function are the same as the ones used in s_startup. The actual
message passed to the custom function is simply a character string.
Return Values S_CATERR S_NOCATALOG

S_CATLOCKED S_OKAY
See Also rm_startup, s_startRPCThreads, s_terminate

s_startup
Example

...
stat = s_startup(NULL, MessageConsole, LOG_ALL);
printf("Unable to start Velocis engine, status = %d\n", stat);
exit(1);
}
...
/* Log Velocis console message

*/
void MessageConsole(
RDSLOG_CTRL fcn, /* call type: open, close, message */
short type, /* message type */
char *msg) /* message to be logged */
{
static FILE *errlog;
switch ( fcn ) {
case RDSLOG_OPEN:
errlog = fopen("velocis.log", "w");
break;
case RDSLOG_MESSAGE:
if ( type == LOG_ERROR ) {
/* make sure this gets noticed */
fprintf(errlog, "******* ERROR! ******* ");
printf("******* ERROR! ******* ");
}
fprintf(errlog, "%s\n", msg);
printf("%s\n", msg);
break;
case RDSLOG_CLOSE:
fclose(errlog);
break;
}
}

s_statistics
s_statistics Gather statistics from the server
Syntax short s_statistics (long *stats, short buflen, RDM_SESS *hSess)
Parameters stats [Output] A pointer to an array of long statistic

counters.
buflen [Input] The length, in bytes, of the stats buffer.
There are N_STATS counters. To retrieve the entire
statistics buffer, this parameter should be assigned a
value of N_STATS * sizeof(long).
Description When s_statistics is called, it returns a pointer to an array of

counters of type long. This array holds N_STATS number of
counters, which contain the accumulated statistical totals. The data
returned can be separated into five categories: database, locking,
transaction, remote procedure calls (RPCs), and miscellaneous
internal Velocis processes.
A complete list of the defined server constants appears below.
These constants contain the index into the array of longs returned
from s_statistics. All values are totals and do not show current
values. For example, the value returned in the STAT_LOGINS array
element represents the total number of user logins that have
occurred since the server was started, not the current number of
active users. To obtain the current number, subtract the total of
STAT_LOGOUTS from STAT_LOGINS.
Database STAT_PGZERO_READ
Statistics Total number of times Velocis performed a page zero read from a
database file.
STAT_PGZERO_WRITE
Total number of times Velocis performed a page zero write to a
database file.
STAT_OPEN_DB_TABLES
Total number of times a database open required a database
dictionary read from disk.
STAT_CLOSE_DB_TABLES
Total number of times a database dictionary was removed from
memory. This counter is incremented when all users of the database

s_statistics
have called d_close and the table can be removed from Velocis
memory.
STAT_OPEN_DBS
Total number of times Velocis performed a database open.
STAT_CLOSE_DBS
Total number of times Velocis performed a database close.
Locking STAT_GROUP_LOCK_REQ
Statistics Total number of lock requests Velocis serviced. This counter is
incremented when Velocis receives a lock request, whether it was
granted, blocked, timed out, or a Velocis error occurred.
STAT_GROUP_LOCK_BLOCKED
Total number of lock requests blocked because of an incompatible
lock.
STAT_GROUP_LOCK_TIMEOUT
Total number of times a lock timed out because of an incompatible
lock.
STAT_INST_READ_LOCKS
Total number of times an instance read lock is granted.
STAT_TABLE_READ_LOCKS
Total number of times a table read lock is granted.
STAT_INST_WRITE_LOCKS
Total number of times an instance write lock is granted.
STAT_TABLE_WRITE_LOCKS
Total number of times a table write lock is granted.
STAT_FREED_LOCKS
Total number of successful requests to free instance and table locks.
Transaction STAT_TRBEGINS
Statistics Total number of times a database transaction began. This counter is
incremented after every successful d_trbegin call to an open
database.
STAT_TRENDS
Total number of times a database transaction ended. This counter is
incremented after every successful d_trend call to an open database.
STAT_TRABORTS
Total number of times a transaction aborted. This counter is

s_statistics
incremented after a transaction was aborted by a d_trabort call on

an open database.
STAT_CHGLOG_WRITE
Total number of times the change log is updated. This counter is
incremented when a transaction is written to a change log on disk.
STAT_CHGLOGS
Total number of change logs created. This counter is incremented
when Velocis creates multiple change log cycles.
STAT_CHGLOGS_BYTES_WRITE
Total number of bytes written to change logs. This counter is
increased by the size of each write and is only incremented each
time STAT_CHGLOG_WRITE is increased.
STAT_OPEN_CHGLOG
Total number of times the change log is opened. This counter is
incremented each time Velocis opens the change log file.
STAT_CLOSE_CHGLOG
Total number of times the change log file is closed. This counter is
incremented each time Velocis closes the change log file.
STAT_TRROLLBACKS
Total number of transaction rollbacks. This counter is incremented
after a call to d_trrollback is successful on an open database.
STAT_CHECKPOINTS
Total number of cache checkpoints. (See Chapter 3 of the Velocis
User’s Guide for information on checkpoint processing.)
STAT_PIGGYBACKS
Total number of times a contiguous block writes to a database file
during a checkpoint. This is a measure of the fragmentation of the
checkpoint writes. Higher values mean less fragmentation.
Remote STAT_REQUESTS
Procedure Call Total number of client RPC calls serviced by the server.
(RPC) Statistics
STAT_LOGINS
Total number of times the server processed a login.
STAT_LOGOUTS
Total number of times the server processed a logout. This counter is
increased when a successful client logout is serviced by Velocis.

s_statistics
STAT_CLIENT_ABORTS
Total number of times Velocis aborted a client session. For every
session abort, a logout will be automatically performed by Velocis,
hence the STAT_LOGOUTS total is also incremented.
Miscellaneous STAT_D_FCN_CALLS
Statistics Total number of d_ function calls. This counter is increased each
time a d_ function call is made to Velocis by a client or by a Velocis
extension module.
STAT_DBERRS
Total number of database errors. This counter is increased each time
a database error occurs.
STAT_NORM_REQUESTS
Total number of normal RPC requests. This counter is increased
each time Velocis receives a normal RPC request that is serviced by
a normal Velocis thread.
STAT_PRI_REQUESTS
Total number of priority RPC requests. This counter is increased
each time Velocis receives a priority RPC request that is serviced by
a priority Velocis thread.
Example
long stats[N_STATS];
long totalTx = 0;
/* Print transaction rate once per second */

for (;;) {
s_statistics(stats, N_STATS*sizeof(long), hSess);
printf("Total Transactions: %ld, Transactions in last second: %ld\n",
stats[STAT_TRENDS], stats[STAT_TRENDS]-totalTx);
totalTx = stats[STATS_TRENDS];
sleep(1);
}

s_terminate
s_terminate Shut down the Velocis database engine
Syntax void s_terminate (void)
Parameters None
Description This function shuts down the Velocis database engine. If you have
previously called s_startRPCThreads, you must first call
s_endRPCThreads before calling s_terminate.
Note: The s_startRPCThreads function starts the Velocis remote

procedural call (RPC) and network control processor (NCP)
subsystems. The s_endRPCThreads function shuts down those
subsystems.
Return Values None
See Also s_startup, s_endRPCThreads
Example

...
stat = s_startup(catpath, MessageConsole, LOG_ALL);

printf("Unable to start Velocis engine, status = %d\n", stat);
exit(1);
}
stat = s_startRPCThreads(server, noSessionThreads, &shutdown_flag);
exit(1);
}
rm_sleep(5000L);
s_endRPCThreads();
s_terminate();
}

s_userAdd
s_userAdd Add a new database user
Syntax short s_userAdd (USERINF_CHG *user, RDM_SESS hSess)
Parameters user [Input] A pointer to the USERINF_CHG structure

containing fields that describe the user in detail and
the home database device for the user.
Description This function adds a user to the system catalog, using information
from the USERINF_CHG structure. Your application must have
previously called s_devAdd to register the home database device
for the user.
Return Values S_INVSESS S_PRIV

S_NODEV S_USEREXISTS
S_OKAY
See Also s_devAdd, s_userDel, s_userModify

USERINF_CHG (structure)

s_userDel
s_userDel Delete a database user
Syntax short s_userDel (char *username, RDM_SESS hSess)
Parameters username [Input] The name of the database user to remove.

Description This function removes a database user from the system catalog. The
user is then blocked from accessing the server or its databases.
Return Values S_INVNULL S_OKAY

S_INVSESS S_PRIV
S_NOUSER
See Also s_userAdd, s_userModify

s_userGet
s_userGet Retrieve the user definition
Syntax short s_userGet (char *username, USERINF_CHG *user,

RDM_SESS hSess)
Parameters username [Input] The name of the user from whom to retrieve
information.
user [Output] A pointer to the USERINF_CHG structure
containing the retrieved user information.
Description This function retrieves the definition for the specified database user
from the system catalog.
Return Values S_INVNULL S_NOUSER

S_INVSESS S_OKAY
See Also s_userAdd, s_userDel, s_userModify

USERINF_CHG (structure)

s_userModify
s_userModify Change the user definition
Syntax short s_userModify (USERINF_CHG *user, RDM_SESS hSess)
Parameters user [Input] A pointer to the structure containing the

user definition.
Description This function modifies the user definition for the specified user. It
changes the password, database access privileges, or default user
device in the system catalog.

S_NODEV S_PRIV
S_NOUSER
Privilege Required Administrator or same user
See Also s_userAdd, s_userDel, s_userGet

s_version
s_version Retrieve the server version number
Syntax short s_version (char **pVersion, RDM_SESS hSess)
Parameters pVersion [Output] A pointer to the version number string.

hSess [Input] The session handle or NO_SESS.
Description This function retrieves the version string of the server. If you set the
session handle to NO_SESS, the function retrieves the version string
from the client side shared library. An application can use this
information to check whether there is a need to upgrade the
database software.
Return Values S_NOLOGIN

S_OKAY
S_SESDISCON

s_version
Example
/* Get Velocis Client and Server library versions. */
#include <stdio.h>
void main(void)
{
short sStatus = 0;
RDM_SESS hSess = 0;
char *szVersion = NULL;
/* ----------------------------------------------------------
** Get and display Client libraries version.
** ---------------------------------------------------------- */
sStatus = s_version( &szVersion, NO_SESS );
printf( "Client libraries version (%s) status = %d\n",
szVersion, sStatus );
/* ----------------------------------------------------------
** Login to Velocis.
** Get and display Server libraries version.
** ---------------------------------------------------------- */
sStatus = s_login( "RDS", "admin", "secret", &hSess );
if ( S_OKAY != sStatus )
{
printf( "Failed to log into server RDS, error: %hd\n", sStatus );
return;
}
sStatus = s_version( &szVersion, hSess );

printf( "Server libraries version (%s) status = %d\n",
szVersion, sStatus );
s_logout( hSess );
}

Chapter 12
SQL API Functions (SQL Prefix)
This chapter describes the functions in the Velocis implementation of the SQL API.
Although some of the function prototypes appear in sql.h and sqlext.h, you may simply
include sqlrds.h to access the entire API. Each function has a return type of RETCODE
(a short integer).
The functions return these codes, which are defined in sqldefs.h and explained in
Chapter 19:
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NEED_DATA
SQL_NO_DATA_FOUND
SQL_STILL_EXECUTING
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ZERODIV
If a function returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, you can call the
SQLError function to reveal another return code with more specific information. These
codes, which have an err prefix, are declared in rsqlerrs.h.
SQL API Functions (SQL Prefix) 12-1

SQLAllocCData
SQLAllocCData Allocate a c_data column handle
Syntax RETCODE SQLAllocCData (HSTMT hstmt,

UCHAR *tabQual, SWORD tabQualLen,
UCHAR *tabName, SWORD tabNameLen,
UCHAR *colName, SWORD colNameLen,
HCDATA *phCData)
Parameters hstmt [Input] The SQL statement handle.
tabQual [Input] The name of the table qualifier.
tabQualLen [Input] The length, in bytes, of the table qualifier
name. For null-terminated strings, use SQL_NTS.
tabName [Input] The name of the table for the result set.
tabNameLen [Input] The length, in bytes, of the table name. If
null-terminated strings are used, specify SQL_NTS.
colName [Input] The name of the c_data column.
colNameLen [Input] The length, in bytes, of the column name. If
null-terminated strings are used, specify SQL_NTS.
phCData [Output] A pointer to the allocated handle.
Description This function passes an SQL c_data column as a parameter in a

select statement in a heterogeneous environment. The function
requires a handle to an SQL statement and the names of the
database, table, and column. Velocis allocates a special handle,
called a c_data handle, which contains the description information
for the subcolumns of the c_data column. The next call is to
SQLSetCData, passing in the handle and a pointer to the data to
bind to this parameter. The last call is to SQLBindParameter,
passing in the c_data handle as the parameter data.
If you operate in a heterogeneous environment, Velocis will use the
handle information to perform any necessary data conversions.
Because c_data columns are understood only within the SQL API,
you can only use this function with the select statement. Use
SQLFreeCData to free the handle when it is no longer needed.
Return Values SQL_ERROR SQL_SUCCESS

SQL_INVALID_HANDLE
See Also SQLFreeCData, SQLSetCData

SQLAllocConnect
SQLAllocConnect Allocate a server connection handle
Syntax RETCODE SQLAllocConnect (HENV henv, HDBC *hdbc)
Parameters henv [Input] The environment handle.

hdbc [Output] A pointer to the allocated server
connection handle.
Description This function allocates a new server connection handle. Your

application passes the handle to SQLConnect to establish a
connection between the application and the desired Velocis server.
Before calling SQLAllocConnect, your application must call
SQLAllocEnv to allocate an environment handle.
Caution: To make multiple calls to this function using the same

connection handle, you must first call SQLFreeConnect to free the
server connection handle.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLAllocEnv, SQLDisconnect, SQLFreeConnect

SQLAllocEnv
SQLAllocEnv Allocate an environment handle
Syntax RETCODE SQLAllocEnv (HENV *henv)
Parameters henv [Output] A pointer to the allocated environment

handle.
Description This function allocates a new environment handle and initializes the
Velocis SQL API. Only one environment handle is used by each
application. Each environment handle can support multiple
connections. The function returns SQL_ERROR if the server does
not have enough memory for the connection handle.
Your application must call SQLAllocEnv before invoking
SQLAllocConnect. Only one call to SQLAllocEnv needs to be
made within a single application.

SQL_SUCCESS
See Also SQLAllocConnect, SQLDisconnect, SQLFreeConnect,

SQLFreeEnv

SQLAllocStmt
SQLAllocStmt Allocate an SQL statement handle
Syntax RETCODE SQLAllocStmt (HDBC hdbc, HSTMT *hstmt)
Parameters hdbc [Input] The server connection handle.

hstmt [Output] A pointer to the allocated statement
handle.
Description This function allocates and initializes a new SQL statement handle
for the processing of Velocis SQL statements on the specified server.
The function returns SQL_ERROR only when the server does not
have enough memory for the SQL connection handle.
An application may use an unrestricted number of SQL statement
handles, but it is good practice to conserve server memory by
limiting the number of active handles.

SQL_INVALID_HANDLE SQL_SUCCESS_WITH_INFO
See Also SQLAllocConnect, SQLFreeStmt

SQLBindCol
SQLBindCol Bind a host variable to a result column value
Syntax RETCODE SQLBindCol (HSTMT hstmt, UWORD col,

SWORD ctype, PTR buf, SDWORD bufLen,
SDWORD *outLen)

col [Input] The column number of the result. Specify
an integer between 1 and the number of result
columns (see SQLNumResultCols).
ctype [Input] The host variable data type as one of the
elementary data types (for example, SQL_C_LONG)
listed in Chapter 18. The function can bind any
Velocis-supported data type to a character string
and can make the usual conversions between
numeric types. To prevent binding, specify
SQL_C_DEFAULT. Refer to Chapter 18 for
information on the ODBC data types supported by
Velocis.
Note: Specifying SQL_C_DEFAULT requires that the col parameter
hold a value with a compatible elementary data type.
buf [Input] A pointer to the buffer that stores the

column value of a fetched result set. This variable
holds a single column value (SQLFetch) or an array
of column values (SQLExtendedFetch). The
binding type depends on the value of
SQL_BIND_TYPE set by SQLSetStmtOptions.
bufLen [Input] The length, in bytes, of the buffer for the
column value. The length must include space for
the null byte when retrieving values of type char. It
represents the actual size of the entire array or
structure variable. This parameter is ignored for
scalar types with a known length (such as long or
short).
outLen [Output] A pointer to the host variable to store the
output length for the column retrieved by a fetch
operation (buf parameter). This variable holds a
single output length (SQLFetch) or an array of
output lengths (SQLExtendedFetch). The binding

SQLBindCol
type depends on the value of SQL_BIND_TYPE set

by SQLSetStmtOptions. If the value retrieved by
the fetch is NULL, SQL_NULL_DATA is returned
in this parameter. Check for SQL_NULL_DATA
only after calling SQLFetch.
Description This function binds a host variable to a result column value. Your
application must call this function before calling SQLFetch or
SQLExtendedFetch to retrieve select statement processing results.
The application can also call SQLBindCol between fetch calls to
rebind a column to another host variable.
After binding the result column values to host variables (when your
application calls SQLFetch or SQLExtendedFetch), the results
obtained are automatically written to the bound host variables. If a
bound variable is too small to contain an entire result column value,
SQLFetch or SQLExtendedFetch writes a truncated value to the
bound variable (buf) of SQLBindCol. The fetch function truncates
the value of buf to (bufLen-1), sets outLen to the true length of the
result, and returns SQL_SUCCESS_WITH_INFO. The offending
columns are those that have outLen greater than or equal to bufLen.
Velocis uses 6-byte database addresses. As in previous versions of
Velocis, you can fetch a rowid-type column by binding the rowid
column to an integer variable. However, to retrieve the entire 6-byte
database address (including the two-byte file number), you must
use a different C bind type, SQL_C_DBADDR. The default bind
type for rowid columns and all other bind types (for example,
SQL_C_CHAR and SQL_C_LONG) returns only the slot
information (the normal row identifier) when performed on a rowid
column. If you need to retrieve the complete address (for instance,
for Core API operations), bind the column to a DB_ADDR-type
variable with the SQL_C_DBADDR bind type. The
SQL_C_DBADDR C type also works with SQLGetData.
The SQLBindCol function supports bookmarks. To bind a
bookmark, specify SQL_C_BOOKMARK in the host variable data
type (ctype) parameter, and specify 0 in the column number (col).
The buffer length parameter (buflen) is ignored for bookmarks. The
buffer parameter (buf) must include an array of longs, with the
number of array elements matching the size of the rowset. After
calling SQLExtendedFetch, this array stores the bookmarks for the
rows in the current rowset.

SQLBindCol
For more information about using SQLBindCol, see Chapter 9 of


(errCHTRUNC)
See Also SQLExtendedFetch, SQLFetch, SQLNumResultCols

SQLBindParameter
SQLBindParameter Bind a host variable to a parameter
Syntax RETCODE SQLBindParameter (HSTMT hstmt, UWORD pnum,

SWORD ptype, SWORD ctype, SWORD dtype,
UDWORD precision, SWORD scale, PTR value,
SDWORD maxvalLen, SDWORD *valLen)

pnum [Input] The parameter number. This number starts
at 1.
ptype [Input] The parameter type indicator. Possible
values are:
SQL_PARAM_INPUT
The parameter is in an SQL statement that does not
call a procedure, such as a parameter in an insert or
select statement, or it is an input parameter for a
procedure.
SQL_PARAM_INPUT_OUTPUT
A parameter that contains input when calling a
procedure and output after calling a procedure.
Before the procedure is called, value will have the
input value. After the procedure is called, it will
have the result for this parameter.
SQL_PARAM_OUTPUT
The parameter marks an output value in a
procedure. After the procedure is called, value will
contain the proper output value for this parameter.
ctype [Input] The elementary data type of the host
variable to associate with the parameter value. See
the possible data types in Chapter 18.
dtype [Input] The SQL data type that Velocis associates
with the parameter, as determined from its context
in the specified SQL statement. See Chapter 18.
precision [Input] The precision of the parameter after
conversion to its SQL data type. The only SQL data
types that use this value are SQL_CHAR (precision
is the length of the string excluding the null byte),
SQL_DECIMAL, and SQL_TIMESTAMP.
scale [Input] The decimal scaling factor for parameters of
type SQL_DECIMAL and SQL_TIMESTAMP. The
scaling factor specifies the maximum number of

SQLBindParameter
digits to the right of the decimal point. Use this

value only for the data types listed above.
value [Input] A pointer to the host variable to bind to the
parameter.
maxvalLen [Input] Reserved for future use. Any values
specified here are ignored.
valLen [Input/Output] A pointer to the actual length, in
bytes, of the host variable. Alternatively, you may
specify these constants:
SQL_DEFAULT_PARAM
A default value that is used for a parameter in a
procedure. This value is only valid if the statement
is a procedure call.
SQL_LEN_DATA_AT_EXEC(length)
A macro that is only used for a parameter whose
value is provided only after calling SQLExecute or
SQLExecDirect (such as a BLOB parameter). The
parameter for this macro specifies the length, in
bytes, of the parameter to be sent. If the length is
unknown, it can be set to 0.
SQL_NTS
A null-terminated string.
SQL_NULL_DATA
A NULL value for the parameter.
Description This function associates a host variable with a parameter referenced

in the specified statement. The function replaces the SQLSetParam
function in ODBC 1.0 and functions similarly.
An application calls SQLBindParameter to bind a variable (value) to
a parameter marker ("?") in a statement. Upon statement execution,
whatever is in value is assigned to the parameter marker in the
statement.
You can assign new values to the parameter marker simply by
changing the contents of value and re-executing. Alternatively, the
parameter can be bound to a new variable by calling
SQLBindParameter again. The value remains bound until
SQLFreeStmt is called with the SQL_DROP or
SQL_RESET_PARAMS options.
You can use parameter markers in SQL user-defined functions
(UDFs), as long as the UDF type-checking function can handle it. To
do this, your udfCheck function needs to allow for an SQL data

SQLBindParameter
type indicator of SQL_PARAMREF for the UDF function argument.

The type of the actual parameter value will need to be validated in
your udfFunc function.
Parameter markers cannot be used in these situations:
• In a select list
• On both sides of a relational operator (for example, "<=") or a
binary operator (for example, "+")
• As both the first and either the second or third operands of a
between comparison
• As the operand of a unary plus ("+") or minus ("-") operation

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLSetParam

SQLCancel
SQLCancel Cancel the processing of an SQL statement
Syntax RETCODE SQLCancel (HSTMT hstmt)
Description This function cancels the processing of the specified SQL statement.
It has the same effect as the SQL_CLOSE option of the SQLFreeStmt
function. It is typically used with select statements to terminate
processing before reaching the end of the result set.
If you call this function to cancel a statement that still requires data
completion (for instance, while the statement requires data for
SQL_DATA_AT_EXEC parameters), Velocis rolls back the current
transaction only if it is in auto commit mode. If in manual commit
mode (Velocis’s default mode), Velocis simply cancels the statement
and relies on you to roll back if you so choose.
Note: This is not standard ODBC behavior. Velocis does this
because it cannot easily roll back SQL operations to a mark, and
because ODBC does not clearly define how to handle a canceled
operation in manual commit mode (although rolling back would be
the logical handling).
Therefore, if Velocis is in manual commit mode, you cannot simply
re-execute a statement that has been canceled, as ODBC specifies.
Instead, you must first abort or commit the transaction to clear the
canceled state, then re-execute the statement. Thus, in manual
commit mode, Velocis requires you to specify how to handle a
canceled statement (abort or commit) before you can re-execute the
statement. Again, this is a Velocis-specific behavior.

See Also SQLFreeStmt

SQLCDataColumn
SQLCDataColumn Retrieve a result set of c_data column descriptions
Syntax RETCODE SQLCDataColumn (HSTMT hstmt,

UCHAR *colName, SWORD colNameLen)

tabQual [Input] The table qualifier name.
name. For a null-terminated string, specify
SQL_NTS.
tabName [Input] The table name.
tabNameLen [Input] The length, in bytes, of the table name. For
a null-terminated string, specify SQL_NTS.
colName [Input] The column name.
colNameLen [Input] The length, in bytes, of the column name.
For a null-terminated string, specify SQL_NTS.
Description This function generates a result set of data describing the c_data
column or group of columns. The data from this result set can then
be retrieved using SQLFetch or SQLExtendedFetch. Search
patterns cannot be used on the names for the table qualifier, table, or
column. The function generates a row for the c_data column itself,
with an additional row for each subcolumn of the c_data column, if
any. The result set contains the following columns:
Table 12-1. Result Set Columns for SQLCDataColumn

Column Name Type Description
FLDNAME char[33] A 32-byte character field containing the
name of the column or subcolumn.
DATA_TYPE smallint The SQL data type of the column or
subcolumn.
UNSIGNED smallint Whether the column is signed or unsigned.
NOFIELDS smallint The number of subfields in this column.
DIM0, DIM1, DIM2 smallint The number of bytes of the first, second,
and third array dimension, respectively.

SQLCDataColumn

See Also SQLAllocCData, SQLDescribeCData, SQLFreeCData,

SQLSetCData

SQLColAttributes
SQLColAttributes Get the column attributes
Syntax RETCODE SQLColAttributes (HSTMT hstmt, UWORD colno,

UWORD attr, PTR buf, SWORD bufLen, SWORD *outLen,
SDWORD *descr)
Parameters hstmt [Input] The select statement handle.

colno [Input] The column number from the result set.
This number starts at 1.
attr [Input] The column attribute type indicator.
Possible values are described later in this section.
buf [Output] A pointer to the column attributes.
bufLen [Input] The length, in bytes, available to return in
buf.
outLen [Output] A pointer to the length, in bytes, of the
column attributes (buf).
descr [Output] A pointer to the numeric descriptor
information.
Description This function obtains information about the specified column from
the result set of the specified select statement. From the attr
parameter, the function determines the attribute for which to return
information. It then obtains the descriptor information and writes it
either to the buf parameter or the descr parameter.
This function only retrieves information for one attribute. Your
application must repeat the call as necessary to retrieve data for all
attributes of interest.
Note: Your application must call SQLPrepare before calling

SQLColAttributes.
Column Attribute SQL_COLUMN_AUTO_INCREMENT

Type Indicators Sets descr to TRUE (1) if column is an auto incrementing column,
otherwise FALSE (0).
SQL_COLUMN_CASE_SENSITIVE
Sets descr to TRUE (1) if the column is a character type column. For
all other type columns, descr is set to FALSE (0).

SQLColAttributes
SQL_COLUMN_COUNT
Sets descr to the number of columns in the result set. This value is
also obtained from SQLNumResultCols. The colno argument is
ignored.
SQL_COLUMN_DISPLAY_SIZE
Sets descr to the maximum number of characters needed when the
column value is converted to type SQL_C_CHAR.
SQL_COLUMN_LABEL
Returns in buf the column label or title. If there is no label or title,
the column name is returned.
SQL_COLUMN_LENGTH
Sets descr to the length, in bytes, of the column value for the default
(SQL_C_DEFAULT) elementary data type of the result. This length
is the actual number of bytes that can be copied into the
application’s result column buffer.
SQL_COLUMN_MONEY
Sets descr to FALSE (0). Velocis SQL does not have a money-based
data type.
SQL_COLUMN_NAME
Returns in buf the name of the column. If the column contains an
unaliased expression, the expression text is written.
Note: In Velocis, both SQL_COLUMN_NAME and
SQL_COLUMN_LABEL return the same information. This behavior
is not compliant with ODBC. In ODBC, using
SQL_COLUMN_LABEL returns a heading, or a column name if
there is no heading. Using SQL_COLUMN_NAME in ODBC
always returns the column name, regardless of whether a column
heading exists.
SQL_COLUMN_NULLABLE
Sets descr to the null state of the column. This attribute type
indicates whether the column is "nullable" (that is, can contain a
NULL value). The possible attribute values are SQL_NO_NULLS
(cannot contain nulls), SQL_NULLABLE (can contain nulls), and
SQL_NULLABLE_UNKNOWN (the function cannot determine
whether null values are allowed).
SQL_COLUMN_OWNER_NAME
Returns a blank string. A value for this attribute type cannot be
determined.

SQLColAttributes
SQL_COLUMN_PRECISION
Sets descr to the column precision.
SQL_COLUMN_QUALIFIER_NAME
Returns a blank string. A value cannot be determined for this
attribute type.
SQL_COLUMN_SCALE
Sets descr to the column scale for data types that allow scale to be
specified.
SQL_COLUMN_SEARCHABLE
Determines whether the column can be used for a search. There are
four different levels of searching in descr:
SQL_SEARCHABLE
Column is fully searchable.
SQL_ALL_EXCEPT_LIKE
Column can be used in any where clause comparison except like.
SQL_LIKE_ONLY
Column can only be used in a like comparison.
SQL_UNSEARCHABLE
Column cannot be used in any search.
In Velocis, char and varchar types are SQL_SEARCHABLE, BLOB
types are SQL_UNSEARCHABLE, and all remaining supported
types are SQL_ALL_EXCEPT_LIKE.
SQL_COLUMN_TABLE_NAME
Sets descr to the table name for the column. If the table name cannot
be retrieved, a blank string is returned.
SQL_COLUMN_TYPE
Sets descr to the data type of the result column. Possible data types
are described in Chapter 18.
SQL_COLUMN_TYPE_NAME
Returns in buf the data type for the column result (for example, char,
integer, etc.).
SQL_COLUMN_UNSIGNED
Sets descr to FALSE (0). Velocis SQL does not support unsigned
data types.

SQLColAttributes
SQL_COLUMN_UPDATABLE
Sets descr to an indicator of whether the column’s data type supports
updates and, if the statement accesses a view, whether the view is
updateable. The possible values for this attribute are
SQL_ATTR_READONLY (the column is not updateable),
SQL_ATTR_WRITE (the column is updateable), and
SQL_ATTR_READWRITE_UNKNOWN (the column’s updateable
status is not known).

See Also SQLColumns, SQLDescribeCol

SQLColumns
SQLColumns Prepare a result set from columns
Syntax RETCODE SQLColumns (HSTMT hstmt,

UCHAR *tabOwner, SWORD tabOwnerLen,
UCHAR *colName, SWORD colNameLen)

name. For null-terminated strings, specify
SQL_NTS.
tabOwner [Input] Unused (NULL).
tabOwnerLen [Input] Unused (0).
tabName [Input] The name of the table for the result set.
null-terminated strings, specify SQL_NTS.
colName [Input] The name of the column.
colNameLen [Input] The length, in bytes, of the column name.
For null-terminated strings, specify SQL_NTS.
Description This ODBC level 1 function sets up a result set of column

information for the specified SQL statement handle. It forms the set
from the columns associated with the specified table qualifier, table,
and column. Each of these parameters can contain a search pattern.
The function places in the result set all columns that match the
specified search pattern for all three parameters.
The result set is composed of information about the columns,
ordered by TABLE_QUALIFIER and TABLE_NAME. Each row of
the set contains information about one column (see the table below).
Your application can obtain these rows by calling SQLFetch or
SQLExtendedFetch. Refer to the Microsoft ODBC SDK Programmer’s
Reference for ODBC-specific operational details about SQLColumns.

SQLColumns
Table 12-2. Result Set Columns for SQLColumns

TABLE_QUALIFIER varchar(32) The name of the database containing
the table and column.
TABLE_OWNER null Unused for Velocis SQL.
TABLE_NAME varchar(32) The name of the table containing the
column.
COLUMN_NAME varchar(32) The name of the column.
DATA_TYPE smallint The ODBC data type code number.
TYPE_NAME varchar(32) The name of the data type.
PRECISION integer The declared precision of the column.
LENGTH integer The length, in bytes, of the column
(excluding the NULL terminator if the
column is a character string).
SCALE smallint The scale of the column.
RADIX smallint The radix of the numeric column. For
this release, it always returns ten (10).
NULLABLE smallint The null state of the column. A value
of SQL_NULLABLE or
SQL_NO_NULLS indicates that the
column can or cannot contain null
values, respectively. If the function
cannot determine whether null values
are allowed, the value is
SQL_NULLABLE_UNKNOWN.
REMARKS varchar(132) A description of the column.

See Also SQLColAttributes, SQLDescribeCol, SQLExtendedFetch,

SQLFetch

SQLConnect
SQLConnect Connect an application to a Velocis SQL support module
Syntax RETCODE SQLConnect (HDBC hdbc,

UCHAR *server, SWORD serverLen,
UCHAR *user, SWORD userLen,
UCHAR *password, SWORD passwordLen)

server [Input] The name of the Velocis SQL server.
serverLen [Input] The length, in bytes, of the server name. For
user [Input] The name of the application user. The
specified user and password must be a valid user
for the specified Velocis server.
userLen [Input] The length, in bytes, of the user name. For
password [Input]The application user’s password. The
specified user and password must be a valid user
for the specified Velocis server.
passwordLen [Input] The length, in bytes, of the password. For
Description This function establishes a connection between the application and

the Velocis SQL support module. Each connection establishes an
independent Velocis SQL context. To differentiate between
contexts, Velocis SQL uses a server connection handle (hdbc), which
you assign by making an earlier call to SQLAllocConnect.
Note: Your application can set up any number of connections with

one or more servers.

See Also SQLAllocConnect, SQLDisconnect, SQLFreeConnect

SQLConnectWith
SQLConnectWith Associate a Velocis session with an SQL connection handle
Syntax RETCODE SQLConnectWith (HDBC hdbc, RDM_SESS sess_id)

sess_id [Input] The Velocis session identifier (handle). An
extension module or UDF obtains this through a call
to SYSSessionId.
Description This function is called from an extension module or UDF to

associate a Velocis session with a Velocis SQL connection handle.
The function allows database changes made by the extension
module or UDF to be included in a transaction started by the main
Velocis SQL application.
Note: For SQLConnectWith to work properly with an extension

module or UDF, the application calling the extension module must
connect to Velocis using SQLConnect. In other words, it must be a
Velocis SQL application. If the connection is made using the s_login
function, hdbc will be set to null.
Once the association is made, the extension module or UDF can use
the server connection handle (hdbc) in calls to other SQL API
functions. For example, the module or function passes this handle
in a call to SQLAllocStmt to allocate the handles needed to process
SQL statements.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SYSSessionId

SQLDbaToRowId
SQLDbaToRowId Convert a database address of a table row to a row identifier
Syntax RETCODE SQLDbaToRowId (HSTMT hstmt, UCHAR *tblname,

DB_ADDR dba, UDWORD *rowid)
Parameters hstmt [Input] The handle for the SQL statement that
referencesthe table.
tblname [Input] The name of the database table. If
correlation names have been specified for the tables
listed in the from clause of the referencing select
statement, you must specify the correlation name.
dba [Input] The database address to convert.
rowid [Output] A pointer to the row identifier ("rowid").
Description This function converts the specified database address to the rowid
for a row in the corresponding database table. The function returns
SQL_ERROR if the database address is not valid for the specified
table or the specified table is not referenced in the given SQL
statement.
Note: This function is only needed in applications that call both the
Velocis SQL API and the Velocis Core APIs.

See Also SQLRowIdToDba, SYSDbaToRowId

SQLDBHandle
SQLDBHandle Get a database handle
Syntax RETCODE SQLDBHandle (HDBC hdbc, UCHAR *dbname,

RDM_DB *phDb)

dbname [Input] The database name. Your application must
have already opened the database during server
connection, either implicitly or explicitly (for
example, using the open statement).
phDb [Output] A pointer to the database handle.
Description This function retrieves the handle that Velocis uses to represent the
specified database. Your application can later use this handle in
calls to the Velocis Core APIs (bypassing Velocis SQL) to access
database information.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SYSDBHandle

SQLDescribeCData
SQLDescribeCData Get a c_data column description from a prepared select statement
Syntax RETCODE SQLDescribeCData (HSTMT hstmt, UWORD col,

UWORD fld, UCHAR *fldname, SWORD bufLen,
SWORD *outLen, SWORD *type, SWORD *unsgd,
SWORD *noflds, SWORD *dims)

col [Input] The number of the column to describe. This
number must be between 1 and the number of
columns indicated in the select statement. It can be
an expression instead of a single table column
reference.
fld [Input] The field or subfield number for the desired
field.
fldname [Output] The name of the specified field or subfield.
bufLen [Input] The size of the fldname buffer.
outLen [Output] A pointer to the size, in bytes, of the full
field name. Check this value against the length of
fldname to determine whether truncation has
occurred.
type [Output] A pointer to the SQL data type indicator
for the column. See Chapter 18.
unsgd [Output] A pointer to a flag that indicates whether
the field is signed (1) or unsigned (0).
noflds [Output] A pointer to the number of subfields
possessed by this column.
dims [Output] A pointer to the three array dimensions of
this field.
Description This function retrieves information from a prepared select statement

(hstmt) to describe a c_data column. Before calling this function,
your application must have already compiled the statement by a call
to either SQLPrepare or SQLExecDirect.
Specify the column number of the c_data column (starting at 1) in
the result set. Use the fld parameter to specify which of the subfields
of the c_data structure to describe. A value of 0 in this parameter
will return the description of the c_data column itself.

SQLDescribeCData

See Also SQLAllocCData, SQLCDataColumn, SQLFreeCData,

SQLSetCData

SQLDescribeCol
SQLDescribeCol Get a column description from a prepared select statement
Syntax RETCODE SQLDescribeCol (HSTMT hstmt, UWORD col,

UCHAR *colname, SWORD bufLen, SWORD *outLen,
SWORD *type, UDWORD *prec, SWORD *scale,
SWORD *nullable)

col [Input] The number of the column to describe. This
number must be between 1 and the number of
columns indicated in the select statement. It can be
an expression instead of a single table column
reference.
colname [Output] The column name. If the column contains
an expression, the function writes that instead of the
column name.
bufLen [Input] The length, in bytes, of the column name
buffer (colname).
outLen [Output] A pointer to the total number of bytes
available to return in colname.
type [Output] A pointer to the SQL data type indicator
for the column. See Chapter 18 for descriptions of
possible data types.
prec [Output] A pointer to the display length, in bytes
(precision), for the column. Note that precision
does not include the null byte.
scale [Output] A pointer to the scale factor for the
column.
nullable [Output] A pointer to the null state indicator for the
column. A value of SQL_NULLABLE or
SQL_NO_NULLS indicates that the column can or
cannot contain null values, respectively. If the
function cannot determine whether null values are
allowed, the indicator contains
SQL_NULLABLE_UNKNOWN.
Note: Any of the output parameters can contain NULL.

SQLDescribeCol
Description This function retrieves information from a prepared select statement

(hstmt) to describe a column. Before calling this function, your
application must have already compiled the statement by calling
either SQLPrepare or SQLExecDirect.

See Also SQLColumns, SQLNumResultCols

SQLDescribeParam
SQLDescribeParam Get a parameter description from a prepared select statement
Syntax RETCODE SQLDescribeParam (HSTMT hstmt,

UWORD paramNum, SWORD *sqlType, UDWORD *precision,
SWORD *scale, SWORD *nullable)

paramNum [Input] The number of the parameter to describe.
This number must be between 1 and the number of
parameters indicated in the select statement.
sqlType [Output] A pointer to the SQL data type indicator
for the parameter. See Chapter 18 for descriptions
of the possible data types.
precision [Output] A pointer to the display length, in bytes,
for the parameter. Note that precision does not
include the null byte.
scale [Output] A pointer to the scale factor for the
parameter.
nullable [Output] A pointer to the null state indicator for the
parameter. A value of SQL_NULLABLE or
SQL_NO_NULLS indicates that the column can or
cannot contain null values, respectively. If the
function cannot determine whether null values are
allowed, the indicator contains
SQL_NULLABLE_UNKNOWN .
Note: Any of the output parameters can contain NULL.
Description This ODBC level 2 function retrieves information from a prepared

select statement (hstmt) to describe a parameter. Before calling this
function, your application must have already compiled the
statement by a call to either SQLPrepare or SQLExecDirect. Refer
to the Microsoft ODBC SDK Programmer’s Reference for ODBC-
specific operational details about SQLDescribeParam.

SQL_INVALID_HANDLE
See Also SQLBindParameter, SQLSetParam

SQLDescribeStmt
SQLDescribeStmt Determine an SQL statement type
Syntax RETCODE SQLDescribeStmt (HSTMT hstmt, UWORD *type)

type [Output] A pointer to the statement type indicator,
defined as a manifest constant declared in standard
Velocis SQL header file sqlrdefs.h. Possible values
are defined later in this section.
Description This function determines the type of SQL statement associated with
the specified statement handle (hstmt). The statement type
indicators that can be returned in the type parameter are listed
below, along with the SQL statement types they represent. See
Chapter 4 of the Velocis Language Guide for definitions of these
statements.

SQLDescribeStmt
Table 12-3. SQL Statement Type Indicators

SQL Statement Type Indicator
activate index sqlACTIVATE
begin sqlBEGIN
close sqlCLOSE
commit sqlCOMMIT
create database instance sqlCRDB
create filter sqlCRFILTER
create function sqlCRFUNC
create index sqlCRINDEX
create procedure sqlCRPROC
create view sqlCRVIEW
create table or create temporary table sqlCRTABLE
deactivate index sqlDEACTIVATE
delete sqlDELETE
drop database sqlDRDB
drop filter sqlDRFILTER
drop function sqlDRFUNC
drop index sqlDRINDEX
drop procedure sqlDRPROC
drop table sqlDRTABLE
drop view sqlDRVIEW
execute sqlEXECUTE
grant sqlGRANT
insert sqlINSERT
lock table sqlLOCK
mark sqlMARK
open sqlOPEN
revoke sqlREVOKE
rollback sqlROLLBACK
select sqlSELECT
One of the set statements sqlSET
unlock table sqlUNLOCK
update sqlUPDATE
update statistics sqlSTATS

SQL_INVALID_HANDLE
See Also SYSDescribeStmt

SQLDisconnect
SQLDisconnect Disconnect an application from a Velocis SQL support module
Syntax RETCODE SQLDisconnect (HDBC hdbc)
Description This function disconnects the application from the Velocis SQL
support module associated with the specified connection handle
(hdbc). If successful, the function automatically frees all SQL
statement handles allocated for the connection on a successful
SQLDisconnect call. If there are any active transactions (in other
words, transactions that have not yet been committed or rolled
back) at the time of disconnection, SQLDisconnect returns an
appropriate SQL_ERROR code and the connection remains open.
Note: After a successful return from SQLDisconnect, your

application can reuse the connection handle in a subsequent call to
SQLConnect. Alternatively, it can free the handle by calling
SQLFreeConnect.
Return Values SQL_ERROR (errTXACTIVE, a transaction is active)

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLAllocConnect, SQLConnect, SQLFreeConnect

SQLDriverConnect
SQLDriverConnect Connect an application to a Velocis SQL support module by using

an ODBC driver
Syntax RETCODE SQLDriverConnect (HDBC hdbc, HWND hwnd,

UCHAR *strIn, SWORD strInLen, UCHAR *strOut,
SWORD strOutMax, SWORD *actualOutLen,
UWORD driverOption)

hwnd [Input] The window handle of the parent window.
This parameter can be set to NULL.
strIn [Input] A connection string in this format:
"DSN=DataSource[;UID=UserID;PWD=Password]".
The data source name is required, but the user ID
and password are optional.
For example, to log into a data source named
"Velocis Default", you might provide this string:
"DSN=Velocis Default;UID=admin;PWD=secret"
strInLen [Input] The length, in bytes, of the connection string
(strIn).
strOut [Output] The resulting connection string.
strOutMax [Input] The size, in bytes, of the buffer specified by
strOut.
actualOutLen [Output] A pointer to the number of bytes available
to return in strOut. If this is larger than strOutMax,
strOut is truncated to (strOutMax-1) bytes.
driverOption [Input] The driver completion control flag. Possible
values are:
SQL_DRIVER_NOPROMPT
Connects if the connection information is complete;
otherwise, the connection fails, and there is no dialog
box to prompt for missing information.
SQL_DRIVER_COMPLETE
Connects if the connection information is complete;
otherwise, the dialog box in SQL_DRIVER_PROMPT
is provided for completion.
SQL_DRIVER_PROMPT
Displays a dialog box containing information
supplied in the connection string (strIn). The user
must complete the rest of the information to connect.

SQLDriverConnect
SQL_DRIVER_COMPLETE_REQUIRED
Operates similarly to SQL_DRIVER_COMPLETE
except that any unneeded fields within the dialog
box are deactivated.
Description This ODBC level 1 function connects your application to the Velocis
SQL support module. This function allows your application to
specify any combination of connection parameters (server name,
user name, and password) with the ODBC driver, prompting the
user for any unspecified values. The corresponding non-ODBC
connection function (SQLConnect) must have all parameters
furnished at the same time to perform a connection. Refer to the
Microsoft ODBC SDK Programmer’s Reference for ODBC-specific
details of SQLDriverConnect.

SQL_NO_DATA_FOUND
See Also SQLConnect

SQLError
SQLError Get the details about error/status codes
Syntax RETCODE SQLError (HENV henv, HDBC hdbc, HSTMT hstmt,

UCHAR *sqlstate, SDWORD *rsqlcode, UCHAR *errMsg,
SWORD errMsgLen, SWORD *outLen)
Parameters henv [Input] The environment handle. This parameter

can be equal to NULL.
hdbc [Input] The server connection handle, if the
error/status code is associated with a server
context. If no context is involved, specify
SQL_NULL_HDBC or NULL.
hstmt [Input] The SQL statement handle, if the
error/status code is associated with a Velocis SQL
statement. If no SQL statement is involved, specify
SQL_NULL_HSTMT or NULL.
sqlstate [Output] A pointer to the 5-character ODBC-
specified code providing details about the original
return code. This parameter can be equal to NULL.
rsqlcode [Output] A pointer to the Velocis SQL-specific
error/status code. This parameter can be equal to
NULL.
errMsg [Output] A pointer to the text of the error/status
message corresponding to the code. This parameter
can be equal to NULL.
errMsgLen [Input] The length, in bytes, of the message buffer
(errMsg).
outLen [Output] A pointer to the length, in bytes, of the
message text (errMsg). If the length of the message
text exceeds the length of the message buffer
(errMsgLen), the function truncates the message.
Description This function is called by your application after another Velocis SQL
API function returns the standard code SQL_ERROR or
SQL_SUCCESS_WITH_INFO (described in Chapter 19). The
function examines the standard error/status code and writes both
the standard SAG/ODBC code and the Velocis SQL-specific code
that explains it. If required, it also copies the explanatory message
text to the errMsg parameter.

SQLError
For each active connection or active SQL statement, the SQL server
maintains only the error/status information associated with the
most recent function call. If your application does not call SQLError
before the next function call for a given connection or statement, the
previous error/status information is lost.

SQL_NO_DATA_FOUND
See Also SQLWhenever

SQLExecDirect
SQLExecDirect Compile and execute a Velocis SQL statement
Syntax RETCODE SQLExecDirect (HSTMT hstmt, UCHAR *sqlStr,

SWORD sqlStrLen)

sqlStr [Input] A string that contains the Velocis SQL
statement. This string can include embedded
parameter references.
sqlStrLen [Input] The length, in bytes, of the SQL statement
(sqlStr). For a null-terminated string, specify
SQL_NTS.
Description This function compiles and executes the specified Velocis SQL
statement. To include embedded parameter references in the SQL
string, call SQLBindParameter as often as needed to assign values
to the parameters in the order of their arrangement in the statement
string. Each parameter reference must be assigned a value before
your application can call SQLExecDirect.

SQL_NEED_DATA
See Also SQLBindParameter, SQLExecute, SQLPrepare

SQLExecute
SQLExecute Execute an SQL statement
Syntax RETCODE SQLExecute (HSTMT hstmt)
Description This function executes the specified statement, which has already
been prepared by SQLPrepare. Any parameter markers contained
in the statement must have been bound to host program variable
values through prior calls to SQLBindParameter. These values
remain in effect until the statement is completely processed (or a call
to SQLFreeStmt has aborted statement execution). Your application
can then assign new values to the statement parameters and recall
SQLExecute for the new parameter set.

SQL_NEED_DATA
See Also SQLBindParameter, SQLExecDirect, SQLPrepare

SQLExtendedFetch
SQLExtendedFetch Retrieve multiple select statement result rows at a time
Syntax RETCODE SQLExtendedFetch (HSTMT hstmt, UWORD fetchType,

SDWORD rowNum, UDWORD *actualRows,
UWORD *rowStatArray)
Parameters hstmt [Input] The statement handle that corresponds to a

select statement previously prepared by a call to
SQLPrepare or SQLExecDirect.
fetchType [Input] The fetch operation type indicator. If the
cursor type is SQL_CURSOR_FORWARD_ONLY
(the default), this parameter must be
SQL_FETCH_NEXT. If the cursor type is
SQL_CURSOR_STATIC, the parameter can be any
of the following:
SQL_FETCH_ABSOLUTE
Fetches the rowset determined by rowNum (see
below). If rowNum is positive, the parameter fetches
the rowset starting at row rowNum. If rowNum is
negative, the parameter fetches the rowset starting
rowNum rows before the end of the result set. If
rowNum is zero, the driver returns
SQL_NO_DATA_FOUND and the cursor is
positioned before the start of the result set.
Example:
If rowNum is -10, Velocis fetches the rowset
starting 10 rows from the end of the result set. If
the rowNum specified is before the start of the
result set, Velocis fetches starting from row 1,
unless rowNum plus the rowset size is still
smaller than 0. In the latter case, the cursor is
positioned before the start of the result set and
returns SQL_NO_DATA_FOUND.
SQL_FETCH_BOOKMARK
Fetches the rowset starting at the bookmark supplied
in rowNum.
SQL_FETCH_FIRST
Fetches the first result rowset.
SQL_FETCH_LAST
Fetches the last result rowset.
SQL_FETCH_NEXT
Fetches the next result rowset.

SQLExtendedFetch
SQL_FETCH_PREV or SQL_FETCH_PRIOR
Fetches the previous result rowset. If the cursor is
positioned after the end of the result set, the result is
the same as SQL_FETCH_LAST.
SQL_FETCH_RELATIVE
Fetches the rowset that is rowNum rows from the
current row position.
Examples:
If rowNum is -10, Velocis fetches the rowset
starting 10 rows before the beginning of the
current rowset. Thus, if the current rowset
starts with row 50, this operation will fetch the
rowset starting at row 40.
If rowNum is 30, Velocis fetches the rowset
starting 30 rows after the start of the current
rowset. Thus, if the current rowset starts at row
50, this operation will fetches the rowset starting
at row 80.
If rowNum is zero, the driver retrieves the
current rowset again.
If the cursor is positioned before the start of the
result set and rowNum is positive, or if the
cursor is positioned after the end of the result
set and rowNum is negative, this operation acts
like SQL_FETCH_ABSOLUTE.
rowNum [Input] The rowset to fetch. This parameter is only
used with static cursors if fetchType is
SQL_FETCH_ABSOLUTE,
SQL_FETCH_RELATIVE, or
SQL_FETCH_BOOKMARK (see above). This
option is not used with forward-only cursors.
actualRows [Output] A pointer to the number of rows fetched.
rowStatArray [Output] A pointer to an array showing the status of
each result set row. Element values are:
SQL_ROW_ADDED
The row was added.
SQL_ROW_DELETED
The row was deleted.
SQL_ROW_ERROR
The row was successfully fetched, but one or more
columns had a truncation error. All other errors
terminate the result set, so no results are retrieved.
SQL_ROW_NOROW
No row was fetched for this row set entry (that is,

SQLExtendedFetch
the number of rows fetched is less than the row set

size).
SQL_ROW_SUCCESS
The row was successfully fetched with no truncation
errors.
SQL_ROW_UPDATED
The row was updated.
Description This ODBC level 2 function extends the basic fetch capabilities
provided by SQLFetch. It implements a forward-only (that is,
nonscrollable), block mode, read-only cursor that allows the
retrieval of multiple select statement result rows using a single RPC.
The maximum number of rows that can be retrieved in a single call
to SQLExtendedFetch (that is, the size of the result set) is specified
in an earlier call to the SQLSetScrollOptions function. The default
number of rows is 1.
The SQLExtendedFetch function automatically writes column
values for each fetched row to host variables bound through prior
calls to SQLBindCol. SQLExtendedFetch returns
SQL_NO_DATA_FOUND when it finds no more rows in the result
set. Refer to the Microsoft ODBC SDK Programmer’s Reference for
ODBC-specific details of SQLExtendedFetch.
For errors encountered during the fetch operation, the function
writes SQL_ROW_ERROR to the rows involved (rowStatArray
parameter). The function returns SQL_SUCCESS_WITH_INFO
when one or more rows in the retrieved result set have a data
truncation error (errCHTRUNC).
If a timeout occurs when SQLExtendedFetch has retrieved at least
one row and tries to fetch another row that is locked, the function
returns SQL_SUCCESS or SQL_SUCCESS_WITH_INFO. It sets
actualRows to the number of rows actually fetched (which is less
than the result set size). On the next call to SQLExtendedFetch, the
first row retrieved is the row for which the timeout has occurred. If
that row is still locked, SQLExtendedFetch returns SQL_ERROR
(errTIMEOUT). The application can call SQLExtendedFetch as
needed until it succeeds in retrieving the locked row.
If static cursors are activated, SQLExtendedFetch fetches any
rowset within the result set. Fetched rows are cached on the client
side for easy re-fetching. Because rows are fetched when requested,
exercise caution with the SQL_FETCH_LAST option, and with the
SQL_FETCH_ABSOLUTE option when it has a negative rowNum

SQLExtendedFetch
value. Both options require Velocis to fetch the entire result set to
the client side before returning the requested rowset. If the result
set is large, this can take some time. Once cached, however, the
rows can be retrieved quickly without calling the server again.
See your ODBC manual if you require more detail on how
SQLExtendedFetch works with static cursors.

SQL_NO_DATA_FOUND
See Also SQLBindCol, SQLExecDirect, SQLFetch, SQLPrepare

SQLExtendedTransact
SQLExtendedTransact Extend transaction capabilities
Syntax RETCODE SQLExtendedTransact (HENV henv, HDBC hdbc,

UWORD option, UCHAR *markID, SWORD markIDLen)

hdbc [Input] The server connection handle. A value of
SQL_NULL_HDBC requests the specified
transaction for all active connections.
option [Input] The transaction type indicator, which can be
one of these values:
SQL_COMMIT
Commits changes made since the transaction began.
The changes are committed at the point identified by
the transaction identifier.
SQL_ROLLBACK
Rolls back changes made since the transaction mark
or begins at the point identified by the transaction
identifier.
SQL_BEGIN
Begins a new transaction with the identifier specified
by markID. Specification of this type allows the user
to name specific transactions and clearly delineate
the portions of a SQL program that modify the
contents of a database.
SQL_MARK
Marks the transaction rollback point with the
transaction identifier.
markID [Input] The transaction identifier.
markIDLen [Input] The length, in bytes, of the transaction
identifier (markID).
Description This function extends the basic transaction capabilities provided by

SQLTransact. Extended capabilities include the ability to begin a
transaction and mark the transaction rollback points.
A Velocis SQL transaction begins just after the user opens a database
and after completion of a commit for the prior transaction. To start
the transaction, the application calls SQLExtendedTransact with the
SQL_BEGIN transaction type specified. Once the transaction is
started, another transaction cannot begin until the active transaction
is terminated by a call to SQLExtendedTransact with

SQLExtendedTransact
SQL_COMMIT or SQL_ROLLBACK specified as the transaction

type.
Note that SQLExtendedTransact, with its transaction type flags, is
identical in functionality to the begin, mark, commit, and rollback
Velocis SQL statements. Therefore, the two functions illustrated
below are identical in operation:
SQLExtendedTransact(henv, hdbc, SQL_BEGIN, "accts", SQL_NTS)
SQLExecDirect(hstmt, "begin transaction \"accts\";", SQL_NTS)

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLTransact

SQLFetch
SQLFetch Get the next row from a result set for a select statement
Syntax RETCODE SQLFetch (HSTMT hstmt)
Parameters hstmt [Input] The SQL statement handle that corresponds

to a select statement previously executed by
SQLExecute or SQLExecDirect.
Description This function retrieves the next row of a result for the specified
select statement. If the columns of the result set were already
bound to host variables in calls to SQLBindCol, SQLFetch
automatically writes column values for the fetched row to the host
variables. If the columns are unbound, the application can call
SQLGetData to retrieve the column values for the fetched row. The
SQLFetch function returns SQL_SUCCESS_WITH_INFO if one or
more of the host variables bound to column values are not large
enough to hold entire column values.

SQL_NO_DATA_FOUND
See Also SQLBindCol, SQLExtendedFetch, SQLGetData,

SQLNumResultCols

SQLForeignKeys
SQLForeignKeys Retrieve information about foreign keys in a table
Syntax RETCODE SQLForeignKeys (HSTMT hstmt,

UCHAR *szPkTabQual, SWORD cbPkTabQual,
UCHAR *szPkTabOwner, SWORD cbPkTabOwner,
UCHAR *szPkTabName, SWORD cbPkTabName,
UCHAR *szFkTabQual, SWORD cbFkTabQual,
UCHAR *szFkTabOwner, SWORD cbFkTabOwner,
UCHAR *szFkTabName, SWORD cbFkTabName)

szPkTabQual [Input] The primary table qualifier name.
cbPkTabQual [Input] The length of the primary table qualifier
string, in bytes. Use SQL_NTS for a NULL-
terminated string.
szPkTabOwner [Input] The primary table owner name.
cbPkTabOwner [Input] The length of the primary table owner
terminated string.
szPkTabName [Input] The primary table name.
cbPkTabName [Input] The length of the primary table string, in
bytes. Use SQL_NTS for a NULL-terminated string.
szFkTabQual [Input] The foreign table qualifier name.
cbFkTabQual [Input] The length of the foreign table qualifier
terminated string.
szFkTabOwner [Input] The foreign table owner name.
cbFkTabOwner [Input] The length of the foreign table owner string,
in bytes. Use SQL_NTS for a NULL-terminated
string.
szFkTabName [Input] The foreign table name.
cbFkTabName [Input] The length of the foreign table string, in
bytes. Use SQL_NTS for a NULL-terminated string.
Description This ODBC Level 2 function returns information about foreign keys
in the specified tables. It returns a result set based on one of the
following sets of results.

SQLForeignKeys
• If szPkTabName contains a table name, the function returns a

result set containing the primary key of that table and all of the
foreign keys that refer to it.
• If szFkTabName contains a table name, the function returns a
result set containing all of the foreign keys in the specified table
and the primary keys to which they refer.
• If both szPkTabName and szFkTabName contain table names, the
function returns a result set of the foreign keys in the
szFkTabName table that refer to the primary key in the
szPkTabName table. This result set usually contains either one or
zero rows.
In all cases, this function only returns information about foreign
keys that refer to primary keys; keys that reference unique (non-
primary) keys are ignored. Similarly, the function returns no results
if the table specified in szPkTabName has no primary key, even if it
has unique non-primary keys. Refer to the Microsoft ODBC SDK
Programmer’s Reference for ODBC-specific operational details about
SQLForeignKeys.

SQLForeignKeys
Table 12-4. Result Set Columns for SQLForeignKeys

PKTABLE_QUALIFIER varchar(32) Primary key table qualifier name or
NULL.
PKTABLE_OWNER varchar(32) Primary key table owner name or
NULL.
PKTABLE_NAME varchar(32) Primary key table name.
PKCOLUMN_NAME varchar(32) Primary key constituent column
name.
FKTABLE_QUALIFIER varchar(32) Foreign key table qualifier name or
NULL.
FKTABLE_OWNER varchar(32) Foreign key table owner name or
NULL.
FKTABLE_NAME varchar(32) Foreign key table name.
FKCOLUMN_NAME varchar(32) Foreign key constituent column
name.
KEY_SEQ smallint Sequence number of column in key
(starting with 1).
UPDATE_RULE smallint Action applied to foreign key when
operation is update:
SQL_CASCADE, SQL_RESTRICT,
SQL_SET_NULL, or NULL.
DELETE_RULE smallint Action applied to foreign key when
operation is delete. See
UPDATE_RULE, above.
PK_NAME varchar(32) Primary key identifier. Velocis
always returns NULL.
FK_NAME varchar(32) Identifier for foreign key. Always
NULL.

See Also SQLColumns, SQLPrimaryKeys, SQLTables

SQLFreeCData
SQLFreeCData Free a c_data column handle
Syntax RETCODE SQLFreeCData (HCDATA hCData)
Parameters hCData [Input] The c_data column handle.
Description This function frees a c_data column handle previously allocated in a

call to SQLAllocCData.
Return Values SQL_SUCCESS
See Also SQLAllocCData, SQLCDataColumn, SQLDescribeCData,

SQLSetCData

SQLFreeConnect
SQLFreeConnect Free the memory for a server connection
Syntax RETCODE SQLFreeConnect (HDBC hdbc)
Description This function is called after SQLDisconnect to free all memory

associated with the specified server connection. After this function
returns, the server connection handle (hdbc) is no longer valid.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLAllocConnect, SQLConnect, SQLDisconnect

SQLFreeEnv
SQLFreeEnv Free the memory for an environment
Syntax RETCODE SQLFreeEnv (HENV henv)
Description This function frees all memory associated with the specified
environment handle. Before calling this function, your application
must call SQLFreeConnect to release all allocated connection
handles. After SQLFreeEnv returns, your application cannot call
any other Velocis SQL functions except SQLAllocEnv.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLAllocConnect, SQLAllocEnv, SQLConnect, SQLDisconnect,

SQLFreeConnect

SQLFreeStmt
SQLFreeStmt End the processing of an SQL statement
Syntax RETCODE SQLFreeStmt (HSTMT hstmt, UWORD option)

option [Input] A free statement option indicator. Possible
values are:
SQL_CLOSE
Closes any cursor associated with the statement, and
discards pending results. Your application can
execute the statement later.
SQL_DROP
Closes any cursor associated with the statement, and
discards pending results. In addition, this option
frees all resources associated with the statement and
allows no further access to the statement. A
subsequent call to SQLDisconnect will automatically
discard any SQL statement handles not already
dropped.
SQL_RESET_PARAMS
Releases all parameter bindings.
SQL_UNBIND
Releases all bound columns.
Description This function ends the processing associated with the specified SQL
statement.

See Also SQLAllocStmt, SQLDisconnect

SQLGetConnectOption
SQLGetConnectOption Get the current setting for a specified connection option
Syntax RETCODE SQLGetConnectOption (HDBC hdbc, UWORD option,

PTR data)

option [Input] The connection option type indicator.
Possible values are described below.
data [Output] A pointer to the current option setting.
This parameter is either a long (SDWORD) variable
or a pointer to a character pointer.
Description This ODBC level 1 function retrieves the current setting for the
specified connection option. The list of valid connection options is
given in the next section. Some options in SQLGetStmtOption can
also be sent to this function. Refer to the Microsoft ODBC SDK
Programmer’s Reference for ODBC-specific details of
SQLGetConnectOption.
Connection You can request the types of connection options (option parameter)
Option Type indicated by the defined constants shown below. Each option
Indicators description outlines the kinds of settings that the option can contain
(data parameter).
SQL_ACCESS_MODE
Retrieves an integer that indicates whether the Velocis connection is
read only or read/write. It returns SQL_MODE_READ_ONLY if
the connection is read only and SQL_MODE_READ_WRITE if the
connection is read/write.
SQL_AUTOCOMMIT
Retrieves a 32-bit integer indicating the transaction commit state.
SQL_AUTOCOMMIT_OFF
Specifies that the application issue commits. This is the default value.
Note that it is different from the ODBC-specified default. The default
can, however, be changed through the ODBC administrator utility or
in the odbc.ini file.
SQL_AUTOCOMMIT_ON
Specifies that Velocis automatically issue a transaction commit after
each statement.

SQLGetConnectOption
SQL_LOGIN_TIMEOUT
Retrieves an integer that indicates the time, in seconds, that Velocis
waits for a login request to complete before returning to the
application. The default is 15 seconds.
SQL_OPT_TRACE
Retrieves a 32-bit integer that indicates whether the ODBC Driver
Manager traces ODBC functions. If SQL_OPT_TRACE_ON is the
value, the driver manager writes each ODBC call to a trace file. If
this value is SQL_OPT_TRACE_OFF, the driver manager does not
perform a write for each ODBC call. This option does nothing if the
application is linked directly to Velocis; it only works if the
application is linked to the ODBC library and calls Velocis through
the ODBC Driver Manager. This standard ODBC option is only for
client platforms that have DLL support (such as Windows).
SQL_TXN_ISOLATION
Retrieves a 32-bit integer indicating the transaction isolation mode.
SQL_TXN_READ_UNCOMMITTED
Indicates the transaction isolation mode is at the lowest level and that
"dirty read" mode is in effect, which allows unlocked reading of data.
SQL_TXN_READ_COMMITTED
Indicates that transaction isolation mode is on and cursor stability
mode, which allows read repeatability, is off. Changes are invisible
until the transaction is committed. Only the current row is locked.
SQL_TXN_REPEATABLE_READ
Indicates that both transaction isolation mode and cursor stability
mode are in effect. Changes are not visible until the transaction is
committed. All accessed rows remain locked until the transaction
ends. This is the highest level of isolation.
SQL_TXN_REPEATABLE_UNCOMMITTED
Indicates the "dirty read mode" is in effect, but cursor stability mode is
enforced inside the transaction.
SQL_OPT_VENDOR
Retrieves a null-terminated string identifying the vendor name
encoded in error messages provided by SQLError. The default
string for this option is "Centura".

SQL_INVALID_HANDLE
See Also SQLGetStmtOption, SQLSetConnectOption

SQLGetCursorName
SQLGetCursorName Get the current cursor name
Syntax RETCODE SQLGetCursorName (HSTMT hstmt, UCHAR *cursor,

SWORD cLen, SWORD *oLen)

cursor [Output] The cursor name.
cLen [Input] The length, in bytes, of the cursor name
(cursor) buffer.
oLen [Output] A pointer to the actual size, in bytes, of the
cursor name (cursor).
Description This function retrieves the current cursor name for the specified
SQL statement. The application can then use this cursor in a call to
SQLExecute to process positioned update and delete statements
using a separate statement handle.
For SQLGetCursorName to operate properly, the Velocis SQL
statement indicated by hstmt must correspond to a select statement
that does not contain a group by or order by clause. The statement
must have a valid cursor name.
If the application has issued a prior call to SQLSetCursorName for
the given statement, SQLGetCursorName writes the same cursor
name. If SQLSetCursorName has not been called,
SQLGetCursorName writes a Velocis-generated cursor name of the
form SQL_CUR_connection_server, resulting from a prior call to
SQLExecute. In this name, connection represents the integer the
server has assigned to the connection and server represents the
integer the server has assigned to the SQL statement handle. An
example of a Velocis-generated cursor name is
SQL_CUR_0005_0003.

See Also SQLExecute, SQLSetCursorName

SQLGetData
SQLGetData Get the column values for a select statement result
Syntax RETCODE SQLGetData (HSTMT hstmt, UWORD colNum,

SWORD cnvType, PTR outBuff, SDWORD outBuffLen,
SDWORD *actualOutLen)

colNum [Input] The column number of the result. This
number is an integer between 1 and the number of
result columns (see SQLNumResultCols).
cnvType [Input] The host variable data type as one of the
elementary data types (for example, SQL_C_LONG)
listed in Chapter 18.
outBuff [Output] A pointer to the column value.
outBuffLen [Input] The maximum length, in bytes, of the buffer
specified by outBuff. The length must include space
for the null byte when retrieving values of character
type.
actualOutLen [Output] A pointer to the state of the outBuff
parameter after processing. Possible values are:
• The actual number of bytes copied into outBuff.
• The number of bytes that were available to fetch
before the call to this function.
• SQL_NULL_DATA, if the fetched value is NULL.
Description This ODBC level 1 function serves as an alternative to SQLBindCol

for fetching column values resulting from processing of a select
statement. You can call SQLGetData after each SQLFetch or
SQLExtendedFetch call to retrieve a column value from the current
row of the result set.
If the specified buffer is not large enough to contain the entire result,
the function truncates the value of outBuff to (outBuffLen-1), and sets
actualOutLen to the true length of the result. In this case, the
function returns SQL_SUCCESS_WITH_INFO with an indication of
columns having actualOutLen >= outBuffLen as the offending
columns.
Your Velocis SQL application can call SQLGetData to retrieve any
column values from the result set. However, if your application is
using an ODBC driver, it should only call SQLGetData to retrieve

SQLGetData
data for unbound columns beyond the last bound column. Refer to
the Microsoft ODBC SDK Programmer’s Reference for ODBC-specific
details of SQLGetData.
The SQLGetData function can alternatively be used with
SQLExtendedFetch (with static cursors only) instead of SQLFetch.
To fetch the data for a particular row in a rowset, first retrieve a
rowset (using SQLExtendedFetch), then position to a row within
that rowset (using SQLSetPos). The data can then be retrieved
using SQLGetData. If SQLSetPos is not called, the data for the first
row in the rowset is retrieved.
To retrieve a bookmark, specify SQL_C_BOOKMARK as the host
variable data type (cnvType) of the parameter, and specify 0 as the
column number (colNum). The buffer length parameter (buflen) is
ignored for bookmarks. The bookmark is returned into a four-byte
integer buffer.
Additional fetching information about this function can be seen
through the following example. Suppose the following sequence of
function calls is performed:
SQLGetData(colNum=n)
SQLGetData(colNum=m)
SQLGetData(colNum=n)
The final call to SQLGetData retrieves data from the start of the nth
column. Any offset in the column data due to earlier calls to
SQLGetData for that column is no longer valid. Velocis starts
fetching where it left off, not from the beginning.
Since Velocis uses 6-byte database addresses, a special bind type
(SQL_C_DBADDR) must be used to retrieve the entire 6-byte
address. See SQLBindCol for information about this new bind
type.
With BLOB data types, it is possible to call SQLGetData multiple
times to retrieve all the data in parts. Each call retrieves the number
of bytes specified in outBuffLen into outBuff. The next call retrieves
data starting where the previous call ended. When there are no
more bytes to retrieve, SQLGetData returns
SQL_NO_DATA_FOUND. For types other than
SQL_LONGVARCHAR and SQL_LONGVARBINARY, multiple
calls to SQLGetData return SQL_NO_DATA_FOUND on the
second and all subsequent calls.

SQLGetData
For more information about using SQLGetData, see Chapter 9 of


SQL_NO_DATA_FOUND (translates to errCHTRUNC)
See Also SQLBindCol, SQLExtendedFetch, SQLFetch,

SQLNumResultCols, SQLSetPos

SQLGetFunctions
SQLGetFunctions Determine whether Velocis SQL supports an ODBC function
Syntax RETCODE SQLGetFunctions (HDBC hdbc, UWORD function,

UWORD *exists)

function [Input] The ODBC function code. Possible values
are:
0 SQL_API_ALL_FUNCTIONS
Specifies all ODBC functions.
1-100 SQL_API_* constant
Specifies a particular core (1-23), level 1 (40-54), or
level 2 (55-72) function. (Codes 24-39 and 73-100
are currently unused but are reserved by ODBC.)
An example of this constant type is
SQL_API_SQLFREESTMT.
exists [Output] A pointer to a value or array indicating
whether Velocis SQL supports the ODBC function.
If Velocis SQL supports the function, a value of one
is returned; otherwise, zero is returned.
Description This ODBC level 1 function retrieves data indicating if Velocis SQL
supports the specified ODBC function. The function writes a single
UWORD variable if function is an SQL_API_* constant.
Alternatively, if function is SQL_API_ALL_FUNCTIONS, the
function writes a 100-element UWORD array. Your application can
index each array element by the appropriate SQL_API_* constant to
determine if Velocis SQL supports a given function. Refer to the
Microsoft ODBC SDK Programmer’s Reference for more details of
SQLGetFunctions.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLGetInfo, SQLGetTypeInfo

SQLGetInfo
SQLGetInfo Get Velocis SQL capabilities
Syntax RETCODE SQLGetInfo (HDBC hdbc, UWORD infoType, PTR outBuf,

SWORD outBufLen, SWORD *actualOutLen)

infoType [Input] The information type indicator. Possible
values are listed in sqlxdefs.h.
outBuf [Output] A pointer to Velocis SQL information.
outBufLen [Input] The maximum length, in bytes, of the SQL
information.
actualOutLen [Output] A pointer to the size, in bytes, of the
Velocis SQL information.
Description This ODBC level 1 function retrieves a variety of information about

Velocis SQL capabilities. This function is available to non-ODBC
applications, but its main use is to provide information for vendor-
independent ODBC tools and applications. Refer to the Microsoft
ODBC SDK Programmer’s Reference for details about the use of
SQLGetInfo.
Currently, Velocis does not support all of the ODBC 2.0 scalar
functions. The unsupported functions are listed in the table below.
Table 12-5. Unsupported ODBC 2.0 Scalar Functions

Category Functions
String difference, locate (2-parameter version only), soundex, space
Numeric degrees, log10, power, radians, round, truncate
Date/Time dayname, monthname, timestampadd, timestampdiff

See Also SQLGetFunctions, SQLGetTypeInfo

SQLGetStmtOption
SQLGetStmtOption Get the current setting for a Velocis SQL statement option
Syntax RETCODE SQLGetStmtOption (HSTMT hstmt, UWORD option,

PTR data)

option [Input] The option type indicator. Possible option
values are listed in the Option Type Indicators
section.
data [Output] A pointer to an SDWORD variable that
contains the option setting.
Description This ODBC level 1 function retrieves the current setting of the
specified SQL statement option. Refer to the Microsoft ODBC SDK
Programmer’s Reference for details about the use of
SQLGetStmtOption.
Statement Option SQL_BIND_TYPE

Type Indicators Retrieves a long integer that specifies the binding type used by
SQLBindCol. Possible types are:
SQL_BIND_BY_COLUMN
Specifies column-wise binding, in which the pointers provided to
SQLBindCol are addresses of single columns or column arrays. This
type is the default.
SQL_BIND_BY_ROW
Specifies row-wise binding, in which the pointers provided to
SQLBindCol are addresses of the first element of a structure array in
which the column value (or output length) is located.
SQL_CALENDAR
Retrieves a long integer specifying the calendar type the current
statement is using. Possible types are GREGORIAN,
GREGORIAN_GB, ISLAMIC and ISO.
SQL_CONCURRENCY
Retrieves a long integer that specifies the cursor concurrency option
for the result set retrieved by a select statement. Possible values are:
SQL_CONCUR_LOCK
Specifies that the cursor uses the lowest level of locking needed to
update the row.

SQLGetStmtOption
SQL_CURSOR_TYPE
Specifies the type of cursor to use for the SQL statement. Velocis
supports two settings for this option:
SQL_CURSOR_FORWARD_ONLY (forward-only cursors, the
default) and SQL_CURSOR_STATIC (for static cursors).
SQL_FETCH_CHUNKSIZE
Sets size for a chunk of rows. The chunk size (default 100)
determines the maximum number of rows fetched from the server,
per network call, on a FETCH_LAST or a high absolute fetch. This
value is used to optimize data retrieval by reducing the number of
network calls necessary to retrieve the requested rows. It is only
used when more than a single rowset must be fetched from the
server to meet the request. Therefore, SQL_FETCH_LAST, or
SQL_FETCH_ABSOLUTE with a rownum value much higher than
the highest row currently cached, will use this value.
SQL_FETCH_NEXT, which only fetches the next rowset, will not
use the value.
Examples:
Suppose no rows have been fetched, the rowset size is 10, the chunk
size is 100, and the user requests the rowset starting at row 50. Velocis
fetches into the cache all rows between 1 and 59 (the last row in the
requested rowset) in one call, as opposed to making 6 calls, fetching 10
rows (the rowset size) each time.
As another example, suppose the same user requested the last rowset
instead, and the total result set size is 200. In this case, the user wants
the rowset starting at row 191 and ending at 200 (the last row). Velocis
will fetch the intervening rows into the cache first, so it will make three
network calls, the first to fetch rows 1-100, the next to fetch 101-200,
and the third to confirm there are no more rows to fetch. If the chunk
size were instead 50, then five calls would be necessary to fetch the
same data.
The chunk size sets the maximum number of rows that Velocis fetches
in this manner. If the rowset size is larger than this value, Velocis
fetches the number of rows equal to the rowset size, regardless of the
chunk size. Although a large chunk size causes fewer network calls to
fetch result data, it also results in more client side memory usage.
Velocis also uses the chunk size to determine the number of rows
kept in memory by the client side cache. Velocis will keep in
memory the quantity of rows equal to the chunk size, the rowset
size, or 100, whichever is largest.

SQLGetStmtOption
SQL_FETCH_MAXBLOB
Sets the maximum number of bytes to return from an unbound
BLOB. (If a BLOB field is bound, Velocis ignores this setting.) By
using this Velocis-specific option, you can retrieve bytes (using
SQLGetData) from an unbound BLOB without being required to re-
execute the query. The default is zero, which means that Velocis
does not return any bytes from BLOBs that are not bound. All
unbound BLOBs in the query use this value; you are not allowed to
set different values for different BLOBs in the same query.
When using static cursors, Velocis normally restricts you to fetching
only bound BLOBs. When you use static cursors, Velocis, by
default, fetches BLOB field data only if the BLOB field has been
bound. If no BLOB data is fetched, then the BLOB data from that
field cannot be accessed until you re-execute the query.
SQL_FETCH_USECHUNK
Determines whether to do "fetch ahead" operations. If this option is
set to 1, Velocis uses the chunk size (set with
SQL_FETCH_CHUNKSIZE) as the maximum number of rows to
retrieve, even if a smaller fetch could retrieve the desired rows. If
this option is set to 0, chunks are only used in fetching as outlined in
the SQL_FETCH_CHUNKSIZE option above.
Normally, an SQL_FETCH_NEXT operation fetches from the server
only the next rowset. Therefore, repeatedly calling FETCH_NEXT
with a small rowset size can generate needless network traffic.
However, with SQL_FETCH_USECHUNK set, using FETCH_NEXT
once returns from the server a quantity of rows less than or equal to
the chunk size (that is, a chunk of rows). The remaining calls using
FETCH_NEXT retrieve data from the client side cache, rather than
generating more network traffic. This can significantly increase
performance.
Example:
The user has a rowset size of 10, a chunk size of 100, and is fetching the
data using FETCH_NEXT. Normally, this action would generate a
network call with each call to SQLExtendedFetch; each call would
return 10 rows from the server. However, with the
SQL_FETCH_USECHUNK option set, the first call fetches a chunk of
rows (100) from the server. The next nine FETCH_NEXT calls will
fetch the data not from the server, but from the client side cache, which
is much faster. Since the rows will probably be stored in memory,
performance will be further enhanced by eliminating the need to
access them from the client-side disk cache.

SQLGetStmtOption
If the SQL_FETCH_USECHUNK option is set, any fetch operation

that requires server data always returns up to a chunk of rows,
unless the rowset size is larger than the chunk size; in that case, the
number of rows retrieved is equal to the rowset size. A downside of
the option is that it can take longer on the first call to retrieve a
chunk of rows from the server than a rowset, especially if the query
is complex and there is a large difference between rowset size and
chunk size. However, once the data is cached, fetching remaining
rows is much faster. In addition, large chunk sizes require more
client side memory to process the larger network packet of data.
SQL_GET_BOOKMARK
Fetches the bookmark for the current row. This option is available
only with static cursors, and only if bookmarks have been enabled
by setting the SQL_USE_BOOKMARKS statement option.
SQL_MAX_ROWS
Retrieves a long integer representing the maximum number of rows
that a select statement is allowed to retrieve for the application. If
this value is 0, no maximum limit is enforced.
SQL_NOSCAN
Retrieves a long integer indicating whether SQL statement strings
are being scanned for ODBC escape sequences. Possible values are:
SQL_NOSCAN_OFF
Specifies that the driver scans strings for escape sequences. This is the
default setting.
SQL_NOSCAN_ON
Specifies that the driver does not scan for escape sequences.
SQL_QUERY_TIMEOUT
Retrieves a 32-bit integer value that specifies the number of hold
locks before timing out. The default timeout is 30 seconds. A value
of 0 indicates that no timeout is set.
SQL_ROWSET_SIZE
Retrieves a long integer that specifies the number of rows in the
result set for a select statement.
SQL_USE_BOOKMARKS
Specifies whether to use bookmarks. SQL_UB_ON turns on
bookmarks, and SQL_UB_OFF (the default) turns them off. This
option must be turned on before bookmarks can be used, and the
SQL_CURSOR_TYPE option must be set to SQL_CURSOR_STATIC
before activating this option.

SQLGetStmtOption

See Also SQLBindCol, SQLSetScrollOptions, SQLSetStmtOption

SQLGetTypeInfo
SQLGetTypeInfo Get the Velocis SQL characteristics for ODBC data types
Syntax RETCODE SQLGetTypeInfo (HSTMT hstmt, SWORD sqlType)

sqlType [Input] The type indicator for ODBC data, as
defined in Chapter 18. Specify one of these
constants:
SQL_ALL_TYPES
SQL_BINARY
SQL_CHAR
SQL_DATE
SQL_DECIMAL
SQL_DOUBLE
SQL_FLOAT
SQL_INTEGER
SQL_LONGVARBINARY
SQL_LONGVARCHAR
SQL_REAL
SQL_SMALLINT
SQL_TIME
SQL_TIMESTAMP
SQL_VARBINARY
SQL_VARCHAR
Description This ODBC level 1 function retrieves a result set describing Velocis
SQL-specific characteristics of the specified ODBC data type(s). If
the sqlType parameter corresponds to one data type, the result set
consists of a single row. If the function retrieves no rows, the
specified type is not supported by Velocis. If the value of sqlType is
SQL_ALL_TYPES, the function retrieves one row for each
supported type. Refer to the Microsoft ODBC SDK Programmer’s
Reference for details of SQLGetTypeInfo and a description of the
result set.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLGetFunctions, SQLGetInfo

SQLKill
SQLKill Kill an SQL statement executing in a separate connection
Syntax RETCODE SQLKill (HDBC thisHdbc, HDBC thatHdbc)
Parameters thisHdbc [Input] The SQL connection handle for the session
within which this function is being called.
thatHdbc [Input] The SQL connection handle of the session
with the statement to be killed.
Description This function terminates a long-running SQL statement being

executed within a companion connection inside the same program.
The function must be called from a separate connection that is
executing in a separate thread.
The SQLExecDirect, SQLExecute, SQLFetch, or
SQLExtendedFetch call that has the long-running query will return
SQL_ERROR. A subsequent call to SQLError returns the Velocis
error code errCANCELED and the ODBC error code S1008,
"operation canceled."
Return Values SQL_INVALID_HANDLE SQL_SUCCESS
See Also SQLCancel
Example
/* Separate thread function */
void KillThread(void *pHdbc)
{
RETCODE stat;
HDBC thisHdbc, thatHdbc;
thatHdbc = *(HDBC *)pHdbc;
WaitForButtonClick();
SQLAllocConnect(henv, &thisHdbc);
stat = SQLConnect(thisHdbc, server, SQL_NTS, user,
SQL_NTS, password, SQL_NTS);
if ( stat == SQL_SUCCESS ) {
SQLKill(thisHdbc, thatHdbc);
SQLDisconnect(thisHdbc);
SQLFreeConnect(thisHdbc);
}
}

SQLMoreResults
SQLMoreResults Determine whether a stored procedure has more statements to

process
Syntax RETCODE SQLMoreResults (HSTMT hstmt)
Description This ODBC level 2 function determines if a stored procedure has

more statements to process. If SQLMoreResults finds unexecuted
statements, it calls SQLExecute for the next statement and returns
SQL_SUCCESS if successful. After the last statement in the stored
procedure has been executed, SQLMoreResults returns
SQL_NO_DATA_FOUND. Refer to the Microsoft ODBC SDK
Programmer’s Reference for details of SQLMoreResults.
Your application can call SQLNumResultCols to determine if the
statement executed by a call to SQLMoreResults is a select
statement that produces a result set. If the number of columns in
the result set is greater than zero, the application can call
SQLDescribeCol and SQLBindCol to set up SQLFetch. If the
application then calls SQLFetch, the function retrieves each row of
the result set.

SQL_NO_DATA_FOUND
See Also SQLBindCol, SQLDescribeCol, SQLExecute, SQLExtendedFetch,

SQLFetch, SQLNumResultCols

SQLNativeSql
SQLNativeSql Translate a statement from ODBC-compliant SQL to Velocis SQL
Syntax RETCODE SQLNativeSql (HDBC hdbc,

UCHAR *sqlIn, SDWORD sqlInLen,
UCHAR *nativeOut, SDWORD nativeOutLen,
SDWORD *actualOutLen)

sqlIn [Input] A string that contains the ODBC-compliant
SQL statement.
sqlInLen [Input] The length, in bytes, of the statement string
indicated by sqlIn.
nativeOut [Output] A string that contains the Velocis SQL
statement.
nativeOutLen [Input] The maximum length, in bytes, of the
Velocis SQL statement string (nativeOut).
actualOutLen [Output] A pointer to the actual length, in bytes, of
the Velocis SQL statement string (nativeOut).
Description This ODBC level 2 function translates an ODBC-compliant SQL

statement string into the equivalent Velocis SQL statement string.
Velocis supports this function, but it is intended for use by
developers of vendor-independent ODBC tools and applications.
Refer to the Microsoft ODBC SDK Programmer’s Reference for details
of SQLNativeSql.


SQLNumParams
SQLNumParams Retrieve the number of parameter markers in a statement
Syntax RETCODE SQLNumParams (HSTMT hstmt, SWORD *numParms)

numParms [Output] A pointer to the number of parameter
markers.
Description This ODBC level 2 function retrieves the number of parameter

markers in the specified SQL statement. Your application must call
SQLPrepare before calling SQLNumParams. Refer to the Microsoft
ODBC SDK Programmer’s Reference for details of SQLNumParams.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLBindParameter, SQLPrepare, SQLSetParam

SQLNumResultCols
SQLNumResultCols Retrieve the number of columns in a result set
Syntax RETCODE SQLNumResultCols (HSTMT hstmt, SWORD *numCols)

numCols [Output] A pointer to the number of columns.
Description This function retrieves the number of columns in the result set for
the specified select statement. Your application must call
SQLPrepare (or SQLExecDirect) before issuing a call to
SQLNumResultCols.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLBindCol, SQLDescribeCol, SQLExecDirect, SQLPrepare

SQLParamData
SQLParamData Retrieve the parameter values specified by SQLBindParameter as

SQL_DATA_AT_EXEC parameters
Syntax RETCODE SQLParamData (HSTMT hstmt, PTR *outBuff)

outBuff [Output] A pointer to an SQL_DATA_AT_EXEC
parameter.
Description This ODBC level 1 function is used with SQLPutData to retrieve

SQL_DATA_AT_EXEC parameter values previously specified by
SQLBindParameter. The SQLParamData function primarily passes
large parameter values associated with data types long varchar and
long varbinary. For details of SQLParamData, refer to the Microsoft
ODBC SDK Programmer’s Reference.
After a call to SQLExecute or SQLExecDirect to execute the query,
SQL_DATA_AT_EXEC parameter values are set by individual calls
to SQLParamData. When called, this function returns
SQL_NEED_DATA, while outBuff contains a pointer to the data
buffer previously set by SQLBindParameter for the first
SQL_DATA_AT_EXEC parameter. The data contained in this
parameter is then written to the buffer by calling SQLPutData. If
the data is a BLOB type, SQLPutData can be called repeatedly to
send the data in parts to the server; otherwise, this function can be
called only once per parameter.
The process outlined above is repeated for each
SQL_DATA_AT_EXEC parameter, sequentially according to the
numbering set by SQLBindParameter, until SQLParamData returns
SQL_SUCCESS. This status code indicates that all
SQL_DATA_AT_EXEC parameters associated with hstmt were sent
to the server.
Return Values SQL_ERROR SQL_NEED_DATA

SQL_INVALID_HANDLE SQL_SUCCESS
See Also SQLBindParameter, SQLPutData, SQLSetParam

SQLPrepare
SQLPrepare Compile a Velocis SQL statement
Syntax RETCODE SQLPrepare (HSTMT hstmt, UCHAR *sqlStr,

SWORD sqlStrLen)

sqlStr [Input] A string that contains an Velocis SQL
statement.
sqlStrLen [Input] The length, in bytes, of the SQL statement
string. For a null-terminated string, specify
SQL_NTS.
Description This function compiles the specified Velocis SQL statement, which is
subsequently executed in a call to SQLExecute. If SQLPrepare finds
errors in the statement that it is processing, it returns SQL_ERROR.
The Velocis SQL statement processed by SQLPrepare can include
embedded host variable references or parameter markers. Each
parameter marker must be encoded as a literal "?". After
SQLPrepare finishes, your application can change a parameter
marker before calling SQLExecute by simply changing the value of
the host variables. The application can also change the host variable
for a parameter by calling SQLBindParameter before the next
SQLExecute call.

See Also SQLBindParameter, SQLExecute

SQLPrimaryKeys
SQLPrimaryKeys Retrieve the information about a table’s primary key columns
Syntax RETCODE SQLPrimaryKeys (HSTMT hstmt,

UCHAR *szTabQual, SWORD cbTabQual,
UCHAR *szTabOwner, SWORD cbTabOwner,
UCHAR *szTabName, SWORD cbTabName)

szTabQual [Input] The table qualifier name.
cbTabQual [Input] The length of the table qualifier string, in
bytes. Use SQL_NTS for a null-terminated string.
szTabOwner [Input] The table owner name.
cbTabOwner [Input] The length of the table owner string, in
bytes. Use SQL_NTS for a null-terminated string.
szTabName [Input] The table name.
cbTabName [Input] The length of the table string, in bytes. Use
SQL_NTS for a null-terminated string.
Description This ODBC Level 2 function returns a result set for the table
specified in szTabName that names the primary key columns of that
table. One row is returned for each column that is part of the
primary key. This function only returns information for one table at
a time, and no wildcards are allowed in szTabName. The function
only returns primary key information, not unique (non-primary)
key information. Refer to the Microsoft ODBC SDK Programmer’s
Reference for ODBC-specific operational details about this function.
Table 12-6. Result Set Columns for SQLPrimaryKeys

TABLE_QUALIFIER varchar(32) Table qualifier name or NULL.
TABLE_OWNER varchar(32) Table owner name or NULL.
TABLE_NAME varchar(32) Table name.
COLUMN_NAME varchar(32) Primary key constituent column name.
KEY_SEQ smallint Sequence number of column in key
(starting with 1).
PK_NAME varchar(32) Primary key identifier. Velocis always
returns NULL.

SQLPrimaryKeys

See Also SQLForeignKeys

SQLProcedures
SQLProcedures Describe the available stored procedures
Syntax RETCODE SQLProcedures (HSTMT hstmt,

UCHAR *procQual, SWORD procQualLen,
UCHAR *procOwner, SWORD procOwnerLen,
UCHAR *procName, SWORD procNameLen)

procQual [Input] Unused.
procQualLen [Input] Unused.
procOwner [Input] Unused.
procOwnerLen [Input] Unused.
procName [Input] The name of the search string to be applied
in finding the procedures. If this parameter is
NULL, the function finds all procedures.
procNameLen [Input] The length, in bytes, of the procedure name
(procName). For a null-terminated string, specify
SQL_NTS.
Description This ODBC level 2 function produces a result set describing the
stored procedures available on the Velocis server. The function
provides all stored procedure names that match the specified search
pattern (procName) in a result set, with one row for each stored
procedure and columns ordered by PROCEDURE_NAME (see the
table below). If procName is NULL, SQLProcedures provides the
names of all stored procedures. Your application can then retrieve
the result set by calling SQLFetch or SQLExtendedFetch. For
details of SQLProcedures, refer to the Microsoft ODBC SDK
Programmer’s Reference.

SQLProcedures
Table 12-7. Result Set Columns for SQLProcedures

NUM_INPUT_PARAMS integer The number of input
parameters for the procedure.
NUM_OUTPUT_PARAMS integer 0. Velocis SQL stored
procedures have no output
parameters.
NUM_RESULT_SETS integer -1. The number of result sets
is unknown.
PROCEDURE_NAME varchar (32) The name of the stored
procedure.
PROCEDURE_OWNER null Unused for Velocis SQL.
PROCEDURE_QUALIFIER null Unused for Velocis SQL.
REMARKS varchar (132) Comments about the stored
procedure.
Note: In Velocis, the SQLProcedures function does not return the

PROCEDURE_TYPE column information.

See Also SQLColumns, SQLExtendedFetch, SQLFetch, SQLTables

SQLPutData
SQLPutData Supply parameter values specified by SQLBindParameter as

SQL_DATA_AT_EXEC parameters
Syntax RETCODE SQLPutData (HSTMT hstmt, PTR inBuff,

SDWORD inBuffLen)

inBuff [Input] A pointer to a parameter value.
inBuffLen [Input] The length, in bytes, of the parameter value
(inBuff).
Description This ODBC level 1 function is used with SQLParamData to supply

SQL_DATA_AT_EXEC parameter values previously specified by
SQLBindParameter. The SQLPutData function primarily passes
large parameter values associated with data types long varchar and
long varbinary. For details of SQLPutData, refer to the Microsoft
ODBC SDK Programmer’s Reference. For details about the
SQL_DATA_AT_EXEC parameter, refer to the SQLParamData
function.
Note: It might be simpler for your application to just call

SQLBindParameter, entirely avoiding SQL_DATA_AT_EXEC type
parameter processing.

See Also SQLBindParameter, SQLParamData, SQLSetParam

SQLRowCount
SQLRowCount Retrieve the number of rows processed by an insert, update, or

delete statement
Syntax RETCODE SQLRowCount (HSTMT hstmt, SDWORD *numRows)
Parameters hstmt [Input] The SQL statement handle for an insert,

update, or delete statement.
numRows [Output] A pointer to the number of rows
processed.
Description This function retrieves the number of rows processed by an insert,

update, or delete statement. Your application can only call
SQLRowCount after calling SQLExecute or SQLExecDirect.
The SQLRowCount function is not intended (according to ODBC
specification) for use with a select statement. However, if you do
use it with a select statement, it will behave as follows:
• If you call this function after a call to SQLExecute or
SQLExecDirect, but before a call to SQLFetch or
SQLExtendedFetch, it returns the row cardinality estimate for
the query (that is, the number of rows that the Velocis SQL
query optimizer expects to return).
• If you call this function after a call to SQLFetch or
SQLExtendedFetch, it returns the number of rows that were
fetched.
Examples:
• Calling SQLRowCount after five calls to SQLFetch returns a
value of 5.
• Calling SQLRowCount after a single call to SQLExtendedFetch,
when the rowset size is 10, returns a value of 10.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLDescribeStmt, SQLNumResultCols

SQLRowDba
SQLRowDba Retrieve the database address of the current table row
Syntax RETCODE SQLRowDba (HSTMT hstmt, UCHAR *tblname,

DB_ADDR *dba)
references the table.
tblname [Input] The table name. If correlation names have
been used for the tables listed in the from clause of
the referencing select statement, you must specify
the correlation name.
dba [Output] A pointer to the database address.
Description This function retrieves the database address of the current row of
the specified table, if the table is referenced in the specified SQL
statement. If the statement is insert, it must have been executed
prior to your application’s call to SQLRowDba. If the statement is
select, update, or delete, it must have been positioned before your
application calls SQLRowDba. If the statement is select, it must
also not contain an order by or a group by clause. The function
returns SQL_ERROR if the given SQL statement does not reference
the specified table.
Note: After SQLRowDba returns, your application can use the

database address in calls to Velocis Core API functions.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLRowId

SQLRowId
SQLRowId Retrieve the identifier of the current table row
Syntax RETCODE SQLRowId (HSTMT hstmt, UCHAR *tblname,

UDWORD *pRowid)
tblname [Input] The table name. If correlation names were
used for the tables listed in the from clause of the
referencing select statement, you must specify the
correlation name.
pRowid [Output] A pointer to the row identifier.
Description This function retrieves the identifier of the current row from the
given table being accessed by the specified SQL statement. If the
statement is insert, it must have been executed prior to your
application’s call to SQLRowId. If the statement is select, update,
or delete, it must have been positioned before your application calls
SQLRowId. If the statement is select, it must also not contain an
order by or a group by clause. The function returns SQL_ERROR if
the specified table is not referenced in the SQL statement.
This function is useful when using primary keys of the rowid type.
For example, after your application executes an insert statement to
insert a row in a table with a primary key of the rowid type, a call to
SQLRowId will retrieve the identifier of the inserted row. Your
application can then specify this row identifier in any insert
statements using foreign keys that reference the table containing the
row.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLRowDba

SQLRowIdToDba
SQLRowIdToDba Convert the identifier of table row to the database address of the
row
Syntax RETCODE SQLRowIdToDba (HSTMT hstmt, UCHAR *tblname,

UDWORD rowid, DB_ADDR *dba)
tblname [Input] The table name. If correlation names have
been used for the tables listed in the from clause of
the referencing select statement, you must specify
the correlation name.
rowid [Input] A pointer to the row identifier.
dba [Output] A pointer to the database address.
Description This function converts a row identifier to the database address for
the row. If the statement that references the specified table is insert,
it must have been executed prior to your application’s call to
SQLRowIdToDba. If the statement is select, update, or delete, it
must have been positioned before your application calls
SQLRowIdToDba. The function returns SQL_ERROR if the
database address is not valid for the specified table or if the
specified table is not referenced in the given SQL statement.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLDbaToRowId, SQLRowDba, SQLRowId

SQLSessionId
SQLSessionId Retrieve the Velocis session handle
Syntax RETCODE SQLSessionId (HDBC hdbc, RDM_SESS *sess_id)

sess_id [Output] A pointer to the session handle
corresponding to the server connection.
Description This function retrieves the Velocis session handle associated with
the specified server connection handle (hdbc). Your application
needs the session handle to call extension modules located on the
server side of Velocis. The application also uses the session handle
in calling Velocis Runtime API functions.
The session ID is used with the em_call function to call a Velocis
extension module from a client application.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLConnectWith

SQLSetCData
SQLSetCData Set the value of a c_data column
Syntax RETCODE SQLSetCData (HCDATA hCData, void *pValue)
Parameters hCData [Input] The c_data column handle.

pValue [Input] A pointer to the values to set.
Description This function sets the specified c_data column to the indicated
values. The application uses SQLAllocCData to allocate hCData, a
parameter that contains information about the c_data column, such
as member column sizes and types. Use this function to set the data
values inside the handle. See SQLAllocCData for more details.
See Also SQLAllocCData, SQLCDataColumn, SQLDescribeCData,

SQLFreeCData

SQLSetConnectOption
SQLSetConnectOption Set the connection option
Syntax RETCODE SQLSetConnectOption (HDBC hdbc, UWORD option,

UDWORD toValue)

option [Input] The type indicator for the current
connection option. Possible values are described for
the SQLGetConnectOption function. Options
listed in SQLGetStmtOption can also be used.
toValue [Input] The new value to set for the connection
option. This parameter can be either a 32-bit integer
or a pointer to a NULL-terminated string,
depending on which option is chosen.
Description This ODBC level 1 function sets the specified connection option to a
new value (toValue). For details of SQLSetConnectOption, refer to
the Microsoft ODBC SDK Programmer’s Reference.
Note: If an option listed in SQLGetStmtOption is used with this

function, it will set the option for all statement handles associated
with the server connection.

See Also SQLGetConnectOption, SQLGetStmtOption

SQLSetCursorName
SQLSetCursorName Set the cursor name
Syntax RETCODE SQLSetCursorName (HSTMT hstmt, UCHAR *cursor,

SWORD cursorLen)

cursor [Input] The new cursor name to set.
cursorLen [Input] The length, in bytes, of the cursor name. For
Description This function sets a user-defined cursor name (cursor) for the
specified SQL statement. The application can then use the cursor to
process positioned update and delete statements in calls to
SQLExecute with a separate SQL statement handle.
For SQLSetCursorName to operate properly, the Velocis SQL
statement indicated by hstmt must correspond to a select statement
that does not contain a group by or order by clause.
Note: Your application must call SQLSetCursorName before

calling SQLExecute.

See Also SQLGetCursorName

SQLSetParam
SQLSetParam Set the value of a host variable reference or a parameter marker
Syntax RETCODE SQLSetParam (HSTMT hstmt, UWORD pnum,

SWORD ctype, SWORD dtype, UDWORD coldef,
SWORD scale, PTR value, SDWORD *len)

pnum [Input] The parameter number. This number starts
at 1.
ctype [Input] The elementary data type of the host
variable that contains the parameter value. See the
possible data types in Chapter 18.
stype [Input] The SQL data type that Velocis associates
with the parameter, as determined from its context
in the specified SQL statement. Possible types are
described in Chapter 18.
coldef [Input] The precision of the parameter after
conversion to its SQL data type. The only SQL data
types using this parameter are SQL_CHAR
(precision is the length of the string excluding the
null byte), SQL_DECIMAL, and SQL_TIMESTAMP.
scale [Input] The decimal scaling factor for parameters of
type SQL_DECIMAL and SQL_TIMESTAMP. The
scaling factor is the maximum number of digits to
the right of the decimal point.
value [Input] A pointer to the host variable containing the
parameter.
len [Input] A pointer to the length, in bytes, of the host
variable.
Description This function sets the value of a host variable reference or parameter
marker embedded in the hstmt statement. While SQLSetParam is
left in Velocis for backward compatibility, new users should use the
SQLBindParameter function.

See Also SQLBindParameter

SQLSetPos
SQLSetPos Set the cursor position within a rowset
Syntax RETCODE SQLSetPos (HSTMT hstmt, UWORD row,

UWORD fOption, UWORD fLock)
Parameters hstmt [Input] A statement handle with at least one rowset

already fetched on it with SQLExtendedFetch.
row [Input] The row number to position to within the
rowset. This must be between 1 (the first row in the
rowset) and the number of rows in the current
rowset.
fOption [Input] The operation to perform. Currently, only
SQL_POSITION is supported.
fLock [Input] Currently not used.
Description This ODBC Level 2 function positions the current row within a
rowset. Once positioned, SQLGetData can be called on the current
row to retrieve its data, thus allowing SQLGetData functionality
within a multi-row rowset. Before calling SQLSetPos, the user must
set the statement to use static cursors, execute a query, and use
SQLExtendedFetch (not SQLFetch) to fetch at least one rowset. The
function returns an error if row is less than 1 or greater than the
number of rows in the current rowset. The SQLSetPos function also
returns an error if the cursor is positioned either before the
beginning or after the end of the result set. After calling
SQLExtendedFetch, the current row is set to the first row in the
current rowset.

See Also SQLExtendedFetch

SQLSetScrollOptions
SQLSetScrollOptions Set the scroll options
Syntax RETCODE SQLSetScrollOptions (HSTMT hstmt,

UWORD concurrency, SDWORD numRowKeys,
UWORD numRows)

concurrency [Input] The scroll concurrency option. The default
setting is SQL_CONCUR_READ_ONLY (read-
only). The SQL_CONCUR_LOCK setting can also
be used to specify that the server uses the lowest
level of locking possible to ensure that the row can
be updated.
numRowKeys [Input] The cursor operation indicator. For
forward-only cursors (the default), specify
SQL_SCROLL_FORWARD_ONLY. For static
cursors, specify SCR_SCROLL_STATIC.
numRows [Input] The number of rows in the result set. A
value of 1 for this parameter specifies retrieval of
rows via SQLFetch. For this case, the concurrency
parameter can be set to either of the two values
shown above. If the value is greater than 1, then
retrieval of rows via SQLExtendedFetch is
specified, with concurrency set to
SQL_CONCUR_READ_ONLY.
Description This ODBC level 2 function sets scroll options for select statements
with the specified handle. While this function is left in Velocis for
backward compatibility, it has been superseded by the
SQLSetStmtOption function.
The SQLSetScrollOptions function supports both forward-only (the
default) and static cursors. You can change the cursor type by using
the SQL_SCROLL_FORWARD_ONLY and SQL_SCROLL_STATIC
options, respectively, in the SQLSetStmtOption function.
Changing the cursor type requires a call to this function before the
statement has been prepared. In Velocis 2.0 and earlier, this
function could be called anytime, as it set the rowset size only.
However, the cursor type can only be set before the statement is
prepared, hence this new requirement.

SQLSetScrollOptions

See Also SQLExtendedFetch, SQLFetch, SQLGetStmtOption,

SQLSetStmtOption

SQLSetStmtOption
SQLSetStmtOption Set the Velocis SQL statement option
Syntax RETCODE SQLSetStmtOption (HSTMT hstmt, UWORD option,

UDWORD toValue)

option [Input] The option type indicator.
toValue [Input] The new option setting. Possible values are
listed in SQLGetStmtOption.
Description This ODBC level 1 function sets the value of the option associated
with the specified statement. Refer to the Microsoft ODBC SDK
Programmer’s Reference for details about the use of
SQLSetStmtOption.
Normally, Velocis returns the data type of rowid columns as
SQL_INTEGER (from functions such as SQLDescribeCol,
SQLColAttributes, and SQLColumns). This is because the ODBC
specification does not clearly specify how a third-party ODBC
application handles a driver-specific type in a data source.
However, if an application is directly linked with Velocis, Velocis
can return the rowid column’s type as SQL_ROWID. To activate
this feature, call SQLSetStmtOption with the
SQL_ACTUAL_TYPES option and an option setting parameter of
TRUE. To turn off this feature, repeat that function call, but instead
use an option setting parameter of FALSE (the default setting). Do
not set this option if you are connecting to Velocis through ODBC.

See Also SQLGetStmtOption

SQLShowPlan
SQLShowPlan Show the execution plan chosen by the optimizer for a query
Syntax RETCODE SQLShowPlan (HSTMT hPlan, HSTMT hQuery)
Parameters hPlan [Input] The SQL statement handle on which the

results of this function are returned.
hQuery [Input] The SQL statement handle on which the
execution plan is found.
Description This function sets up a result set containing information about the
execution plan the optimizer has picked for the query specified by
hQuery. There is one row for each table in hQuery, specifying the
method Velocis uses to access the data. The columns of the result
set are shown below.

SQLShowPlan
Table 12-8. Result Set Columns for SQLShowPlan

STEP_NUMBER smallint Indicates the step number of the
particular access step.
DB_NAME char(32) Indicates the name of the database
holding the table that is accessed in this
step.
TABLE_NAME char(32) Indicates the name of the table that is
accessed in this step.
ACCESS_METHOD char(15) Indicates the access method for this
table. The possible access methods are
listed in another table below.
ACCESS_NAME char(32) Indicates the name of the index used
for access, if the ACCESS_METHOD is
INDEX SCAN, INDEX LIST, INDEX
LIKE, INDEX FIND, or JOINED
INDEX, or the name of the join used if
the method is F_TO_P JOIN or P_TO_F
JOIN. Otherwise this column is NULL.
STEP_CARDINALITY integer Estimates the number of rows returned
from this step.
PLAN_CARDINALITY float Estimates the number of rows returned
from the query.
PLAN_COST float Estimates the total cost (in logical I/Os)
to execute the query.
SORT_LEN smallint Indicates the length of the sort record
for the order by clause (0 => no sort
required).
GROUP_LEN smallint Indicates the length of the sort record
for the group by clause (0 => no sort
required).
The possible result values for the ACCESS_METHOD column are

shown below.

SQLShowPlan
Table 12-9. Access Methods for SQLShowPlan

Access Method Description
TABLE SCAN Scans the entire table from beginning to end.
INDEX SCAN Scans an index from beginning to end, or from or to a
specified point (the between clause, inequality
operations).
INDEX LIST Searches an index from a list of values (the in clause).
INDEX LIKE Searches an index for values that match a supplied
pattern (the like clause).
INDEX FIND Searches an index for a specified value (equality
operation).
F-TO-P JOIN Traverses a join from the foreign key to the primary key.
P-TO-F JOIN Traverses a join from the primary key to the foreign key.
DIRECT Accesses a table directly through a rowid value.
VIEW SCAN Access method for views.
JOINED INDEX Uses an index on a primary key through a foreign key
join, even if the primary table is not referenced in the
query.
JOINED DIRECT Uses a rowid on a primary key through a foreign key
join, even if the primary table is not referenced in the
query.

SQL_INVALID_HANDLE
SQL_SUCCESS

SQLSpecialColumns
SQLSpecialColumns Prepare a result set from columns that uniquely identify and access
rows
Syntax RETCODE SQLSpecialColumns (HSTMT hstmt, UWORD colType,

UWORD scope, UWORD nullable)

colType [Input] The column type indicator. If the columns
are for use with Velocis SQL, specify
SQL_BEST_ROWID; otherwise, specify
SQL_ROWVER.
SQL_NTS.
tabOwner [Input] The name of the table owner.
tabOwnerLen [Input] The length, in bytes, of the table owner
SQL_NTS.
tabName [Input] The name of the table.
scope [Input] The indicator for the minimum required
scope for the column type (colType). The
application uses this parameter to request that the
function only write columns that are valid for the
specified scope. Possible scope values are:
SQL_SCOPE_CURROW
Specifies that column values uniquely identifying
each row only be valid the first time the row is
accessed. Subsequent access might find the row
deleted or changed.
SQL_SCOPE_TRANSACTION
each row be valid for the duration of a transaction.

SQLSpecialColumns
SQL_SCOPE_SESSION
each row be valid for the entire session.
nullable [Input] The null state indicator for a column. If the
column cannot contain nulls, specify
SQL_NO_NULLS; otherwise, specify
SQL_NULLABLE.
Description This ODBC level 1 function sets up a result set for the specified SQL
statement. The function forms the set from table columns that
uniquely identify and access rows in the same table. The table to be
processed by SQLSpecialColumns is specified through the
database name (tabQual or tabOwner) and the table name (tabName).
Refer to the Microsoft ODBC SDK Programmer’s Reference for ODBC-
specific operational details about SQLSpecialColumns.
The function places in the result set all special columns that match
the specified search pattern for all three parameters. If
SQLSpecialColumns finds no columns that can be used to uniquely
identify table rows, it returns SQL_NO_DATA_FOUND.
Each row of the set contains information about one of the columns
(see the table below). Your application can obtain these rows by
calling SQLFetch or SQLExtendedFetch.
Result set rows have a scope that is at least as restrictive as that
specified in the scope parameter. As defined for Velocis SQL
applications, all special columns support a scope of
SQL_SCOPE_CURROW. Sometimes the actual scope may be larger,
but SQLSpecialColumns cannot determine this because the Velocis
SQL user can change operational characteristics dynamically. For
example, if cursor stability mode (read repeatability) is turned on,
SQL_SCOPE_TRANSACTION is the type of scope used. If the
database has been opened in exclusive access mode, the type of
scope is SQL_SCOPE_SESSION.

SQLSpecialColumns
Table 12-10. Result Set Columns for SQLSpecialColumns

SCOPE smallint The indicator for the minimum
required scope. For Velocis SQL, the
indicator is SQL_SCOPE_CURROW.
COLUMN_NAME varchar(32) The name of the column.
DATA_TYPE smallint The ODBC data type code number. See
SQLGetTypeInfo.
TYPE_NAME varchar(32) The name of the data type.
PRECISION integer The declared precision of the column.
LENGTH integer The length, in bytes, of the column.
SCALE smallint The scale of the column (decimal types
only).
PSEUDO_COLUMN smallint Whether the column is a
pseudo_column. All Velocis rows
return SQL_PC_NOT_PSEUDO.
Return Values SQL_ERROR SQL_NO_DATA_FOUND

SQL_INVALID_HANDLE SQL_SUCCESS
See Also SQLColumns, SQLExtendedFetch, SQLFetch, SQLStatistics,

SQLTables

SQLStatistics
SQLStatistics Prepare a result set containing statistics about a table and its indexes
Syntax RETCODE SQLStatistics (HSTMT hstmt,

UWORD unique, UWORD accuracy)
name. For a null-terminated string, use SQL_NTS.
unique [Input] The index type. Set to TRUE (1) for a
unique index or FALSE (0) for an index that can
contain duplicate values.
accuracy [Input] The indicator of the importance level for
correctly retrieving the CARDINALITY and PAGES
columns. Specify SQL_QUICK to retrieve the
columns only if it can be readily done. Specify
SQL_ENSURE to ensure unconditionally that the
columns are retrieved.
Description This ODBC level 1 function produces a result set for the specified
SQL statement. The function forms the set from statistics on the
specified table and any indexes that are defined for the table. Refer
to the Microsoft ODBC SDK Programmer’s Reference for ODBC-
specific operational details about SQLStatistics.
If SQLStatistics finds no statistics that can be used to uniquely
identify table rows, it returns SQL_NO_DATA_FOUND.
In the result set, the statistics are ordered by NON_UNIQUE, TYPE,
INDEX_QUALIFIER, INDEX_NAME, and then SEQ_IN_INDEX.
Each row of the set contains information about one of the statistics
or indexes (see the table below). Your application can obtain these
rows by calling SQLFetch or SQLExtendedFetch.

SQLStatistics
Table 12-11. Result Set Columns for SQLStatistics

TABLE_QUALIFIER varchar(32) The name of the database containing
the table.
TABLE_NAME varchar(32) The name of the table containing the
statistics.
NON_UNIQUE smallint The index state. Possible values are:
0 Index is unique.
1 Index is non-unique.
NULL TYPE is SQL_TABLE_STAT.
INDEX_QUALIFIER varchar(32) The table that contains the index. Its
value is NULL if TYPE is
SQL_TABLE_STAT.
INDEX_NAME varchar(32) The name of the index. Its value is
NULL if TYPE is SQL_TABLE_STAT.
TYPE smallint The statistics type indicator. If this
value is SQL_TABLE_STAT, the
statistics are for a table. If this value
is SQL_INDEX_OTHER, the statistics
are for an index.
SEQ_IN_INDEX smallint The sequence number for the column
in the index, starting at 1. This value
is NULL when TYPE value is
SQL_TABLE_STAT.
COLUMN_NAME char(32) The name of the subcolumn within
the index.
COLLATION char(1) The ordering for the column in the
index. Possible values are:
A Ascending order.
D Descending order.
NULL TYPE is SQL_TABLE_STAT.
CARDINALITY integer The number of rows in the table if
the value of TYPE is
SQL_TABLE_STAT. If the value of
TYPE is SQL_INDEX_OTHER, this
item specifies the number of unique
values in the index.
PAGES integer The number of database pages used
to store the index or table.
FILTER_CONDITION char(1) Always NULL for Velocis.

SQLStatistics
Note: The CARDINALITY and PAGES values are only accurate at

the time of the most recent update statistics statement for the
database.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLColumns, SQLExtendedFetch, SQLFetch,

SQLSpecialColumns, SQLTables

SQLTables
SQLTables Prepare a result set of the tables in a database
Syntax RETCODE SQLTables (HSTMT hstmt,

UCHAR *tabType, SWORD tabTypeLen)

SQL_NTS.
tabType [Input] A string indicating the list of table types.
tabTypeLen [Input] The length, in bytes, of the table type list.
For a null-terminated string, specify SQL_NTS.
Description This ODBC level 1 function produces a result set for the specified
SQL statement. The function forms the set from the tables contained
in the specified database. Refer to the Microsoft ODBC SDK
Programmer’s Reference for ODBC-specific operational details about
SQLTables.
The SQLTables function associates tables with the tabQual and
tabName parameters, each of which can contain a search pattern.
The function places in the result set all tables that match the
specified search pattern for these parameters. If SQLTables finds
no tables, it returns SQL_NO_DATA_FOUND.
In the result set, the tables are ordered by TABLE_TYPE,
TABLE_QUALIFIER, and TABLE_NAME. Each row of the set
contains information about one of the tables (see the table below).
Your application can obtain these rows by calling SQLFetch or
SQLExtendedFetch.

SQLTables
Table 12-12. Result Set Columns for SQLTables

TABLE_QUALIFIER varchar(32) The name of the database
containing the table.
TABLE_NAME varchar(32) The name of the table.
TABLE_TYPE varchar(12) The table type. Possible values
are TABLE, VIEW, and
SYSTEM TABLE, which specify
a database table, view table, and
system table, respectively.
REMARKS varchar(132) Comments about the table.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLColumns, SQLExtendedFetch, SQLFetch,

SQLSpecialColumns, SQLStatistics

SQLTransact
SQLTransact Process a transaction
Syntax RETCODE SQLTransact (HENV henv, HDBC hdbc, UWORD type)

hdbc [Input] The server connection handle. A value of
SQL_NULL_HDBC tells Velocis to commit or roll
back all transactions associated with the specified
environment handle.
type [Input] The transaction type indicator. To apply the
changes made since the beginning of the
transaction, specify SQL_COMMIT. To roll back
the changes, specify SQL_ROLLBACK.
Description This function processes a database transaction, which begins just

after the user opens the database and after completion of an
SQLTransact call (or equivalent) for the previous transaction.
Another transaction cannot begin on the same server connection
handle until the active transaction is terminated by another call to
SQLTransact, specifying either SQL_COMMIT or
SQL_ROLLBACK. According to the option provided, SQLTransact
either commits (accepts) or rolls back (rejects) all changes made
since the beginning of the transaction. The function then finishes
and another transaction begins.
Unless automatic transaction mode is active (i.e., the
SQL_AUTOCOMMIT option is set in SQLSetConnectOption), your
application must bind by transactions any statements that can
change the database. The application must then call SQLTransact
(or equivalent) to commit for each statement making a change.
Committed changes become permanent in the database.
Note: As an alternative to SQLTransact, your application can either

process a commit or rollback statement through SQLExecDirect, or
it can call SQLExtendedTransact.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLExecDirect, SQLExtendedTransact

SQLTransactTrigger
SQLTransactTrigger Register a transaction trigger
Syntax short SQLTransactTrigger (HMOD hMod, RDM_SESS hSess,

char *name, PTRANSACTTRIGGER Trigger, void *ptr,
short mode)
Parameters hMod [Input] The handle for the UDP module defining
the trigger function.
hSess [Input] The handle for the session with which the
trigger function is associated.
name [Input] The name of the transaction trigger function.
Trigger [Input] A pointer to the trigger function. The
void REXTERNAL TransactionTriggerFunction
(short OperationTypeIndicator,
char *TransactionIdentifierString,
char *TriggerName, void *TriggerContextPointer)
ptr [Input] A pointer to a user-maintained context
passed to the trigger function. It can be set to
NULL.
mode [Input] The indicator for the calling frequency
mode. To have the trigger called any time commit
or rollback occurs in the session, specify
SYS_COMMIT_EVERY. To have it called only once,
when the next transaction commit or rollback
occurs, specify SYS_COMMIT_ONCE.
Description This function registers a transaction trigger function, which is a UDF

packaged in a DLL that runs in the extension module section of the
Velocis server extension library. A transaction trigger function is
associated with a specific connection and must first be registered in
a call to SQLTransactTrigger. Then, whenever a transaction
commit or rollback occurs on this connection, Velocis calls the
trigger function. You may register multiple trigger functions.
Note: Because SQLTransactTrigger is only available on the server

side of Velocis, your application cannot call that function from the
client side. It must call SQLTransactTrigger from a UDP.
Whenever a commit, mark, or rollback statement is executed,

Velocis calls the trigger function with an operation type indicator of

SQLTransactTrigger
SYS_COMMIT, SYS_MARK, or SYS_ROLLBACK, respectively.

Velocis removes the trigger from memory by calling the trigger
function with a type indicator of SYS_REMOVE.
The timing of the removal depends on the calling frequency of the
trigger, which is set when the trigger function is registered by
SQLTransactTrigger. If, in that function, the trigger was registered
with a frequency mode indicator of SYS_COMMIT_EVERY, the
trigger is called after each commit or rollback, and it is removed
after the user has disconnected. If the mode indicator was
SYS_COMMIT_ONCE, the trigger is called only after the next
commit or rollback, and it is removed immediately after that.
The parameter for the transaction identifier string represents an
optional SQL identifier that can be specified in begin, commit,
mark, or rollback statements. If a transaction identifier was not
specified, this parameter will be NULL. The other two parameters,
the trigger name and the trigger context pointer, have the values
specified in the SQLTransactTrigger call that registered the trigger
function.
Return Values S_BADSRV SQL_SUCCESS

See Also SQLExtendedTransact, SQLTransact
Example For the sample function definition below, the trigger function is
called every time a transaction event occurs. In a separate
transaction log database, this trigger writes all transaction events
occurring during the user’s connections. The transaction trigger has
its own connection for this database, so commits to the log database
will not be recorded in the log database.
If type is SYS_MARK, or if type is SYS_ROLLBACK to a mark, the
function saves the action that has occurred in the trigger’s memory
context for later addition into the transaction log database.
If type is SYS_COMMIT, or if type is SYS_ROLLBACK and no marks
are present, the transaction trigger actually puts the actions that
have occurred into the transaction log database. It first loops
through the actions that are stored in its private context, adding
each of them as a new record in the log, then it adds the commit or
rollback action as a log entry. Then this information is committed to
the transaction log database.

SQLTransactTrigger
void REXTERNAL TransactTrigger(

short type, char *label, char *name, void *ptr)
{
LOG_CTX *ctx = ptr;
LOG_ACTION *lap = NULL, *lgp;
if ( type == SYS_REMOVE ) {
rm_freeTagMemory (ctx->mTag, 1);
ctx->mTag = NULL;
SQLFreeStmt(ctx->hStmt, SQL_DROP);
SQLDisconnect(ctx->hDbc);
SQLFreeConnect(ctx->hDbc);
SQLFreeEnv(ctx->hEnv);
} else {
if (type == SYS_MARK ||
(type == SYS_ROLLBACK && IsAMark(ctx->act_list, label))) {
/* Record the event, but don’t commit it yet
** It will be committed to the log when a commit
** or rollback occurs...*/
lap = rm_getMemory(sizeof(LOG_ACTION), ctx->mTag);
if ( lap ) {
lap->type = type;
lap->next = ctx->act_list;
lap->prev = NULL;
if (ctx->act_list) ctx->act_list->prev = lap;
lap->label = label ? rm_Strdup(label, ctx->mTag) : NULL;
ctx->act_list = lap;
}
} else if (type == SYS_COMMIT || type == SYS_ROLLBACK) {
if (ctx->act_list) { /* Process stored actions (if any) */
/* Find first event (it’s last in the list) */
for (lap = ctx->act_list; lap->next; lap = lap->next) ;
for (lgp = lap; lgp; lgp = lgp->prev) {
switch (lgp->type) {
case SYS_MARK:
strcpy(ctx->action, "mark"); break;
case SYS_ROLLBACK:
strcpy(ctx->action, "rollback to mk"); break;
}
strcpy(ctx->label, lgp->label);
SQLExecute(ctx->hStmt);
}
ctx->act_list = NULL;
rm_freeTagMemory(ctx->mTag, 0);
}
switch (type) {
case SYS_COMMIT: strcpy(ctx->action, "commit"); break;
case SYS_ROLLBACK: strcpy(ctx->action, "rollback"); break;
}
strcpy(ctx->label, label);
SQLExecute(ctx->hStmt);
SQLTransact(ctx->hEnv, ctx->hDbc, SQL_COMMIT);
}
}
return;
}

SQLTransactTrigger
The mark finding function (IsAMark) and the action and context
structures (log_action and log_ctx, respectively) are defined in the
following example.
typedef struct log_action {

short type;
char *label;
struct log_action *next;
struct log_action *prev;
} LOG_ACTION;
typedef struct log_ctx {

HENV hEnv;
HDBC hDbc;
HSTMT hStmt;
RDM_SESS hSess;
RM_MEMTAG mTag;
char action[16];
char label[21];
LOG_ACTION *act_list;
} LOG_CTX;
short RINTERNAL IsAMark (LOG_ACTION *lap, char *label)

{
LOG_ACTION *lgp;
for (lgp = lap; lgp; lgp = lgp->next) {
if (strcmp (lgp->label, label) == 0) return 1;
}
return 0;
}

SQLTransactTrigger
The code fragment of the logLogin function, which is shown below,

is called automatically when a user connects. This function sets up
the transaction activity log and calls SQLTransactTrigger to register
the transaction trigger function.
short REXTERNAL logLogin(

void **ctxp,
short noargs,
VALUE *args,
RM_MEMTAG mTag,
HSTMT *phStmt,
VALUE *err)
{
LOG_CTX *ctx = ctxp, *ptr;
...
/* record the login */
...
/* allocate trigger’s log context on global memory tag */
ptr = rm_getMemory(sizeof(LOG_CTX), mTag);
...
SQLTransactTrigger(ghMod, ctx->hSess, "activity_log",
TransactTrigger, ptr, SYS_COMMIT_EVERY);
...
}

SQLWhenever
SQLWhenever Register a status/error-handling callback function
Syntax RETCODE SQLWhenever (HDBC hdbc, HSTMT hstmt,

SWORD code, ECALLBACK fcn)

hstmt [Input] The SQL statement handle.
code [Input] The status or error code.
fcn [Input] A pointer to the callback function. To
disable error handling, specify NULL; otherwise,
the function must have this prototype:
long REXTERNAL SQLErrorHandler
(HENV EnvironmentHandle,
HDBC ServerConnectionHandle,
HSTMT SQLStatementHandle, long ReturnCode);
Description This function allows the application to register a status/error-

handling callback function with the Velocis SQL API. Velocis will
call your SQLErrorHandler function whenever an SQL API function
encounters the specified code for the specified hdbc or hstmt. Your
handler can take whatever action is necessary to process the error.
The status code returned by your handler is the code that will be
returned by the SQL API function that encountered the error. To
handle all errors, pass SQL_ERROR for code.
You can also specify different handlers for specific error codes by
making additional calls to SQLWhenever. A handler for a specific
code will take precedence over a handler for SQL_ERROR.

SQL_INVALID_HANDLE
SQL_SUCCESS
See Also SQLError

SQLWhenever
Example In this example, an errINVCONVERT error on any statement handle

associated with the server connection handle (hdbc) results in a call
to BadConvert. For any other error on that connection, the
ErrHandler function is called.
Note: This particular example was created only to illustrate the use
of separate error handlers. It is more efficient to use a table in a
single error handler.
#include <stdio.h>
#include "sqlrds.h" /* SQLWhenever is a Velocis extension */
/* ====================================================================
Invalid data type conversion
*/
long REXTERNAL BadConvert(HENV henv, HDBC hdbc, HSTMT hstmt, long code)
{
/* My error message is better */
printf("**** A type conversion specified in SQLBindCol or "
"SQLBindParameter call is not valid.\n");
return code;
}
...
/* Register standard error handler */

SQLWhenever(hdbc, NULL, SQL_ERROR, ErrHandler);
/* Register invalid conversion handler */

SQLWhenever(hdbc, NULL, errINVCONVERT, BadConvert);
...

Chapter 13
SQL UDF Support Functions
(SYS Prefix)
This chapter describes the C functions that can be used in support of an SQL user-
defined function (UDF) module. These functions, which have an SYS prefix, can
perform the following tasks:
• Do low-level database operations using the Core API
• Associate SQL modification commands with client application transactions
• Use the data type arithmetic capabilities of Velocis SQL
Many of the SYS functions use the VALUE type, which is a structure for containing SQL
data values. For details about this structure, see Chapter 18 of this manual.
SQL UDF Support Functions (SYS Prefix) 13-1

SYSDbaToRowId
SYSDbaToRowId Convert the database address of a table row to a row identifier
Syntax short SYSDbaToRowId (HSYS hSys, char *tblname, DB_ADDR dba,

long *pRowID)
Parameters hSys [Input] The handle for the Velocis SQL support module.
tblname [Input] The name of the database table. This name must
be the correlation name, if correlation names have been
specified for the tables listed in the from clause of the
referencing select statement.
dba [Input] The database address to convert.
pRowID [Output] A pointer to the row identifier.
Description This function is called from a server-side UDF module to convert the
specified database address to the identifier for a row in the
corresponding database table. The function returns SQL_ERROR if
the database address is not valid for the specified table, or if the
specified table is not referenced in the SQL statement that
corresponds to the handle for the Velocis SQL support module.

SQL_SUCCESS
See Also SQLDbaToRowId, SYSRowIdToDba

SYSDBHandle
SYSDBHandle Get the database handle
Syntax short SYSDBHandle (HSYS hSys, char *dbname, RDM_DB *phDb)
dbname [Input] The database name. Your application must have
already opened the database during server connection,
either implicitly or explicitly (for example, using the
open statement).
phDb [Output] A pointer to the database handle.
Description This function is called from a server-side UDF module to retrieve

the handle that Velocis uses to represent the specified database. The
UDF module later uses this handle when issuing calls to the Velocis
Core API (d_) functions. If the specified database is not open at the
time of the call, the function returns SQL_ERROR.

SQL_SUCCESS
See Also SQLDBHandle

SYSDescribeStmt
SYSDescribeStmt Determine the SQL statement type
Syntax short SYSDescribeStmt (HSYS hSys, short *pStype)
pStype [Output] A pointer to the statement type, defined as a
manifest constant declared in the standard Velocis SQL
header file sqlrds.h. Possible values are:
sqlDELETE Deletes a row or rows from a table.
sqlINSERT Inserts a row into a table.
sqlSELECT Implements a select statement.
sqlUPDATE Implements an update statement.
Description This function is called from a server-side UDF module to determine

the type of SQL statement associated with the handle for the Velocis
SQL support module. Transaction trigger functions that are called
from a check clause need this function to determine the kind of SQL
modification statement that is being executed.
See Also SQLDescribeStmt, SQLTransactTrigger

SYSHandle
SYSHandle Retrieve the system handle for the current statement
Syntax short SYSHandle (RDM_SESS hSess, short stmtno, HSYS *hSys)
Parameters hSess [Input] The session handle on which the specified

statement was created.
stmtno [Input] The SQL statement number.
hSys [Output] The system handle for the Velocis SQL support
module.
Description This function is used only in SQL extension modules, transaction

triggers, and user-defined procedures (UDPs). It is used to gain
access to the system handle for the current statement. This handle
can then be used in other SYS API functions.

SQL_SUCCESS

SYSMemoryTag
SYSMemoryTag Get the Velocis memory allocation tag
Syntax short SYSMemoryTag (HSYS hSys, RM_MEMTAG *pudftag)
pudftag [Output] A pointer to the memory allocation tag.
Description This function is called from a server-side UDF module to retrieve a

Velocis memory allocation tag. The UDF module can then use the
tag when allocating memory with a call to the rm_getMemory
function.
The advantage of using tagged memory allocation is that the Velocis
SQL support module automatically handles out-of-memory
conditions for your extension module. The SQL support module
frees all allocated memory and notifies the client of the
errSRVMEMORY condition. This frees your server extension from
having to check the returned pointer for NULL and handling the
condition itself (as it would if the code used malloc). In addition,
the SQL support module automatically frees any memory that your
extension module has allocated, using the memory allocation tag
when the SQL statement has finished executing.

SYSRowDba
SYSRowDba Retrieve the database address of the current table row
Syntax short SYSRowDba (HSYS hSys, char *tblname, DB_ADDR *dbap)
tblname [Input] The table name. This name must be the
correlation name, if correlation names have been
dbap [Output] A pointer to the database address of the current
row.
Description This function retrieves the database address of the current row of a
table, if the table is referenced in the SQL statement specified by the
handle for the Velocis SQL support module. The function returns
SQL_ERROR if the SQL statement does not reference the specified
table.
Note: After SYSRowDba returns, your application can use the

database address in calls to the Velocis Core API (d_) functions.

SQL_SUCCESS
See Also SQLRowDba

SYSRowId
SYSRowId Retrieve the identifier of the current table row
Syntax short SYSRowId (HSYS hSys, char *tblname, long *pRowid)
pRowid [Output] A pointer to the row identifier.
Description This function retrieves the identifier of the current row from the
given table, which is accessed by the SQL statement associated with
the handle for the Velocis SQL support module. It is called from a
server-side UDF module. The function returns SQL_ERROR if the
specified table is not referenced in the SQL statement.
This function is useful when using primary keys of the rowid type.
For example, after your application executes an insert statement to
insert a row in a table with a primary key of the rowid type, a call to
SQLRowId will retrieve the identifier of the inserted row. Your
application can then specify this row identifier in any insert
statement using foreign keys that reference the table containing the
row.

SQL_SUCCESS
See Also SQLRowId

SYSRowIdToDba
SYSRowIdToDba Convert the identifier of a table row to the database address of the
row
Syntax short SYSRowIdtoDba (HSYS hSys, char *tblname, long *rowid,

DB_ADDR *dbap)
rowid [Input] A pointer to the row identifier.
dbap [Output] A pointer to the database address.
Description This function is called from a server-side UDF module to convert a

row identifier to the database address for the row. The function
returns SQL_ERROR if the specified table is not referenced in the
SQL statement associated with the handle for the Velocis SQL
support module.

SQL_SUCCESS
See Also SQLRowIdToDba

SYSSessionId
SYSSessionId Retrieve the Velocis session handle
Syntax short SYSSessionId (HSYS hSys, RDM_SESS *hSess)
hSess [Output] A pointer to the session handle corresponding
to the server connection.
Description This function is called from a server-side UDF module to retrieve

the Velocis session handle associated with the handle for the Velocis
SQL support module. The UDF module most often uses the session
handle in a call to SQLConnectWith to fetch the connection handle
associated with the executing statement.
See Also SQLConnectWith, SQLSessionId

SYSValAdd
SYSValAdd Add two numeric SQL values
Syntax short SYSValAdd (HSYS hSys, const VALUE *lv, const VALUE *rv,
VALUE *result)
lv [Input] A pointer to the left operand. This parameter
must contain a valid numeric SQL value. Possible value
types are SQL_SMALLINT, SQL_INTEGER, SQL_REAL,
SQL_FLOAT, SQL_DECIMAL, and SQL_DOUBLE.
rv [Input] A pointer to the right operand. This parameter
must also contain a valid numeric SQL value, as
described for the lv parameter.
result [Output] A pointer to the result of the addition.
Description This function is called from a server-side UDF module to add two
numeric SQL values (lv + rv). The function uses mixed-mode
arithmetic following standard Velocis SQL rules.
Note: Velocis defines the SYSVal* functions for use with scalar and
aggregate UDFs that might need to perform calculations on mixed-
mode numeric values.

SQL_SUCCESS
See Also SYSValChgSign, SYSValCompare, SYSValConvert, SYSValDiv,

SYSValMult, SYSValSub

SYSValChgSign
SYSValChgSign Change the sign of a numeric SQL value
Syntax short SYSValChgSign (HSYS hSys, VALUE *lv)
lv [Input/Output] A pointer to the location of the SQL
value. This parameter must contain a valid numeric SQL
value. Possible value types are SQL_SMALLINT,
SQL_INTEGER, SQL_REAL, SQL_FLOAT,
SQL_DECIMAL, and SQL_DOUBLE.
Description This function is called from a server-side UDF module to change the
sign of the specified numeric SQL value. The function uses mixed-
mode arithmetic following standard Velocis SQL rules.

SQL_SUCCESS
See Also SYSValAdd, SYSValCompare, SYSValConvert, SYSValDiv,


SYSValCompare
SYSValCompare Compare two numeric SQL values
Syntax short SYSValCompare (HSYS hSys, const VALUE *lv,

const VALUE *rv)
lv [Input] A pointer to the left numeric value. This
parameter must contain a valid numeric SQL value.
Possible value types are SQL_SMALLINT,
rv [Input] A pointer to the right numeric value. This
parameter must also contain a valid numeric SQL value,
as described for the lv parameter.
Description This function is called from a server-side UDF module to compare

two numeric SQL values, which must be type-compatible. The
function returns the comparison result.
Return Values The SYSValCompare function returns one of the following:

-1 lv is less than rv
0 lv is equal to rv
+1 lv is greater than rv
See Also SYSValAdd, SYSValChgSign, SYSValConvert,

SYSValDivSYSValMult, SYSValSub

SYSValConvert
SYSValConvert Convert a numeric SQL value
Syntax short SYSValConvert (HSYS hSys, short rtype, VALUE *lv)
rtype [Input] The data type. This parameter must contain a
valid SQL data type. These are SQL_SMALLINT,
lv [Input/Output] A pointer to the location of the numeric
value.
Description This function is called from a server-side UDF module to convert a

numeric SQL value to the data type specified in rtype.

SQL_SUCCESS
See Also SYSValAdd, SYSValChgSign, SYSValCompare, SYSValDiv,


SYSValDiv
SYSValDiv Divide one numeric SQL value by another
Syntax short SYSValDiv (HSYS hSys, const VALUE *lv, const VALUE *rv,
VALUE *result)
lv [Input] A pointer to the left value (numerator). This
parameter must contain a value with a valid SQL data
type. Possible value types are SQL_SMALLINT,
rv [Input] A pointer to the right value (denominator). This
parameter must also contain a value with a valid SQL
data type, as defined for the lv parameter.
result [Output] A pointer to the result of the division.
Description This function is called from a server-side UDF module to divide one
numeric SQL value by another (lv / rv). The function uses mixed-
mode arithmetic following standard Velocis SQL rules.

SQL_SUCCESS
SQL_ZERODIV
See Also SYSValAdd, SYSValChgSign, SYSValCompare, SYSValConvert,


SYSValMult
SYSValMult Multiply two numeric SQL values
Syntax short SYSValMult (HSYS hSys, const VALUE *lv, const VALUE *rv,
VALUE *result)
lv [Input] A pointer to the left value. This parameter must
contain a value with a valid SQL data type. Possible
value types are SQL_SMALLINT, SQL_INTEGER,
SQL_REAL, SQL_FLOAT, SQL_DECIMAL, and
SQL_DOUBLE.
rv [Input] A pointer to the right value. This parameter
must also contain a value with a valid SQL data type, as
defined for the lv parameter.
result [Output] A pointer to the result of the multiplication.
Description This function is called by a server-side UDF module to multiply two

numeric SQL values (lv • rv). The function uses mixed-mode
arithmetic following standard Velocis SQL rules.

SQL_SUCCESS

SYSValDiv, SYSValSub

SYSValSub
SYSValSub Subtract one numeric SQL value from another
Syntax short SYSValSub (HSYS hSys, const VALUE *lv, const VALUE *rv,
VALUE *result)
lv [Input] A pointer to the left value. This parameter must
contain a value with a valid SQL data type. Possible
value types are SQL_SMALLINT, SQL_INTEGER,
SQL_REAL, SQL_FLOAT, SQL_DECIMAL, and
SQL_DOUBLE.
rv [Input] A pointer to the right value. This parameter
must also contain a value with a valid SQL data type, as
defined for the lv parameter.
result [Output] A pointer to the result of the subtraction.
Description This function is called by a server-side UDF module to subtract one

SQL value from another. The function uses mixed-mode arithmetic
following standard Velocis SQL rules.

SQL_SUCCESS

SYSValDiv, SYSValMult

Chapter 14
UDF Module Functions (udf Prefix)
This chapter describes the C functions that are used to create user-defined functions
(UDFs) for use in SQL. The chapter contains function interfaces for UDF type checking
(udfCheck), UDF initialization (udfInit) and cleanup (udfCleanup), the actual UDF
processing (udfFunc), and if the UDF operates on aggregate values, resetting of running
values for the last aggregate function (udfReset). Because you can define multiple UDFs
in an extension module, you can use these function interfaces to create as many C
functions as you need to support the UDFs. The names udfCheck, udfCleanup,
udfFunc, udfInit and udfReset represent the actual names for the functions you create
that implement your user-defined function. Each UDF module has one function called
udfDescribeFcns. This function is called by SQL to fetch the addresses of the other UDF
functions.
The functions in this chapter use two special structures: a container for SQL data values
(VALUE) and a structure that describes the functions that make up a UDF
(UDFLOADTABLE). For details about these structures, see Chapter 18 of this manual.
When declaring and defining these functions, you must also add the REXTERNAL
macro between the function return type and function name. For details about using
UDF module functions, see Chapter 12 of the Velocis User's Guide.
UDF Module Functions (udf Prefix) 14-1

udfCheck
udfCheck Perform type checking on UDF parameters
Syntax short REXTERNAL udfCheck (HSYS hSys, short noargs,

const VALUE *args, VALUE *result, short *len)
Parameters hSys [Input] The system handle used by the SQL support
module to identify and maintain the context of the
executing statement.
noargs [Input] The number of parameters in the UDF.
args [Input] A pointer to an array of VALUE structures
containing the UDF parameters.
result [Output] A pointer to a VALUE structure
containing the result of the type checking operation.
The result is either a detailed error message or one
of the Velocis SQL data types listed in Chapter 18.
len [Output] A pointer to the length, in bytes, of the
result information. If there are no UDF parameters,
this parameter is ignored.
Description This function performs type checking on the parameters of a scalar

or aggregate UDF. The actual function name can be any valid C
function name. During processing, your udfCheck function
examines both the number of parameters and the types of the
parameters for the corresponding UDF. If it finds that the value of
noargs is not equal to the number of UDF parameters, it returns
SQL_ERROR as the return code and writes a detailed error message
to the cv field of the VALUE structure for the result parameter.
After checking for the number of UDF parameters, your udfCheck
function checks each parameter to see if its data type is appropriate.
If it discovers a parameter of the wrong type, it returns SQL_ERROR
as the return code and returns an information message in the cv
field of the VALUE structure indicated by result. If the type
checking is successful, your udfCheck function needs to return
SQL_SUCCESS and set the type of the result value to the SQL data
type that your corresponding udfFunc function returns.

SQL_SUCCESS

udfCheck
See Also udfFunc

VALUE (structure)
Example
short REXTERNAL CntCheck (
const VALUE *args, /* in: array of arguments */
VALUE *result, /* out: result value */
short *len) /* out: max length result string */
{
UNREF_PARM(hSys)
UNREF_PARM(args)
UNREF_PARM(len);
if (noargs != 1) {
result->type = SQL_CHAR;
result->vt.cv = "only 1 argument expression is allowed";
status = SQL_ERROR;
}
else
result->type = SQL_INTEGER;
return status;
}

udfCleanup
udfCleanup Clean up after UDF module processing
Syntax void REXTERNAL udfCleanup (HSYS hSys, void **ctxp)
ctxp [Input] A pointer to the Velocis SQL statement
context pointer.
Description This function finishes UDF module processing. It frees memory

allocated in the initial call to your udfInit function, or any memory
allocated during processing. For example, the SQL support module
might call the udfCleanup function after SQLFetch returns
SQL_NO_DATA_FOUND.
Return Values None
See Also udfInit
Example The following example illustrates a specific udfCleanup function

that simply frees the statement context pointer.
void REXTERNAL CntCleanup (

{
COUNT_CTX *cnt = *cxtp;
UNREF_PARM(hSys)
rm_freeMemory(cnt, cnt->mTag);
*cxtp = NULL;
}

udfDescribeFcns
udfDescribeFcns Describe the entry point functions for a UDF module
Syntax void REXTERNAL udfDescribeFcns (unsigned short *NumFcns,

PUDFLOADTABLE *UDFLoadTable, char **fcn_descr)
Parameters NumFcns [Output] A pointer to the number of functions

in the UDF module.
UDFLoadTable [Output] A pointer to an array of
UDFLOADTABLE structures describing the
functions for the module. The array must
contain one structure for each function
supported by the UDF module. Unused
function entries are set to NULL.
fcn_descr [Output] A pointer to the optional description
string. If no string is written, the function
writes NULL in this parameter.
Description This function describes the entry point functions for a UDF module.
It must be included (exactly as named) in each UDF module DLL.
When you compile the first Velocis SQL statement referencing one
of the UDF module functions, the SQL support module calls
udfDescribeFcns. The function returns in UDFLoadTable a pointer
to a function description table containing all entry point
information. In addition, the function can return an optional
module description string to be displayed on the Velocis system
console indicating the UDF module DLL has been loaded.
The UDF load table must specify the name of the UDF and the
address of at least two functions, udfFunc and udfCheck. In
addition, the UDF load table entry can optionally contain the
addresses of the udfInit and udfCleanup functions. For an
aggregate UDF, the table entry must include the address of the
udfReset function.
Return Values None
See Also udfCheck, udfCleanup, udfFunc, udfInit, udfReset

UDFLOADTABLE (structure)

udfDescribeFcns
Example The following is udfDescribeFcns code defined for a udfCount

function.
/* user function for udfCount */

UDFCHECK CntCheck;
UDFFUNC CntFunc;
UDFINIT CntInit;
UDFCLEANUP CntCleanup;
UDFRESET CntReset;
/*============================================================
Table of user-defined functions for this module
============================================================*/
static UDFLOADTABLE UdfTable[ ] = {
/* name udfFunc udfCheck udfInit udfCleanup udfReset*/
{"udfCount", CntFunc, CntCheck, CntInit, CntCleanup, CntReset}
};
#define NFCNS (sizeof(UdfTable)/sizeof(UDFLOADTABLE)) /* table size */
/*===============================================================
User function description, called when statement is prepared
===============================================================*/
void REXTERNAL udfDescribeFcns (
unsigned short *NumFcns, /* out: num. of functions in module */
PUDFLOADTABLE *UDFLoadTable, /* out: points to UdfTable above */
{
*NumFcns = RLEN(UdfTable);
*UDFLoadTable = UdfTable;
*fcn_descr = "Sample of SQL user-defined functions";
}

udfFunc
udfFunc Perform processing for a UDF
Syntax short REXTERNAL udfFunc (HSYS hSys, void **ctxp, short noargs,
const VALUE *args, VALUE *result)
ctxp [Input] A pointer to the Velocis SQL statement
context pointer.
noargs [Input] The number of parameters in the UDF.
containing the UDF parameters.
result [Output] A pointer to a VALUE structure
containing its processing result.
Description This function performs the actual processing for a particular UDF.
The actual function name can be any valid C function name and
must be assigned to the udfFunc entry in the UDF load table
returned by the udfDescribeFcns function.
If the function succeeds, it returns SQL_SUCCESS and puts the
result into the result parameter. Even if the UDF is an aggregate
function, your udfFunc function should always return a running
result every time it is called, because the UDF cannot determine
which call will be the final one of the aggregate calculation. If the
function fails, it should return SQL_ERROR and put a descriptive
error string into the result parameter.
When a scalar UDF is referenced in a where clause, you need to be
sure to check for NULL arguments (a NULL argument will have
type SQL_NULL) and return SQL_NULL as the result type. This is
because the SQL query processing will pre-evaluate expressions
(that is, before all column values have been read) to avoid reading
unnecessary rows. NULLs are passed for column values that have
not yet been read.
The Example section below illustrates an example count aggregate
function.

SQL_SUCCESS

udfFunc
See Also udfDescribeFcns

VALUE (structure)
Example The following is an example of a user function with prototype

udfFunc.
short REXTERNAL CntFunc (

const VALUE *args, /* in: array of arguments */
VALUE *result) /* out: result value */
{
UNREF_PARM(hSys)
UNREF_PARM(noargs)
result->type = SQL_INTEGER;
if (args[0].type != SQL_NULL)
result->vt.lv = ++cnt->count;
else
result->vt.lv = cnt->count;
return SQL_SUCCESS;
}

udfInit
udfInit Initialize processing for a UDF
Syntax short REXTERNAL udfInit (HSYS hSys, void **ctxp)
ctxp [Input] A pointer to the statement context pointer
associated with the system handle.
Description This function initializes processing for the UDF referenced in a

Velocis SQL statement. The actual function name can be any valid
C function name and must be assigned to the udfInit entry in the
UDF load table. It is where you would include any memory
allocations needed for the UDF context.
The SQL UDF support function SYSMemoryTag can be called to
retrieve the memory allocation tag that the udfInit function should
use in its calls to resource manager memory functions, such as
rm_getMemory. Memory allocated with this tag remains active for
the life of the executing statement. When the statement has
terminated, the SQL support module automatically frees the
memory allocated on that tag.
Note: In the rare event that the server does not have enough
memory for the rm_getMemory request within udfInit, the SQL
support module gracefully aborts statement execution and returns
errSRVMEMORY to the application.

SQL_SUCCESS
See Also rm_getMemory, SYSMemoryTag

udfInit
Example
short REXTERNAL CntInit (
{
COUNT_CTX *cnt;
RM_MEMTAG mTag;
cnt = *cxtp = rm_getMemory(sizeof(COUNT_CTX), mTag);
cnt->mTag = mTag;
cnt->count = 0L;
return SQL_SUCCESS;
}
The statement context structure for the example is defined below. It

simply contains the current count value and the memory tag.
typedef struct {
RM_MEMTAG mTag;
long count;
} COUNT_CTX;

udfReset
udfReset Reset the running values for the last aggregate function
Syntax short REXTERNAL udfReset (HSYS hSys, void **ctxp)
ctxp [Input] A pointer to the statement context pointer.
Description This function is called by Velocis SQL for an aggregate UDF to reset
the running values for the current aggregate when the grouping
value changes. The actual function name can be any valid C
function name and must be assigned to the udfReset entry in the
UDF load table.

SQL_SUCCESS
See Also udfDescribeFcns
Example
short REXTERNAL CntReset (
{
UNREF_PARM(hSys)
cnt->count = 0L;
return SQL_SUCCESS;
}

Chapter 15
UDP Module Functions (udp Prefix)
This chapter describes the functions that are used to create user-defined procedures
(UDPs) for use in SQL. The chapter contains function interfaces for UDP type checking
(udpCheck), UDP initialization (udpInit) and cleanup (udpCleanup), the actual UDP
processing (udpExecute), and retrieving the next result set into the UDP
(udpMoreResults). Because you can define multiple UDPs in an extension module, use
these interfaces to create the functions to support all of your UDPs. The names:
udpCheck, udpCleanup, udpExecute, udpInit and udpMoreResults represent the
actual names for the functions you create that implement your user-defined procedures.
Each UDP module has one function called udpDescribeFcns. This function is called by
SQL to fetch the addresses of the other UDP functions.
The functions in this chapter use two special structures: a container for SQL data values
(VALUE) and a structure that describes the functions that make up a UDP
(UDPLOADTABLE). For details about these structures, see Chapter 18 of this manual.
When declaring and defining these functions, you must also add the REXTERNAL
macro between the function return type and function name. For details about using
UDP module functions, see Chapter 12 of the Velocis User's Guide.
UDP Module Functions (udp Prefix) 15-1

udpCheck
udpCheck Perform type checking on UDP parameters
Syntax short REXTERNAL udpCheck (short noargs, const short *types,

VALUE *err)
Parameters noargs [Input] The number of parameters in the UDP.

types [Input] A pointer to an array of data types for UDP
parameters. Possible data types are listed in
Chapter 18.
err [Output] A pointer to a VALUE structure
containing the result of the type checking operation.
The result is either a detailed error message or one
of the Velocis SQL data types listed for the types
parameter.
Description This function performs compile-time type checking on UDP

parameters in an execute statement. The actual function name can
be any valid C function name and must be assigned to the
udpCheck entry in the UDP load table. When SQLPrepare
compiles the statement, it calls your udpCheck function to validate
that the parameters specified in the statement are appropriate for
the UDP.
During processing, your udpCheck function should check both the
number of parameters and the types of the parameters for the
corresponding UDP. If it finds that the value of noargs is not equal
to the number of UDP parameters, it should return a detailed error
message in the cv field of the VALUE structure for the err
parameter. It should also then return SQL_ERROR to indicate that
an error has occurred.
After checking for the number of UDP parameters, udpCheck
should check each parameter to see if its data type is appropriate. If
udpCheck discovers a parameter of the wrong type, it should
return an information message to the cv field of the VALUE
structure indicated by err and then return SQL_ERROR to indicate
that an error has occurred.
If no error occurs, your udpCheck function should return
SQL_SUCCESS.

udpCheck

SQL_SUCCESS
See Also udpExecute

VALUE (structure)
Example
short REXTERNAL timsCheck (
short noargs, /* in: number of arguments passed */
const short *types, /* in: type of each argmt, types[noargs-1] */
VALUE *err) /* out: container for error messages */
{
short arg;
err->type = SQL_CHAR;
err->vt.cv = "tims_data requires char arguments only";
for (arg = 0; arg < noargs; ++arg) {

if ( types[arg] != SQL_CHAR )
return SQL_ERROR;
}
return SQL_SUCCESS;
}

udpCleanup
udpCleanup Clean up after UDP processing
Syntax void REXTERNAL udpCleanup (void **ctxp, RM_MEMTAG mTag)
Parameters ctxp [Input] A pointer to the Velocis SQL statement

context pointer.
mTag [Input] The memory tag for use in calls to resource
manager memory functions, such as
rm_getMemory.
Description This function is called by Velocis SQL when the execute statement is
closed for the UDP module. The actual function name can be any
valid C function name and must be assigned to the udpCleanup
entry in the UDP load table. It cleans up by closing and freeing
statement handles, terminating connections, dropping temporary
tables, etc. It also allows you to free any memory allocated in the
initial call to your udpInit function, or any memory allocated
during processing.
Return Values None
See Also udpInit
Example
void REXTERNAL timsCleanup (
void **ctxp, /* in: statement udp_ctx pointer */
RM_MEMTAG mTag) /* memory tag for rm_ memory calls */
{
UDP_CTX *ctx = *ctxp;
SQLFreeStmt(ctx->hStmt, SQL_CLOSE);
SQLExecDirect(ctx->hStmt, "drop table timstab", SQL_NTS);
SQLFreeStmt(ctx->hStmt, SQL_DROP);
SQLDisconnect(ctx->hDbc);
SQLFreeConnect(ctx->hDbc);
SQLFreeEnv(ctx->hEnv);
d_close(ctx->hDb);
d_closetask(ctx->hSess);
return;
}

udpDescribeFcns
udpDescribeFcns Describe the entry point functions for a UDP module
Syntax void REXTERNAL udpDescribeFcns (unsigned short *NumProcs,

PUDPLOADTABLE *UDPLoadTable, char **fcn_descr)
Parameters NumProcs [Output] A pointer to the number of functions

in the UDP module.
UDPLoadTable [Output] A pointer to an array of
UDPLOADTABLE structures describing the
functions for the module. The array must
contain one structure for each function
supported by the UDP module. Unused
function entries are set to NULL.
fcn_descr [Output] A pointer to an optional description
string. If no string is written, the function
writes NULL in this parameter.
Description This function describes all of the UDPs and their function entry
points for a UDP module. You must include it (exactly as named) in
each of your UDP modules.
When you compile the first SQL statement referencing the UDP,
Velocis SQL calls udpDescribeFcns. This function must return the
number of UDPs contained in the module and the function
description table containing all entry point information. In addition,
the function can return an optional module description string to be
displayed on the Velocis system console indicating the UDP DLL
has been loaded.
Each entry in the UDP load table array must specify the name of a
UDP and the addresses of up to five processing functions that
implement that UDP, including udpCheck, udpCleanup,
udpExecute, udpInit, and udpMoreResults. Each UDP must at
least include a udpExecute function. The other processing functions
are optional.
Return Values None
See Also udpCheck, udpCleanup, udpExecute, udpInit, udpMoreResults

UDPLOADTABLE (structure)

udpDescribeFcns
Example
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>
#include "rdm.h" /* include for use of d_ API */

#include "sqlrds.h" /* required for UDPs */
#include "sqlsys.h" /* required for UDPs */
#include "..\rdm\tims.h" /* need for d_ access to TIMS db */
...
UDPCHECK timsCheck;
UDPEXECUTE timsExecute;
UDPMORERESULTS timsMoreResults;
UDPINIT timsInit;
UDPCLEANUP timsCleanup;
...
/*---------------------------------------------------
Table of user-defined functions in this module
-----------------------------------------------------*/
static UDPLOADTABLE UdpTable[] = {
/* "UDP name",
UDPCHECK, UDPEXECUTE, UDPMORERESULTS, UDPINIT, UDPCLEANUP
*/
{ "tims_data",
timsCheck, timsExecute, timsMoreResults, timsInit, timsCleanup},
{ "log_login",
NULL, logLogin, NULL, logInit, logCleanup},
{ "log_logout",
NULL, logLogout, NULL, logInit, logCleanup}
};
/* ----------------------------------------------------------
List of functions in module, called when module is loaded
-------------------------------------------------------------*/
void REXTERNAL udpDescribeFcns (

unsigned short *NumProcs, /* out: num. of procedures in module */
PUDPLOADTABLE *UDPLoadTable, /* out: points to UdpTable above */
{
*NumProcs = RLEN(UdpTable);
*UDPLoadTable = UdpTable;
*fcn_descr = "Sample of SQL C-based procedures";

}

udpExecute
udpExecute Obtain the first result set
Syntax short REXTERNAL udpExecute (void **ctxp, short noargs,

VALUE *args, RM_MEMTAG mTag, HSTMT *phStmt,
VALUE *err)
Parameters ctxp [Input] A pointer to the Velocis SQL statement

context pointer.
noargs [Input] The number of parameters in the UDP.
containing the UDP parameters.
rm_getMemory.
phStmt [Output] A pointer to the handle of the select
statement associated with the result set.
containing a Velocis SQL error code.
Description This function is called by Velocis SQL to obtain the first result set
from the UDP. It is invoked when SQLExecute processes the
execute statement for the named UDP. The actual function name
can be any valid C function name and must be assigned to the
udpExecute entry in the UDP load table.
Your udpExecute function can be defined to perform a variety of
tasks, such as SQL commands, runtime operations, administrative
functions, etc. When processing is complete, if the procedure
returns a result set, your function will need to execute a select
statement and return the handle of the select statement in phStmt so
that ensuing calls to SQLFetch or SQLExtendFetch can retrieve the
results.
If an error occurs, the function will need to return SQL_ERROR and
an error string in the err parameter. Otherwise, the function should
return SQL_SUCCESS.
The statement context pointer, ctxp, points to a pointer variable that
is maintained in the SQL statement context. This pointer allows you
to allocate and store UDP-specific context information. Your
udpInit function would typically be used to allocate the context,
udpExecute (and udpMoreResults) would use the context, and

udpExecute
udpCleanup would free it. In the example below, the context is

used to store statement and database handles that were assigned in
the udpInit function.

SQL_SUCCESS
See Also rm_getMemory, SQLFetch, udpDescribeFcns, udpInit

VALUE (structure)
Example
short REXTERNAL timsExecute (
void **ctxp, /* in: proc context pointer */
short noargs, /* in: number of arguments to procedure */
RM_MEMTAG mTag, /* in: memory tag for rm_ memory calls*/
HSTMT *phStmt, /* out: hstmt for result set */
{
static char errmsg[65];
char author[32];
struct info ir;
short stat, arg;
char *author_arg = args->vt.cv;
RDM_DB hdb = ctx->hDb;
HSTMT hstmt = ctx->hStmt;
/* set up insert parameter values */

SQLBindParameter(hstmt,1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
31, 0, author, 0, NULL);
15, 0, ir.id_code, 0, NULL);
79, 0, ir.info_title, 0, NULL);
31, 0, ir.publisher, 0, NULL);
11, 0, ir.pub_date, 0, NULL);
SQLBindParameter(hstmt,6, SQL_PARAM_INPUT, SQL_C_SHORT, SQL_SMALLINT,
0, 0, &ir.info_type, 0, NULL);
/* extract data from tims database & insert into SQL table */
d_setoo(AUTHOR_LIST, AUTHOR_LIST, hdb);
(continued)

udpExecute
(continued)
for ( ; ; ) {
while ( (stat = d_findnm(AUTHOR_LIST, hdb)) == S_OKAY ) {
d_recread(AUTHOR, author, hdb);
for ( arg = 0; arg < noargs; ++arg) {
/* check for author in argument list */
char *aname = args[arg].vt.cv;
if ( strncmp(author, aname, strlen(aname)) == 0 )
break;
}
if ( noargs == 0 || arg < noargs )
break;
}
if ( stat != S_OKAY )
break;
d_setor(HAS_PUBLISHED, hdb);
while ( (stat = d_findnm(HAS_PUBLISHED, hdb)) == S_OKAY ) {
d_recread(INFO, &ir, hdb);
SQLExecute(hstmt);
}
}
SQLFreeStmt(hstmt, SQL_RESET_PARAMS);
/* return result set from SQL table */

SQLExecDirect(hstmt, "select * from timstab", SQL_NTS);
*phStmt = ctx->hStmt;
return SQL_SUCCESS;
}

udpInit
udpInit Initialize processing for a UDP
Syntax short REXTERNAL udpInit (void **ctxp, short noargs, VALUE *args,
RDM_SESS hSess, RM_MEMTAG mTag, VALUE *err)
Parameters ctxp [Input] A pointer to a statement context pointer.

hSess [Input] The current session ID.
rm_cGetMemory.
Description This function is called by Velocis SQL to initialize processing for a

UDP referenced in a Velocis SQL execute statement. The actual
function name can be any valid C function name and must be
assigned to the udpCleanup entry in the UDP load table. During
initialization, your udpInit function can allocate and initialize
memory for storing context information and statement handles.
Any memory allocation needed by your udpInit function for the
statement context should be done by calling rm_cGetMemory. The
function should uses the input memory tag for all dynamic memory
allocations. The SQL support module uses this tag to free all
memory allocated by the UDP in case an error occurs outside the
UDP module.
If an error occurs during initialization, your udpInit function needs
to return SQL_ERROR and a descriptive error message to the cv
field of the VALUE structure for the err parameter. Otherwise, the
function should return SQL_SUCCESS.

SQL_SUCCESS
See Also rm_cGetMemory

VALUE (structure)

udpInit
Example
short REXTERNAL timsInit (
short noargs, /* in: number of arguments pased */
VALUE *args, /* in: arguments, args[noargs-1] */
RDM_SESS hSess, /* in: current session id */
RM_MEMTAG mTag, /* in: memory tag for rm_ memory calls */
{
short stat;
/* allocate a cleared UDP context memory */

UDP_CTX *ctx = rm_cGetMemory(sizeof(UDP_CTX), mTag);
/* open TIMS w/separate RDS task, allows dirty reads w/in trans */
d_opentask("", &ctx->hSess);
stat = d_open("tims", "s", ctx->hSess, &ctx->hDb);
err->type = SQL_CHAR;
err->vt.cv = "unable to open TIMS";
d_closetask(ctx->hSess);
return SQL_ERROR;
}
/* enable dirty syscat reads */

d_rdlockmodes(1, 1, ctx->hSess);
/* allocate and initialize SQL handles */

SQLAllocEnv(&ctx->hEnv);
SQLAllocConnect(ctx->hEnv, &ctx->hDbc);
SQLConnectWith(ctx->hDbc, hSess);
SQLAllocStmt(ctx->hDbc, &ctx->hStmt);
SQLExecDirect(ctx->hStmt, TimsCreate, SQL_NTS);

SQLPrepare(ctx->hStmt, TimsInsert, SQL_NTS);
*ctxp = ctx;
return SQL_SUCCESS;
}
The context structure is defined in the following example.
typedef struct udp_ctx {

HENV hEnv;
HDBC hDbc;
HSTMT hStmt;
RDM_SESS hSess;
RDM_DB hDb;
short finished;
} UDP_CTX;

udpMoreResults
udpMoreResults Obtain the next result set
Syntax short REXTERNAL udpMoreResults (void **ctxp, short noargs,

VALUE *args, RM_MEMTAG mTag, HSTMT *phStmt,
VALUE *err)
Parameters ctxp [Input] A pointer to a statement context pointer.

rm_getMemory.
phStmt [Output] A pointer to the handle of the select
statement associated with the result set.
Description This function is called by Velocis SQL to obtain the next result set
for the specified UDP. It is invoked each time your application calls
SQLMoreResults on the execute statement handle that
referencesthe UDP. The actual function name can be any valid C
function name and must be assigned to the udpCleanup entry in the
UDP load table.
If there are no more result sets, your udpMoreResults function
should return SQL_NO_DATA_FOUND. If there is no more than
one result set returned by your UDP, you do not need to have a
udpMoreResults function (just set the UDP load table entry for it to
NULL).
The statement context pointer, ctxp, points to a pointer variable that
is maintained in the SQL statement context. This pointer allows you
to allocate and store UDP-specific context information. Your
udpInit function would typically be used to allocate the context,
udpMoreResults (and udpExecute) would use the context, and
udpCleanup would free it. In the example below, the context is
used to store statement and database handles that were assigned in
the udpInit function.

udpMoreResults

SQL_NO_DATA_FOUND
SQL_SUCCESS
See Also rm_getMemory, SQLExecDirect, SQLMoreResults,

udpDescribeFcns, udpExecute
VALUE (structure)
Example
short REXTERNAL timsMoreResults (
short noargs, /* in: number of arguments to procedure */
RM_MEMTAG mTag, /* in: memory tag for rm_ memory calls */
HSTMT *phStmt, /* out: hstmt for result set */
{
if ( ctx->finished )
return SQL_NO_DATA_FOUND;
ctx->finished = 1;
SQLFreeStmt(ctx->hStmt, SQL_CLOSE);
SQLExecDirect(ctx->hStmt,
"select count(*) 'TOTAL ROWS FOUND' from timstab",
SQL_NTS);
*phStmt = ctx->hStmt;
return SQL_SUCCESS;
}

Chapter 16
SQL Date/Time Manipulation
Functions (VAL Prefix)
This chapter describes functions that convert date, time, or timestamp values between
the ODBC and the internal Velocis representations of these entities. Functions with a
ValPack prefix (ValPackDate, ValPackTime, and ValPackTimestamp) convert from
ODBC format to Velocis format, and functions with a ValUnPack prefix convert in the
opposite direction. Each function has a RETCODE data type and returns codes
(VAL_ prefix) that are listed in valerrs.h.
The type definitions for the Velocis format have a _VAL suffix and are defined in
caldefs.h. The DATE_VAL and TIME_VAL data types are long integers, and the
TIMESTAMP_VAL data type is a structure containing members for those two types.
The type definitions for the structures used to represent these values in ODBC have a
_STRUCT suffix and are defined in sqlxdefs.h. These definitions are shown below.
typedef struct tagDATE_STRUCT { /* ODBC date structure */
short year; /* Counted from 1 A.D. (e.g., year 1993 is 1993) */
short month; /* Must be between 1 through 12 */
short day; /* Must be between 1 through 31 */
} DATE_STRUCT;
typedef struct tagTIME_STRUCT { /* ODBC time structure */

short hour; /* Must be between 0 through 23 */
short minute; /* Must be between 0 through 59 */
short second; /* Must be between 0 through 59 */
} TIME_STRUCT;
typedef struct tagTIMESTAMP_STRUCT { /* ODBC timestamp structure */

short year, month, day; /* Date components (see above) */
short hour, minute, second; /* Time components (see above) */
long fraction; /* (Timestamp only) Fraction of a second:
** Must be between 0 and 999,900,000 (Velocis SQL
** only tracks fractions/sec to 4 decimal places).
*/
} TIMESTAMP_STRUCT;
SQL Date/Time Manipulation Functions (VAL Prefix) 16-1

VALPackDate
VALPackDate Convert an ODBC date value to an internal Velocis date
Syntax RETCODE VALPackDate (DATE_STRUCT *dsp, DATE_VAL *dvp)
Parameters dsp [Input] A pointer to a DATE_STRUCT structure

containing the ODBC date value.
dvp [Output] A pointer to the DATE_VAL structure defining
the internal Velocis date.
Description This function converts an ODBC date value into an internal Velocis
date.

VAL_OKAY
See Also VALUnpackDate

DATE_STRUCT (structure)

VALPackTime
VALPackTime Convert an ODBC time value to an internal Velocis time
Syntax RETCODE VALPackTime (TIME_STRUCT *tsp, TIME_VAL *tvp)
Parameters tsp [Input] A pointer to a TIME_STRUCT structure

containing the ODBC time value.
tvp [Output] A pointer to the TIME_VAL structure defining
the internal Velocis time.
Description This function converts an ODBC time value into an internal Velocis
time.

VAL_OKAY
See Also VALUnpackTime

TIME_STRUCT (structure)

VALPackTimestamp
VALPackTimestamp Convert an ODBC timestamp value to an internal Velocis timestamp
Syntax RETCODE VALPackTimestamp (TIMESTAMP_STRUCT *tssp,

TIMESTAMP_VAL *tsvp)
Parameters tssp [Input] A pointer to a TIMESTAMP_STRUCT structure

containing the ODBC timestamp value.
tsvp [Output] A pointer to the TIMESTAMP_VAL structure
defining the internal Velocis timestamp.
Description This function converts an ODBC timestamp value into an internal

Velocis timestamp.

VAL_OKAY
See Also VALUnpackTimestamp

TIMESTAMP_STRUCT (structure)

VALUnpackDate
VALUnpackDate Convert an internal Velocis date value to the standard ODBC format
Syntax RETCODE VALUnpackDate (DATE_VAL *dvp,

DATE_STRUCT *dsp)
Parameters dvp [Input] A pointer to a DATE_VAL value containing the

packed internal Velocis date value.
dsp [Output] A pointer to the DATE_STRUCT structure
containing the standard ODBC date.
Description This function converts a Velocis date from its internal format to the
standard ODBC format.

VAL_OKAY
See Also VALPackDate

DATE_STRUCT (structure)

VALUnpackTime
VALUnpackTime Convert an internal Velocis time value to the standard ODBC format
Syntax RETCODE VALUnpackTime (TIME_VAL *tvp,

TIME_STRUCT *tsp)
Parameters tvp [Input] A pointer to a TIME_VAL value containing the

packed internal Velocis time value.
tsp [Output] A pointer to the TIME_STRUCT structure
defining the standard ODBC time.
Description This function converts a Velocis time from its internal format to the
standard ODBC format.

VAL_OKAY
See Also VALPackTime

TIME_STRUCT (structure)

VALUnpackTimestamp
VALUnpackTimestamp Convert an internal Velocis timestamp to the standard ODBC

format
Syntax RETCODE VALUnpackTimestamp (TIMESTAMP_VAL *tsvp,

TIMESTAMP_STRUCT *tssp)
Parameters tsvp [Input] A pointer to a TIMESTAMP_VAL structure

containing the packed internal Velocis timestamp.
tssp [Output] A pointer to the TIMESTAMP_STRUCT
structure defining the ODBC timestamp.
Description This function converts a Velocis timestamp from its internal format
to the standard ODBC format.

VAL_OKAY
See Also VALPackTimestamp

TIMESTAMP_STRUCT (structure)

Chapter 17
Server Extension Toolkit Functions
(C++ API)
This chapter describes the the C++ classes, methods and macros that are in the Server
Extension Toolkit (C++ API). The classes and methods are described in section 17.1. The
macros defined for this toolkit are explained in section 17.2. For more information, see
Chapter 11 of the Velocis User’s Guide.
17.1 Class Reference

This section describes the C++ classes and methods that are in the Velocis Server
Extension Toolkit library. They are listed alphabetically by class and then method. The
five predefined classes include one principal base class (SeBase) and four derived classes
(DataDescriptor, ParmReceive, ParmSend, and ServerExtension).
Many of the class methods return status/error codes that are defined by the SeStatus
global enumeration, which is detailed as follows:
Table 17-1. Status Codes Defined by the SeStatus Enumeration

Status Code Description
AttachFailure The extension module cannot be attached.
DetachFailure The extension module cannot be detached.
InvalidData A data element of invalid type was encountered in the parameter buffer.
InvalidSize The size of the data element is incorrect.
LoadFailure The extension module cannot be loaded.
RPCError An RPC function returned an error.
Success A successful operation.
UnloadFailure The extension module cannot be unloaded.
class DataDescriptor : public SeBase

This class provides methods to build the definition of a structure or an array of
structures. It generates the definition automatically, based on the types of particular
elements of the structure. Internally, the definition is created as a dynamic array of
PL_ITEM structures. The constructor creates this array with some initial size, then
extends its size in chunks as necessary. The structure definitions are supposed to be
built only once, usually by the client envelope constructor.
Server Extension Toolkit Functions (C++ API) 17-1

Constructor and Destructor
DataDescriptor::DataDescription
Public DataDescription (short nInitSize = 0)
Remarks This is the default constructor of the data definition array. You can
specify the initial size of the data definition array by passing
nInitSize. The default initial size is 0.
DataDescriptor::~DataDescription
Public ~DataDescription ()
Remarks This destructor frees memory allocated for the data definition array.
Member Functions
DataDescriptor::Begin
Public void Begin (unsigned short nStructSize,
unsigned short nArraySize = 0)
Remarks This method inserts a logical start item into the definition of a
structure or an array of structures. For an array of structures, the
size of the array must be supplied in nArraySize. If a structure being
defined contains nested structures, the definition sequence must call
Begin every time a nested structure begins.
See Also DataDescriptor::End
DataDescriptor::End
Public void End ()
Remarks This method inserts a logical end item into the definition of a
structure or array of structures. The method automatically
determines whether it needs to put an end to the entire definition or
just to a nested structure definition. The number of End calls must
match the number of Begin calls in your structure definition. To
end the entire definition, the PL_FLAG_CLOSE data modifier flag is
added to the closing element.
See Also DataDescriptor::Begin

DataDescriptor::Field
Public void Field (type *_pa, short _nSize)
void Field (type& _f)
type:
[unsigned] {char | int | long | short}
| double | float | signed char
Remarks This set of methods is provided to define the description item of a
field of the structure. If the field is a scalar element, its reference (_f)
is the only parameter that must be provided. If the field is an array
(pointed to by _pa), the number of elements in the array must be
supplied (nSize).
See Also class ParmReceive, ParmReceive::operator >> (Table 17-2)
Example
struct _s {
char Param1[20];
struct _s1 {
int Param2;
float Param3;
double Param4;
} s1;
} s;
...
DataDescriptor desc;
desc.Begin(sizeof(struct _s));
desc.Field(s.Param1, sizeof(_data.Param1));
desc.Begin(sizeof(struct _s1));
desc.Field(s.s1.Param2);
desc.End();
desc.End();
DataDescriptor::IsEmpty
Public T_F IsEmpty ()
Remarks This method returns TRUE if the structure has not been built yet;
FALSE otherwise.

class ParmReceive : public SeBase
The ParmReceive class encapsulates the functionality for receiving parameter lists. It
provides various methods and operators to retrieve data from the parameter list in a
manner similar to the standard C++ streams. Each method and operator performs data
type validation to assure consistency between the expected and actual data in the list.
On the client side, the output parameter list object contains the data sent by the
extension. On the server side, the input list contains the data sent by the client
application.
Operators
ParmReceive::operator >>
Public ParmReceive& operator >> (char *ps)
ParmReceive& operator >> (type& value)
ParmReceive& operator >> (ParmReceive& (*func)(ParmReceive&))
type:
Parameters ps A pointer to a character array or a character string.
value The reference to a scalar value.
func A pointer to a function that takes a stream as an
argument and returns a stream as a result.
Remarks This operator retrieves a scalar value from the parameter list and
assigns it to the variable, if the type of data in the parameter list
matches that of the variable. For data to be retrieved successfully,
they must be sent by the remote process in a typesafe manner. The
only exception is when the operator is used with a character pointer,
because it accepts both character arrays (PL_CHAR) and null-
terminated character strings (PL_ASCIZ). In Table 17-2 below, the
correlation is shown between the C++ integral types and the DPL
(Data Portability Layer) types, as defined in the Velocis library. To
retrieve a structure or an array, a corresponding Get method must
be used.
Note: Type definitions can be used as long as they are based on

integral types. For example, the DB_ADDR type is defined in
Velocis as an unsigned long integer, so its counterpart’s type must
be DB_ADDR or unsigned long for the operation to be successful.

Table 17-2. Correlation Between C++ Integral Types and DPL Types
C++ Type DPL Type

char *(zero terminated) PL_ASCIZ
char PL_CHAR
double PL_DOUBLE
float PL_FLOAT
int PL_INT
long PL_LONG
short PL_SHORT
signed char PL_CHAR
signed short PL_SHORT
unsigned char PL_UCHAR
unsigned int PL_UINT
unsigned long PL_ULONG
unsigned short PL_USHORT
When reading a text string from the input stream, you have to make
sure that your character array has enough space to accommodate the
received data. If you are not sure about the size of the string in the
stream, the GetNextSize method should be used first.
If the operator is used with a function pointer, any function of the
ParmReceive object can be used with the operator as long as it
returns a ParmReceive object. This may be handy when the user
designs such a function. (Currently, no functions of that type are
included in the ParmReceive class.)
See Also ParmReceive::Get, ParmReceive::GetNextSize,
ParmSend::operator <<, ServerExtension::Rpc
Example
short MyServerExtension::XFunction(short *sOut, long *lOut, float *fOut)
{
short nRet;
ParmSend Input(XFUNCTION, GetSession());
ParmReceive Output;
nRet = Rpc(Input, Output);

Output >> *sOut >> *lOut >> *fOut;
return nRet;
}

Member Functions
ParmReceive::Get
Public SeStatus Get (type *pValue, short nSize = 0)
SeStatus Get (void *pValue, short nSize = 0, short nStructSize = 0)
type:
Parameters pValue A pointer to the address where the data is copied.
nSize The expected size of the data; this value is ignored if
0 is specified.
Remarks Call this method to retrieve a structure or an array of scalar values.
To read an array successfully, use the proper version of the Get
method. The method actually copies data from the parameter list to
the address pointed to by pValue only if their type in the list is
consistent with that of the argument. That is, the remote process
must send an array of the exact same type that is being expected.
(The only exceptions are for the char and unsigned char pointer
types, which accept both null-terminated character strings and
character arrays.) This guarantees that data sent by the remote
process as a character string, using << (char *), will be correctly
received by the local process with Get (char *). If a non-zero value
of nSize (the expected size of data) is specified, it is used for
additional data size validation. If nSize does not match that in the
parameter list, the InvalidSize error code is returned.
To retrieve a structure, an array of structures, or opaque data, use
the version of the method that takes a generic pointer (void *)
parameter. If nSize is provided, the additional size validation is
performed by comparing this value with the one in the descriptor
associated with the data element in the stream. By default, the size
of the data in the descriptor is used.
Always make sure that the destination structure or array has
enough room to accept the data from the stream. For opaque data
and character strings, it is recommended that GetNextSize be called
first, to inspect the size of incoming data. For structures, you can
use the sizeof function within nSize to insure safety.
This method returns the status code of the most recent operation.

See Also ParmReceive::operator >>, ParmReceive::GetNextSize,
ParmSend::operator <<, ParmSend::Put, SeBase::GetStatus
Example
short MyEnvelopeClass::XFunction(float fRes[], short nArraySize)
{
short nRet;
if (!IsServer()){
ParmSend Input(XFUNCTION, GetSession());
ParmReceive Output;
nRet = Rpc(Input, Output);
Output.Get(fRes, nArraySize);
}
return nRet;
}
ParmReceive::GetNextSize
Public unsigned short GetNextSize ()
Remarks Call this method to get the size, in bytes, of the next value in the
input stream.
See Also ParmReceive::GetNextType
ParmReceive::GetNextType
Public unsigned short GetNextType ()
Remarks Call this method to inspect the type of the next value in the input
stream. This method should be used when the type of data in the
input stream is unknown.
See Also ParmReceive::GetNextSize
ParmReceive::GetSize
Public unsigned short GetSize ()
Remarks Call this method to get the size, in bytes, of the current value in the
input stream.
See Also ParmReceive::GetType

ParmReceive::GetType
Public unsigned short GetType ()
Remarks Call this method to get the type of the current value in the input
stream. This method may be used to check the actual type in case
the input operation fails with the InvalidData status code.
See Also ParmReceive::GetSize
ParmReceive::NoData
Public T_F NoData ()
Remarks Call this method to detect the end of data condition in the input
stream. It returns TRUE if the "end of data" condition is reported by
the communication layer with the S_RPCENDOFPARMS error code.

class ParmSend : public SeBase
The ParmSend class is a C++ implementation of the parameter list to be sent to the
remote function. It provides various methods and operators to add data to the list, in a
manner similar to the standard C++ streams. Each method and operator performs data
type validation to check consistency between the expected and actual data in the list.
Operators
ParmSend::operator <<
Public ParmSend& operator << (char *ps)
ParmSend& operator << (type& value)
ParmSend& operator << (ParmSend& (*func)(ParmSend&))
type:
Parameters ps A pointer to a character array or a null-terminated
character string.
value A reference to scalar value.
func A pointer to a function that takes a stream as an
argument and returns a stream as a result.
Remarks This operator places a value in the output parameter list and assigns
a DPL type to it according to the variable’s type. For data to be read
successfully by the remote process, they should be retrieved by the
operator >> (its counterpart) or by the Get method with the same
type of argument. (For example, short and unsigned short integers
are considered different types, which results in the InvalidData
error code.) Table 17-2 shows the correlation between C++ integral
types and the DPL types defined in Velocis library.
The third version of the operator shown allows any method of the
output stream object to be used with the operator as long as it
returns an output stream object. This may be convenient if the user
needs to design such a method. (Currently, no methods of that type
are included in the ParmSend class.)
This operator returns the status code of the most recent operation.
Note: The Put family of methods can be used instead to perform the
same operation.

See Also ParmReceive::operator >>, ParmReceive::Get, ParmSend::Put
Example
short MyServerExtension::XMin(short sValue1, short sValue2)
{
short nMin;
ParmSend Input(XMIN, GetSession());
ParmReceive Output; // must be present even if no data
// will be returned
Input << sValue1 << sValue2;

nMin = Rpc(Input, Output);
return nMin;
}
Member Functions
ParmSend::Put
Public SeStatus ParmSend::Put (type *pValue, short nSize = 0)
SeStatus ParmSend::Put (void *pValue, PL_ITEM *pItemDesc,
short nSize = 0)
type:
Parameters pValue A pointer to the data item to be sent.
pItemDesc (Second version—for structure or opaque data only)
The DPL description of a structure, if the data is a
structure; if the data is opaque, specify NULL.
nSize The size of the array, structure, or opaque data. If 0
is specified, the item is considered a scalar value.
Remarks There are two forms of the ParmSend::Put method. The first
version shown is used to store a scalar value or an array of scalar
values, while the second version is used to store structure or opaque
data.
• Call the first form of this method to store a single scalar value or
an array of scalar values. The data items stored by the Put
method should be retrieved by a corresponding Get method.
Although scalar values stored by the Put method can also be

retrieved by the operator >>, arrays can only be stored by Put
and must be retrieved by Get. This version of Put returns the
status code of the most recent operation.
• Call the second form of this method to store a structure or
opaque data. The data items stored in the list by this Put can
only be retrieved by the corresponding Get method. On the
server side, this method insures that the data is actually copied
to the parameter list, which means that the data buffer can be
reused in loops. The nSize argument must be specified on the
server side, otherwise InvalidSize is returned (Success and
InvalidData are the other possible return codes). On the client
side, nSize is ignored for structures, and data is not physically
copied to the parameter list. Therefore, the data buffer cannot
be reused until Rpc is returned.
For opaque data, nSize must always be specified. But as with
structures, the data is physically copied to the parameter list on
the server side and is not on the client side.
See Also ParmReceive::operator >>, ParmReceive::Get,
ParmSend::operator <<, SeBase::GetStatus
Example
short MyEnvelopeClass::XAvg(short sData[], short nInSize)
{
if(!IsServer()){
short nAvg;
ParmSend Input(XAVG, GetSession());
ParmReceive Output; // must be present even if no data
// will be returned
Input.Put(sData, nInSize);
nAvg = Rpc(Input, Output);
}
return nAvg;
}

class SeBase
The SeBase class is a principal base class for all Server Extension Toolkit objects. It
encapsulates the error status information and connection status (server or client), and
provides overloaded new and delete operators for derived classes.
On the client side, these overloaded operators use the native Velocis rm_getMemory and
rm_freeMemory functions. On the server side, the operators use tagged memory to
allocate an object, which guarantees a proper cleanup when the extension is detached
from the session or the session is closed. In the case of multiple inheritance, any class
derived from SeBase must use SeBase as the first base class, because the delete operator
casts the pointer to this class to obtain the tag ID. If this is not an option, global new and
delete should be used. They are overloaded to allocate memory from the default tag
(Velocis server system memory).
The class also includes methods to obtain error information if a failure occurs. Since any
class in the toolkit is derived from SeBase, both the status and error code (if any) are
available.
By encapsulating the connection status, the class can tell you on which side (client or
server) the object has been allocated. This is vital in the case where a derived class
method can only be executed on the server side.
SeBase has a virtual destructor, so the derived objects can be effectively used in various
collection objects (lists, arrays, maps, etc.) that hold pointers to objects of different type.
A number of methods defined in the SeBase class are wrappers for some of the Velocis
em_ and rm_ functions. The wrappers are designed to represent Velocis functions that
have either different implementation on the client side than on the server side, or are not
available at all on the server side. If the function is not available on the client side, then
the wrapper is a stub. This makes the ServerExtension-derived classes independent
from the client/server API particulars. This architecture simplifies the task of
maintaining builds where some of the existing classes are re-implemented to include
remote functionality.
In most cases, the user does not need to use the wrapper methods. However, they are
used in the implementation of the CREATE_EXPORTS macro, so references to them are
included in the user program.

SeBase::SeBase
Protected SeBase (T_F bServer = FALSE)
Remarks This is a standard constructor. As a protected method, it enforces
subclassing. The default value of bServer is FALSE. From the client
side, it is called with no arguments, while on the server side, TRUE
is passed explicitly.
See Also SeBase::~SeBase
SeBase::~SeBase
Public virtual ~SeBase ()
Remarks This method is a standard destructor. Because it is a virtual method,
C++ ensures the destructor of the topmost derived class is called
first.
See Also SeBase::SeBase
Operators
SeBase::operator new
Public operator new (size_t nSize, short nMemTag = 0)
Remarks This operator performs an optimized memory allocation of nSize
bytes using rm_getMemory, defined in the Velocis library. The
default version of the operator is available for allocating both the
client and server-side objects. On the server side, you can also
specify a memory tag ID (nMemTag). The memory tag is internally
generated by rm_allocTag and can be obtained by calling the
GetMemoryTag member method. With tagged memory allocations,
you can guarantee that all objects allocated with the tag will be
properly cleaned up simply by freeing the tag.
If you should override this operator in your class, you must also
override the delete operator. On the server side, make sure your
overloaded operator uses rm_getMemory to perform allocation.
When using this operator, make sure that the class inherited from
SeBase comes first in the multiple inheritance declarations. If this is

not an option, the global new operator should be used (without the
tag parameter). In that case, the object is created with the default
memory tag (0 or NULL).
See Also SeBase::operator delete
Example
short nTag = GetMemoryTag(); // get tag of the object
theClass pObj = new(nTag) theClass; // allocate in tag nTag
SeBase::operator delete
Public operator delete (void *p)
Remarks This operator frees memory by calling rm_freeMemory and passing
the memory buffer pointer (p). On the server side, the operator
deletes the objects using the same tag as the new operator.
If you should override this operator in your class, you must also
override the new operator. On the server side, make sure you are
using rm_freeMemory to do the cleanup.
When using this operator, make sure that the class inherited from
SeBase comes first in the multiple inheritance declarations. To
obtain the memory tag ID, the operator casts the memory pointer to
SeBase, which only works if SeBase is the first base class.
Member Functions
SeBase::AllocateNewTag
Protected short AllocateNewTag ()
Remarks This method calls rm_allocTag to retrieve the value of the new
memory tag ID.
SeBase::FreeMemory
Protected void FreeMemory (void *ptr, short nTag)
Remarks This method calls rm_freeMemory (ptr, nTag), where ptr is a pointer
to the memory block to be freed, and nTag is the memory tag ID
where the memory block has been allocated.

SeBase::FreeTagMemory
Protected void FreeTagMemory (short nTag)
Remarks This method calls rm_freeTagMemory (nTag, 1), which frees the tag
and all of the memory associated with it.
SeBase::GetContext
Protected void **GetContext (RDM_SESS hSess, short hEM)
Remarks This method calls em_getContext (hSess, hEM), where hSess is the
session handle, and hEM is the extension module handle. It returns
a reference to the context pointer. This method can be used to get
access to the ServerExtension-derived object, which has been
created by ModInit.
SeBase::GetErrorCode
Public short GetErrorCode ()
Remarks This method retrieves the S_ return code from the most recent RPC
call. The purpose of this is to retrieve more detailed information
about the cause of a failure when GetStatus returns the RPCError
status.
SeBase::GetMemory
Protected void *GetMemory (size_t nLen, short nTag)
Remarks This method calls rm_getMemory (nLen, nTag), where nLen is the
size of the memory block, and nTag is the memory tag ID where the
memory block is allocated. It returns a pointer to the allocated
memory block.
SeBase::GetMemoryTag
Public short GetMemoryTag ()
Remarks Call this method to get the object’s memory tag ID. If you allocate
objects using this memory tag, they are guaranteed to be cleaned up
when the object itself is deleted at session’s end.

SeBase::GetStatus
Public SeStatus RPCStream::GetStatus ()
Remarks Call this method to get the status code of the most recent operation.
Possible status codes are defined by the SeStatus global
enumeration type, shown in Table 17-1 at the beginning of the
chapter. Note that this value is only used to indicate errors related
to client/server communication; it is not concerned with database
operations.
See Also SeBase::GetErrorCode
SeBase::IsServer
Protected short IsServer ()
Remarks This method can be used in a derived class to query if the execution
is being conducted on the server side or the client side. It is
instrumental for implementing polymorphic methods that behave
differently on different sides of the connection. The method returns
TRUE if the method was created on the server side (in the extension)
and FALSE if it is was created on the client side.
SeBase::LogWrite
Protected void LogWrite (char *str)
Remarks This method calls rm_systemLogWrite (char *format, ...). The
method writes a string (str) to the server console and to the log file
(RDS.log). Contrary to its native counterpart, it does not format the
output and only accepts a character string.
SeBase::Okay
Public T_F Okay ()
Remarks Call this method whenever you want to check if the most recent
operation was successful. It returns TRUE if the most recent
operation was successful, FALSE otherwise.

class ServerExtension : public SeBase
The ServerExtension class is designed as a tool to implement classes with methods fully
or partially executed remotely in an extension module. It can also be used as a tool to
convert existing classes into extension modules, whose methods can be called remotely.
By inheriting from ServerExtension, a class becomes polymorphic, meaning that its
methods can execute different code depending on whether the execution is conducted on
the server or on the client side. If a method needs to be executed remotely, the client
side logic usually differs from the server side logic. On the client, it consists of a simple
remote call to an envelope method in the extension module, which in turn may call the
same method. On the server, the server specific section of the method is executed.
A ServerExtension-derived subclass is a placeholder for all methods that are to be
executed remotely. A single instance of this class is created for each session when a
session attaches the extension. At this time, the pointer to the class object is saved in the
session’s memory context. Any session-specific data should be defined as the class
members to guarantee that the data is not shared by different sessions.
When the ServerExtension-derived object in the client program remotely invokes its
server counterpart, an appropriate member method of the server class is called in
response. In the toolkit, each RPC is viewed as a message sent by the client application
to the server extension. For the extension to process the message, the ServerExtension
class implements a message mapping scheme that allows derived classes to inherit
message maps associated with the parent classes. This allows further subclassing of the
existing envelope classes.
Each method that can be invoked remotely must be accompanied by an envelope
method with two arguments of type ParmSend and ParmReceive, representing input
and output parameter lists. Both types include a variety of methods and operators that
facilitate the job of storing and retrieving data in parameter lists. The envelope methods
are defined as message handlers. Upon retrieving the parameters from the input list,
they usually call the method that actually executes the code of the remote operation.
ServerExtension::ServerExtension
Public [default] ServerExtension ()
[client] ServerExtension (char *strModuleName, RDM_SESS hSess)
[server] ServerExtension (RDM_SESS hSess, short hEM)
Remarks There are 3 versions of the ServerExtension constructor: a default
constructor without parameters, a client-side constructor that passes

the extension module name (strModuleName) and the session handle
(hSess), and a server-side constructor that passes the session handle
and the extension module handle (hEM).
• The default constructor can be used on the client side only in
cases where the object is instantiated before the connection to
the server is created.
• The client-side constructor attempts to load and attach the
extension module by name. The handle to the module is stored
within the object. Only one object of the ServerExtension-
derived class can be instantiated per session.
The calling method is not concerned with whether the module is
already in memory. If the module is already in memory, the
calling method will increase the extension module load counter
on the server side. Otherwise, the module will be loaded into
memory.
The main purpose of this constructor is to automate loading and
attaching the extension module.
• The server-side constructor is called within the ModInit
function when the extension object is created. It is not used
directly by user functions, because ModInit is generated by the
CREATE_EXPORTS macro. The ModInit function is the place
for the code that needs to be executed in the extension module
when em_attach is called (that is, each time a new client attaches
to the extension module).
See Also ServerExtension::~ServerExtension
CREATE_EXPORTS (macro)
Example
UserExtension::UserExtension(RDM_SESS hSess, short hEM)
{
//server side initialization (em_attach called)
...
}

ServerExtension::~ServerExtension
Public ~ServerExtension ()
Remarks The destructor’s behavior depends on which constructor has been
used at the object’s creation. On the client side, the destructor will
attempt to detach and unload it from memory. As the server keeps
track of load requests, the actual unloading will only occur when the
last object of the class is deleted. On the server side, the destructor
is called by ModCleanup, which should include the code to execute
when the extension module is detached by the client program.
See Also ServerExtension::ServerExtension
Example
UserExtension::~UserExtension()
{
if (IsServer()) {
//server side cleanup (em_detach called)
...
}
else {
//client side cleanup (object is destroyed)
...
}
}
Member Functions
ServerExtension::Attach
Public T_F Attach (char *strModuleName)
Remarks This method is a client-side wrapper for em_attach; it has no effect if
it is called on the server side. It explicitly attaches the extension
module by name (strModuleName). Before the module can be
attached, it must be loaded into the server’s memory using the Load
method. The handle to the module is stored within the object and
can be retrieved by calling GetHandle. If FALSE is returned, you
should check the error code with GetErrorCode to determine the
cause of the failure. In most cases, it is not necessary to call this
method since it is called implicitly by the constructor.
See Also SeBase::GetErrorCode, ServerExtension::Detach,
ServerExtension::GetHandle, ServerExtension::Load

ServerExtension::Detach
Public T_F Detach ()
Remarks This method is a client-side wrapper to em_detach; it has no effect if
it is called on the server side. It explicitly detaches the attached
extension. Use this method when you are finished using the
extension module. If FALSE is returned, you should check the error
code with GetErrorCode to determine the cause of the failure. In
most cases, it is not necessary to call this method since it is called
implicitly by the destructor.
See Also SeBase::GetErrorCode, ServerExtension::Attach,
ServerExtension::Load
ServerExtension::GetDescription
Public static char *GetDescription () const
Remarks This server-side method retrieves a pointer to a static string. This
static method is called by the extension module to obtain the
description string of the module. By default, the string "A
C++ server extension" is returned. You can overload this method if
you want a different string to appear on the Velocis server console
when the module is loaded.
ServerExtension::GetHandle
Public short GetHandle ()
Remarks This method returns the extension module handle. On the client
side, the handle is returned by em_load in the object constructor.
On the server side, the handle is set in ModDescribeFcns.
ServerExtension::GetSession
Public RDM_SESS GetSession ()
Remarks This method retrieves the session handle.
See Also CREATE_EXPORTS (macro)

ServerExtension::Load
Public T_F Load (char *strModuleName)
Remarks This client-side method is a C++ version of em_load; it has no effect
if it is called on the server side. It explicitly loads the extension
module by name (strModuleName). When called, Load increases the
extension module load counter on the server side, physically
loading the extension module into memory only at the first call to
this constructor. The handle to the module is stored within the
object and can be retrieved by calling GetHandle. If FALSE is
returned, you should check the error code with GetErrorCode to
determine the cause of the failure.
Note: Right after it is loaded, the extension module will call the
OnLoad static method.
See Also SeBase::GetErrorCode, ServerExtension::GetHandle,

ServerExtension::OnLoad, ServerExtension::Unload
ServerExtension::OnLoad
Public static void OnLoad ()
Remarks This server-side method is only called once (by ModDescribeFcns)
when the extension module is being loaded into memory. This
allows you to include certain "on-load" actions in the extension
module code. It is a static method, because at loading time, no
object of type ServerExtension exists. Therefore, only static data or
methods can be accessed within your OnLoad method. Any global
calculations that are shared by some or all extension functions
should be done here. For example, this is an obvious place for
building structure definitions, since they only need to be created
once.
Note: This is not a virtual method, but once overloaded, it acts like
one, since ModDescribeFcns (which is compiled as part of the
CREATE_EXPORTS macro) uses the user-defined class to invoke it.

Example
#include <math.h>
#include "senvlp.hpp"
#define XEXP 1
#define XLOG 2
#define XSIN 3
#define XCABS 4
class MathServer : public ServerExtension {

static DataDescriptor m_ComplexDesc;
//the following are the private session data
struct _complex m_cValue;
double m_dValue;
MathServer(RDM_SESS hSess) : ServerExtension(hSess) {}

double Xcabs(struct _complex);
static char *GetDescription() {return "Remote math server";}
static void OnLoad();
DECLARE_RPC_MAP();
};
static DataDescriptor MathServer::m_ComplexDesc; //static member
BEGIN_RPC_MAP(MathServer, ServerExtension)
ON_RPC(XCABS, XCabs)
ON_RPC(XEXP, XExp)
ON_RPC(XLOG, XLog)
ON_RPC(XSIN, XSin)
...
END_RPC_MAP()
short MathServer::XCabs(ParmReceive& In, ParmSend& Out)

{
In.Get(&m_cValue);
m_dValue = cabs(m_cValue);
Out << m_dValue;
return 0;
}
CREATE_EXPORTS(MathServer)

ServerExtension::Rpc
Public short Rpc (ParmSend& out, ParmReceive& in)
Parameters out A parameter object to send to the extension.
in A parameter object to receive from the extension.
Remarks This client-side method sends a message to the extension module. It
has no effect if it is called on the server side. The ID of the server-
side method to call is stored as the first value in the ParmSend
parameter object. The extension module will call the server
envelope member function, specified in the message map for this
message ID. The results of the remote execution will be delivered as
the out object.
Note: Calling this method results in execution on the server side of

an envelope function with the following prototype:
short EnvelopeName (ParmReceive& out, ParmSend& in)
This function must be added to the RPC map using the ON_RPC
macro. As you can see, the types of the arguments of the remote
function are reversed.
Return Values The short value returned by the remote function.

See Also class ParmReceive, class ParmSend
BEGIN_RPC_MAP, END_RPC_MAP, ON_RPC (macros)
Example
#include "senvlp.hpp"
class MathClient : public ServerExtension {

enum FcnsId { XEXP=1, XLOG, XSIN, XCABS };
protected:
DataDescriptor m_ComplexDesc;
public:
Xmath(RDM_SESS hSess); //constructor
double Xexp(double);
double Xlog(double);
double XSin(double);
double Xcabs(struct _complex *);
...
};
(continued)

(continued)
MathClient(RDM_SESS hSess) : ServerExtension("xmath", hSess)
{
struct _complex cValue;
m_ComplexDesc.Begin(sizeof(cValue));
m_ComplexDesc.Field(cValue.x);
m_ComplexDesc.Field(cValue.y);
m_ComplexDesc.End ();
}
double MathClient::XCabs(struct _complex *pValue)

{
if (!IsServer()){
double dRet;
ParmSend in(XCABS, GetSession());
ParmReceive out;
in.Put(pValue, m_ComplexDesc);
nRet = Rpc(in, out);
if (!Okay()){
printf("Failed to call XMath: %d\n", GetErrorCode());
exit(1);
}
out >> dRet;
return dRet;
}
}
// Actual Xcabs code here
short MathClient::_Xcabs(ParmReceive &in, ParmSend &out)
{
...
}
ServerExtension::SetSession
Public void SetSession (RDM_SESS hSess)
void SetSession (HDBC hDbc)
Remarks The first version of this method is provided to explicitly set the
session handle (hSess) in the object. The second version is a helper
method that sets the session handle in the object from the SQL
connection handle (hDbc). This version is provided for the cases
where a mixture of SQL and d_ APIs are used in the program.
See Also ServerExtension::GetSession

ServerExtension::Unload
Public T_F Unload ()
Remarks This method is a client-side wrapper to em_unload; it has no effect
if it is called on the server side. It merely decreases the extension
module load counter; only when the counter reaches 0 is the
extension module actually unloaded. If FALSE is returned, you
should check the error code with GetErrorCode to determine the
cause of failure.
Note: The Velocis extension module standard API does not provide
an entry point for unloading, so this event cannot be custom
processed on the server.
See Also SeBase::GetErrorCode, ServerExtension::Load

17.2 Macro Reference
The SE Toolkit library defines a number of special macros the program must use to
implement the extension module. The five macros used (BEGIN_RPC_MAP,
CREATE_EXPORTS, DECLARE_RPC_MAP, END_RPC_MAP, and ON_RPC) are
listed and described in alphabetical order.
Macros
BEGIN_RPC_MAP
Syntax BEGIN_RPC_MAP (theClass, baseClass)
Fields theClass The derived class for which the message map is
defined.
baseClass The immediate parent class.
Remarks Use this macro as the opening bracket of the message map definition
for your server envelope object. The map has to be defined once in
one of the source (.cpp) files. Each entry in the map must be defined
using the ON_RPC macro.
See Also END_RPC_MAP, ON_RPC
CREATE_EXPORTS
Syntax CREATE_EXPORTS (theUserDefinedClass)
Remarks This macro must be called once in any of the source files (.cpp) that
implement the extension classes. It creates definitions for the
exported functions ModDescribeFcns, ModInit and ModCleanup
in a standard extension module. The macro parameter
(theUserDefinedClass) is the user-defined envelope class derived from
ServerExtension. An object of this type will be instantiated by
ModInit, and a pointer to it will be stored in the session context.
Therefore, each session contains its own unique object of type
theUserDefinedClass. Since this type is required to instantiate the
object, the standard export functions cannot be precompiled and a
macro must be used to generate them.
Note: The constructor and destructor of theUserDefinedClass can be

used to implement the code, which will be triggered by the module
attach and detach events.

Macro Definition The definition of the CREATE_EXPORTS macro is shown here. It
contains implementations for the ModDescribeFcns, ModInit, and
ModCleanup functions, and it contains the EnvFunc extension
module function, which is based on the ModFunction function
interface. (For information on the Mod functions, see Chapter 7 of
this manual.) Here are the details about these function
implementations:
• The ModDescribeFcns function calls the GetDescription and
OnLoad static methods. They may be overloaded in
theUseDefinedClass to change the startup behavior of the default
module. (The OnLoad method is not virtual, because it is called
before an object has been created.)
• The ModInit function creates an object of type
theUserDefinedClass. The object is created in the tagged memory
specific for the session. The implementation of the function is
theUserDefinedClass dependent.
• The code for the ModCleanup function does not depend on
theUserDefinedClass.
• The EnvFunc function is the only true extension module
function from the server perspective. Its purpose is to dispatch
the message received from the client via RPC to the proper
method defined in theUserDefinedClass. It retrieves from the
session context the pointer to the instance of theUserDefinedClass
and invokes the method identified in the input parameter list.
The macro is defined as follows:

#define CREATE_EXPORTS(theClass) \
static EMLOADTABLE emTable[] = { {EnvFunc, MESSAGE_ENTRY} }; \
void REXTERNAL ModDescribeFcns( short hMod, \
unsigned short *pusNumFcns, \
EMLOADTABLE **emLoadTable, \
char **loadStr ) \
{ \
*pusNumFcns = 1; \
*emLoadTable = emTable; \
if ( loadStr ) *loadStr = theClass::GetDescription(); \
ServerExtension::m_hModule = hMod; \
theClass::OnLoad(); \
} \
short REXTERNAL ModInit( RDM_SESS hSess ) \
{ \
void **ppContext = SeBase::GetContext(hSess, \
ServerExtension::m_hModule); \
RM_MEMTAG nTag = SeBase::AllocateNewTag(); \
theClass *theObjectPtr = new(nTag) theClass(hSess, nTag); \
*ppContext = theObjectPtr; \
return 0; \
} \
short REXTERNAL ModCleanup( RDM_SESS hSess ) \
{ \
theClass *theObjectPtr = (theClass*)*ppContext; \
RM_MEMTAG nTag = theObjectPtr->GetMemoryTag(); \
delete theObjectPtr; \
SeBase::FreeTagMemory(nTag); \
*ppContext = NULL; \
return 0; \
} \
short REXTERNAL EnvFunc( PL_DATADESC *inParmList, \
PL_DATADESC *outParmList ) \
{ \
RDM_SESS hSess; \
ParmReceive in(inParmList); \
in >> hSess; \
theClass *theObjectPtr = (theClass*)*ppContext; \
if (theObjectPtr->GetSession() != hSess) return -1; \
return theObjectPtr->DispatchMsg(inParmList, outParmList); \
}

DECLARE_RPC_MAP
Syntax DECLARE_RPC_MAP ()
Remarks This macro must be used once within the declaration of each
ServerExtension derived class. It declares some of the internal data
members and member methods necessary to facilitate the message
mapping architecture. The message map is created using the
BEGIN_RPC_MAP macro.
See Also BEGIN_RPC_MAP, END_RPC_MAP
END_RPC_MAP
Syntax END_RPC_MAP ()
Remarks Use this macro as the closing bracket of the message map for your
server envelope object.
See Also BEGIN_RPC_MAP, ON_RPC
ON_RPC
Syntax ON_RPC (MessId, Func)
Remarks Use this macro to define a message map entry for your envelope
class. The macro fields specify the message ID (MessId) and the
name of a member method of the derived class that was specified in
the BEGIN_RPC_MAP macro (Func). There must be one entry for
each message type receivable from the client, unless the entry is
defined in the parent class.
See Also BEGIN_RPC_MAP, END_RPC_MAP
Example
class MyEnvelope : public ServerExtension {
...
DECLARE_RPC_MAP();
};
BEGIN_RPC_MAP(MyEnvelope, SetverEnvelope)
ON_RPC(MESS1, emFunction1)
ON_RPC(MESS2, emFunction2)
END_RPC_MAP()

Chapter 18
Velocis Data Types
This chapter describes the C data types, constants, and macros that you need to use in
your Velocis database application programs. Those that are utilized in Velocis Core
database applications are described in section 18.1. The ones that you need to use in your
Velocis SQL ODBC-based applications are presented in section 18.2. The compound data
types (structures) used in Velocis are illustrated in section 18.3. The definitions are
contained in the various header files located in the Velocis include subdirectory.
Note: If you are a programmer in another language (such as Visual Basic, Delphi, etc.),
you need to map these C data types to the appropriate data types in the language you
plan to use.
18.1 Low-Level Database Programming

The data types, constants, and macros that you need to understand when using the
Velocis Core database function calls are described in the following three tables. These
tables summarize the primary entities that relate to the use of the Core API database
functions (d_ prefix), the administration functions (s_ prefix) and the resource manager
functions (rm_ prefix). The entities that are used in the the C++ server extension toolkit
are described in Chapter 17.
Velocis Data Types 18-1

Table 18-1. Low-Level Data Type Definitions
Type Name API Definition Description

BLOB_ID d_ unsigned long Blob identification handle. Contains the
page number of the first page in the blob file
that contains the blob field data.
DB_ADDR d_ unsigned long or struct Database address. A structure that contains
the file ID number and the record slot
number in the file.
GROUPLOCK d_ struct Group lock packet descriptor. See
section 18.3 and d_grplock.
RDM_DB d_ unsigned long Database handle. Is composed of a session
ID and a database number. Unique only
while a database is open. See d_open.
RDM_SESS d_ unsigned short Session identification number. One for each
login session. Note that the client-side value
for the same session may be different than
the server-side value. See s_login.
RM_MEMTAG rm_ void * Dynamic memory allocation tag. See
rm_createTag.
RM_PFILE rm_ int (client), void * (server) Resource manager file handle. See
rm_fileOpen.
RM_POOL rm_ void * Pooled memory tag. See rm_allocPool.
DBD_DBF s_ struct Database dictionary files descriptor packet.
See section 18.3 and s_dbAdd.
device s_ struct Device definition structure. See section 18.3
and s_devAdd.
EM_CHG s_ struct Extension module change packet. See
section 18.3 and s_emAdd.
FILEDEV s_ struct File device descriptor packet. See
section 18.3 and s_dbAdd.
USERINF_CHG s_ struct User information change packet. See
section 18.3 and s_userAdd.

Table 18-2. Low-Level Constant Definitions
Constant Description
DB_ADDR_SIZE Use when the size of a database address variable is needed. Same
as sizeof(DB_ADDR).
LITERAL_NULL_DBA Use when statically initializing database address fields in a
structure, such as a GROUPLOCK variable.
NULL_DBA Use to assign a null database address value to a DB_ADDR
variable in an assignment statement.
Table 18-3. Low-Level Macro Definitions
Macro Description
DB_ADDR_EQ(dba1, dba2) Returns 1 (true) if two database address (DB_ADDR) variables are
equal.
DB_ADDR_ISNULL(dba) Returns 1 (true) if a database address is null.
MAKE_SESS(hDb) Returns the session ID that is contained in the specified RDM_DB
value.
18.2 SQL Programming

Most of the data types and constants described below are defined in the Microsoft Open
Database Connectivity Specification. The declarations are included in the Velocis header
files sqldefs.h and sqlxdefs.h. The Velocis extensions are declared in sqlrdefs.h. All of
these header files are located in the Velocis include subdirectory. Note that these
headers are included automatically when you include the standard ODBC header files
sql.h or sqlext.h.
Velocis uses C data types (Table 18-4) as defined by ODBC. These "portable" data types
map to standard C types. Thus, to avoid type mismatch warnings from the compiler,
your application should use the special Velocis data types for parameter variables.

Table 18-4. ODBC C Function Argument Types
C Data Type Name C Data Type Description

HDBC void * Database connection handle.
HENV void * Environment handle.
HSTMT void * SQL statement handle.
RETCODE short Status/error code returned by all SQL functions.
SDWORD long Signed, double word integer arguments.
SWORD short Signed, single word integer arguments.
UCHAR unsigned char Unsigned character. Used for character array/string
arguments.
UDWORD unsigned long Unsigned, double word integer arguments.
UWORD unsigned short Unsigned, single word integer arguments.
Also provided are additional, Velocis-specific types (Table 18-5) for use with the SQL
support functions (i.e., the BCD, VAL, and SYS function APIs).
Table 18-5. SQL Support API Types
C Data Type Name C Data Type Description

BCD_HENV void * BCD environment handle. Assigned by BCDAllocEnv
and used by each BCD support function.
BCD_Z struct Packed BCD value. This is the Velocis format for a BCD
value as it is stored in the database. See BCDAllocZBuf.
DATE_VAL long Velocis internal julian date value.
TIME_VAL long Velocis internal time value.
TIMESTAMP_VAL struct Velocis internal timestamp value. Is composed of a
DATE_VAL and a TIME_VAL field.
VALUE struct SQL data value container. Used by SQL to pass argument
values to C-based UDF and UDP functions.
The following three tables list the standard ODBC/SQL data type definitions. Table 18-6
lists the standard SQL data types. Use of these definitions requires that you include the
sql.h header file.

Table 18-6. ODBC Core Data Type Definitions
ODBC Data SQL
Type Constant Data Type Description
SQL_CHAR char Specifies a fixed-length character string of specified length, in
bytes. This string is stored as a null-terminated string of
(length+1) bytes.
SQL_DECIMAL decimal Specifies a binary-coded decimal (BCD) value of a specified
precision (default 15) and scale (default 0). The precision is the
overall number of digits that are allowed, and the scale is the
number of digits that are allowed past the decimal point. For
example, decimal(4,2) will take the number 1234.5678 and
truncate it to 34.56.
SQL_INTEGER integer Specifies a 4-byte signed integer between -2,147,483,648 and
+2,147,483,647.
SQL_SMALLINT smallint Specifies a 2-byte signed integer between -32,768 and +32,767.
SQL_FLOAT float Specifies a double-precision floating-point number (usually 8
bytes). This data type is the same as double.
SQL_REAL real Specifies a single-precision floating-point number (usually 4
bytes).
SQL_DOUBLE double Specifies a double-precision floating-point number (usually 8
bytes). This data type is the same as float.
SQL_VARCHAR varchar Specifies a variable-length character string of specified length,
in bytes. This string is stored as a null-terminated string of
(length+1) bytes.
Table 18-7 lists the extended SQL data types. To use these types in addition to the
standard SQL data types, include the sqlext.h header file.

Table 18-7. ODBC Extended Data Type Definitions
ODBC Data Type Constant SQL Data Type Description
SQL_DATE date Specifies an SQL date value containing the
number of elapsed days since December 31, 1 BC.
Therefore, the date value for January 1, 1 AD is 1.
The value is stored as a long integer.
SQL_TIME time Specifies an SQL time value containing a
4-decimal-place, fixed-point time of the form
HHMMSS.dddd; it is stored as a long integer.
SQL_TIMESTAMP timestamp Specifies an SQL timestamp value consisting of
both a date and a time.
SQL_LONGVARCHAR long varchar Specifies an SQL character large object value.
SQL_LONGVARBINARY long varbinary Specifies an SQL binary large object value.
SQL_WCHAR wchar Specifies a fixed-length Unicode character value.
SQL_WVARCHAR wvarchar Specifies a variable-length Unicode character
value.
SQL_WLONGVARCHAR long wvarchar Specifies an SQL Unicode character large object
value.
Velocis-specific data types are listed in Table 18-8. These data types, the standard SQL
data types, and the extended SQL data types are made available when you include the
sqlrds.h header file.
Table 18-8. Velocis-Specific Data Type Definitions

ODBC Data SQL
Type Constant Data Type Description
SQL_CDATA c_data Specifies a column containing C data constructs that are composed
of basic data, structure data, and/or multi-dimensional arrays.
Databases containing c_data columns can only be queried using a
select statement. Modifications can only be made using the Velocis
Core (d_) API functions. This data type is supported by Velocis
SQL for compatibility with RDM applications migrated to Velocis
and requiring SQL database access for queries and reports. Refer
to Chapters 5 and 9 of the Velocis User's Guide for detailed
information on the use of c_data columns.
SQL_ROWID rowid Specifies a row identifier value. The rowid is a monotonic, long
integer value equal to the record number in the database file that
contains a particular row of a table.
Velocis supports all ODBC-specified data type conversions. This includes conversion
into a character string for any data type, and the usual conversions between numeric

types. If no conversion is desired, the data type can be set to SQL_C_DEFAULT, in
which case the result variable must be of the C data type that is compatible with the
column result as listed in Table 18-9.
Table 18-9. Mapping of Velocis SQL/ODBC Constants to C Data Types
ODBC Data Type Constant C Data Type Constant C Data Type

SQL_CDATA SQL_C_DATA specified array/struct
SQL_CHAR SQL_C_CHAR char *
SQL_DATE SQL_C_DATE DATE_STRUCT
SQL_DECIMAL SQL_C_CHAR char *
SQL_DOUBLE SQL_C_DOUBLE double
SQL_FLOAT SQL_C_DOUBLE double
SQL_INTEGER SQL_C_LONG long
SQL_LONGVARBINARY SQL_C_BINARY char *
SQL_LONGVARCHAR SQL_C_CHAR char *
SQL_REAL SQL_C_FLOAT float
SQL_ROWID SQL_C_LONG long
SQL_SMALLINT SQL_C_SHORT short
SQL_TIME SQL_C_TIME TIME_STRUCT
SQL_TIMESTAMP SQL_C_TIMESTAMP TIMESTAMP_STRUCT
SQL_VARCHAR SQL_C_CHAR char *
SQL_WCHAR SQL_C_WCHAR wchar_t *
SQL_WLONGVARCHAR SQL_C_WCHAR wchar_t *
SQL_WVARCHAR SQL_C_WCHAR wchar_t *

CMPLOADTABLE
18.3 Compound Velocis Data Types
CMPLOADTABLE Customized comparison function load table definition structure
API Customized comparison (cmp prefix)
Syntax typedef struct cmploadtable {

char cmpName[33];
PCMPFUNCTION cmpFunction;
} CMPLOADTABLE, *PCMPLOADTABLE;
Fields cmpName The name of the customized comparison routine.

Use this name in the SQL or Core DDL schema
when you want a column or field to have a sorting
attribute that uses this routine.
cmpFunction A pointer to your (C) module function that
implements the functionality of the (SQL/Core)
customized comparison function. For details, see
the cmpFunction function.
Description This structure contains the information that is needed to register a

customized comparison function. You must supply values for both
fields in the structure.
To register all of the customized comparison functions in a module,
you need to create an array of these structures, with an entry for
each customized comparison function. The cmpDescribeFcns
function uses this array table to register the functions.
See Also cmpDescribeFcns, cmpFunction, cmpShutdown (functions)

DATE_STRUCT
DATE_STRUCT SQL/ODBC date structure
API SQL/ODBC (SQL prefix)
Syntax typedef struct tagDATE_STRUCT {

short year;
short month;
short day;
} DATE_STRUCT;
Fields year The year, which must be greater than or equal to

1 A.D. (for example, 1997, which represents
1997 A.D.).
month The month. Possible values are 1 (January) to
12 (December).
day The day of the month. Possible values are 1 to 31.
Description This structure defines a date, consisting of the month, day, and year.
You use a C variable of DATE_STRUCT type to hold SQL date
values as a bound column result or parameter value.
See Also SQL date/time manipulation (VAL_) functions

dbase
dbase Database definition structure
API Administration (s_ prefix)
Syntax typedef struct dbase {

char dbname[33];
char dbmode;
unsigned short dbid;
long datecreate;
char createchg[8];
unsigned long createofs;
char dbaccess;
} dbase;
Fields dbname The database name.

dbmode System use only.
dbid The system-assigned database identifier.
datecreate The date of database creation (time() format).
createchg System use only.
createofs System use only.
dbaccess The database access type. Possible values for this
field are:
0 Global access
1 Access from a database access list
Description This structure contains database information. A field of this

structure type is contained in the database registration structure
(DBD_DBF). When calling s_dbAdd to register a new database,
you must specify the dbname and dbaccess fields in the dbase
structure. The function will assign the other values.
See Also DBD_DBF

s_dbAdd, s_dbGet, s_dbModify (functions)

DBD_DBF
DBD_DBF Database registration structure
Syntax typedef struct {

char dbdfiledev[33];
struct dbase db;
} DBD_DBF;
Fields dbdfiledev A string containing the name of the device where

the database dictionary is stored.
db A dbase structure containing the name of the
database and access information.
Description This structure contains the name of the database device in which the
data dictionary (.dbd) file is stored and information about the
database name.
See Also dbase

s_dbAdd, s_dbGet, s_dbModify (functions)

device
device Device definition structure
Syntax typedef struct device {

char devname[33];
char reserved2;
struct { char devkey[33]; char devdata[419]; } devpath;
short readonly_flg;
} device;
Fields devname The device name.

reserved2 Unused.
devpath.devkey, devpath.devdata
The two character array fields of the structure in
which the device path information is stored. See
the Description section for details.
readonly_flg A flag that indicates whether the device is read-
only.
Description This structure contains information about a Velocis device. The

devpath field structure contains a null-terminated character string
that defines the directory path of the device. The devpath structure is
organized in this manner so that a portion of the path (up to
33 bytes) can be indexed and used by the system to efficiently
ensure that the path is unique. You can assign the device path prior
to your call to s_devAdd, as in the example below:
struct device dev;
...
strcpy ( dev.devname, "sqldev" );
strcpy ( (char *)dev.devpath, "c:\v\sqldb" );
See Also s_devAdd, s_devAddEx, s_devModify, s_devModifyEx (functions)

EM_CHG
EM_CHG Extension module registration structure
Syntax typedef struct extmodule {

char emname[48];
} extmodule;
typedef struct {
struct extmodule em;
char emdevice[33];
} EM_CHG;
Fields emname The name of the extension module.

em A structure containing the name of the extension
module.
emdevice The name of the device on which the extension
module is stored.
Description This structure contains information about an extension module,

including its name and its associated device.
See Also s_emAdd (function)

EMLOADTABLE
EMLOADTABLE Extension module load table definition structure
API Extension module access (em_ prefix)

EMFCN fcn;
short id;
} EMLOADTABLE;
Fields fcn A pointer to the extension module function. The

function must have this prototype (see the
ModFunction function for details):
short REXTERNAL ExtensionModuleFunction
(PL_DATADESC *pInputParameterList,
PL_DATADESC *pOutputParameterList);
id The function identifier number.
Description This structure contains a pointer to an implemented extension

module function and an identifier number for that function. You
need to set up an array of these structures, using one element for
each extension module function in an extension module, with the
identifier numbers in sequential order, starting from 0. The
ModDescribeFcns function, which is defined by the user, uses the
array to register the extension module and its functions with the
Velocis Remote Procedural Call (RPC) subsystem.
An extension module function allows you to pass data between a
client and a server. It takes two arguments: a typed parameter list
for input data, and a typed parameter list for output data. To create
and modify these lists, use the parameter list functions (pl_ prefix).
See Also em_call, ModDescribeFcns, ModFunction, parameter list functions

(pl_ prefix)

FILEDEV
FILEDEV Database file registration structure

char fname[48];
char fdevice[33];
} FILEDEV;
Fields fname The name of a data file, key file, or BLOB file.
fdevice The name of the device on which the the file in
fname is stored.
Description This structure provides the name of the file device for the database
dictionary.
See Also s_dbAdd, s_dbModify (functions)

GROUPLOCK
GROUPLOCK Group lock request packet structure
API Core (d_ prefix)
Syntax typedef struct _GROUPLOCK {

LOCK_TYPE ftype;
short rstype;
DB_ADDR dba;
RDM_DB hDb;
unsigned short odn;
char lmode;
short status;
} GROUPLOCK;
Fields ftype The lock type that was requested in a call to

d_grplock. Your application must always fill in this
field. Possible enumeration values (defined in
rdm.h) are:
CMLOCK Lock on the current member. This constant
corresponds to the d_cmlock function. The
d_grplock function ignores the dba field.
The rstype field contains the set type.
COLOCK Lock on the current set owner. This
constant corresponds to the d_colock
function. The d_grplock function ignores
the dba field. The rstype field contains the
set type.
CRLOCK Lock on the current record. This constant
corresponds to the d_crlock function. The
d_grplock function ignores the dba and
rstype fields.
CRSLOCK Lock on the set that owns the current
record. This constant corresponds to the
d_crslock function. The d_grplock function
ignores the dba field. The rstype field
contains the set type.
CSLOCK Lock on the current set indicated by the set
type in the rstype field. This constant
corresponds to the d_cslock function. The
d_grplock function ignores the dba field.
DBALOCK Lock on the record specified by its database
address contained in the dba field. This

GROUPLOCK
constant corresponds to the d_dbalock

function. The d_grplock function ignores
the rstype field.
RTLOCK Lock on the record type contained in the
rstype field. This constant corresponds to
the d_rtlock function. The d_grplock
function ignores the dba field.
STLOCK Lock on the set type contained in the rstype
field. This constant corresponds to the
d_stlock function. The d_grplock function
ignores the dba field.
rstype The record or set type involved with the lock
request to d_grplock. If the ftype field is equal to
CRLOCK or DBALOCK, rstype is unused. If ftype is
RTLOCK, rstype is a record type. Otherwise, rstype
is a set type.
dba The database address of the record to lock when
ftype is set to DBALOCK. For other values of ftype,
this field is not used.
hDb The handle of the database involved with the lock
request to d_grplock. Your application must
always supply a database handle.
odn Reserved. Velocis uses this field internally. Your
application must not alter field contents in any way.
lmode A single character indicating the mode of lock
requested. Your application must fill in this field.
’r’ Read locking enabled.
’w’ Write locking enabled.
status System use only.
Description This structure contains lock request information for use by the
d_grplock function in making multiple lock requests for your
application.
See Also d_cmlock, d_colock, d_crlock, d_crslock, d_cslock, d_dbalock,

d_grplock, d_rtlock, d_stlock (functions)

IEFLOADTABLE
IEFLOADTABLE Import or export filter load table definition structure
API SQL import and export filter module (ief prefix)
Syntax typedef struct iefloadtable {

char iefName[33];
PIEFFETCH iefFetch;
PIEFSTORE iefStore;
PIEFCHECK iefCheck;
PIEFINIT iefInit;
PIEFCLEANUP iefCleanup;
} IEFLOADTABLE, *PIEFLOADTABLE;
Fields iefName The name of the import/export filter.

iefFetch A pointer to a function that fetches rows from the
import filter. For details, see the iefFetch function.
iefStore A pointer to a function that stores rows into the
export filter. For details, see the iefStore function.
iefCheck A pointer to a function that checks the data types of
the arguments to the filter. For details, see the
iefCheck function.
iefInit A pointer to a function that initializes filter
processing for a particular statement invocation.
For details, see the iefInit function.
iefCleanup A pointer to a function that cleans up after filter
execution. For details, see the iefCleanup function.
Description This type definition is used in an import/export filter module in the

declaration of a table of import/export filters contained in that
module. Each entry in the table maps a filter name to the functions
in the module that implement that filter’s functionality. Every field
must have a valid pointer. The IEFLOADTABLE array containing
the filter declarations is returned by the iefDescribeFcns function.
See Also iefCheck, iefCleanup, iefDescribeFcns, iefFetch, iefInit, iefStore

(functions)

PL_ITEM
PL_ITEM Parameter list item descriptor structure
API Parameter list (pl_ prefix)

unsigned long size;
PL_DATATYPE type;
} PL_ITEM;
Fields size Either the total number of elements in the array

(single or multi-dimensional) or the size, in bytes, of
opaque data. This field is used only if the item is an
array (the flags field has PL_FLAG_ARRAY set) or if
the item contains opaque data (the type field is equal
to PL_OPAQUE). Otherwise, the field is ignored.
type The data type indicator for the item. Specify a value
described in the table in the Description section,
below.
flags A bit map of data modifier flags. This field can
contain any combination of the indicators below.
PL_FLAG_ARRAY
The item is an array. The size field contains the
number of elements in the array.
PL_FLAG_FREE
NULL tag.
PL_FLAG_OPEN
The item marks the beginning of a structure. When
using this flag, the type field must be equal to
PL_STRUCT to indicate that the data type is a
structure.
PL_FLAG_CLOSE
The item marks the end of a structure. When using
this flag, the type field must be equal to PL_STRUCT
to indicate that the data type is a structure.

PL_ITEM
Description The pl_putStruct function uses arrays of this structure to define the
fields that make up a structure parameter. Structures can be nested
within a structure parameter.
The data type, which is specified in the type field, must be equal to
one of the enumerated values described in the table below. The
table lists the data type indicators, their equivalent C data types, and
their descriptions. Although equivalent data types for C are shown,
the conversion mechanism works for any variety of languages (for
example, SQL, Core DDL, Pascal, etc.).
Table 18-10. Data Types for Parameter Items
Indicator Value Equivalent C

for the type Field Data Type Comments
PL_CHAR char An ASCII character.
PL_DB_ADDR DB_ADDR A Velocis database address.
PL_DOUBLE double A double-precision, floating-point
number.
PL_FLOAT float A single-precision, floating-point
number.
PL_INT int An integer.
PL_LONG long A long integer.
PL_SHORT short A short integer.
PL_STRUCT struct The beginning or end of a structure.
When using this indicator, set
PL_FLAG_OPEN or
PL_FLAG_CLOSE in the flags field to
mark the beginning or end of the
structure, respectively. If you have
an array of structures, the size of the
array has to be specified only with
PL_FLAG_OPEN; it is not necessary
with PL_FLAG_CLOSE.
PL_UCHAR unsigned char An unsigned, ASCII character.
PL_UINT unsigned int An unsigned integer.
PL_ULONG unsigned long An unsigned, long integer.
PL_USHORT unsigned short An unsigned, short integer.
PL_WCHAR wchar A Unicode (wide) character.
See Also pl_putStruct (function)

TIME_STRUCT
TIME_STRUCT SQL/ODBC time structure
Syntax typedef struct tagTIME_STRUCT {

short hour;
short minute;
short second;
} TIME_STRUCT;
Fields hour The hour of the day. Possible values are 0 (12 am)
to 23 (11 pm).
minute The minute of the hour. Possible values are 0 to 59.
second The second of the minute. Possible values are 0 to
59.
Description This structure defines a time, consisting of the hour, minute, and
second. You use a C variable of TIME_STRUCT type to hold SQL
time values as a bound column result or parameter value.

TIMESTAMP_STRUCT
TIMESTAMP_STRUCT SQL/ODBC timestamp structure
Syntax typedef struct tagTIMESTAMP_STRUCT {

short year;
short month;
short day
short hour;
short minute;
short second;
long fraction;
} TIMESTAMP_STRUCT;
Fields year The year, which must be greater than or equal to

1 A.D. (for example, 1993 represents 1993 A.D.).
month The month. Possible values are 1 (January) to 12
(December).
day The day of the month. Possible values are 1 to 31.
hour The hour of the day. Possible values are 0 (12 am)
to 23 (11 pm).
minute The minute of the hour. Possible values are 0 to 59.
second The second of the minute. Possible values are 0 to
59.
fraction The fraction of a second, in billionths of a second.
Possible values are 0 to 999,900,000.
Description This structure contains a timestamp. You use a C variable of

TIMESTAMP_STRUCT type to hold SQL timestamp values as a
bound column result or parameter value.
Note that the fraction part of the timestamp structure is in billionths
of a second. Velocis SQL only tracks fractions of a second to four
decimal places. Thus, the last five digits of a timestamp fraction
value for a Velocis SQL application will always be 0.

UDFLOADTABLE
UDFLOADTABLE UDF function load table definition structure
API SQL UDF module (udf prefix)
Syntax typedef struct udfloadtable {

char udfName[33];
PUDFFUNC udfCall;
PUDFCHECK udfCheck;
PUDFINIT udfInit;
PUDFCLEANUP udfCleanup;
PUDFRESET udfReset;
} UDFLOADTABLE,*PUDFLOADTABLE;
Fields udfName The name of the UDF.

udfCall A pointer to the actual processing function for the
UDF. For details, see the udfFunc function.
udfCheck A pointer to the function that performs type
checking on the UDF parameters. For details, see
the udfCheck function.
udfInit A pointer to the function that initializes the UDF
module. For details, see the udfInit function.
udfCleanup A pointer to the function that cleans up the UDF
module after processing. For details, see the
udfCleanup function.
udfReset A pointer to the function that resets the module
after processing for an aggregate UDF. For
details, see the udfReset function.
Description This structure describes the functions that implement a UDF

module. At a minimum, the structure must specify the name of the
UDF and the addresses of at least the processing function (udfCall
field) and the parameter type checking function (udfCheck field). In
addition, the structure can optionally specify the addresses of an
initialization function (udfInit field) and a cleanup function
(udfCleanup field). The structure can also specify the address of a
UDF reset function (udfReset field), but only if the UDF is an
aggregate function. Unused fields of the structure contain NULL.
See Also udfCheck, udfCleanup, udfDescribeFcns, udfFunc, udfInit,

udfReset (functions)

UDPLOADTABLE
UDPLOADTABLE UDF function load table definition structure
API SQL UDP module (udp prefix)
Syntax typedef struct udploadtable {

char udpName[33];
PUDPCHECK udpCheck;
PUDPEXECUTE udpExecute;
PUDPMORERESULTS udpMoreResults;
PUDPINIT udpInit;
PUDPCLEANUP udpCleanup;
} UDPLOADTABLE, *PUDPLOADTABLE;
Fields udpName The name of the UDP.

udpCheck A pointer to the function that performs type
checking on the UDP parameters. For details,
see the udpCheck function.
udpExecute A pointer to the function that retrieves the first
result set for the UDP. For details, see the
udpExecute function.
udpMoreResults A pointer to the function that retrieves
subsequent result sets for the UDP. For details,
see the udpMoreResults function.
udpInit A pointer to the function that initializes the
UDP module. For details, see the udpInit
function.
udpCleanup A pointer to the function that cleans up the
UDP module after processing. For details, see
the udpCleanup function.
Description This structure describes the functions that implement a UDP

module. At a minimum, the structure must specify the name of the
UDP and the address of the function that obtains the first result set
(udpExecute field). The other UDP module functions are optional; if
they are not used, the structure fields for those functions contain
NULL.
See Also udpCheck, udpCleanup, udpDescribeFcns, udpExecute, udpInit,

udpMoreResults (functions)

userinf
userinf User information structure
Syntax typedef struct userinf {

char username[33];
char userpass[33];
char userpriv;
} userinf;
Fields username The name of the user. This name must be unique.
userpass The user password.
userpriv The database access privilege for the user. Possible
values are:
0 Normal user
1 Administrative user
Description This structure contains Velocis user information. A field of this

structure type is used in the USERINF_CHG structure, which
contains information on a database user for use in updating the
system catalog.
See Also USERINF_CHG

s_userAdd (function)

USERINF_CHG
USERINF_CHG User information and device structure

struct userinf us;
char usdevice[33];
} USERINF_CHG;
Fields us A userinf structure defining user information.

usdevice An array containing the home database device for
the user.
Description This structure contains database user information to use in updating

the system catalog.
See Also userinf

s_userAdd (function)

VALUE
VALUE SQL data value container structure

SQL UDF support (SYS prefix)
SQL UDF module (udf prefix)
SQL UDP module (udp prefix)

short type;
union {
short sv;
long lv;
float fv;
double dv;
double bv;
struct { long date; long time; } tsv;
char *cv;
DB_WCHAR *wcv;
} vt;
} VALUE;
Fields type A standard data type for a UDF or UDP function

argument. The standard data types are described in
section 18.1 of this chapter.
vt.sv A value of type SQL_SMALLINT.
vt.lv A value of type SQL_INTEGER, SQL_DATE, or
SQL_TIME.
vt.fv A value of type SQL_REAL.
vt.dv A value of type SQL_FLOAT.
vt.bv A value of type SQL_DECIMAL.
vt.tsv.date An absolute date for a structure value. No date is
available if this field is set to 0.
vt.tsv.time The number of seconds into the day for the current
time, multiplied by 10,000. For example, if the time
is 4 hours, 58 minutes, and 25 seconds in the
afternoon, use a value of {10,000 *
[((4+12) * 60 * 60) + (58 * 60) + 25]}, which equals
611,050,000.
vt.tsv A value of type SQL_TIMESTAMP.

VALUE
vt.cv A pointer to a value of type SQL_CHAR or

SQL_VARCHAR.
vt.wcv A pointer to a value of type SQL_WCHAR or
SQL_WVARCHAR.
Description This structure defines a parameter of a UDF or UDP. The type field
holds the parameter type, while the parameter value is placed in one
of the fields of the vt union, depending on the data type.
See Also udfCheck, udfFunc, udpCheck, udpExecute, udpInit,

udpMoreResults (functions)

VALUE_DESCR
VALUE_DESCR Import and export filter column values descriptor structure
Syntax typedef struct value_descr {

char *name;
short type;
short prec;
short scale;
} VALUE_DESCR;
Fields name The name of the column.

type The SQL data type of the column.
prec The precision of the column (or maximum display
width).
scale The scale of SQL_DECIMAL type columns.
Description An array of type VALUE_DESCR is passed into the iefInit function

for an import/export filter. This array contains one entry for each
column value to be imported or exported through the filter.
See Also iefInit (function)

Chapter 19
Return Codes and Error Messages
This chapter describes the return codes and error messages returned by the Velocis
functions. These codes and messages are organized in this chapter by the categories
listed below. For more information on error handling, see Chapter 7 of the Velocis User’s
Guide.
• Section 19.1: Standard return codes from Velocis functions
• Section 19.2: SQL-specific return codes from Velocis functions
• Section 19.3: Error messages returned by the sddlp utility
19.1 Standard Return Codes

This section describes the standard status and error codes returned by the Velocis Core
and administration API functions. A status code has a positive numeric value, while an
error code has a negative value. Note that a status code does not necessarily indicate an
operational error and that the internal Velocis function dberr is not called to interpret it.
The standard return codes have an S_ prefix. Table 19-1 below lists the standard Velocis
API return codes, sorted numerically.
Table 19-1. Standard (S_*) Return Codes Listed Numerically

Value Name Value Name Value Name
0 S_OKAY 21 S_CATLOCKED -13 S_ISMEM
1 S_EOS 22 S_LOCKLIMIT -14 S_ISOWNED
2 S_NOTFOUND 23 S_PARMEND -15 S_ISCOMKEY
3 S_DUPLICATE 6001 S_DBRIDLE -16 S_NOTCON
4 S_KEYSEQ 6002 S_DBRACTIVE -17 S_NOTKEY
5 S_UNAVAIL -18 S_INVOWN
6 S_DELETED -1 S_DBOPEN -19 S_INVMEM
8 S_EXOPENED -2 S_INVSET -20 S_INCOMPAT
9 S_OPENED -3 S_INVREC -21 S_DELSYS
10 S_INCMODE -4 S_INVDB -22 S_NOTLOCKED
11 S_UPGDEN -5 S_INVFLD -23 S_TRANSID
12 S_NOLOCK -6 S_INVADDR -24 S_TRACTIVE
13 S_NOTGRANTED -7 S_NOCR -25 S_TRNOTACT
14 S_LOCKED -8 S_NOCO -26 S_TRFREE
16 S_SETCLASH -9 S_NOCM -27 S_NOTRANS
17 S_RPCENDOFPARMS -10 S_KEYREQD -28 S_EXCLUSIVE
18 S_VOIDTX -11 S_BADTYPE -30 S_NOTOPTKEY
19 S_TXTIMEOUT -12 S_HASMEM -31 S_BADFIELD
Return Codes and Error Messages 19-1

Table 19-1. Standard (S_*) Return Codes Listed Numerically (continued)
Value Name Value Name Value Name
-32 S_COMKEY -1005 S_BADSRV -1053 S_DBINV
-34 S_NOTYPE -1006 S_BADEMH -1054 S_LONGNAME
-35 S_INVSORT -1007 S_FREEMODULE -1055 S_INCOMPSERVER
-37 S_INVSESS -1009 S_LOADMODULE -1056 S_NOTBASEFILE
-38 S_DBUNAVAIL -1010 S_DEVEXISTS -1060 S_NOCMPFUNC
-39 S_DBACCESS -1011 S_DBEXISTS -1061 S_OPENDBLIMIT
-40 S_DBNOTREG -1012 S_PRIV -1062 S_INVFCN
-41 S_ILLMODE -1014 S_NODEV -1063 S_TOOMANYEMS
-42 S_BUFLEN -1015 S_NODB -1064 S_PARMINTERR
-43 S_CONFLICT -1016 S_EMEXISTS -1065 S_INVPARM
-45 S_ILLDOWNG -1017 S_USEREXISTS -1066 S_NOT_STARTED
-46 S_NOFILE -1018 S_FILEOPERR -2000 S_NCPINVSTATE
-47 S_CATERR -1021 S_NOSVNAME -2001 S_INVSVRNAME
-48 S_INVFLOAT -1023 S_NOCONFIG -2002 S_NCPENCERROR
-49 S_INVDOUB -1024 S_NODBFEXISTS -2004 S_INVSESSID
-50 S_ILLCALL -1025 S_NOEM -2005 S_SVRUNAVAIL
-51 S_DBPERM -1026 S_NOUSER -2006 S_INSUFFNETRES
-52 S_INVNULL -1027 S_EMMEMS -2007 S_SESREJECT
-53 S_INVELEM -1028 S_DBASEMEMS -2008 S_NINTERR
-54 S_NOMARK -1029 S_FILEMEMS -2009 S_SESDISCON
-55 S_STATIC -1030 S_USERMEMS -2010 S_NOMEMORY
-56 S_PROGRAM -1031 S_NOTONLIST -4000 S_DPLINTERR
-57 S_LONGPATH -1032 S_ONLIST -4001 S_DPLTOOLARGE
-58 S_INVMODE -1033 S_OWNEXIST -4002 S_DPLINTOVF
-59 S_UNCOMMITED -1034 S_CATTIME -4003 S_DPLFLTOVF
-60 S_NODBERR -1035 S_DBINUSE -4004 S_DPLDBLOVF
-61 S_BADBLOB -1040 S_INVEM -4005 S_DPLINTUNDF
-62 S_BLOBPOS -1041 S_BUACTIVE -4006 S_DPLFLTUNDF
-63 S_BLOBUPD -1042 S_BUNOTACTIVE -4007 S_DPLDBLUNDF
-68 S_BADEXTNO -1043 S_BUBADFILEID -5001 S_RPCINTERR
-69 S_BADEXTLIMIT -1044 S_BUQUICK -5002 S_RPCINVFCN
-71 S_READONLY -1045 S_BUOPTION -5003 S_RPCSESSDISC
-74 S_NOSYSNULLS -1046 S_BUTIMEOUT -5004 S_RPCINVDATAITEM
-900 S_NOSPACE -1047 S_PATHEXISTS -5005 S_RPCINVDATATYPE
-1000 S_NOCATALOG -1048 S_FILEDEVICE -5007 S_RPCINVSESSID
-1001 S_USERNAME -1049 S_INVAMTTHRDS -6000 S_DBRERROR
-1002 S_PASSWORD -1050 S_BADPATH -6002 S_DBRNOREPORT
-1003 S_NOLOGIN -1051 S_NOTATTACHED -6003 S_DBRBADDB
-1004 S_UNREGEM -1052 S_USERLIMIT
The rest of this section lists the standard Velocis return codes, sorted by name (as defined
in rdserrs.h). Each description includes the return code, its numerical value, a message
string, and a description of the status or error. For ways to correct the errors, see
Chapter 13 in the Velocis User’s Guide.

S_BADBLOB -61
BLOB data error - the BLOB data has been corrupted.
The cyclic redundancy check (CRC) for the BLOB data being read by a
call to d_blobread indicates that the BLOB data has been corrupted. This
can be the result of an earlier recovery of an unlogged d_blobwrite.
S_BADEMH -1006
Extension module handle was bad.
Your application must first call em_attach to create an extension module
handle before it can call em_call or em_detach.
S_BADEXTLIMIT -69
New extension file limit < allocated size of file.
You have specified a maximum file size in a call to s_fileSetSizes that is
less than the currently allocated size of the file. This error is also
returned when you try to increase the size of a file after the current
maximum size has already been reached.
S_BADEXTNO -68
Bad extension file number.
You have specified an invalid extension file number in a call to either
s_fileInfo or s_fileSetSizes. The base file is always has an extension file
number of 0. You can call s_fileTotals to find out how many extension
files are attached to a particular base file.
S_BADFIELD -31
Field is not defined in current record type.
The field parameter passed to an optional key function (d_keystore,
d_keydel, or d_keyexist) does not represent an optional key field for the
current record.
S_BADPATH -1050
Physical path does not exist.
The application has specified a device path (directory) that cannot be
found.
S_BADSRV -1005
srv (task index) was bad.
The server handle is invalid. Before the application can use any database
access function, it must first log into the server (via s_login) to get a
server handle.
S_BADTYPE -11
Invalid database open mode or lock type.
The application has passed either an invalid mode string to d_open or an
invalid lock mode string to the locking functions.

S_BLOBPOS -62
d_blobseek offset position out of range.
In a call to d_blobseek, the application has requested a position beyond
the boundaries of BLOB data.
S_BLOBUPD -63
blob_id fields cannot be updated thru d_recwrite or d_c?write.
In a call to d_crwrite, d_csmwrite, d_csowrite, or d_recwrite, the
application has tried to update a BLOB ID field.
S_BUACTIVE -1041
Backup mode is active.
The application has tried to invoke backup mode but found that it is
already active.
S_BUBADFILEID -1043
Bad backup file ID number.
You have specified an incorrect file ID number in a call to
s_backupFreeFile. See s_showBackupFiles for more information.
S_BUFLEN -42
Buffer is not big enough to receive contents.
The buflen parameter passed to d_rdcurr or d_wrcurr is too small to
receive the entire currency.
S_BUNOTACTIVE -1042
Backup mode is not active.
You have called a hot backup function (s_backupEnd, s_backupFreeFile,
or s_showBackupFiles) that requires that Velocis has previously been
placed into hot backup mode.
S_BUOPTION -1045
Bad s_showBackupFiles function option.
The position option of s_showBackupFiles must be either FETCHFIRST
or FETCHNEXT.
S_BUQUICK -1044
A database is opened in ’quick’ mode.
You cannot place Velocis into hot backup mode when any database is
open in quick mode.
S_BUTIMEOUT -1046
Change log cycle timeout.
A change log cycle timed out while processing a call to s_backupBegin.
Retry your call to s_backupBegin later when system update activity is
lower.

S_CATERR -47
Catalog error.
The application has made a general catalog error during access or update
of the system catalog. For example, you tried to add a device with the
same path name as an existing device.
S_CATLOCKED 21
Catalog is locked by another process.
You have attempted to start a Velocis server when another server is
already using the catalog. If you are sure that there is no other Velocis
process using the catalog, a file contained in the catalog directory called
lockcat.fil can be removed to remedy the situation.
S_CATTIME -1034
Catalog timeout.
Velocis has timed out while processing an application call to an
administration API (s_) function. No changes have been made to Velocis.
Your application should try the call again. Note that this error might
happen if the server is heavily loaded.
S_COMKEY -32
Record has a compound key.
The application has attempted to use d_makenew to create an empty
record that has a compound key. Records containing compound keys
must be created with d_fillnew.
S_CONFLICT -43
Instance/table level locking conflict.
The application has attempted an illegal mixture of lock downgrade or
upgrade with escalation or de-escalation. The application cannot
downgrade a lock while escalating. It also cannot upgrade a lock while
de-escalating.
S_DBACCESS -39
Database is unavailable.
The application has tried to access a private database for which it does
not have access privileges (that is, it is not on the access list).
S_DBASEMEMS -1028
Device has database members, delete not allowed.
The application has attempted to delete a device that still has associated
database definitions. To delete the device, the application must first
either delete associated database definitions, or associate the databases
with another database device.

S_DBEXISTS -1011
Database exists.
The application has attempted to add a database definition to the system
catalog when the definition already exists. No change to the system
catalog is made.
S_DBINUSE -1035
Db is unavailable for catalog operation.
The application has attempted to change database information in the
system catalog when the database is currently open. The application
cannot change system catalog information until all users have closed the
database.
S_DBINV -1053
Invalid database dictionary.
Velocis cannot read the database dictionary (.dbd file) for the specified
database. The application has attempted to access an RDM database
from a Velocis server.
S_DBNOTREG -40
The database is not registered in the catalog.
The application has attempted to open a database not registered with the
system catalog. Check the database name parameter for d_open. If
necessary, ask the system administrator to register the database via
admin or rdsadm.
S_DBOPEN -1
Database not opened.
The application has tried to access a database that it has not opened. The
application must first call d_open to open the database.
S_DBPERM -51
No permission for Database operation.
The application has attempted to perform an insert, update, or delete
operation on the database without sufficient privileges. See your system
administrator, who will use admin or rdsadm to assign the application
insert, update, and/or delete privileges for the database.
S_DBRACTIVE 6002
Unable to perform an additional dbrepair operation.
The application has tried to call one of the dbrepair operations
asynchronously when a previous operation is still active. That is, the
operation has not been ended by a call to the s_dbrEnd function.

S_DBRBADDB -6003
Unable to open a database for one of the dbrepair operations.
A dbrepair operation cannot access the database being processed.
S_DBRERROR -6000
Internal dbrepair error.
S_DBRIDLE 6001
No dbrepair operation is active.
The application has attempted to call the s_dbrGetStatus or s_dbrEnd
function when no dbrepair operation is active.
S_DBRNOREPORT -6002
No report for a specific dbrepair operation.
A dbrepair operation has failed to open the specified report file.
S_DBUNAVAIL -38
Database is unavailable.
The application has attempted to open a database that is unavailable.
The application can only open databases marked available.
S_DELETED 6
Record/set deleted since last accessed.
The application has attempted to access a record or set that has been
deleted. The application should hold the record lock until it is finished
using the record or set.
S_DELSYS -21
Illegal attempt to delete system record.
The application has attempted to delete the system record, which is a
permanent record that cannot be modified or deleted. Velocis
automatically creates the system record when it initializes the database.
S_DEVEXISTS -1010
Device exists.
The application has tried to add a definition to the system catalog for a
device that already exists. No change has been made to the system
catalog.
S_DPLDBLOVF -4004
Double overflow.
A double value has been received that is too large for the recipient to
handle. This code is typically received when the pl_put function is
called.

S_DPLDBLUNDF -4007
Double underflow.
A double value has been received that is too small for the recipient to
called.
S_DPLFLTOVF -4003
Float overflow.
A floating-point value has been received that is too large for the recipient
to handle. This error is typically received when the pl_put function is
called.
S_DPLFLTUNDF -4006
Float underflow.
A floating-point value has been received that is too small for the recipient
to handle. This code is typically received when the pl_put function is
called.
S_DPLINTERR -4000
Internal DPL error.
An unexpected error has occurred in the data portability layer (DPL).
S_DPLINTOVF -4002
Integer overflow.
An integer value has been received that is too large for the recipient to
called.
S_DPLINTUNDF -4005
Integer underflow.
A negative integer value has been received that is too small for the
recipient to handle. This code is typically received when the pl_put
function is called.
S_DPLTOOLARGE -4001
The data stream to be converted is too large.
The data stream to be sent on the network is too large for the DPL to
handle.
S_DUPLICATE 3
Duplicate key.
The application has attempted to create or modify a record, resulting in
duplication of a unique key value.

S_EMEXISTS -1016
Extension module already exists in catalog.
The application has attempted to register an extension module already
registered with the system catalog. No change has been made to the
system catalog.
S_EMMEMS -1027
Device has extension module members, delete not allowed.
The application has attempted to delete a server device that is associated
with extension modules. To delete the device, either delete all extension
modules that reference it, or associate the extension modules with a
different device.
S_EOS 1
End of set.
A set navigation function or d_discon has reached the end of a set. The
d_isowner and d_ismember functions also return this code when the
current record is not an owner or a member of the set.
S_EXCLUSIVE -28
Exclusive access required.
The s_dbInit or s_dbInitfile functions must have the database opened in
exclusive mode to prevent other users from accessing the database.
S_EXOPENED 8
Database is exclusively opened.
The application has attempted to access a database that is opened in
exclusive mode by another application. The application cannot open the
database until the other application closes it.
S_FILEDEVICE -1048
File already exists on device.
The application has attempted to define a file when there is already a file
with the same name on the specified device. The application can furnish
a file name that is not in use on the device. Alternatively, it can request a
device that does not have a file with the desired file name.
S_FILEMEMS -1029
Device has file members, delete not allowed.
The application has tried to delete a server device that has associated
files. The application must first either delete the associated file
definitions or associate the files with a different device.
S_FILEOPERR -1018
Unable to open a file on server.
A call to open a file on the server has failed.

S_FREEMODULE -1007
The em_unload call failed.
An internal call from em_unload to DosFreeModule has failed. This call
is made when the last application calls em_unload for an extension
module. Obtain all possible information by calling d_errinfo.
S_HASMEM -12
Record is owner of non-empty set(s).
The application has attempted to delete the owner record of a set. The
application must first disconnect all member records before deleting the
owner record.
S_ILLCALL -50
Illegal function call from client.
The application has attempted to call an internal function that is available
only to Velocis service modules.
S_ILLDOWNG -45
Illegal attempt to downgrade a lock inside a Tx.
Illegal request for a read lock on an instance already write-locked inside a
transaction. The application cannot free or downgrade write locks within
a transaction.
S_ILLMODE -41
Attempt to change read lock mode from within Tx.
Invalid attempt to change read lock mode while a transaction is active.
The application cannot call d_rdlockmodes for an active transaction.
S_INCMODE 10
Incompatible open mode (db already open).
The application has attempted to open a database with an incompatible
transaction flag. Once a database has been opened in transaction mode,
all applications must open the database in transaction mode. The same is
true for the no-transaction mode.
S_INCOMPAT -20
Incompatible dictionary file.
The application has attempted to open a database for which the
dictionary was created by an old version of ddlproc. Use the version of
ddlproc supplied with the server to re-create the database dictionary.
Note that older versions of the database (data and key files) might be
incompatible with this version of the server.

S_INCOMPSERVER -1055
Client <--> server incompatibility.
The s_login function has found that the client-side runtime version is
incompatible with the Velocis server version.
S_INSUFFNETRES -2006
Insufficient network resources.
The application has attempted to establish a network connection for
which insufficient resources are available. Typically this code indicates
that a host network resource such as sockets or network I/O buffers has
been exceeded. Check the network configuration file for the particular
network transport being used and adjust the resource values.
S_INVADDR -6
Invalid db_address.
The application has supplied an invalid database address.
S_INVAMTTHRDS -1049
Too many threads.
The application has specified too large a number of threads (normal plus
priority) in the configuration.
S_INVDB -4
Invalid database handle.
The application has specified an invalid database handle. All functions
that access the database require a valid database handle obtained from
d_open or d_iopen.
S_INVDOUB -49
Field contains invalid double value.
The application has passed an illegal double-precision floating-point
value to a function that creates or writes a record or field.
S_INVELEM -53
Invalid table element requested.
The application has specified an invalid value for the table element
parameter for d_dict. Be sure that the application specifies a legal value,
as defined in the Core API (d_) functions.
S_INVEM -1040
Extension module has no ModDescribeFcns function.
The extension module does not have a implemented ModDescribeFcns
function. This function is required so that the server knows which
functions are included in the extension module. The em_load function
returns this code.

S_INVFLD -5
Invalid field name.
The application has passed an invalid value as a field name parameter to
a field access function (for example, d_crread). The application has
probably provided a record or set type.
S_INVFLOAT -48
Field contains invalid floating point value.
The application has passed an illegal floating-point value to a function
that creates or writes a record or field.
S_INVFCN -1062
An invalid function id number was passed to em_attach or em_load.
S_INVMEM -19
Record not legal member of set.
The application has attempted to perform a set operation on a record
type that is not a member of the specified set.
S_INVMODE -58
Database opened in wrong mode for operation.
The application has selected an invalid mode at database open for the
function being called. For example, a call to d_dbflush for a database
opened in temporary mode returns this error.
S_INVNULL -52
A NULL pointer parameter has been provided.
The application has passed an invalid NULL pointer to a function.
S_INVOWN -18
Record not legal owner of set.
The application has attempted to perform a set operation on a record
type that is not the owner of the specified set.
S_INVPARM -1065
Invalid parameter.
The application has attempted to use an incorrect data type. In addition,
this error might occur if the application has called pl_putStruct with
either fewer than three elements in a PL_ITEM structure array (that is,
with an empty structure descriptor) or with an incomplete array.
S_INVREC -3
Invalid record.
The application has specified an invalid value for a record type
parameter to a record function (for example, d_recread). The application
has possibly used a set or field constant.

S_INVSESS -37
Session or database handle is invalid.
The session handle or database handle (which incorporates the session
handle) that was passed to a Core API (d_) function is invalid. You may
be passing a session handle where a database handle is required, or vice
versa. A valid session handle returned from s_login must be used.
S_INVSESSID -2004
Invalid session ID.
The application has specified an invalid session identifier. This code
indicates an internal error.
S_INVSET -2
Invalid set.
The application has specified an invalid value for the set type parameter
to a set function (for example, d_connect). The application has possibly
used a record or field constant or omitted the set parameter.
S_INVSORT -35
Invalid country table sort string.
The application has specified a country table sort string that is longer
than two characters. Correct the sort string in rdm.ctb and re-run the
application.
S_INVSVRNAME -2001
Invalid server name.
The server cannot be found, or the server name is invalid (that is, longer
than 16 characters). Check the name that the application has supplied to
s_login to be sure that it is correct. Verify that the server is running on
the correct node.
S_ISCOMKEY -15
Field is a compound key.
The application has attempted to use a field function (d_crwrite,
d_csmwrite, or d_csowrite) to write to a compound key field. Field
functions cannot write to compound keys. When the application updates
the elements of a compound key field, the compound key is
automatically updated.
S_ISMEM -13
Record is member of set(s).
The application has attempted to delete a record that is currently owned
by one (or more) owner records. The application must first disconnect
this member record from all its owners before deleting it.

S_ISOWNED -14
Member already owned.
The application has attempted to connect a member record to a set to
which it is already connected. If the application needs to connect a
record to a different owner record, it must first disconnect it from the
current owner before connecting the record to a new owner.
S_KEYREQD -10
Key value required.
The application has attempted to use d_makenew to create a record that
has key fields, and has not called d_setkey yet to create all the fields. If
the record has many keys, it might be easier to use d_fillnew to create
the record.
S_KEYSEQ 4
Field type used out of sequence in d_keynext.
The application has made an invalid call to d_keyread to read a key. The
application must first establish the position of the key (for example, via
d_keyfind or d_keynext) before calling d_keyread.
S_LOADMODULE -1009
The em_load call failed.
A call to em_load has failed to load the extension module, even though
an entry for it has been found in the system catalog. Be sure that the
extension module file exists on the server and in the correct directory, as
indicated by the device registered in the system catalog.
S_LOCKED 14
Lock was granted in previous request.
The application has made a request for a lock on an item that already has
a lock.
S_LOCKLIMIT 22
The maximum number of row-level locks allowed for the calling session
has been reached. You can call the d_locklimit function to reset the
maximum limit. However, this status is designed to inform a session that
it needs to use table-level locks instead of row-level locks, to prevent
server performance degradation due to the management of many row-
level locks.
S_LONGNAME -1054
Name too long.
The application has specified a name (for example, database name or
extension module name) that is too long.

S_LONGPATH -57
Database file path too long.
The application has specified a path name too long to be used to form a
Velocis file name. For example, the CATPATH environment variable
setting for the name might be too long for Velocis to handle.
S_NCPINVSTATE -2000
Failed to initialize NCP.
The client library has failed to initialize the NCP. This code indicates an
internal error.
S_NCPENCERROR -2002
NCP encryption error
An error occurred while attempting to perform encryption on an NCP
message packet. This indicates some kind of internal error occurred.
S_NINTERR -2008
NCP internal error.
S_NOCATALOG -1000
Unable to open server catalog.
Velocis cannot find the system catalog when the server starts. Either the
application has not set the CATPATH environment variable or the
variable does not point to the location where catalog.dbd is located.
S_NOCM -9
Set has no current member.
The application has attempted to access a set member (for example, via
d_csmread), but it has not yet established a current member for the set
(for example, via d_findnm).
S_NOCO -8
Set has no current owner.
The application has attempted to access a set owner (for example, via
d_csoread), but it has not yet established a current owner for the set (for
example, via d_findco).
S_NOCMPFUNC -1060
User-defined comparison function has not been registered.
S_NOCONFIG -1023
Config record does not exist.
The system configuration record does not exist in the system catalog.
Velocis cannot run without a system configuration record. Shut down
the server and check the application to ensure that it creates a valid
database registered with the server.

S_NOCR -7
No current record.
The application has called a function for which there is no current record
to process.
S_NODB -1015
No database.
The application has attempted to access a definition in the system catalog
for a database that does not exist.
S_NODBERR -60
Specified error handler does not exist.
The error handlers passed into a call to either d_unset_dberr or
d_reset_dberr does not exist.
S_NODBFEXISTS -1024
Database file does not exist.
The application has attempted to modify a database definition for a
database file that does not exist. This code indicates an internal
inconsistency error.
S_NODEV -1014
No device.
No database device is registered in the system catalog. The application
has attempted to access a database device. The application must first
register the database device before registering server objects that access
it. This code is also returned if the system administrator has tried to add
a server object (for example, a database definition) that accesses the
database device.
S_NOEM -1025
Extension module does not exist.
The application has attempted to access, modify, or delete the definition
of an extension module that has not been registered with the system
catalog.
S_NOFILE -46
Unable to locate a file.
A data or key file is missing. Check the system catalog definition for the
database, making sure that each data and key file exists on the device
specified.
S_NOLOCK 12
Trying to free unlocked entity.
The application has attempted to free an item that is not locked.

S_NOLOGIN -1003
Login has been denied.
The application cannot log into the server. Usually this code indicates
that the user name and/or password is invalid.
S_NOMARK -54
Mark not found during d_trrollback.
The application has called d_trrollback with a transaction marker that
does not match any markers put into the transaction change log (via
d_trbegin or d_trmark). All changes in the transaction have been
undone, but the transaction is still active.
S_NOMEMORY -2010
Insufficient memory available for operation.
The client or server computer has insufficient memory to process the
request function call. For hot backup, this code indicates insufficient
memory for allocating the hot backup control tables.
S_NOSPACE -900
Available disk space below min threshold.
The application has called a function that cannot respond. Available
space on a Velocis device has fallen below the minimum threshold
needed to implement the function.
S_NOSVNAME -1021
Server name not in catalog.
The application has attempted to add a null server name to the system
catalog. The application must provide a valid server name. This name
must be alphanumeric, beginning with a letter. Case is significant.
S_NOSYSNULLS -74
Record does not contain sysnulls_.
There is no sysnulls_ field in the current record. The sysnulls_ field only
exists in (and is automatically created in) Core DDL versions of SQL
databases. This error probably resulted from a call to d_nullset or
d_nulltest.
S_NOT_STARTED -1066
Server not started.
The application has attempted to execute a command on a server that is
not currently running. This error can occur from any call inside the
application server.

S_NOTATTACHED -1051
Client is not attached to extension module.
The application has been unsuccessful in a call to em_attach to attach to
an extension module.
S_NOTBASEFILE -1056
File to s_fileAddExt is not a base file.
The base file to which an extension is to be added must be specified in
the your call to s_fileAddExt. You may have specified an incorrect base
file device name.
S_NOTCON -16
Record not connected to set.
The application has attempted to work with a record that has not been
connected to a set.
S_NOTFOUND 2
Record not found.
A key find function cannot locate the specified key.
S_NOTGRANTED 13
Instance lock not granted, covered by an existing table lock.
The application has requested an instance lock, but it already has a table
lock providing implicit access to the instance. Even though the instance
lock is not granted, the application still has access to the instance.
S_NOTKEY -17
Field not a valid key.
The application has attempted an operation on a key field but has not
specified a valid key name. The application might have omitted the
parameter entirely or specified a record or set name.
S_NOTLOCKED -22
Illegal attempt to access unlocked record/set.
The application has attempted an operation on a record or set that
requires a lock. Read locks are usually required for read operations.
Write locks are needed for insert, update, and delete operations.
S_NOTONLIST -1031
User/database not on access list.
The application has attempted to delete a user from a database access list
to which the user was never added. No change to the database access list
has been made.

S_NOTOPTKEY -30
Field is not an optional key field.
The application has specified a value that does not represent an optional
key field. The optional key functions (d_keydel, d_keyexist, and
d_keystore) can only be used on optional keys.
S_NOTRANS -27
Attempted transaction in no-trans mode.
The application has tried to initiate a transaction when no transaction
mode is active. This mode allows the application to modify the database
only without transactions.
S_NOTYPE -34
No current record type.
The application has called d_recnext or d_recprev without previously
establishing a record type in a call to d_recfrst, d_reclast, or d_recset.
S_NOUSER -1026
User does not exist.
The application has attempted to access the definition of a user who is
not registered in the system catalog.
S_OKAY 0
Normal return, okay.
The function called by the application has detected no errors.
S_ONLIST -1032
User/database already on access list.
The application has attempted to add a user to a database access list that
already includes the user. No change has been made to the database
access list.
S_OPENDBLIMIT -1061
Maximum number of databases are currently open.
This error occurs on an attempt to open a database when the maximum
allowed number of databases are currently open. The limit can be set
using the MaxOpenDbs velocis.ini setting in the [Engine] section.
S_OPENED 9
Cannot exclusively open database, it is already opened.
The application has attempted to exclusively open a database already
opened by another application. Your application must wait until all
other applications close the database before it can successfully execute an
exclusive open.

S_OWNEXIST -1033
Owner already exists.
The application has attempted to define a user as the owner of a database
that already has an owner. Your application must first delete the existing
owner.
S_PARMEND 23
End of parameters has been reached.
The application has attempted to retrieve a parameter (via pl_get) from a
parameter list that contains no more parameters.
S_PARMINTERR -1064
Parameter list internal error.
Internal RPC error.
S_PASSWORD -1002
Wrong password.
The application has specified an incorrect password in a call to s_login.
S_PATHEXISTS -1047
Path exists already.
The application has attempted to create or modify a device for which the
path is already in use. Two Velocis devices can never refer to the same
path.
S_PRIV -1012
No privilege.
The application has insufficient privileges to execute the function that it
has called. For hot backup, this code indicates that administrator
privilege is required.
S_PROGRAM -56
Program(mer) error -- can’t do operation, but otherwise OK to proceed.
The function that the application has called is not implemented.
S_READONLY -71
Attempt to modify a read-only file.
A read-only file is one that is located on a read-only device. Any call to a
function that modifies a record contained in a read-only file will return
this error.
S_RPCENDOFPARMS 17
End of RPC parameter list reached.
The application has attempted to retrieve a parameter (via pl_get) from a
parameter list that contains no more parameters.

S_RPCINTERR -5001
Internal RPC error.
S_RPCINVDATAITEM -5004
RPC error.
The application has attempted to use a data type in an incorrect context.
(For example, if the application uses a PL_ASCIZ data item inside a
structure, or if it does not use PL_FLAG_OPEN and PL_STRUCT in the
first entry in the PL_ITEM list for pl_putStruct.)
S_RPCINVDATATYPE -5005
Invalid data item type in parameter list.
The application has passed an invalid data type to one of the parameter
list (pl_ prefix) functions.
S_RPCINVFCN -5002
RPC error. The application has passed an invalid function identifier to
em_call. Be sure that the function identifier matches the definition
provided in ModDescribeFcns in your extension module.
S_RPCINVSESSID -5007
RPC error. The application has passed an invalid session identifier to the
RPC layer. This problem is typically caused by an invalid session handle
passed to a function that generates an RPC call. Check the session handle
parameter.
S_RPCSESSDISC -5003
RPC error. The session connection with the server has been abnormally
terminated. Terminate the application, because further communication
with the server (using this session) is not possible.
S_SESDISCON -2009
The session is disconnected.
A network error has occurred. If the network is still active, you can
re-run your application.
S_SESREJECT -2007
Session rejected connection.
The server has rejected an attempt to connect by the network transport.

S_SETCLASH 16
Set currency clash with another user.
The current set being processed by the application has changed. The
application must have released a lock on the record (current member),
and it is now attempting to navigate or change the record after
re-establishing the lock. During the time that the lock was released,
another application has modified the record. The record either is
connected to a different owner or is not connected to any owner.
S_STATIC -55
Illegal attempt to write lock static entity.
The application has attempted to place a write lock on a record or set
(instance or table) that is defined as STATIC. To update the record or set,
the application must open the database in exclusive ("x") mode.
S_SVRUNAVAIL -2005
Server unavailable (i.e., doesn’t exist).
The network has run out of resources (connections) and has rejected the
connect request. Re-run your application later.
S_TOOMANYEMS -1063
Too many extension modules are currently loaded.
S_TRACTIVE -24
Transaction already active.
The application has called d_trbegin to start a new transaction when a
transaction is already active. Nested transactions are not supported.
S_TRANSID -23
Transaction ID not supplied.
The application has not supplied a transaction identifier in a call to
d_trbegin. The transaction identifier can be a zero length string but not a
NULL pointer.
S_TRFREE -26
Cannot free locks within a transaction.
The application has attempted to free a lock within a transaction. Write
locks cannot be freed within a transaction. Similarly, read locks cannot
be freed inside a transaction unless the free read lock option has been set
in a call to d_rdlockmodes.
S_TRNOTACT -25
Transaction not active.
The application has attempted to end, abort, mark, or roll back a
transaction that is not active. The application can begin a transaction by
calling d_trbegin.

S_TXTIMEOUT 19
d_trbegin timed out - change log cycle in progress.
An application call to d_trbegin has timed out, because a change log
cycle is in progress. The application should retry the call after a few
seconds.
S_UNAVAIL 5
Lock request currently unavailable.
The application has requested a lock on a record or set that is currently
locked by another session.
S_UNCOMMITED -59
Modification to an uncommitted set.
The application has requested modification for an uncommitted,
modified record that has a record lock, but no set lock, in another session.
The application can avoid this lock contention by issuing both a set lock
and a record lock on the owner and member records that are to be either
connected to or disconnected from the set.
S_UNREGEM -1004
Extension module is not registered in catalog.
The application has called em_load to load an unregistered extension
module. Before the application can use an extension module, it must be
defined (registered) with the system catalog. Ask the system
administrator to register the extension module using admin or rdsadm.
S_UPGDEN 11
Upgrade denied - another upgrade pending.
Your application has requested an upgrade when another upgrade is
already pending. Velocis can only process one upgrade at a time and
immediately denies the new upgrade request.
S_USEREXISTS -1017
User name already exists in catalog.
The application has attempted to add to the system catalog a user that
has already been defined. No change has been made to the system
catalog.
S_USERLIMIT -1052
Maximum licensed users already logged on.
An attempt by the application to log into the server has been rejected.
The maximum number of licensed users that can log in has been reached.

S_USERMEMS -1030
Device has user members.
The application has attempted to delete a database device, but it has a
user definitions associated with it. The application must first either
delete the user definitions or associate them with a different database
device.
S_USERNAME -1001
Unable to locate user name.
The application has specified an unknown user name in a call to s_login.
S_VOIDTX 18
Cannot roll back a void transaction.
The application has attempted to roll back a transaction on a database
opened in no transaction mode.

19.2 SQL-Specific Return Codes
This section consists of three parts: general codes returned by Velocis SQL API functions
(SQL functions, SQL_ codes); detailed error codes that can be retrieved by the SQLError
function whenever SQL_ERROR or SQL_SUCCESS_WITH_INFO is returned by Velocis
SQL API functions (err codes); and codes returned by Velocis SQL value manipulation
functions (BCD and VAL functions, VAL_ codes).
19.2.1 General Codes Returned by SQL Functions

All Velocis SQL API functions return the short integer status codes described in
alphabetical order below. If the application receives SQL_ERROR or
SQL_SUCCESS_WITH_INFO, it can call SQLError for additional information. The
detailed codes written by SQLError are listed in section 19.2.2.
SQL_ERROR -1
An SQL error was detected.
The application has generated an SQL error. Check SQLError for more
specific failure information (see section 19.2.2).
SQL_INVALID_HANDLE -2
Null statement or connection handle.
A function has failed due to an invalid environment, connection, or
statement handle. This code only results from a programming error. No
further information is available from SQLError.
SQL_NEED_DATA 99
SQLExecute has encountered an execution-time parameter.
In a call to SQLExecute or SQLExecDirect, there were
SQL_DATA_AT_EXEC parameters specified for the statement being
executed. The application now needs to send the data using
SQLParamData and SQLPutData.
SQL_NO_DATA_FOUND 100
No data found.
The SQLFetch function has returned all rows from the result table.
SQL_SUCCESS 0
Success.
The function has been completed successfully.

SQL_SUCCESS_WITH_INFO 1
Success with warning.
The function has been completed successfully, but a warning or
additional information is available.
SQL_ZERODIV -19
Division by zero attempted.
A function has attempted to divide by zero, which is an illegal operation.
19.2.2 Detailed Codes Retrieved by the SQLError Function

The detailed codes provided by SQLError are described in this section. Your application
can call this function for an explanation of an SQL_SUCCESS_WITH_INFO or
SQL_ERROR return code received from the Velocis SQL API.
The SQLError function copies to its sqlstate parameter a 5-character code that is based on
the Microsoft ODBC specification standard error codes. The first two characters of the
code comprise the error class, while the remaining characters represent the subclass.
In its rsqlcode parameter, SQLError returns a Velocis SQL-specific integer error code. This
code often provides more explanatory information on the original error than the ODBC
code does. These codes are described in numerical order according to this parameter.
The following table lists each SQLError return code in alphabetical order by its constant
name, along with its accompanying ODBC standard error code and Velocis SQL integer
error code:

Table 19-2. SQLError Detailed (err*) Return Codes Listed Alphabetically
Velocis Velocis ODBC/SAG Velocis Velocis ODBC/SAG
SQL Code SQL Name Code SQL Code SQL Name Code
4200 errACCESS 42000 15017 errDESCRANGE S1091
15027 errACCRANGE S1101 20028 errDIFFHDBC RX028
14039 errACTINDEX S0R09 15029 errDIRRANGE S1103
20004 errBADCODE RX004 2212 errDIVBY0 22012
14020 errBADCOLUMN S0020 20009 errDLLERR RX009
15016 errBADDATALEN S1090 15001 errDRVMEMORY S1001
20015 errBADDEVICE RX015 14021 errDUPCOLUMN S0021
14036 errBADFILTER S0R06 3800 errDUPCURSOR 3C000
3729 errBADFORMAT 37000 14041 errDUPDB S0R11
14032 errBADFUNC S0R02 14037 errDUPFILTER S0R07
2205 errBADLITERAL 22005 14033 errDUPFUNC S0R03
20014 errBADMOD RX014 14011 errDUPINDEX S0011
3743 errBADOUTERJOIN 37000 14031 errDUPPROC S0R01
14030 errBADPROC S0R00 14001 errDUPTABLE S0001
20019 errBADSYSCAT RX019 14035 errDUPUSER S0R05
14000 errBADTABLE S0000 14003 errDUPVIEW S0003
14034 errBADUSER S0R04 1201 errENVHANDLE 02002
1013 errCANCELASFREE 01S05 3731 errESCAPE 37000
15006 errCANCELED S1008 15011 errEXECUTED S1010
15013 errCANCELFIRST S1010 3704 errFCNARG 37000
20024 errCANTINST RX024 15021 errFCNRANGE S1095
2100 errCARDINALITY 21000 15008 errFCNSEQ S1010
3732 errCD_BADCOL 37000 15030 errFETCHTYPE S1106
3734 errCD_BADELTNAME 37000 20020 errIEF RX020
3738 errCD_HASCDATA 37000 15022 errINFORANGE S1096
3733 errCD_NOELTNAME 37000 2112 errINSERTCOLS 21S02
3735 errCD_NUMSUBS 37000 2111 errINSERTVALS 21S01
3737 errCD_SUBRANGE 37000 2300 errINTEGRITY 23000
3736 errCD_SUBTYPE 37000 15007 errINVARG S1009
4400 errCHECKOPT 44000 15035 errINVCONVERT S1C00
1002 errCHTRUNC 01004 15039 errINVOPNOW S1011
15012 errCLOSESERVER S1010 2800 errINVUSER 28000
15003 errCOLNUMBER S1002 20013 errLOADMOD RX013
15023 errCOLRANGE S1097 2227 errLONGVARLEN 22026
1202 errCONHANDLE 02002 3710 errMIXEDMODE 37000
15032 errCONRANGE S1108 14022 errNOCOLUMN S0022
3711 errCURMISMATCH 37000 20027 errNOCONNECT RX027
2400 errCURSTATE 24000 15015 errNOCURSOR S1015
2200 errDATA 22000 15037 errNODATANEEDED S1DE0
2204 errDATALOST 22003 14012 errNOINDEX S0012
2211 errDATETIMEOVF 22008 3739 errNOINDEXCOL 37000
3709 errDBAPK 37000 2228 errNOINDVAR 22002
3712 errDBAPKUPD 37000 3714 errNOPKUPD 37000
3705 errDBNOTOPEN 37000 1801 errNOSERVER 08001
3723 errDBNOTREFD 37000 14002 errNOTABLE S0002
20011 errDBUNAVAIL RX011 15034 errNOTCAPABLE S1C00

Table 19-2. SQLError Detailed (err*) Return Codes Listed Alphabetically (continued)
Velocis Velocis ODBC/SAG Velocis Velocis ODBC/SAG
SQL Code SQL Name Code SQL Code SQL Name Code
1702 errNOTCURSOR 07005 1811 errSERVER 08S01
3707 errNOTNULL 37000 3718 errSORTLIMIT 37000
1803 errNOTOPEN 08003 3719 errSORTSIZE 37000
14038 errNOTOPTIONAL S0R08 15005 errSQLTYPE S1004
2401 errNOTSELECT 24000 15002 errSRVMEMORY S1001
10099 errNOTSUPPORTED IM001 1802 errSRVOPEN 08002
20023 errNOTTEMP RX023 1804 errSRVREJECT 08004
3724 errNOTUPDATEABLE 37000 1203 errSTMTHANDLE 02002
14004 errNOVIEW S0004 20007 errSTMTLIMIT RX007
20001 errNULLPTR RX001 2201 errSTRTRUNC 22001
15025 errNULLRANGE S1099 3700 errSYNTAX 37000
2102 errNUMFCNARGS 21000 20999 errSYSTEM RX999
1701 errNUMPAR 07001 15028 errTABRANGE S1102
20010 errOPEN RX010 15036 errTBD S1C00
15009 errOPENHDBCS S1010 15038 errTIMEOUT S1T00
1012 errOPTCHANGED 01S02 2202 errTOOLONG 22001
15018 errOPTIONRANGE S1092 3722 errTOOMANYROWS 37000
20025 errOUTOFSPACE RX025 20008 errTRANSID RX008
3721 errPARAMREF 37000 2501 errTXACTIVE 25000
3730 errPARAMTYPE 37000 2502 errTXNOTACTIVE 25000
15041 errPARMTYPE S1105 2503 errTXSYNC 25000
15019 errPARNO S1093 15014 errTXTYPE S1012
3701 errPATTERN 37000 1703 errTYPEATTR 07006
15010 errPREPARED S1010 20016 errUDF RX016
20022 errPROCTEMPREF RX022 20018 errUDFNORESET RX018
15004 errPROGTYPE S1003 20017 errUDFNOVAL RX017
2203 errRANGE 22003 3706 errUNDEFDB 37000
20026 errREADONLY RX026 3716 errUNDEFFK 37000
3713 errREFPKUPD 37000 15026 errUNIQRANGE S1100
3728 errRESTRICT 37000 3715 errUNRELFK 37000
1011 errROWERROR 01S01 3708 errVALTYPE 37000
15031 errROWVALUE S1107 3725 errVIEWCOLS 37000
15020 errSCALE S1094 2101 errVIEWMISMATCH 21000
15024 errSCOPERANGE S1098 20021 errVIEWTEMPREF RX021
4001 errSERIAL 40001 3720 errWHERECALCS 37000
The remainder of this section lists the SQLError codes, sorted by Velocis numerical code.
Each description includes:
• Velocis SQL numeric code (for example, 1002).
• Velocis SQL constant name for the error (for example, errCHTRUNC).
• The ODBC/SAG code for the error (for example, 01004 for errCHTRUNC). Some of
the ODBC codes are not unique due to their lack of specificity. In contrast, the Velocis
SQL-specific codes are more specific. For example, Velocis SQL provides a number of
syntax error codes that parallel the ODBC code for all syntax errors (37000).

• The error message written by SQLError.
• A full description of the error.
The Velocis SQL API functions referenced in the following code descriptions are defined
in Chapter 12 of this manual. See the Velocis Language Guide for details of the Velocis SQL
language elements and built-in functions referenced in the code descriptions.
1002 errCHTRUNC 01004
Data truncation.
The SQLFetch function has retrieved a result column value larger than
the length of the host variable container to which it is bound. This code
is also returned by SQLDescribeCol, SQLGetData, and
SQLGetCursorName to indicate that the host buffer is not large enough
to contain the requested column identifier or cursor name. The
SQLPutData function also returns this code to indicate that the user-
specified value is larger than required by the parameter.
1011 errROWERROR 01S01
Error in row.
A truncation error has occurred in one or more of the rows returned by
SQLExtendedFetch.
1012 errOPTCHANGED 01S02
Unsupported option - value changed to default.
An option has been specified in a call to SQLSetConnectOption or
SQLSetStmtOption that is not currently supported in Velocis.
1013 errCANCELASFREE 01S05
Cancel treated as FreeStmt/Close.
A call to SQLCancel has been treated as
SQLFreeStmt(hstmt, SQL_CLOSE). You should use SQLFreeStmt, not
SQLCancel, to close a cursor.
1201 errENVHANDLE 02002
Invalid environment handle.
The environment handle passed to SQLAllocConnect, SQLFreeEnv,
SQLTransact, or SQLExtendedTransact is not valid. The application
must call SQLAllocEnv before calling SQLAllocConnect.
1202 errCONHANDLE 02002
Invalid connection handle.
The application has passed a server connection handle to an SQL API
function. The function returns this code to indicate that the connection
handle has not been allocated.

1203 errSTMTHANDLE 02002
Invalid statement handle.
The application has specified a null statement handle. The application
must call SQLAllocStmt to allocate a valid statement handle.
1701 errNUMPAR 07001
Insufficient number of parameters specified.
The application has attempted to call SQLExecute or SQLExecDirect
before all of the needed parameter values have been set.
1702 errNOTCURSOR 07005
Prepared statement is not a valid cursor.
The application has submitted a select statement that is not a valid cursor
specification. A valid cursor specification is any select statement that
references a single table and does not have a group by or an order by
clause.
1703 errTYPEATTR 07006
Data value cannot be converted to C type.
1801 errNOSERVER 08001
Unable to connect to specified server.
The SQLConnect function cannot connect to the specified server because
it is not available on the network.
1802 errSRVOPEN 08002
Connection is in use.
The SQLConnect function has discovered that the connection to the
specified server has already been made.
1803 errNOTOPEN 08003
Connection is not open.
The application has called a Velocis SQL API function with a handle to
an unopened connection. The application must call SQLConnect.
1804 errSRVREJECT 08004
Connection timeout - retry.
The server has timed out while attempting to process the connection
request. The application should wait a few seconds and try again.
1811 errSERVER 08S01
Communication link failure.
The SQL support module has encountered an error while interacting
with the server. Either there is a network error or the server computer is
down.

2100 errCARDINALITY 21000
Cardinality violation.
The expected number of list items is incorrect.
2101 errVIEWMISMATCH 21000
Number of view columns does not match select.
The number of view column alias names does not equal the number of
select statement result columns.
2102 errNUMFCNARGS 21000
Incorrect number of function arguments.
The number of parameters being passed to a Velocis SQL UDP is
incorrect.
2111 errINSERTVALS 21S01
Insert value list does not match column list.
The number of specified values does not match the number of specified
columns in the insert statement.
2112 errINSERTCOLS 21S02
Degree of table does not match column list.
The number of named columns in the insert statement does not match
the number of columns declared in the table.
2200 errDATA 22000
Data exception.
Errors have been found in data values retrieved from a result set.
2201 errSTRTRUNC 22001
String truncated.
The string value specified in the insert or update statement has been
truncated.
2202 errTOOLONG 22001
String too long or missing ending quote.
The string value specified in the insert or update statement is longer than
allowed for the specified column.
2203 errRANGE 22003
Numeric value out of range.
A numeric conversion has been requested in which the destination data
type is too small to contain the source value (for example, converting a
long integer that is larger than 65,535 into an unsigned short integer).

2204 errDATALOST 22003
Significant data lost due to truncation.
The requested data conversion to string has resulted in a loss of
significant data, because the result string buffer is not large enough.
2205 errBADLITERAL 22005
Invalid literal string.
An ODBC literal escape sequence has not been properly formulated.
2211 errDATETIMEOVF 22008
Invalid date/time value.
An invalid date value has a month value greater than 12 or a day value
greater than the number of days in the specified month. An invalid time
value has an hour greater than 23 and minutes or seconds greater than
59.
2212 errDIVBY0 22012
Division by zero.
A division by zero has occurred during evaluation of an expression in the
current statement.
2227 errLONGVARLEN 22026
Insufficient parameter data sent for long var.
You have called SQLParamData before all of the long varchar/varbinary
parameter data has been sent through calls to SQLPutData.
2228 errNOINDVAR 22002
Indicator variable required but not supplied.
The SQLFetch or SQLExtendedFetch function has fetched NULL data
into a column whose outlen parameter (as previously set by
SQLBindCol) is a null pointer. This code is also returned by
SQLGetData when NULL data has been retrieved and the actualOutLen
parameter in that function is a null pointer.
2300 errINTEGRITY 23000
Integrity constraint violation: <name>.
A DDL-specified integrity constraint has been violated. A referential
integrity violation occurs when the primary key referenced by a foreign
key value does not exist. A unique integrity violation occurs when an
attempt is made to add a duplicate primary or unique key value to a
table. A check integrity violation occurs when a check clause for a table
or column or a with check option specification for a view evaluates to
FALSE. If the check integrity violation is caused by a UDF trigger
function, the error message includes: "denied by UDF in check clause".

2400 errCURSTATE 24000
Invalid cursor state.
The cursor state of the select statement is not valid for the requested
operation. For example, if the application tries to call SQLFetch before it
calls SQLExecute, it receives this error.
2401 errNOTSELECT 24000
Statement type is not select.
The application can only call the specified function with a handle that
corresponds to a select statement.
2501 errTXACTIVE 25000
A transaction is already active.
The application has attempted to begin a transaction when another
transaction is active (that is, has not yet been committed or rolled back)
for the same connection.
2502 errTXNOTACTIVE 25000
No transaction is active.
A commit or rollback operation has been attempted when there is no
active transaction.
2503 errTXSYNC 25000
Transaction out of sync between sql and server.
The transaction state as interpreted by the Velocis SQL API is different
from the state that the server interprets. This situation can only occur
when the application calls the Core (d_) API while performing SQL-
based transaction operations to start or end the transaction associated
with the connection.
2800 errINVUSER 28000
Invalid user authorization.
The specified user name and password combination are not valid for the
specified server.
3700 errSYNTAX 37000
Syntax error: <supplementary information>.
The Velocis SQL statement contains a syntax error. Supplementary
information contained in the error message should help to isolate the
specific problem.
3701 errPATTERN 37000
Error in regular expression.
The like expression pattern must be a character string.

3704 errFCNARG 37000
Invalid function argument.
An asterisk (*) can only be specified with the count calculation function.
3705 errDBNOTOPEN 37000
Database not open.
The server cannot automatically open an SQL database. Another server
has probably opened the database in exclusive access mode.
3706 errUNDEFDB 37000
Undefined database: <name>.
The Velocis SQL system catalog, syscat, does not include a definition for
the referenced database.
3707 errNOTNULL 37000
Must specify value for column: <name>.
The DDL schema declares the named column as not null, so the insert
statement must define a non-null value for the column.
3708 errVALTYPE 37000
Incompatible value type for column: <name>.
The value type specified for the named column in the insert statement is
not compatible with the data type of the column.
3709 errDBAPK 37000
db_addr primary keys are auto-generated: <name>.
The insert statement incorrectly specifies the name of a rowid (db_addr)
primary key column in its column list. The Velocis SQL support module
automatically assigns a value to this column, so it cannot be specified in
an insert statement.
3710 errMIXEDMODE 37000
Incompatible data types in expression: <name>.
The data types of the operands for an arithmetic or relational operation
are not compatible.
3711 errCURMISMATCH 37000
Update/delete invalid on specified cursor.
The cursor specified in a positioned update or delete statement does not
correspond to an updateable select statement. For example, a select
statement containing a group by or order by clause is not updateable.

3712 errDBAPKUPD 37000
Updates to db_addr primary key not allowed: <name>.
An update statement has tried to assign a value to a rowid (db_addr)
primary key column. The Velocis SQL support module automatically
assigns a value to this column, so it cannot be specified in that statement.
3713 errREFPKUPD 37000
Non-zero references on primary/unique key: <name>.
The application has attempted to delete a row for which one or more
outstanding foreign key references are defined. The application must
first delete the references (either by modifying the foreign key values or
deleting the rows) before it can delete the row.
3714 errNOPKUPD 37000
Updates to primary/unique keys not allowed: <name>.
The referenced database does not maintain foreign key reference counts.
See the description of the disable references count clause of the
create database statement in the Velocis Language Guide.
3715 errUNRELFK 37000
Foreign key not related to specified table.
A foreign key specified in the thru clause of a path clause does not
reference a related table.
3716 errUNDEFFK 37000
Undefined foreign key.
A foreign key specified in the thru clause of a path clause is not defined.
3718 errSORTLIMIT 37000
Too many order by fields specified.
Too many fields are specified for an order by clause.
3719 errSORTSIZE 37000
Total length of sort fields exceeds limit.
The length of all columns in an order by clause exceeds 243 bytes.
3720 errWHERECALCS 37000
Aggregate functions not allowed in where.
The where clause cannot contain any references to the Velocis aggregate
functions sum, avg, min, max, or count.
3721 errPARAMREF 37000
Improper parameter marker placement.
A Velocis SQL statement contains a parameter marker that has been
placed incorrectly. See SQLBindParameter for details.

3722 errTOOMANYROWS 37000
Subquery must return only one row.
An unquantified subquery referenced in a comparison operation (that is,
a subquery containing no any or all clause) has retrieved more than one
row value. Since the result is compared to a single value, subqueries of
this type must only return one value.
3723 errDBNOTREFD 37000
Database not referenced in defining select.
The select statement defining a view does not reference the database
name qualifying the view name. A view can only be associated with a
database that it uses.
3724 errNOTUPDATEABLE 37000
View is not updateable.
The create view declaration that includes a with check option
specification does not specify an updateable view. This code is also
returned if an insert, update, or delete modification statement has been
issued for a non-updateable view.
3725 errVIEWCOLS 37000
View column list must be specified.
The application has not specified a view column list. This list must be
specified when any of the defining select statement column results
involve more than a simple column reference.
3728 errRESTRICT 37000
View dependencies exist, drop not allowed.
A drop view ... restrict statement has failed, because there are other
existing views that reference the view specified to be dropped.
3729 errBADFORMAT 37000
Invalid convert format: <name>.
The format specifier for the convert function is invalid.
3730 errPARAMTYPE 37000
Incompatible parameter type.
The data type of the parameter supplied to SQLBindParameter is
invalid.
3731 errESCAPE 37000
Escape clause syntax error.
The ODBC escape clause contains a syntax error.

3732 errCD_BADCOL 37000
Column must be of type c_data: <name>.
The named column is not of type c_data (defined in Chapter 18). Only
columns of type c_data can be passed into the c_data scalar function.
3733 errCD_NOELTNAME 37000
Must specify element name for column: <name>.
A c_data scalar function call does not include the structure element name
for the named c_data column declared as a structure field.
3734 errCD_BADELTNAME 37000
Column does not contain element name: <name>.
The element name specified for the c_data scalar function is not defined
in the column.
3735 errCD_NUMSUBS 37000
Incorrect number of subscripts on: <name>.
The number of subscripts specified in a c_data function call for the
specified name does not match the declared number of dimensions.
3736 errCD_SUBTYPE 37000
Subscript must be smallint value: <name>.
The subscript specified for a column or element name is not a value of
the smallint (short) type.
3737 errCD_SUBRANGE 37000
Subscript out of range: <name>.
The subscript value specified for a column or element name is outside
the declared array dimensions.
3738 errCD_HASCDATA 37000
Can’t modify tables containing c_data columns.
The Velocis SQL application has attempted to use an insert, update, or
delete statement to modify a table that contains c_data columns. These
modifications can only be made through calls to the Velocis Core API
(d_) functions.
3739 errNOINDEXCOL 37000
Column not contained in specified index: <name>.
A column specified with the "colname@indexname" syntax in the where
clause (used to force the optimizer to use the specified index) is not
contained in indexname.

3743 errBADOUTERJOIN 37000
This error appears if you created an outer join between two tables, and
the optimizer cannot access the second table from the first (outer joined)
table. This can happen if all of the following occur:
• No actual create join statement exists between the two tables in the
schema
• No index exists for the foreign key
• The outer join was performed on the primary key
For performance reasons, Velocis does not perform cross products on
multiple tables that are joined with an outer join. Thus, the optimizer
will be unable to access the second table from the first table. To provide
an alternative access method to the second table, add an index to that
table, or add a create join statement between the two tables to the
schema.
3800 errDUPCURSOR 3C000
Duplicate cursor name.
The cursor name passed to SQLSetCursorName has already been
assigned to another statement.
4001 errSERIAL 40001
Transaction terminated to prevent deadlock.
SQLExecute, SQLExecDirect, or SQLFetch has terminated processing,
because Velocis has automatically rolled back the transaction to prevent a
deadlock situation on the database server.
4200 errACCESS 42000
User access rights violation: <name>.
The specified user does not have the proper privileges to perform the
requested operation.
4400 errCHECKOPT 44000
’with check option’ violation.
The where clause of the view referenced in the insert or update
statement has evaluated to FALSE. The view has been created with with
check option specified, disallowing modifications that cause the where
clause to evaluate to FALSE.
10099 errNOTSUPPORTED IM001
Function not supported.
The Velocis SQL API does not support the ODBC function called by the
application.

14000 errBADTABLE S0000
Invalid table name: <name>.
The from clause of the select statement does not indicate the table name
specified in the referenced, qualified column name. This code can also be
returned if the table name specified with a foreign key in a thru clause of
a path clause does not contain the named foreign key.
14001 errDUPTABLE S0001
Duplicate table: <name>.
A base table with the specified name already exists in the referenced
database.
14002 errNOTABLE S0002
Table not found: <name>.
The referenced table does not exist.
14003 errDUPVIEW S0003
Duplicate view: <name>.
A view with the specified name already exists in the referenced database.
14004 errNOVIEW S0004
View not found: <name>.
The referenced view does not exist.
14011 errDUPINDEX S0011
Index already exists: <name>.
An index with the specified name already exists in the referenced
database.
14012 errNOINDEX S0012
Index not found: <name>.
The index specified in the activate index or deactivate index statement
does not exist.
14020 errBADCOLUMN S0020
Invalid column name: <name>.
The specified column has not been found in the Velocis SQL system
catalog, syscat.
14021 errDUPCOLUMN S0021
Column already exists: <name>.
The referenced column is already declared in the table or view.
14022 errNOCOLUMN S0022
Column not found: <name>.
The referenced column is not declared in the listed tables.

14030 errBADPROC S0R00
Invalid procedure name: <name>.
The specified procedure does not exist.
14031 errDUPPROC S0R01
Duplicate procedure name: <name>.
A procedure with the same name already exists.
14032 errBADFUNC S0R02
Invalid function: <name>.
The referenced UDF does not exist in the specified library.
14033 errDUPFUNC S0R03
Duplicate user-defined function name: <name>.
A UDF of the same name already exists.
14034 errBADUSER S0R04
Invalid user name: <name>.
The user name specified in a grant or revoke statement does not exist.
14035 errDUPUSER S0R05
Duplicate user name: <name>.
The user name specified in a grant or revoke statement already exists.
14036 errBADFILTER S0R06
Invalid filter: <name>.
The specified filter does not exist.
14037 errDUPFILTER S0R07
Duplicate filter name: <name>.
A filter of the specified name already exists.
14038 errNOTOPTIONAL S0R08
Index is not optional: <name>.
The specified index is required.
14039 errACTINDEX S0R09
Statement uses a deactivated optional index.
The stored procedure or view that is being used had an optional index in
its original execution plan, and that index is not currently active.
Activate the index and re-execute the statement.
14041 errDUPDB S0R11
Database already exists: <name>.
The database with the same name as the one you are attempting to create
already exists.

15001 errDRVMEMORY S1001
Insufficient memory on client.
The client workstation does not have enough memory for Velocis to
process the requested function.
15002 errSRVMEMORY S1001
Insufficient memory on server.
The server computer does not have enough memory to complete the
operation.
15003 errCOLNUMBER S1002
Column number out of range.
The column number passed to SQLBindCol, SQLGetData, or
SQLDescribeCol is not valid for the specified select statement. The
number should be between 1 and the number of result columns in the
selection list.
15004 errPROGTYPE S1003
Program type argument out of range.
The data type parameter is invalid.
15005 errSQLTYPE S1004
SQL data type argument out of range.
The SQL data type parameter is invalid.
15006 errCANCELED S1008
Operation canceled.
15007 errINVARG S1009
Invalid argument value.
A null handle or invalid option has been passed to the function.
15008 errFCNSEQ S1010
Function call sequence error.
The application has called the function out of sequence. Your application
must call one or more other functions before calling the function
returning this error. Consult the particular function description in this
manual for details.
15009 errOPENHDBCS S1010
Must free all connection handles first.
The application has called SQLFreeEnv before closing all open
connections.

15010 errPREPARED S1010
Statement not prepared.
The application has attempted to execute an uncompiled statement. It
must call SQLPrepare before calling SQLExecute. As an alternative, the
application can call SQLExecDirect to both compile and execute the
statement.
15011 errEXECUTED S1010
Statement has not been executed.
The application has used a handle for an unexecuted statement in a
function call. It must first execute the associated statement by calling
SQLExecute.
15012 errCLOSESERVER S1010
Connection not closed.
The application has called SQLFreeConnect before calling
SQLDisconnect.
15013 errCANCELFIRST S1010
Must call SQLCancel first.
The application has called a function without first calling SQLCancel to
stop statement processing.
15014 errTXTYPE S1012
Invalid transaction operation code.
The transaction type code passed to SQLTransact or
SQLExtendedTransact is invalid. For the correct codes, see the
descriptions of these functions.
15015 errNOCURSOR S1015
No cursor name available.
Cursors are only available for select statements that have been prepared.
15016 errBADDATALEN S1090
Invalid string or buffer length.
The application has supplied an invalid length value in an SQLBindCol,
SQLBindParameter, or SQLSetParam call.
15017 errDESCRANGE S1091
Descriptor type out of range.
15018 errOPTIONRANGE S1092
Option type out of range.

15019 errPARNO S1093
Parameter number out of range.
The application has supplied SQLBindParameter with a parameter value
that is out of range, based on the number of host references encoded in
the referenced statement.
15020 errSCALE S1094
Invalid scale value.
15021 errFCNRANGE S1095
Function type out of range.
15022 errINFORANGE S1096
Information type out of range.
15023 errCOLRANGE S1097
Column type out of range.
15024 errSCOPERANGE S1098
Scope type out of range.
15025 errNULLRANGE S1099
Nullable type out of range.
15026 errUNIQRANGE S1100
Uniqueness option type out of range.
15027 errACCRANGE S1101
Accuracy option type out of range.
15028 errTABRANGE S1102
Table type out of range.
15029 errDIRRANGE S1103
Direction option out of range.
15030 errFETCHTYPE S1106
Fetch type out of range.
15031 errROWVALUE S1107
Row value out of range.
15032 errCONRANGE S1108
Concurrency option out of range.
15034 errNOTCAPABLE S1C00
Driver not capable.
Velocis does not support the requested function.

15035 errINVCONVERT S1C00
Invalid conversion: <name>.
The data type conversion specified in an SQLBindCol,
SQLBindParameter, or SQLSetParam call is not valid.
15036 errTBD S1C00
Capability not yet implemented.
The function is not available in the current software release.
15037 errNODATANEEDED S1DE0
No data pending for execution values.
The application has not specified the parameter values needed for
execution. It should call SQLParamData to specify the required values.
15038 errTIMEOUT S1T00
Timeout expired: <name>.
The SQLExecute, SQLExecDirect, or SQLFetch function has timed out
while waiting for a resource to become available so that it can acquire a
lock.
15039 errINVOPNOW S1011
Invalid operation at this time.
The option request specified in a call to SQLSetConnectOption or
SQLSetStmtOption cannot be made at this time because of the current
state of the statement associated with the statement or connection handle.
15041 errPARMTYPE S1105
Invalid parameter type.
20001 errNULLPTR RX001
Unexpected NULL pointer.
20004 errBADCODE RX004
Invalid status/error code.
An invalid status/error code was returned from a UDP function.
20007 errSTMTLIMIT RX007
No more stmt handles available on server.
The server does not have sufficient memory for any additional statement
handles.
20008 errTRANSID RX008
Invalid transaction identifier.
The transaction identifier specified in the rollback or commit statement
does not match an active mark or begin statement.

20009 errDLLERR RX009
System error in SQL dynamic/shared library.
The Velocis server is unable to load SQL code (DLL). This error should
not occur if Velocis has been installed properly. Ask the system
administrator to reinstall the server, as described in the Velocis Installation
and Administration Guide.
20010 errOPEN RX010
Database already open: <name>.
The application cannot open one of the temporary internal Velocis SQL
databases.
20011 errDBUNAVAIL RX011
Database not available: <name>.
The indicated database is not available. Either the application has
requested exclusive access to the database or another application has
exclusive access. This error code can also occur when the SQL support
module cannot access the system catalog database. The application
should retry its database request after a few seconds.
20013 errLOADMOD RX013
Unable to load module: <name>.
The SQL support module is unable to load the DLL that contains the
referenced UDF module. Ask the system administrator to check the path
environment variable to ensure that the directory containing the module
is reflected in the library path of the host operating system.
20014 errBADMOD RX014
Invalid module for user-defined functions: <name>.
The SQL support module cannot load the DLL specified in the
create function statement. Ask the system administrator to check the
path environment variable to ensure that the directory containing the
module is reflected in the library path of the host operating system.
20015 errBADDEVICE RX015
Invalid device: <name>.
The specified device does not exist. Ask the system administrator to
register the device, according to instructions in the Velocis Installation and
Administration Guide.
20016 errUDF RX016
User-defined function error: <msg>.
The UDF referenced in the SQL statement is returning the specified error
message.

20017 errUDFNOVAL RX017
No result from user-defined function: <name>.
The UDF has not returned a result value, indicating that the function has
not been implemented correctly. All UDFs must return values.
20018 errUDFNORESET RX018
No reset callback for aggregate user-defined function.
The aggregate UDF does not have a reset function that re-initializes the
accumulation calculations for a new group. If no reset function is
needed, the UDF is a scalar function.
20019 errBADSYSCAT RX019
Unable to open system catalog.
The SQLConnect function cannot access the SQL system catalog, syscat.
The system administrator or another user probably has the system
catalog open in exclusive access mode.
20020 errIEF RX020
Filter error: <msg>.
The import/export filter referenced in the SQL statement is returning the
specified error message.
20021 errVIEWTEMPREF RX021
A view cannot reference temporary table: <name>.
The application has attempted to reference a temporary table in a view.
A view cannot reference temporary tables, because it is persistent, and
temporary tables are not. In addition, a temporary table is visible only to
one user, while multiple users can access a view.
20022 errPROCTEMPREF RX022
A procedure cannot reference temporary table: <name>.
The application has attempted to reference a temporary table in a UDP.
A UDP cannot reference temporary tables, because it is persistent, and
temporary tables are not. In addition, a temporary table is visible only to
one user, while multiple UDPs can access a view.
20023 errNOTTEMP RX023
Not a temporary table: <name>.
The application can only issue a dynamic drop table or create index
statement on a temporary table.
20024 errCANTINST RX024
Can’t create instance with foreign keys to other dbs: <name>.
20025 errOUTOFSPACE RX025
Out of space on disk.

20026 errREADONLY RX026
Database is in read-only mode.
20027 errNOCONNECT RX027
No client-side connection handle to connect with.
20028 errDIFFHDBC RX028
Statement handles are not associated with same connection.
The statement handles in an SQLShowPlan function call are not
associated with the same connection handle.
20999 errSYSTEM RX999
System error: <name>.
An internal system error has occurred.

19.2.3 Codes Returned by SQL Value Manipulation Functions
The status and error codes listed below are returned by the decimal value manipulation
functions (BCD prefix) and the date/time value manipulation functions (VAL prefix).
VAL_BADENV -5
Passed in a bad environment handle.
VAL_INVALID -6
Passed in a bad argument.
VAL_NOMEM -3
Allocation failed.
VAL_OKAY 0
Operation was successful.
VAL_OVERFLOW -11
Operation resulted in an overflow.
VAL_OVERLOSS -10
Operation resulted in both overflow and precision loss.
VAL_PRECLOSS -12
Operation resulted in precision loss.
VAL_TOOSMALL -4
Output buffer to small for result.

19.3 Error Messages Returned by the sddlp Utility
This section describes the messages that the SQL schema compiler (sddlp) can return.
These messages have been sorted in alphabetical order and include a more complete
explanation. Note that along with a message, sddlp reports the line and column number
of the position in the database schema file of the specific text producing error. Table 19-3
lists the error messages alone, then each message is described in the pages following the
table.
Table 19-3. sddlp Utility Error Messages

’(’ expected. Identifier is a Velocis SQL DML reserved word: <name>.
Bad function table entry for function udfname in UDF DLL: Illegal data type in expression ..
<dllname>. ’in’ clause is non-standard.
c_data columns not allowed in check() clause: <name>. Incorrect number of arguments.
c_data columns not allowed in create join: <name>. Index based on long BLOB ID number, not data.
c_data columns not allowed in foreign key: <name>. Index file already exists: <name>.
c_data columns not allowed in index: <name>. Index files cannot contain table data.
c_data columns not allowed in primary/unique key: <name>. Index name duplicates column name: <name>.
c_data is non-standard. Invalid argument type in UDF: <name>.
check() clause error. Invalid check specification.
check() clause undeclared column ref: <name>. Invalid conditional expression.
Column definition error. Invalid create index statement.
Column of unique/primary key cannot allow nulls: <name>. Invalid device: <name>.
CREATE DATABASE/SCHEMA AUTHORIZATION required. Invalid foreign key specification.
create file is non-standard. Invalid function.
create index is non-standard. Invalid join specification.
create join is non-standard. Invalid join member specification.
Database already exists (owner=username). Invalid primary key specification.
Database dbname is already registered with servername. Invalid unique specification.
Database does not exist: <name>. Join members must all reference the same table.
Database is non-standard alias for ’schema authorization’. Long varchar/varbinary columns cannot be primary/unique keys.
Database not available: <name>. Member table must have one (only) foreign key.
Database SYSCAT is reserved for Velocis SQL. Must specify sort columns for each member.
Decimal precision must be 1..max. Newline encountered inside a string literal.
Decimal scale must be 0..precision. No udfDescribeFcns defined UDF DLL: <name>.
Duplicate column: <name>. NOT NULL conflicts with default for.
Duplicate file name: <name>. Premature EOF: probably missing ’*/’.
Duplicate foreign key definition. Primary key already defined.
Duplicate join definition: <name>. Primary key cannot have a default of NULL on: <name>.
Duplicate table definition: <name>. Primary key must have unique index, table: <name>.
Duplicate unique/primary key definition. Primary key rowid columns not allowed in index.
Error in create file. Ref’d columns is not a unique/primary key.
File cannot contain BLOB data. Ref’d number of columns exceeds limit.
File cannot contain key data. Ref’ing number of columns exceeds limit.
File cannot contain table data. Reference to undeclared table/unique/primary key: <name>.
File is never used: <name>. Reference to undefined table: <name>.
File not found: <name>. Referenced (primary key) table must be declared before
File of same name already exists: <name>. CREATE JOIN.
Foreign key column does not match reference: <name>. References error.
Foreign key is member of another join. References to instd databases not allowed.
Foreign key not defined. rowid columns are non-standard.

Table 19-3. sddlp Utility Error Messages (continued)
ROWID should include PRIMARY KEY or REFERENCE. Undeclared user-defined function: <name>.
Sort column mismatch: <name>. Undefined column: <name>.
Sort columns needed only when order is sorted. Undefined device name: <name>.
Syntax error in CREATE TABLE statement. Undefined referenced column: <name>.
Syntax error in SQL DDL statement. Undefined referencing column: <name>.
SYSCAT inconsistency detected - SDDLP aborted. Undefined sort column: <name>.
System catalog currently unavailable for database: <name>. Undefined table: <name>.
Table does not contain column: <name>. Unequal number of ref’d/ref’ing columns.
Table does not have a primary key: <name>. Unequal number of sort columns.
Too many array dimensions specified. UNIQUE w/o NOT NULL is non-standard, NOT NULL assumed.
Unable to load UDF DLL: <name>. Unsupported data type: <name>.
Unable to open database to initialize new files.
’(’ expected.
You must enclose a check clause in parentheses.
Bad function table entry for function udfname in UDF DLL: <dllname>.
The function table entry for function "udfname" in the UDF DLL
("dllname") has a null address for the type checking function. See the
definition of udfCheck.
c_data columns not allowed in check() clause: <name>.
You cannot reference columns of c_data type in a check clause.
c_data columns not allowed in create join: <name>.
You cannot reference columns of c_data type in a create join statement.
c_data columns not allowed in foreign key: <name>.
You cannot reference columns of c_data type in a foreign key.
c_data columns not allowed in index: <name>.
You cannot reference columns of c_data type in an index.
c_data columns not allowed in primary/unique key: <name>.
You cannot reference columns of c_data type in a primary or unique key.
c_data is non-standard.
check() clause error.

A syntax error exists in the specified check clause.
check() clause undeclared column ref: <name>.
You have not declared the referenced column in the table. It is probably
misspelled.
Column definition error.
A column declaration is improperly formulated.

Column of unique/primary key cannot allow nulls: <name>.
The columns that constitute a unique or primary key must specify
not null.
CREATE DATABASE/SCHEMA AUTHORIZATION required.
The Velocis SQL DDL schema does not have a create database statement
as the first statement in the file.
create file is non-standard.
The create file statement is invalid.
create index is non-standard.
The create index statement is invalid.
create join is non-standard.
The create join statement is invalid.
Database already exists (owner=username).
A database with the same name already exists in the Velocis SQL system
catalog, syscat. If you are upgrading the schema for an existing database,
use the -u command-line option for the sddlp utility.
Database dbname is already registered with servername.
The database name in the create database statement has already been
registered with the server. This message is intended to protect any
existing Core database that has the same name as the one you have
specified for the SQL database. If you are simply using sddlp to create
an SQL version of an existing Velocis database, use the -o command-line
option.
Database does not exist: <name>.
The referenced database does not exist ("... references dbname.table...").
Database is non-standard alias for ’schema authorization’.
Database not available: <name>.

The database referenced in a create table statement does not match the
database set up by the associated create database statement.
Database SYSCAT is reserved for Velocis SQL.
The application cannot specify a database named syscat in a
create database statement.

Decimal precision must be 1..max.
The specified decimal precision is out of range. The valid range is given
in the error message. The system administrator can change the
maximum decimal precision by adjusting an SQL configuration
parameter, as described in the Velocis Installation and Administration
Guide.
Decimal scale must be 0..precision.
The scale must be within the specified range.
Duplicate column: <name>.
You have already declared a table column with the same name.
Duplicate file name: <name>.
You have already specified the file name in a previous create file
statement.
Duplicate foreign key definition.
You have declared two foreign keys containing the same columns.
Duplicate join definition: <name>.
You have already issued a create join statement for the same name.
Duplicate table definition: <name>.
You have already specified the table name in a previous create table
statement.
Duplicate unique/primary key definition.
You have declared two unique/primary keys containing the same
columns.
Error in create file.
The create file statement has been incorrectly formulated.
File cannot contain BLOB data.
A create file statement has been specified to contain long varchar or
long varbinary column data ("BLOB" stands for "binary large object")
which is also used to contain data from a table or an index.
File cannot contain key data.
A create file statement has been specified to contain index data which is
also used to contain data from a table or a long varchar or
long varbinary column.
File cannot contain table data.
A create file statement has been specified to contain table data which is
also used to contain data from an index or a long varchar or
long varbinary column.

File is never used: <name>.
You have issued a create file statement that does not reference any tables
or indexes.
File not found: <name>.
You have not issued a create file statement for the specified file name.
File of same name already exists: <name>.
Table names must be distinct from file names (create file).
Foreign key column does not match reference: <name>.
The column does not match the referenced primary key in type and
length.
Foreign key is member of another join.
You can define only one join for any given foreign key.
Foreign key not defined.
There is no foreign key that corresponds to the columns specified in the
create join statement.
Identifier is a Velocis SQL DML reserved word: <name>.
Words that represent any part of the SQL language cannot be used as
names. Examples are table, view, column, index, join, and file.
Illegal data type in expression ..
The data type of an operand in the identified operation of a check clause
is not valid for that operation.
’in’ clause is non-standard.
Incorrect number of arguments.

An incorrect number of parameters is listed in the call to the specified
scalar function.
Index based on long BLOB ID number, not data.
This is a warning message that indicates that an index created on a
long varchar or long varbinary column is based on the BLOB ID value
and not on the BLOB data itself.
Index file already exists: <name>.
You have already issued a create index statement for a file with the same
name.
Index files cannot contain table data.
Both an index and a table are contained in the same file. You can only
use a create file statement to create a file containing data of one type
(table row or index entry).

Index name duplicates column name: <name>.
An index name must differ from column names in the associated table.
Invalid argument type in UDF: <name>.
The application is passing a parameter with an incorrect data type to the
UDF referenced in the check clause.
Invalid check specification.
There is a syntax error in the formulation of the check clause.
Invalid conditional expression.
There is a syntax error in the formulation of the conditional expression.
Invalid create index statement.
There is a syntax error in the formulation of the create index statement.
Invalid device: <name>.
The specified device does not exist. Ask the system administrator to
define the device properly, as instructed in the Velocis Installation and
Administration Guide.
Invalid foreign key specification.
There is a syntax error in the formulation of the foreign key clause.
Invalid function.
The UDF referenced in the check clause does not exist.
Invalid join specification.
There is a syntax error in the formulation of the create join statement.
Invalid join member specification.
There is a syntax error in the formulation of the on or and clause of the
create join statement.
Invalid primary key specification.
There is a syntax error in the formulation of the primary key clause.
Invalid unique specification.
There is a syntax error in the formulation of the unique clause.
Join members must all reference the same table.
The tables referenced by the foreign keys specified in the and clause of
the create join statement must be identical.
Long varchar/varbinary columns cannot be primary/unique keys.
Member table must have one (only) foreign key.

You can only define one foreign key for a table when specifying a table
name alone (without listing foreign key columns).

Must specify sort columns for each member.
One of the and clauses does not list the sort columns, even though the
order is sorted.
Newline encountered inside a string literal.
String literals cannot span across text lines.
No udfDescribeFcns defined UDF DLL: <name>.
The listed DLL module does not contain a function called
udfDescribeFcns.
NOT NULL conflicts with default for.
You have used a null default for a column specified with a not null
clause.
Premature EOF: probably missing ’*/’.
The sddlp utility has unexpectedly reached the end of the schema file.
This error often occurs because you have failed to terminate a comment
properly.
Primary key already defined.
You can only declare one primary key for a particular table.
Primary key cannot have a default of NULL on: <name>.
Primary and unique keys cannot have null values.
Primary key must have unique index, table: <name>.
The index for the primary key must be unique. Specify the unique
attribute with the create index statement.
Primary key rowid columns not allowed in index.
Indexes on a rowid primary key are unnecessary and are not allowed.
Ref’d columns is not a unique/primary key.
The column referred to in a references or foreign key clause does not
correspond to a unique or primary key.
Ref’d number of columns exceeds limit.
A referenced foreign/unique/primary key can consist of up to eight
columns.
Ref’ing number of columns exceeds limit.
A referencing foreign/unique/primary key can consist of up to eight
columns.
Reference to undeclared table/unique/primary key: <name>.
You have not declared the specified table, or the table does not contain a
matching primary or unique key.

Reference to undefined table: <name>.
The referenced table does not exist in the specified database
("... references dbname.table...").
Referenced (primary key) table must be declared before CREATE JOIN.
You have issued a create join statement referencing a foreign key to an
undeclared table that is to contain the referenced primary key. You must
declare both referencing and referenced tables before issuing the create
join statement.
References error.
There is a syntax error in the formulation of the references clause.
References to instd databases not allowed.
Foreign keys cannot be declared that refer to databases that have
multiple instances.
rowid columns are non-standard.
ROWID should include PRIMARY KEY or REFERENCE.

Rowid columns must either be declared as a primary key or as a foreign
key.
Sort column mismatch: <name>.
You have specified mismatched sort columns. The sort columns
specified for each and clause must match in type and length.
Sort columns needed only when order is sorted.
You only need to specify sort columns when the create join order is
sorted.
Syntax error in CREATE TABLE statement.
The create table statement has been incorrectly formulated.
Syntax error in SQL DDL statement.
The Velocis SQL DDL statement has been incorrectly formulated.
SYSCAT inconsistency detected - SDDLP aborted.
The sddlp utility has encountered unexpected results from an attempted
access of the SQL system catalog (syscat). The syscat database probably
needs to be reinstalled.
System catalog currently unavailable for database: <name>.
The specified database is currently in use. If you want to update the
schema for the database, ensure that other users are not using the
database.

Table does not contain column: <name>.
The column listed in a unique or primary key clause has not been
declared in the table.
Table does not have a primary key: <name>.
The referenced table does not have a primary (or unique) key declared
("... references tabname").
Too many array dimensions specified.
The maximum number of array dimensions for a c_data column is three.
Unable to load UDF DLL: <name>.
The sddlp utility cannot load the DLL containing the referenced UDF.
This message can indicate that the DLL has not been built. Another
interpretation of the message is that Velocis cannot find the DLL in the
location specified by the device.
Unable to open database to initialize new files.
The SQL support module cannot open the database to initialize new files
that are being added during a database upgrade.
Undeclared user-defined function: <name>.
A check clause is referencing a UDF for which you have not submitted a
create function statement. The utility needs to load the UDF so that it
can call the udfCheck function during compilation of the check clause
that references the UDF. Before you can reference the UDF, you must
prepare it as described in Chapter 12 of the Velocis User’s Guide, then use
the rsql utility to issue a create function statement for the UDF. After
this, you can run sddlp on a schema that references the UDF.
Undefined column: <name>.
The column specified in the create index statement does not exist in the
table.
Undefined device name: <name>.
The name specified for a device in an on clause does not exist for the
database server. Ask the system administrator to create the device, as
described in the Velocis Installation and Administration Guide.
Undefined referenced column: <name>.
The referenced column does not exist ("... references tabname(colname)").
The column name listed in the create join statement does not exist.
Undefined referencing column: <name>.
The application has not declared for the table a foreign key (or
references) clause that corresponds with the column name(s) specified in
a foreign key column list of the create join statement.

Undefined sort column: <name>.
The column specified in the create join is not defined in the table.
Undefined table: <name>.
The table specified in the create index or create join statement does not
exist.
Unequal number of ref’d/ref’ing columns.
The columns of a foreign key must match exactly with the columns of a
unique or primary key that the foreign key references.
Unequal number of sort columns.
The sort columns specified for each and clause must match in number.
UNIQUE w/o NOT NULL is non-standard, NOT NULL assumed.
According to the ANSI standard, unique keys must also be specified
with the not null clause. Velocis displays this message when a unique
key is declared that includes columns that are missing the not null
clause.
Unsupported data type: <name>.
Velocis SQL does not support the specified data type.

Index
s_dbUserAdd 11-33
A
s_dbUserDel 11-34
adding parameter list items 9-14 s_dbUserGet 11-35
adding structures to parameter lists 9-17 s_dchainBegin 11-37
adding binary-coded decimals 3-2 s_devAdd 11-39
adding multiple parameter list items s_devAddEx 11-40
9-12 s_devDel 11-41
adding ODBC data sources 2-22 s_devGet 11-42
adding SQL values (from server-side s_devGetEx 11-43
UDF) 13-11 s_devModify 11-44
admin utility (Windows only) s_devModifyEx 11-45
registering a database 19-6 s_emAdd 11-46
summary 2-2 s_emDel 11-47
administering databases s_emGet 11-48
on multiple platforms 2-28 s_emModify 11-49
on Windows 2-2 s_endRPCThreads 11-50
administration API functions s_errinfo 11-51
overview 11-1 s_fileAddExt 11-52
s_backupAttach 11-2 s_fileInfo 11-53
s_backupBegin 11-3 s_fileMove 11-54
s_backupCacheGet 11-4 s_fileRecv 11-55
s_backupCacheSet 11-5 s_fileSend 11-56
s_backupDetach 11-6 s_fileSetSizes 11-57
s_backupEnd 11-7 s_fileTotals 11-58
s_backupFlush 11-8 s_getDiskFreeSpace 11-59
s_backupFreeFile 11-9 s_getTimeout 11-60
s_backupKill 11-10 s_iniGet 11-61
s_dbAdd 11-11 s_iniGetPrivate 11-63
s_dbcheckBegin 11-13 s_iniSet 11-65
s_dbClone 11-16 s_iniSetPrivate 11-66
s_dbdefragBegin 11-19 s_keybuildBegin 11-67
s_dbDel 11-20 s_log 11-69
s_dbfixBegin 11-22 s_login 11-70
s_dbGet 11-25 s_logout 11-71
s_dbInit 11-26 s_ping 11-72
s_dbInitfile 11-27 s_setMinFreeSpace 11-74
s_dbModify 11-28 s_setTimeout 11-75
s_dbrEnd 11-29 s_showBackupFiles 11-76
s_dbrGetStatus 11-30 s_showDbFiles 11-78
s_dbstat 11-32
Centura Velocis Reference Manual Index-1

s_showDbs 11-80 allocating resource manager memory
s_showDbUsers 11-81 10-44
s_showDevs 11-83 allocating tag memory for copied strings
s_showEms 11-84 10-65
s_showUserDbs 11-85 analyzing databases 2-15
s_showUsers 11-87 arguments See parameters 1-3
s_shutdown 11-88 array fields, reading 6-39
s_startRPCThreads 11-89 AttachFailure status code 17-1
s_startup 11-91 attaching extension modules to Velocis
s_statistics 11-94 clients 7-2
s_terminate 11-98
B
s_userAdd 11-99
s_userDel 11-100 B_CURRENT 6-6
s_userGet 11-101 B_END 6-6
s_userModify 11-102 B_START 6-6
s_version 11-103 backing up the server
structures attaching 11-2
database definition (dbase) 18-10 detaching 11-6
database file registration ending 11-7
(FILEDEV) 18-15 flushing 11-8
database registration (DBD_DBF) freeing backup files 11-9
18-11 getting the number of hot file index
device definition (device) 18-12 pages 11-4
extension module registration killing 11-10
(EM_CHG) 18-13 setting the number of hot file index
user information and device pages 11-5
(USERINF_CHG) 18-26 starting 11-3
user information (userinf) 18-25 backup restoration utility 2-13
administration utility BCD_HENV data type 3-1, 18-4
for multiple platforms 2-28 BCD_Z structure 3-1, 18-4
for Windows 2-2 BCDAdd function 3-2
aggregate SQL UDFs, resetting running BCDAllocEnv function 3-3
values for 14-11 BCDAllocZBuf function 3-4
aliases, printing 2-39 BCDCompare function 3-5
allocating binary-coded decimal BCDDivide function 3-6
environment handles 3-3 BCDFreeEnv function 3-7
allocating cleared resource manager BCDFreeZBuf function 3-8
memory blocks 10-5 BCDMultiply function 3-9
allocating dynamic memory pools 10-2 BCDPack function 3-10
allocating dynamic memory tags 10-3 BCDs See binary-coded decimals
allocating memory for binary-coded BCDStatus function 3-11
decimal buffers 3-4 BCDSubtract function 3-12
allocating parameter lists 9-2 BCDUnpack function 3-13
Index-2 Centura Velocis Reference Manual

BCDZLEN macro 3-4 reading 6-4
BEGIN_RPC_MAP macro 17-26 writing 6-9
beginning operating system threads buffers, packed decimal, calculating
10-80 sizes of 3-4
binary-coded decimal functions
C
BCDAdd 3-2
BCDAllocEnv 3-3 C data column handles
BCDAllocZBuf 3-4 allocating 12-2
BCDCompare 3-5 freeing 12-49
BCDDivide 3-6 c_db_name function 4-2
BCDFreeEnv 3-7 c_fd_dim function 4-3
BCDFreeZBuf 3-8 c_fd_flags function 4-4
BCDMultiply 3-9 c_fd_idx function 4-5
BCDPack 3-10 c_fd_key function 4-6
BCDStatus 3-11 c_fd_keyfile function 4-7
BCDSubtract 3-12 c_fd_keyno function 4-8
BCDUnpack 3-13 c_fd_len function 4-9
binary-coded decimals c_fd_name function 4-10
adding 3-2 c_fd_rec function 4-11
allocating environment handles 3-3 c_fd_size function 4-12
allocating memory buffers 3-4 c_fd_type function 4-13
checking for overflow 3-11 c_field_offset function 4-14
checking for precision loss 3-11 c_freedict function 4-1, 4-15
comparing (in string format) 3-5 c_ft_name function 4-16
dividing 3-6 c_ft_slots function 4-17
freeing handles 3-7 c_ft_type function 4-18
freeing memory buffers for 3-8 c_kt_field function 4-19
multiplying 3-9 c_kt_key function 4-20
packing (converting to from string) c_kt_ptr function 4-21
3-10 c_mt_record function 4-22
subtracting 3-12 c_mt_sort_fld function 4-23
unpacking (converting to string) 3-13 c_mt_totsf function 4-24
BLOB data c_rec_len function 4-25
and d_recwrite 6-112 c_rt_fdtot function 4-26
data types 18-2 c_rt_fields function 4-27
deleting 6-2 c_rt_file function 4-28
enabling/disabling logging 6-3 c_rt_flags function 4-29
finding current byte offset positions c_rt_idx function 4-30
6-8 c_rt_name function 4-31
finding positions 6-6 c_se_fld function 4-32
finding sizes 6-7 c_size_fd function 4-33

c_size_ft function 4-34 changing item currency in parameter
c_size_kt function 4-35 lists 9-20
c_size_mt function 4-36 chapter summaries 1-1
c_size_rt function 4-37 checking binary-coded decimals for
c_size_srt function 4-38 overflow 3-11
c_size_st function 4-39 checking binary-coded decimals for
c_st_flags function 4-40 precision loss 3-11
c_st_idx function 4-41 checking data types in SQL import and
c_st_members function 4-42 export filter parameters 8-2
c_st_memtot function 4-43 checking data types in SQL UDF
c_st_name function 4-44 parameters 14-2
c_st_order function 4-45 checking data types in SQL UDP
c_st_own_rt function 4-46 parameters 15-2
C++ classes checking database consistency 2-3
DataDescriptor 17-1 checking for existence of resource
ParmReceive 17-4 manager files 10-35
ParmSend 17-9 checkpoints, forcing 6-10
SeBase 17-12 class hierarchy, server extension toolkit
ServerExtension 17-17 17-1
C++ classes, server extension toolkit classes, server extension toolkit 17-1
17-1 cleaning up after SQL UDF modules
C++ constructors See constructors, C++ 14-4
C++ data types, correlating with DPL cleaning up after SQL UDP modules
data types 17-5 15-4
C++ destructors See destructors, C++ cleaning up extension modules 7-15
C++ macros 17-26 cleaning up SQL import and export
C++ member functions See methods, filters 8-4
C++ cleaning up the resource manager 10-6
C++ methods See methods, C++ client library 19-15
C++ operators See operators, C++ client utilities
C++ server extension toolkit See server admin (Windows only) 2-2
extension toolkit dbcheck 2-3
calculating packed decimal buffer sizes dbdefrag 2-5
3-4 dbfix 2-7
caldefs.h header file 16-1 dbimp 2-9
calling extension modules 7-4 dbreplay 2-13
Centura Software Corporation dbstat 2-15
Books Online 1-5 dchain 2-17
Web home page 1-6 ddlproc 2-19
changing signs of SQL values (from instodbc 2-22
server-side UDF) 13-12 keybuild 2-24

logging in automatically 2-1 converting database addresses to row
prdbd 2-26 identifiers 13-2
rdsadm 2-28 converting row identifiers to database
rsql 2-29 addresses 13-9
sddlp 2-37 converting SQL value types (from
vping 2-39 server-side UDF) 13-14
closing resource manager files 10-11 converting strings to binary-coded
closing resource manager stream files decimals 3-10
10-28 copying resource manager files 10-12
CMLOCK lock mode indicator 18-16 Core API functions
cmpDescribeFcns function 5-2 d_blobdelete 6-2
cmpFunction function 5-4 d_bloblog 6-3
CMPLOADTABLE structure 5-1, 5-2, d_blobread 6-4
18-8 d_blobseek 6-6
cmpShutdown function 5-6 d_blobsize 6-7
codes, return See return codes d_blobtell 6-8
COLOCK lock mode indicator 18-16 d_blobwrite 6-9
comparing binary-coded decimals (in d_checkpoint 6-10
string format) 3-5 d_close 6-11
comparing SQL values (from server-side d_cmfree 6-12
UDF) 13-13 d_cmlock 6-13
compiling Core DDL database schemas d_cmtype 6-15
2-19 d_cofree 6-16
compiling Velocis SQL database d_colock 6-17
schemas 2-37 d_connect 6-18
compound data types See structures d_cotype 6-19
compressing data files 2-5 d_crfree 6-20
connection handles, allocating 12-3 d_crget 6-21
consistency checking, database 2-3 d_crlock 6-22
constants d_crread 6-23
DB_ADDR_SIZE 18-3 d_crset 6-24
LITERAL_NULL_DBA 18-3 d_crslock 6-25
low-level 18-3 d_crtype 6-27
NULL_DBA 18-3 d_crwrite 6-28
constructors, C++ d_csfree 6-30
DataDescriptor::DataDescription 17-2 d_cslock 6-31
SeBase::SeBase 17-13 d_csmget 6-33
ServerExtension::ServerExtension d_csmread 6-34
17-17 d_csmset 6-35
conventions, notational 1-5 d_csmwrite 6-36
converting binary-coded decimals to d_csoget 6-38
strings 3-13 d_csoread 6-39

d_csoset 6-40 d_open 6-91
d_csowrite 6-41 d_pkeyfind 6-93
d_curkey 6-43 d_pkeynext 6-95
d_dbafree 6-44 d_pkeyprev 6-97
d_dbalock 6-45 d_rdcurr 6-99
d_decode_dba 6-47 d_rdlockmodes 6-101
d_delete 6-48 d_recfrst 6-103
d_dict 6-49 d_reclast 6-104
d_discon 6-50 d_recnext 6-105
d_disdel 6-51 d_recprev 6-106
d_encode_dba 6-52 d_recread 6-107
d_errinfo 6-53 d_recseqno 6-110
d_fillnew 6-54 d_recset 6-108
d_findco 6-56 d_recsetat 6-109
d_findfm 6-57 d_rectot 6-111
d_findlm 6-58 d_recwrite 6-112
d_findnm 6-59 d_release 6-114
d_findpm 6-60 d_reset_dberr 6-115
d_fldcmp 6-61 d_rtfree 6-116
d_getDD 6-62 d_rtlock 6-117
d_grplock 6-65 d_set_dberr 6-119
d_iclose 6-67 d_setkey 6-121
d_iopen 6-68 d_setmm 6-122
d_ismember 6-69 d_setmo 6-123
d_isowner 6-70 d_setmr 6-124
d_keydel 6-71 d_setom 6-125
d_keydir 6-72 d_setoo 6-126
d_keyexist 6-74 d_setor 6-127
d_keyfind 6-75 d_setrm 6-128
d_keyfrst 6-76 d_setro 6-129
d_keylast 6-77 d_showLocks 6-130
d_keynext 6-78 d_showOwners 6-131
d_keyprev 6-79 d_stfree 6-132
d_keyrdstate 6-80 d_stlock 6-133
d_keyread 6-81 d_taskinfo 6-135
d_keystore 6-82 d_timeout 6-136
d_keyszstate 6-83 d_trabort 6-137
d_keywrstate 6-84 d_tractive 6-138
d_locklimit 19-14 d_trbegin 6-139
d_makenew 6-85 d_trend 6-141
d_members 6-86 d_trmark 6-142
d_nullset 6-87 d_trrollback 6-143
d_nulltest 6-89 d_unset_dberr 6-145

d_wrcurr 6-146 getting database addresses 6-38
group lock request packet structure getting record types 6-19
(GROUPLOCK) 18-16 requesting record instance locks 6-17
overview 6-1 setting database addresses 6-40
Core database schema compiling utility writing to fields 6-41
2-19 current records
counting the number of parameter list copying fields 6-23
items 9-4 deleting 6-51
create database instance statement and disconnecting 6-51
s_dbClone 11-16 finding owners 6-56
CREATE_EXPORTS macro 17-26 freeing instance locks 6-20
creating dynamic memory tags 10-7 getting database addresses 6-21
creating queues 10-54 getting record types 6-27
creating semaphores 10-66 locks 18-16
CRLOCK lock mode indicator 18-16 if member of set 6-69
CRSLOCK lock mode indicator 18-16 if owner of set 6-70
CSLOCK lock mode indicator 18-16 requesting instance locks 6-22
currency setting database addresses 6-24
reading tables 6-99 setting key stack positions 6-43
restoring 6-146 writing to fields 6-28
setting members from members 6-122 current sets
setting members from owners 6-123 locks 18-16
setting members from records 6-124 requesting instance locks 6-31
setting owners from members 6-125 current set owner locks 18-16
setting owners from owners 6-126 cursors, getting names of 12-55
setting owners from records 6-127 customized comparison function load
setting records from members 6-128 tables 5-1, 5-2, 18-8
setting records from owners 6-129 customized comparison function
current members module functions
copying fields 6-34 cmpDescribeFcns 5-2
disconnecting 6-50 cmpFunction 5-4
freeing record instance locks 6-12 cmpShutdown 5-6
getting database addresses 6-33 customized comparison function
getting record types 6-15 module functions (cmp prefix) 5-1
locks 18-16 customized comparison functions
requesting record instance locks 6-13 implementing 5-4
requesting set instance locks 6-25 registering 5-2
setting database addresses 6-35 shutting down the module 5-6
writing to fields 6-36
D
current owners
connecting to current records 6-18 d_blobdelete function 6-2
copying fields 6-39 d_bloblog function 6-3
freeing record instance locks 6-16 d_blobread function 6-4

d_blobseek function 6-6 d_discon function
d_blobsize function 6-7 and d_recwrite 6-112
d_blobtell function 6-8 summary 6-50
d_blobwrite function 6-9 d_disdel function 6-51
d_checkpoint function 6-10 d_encode_dba function 6-52
d_close function 6-11 d_errinfo function 6-53
d_cmfree function 6-12 d_fillnew function
d_cmlock function and d_makenew 6-85
and d_stlock 6-133 summary 6-54
summary 6-13 d_findco function 6-56
d_cmtype function 6-15 d_findfm function 6-57
d_cofree function 6-16 d_findlm function 6-58
d_colock function 6-17 d_findnm function 6-59
d_connect function d_findpm 6-60
and d_recwrite 6-112 d_findpm function 6-60
summary 6-18 d_fldcmp function 6-61
d_cotype function 6-19 d_getDD function 6-62
d_crfree function 6-20 d_grplock function 6-65
d_crget function 6-21 d_iclose function 6-67
d_crlock function 6-22 d_iopen function
d_crread function 6-23 and d_open 6-91
d_crset function 6-24 summary 6-68
d_crslock function 6-25 d_ismember function 6-69
d_crtype function 6-27 d_isowner function 6-70
d_crwrite function 6-28 d_keydel function 6-71
d_csfree function 6-30 d_keydir function 6-72
d_cslock function 6-31 d_keyexist function 6-74
d_csmget function 6-33 d_keyfind function
d_csmread function 6-34 and d_keydir 6-73
d_csmset function 6-35 and d_pkeyfind 6-93
d_csmwrite function 6-36 summary 6-75
d_csoget function 6-38 d_keyfrst function
d_csoread function 6-39 and d_keydir 6-73
d_csoset function 6-40 summary 6-76
d_csowrite function 6-41 d_keylast function
d_curkey function 6-43 and d_keydir 6-73
d_dbafree function 6-44 summary 6-77
d_dbalock function 6-45 d_keynext function
d_decode_dba function 6-47 and d_curkey 6-43
d_delete function 6-48 and d_keydir 6-73
d_dict function 4-1, 6-49 and d_pkeyfind 6-93

and d_pkeynext 6-95 d_reclast function
summary 6-75, 6-78 and d_recnext 6-105
d_keyprev 6-75 and d_recprev 6-106
d_keyprev function summary 6-104
and d_ pkeyprev 6-97 d_recnext function
and d_keydir 6-73 and d_recfrst 6-103
and d_pkeyfind 6-93 and d_reclast 6-104
summary 6-79 and d_recprev 6-106
d_keyrdstate function and d_recset 6-108
and d_keywrstate 6-84 summary 6-105
summary 6-80 d_recprev function
d_keyread function 6-81 and d_recfrst 6-103
d_keystore function 6-82 and d_reclast 6-104
d_keyszstate function and d_recnext 6-105
and d_keywrstate 6-84 and d_recset 6-108
summary 6-83 summary 6-106
d_keywrstate function 6-84 d_recread function 6-107
d_locklimit function 19-14 d_recseqno function 6-110
d_makenew function 6-85 d_recset function
d_members function 6-86 and d_recnext 6-105
d_nullset function 6-87 and d_recprev 6-106
d_nulltest function 6-89 summary 6-108
d_open function d_recsetat function 6-109
and d_iopen 6-91 d_rectot function 6-111
and d_timeout 6-136 d_recwrite function 6-112
summary 6-91 d_release function 6-114
d_pkeyfind function d_reset_dberr function 6-115
and d_keydir 6-73 d_rtfree function 6-116
summary 6-93 d_rtlock function
d_pkeynext function and d_rectot 6-111
and d_keydir 6-73 summary 6-117
summary 6-95 d_set_dberr function 6-115, 6-119
d_pkeyprev function d_setkey function
and d_keydir 6-73 and d_makenew 6-85
summary 6-97 summary 6-121
d_rdcurr function d_setmm function 6-122
and d_wrcurr 6-99, 6-146 d_setmo function 6-123
summary 6-99 d_setmr function 6-124
d_rdlockmodes function 6-101 d_setom function 6-125
d_recfrst function d_setoo function 6-126
and d_recnext 6-105 d_setor function 6-127
and d_recprev 6-106 d_setrm function 6-128
summary 6-103 d_setro function 6-129

d_showLocks function 6-130 compound See structures
d_showOwners function 6-131 conversion 18-6
d_stfree function 6-132 correlation between C++ and DPL
d_stlock function 6-133 17-5
d_taskinfo function 6-135 DATE_VAL 16-1, 18-4
d_timeout function 6-136 DB_ADDR 18-2
d_trabort function GROUPLOCK 18-2
and d_trend 6-141 HDBC 18-4
summary 6-137 HENV 18-4
d_tractive function 6-138 HSTMT 18-4
d_trbegin function low-level 18-2
and d_trabort 6-137 mapping SQL to C 18-7
and d_trend 6-141 ODBC function arguments 18-4
and d_trrollback 6-143 ODBC/SQL core 18-5
summary 6-139 ODBC/SQL extended 18-6
d_trend function PL_DATADESC 9-1
and d_trabort 6-137 PL_ITEM 9-1
and d_trbegin 6-139 RDM_DB 18-2
summary 6-141 RDM_SESS 18-2
d_trmark function RETCODE 3-1, 18-4
and d_trbegin 6-139 RM_MEMTAG 18-2
and d_trollback 6-143 RM_PFILE 18-2
and d_trrollback 6-143 RM_POOL 18-2
summary 6-142 SDWORD 18-4
d_trrollback function SQL See SQL data types
and d_trmark 6-142 SQL support functions 18-4
and d_trrollback 6-139 SWORD 18-4
summary 6-143 TIME_VAL 16-1, 18-4
d_unset_dberr function 6-145 TIMESTAMP_VAL 16-1
d_wrcurr function 6-146 UCHAR 18-4
data file compression utility 2-5 UDWORD 18-4
data files, compressing (defragmenting) UWORD 18-4
2-5 Velocis-specific SQL 18-6
Data Portability Layer (DPL) 9-1 database addresses
data type checking See type checking, converting from row identifiers 13-9
data converting to row identifiers 12-23,
data types See also structures 13-2
and Core database programming 18-1 encoding 6-52
and other languages 18-1 extracting file/slot numbers 6-47
and SQL/ODBC programming 18-3 retrieving 13-7
BCD_HENV 3-1, 18-4 database analysis utility 2-15
BLOB_ID 18-2 database consistency checking utility
C types for SQL 18-3 2-3

database definition structure (dbase) DataDescriptor class 17-1
18-10 ~DataDescription destructor 17-2
database dictionaries See database Begin method 17-2
dictionary files constructor and destructor 17-2
database dictionary files DataDescription constructor 17-2
accessing 6-49 End method 17-2
caching 4-1 Field method 17-3
contents 4-1 IsEmpty method 17-3
generating 2-20 methods 17-2
overview 4-1 DataDescriptor::~DataDescription
printing 2-26 destructor 17-2
retrieving 4-1 DataDescriptor::Begin method 17-2
database file registration structure DataDescriptor::DataDescription
(FILEDEV) 18-15 constructor 17-2
database handles DataDescriptor::End method 17-2
retrieving 12-24, 13-3 DataDescriptor::Field method 17-3
summary 1-3 DataDescriptor::IsEmpty method 17-3
database importing utility 2-9 date/time manipulation functions, SQL
database registration structure (VAL prefix)
(DBD_DBF) 18-11 overview 16-1
database repair toolkit See dbrepair structures
toolkit SQL/ODBC date (DATE_STRUCT)
database repair utility 2-7 18-9
database server utility 2-27 SQL/ODBC time (TIME_STRUCT)
database statistics 11-94 18-21
databases SQL/ODBC timestamp
administering 2-28 (TIMESTAMP_STRUCT) 18-22
analyzing 2-15 VALPackDate 16-2
checking consistency 2-3 VALPackTimeStamp 16-4
closing 6-11 VALTime 16-3
closing in increments 6-67 VALUnpackDate 16-5
compiling (Core DDL) 2-19 VALUnpackTime 16-6
compiling (Velocis SQL) 2-37 VALUnpackTimestamp 16-7
compressing (defragmenting) 2-5 DATE_STRUCT structure 16-1, 18-9
importing data into 2-9 DATE_VAL data type 16-1, 18-4
opening 6-91 dates
opening incrementally 6-68 converting from ODBC to Velocis
repairing 2-7 format 16-2
repairing delete chains 2-17 converting from Velocis to ODBC
restoring backups 2-13 format 16-5
retrieving open mode of 6-46 SQL/ODBC structure
rolling forward change logs 2-13 (DATE_STRUCT) 18-9

DB_ADDR data type 18-2 deallocating resource manager memory
DB_ADDR_EQ macro 18-3 blocks 10-38
DB_ADDR_ISNULL macro 18-3 deallocating tag-associated resource
DB_ADDR_SIZE constant 18-3 manager memory blocks 10-39
DBALOCK lock mode indicator 18-17 decimal (SQL data type) 18-5
dbase structure 18-10 DECLARE_RPC_MAP macro 17-29
dbcheck utility 2-3 defragmenting data files 2-5
DBD_DBF structure 18-2, 18-11 delete chain repairing utility 2-17
dbdefrag utility 2-5 delete chains, repairing 2-17
dberr and d_set_dberr 6-119 deleting queues 10-55
dbfix utility 2-7 deleting resource manager files 10-22
dbimp utility deleting semaphores 10-68
ASCII text to database 2-9 describing SQL import and export filter
language summary 2-10 modules 8-5
summary 2-9 describing SQL UDFs 14-5
dbrepair toolkit 2-1, 11-1 describing SQL UDPs 15-5
dbcheck 2-3 destructors, C++
dbdefrag 2-5 DataDescriptor::~DataDescription
dbfix 2-7 17-2
dchain 2-17 SeBase::~SeBase 17-13
keybuild 2-24 ServerExtension::~ServerExtension
overview 2-1, 11-1 17-19
server cache 2-4, 2-5, 2-8, 2-18, 2-24 DetachFailure status code 17-1
dbreplay utility 2-13 detaching extension modules from
dbstat utility 2-15 Velocis clients 7-7
dchain utility 2-17 determining SQL statement types 13-4
ddlproc utility device definition structure (device)
and compound key table 4-35 18-12
and field table 4-33 device names, changing 11-44, 11-45
and file table 4-34 device structure 18-2, 18-12
and record table 4-37 dictionaries, database See database
and set member table 4-36 dictionary files
and set table 4-39 dictionary access API functions
and sort table 4-38 (c_ prefix)
creating C constants 1-3 c_db_name 4-2
keywords, list of 2-21 c_fd_dim 4-3
re-creating database dictionary 19-10 c_fd_flags 4-4
summary 2-19 c_fd_idx 4-5
deadlock 6-136 c_fd_key 4-6
deallocating parameter lists 9-6 c_fd_keyfile 4-7
deallocating resource manager memory c_fd_keyno 4-8
and clearing its pointer 10-83 c_fd_len 4-9

c_fd_name 4-10 dividing SQL values (from server-side
c_fd_rec 4-11 UDF) 13-15
c_fd_size 4-12 documentation, Velocis
c_fd_type 4-13 Centura Books Online 1-5
c_field_offset 4-14 function reference format 1-3
c_freedict 4-15 Installation/Administration Guide
c_ft_name 4-16 1-4
c_ft_slots 4-17 Language Guide 1-4
c_ft_type 4-18 notational conventions 1-5
c_kt_field 4-19 other resources 1-5
c_kt_key 4-20 readme.txt 1-4
c_kt_ptr 4-21 related documents 1-4
c_mt_record 4-22 summary 1-1
c_mt_sort_fld 4-23 User’s Guide 1-4
c_mt_totsf 4-24 DPL 9-1
c_rec_len 4-25 DPL data types, correlating with C++
c_rt_fdtot 4-26 data types 17-5
c_rt_fields 4-27 dynamic memory pool handles 10-2
c_rt_file 4-28 dynamic memory pools See pools,
c_rt_flags 4-29 dynamic memory
c_rt_idx 4-30 dynamic memory tags See tags,
c_rt_name 4-31 dynamic memory
c_se_fld 4-32
E
c_size_fd 4-33
c_size_ft 4-34 em_attach function
c_size_kt 4-35 and ModInit 7-20
c_size_mt 4-36 summary 7-2
c_size_rt 4-37 em_call function 7-4
c_size_srt 4-38 EM_CHG structure 18-2, 18-13
c_size_st 4-39 em_detach function
c_st_flags 4-40 and ModCleanup 7-15
c_st_idx 4-41 summary 7-7
c_st_members 4-42 em_getContext function
c_st_memtot 4-43 and ModInit 7-20
c_st_name 4-44 summary 7-9
c_st_order 4-45 em_getHandle function 7-11
c_st_own_rt 4-46 em_load function 7-12
overview 4-1 em_unload function 7-14
dictionary printing utility 2-26 EMLOADTABLE structure 7-4, 18-14
dirty reads 6-74, 6-101, 6-107, 6-124 enabling quiescent semaphores 10-71
disabling quiescent semaphores 10-69 END_RPC_MAP macro 17-29
dividing binary-coded decimals 3-6 ending operating system threads 10-82

engine resource manager functions errCONRANGE 19-43
(rm_ prefix) 10-1 errCURMISMATCH 19-34
entering exclusive access to mutex errCURSTATE 19-33
semaphores 10-72 errDATA 19-31
environment handles errDATALOST 19-32
allocating 12-4 errDATETIMEOVF 19-32
freeing 12-51 errDBAPK 19-34
environment variable, RDSLOGIN 2-1 errDBAPKUPD 19-35
err return codes 19-26 errDBNOTOPEN 19-34
errACCESS 19-38 errDBNOTREFD 19-36
errACCRANGE 19-43 errDBUNAVAIL 19-45
errACTINDEX 19-40 errDESCRANGE 19-42
errBADCODE 19-44 errDIFFHDBC 19-47
errBADCOLUMN 19-39 errDIRRANGE 19-43
errBADDATALEN 19-42 errDIVBY0 19-32
errBADDEVICE 19-45 errDLLERR 19-45
errBADFILTER 19-40 errDRVMEMORY 19-41
errBADFORMAT 19-36 errDUPCOLUMN 19-39
errBADFUNC 19-40 errDUPCURSOR 19-38
errBADLITERAL 19-32 errDUPDB 19-40
errBADMOD 19-45 errDUPFILTER 19-40
errBADPROC 19-40 errDUPFUNC 19-40
errBADSYSCAT 19-46 errDUPINDEX 19-39
errBADTABLE 19-39 errDUPPROC 19-40
errBADUSER 19-40 errDUPTABLE 19-39
errCANCELASFREE 19-29 errDUPUSER 19-40
errCANCELED 19-41 errDUPVIEW 19-39
errCANCELFIRST 19-42 errENVHANDLE 19-29
errCANTINST 19-46 errESCAPE 19-36
errCARDINALITY 19-31 errEXECUTED 19-42
errCD_BADCOL 19-37 errFCNARG 19-34
errCD_BADELTNAME 19-37 errFCNRANGE 19-43
errCD_HASCDATA 19-37 errFCNSEQ 19-41
errCD_NOELTNAME 19-37 errFETCHTYPE 19-43
errCD_NUMSUBS 19-37 errIEF 19-46
errCD_SUBRANGE 19-37 errINFORANGE 19-43
errCD_SUBTYPE 19-37 errINSERTCOLS 19-31
errCHECKOPT 19-38 errINSERTVALS 19-31
errCHTRUNC 19-29 errINTEGRITY 19-32
errCLOSESERVER 19-42 errINVARG 19-41
errCOLNUMBER 19-41 errINVCONVERT 19-44
errCOLRANGE 19-43 errINVOPNOW 19-44
errCONHANDLE 19-29 errINVUSER 19-33

errLOADMOD 19-45 errPATTERN 19-33
errLONGVARLEN 19-32 errPREPARED 19-42
errMIXEDMODE 19-34 errPROCTEMPREF 19-46
errNOCOLUMN 19-39 errPROGTYPE 19-41
errNOCONNECT 19-47 errRANGE 19-31
errNOCURSOR 19-42 errREADONLY 19-47
errNODATANEEDED 19-44 errREFPKUPD 19-35
errNOINDEX 19-39 errRESTRICT 19-36
errNOINDEXCOL 19-37 errROWERROR 19-29
errNOINDVAR 19-32 errROWVALUE 19-43
errNOPKUPD 19-35 errSCALE 19-43
errNOSERVER 19-30 errSCOPERANGE 19-43
errNOTABLE 19-39 errSERIAL 19-38
errNOTCAPABLE 19-43 errSERVER 19-30
errNOTCURSOR 19-30 errSORTLIMIT 19-35
errNOTNULL 19-34 errSORTSIZE 19-35
errNOTOPEN 19-30 errSQLTYPE 19-41
errNOTOPTIONAL 19-40 errSRVMEMORY 19-41
errNOTSELECT 19-33 errSRVOPEN 19-30
errNOTSUPPORTED 19-38 errSRVREJECT 19-30
errNOTTEMP 19-46 errSTMTHANDLE 19-30
errNOTUPDATEABLE 19-36 errSTMTLIMIT 19-44
errNOVIEW 19-39 errSTRTRUNC 19-31
errNULLPTR 19-44 errSYNTAX 19-33
errNULLRANGE 19-43 errSYSTEM 19-47
errNUMFCNARGS 19-31 errTABRANGE 19-43
errNUMPAR 19-30 errTBD 19-44
errOPEN 19-45 errTIMEOUT 19-44
errOPENHDBCS 19-41 errTOOLONG 19-31
errOPTCHANGED 19-29 errTOOMANYROWS 19-36
errOPTIONRANGE 19-42 errTRANSID 19-44
error handlers errTXACTIVE 19-33
in SQL 12-109 errTXNOTACTIVE 19-33
removing 6-145 errTXSYNC 19-33
setting as default 6-119 errTXTYPE 19-42
resetting stack 6-115 errTYPEATTR 19-30
error messages 19-49 errUDF 19-45
errors, retrieving information on 6-53 errUDFNORESET 19-46
errOUTOFSPACE 19-46 errUDFNOVAL 19-46
errPARAMREF 19-35 errUNDEFDB 19-34
errPARAMTYPE 19-36 errUNDEFFK 19-35
errPARMTYPE 19-44 errUNIQRANGE 19-43
errPARNO 19-43 errUNRELFK 19-35

errVALTYPE 19-34 getting the session task context
errVIEWCOLS 19-36 pointer 7-9
errVIEWMISMATCH 19-31 handles 7-2, 7-7, 7-11
errVIEWTEMPREF 19-46 load tables 7-4
errWHERECALCS 19-35 implementing functionality 7-18
event semaphores 10-66, 10-75, 10-77, initializing 7-20
10-78 loading 7-12
execute statement 15-10 registering functions 7-16
executing SQL statements retrieving its handle 7-11
after preparation 12-38 unloading 7-14
directly 12-37 extracting parameter list item
interactively 2-29 information 9-10
exiting exclusive access to mutex
F
semaphores 10-73
extending cleared resource manager fetching rows from SQL import filters
memory blocks 10-4 8-7
extending resource manager memory file numbers 6-52
blocks 10-10 file structure reports 2-19
extension module function load tables FILEDEV structure 18-2, 18-15
18-14 files, compressing (defragmenting) data
extension module functions (em_ and 2-5
Mod prefix) files, database dictionary See database
em_attach 7-2 dictionary files
em_call 7-4 files, rebuilding key 2-24
em_detach 7-7 files, resource manager
em_getContext 7-9 closing 10-11
em_getHandle 7-11 copying 10-12
em_load 7-12 deleting or removing 10-22
em_unload 7-14 finding or seeking a position 10-24
ModCleanup 7-15 moving 10-14
ModDescribeFcns 7-16 opening 10-15
ModFunction 7-18 printing formatted text to 10-19
ModInit 7-20 reading from certain locations 10-25
overview 7-1 reading from current positions 10-20
extension module registration structure renaming 10-23
(EM_CHG) 18-13 retrieving positions of 10-18
extension modules retrieving the length of 10-13
attaching to Velocis clients 7-2 synchronizing 10-34
calling 7-4 validating (checking for the existence
changing names 11-49 of) 10-35
cleaning up 7-15 writing to certain locations 10-26
detaching from Velocis clients 7-7 writing to current positions 10-36

files, resource manager stream dictionary access API functions
closing 10-28 (c_ prefix) 4-1
opening 10-31 engine resource manager functions
reading lines (fixed-length) 10-30 (rm_ prefix) 10-1
reading lines (to end-of-line) 10-29 extension module functions (em_ and
resetting positions 10-33 Mod prefix) 7-1
writing lines 10-32 import and export filter module
filters, SQL import and export functions (ief prefix) 8-1
checking parameter data types 8-2 parameter list functions (pl_ prefix)
cleaning up 8-4 9-1
column values descriptor structure SQL API functions (SQL prefix) 12-1
(VALUE_DESCR) 18-29 SQL date/time manipulation
exporting rows 8-12 functions (VAL prefix) 16-1
importing rows 8-7 SQL decimal value manipulation
initializing 8-9 functions (BCD prefix) 3-1
load tables 8-1 SQL UDF support functions
registering 8-5 (SYS prefix) 13-1
finding positions in resource manager SQL user-defined function (UDF)
files 10-24 module functions (udf prefix)
foreign keys, retrieving information 14-1
about 12-46 SQL user-defined procedure (UDP)
freeing dynamic memory pools and module functions (udp prefix)
clearing its handle 10-84 15-1
freeing memory buffer pools 10-84 function reference format 1-3
freeing memory for BCD handles 3-7 function return values
freeing memory for binary-coded SQL_ERROR 19-25
decimal buffers 3-8 SQL_INVALID_HANDLE 19-25
freeing parameter lists 9-6 SQL_NEED_DATA 19-25
freeing resource manager memory and SQL_NO_DATA_FOUND 19-25
clearing its pointer 10-83 SQL_SUCCESS 19-25
freeing resource manager memory SQL_SUCCESS_WITH_INFO 19-26
blocks 10-38 SQL_ZERODIV 19-26
freeing tag-associated resource manager
G
memory blocks 10-39
function categories getting parameter list items 9-8
administration API functions getting session task context pointers for
(s_ prefix) 11-1 extension modules 7-9
Core API functions (d_ prefix) 6-1 group locks, requesting 6-65
customized comparison functions group lock request packet structure
(cmp prefix) 5-1 (GROUPLOCK) 18-16

GROUPLOCK data type 18-2 killing 11-10
GROUPLOCK structure 18-16 setting the number of hot file index
pages 11-5
H
starting 11-3
handles HSTMT data type 18-4
BCD_HENV 3-1
database 1-3, 13-3 I
dynamic memory pool 10-2 IEF See filters, SQL import and export
extension module 7-2, 7-7, 7-11 IEF column values descriptor structure
queue 10-54 (VALUE_DESCR) 18-29
resource manager file 10-15 iefCheck function 8-2
resource manager streaming file iefCleanup function 8-4
10-31 iefDescribeFcns function 8-5
semaphore 10-66 iefFetch function 8-7
session 1-3, 13-10 iefInit function 8-9, 18-29
system 13-5 IEFLOADTABLE structure 8-1, 8-5,
handles, allocating 18-18
C data column 12-2 iefStore function 8-12
environment 12-4 implementing customized comparison
server connection 12-3 functions 5-4
SQL statement 12-5 implementing extension module
handles, freeing functionality 7-18
C data column 12-49 implementing SQL UDFs 14-7
environment 12-51 implementing SQL UDPs 15-7, 15-12
server connection 12-50 import and export filter (SQL) load
SQL statement 12-52 tables 8-1, 18-18
handling errors in SQL 12-109 import and export filter module
HDBC data type 18-4 functions (ief prefix)
header files iefCheck 8-2
caldefs.h 16-1 iefCleanup 8-4
SQL 18-3 iefDescribeFcns 8-5
sqlxdefs.h 16-1 iefFetch 8-7
usercmp.h 5-1 iefInit 8-9
valerrs.h 3-1, 16-1 iefStore 8-12
HENV data type 18-4 overview 8-1
hot backup mode import and export filters See filters, SQL
ending 11-7 import and export
flushing 11-8 import specification language summary
freeing backup files 11-9 2-10
getting the number of hot file index importing data into databases 2-9
pages 11-4 initializing extension modules 7-20
going from persistent to regular 11-2 initializing SQL import and export
going from regular to persistent 11-6 filters 8-9

initializing SQL UDFs 14-9 filter, import and export (SQL) 8-1,
initializing SQL UDPs 15-10 18-18
Installation/Administration Guide 1-4 user-defined (SQL) function 14-1,
installing Velocis ODBC drivers 2-22 14-5, 18-23
installing Velocis servers (NT only) 2-23 user-defined (SQL) procedure 15-1,
instance locks, freeing 6-114 15-5, 18-24
instodbc utility 2-22 LoadFailure status code 17-1
instrds utility (NT only) 2-23 loading extension modules 7-12
interactive Velocis SQL utility 2-29 lock mode indicators
interface control commands, rsql utility CMLOCK 18-16
2-32 COLOCK 18-16
InvalidData status code 17-1 CRLOCK 18-16
InvalidSize status code 17-1 CRSLOCK 18-16
DBALOCK 18-17
J
RTLOCK 18-17
jump buffers 10-3, 10-5, 10-7, 10-44, STLOCK 18-17
10-60 locks
K current member 18-16
keys current record 18-16
finding last 6-77 current set 18-16
finding next 6-78 current set owner 18-16
finding previous 6-79 freeing all 6-114
reading key state 6-80 implicit 6-117, 6-133
reading last 6-81 record 18-17
restoring key state 6-84 record (by database address) 18-17
setting search direction 6-72 setting 18-17
key fields, setting values 6-121 setting request timeouts 6-136
key file rebuilding utility 2-24 statistics 11-95
key files setting owner of current record 18-16
rebuilding 2-24 log, Velocis message 10-49
re-creating 11-68 LOG_ALL 10-49, 10-62
key states, retrieving sizes of 6-83 LOG_CYCLE 10-49, 10-62
keybuild utility 2-24 LOG_EM 10-49, 10-62
LOG_ERROR 10-49, 10-62
L LOG_INFO 10-49, 10-62
Language Guide 1-4 LOG_LOGIN 10-49, 10-62
library, client 19-15 LOG_RECOV 10-49, 10-62
LITERAL_NULL_DBA constant 18-3 LOG_STARTUP 10-49, 10-62
load tables LOG_USER 10-49, 10-62
customized comparison function 5-1, LOG_WARN 10-49, 10-62
5-2, 18-8 longjmp function 10-3
extension module function 7-4, 18-14

M ModCleanup function 7-15
macros ModDescribeFcns function 7-16
BCDZLEN 3-4 ModFunction function 7-18
BEGIN_RPC_MAP 17-26 ModInit function
CREATE_EXPORTS 17-26 and ModCleanup 7-15
DB_ADDR_EQ 18-3 summary 7-20
DB_ADDR_ISNULL 18-3 moving resource manager files 10-14
DECLARE_RPC_MAP 17-29 multiplying binary-coded decimals 3-9
END_RPC_MAP 17-29 multiplying SQL values (from server-
low-level 18-3 side UDF) 13-16
MAKE_SESS 18-3 mutex semaphores 10-66, 10-72, 10-73
ON_RPC 17-29 N
REXTERNAL 7-1, 8-1, 14-1, 15-1
N_STATS 11-94
server extension toolkit (C++) 17-26
notational conventions 1-5
MAKE_SESS macro 18-3
NULL_DBA constant 18-3
MakeProcInstance 6-120
member O
count 6-86 obtaining subsequent result sets for SQL
memory, resource manager UDPs 15-12
allocating 10-44 obtaining the first result set for SQL
deallocating 10-38 UDPs 15-7
deallocating (and clearing its pointer) ODBC
10-83 adding Velocis data sources 2-22
extending or reallocating 10-10 converting dates from Velocis format
freeing 10-38 16-5
freeing (and clearing its pointer) converting dates to Velocis format
10-83 16-2
freeing tag-associated 10-39 converting times from Velocis format
retrieving amounts of available 16-6
memory on tags 10-51 converting times to Velocis format
retrieving sizes for tags 10-50 16-3
memory, resource manager (cleared) converting timestamps from Velocis
allocating 10-5 format 16-7
extending or reallocating 10-4 converting timestamps to Velocis
messages, error (from sddlp utility) format 16-4
19-49 installing Velocis drivers 2-22
methods, C++ summary 12-16, 12-46, 12-60
DataDescriptor class 17-2 ODBC drivers, adding with instodbc
ParmReceive class 17-6 2-22
ParmSend class 17-10 ODBC installation utility 2-22
SeBase class 17-14 ON_RPC macro 17-29
ServerExtension class 17-19 opening resource manager files 10-15

opening resource manager stream files getting the next item 9-8
10-31 removing items 9-5
operators, C++ ParmReceive class 17-4
ParmReceive::operator >> 17-4 >> operator 17-4
ParmSend::operator << 17-9 Get method 17-6
SeBase::operator delete 17-14 GetNextSize method 17-7
SeBase::operator new 17-13 GetNextType method 17-7
optional keys GetSize method 17-7
checking existence of 6-74 GetType method 17-8
deleting 6-71 methods 17-6
storing 6-82 NoData method 17-8
operators 17-4
P
ParmReceive::Get method 17-6
packed decimal buffers, calculating sizes ParmReceive::GetNextSize method 17-7
of 3-4 ParmReceive::GetNextType method
packing (converting to from string) 17-7
binary-coded decimals 3-10 ParmReceive::GetSize method 17-7
parameter list functions (pl_ prefix) ParmReceive::GetType method 17-8
item descriptor structure (PL_ITEM) ParmReceive::NoData method 17-8
18-19 ParmReceive::operator >> 17-4
overview 9-1 ParmSend class 17-9
pl_alloc 9-2 << operator 17-9
pl_count 9-4 methods 17-10
pl_del 9-5 operators 17-9
pl_free 9-6 Put method 17-10
pl_get 9-8 ParmSend::operator << 17-9
pl_peek 9-10 ParmSend::Put method 17-10
pl_printf 9-12 performing processing for SQL UDFs
pl_put 9-14 14-7
pl_putStruct 9-17 performing processing for SQL UDPs
pl_seek 9-20 15-7, 15-12
parameter list item descriptor structure pinging utility 2-39
(PL_ITEM) 18-19 pl_alloc function 9-2
parameter lists PL_ASCIZ 9-14
adding structure items 9-17 PL_CHAR 9-14, 18-20
adding items 9-14 pl_count function 9-4
adding multiple items 9-12 PL_DATADESC data type 9-1
allocating 9-2 PL_DB_ADDR 9-14, 18-20
changing item currency 9-20 pl_del function 9-5
counting the number of items 9-4 PL_DOUBLE 9-14, 18-20
deallocating 9-6 PL_FLAG_ARRAY 9-10, 9-14, 9-17,
extracting parameter information 18-19
9-10 PL_FLAG_CLOSE 9-18, 18-19

PL_FLAG_FREE 9-10, 9-14, 9-17, 18-19 Q
PL_FLAG_NULL 9-10, 9-14, 9-17 queue handles 10-54
PL_FLAG_OPEN 9-18, 18-19 queues
PL_FLOAT 9-14, 18-20 creating 10-54
pl_free function 9-6 deleting 10-55
pl_get function 9-8 purging 10-56
PL_INT 9-14, 18-20 reading messages from 10-57
PL_ITEM data type 9-1 writing messages to 10-59
PL_ITEM structure 9-10, 9-17, 18-19 quiescent semaphores 10-66, 10-69,
PL_LONG 9-14, 18-20 10-71, 10-74, 10-76, 10-79
PL_OPAQUE 9-14
pl_peek function 9-10 R
pl_printf function 9-12 RDM_DB data type 18-2
pl_put function 9-14 RDM_SESS data type 18-2
pl_putStruct function 9-17 rdsadm utility
pl_seek function 9-20 and s_dbClone 11-16
PL_SHORT 9-14, 18-20 summary 2-28
PL_STRUCT 9-18, 18-20 RDSLOGIN environment variable 2-1,
PL_UCHAR 9-14, 18-20 2-3, 2-5, 2-7, 2-9, 2-15, 2-17, 2-19,
PL_UINT 9-14, 18-20 2-24, 2-28, 2-37
PL_ULONG 9-14, 18-20 read locks
PL_USHORT 9-14, 18-20 freeing 6-101, 6-114
PL_WCHAR 9-14, 18-20 setting modes 6-101
PL_WSCZ 9-14 reading from certain locations in
pools, dynamic memory resource manager files 10-25
allocating 10-2 reading from current positions in
freeing (and clearing its handle) 10-84 resource manager files 10-20
putting buffers into 10-52 reading lines (fixed-length) from
retrieving buffers from 10-41 resource manager stream files 10-30
pools, memory buffer 10-84 reading lines (to carriage return) from
prdbd utility 2-26, 4-1 resource manager stream files 10-29
printing database dictionary files 2-26 reading message from queues 10-57
printing formatted text to resource readme.txt file 1-4
manager files 10-19 reallocating cleared resource manager
purging (removing) queues based on memory blocks 10-4
certain messages 10-56 reallocating resource manager memory
putting buffers into dynamic memory blocks 10-10
pools 10-52 rebuilding key files 2-24

receiving permission to access quiescent relative path use with devices 11-39
semaphores 10-74 remote procedure calls 9-1, 11-94, 11-96
records removing parameter list items 9-5
creating 6-85 removing resource manager files 10-22
creating and filling 6-54 renaming resource manager files 10-23
deleting 6-48 repairing databases 2-7
finding by first key 6-76 repairing delete chains 2-17
finding by key 6-75 resetting jump buffers for dynamic
finding by partial key 6-93 memory tags 10-60
finding next by partial key 6-95 resetting positions of resource manager
finding previous by partial key 6-97 stream files 10-33
freeing instance lock 6-44 resetting running values for SQL
reading 6-107 aggregate UDFs 14-11
requesting instance lock 6-45 resource manager
setting 6-108 cleaning up and shutting down 10-6
writing 6-112 file management 10-11, 10-15
record access file stream management 10-28, 10-31
sequential 6-103, 6-104, 6-105, 6-106, message queues 10-54, 10-55
6-108 pools, dynamic memory 10-2, 10-41,
record instance locks and d_makenew 10-52, 10-84
6-85 starting 10-62
record locks 18-17 synchronization objects (semaphores)
record types 10-66, 10-68
database address 6-109 tags, dynamic memory 10-3, 10-7,
finding first occurrence 6-103 10-60
finding last occurrence 6-104 thread management 10-80, 10-82
finding next occurrence 6-105 resource manager file handles 10-15
finding previous 6-106 resource manager functions
locks 6-116, 6-117 rm_allocPool 10-2
setting 6-109 rm_allocTag 10-3
Reference Manual rm_cExtendMemory 10-4
introduction 1-1 rm_cGetMemory 10-5
chapter summaries 1-1 rm_cleanup 10-6
referential integrity and delete statement rm_createTag 10-7
2-38 rm_extendMemory 10-10
registering customized comparison rm_fileClose 10-11
functions 5-2 rm_fileCopy 10-12
registering SQL import and export filter rm_fileLength 10-13
modules 8-5 rm_fileMove 10-14
registering SQL UDFs 14-5 rm_fileOpen 10-15
registering SQL UDPs 15-5 rm_filePosition 10-18
registering functions in extension rm_filePrintf 10-19
modules 7-16 rm_fileRead 10-20

rm_fileRemove 10-22 rm_syncExitExcl 10-73
rm_fileRename 10-23 rm_syncReceiveQ 10-74
rm_fileSeek 10-24 rm_syncResume 10-75
rm_fileSeekRead 10-25 rm_syncSendQ 10-76
rm_fileSeekWrite 10-26 rm_syncStart 10-77
rm_fileStreamClose 10-28 rm_syncWait 10-78
rm_fileStreamGetLine 10-29 rm_syncWaitQ 10-79
rm_fileStreamGets 10-30 rm_threadBegin 10-80
rm_fileStreamOpen 10-31 rm_threadEnd 10-82
rm_fileStreamPuts 10-32 rm_zFreeMemory 10-83
rm_fileStreamRewind 10-33 rm_zFreePool 10-84
rm_fileSync 10-34 resource manager functions (rm_ prefix)
rm_fileValidate 10-35 10-1
rm_fileWrite 10-36 resource manager streaming file handles
rm_freeMemory 10-38 10-31
rm_freeTagMemory 10-39 restoring database backups 2-13
rm_getenv 10-40 result sets, obtaining (from UDPs) 15-7,
rm_getFromPool 10-41 15-12
rm_getLocalEnv 10-43 resuming event semaphores 10-75
rm_getMemory 10-44 RETCODE data type 3-1, 18-4
rm_iniGet 10-45 retrieving amounts of available memory
rm_iniGetPrivate 10-46 on tag-allocated resource manager
rm_iniSet 10-47 memory blocks 10-51
rm_iniSetPrivate 10-48 retrieving extension module handles
rm_log 10-49 7-11
rm_memoryAllocated 10-50 retrieving buffers from dynamic
rm_memoryAvail 10-51 memory pools 10-41
rm_putInPool 10-52 retrieving database addresses 13-7
rm_putLocalEnv 10-53 retrieving database handles 13-3
rm_queueCreate 10-54 retrieving dynamic memory tags (from
rm_queueDelete 10-55 server-side UDF) 13-6
rm_queuePurge 10-56 retrieving environment variable values
rm_queueRead 10-57 10-40
rm_queueWrite 10-59 retrieving local variable values 10-43
rm_resetTag 10-60 retrieving parameter list items 9-8
rm_sleep 10-61 retrieving positions of resource manager
rm_startup 10-62 files 10-18
rm_Strdup 10-65 retrieving private configuration file
rm_syncCreate 10-66 variable values 10-46
rm_syncDelete 10-68 retrieving row identifiers 13-8
rm_syncDisableQ 10-69 retrieving server configuration
rm_syncEnableQ 10-71 (velocis.ini) variable values 10-45
rm_syncEnterExcl 10-72 retrieving session handles 13-10

retrieving sizes of tag-allocated resource rm_fileStreamOpen function 10-31
manager memory blocks 10-50 rm_fileStreamPuts function 10-32
retrieving system handles 13-5 rm_fileStreamRewind function 10-33
retrieving the length of resource rm_fileSync function 10-34
manager files 10-13 rm_fileValidate function 10-35
return codes rm_fileWrite function 10-36
getting details about (SQL) 12-35 RM_FPRINTF 10-15
overview 19-1 rm_freeMemory function 10-38
SQL (SQL_ prefix) 19-25 rm_freeTagMemory function 10-39
SQL value manipulation (VAL_ rm_getenv function 10-40
prefix) 19-48 rm_getFromPool function 10-41
SQLError (err prefix) 19-26 rm_getLocalEnv function 10-43
standard (S_ prefix) 19-1 rm_getMemory function
REXTERNAL macro 7-1, 8-1, 14-1, 15-1 and rm_zFreeMemory 10-83
rm_allocPool function 10-2 summary 10-44
rm_allocTag function 10-3 RM_INDEFINITE_WAIT 10-78, 10-79
rm_cExtendMemory function 10-4 rm_iniGet function 10-45
rm_cGetMemory function rm_iniGetPrivate function 10-46
and rm_zFreeMemory 10-83 rm_iniSet function 10-47
summary 10-5 rm_iniSetPrivate function 10-48
rm_cleanup function 10-6 rm_log function 10-49
rm_createTag function 10-7 rm_memoryAllocated function 10-50
RM_DIRECTIO 10-15 rm_memoryAvail function 10-51
RM_EVENT_SEM 10-66 RM_MEMTAG data type 10-3, 18-2
RM_EXCLUSIVE 10-66 RM_MUTEX_SEM 10-66
RM_EXIT_ON_FAIL 10-15 RM_NOGROW 10-16
rm_extendMemory function 10-10 RM_NOSEM 10-3, 10-7
rm_fileClose function 10-11 RM_NOSYNC 10-16
rm_fileCopy function 10-12 RM_PFILE data type 18-2
rm_fileLength function 10-13 RM_POOL data type 10-2, 18-2
rm_fileMove function 10-14 rm_putInPool function 10-52
rm_fileOpen function 10-15 rm_putLocalEnv function 10-53
rm_filePosition function 10-18 RM_QUEUE_NORMAL 10-59
rm_filePrintf function 10-19 RM_QUEUE_PRIORITY 10-59
rm_fileRead function 10-20 rm_queueCreate function 10-54
rm_fileRemove function 10-22 rm_queueDelete function 10-55
rm_fileRename function 10-23 rm_queuePurge function 10-56
rm_fileSeek function 10-24 rm_queueRead function 10-57
rm_fileSeekRead function 10-25 rm_queueWrite function 10-59
rm_fileSeekWrite function 10-26 RM_QUIES_SEM 10-66
rm_fileStreamClose function 10-28 rm_resetTag function 10-60
rm_fileStreamGetLine function 10-29 RM_SHARE 10-16, 10-20, 10-24, 10-36
rm_fileStreamGets function 10-30 RM_SHAREABLE 10-66

rm_sleep function 10-61 rsql utility
rm_startup function 10-62 commands, table of 2-30
RM_STICKY 10-16 interface control commands 2-32
rm_Strdup function 10-65 summary 2-29
rm_syncCreate function 10-66 RTLOCK lock mode indicator 18-17
rm_syncDelete function 10-68
S
rm_syncDisableQ function 10-69
rm_syncEnableQ function 10-71 S_ return codes 19-1
rm_syncEnterExcl function 10-72 s_backupAttach function 11-2, 11-6
rm_syncExitExcl function 10-73 s_backupBegin function 11-2, 11-3
rm_syncReceiveQ function 10-74 s_backupCacheGet function 11-4
rm_syncResume function 10-75 s_backupCacheSet function 11-5
rm_syncSendQ function 10-76 s_backupDetach function 11-2, 11-6
rm_syncStart function 10-77 s_backupEnd function 11-7
rm_syncWait function 10-78 s_backupFlush function 11-8
rm_syncWaitQ function 10-79 s_backupFreeFile function 11-9
RM_THREAD_HIGH 10-80 s_backupKill function 11-2, 11-10
RM_THREAD_LOW 10-80 S_BADBLOB 19-3
RM_THREAD_NORMAL 10-80 S_BADEMH 19-3
rm_threadBegin function 10-80 S_BADEXTLIMIT 19-3
rm_threadEnd function 10-82 S_BADEXTNO 19-3
RM_USESEM 10-3, 10-7 S_BADFIELD 19-3
rm_zFreeMemory function 10-83 S_BADPATH 19-3
rm_zFreePool function 10-84 S_BADSRV 19-3
RMF_STREAM 10-31 S_BADTYPE 19-3
RMLOG_CLOSE 10-63 S_BLOBPOS 19-4
RMLOG_MESSAGE 10-63 S_BLOBUPD 19-4
RMLOG_OPEN 10-63 S_BUACTIVE 19-4
rollback 6-139 S_BUBADFILEID 19-4
roll-forward utility 2-13 S_BUFLEN 19-4
rolling forward database change logs S_BUNOTACTIVE 19-4
2-13 S_BUOPTION 19-4
row identifiers S_BUQUICK 19-4
converting to database addresses 13-9 S_BUTIMEOUT 19-4
converting from database addresses S_CATERR 19-5
12-23, 13-2 S_CATLOCKED 19-5
retrieving 13-8 S_CATTIME 19-5
RPC See remote procedure calls S_COMKEY 19-5
RPCError status code 17-1 S_CONFLICT 19-5

S_DBACCESS 19-5 S_DPLDBLUNDF 19-8
s_dbAdd function 11-11 S_DPLFLTOVF 19-8
S_DBASEMEMS 19-5 S_DPLFLTUNDF 19-8
s_dbcheckBegin function 2-4, 11-13 S_DPLINTERR 19-8
s_dbClone function 11-16 S_DPLINTOVF 19-8
s_dbdefragBegin function 2-6, 11-19 S_DPLINTUNDF 19-8
s_dbDel function 11-20 S_DPLTOOLARGE 19-8
S_DBEXISTS 19-6 S_DUPLICATE 19-8
s_dbfixBegin function 2-8, 11-22 s_emAdd function 11-46
s_dbGet function 11-25 s_emDel function 11-47
s_dbInit function 11-26 S_EMEXISTS 19-9
s_dbInitfile function 11-27 s_emGet function 11-48
S_DBINUSE 19-6 S_EMMEMS 19-9
S_DBINV 19-6 s_emModify function 11-49
s_dbModify function 11-28 s_endRPCThreads function 11-50
S_DBNOTREG 19-6 S_EOS 19-9
S_DBOPEN 19-6 s_errinfo function 11-51
S_DBPERM 19-6 S_EXCLUSIVE 19-9
S_DBRACTIVE 19-6 S_EXOPENED 19-9
S_DBRBADDB 19-7 s_fileAddExt function 11-52
s_dbrEnd function 11-29 S_FILEDEVICE 19-9
S_DBRERROR 19-7 s_fileInfo function 11-53
s_dbrGetStatus function 2-4, 2-6, 2-8, S_FILEMEMS 19-9
2-18, 2-25, 11-30 s_fileMove function 11-54
S_DBRIDLE 19-7 S_FILEOPERR 19-9
S_DBRNOREPORT 19-7 s_fileRecv function 11-55
s_dbstat function 11-32 s_fileSend function 11-56
S_DBUNAVAIL 19-7 s_fileSetSizes function 11-57
s_dbUserAdd function 11-33 s_fileTotals function 11-58
s_dbUserDel function 11-34 S_FREEMODULE 19-10
s_dbUserGet function 11-35 s_getDiskFreeSpace function 11-59
s_dchainBegin function 2-18, 11-37 s_getTimeout function 11-60
S_DELETED 19-7 S_HASMEM 19-10
S_DELSYS 19-7 S_ILLCALL 19-10
s_devAdd function 11-39 S_ILLDOWNG 19-10
s_devAddEx function 11-40 S_ILLMODE 19-10
s_devDel function 11-41 S_INCMODE 19-10
S_DEVEXISTS 19-7 S_INCOMPAT 19-10
s_devGet function 11-42 S_INCOMPSERVER 19-11
s_devGetEx function 11-43 s_iniGet function 11-61
s_devModify function 11-44 s_iniGetPrivate function 11-63
s_devModifyEx function 11-45 s_iniSet function 11-65
S_DPLDBLOVF 19-7 s_iniSetPrivate function 11-66

S_INSUFFNETRES 19-11 S_NOCR 19-16
S_INVADDR 19-11 S_NODB 19-16
S_INVAMTTHRDS 19-11 S_NODBERR 19-16
S_INVDB 19-11 S_NODBFEXISTS 19-16
S_INVDOUB 19-11 S_NODEV 19-16
S_INVELEM 19-11 S_NOEM 19-16
S_INVEM 19-11 S_NOFILE 19-16
S_INVFCN 19-12 S_NOLOCK 19-16
S_INVFLD 19-12 S_NOLOGIN 19-17
S_INVFLOAT 19-12 S_NOMARK 19-17
S_INVMEM 19-12 S_NOMEMORY 19-17
S_INVMODE 19-12 S_NOSPACE 19-17
S_INVNULL 19-12 S_NOSVNAME 19-17
S_INVOWN 19-12 S_NOSYSNULLS 19-17
S_INVPARM 19-12 S_NOT_STARTED 19-17
S_INVREC 19-12 S_NOTATTACHED 19-18
S_INVSESS 19-13 S_NOTBASEFILE 19-18
S_INVSESSID 19-13 S_NOTCON 19-18
S_INVSET 19-13 S_NOTFOUND 19-18
S_INVSORT 19-13 S_NOTGRANTED 19-18
S_INVSVRNAME 19-13 S_NOTKEY 19-18
S_ISCOMKEY 19-13 S_NOTLOCKED 19-18
S_ISMEM 19-13 S_NOTONLIST 19-18
S_ISOWNED 19-14 S_NOTOPTKEY 19-19
s_keybuildBegin function 2-24, 11-67 S_NOTRANS 19-19
S_KEYREQD 19-14 S_NOTYPE 19-19
S_KEYSEQ 19-14 S_NOUSER 19-19
S_LOADMODULE 19-14 S_OKAY 19-19
S_LOCKED 19-14 S_ONLIST 19-19
S_LOCKLIMIT 19-14 S_OPENDBLIMIT 19-19
s_log function 11-69 S_OPENED 19-19
s_login function 11-70 S_OWNEXIST 19-20
s_logout function 11-71 S_PARMEND 19-20
S_LONGNAME 19-14 S_PARMINTERR 19-20
S_LONGPATH 19-15 S_PASSWORD 19-20
S_NCPENCERROR 19-15 S_PATHEXISTS 19-20
S_NCPINVSTATE 19-15 s_ping function 11-72
S_NINTERR 19-15 S_PRIV 19-20
S_NOCATALOG 19-15 S_PROGRAM 19-20
S_NOCM 19-15 S_READONLY 19-20
S_NOCMPFUNC 19-15 S_RPCENDOFPARMS 19-20
S_NOCO 19-15 S_RPCINTERR 19-21
S_NOCONFIG 19-15 S_RPCINVDATAITEM 19-21

S_RPCINVDATATYPE 19-21 S_VOIDTX 19-24
S_RPCINVFCN 19-21 schemas
S_RPCINVSESSID 19-21 compiling (Core DDL) 2-19
S_RPCSESSDISC 19-21 compiling (Velocis SQL) 2-37
S_SESDISCON 19-21 SCR_SCROLL_STATIC 12-89
S_SESREJECT 19-21 sddlp utility 2-37
S_SETCLASH 19-22 SDWORD data type 18-4
s_setMinFreeSpace function 11-74 SeBase class
s_setTimeout function 11-75 ~SeBase destructor 17-13
s_showBackupFiles function 11-76 AllocateNewTag method 17-14
s_showDbFiles function 11-78 constructor and destructor 17-13
s_showDbs function 11-80 delete operator 17-14
s_showDbUsers function 11-81 FreeMemory method 17-14
s_showDevs function 11-83 FreeTagMemory method 17-15
s_showEms function 11-84 GetContext method 17-15
s_showUserDbs function 11-85 GetErrorCode method 17-15
s_showUsers function 11-87 GetMemory method 17-15
s_shutdown function 11-88 GetMemoryTag method 17-15
s_startRPCThreads function 11-89 GetStatus method 17-16
s_startup function 11-91 IsServer method 17-16
S_STATIC 19-22 LogWrite method 17-16
s_statistics function 11-94 methods 17-14
S_SVRUNAVAIL 19-22 new operator 17-13
s_terminate function 11-98 Okay method 17-16
S_TOOMANYEMS 19-22 operators 17-13
S_TRACTIVE 19-22 overview 17-12
S_TRANSID 19-22 SeBase constructor 17-13
S_TRFREE 19-22 status codes 17-1
S_TRNOTACT 19-22 SeBase::~SeBase destructor 17-13
S_TXTIMEOUT 19-23 SeBase::AllocateNewTag method 17-14
S_UNAVAIL 19-23 SeBase::FreeMemory method 17-14
S_UNCOMMITED 19-23 SeBase::FreeTagMemory method 17-15
S_UNREGEM 19-23 SeBase::GetContext method 17-15
S_UPGDEN 19-23 SeBase::GetErrorCode method 17-15
s_userAdd function 11-99 SeBase::GetMemory method 17-15
s_userDel function 11-100 SeBase::GetMemoryTag method 17-15
S_USEREXISTS 19-23 SeBase::GetStatus method 17-16
s_userGet function 11-101 SeBase::IsServer method 17-16
S_USERLIMIT 19-23 SeBase::LogWrite method 17-16
S_USERMEMS 19-24 SeBase::Okay method 17-16
s_userModify function 11-102 SeBase::operator delete 17-14
S_USERNAME 19-24 SeBase::operator new 17-13
s_version function 11-103 SeBase::SeBase constructor 17-13

SEEK_CUR 9-20 server extensions
SEEK_END 9-20 customized comparison functions
SEEK_SET 9-20 (cmp prefix) 5-1
seeking positions in resource manager extension module functions 7-1
files 10-24 filters, SQL import and export 8-1
semaphores user-defined functions (UDFs), SQL
creating 10-66 14-1
deleting 10-68 user-defined procedures (UDPs), SQL
event 10-66, 10-75, 10-77, 10-78 15-1
handles 10-66 server installation utility (NT only) 2-23
mutex 10-66, 10-72, 10-73 server utilities
quiescent 10-66, 10-69, 10-71, 10-74, instrds (NT only) 2-23
10-76, 10-79 rds 2-27
semaphores, event ServerExtension class 17-17
resuming 10-75 ~ServerExtension destructor 17-19
starting 10-77 Attach method 17-19
waiting to resume 10-78 constructor and destructor 17-17
semaphores, mutex Detach method 17-20
entering exclusive access to 10-72 GetDescription method 17-20
exiting exclusive access to 10-73 GetHandle method 17-20
semaphores, quiescent GetSession method 17-20
disabling 10-69 Load method 17-21
enabling 10-71 methods 17-19
receiving permission to access 10-74 OnLoad method 17-21
sending exit notice for 10-76 Rpc method 17-23
waiting for completion of 10-79 ServerExtension constructor 17-17
sending exit notices for quiescent SetSession method 17-24
semaphores 10-76 Unload method 17-25
sending messages to the Velocis ServerExtension::~ServerExtension
message log 10-49 destructor 17-19
server connection handles ServerExtension::Attach method 17-19
freeing 12-50 ServerExtension::Detach method 17-20
overview 12-3 ServerExtension::GetDescription
server extension toolkit method 17-20
classes 17-1 ServerExtension::GetHandle method
DataDescriptor class 17-1 17-20
macros 17-26 ServerExtension::GetSession method
overview 17-1 17-20
ParmReceive class 17-4 ServerExtension::Load method 17-21
ParmSend class 17-9 ServerExtension::OnLoad method 17-21
SeBase class 17-12 ServerExtension::Rpc method 17-23
ServerExtension class 17-17 ServerExtension::ServerExtension
status codes 17-1 constructor 17-17

ServerExtension::SetSession method SQLColumns 12-19
17-24 SQLConnect 12-21
ServerExtension::Unload method 17-25 SQLConnectWith 12-22
session handles SQLDbaToRowId 12-23
overview 1-3 SQLDBHandle 12-24
retrieving 13-10 SQLDescribeCData 12-25
SeStatus enumeration 17-1 SQLDescribeCol 12-27
set SQLDescribeParam 12-29
finding first member 6-57 SQLDescribeStmt 12-30
finding last member 6-58 SQLDisconnect 12-32
finding next member 6-59 SQLDriverConnect 12-34
finding previous member 6-60 SQLError 12-35
freeing instance lock 6-30 SQLExecDirect 12-37
set locks 18-16, 18-17 SQLExecute 12-38
set type lock SQLExtendedFetch 12-41
freeing 6-132 SQLExtendedTransact 12-43
requesting 6-133 SQLFetch 12-45
setjmp function 10-3 SQLForeignKeys 12-46
SEToolkit See server extension toolkit SQLFreeCData 12-49
setting local variable values 10-53 SQLFreeConnect 12-50
setting private configuration file SQLFreeEnv 12-51
variable values 10-48 SQLFreeStmt 12-52
setting server configuration (velocis.ini) SQLGetConnectOption 12-53
variable values 10-47 SQLGetCursorName 12-55
shutting down customized comparison SQLGetData 12-56
function modules 5-6 SQLGetFunctions 12-59
shutting down the resource manager SQLGetInfo 12-60
10-6 SQLGetStmtOption 12-61
slot numbers 6-52 SQLGetTypeInfo 12-66
sort by clause and d_recwrite 6-112 SQLKill 12-67
SQL API functions SQLMoreResults 12-68
data value container structure SQLNativeSql 12-69
(VALUE) 18-27 SQLNumParams 12-70
overview 12-1 SQLNumResultCols 12-71
SQLAllocCData 12-2 SQLParamData 12-72
SQLAllocConnect 12-3 SQLPrepare 12-73
SQLAllocEnv 12-4 SQLPrimaryKeys 12-74
SQLAllocStmt 12-5 SQLProcedures 12-76
SQLBindCol 12-7 SQLPutData 12-78
SQLBindParameter 12-10 SQLRowCount 12-79
SQLCancel 12-12 SQLRowDba 12-80
SQLCDataColumn 12-13 SQLRowId 12-81
SQLColAttributes 12-15 SQLRowIdToDba 12-82

SQLSessionId 12-83 SQL import and export filters See filters,
SQLSetCData 12-84 SQL import and export
SQLSetConnectOption 12-85 SQL interactive testing 2-29
SQLSetCursorName 12-86 SQL return codes See Also return codes
SQLSetParam 12-87 detailed 19-26
SQLSetPos 12-88 overview 19-25
SQLSetScrollOptions 12-89 standard 19-25
SQLSetStmtOption 12-91 SQL statement handles
SQLShowPlan 12-92 allocating 12-5
SQLSpecialColumns 12-96 freeing 12-52
SQLStatistics 12-98 SQL statements
SQLTables 12-101 cancelling (from another connection)
SQLTransact 12-103 12-67
SQLTransactTrigger 12-104 cancelling (from same connection)
SQLWhenever 12-109 12-12
SQL data types determining type 13-4
c_data 18-6 executing after preparation 12-38
char 18-5 executing directly 12-37
date 18-6 getting statement type 12-30
decimal 18-5 SQL UDF support functions
double 18-5 SYSDbaToRowId 13-2
float 18-5 SYSDBHandle 13-3
integer 18-5 SYSDescribeStmt 13-4
long varbinary 18-6 SYSHandle 13-5
long varchar 18-6 SYSMemoryTag 13-6
long wvarchar 18-6 SYSRowDba 13-7
real 18-5 SYSRowId 13-8
rowid 18-6 SYSRowIdToDba 13-9
smallint 18-5 SYSSessionId 13-10
time 18-6 SYSVAlAdd 13-11
timestamp 18-6 SYSValChgSign 13-12
varchar 18-5 SYSValCompare 13-13
wchar 18-6 SYSValConvert 13-14
wvarchar 18-6 SYSValDiv 13-15
SQL data value container structure SYSValMult 13-16
(VALUE) 18-27 SYSValSub 13-17
SQL database schema compiling utility SQL UDF support functions (SYS prefix)
2-37 13-1
SQL date/time manipulation functions SQL UDFs See user-defined functions
See date/time manipulation (UDFs), SQL
functions, SQL SQL UDPs See user-defined procedures
SQL decimal value manipulation (UDPs), SQL
functions (BCD prefix) 3-1

SQL user-defined functions See user- SQL_C_TIME data type indicator 18-7
defined functions (UDFs), SQL SQL_C_TIMESTAMP data type
SQL user-defined procedures See user- indicator 18-7
defined procedures (UDPs), SQL SQL_C_WCHAR data type indicator
SQL value manipulation return codes 18-7
19-48 SQL_CALENDAR 12-61
SQL values SQL_CDATA data type indicator 18-6,
adding (from server-side UDF) 13-11 18-7
changing signs of (from server-side SQL_CHAR data type indicator 18-5,
UDF) 13-12 18-7
comparing (from server-side UDF) SQL_CLOSE 12-52
13-13 SQL_COLUMN_AUTO_INCREMENT
converting types (from server-side 12-15
UDF) 13-14 SQL_COLUMN_CASE_SENSITIVE
dividing (from server-side UDF) 12-15
13-15 SQL_COLUMN_COUNT 12-16
multiplying (from server-side UDF) SQL_COLUMN_DISPLAY_SIZE 12-16
13-16 SQL_COLUMN_LABEL 12-16
subtracting (from server-side UDF) SQL_COLUMN_LENGTH 12-16
13-17 SQL_COLUMN_MONEY 12-16
SQL_ return codes 19-25 SQL_COLUMN_NAME 12-16
SQL_ACCESS_MODE 12-53 SQL_COLUMN_NULLABLE 12-16
SQL_ALL_EXCEPT_LIKE 12-17 SQL_COLUMN_OWNER_NAME 12-16
SQL_API_ALL_FUNCTIONS 12-59 SQL_COLUMN_PRECISION 12-17
SQL_AUTOCOMMIT 12-53 SQL_COLUMN_QUALIFIER_NAME
SQL_AUTOCOMMIT_OFF 12-53 12-17
SQL_AUTOCOMMIT_ON 12-53 SQL_COLUMN_SCALE 12-17
SQL_BEGIN 12-43 SQL_COLUMN_SEARCHABLE 12-17
SQL_BIND_BY_COLUMN 12-61 SQL_COLUMN_TABLE_NAME 12-17
SQL_BIND_BY_ROW 12-61 SQL_COLUMN_TYPE 12-17
SQL_BIND_TYPE 12-61 SQL_COLUMN_TYPE_NAME 12-17
SQL_C_BINARY data type indicator SQL_COLUMN_UNSIGNED 12-17
18-7 SQL_COLUMN_UPDATABLE 12-18
SQL_C_CHAR data type indicator 18-7 SQL_COMMIT 12-43, 12-103
SQL_C_DATA data type indicator 18-7 SQL_CONCUR_LOCK 12-61
SQL_C_DATE data type indicator 18-7 SQL_CONCURRENCY 12-61
SQL_C_DEFAULT 12-6 SQL_CURSOR_TYPE 12-62
SQL_C_DOUBLE data type indicator SQL_DATE data type indicator 18-6,
18-7 18-7
SQL_C_FLOAT data type indicator 18-7 SQL_DECIMAL 18-29
SQL_C_LONG data type indicator 18-7 SQL_DECIMAL data type indicator
SQL_C_SHORT data type indicator 18-7 18-5, 18-7

SQL_DEFAULT_PARAM 12-10 SQL_NULL_DATA 12-10
SQL_DOUBLE data type indicator 18-5, SQL_OPT_TRACE 12-54
18-7 SQL_OPT_VENDOR 12-54
SQL_DRIVER_COMPLETE 12-33 SQL_PARAM_INPUT 12-9
SQL_DRIVER_COMPLETE_REQUIRED SQL_PARAM_INPUT_OUTPUT 12-9
12-34 SQL_PARAM_OUTPUT 12-9
SQL_DRIVER_NOPROMPT 12-33 SQL_PARAMREF 12-11
SQL_DRIVER_PROMPT 12-33 SQL_QUERY_TIMEOUT 12-64
SQL_DROP 12-52 SQL_REAL data type indicator 18-5,
SQL_ERROR 19-25 18-7
SQL_FETCH_ABSOLUTE 12-39, 12-41 SQL_RESET_PARAMS 12-52
SQL_FETCH_BOOKMARK 12-39 SQL_ROLLBACK 12-43, 12-103
SQL_FETCH_CHUNKSIZE 12-62 SQL_ROW_ADDED 12-40
SQL_FETCH_FIRST 12-39 SQL_ROW_DELETED 12-40
SQL_FETCH_LAST 12-39, 12-41 SQL_ROW_ERROR 12-40
SQL_FETCH_MAXBLOB 12-63 SQL_ROW_NOROW 12-40
SQL_FETCH_NEXT 12-39 SQL_ROW_SUCCESS 12-41
SQL_FETCH_PREV 12-40 SQL_ROW_UPDATED 12-41
SQL_FETCH_PRIOR 12-40 SQL_ROWID data type indicator 18-6,
SQL_FETCH_RELATIVE 12-40 18-7
SQL_FETCH_USECHUNK 12-63 SQL_ROWSET_SIZE 12-64
SQL_FLOAT data type indicator 18-5, SQL_SCROLL_FORWARD_ONLY
18-7 12-89
SQL_GET_BOOKMARK 12-64 SQL_SEARCHABLE 12-17
SQL_INTEGER data type indicator 18-5, SQL_SMALLINT data type indicator
18-7 18-5, 18-7
SQL_INVALID_HANDLE 19-25 SQL_SUCCESS 19-25
SQL_LEN_DATA_AT_EXEC 12-10 SQL_SUCCESS_WITH_INFO 19-26
SQL_LIKE_ONLY 12-17 SQL_TIME data type indicator 18-6,
SQL_LOGIN_TIMEOUT 12-54 18-7
SQL_LONGVARBINARY data type SQL_TIMESTAMP data type indicator
indicator 18-6, 18-7 18-6, 18-7
SQL_LONGVARCHAR data type SQL_TXN_ISOLATION 12-54
indicator 18-6, 18-7 SQL_TXN_READ_COMMITTED
SQL_MARK 12-43 12-54
SQL_MAX_ROWS 12-64 SQL_TXN_READ_UNCOMMITTED
SQL_NEED_DATA 19-25 12-54
SQL_NO_DATA_FOUND 19-25 SQL_TXN_REPEATABLE_READ 12-54
SQL_NOSCAN 12-64 SQL_TXN_REPEATABLE_UNCOM-
SQL_NOSCAN_OFF 12-64 MITTED 12-54
SQL_NOSCAN_ON 12-64 SQL_UNBIND 12-52
SQL_NTS 12-10 SQL_UNSEARCHABLE 12-17

SQL_USE_BOOKMARKS 12-64 SQLFetch function 12-45
SQL_VARCHAR data type indicator SQLForeignKeys function 12-46
18-5, 18-7 SQLFreeCData function 12-49
SQL_WCHAR data type indicator 18-6, SQLFreeConnect function 12-50
18-7 SQLFreeEnv function 12-51
SQL_WLONGVARCHAR data type SQLFreeStmt function 2-35, 12-52
indicator 18-6, 18-7 SQLGetConnectOption function 12-53
SQL_WVARCHAR data type indicator SQLGetCursorName function 12-55
18-6, 18-7 SQLGetData function 12-56
SQL_ZERODIV 19-26 SQLGetFunctions function 12-59
SQLAllocCData function 12-2 SQLGetInfo function 12-60
SQLAllocConnect SQLGetStmtOption function 12-61
and SQLAllocEnv 12-4 SQLGetTypeInfo function 12-66
and SQLConnect 12-21 SQLKill function 12-67
summary 12-3 SQLMoreResults function 12-68
SQLAllocEnv SQLNativeSql function 12-69
and SQLAllocConnect 12-3 SQLNumParams function 12-70
summary 12-4 SQLNumResultCols function 12-71
SQLAllocStmt function 12-5 SQLParamData function 12-72
SQLBindCol function 12-7 SQLPrepare function 2-35, 12-73
SQLBindParameter function 12-10 SQLPrimaryKeys function 12-74
SQLCancel function 12-12 SQLProcedures function 12-76
SQLCDataColumn function 12-13 SQLPutData function 12-78
SQLColAttributes function 12-15 SQLRowCount function 12-79
SQLColumns function 12-19 SQLRowDba function 12-80
SQLConnect function SQLRowId function 12-81
and SQLAllocConnect 12-3 SQLRowIdToDba function 12-82
and SQLConnectWith 12-22 SQLSessionId function 12-83
summary 12-21 SQLSetCData function 12-84
SQLConnectWith function 12-22 SQLSetConnectOption function 12-85
SQLDbaToRowId function 12-23 SQLSetCursorName function 12-86
SQLDBHandle function 12-24 SQLSetParam function 12-87
SQLDescribeCData function 12-25 SQLSetPos function 12-88
SQLDescribeCol function 12-27 SQLSetScrollOptions function 12-89
SQLDescribeParam function 12-29 SQLSetStmtOption function 12-91
SQLDescribeStmt function 12-30 SQLShowPlan function 12-92
SQLDisconnect function 12-32 SQLSpecialColumns function 12-96
SQLDriverConnect function 12-34 SQLStatistics function 12-98
SQLError function 12-35 SQLTables function 12-101
SQLExecDirect function 12-37 SQLTransact function 12-103
SQLExecute function 2-35, 12-38 SQLTransactTrigger function 12-104
SQLExtendedFetch function 2-33, 12-41 SQLWhenever function 12-109
SQLExtendedTransact function 12-43 sqlxdefs.h header file 16-1

standard return codes 19-1 LoadFailure 17-1
starting event semaphores 10-77 RPCError 17-1
starting the resource manager 10-62 Success 17-1
STAT_CHECKPOINTS 11-96 UnloadFailure 17-1
STAT_CHGLOG_WRITE 11-96 stdout 2-26
STAT_CHGLOGS 11-96 STLOCK lock mode indicator 18-17
STAT_CHGLOGS_BYTES_WRITE storing rows in SQL export filters 8-12
11-96 streaming files, resource manager See
STAT_CLIENT_ABORTS 11-97 files, resource manager stream
STAT_CLOSE_CHGLOG 11-96 structures See also data types
STAT_CLOSE_DB_TABLES 11-94 BCD_Z 3-1, 18-4
STAT_CLOSE_DBS 11-95 CMPLOADTABLE 5-1, 5-2, 18-8
STAT_D_FCN_CALLS 11-97 DATE_STRUCT 16-1, 18-9
STAT_DBERRS 11-97 dbase 18-10
STAT_FREED_LOCKS 11-95 DBD_DBF 18-2, 18-11
STAT_GROUP_LOCK_BLOCKED device 18-2, 18-12
11-95 EM_CHG 18-2, 18-13
STAT_GROUP_LOCK_REQ 11-95 EMLOADTABLE 7-4, 18-14
STAT_GROUP_LOCK_TIMEOUT 11-95 FILEDEV 18-2, 18-15
STAT_INST_READ_LOCKS 11-95 GROUPLOCK 18-16
STAT_INST_WRITE_LOCKS 11-95 IEFLOADTABLE 8-1, 8-5, 18-18
STAT_LOGINS 11-96 overview 18-8
STAT_LOGOUTS 11-96 PL_ITEM 18-19
STAT_NORM_REQUESTS 11-97 TIME_STRUCT 16-1, 18-21
STAT_OPEN_CHGLOG 11-96 TIMESTAMP_STRUCT 16-1, 18-22
STAT_OPEN_DB_TABLES 11-94 TIMESTAMP_VAL 18-4
STAT_OPEN_DBS 11-95 UDFLOADTABLE 14-1, 14-5, 18-23
STAT_PGZERO_READ 11-94 UDPLOADTABLE 15-1, 15-5, 18-24
STAT_PGZERO_WRITE 11-94 userinf 18-25
STAT_PIGGYBACKS 11-96 USERINF_CHG 18-2, 18-26
STAT_PRI_REQUESTS 11-97 VALUE 13-1, 14-1, 15-1, 18-4, 18-27
STAT_REQUESTS 11-96 VALUE_DESCR 8-1, 18-29
STAT_TABLE_READ_LOCKS 11-95 subtracting binary-coded decimals 3-12
STAT_TABLE_WRITE_LOCKS 11-95 subtracting SQL values (from server-
STAT_TRABORTS 11-95 side UDF) 13-17
STAT_TRBEGINS 11-95 Success status code 17-1
STAT_TRENDS 11-95 suspending threads 10-61
STAT_TRROLLBACKS 11-96 SWORD data type 18-4
status codes, server extension toolkit synchronization objects See semaphores
AttachFailure 17-1 synchronizing resource manager files
DetachFailure 17-1 10-34
InvalidData 17-1 SYS_COMMIT_EVERY 12-104
InvalidSize 17-1 SYS_COMMIT_ONCE 12-104

SYSDbaToRowId function 13-2 threads, operating system
SYSDBHandle function 13-3 beginning 10-80
SYSDescribeStmt function 13-4 ending 10-82
SYSHandle function 13-5 suspending 10-61
SYSMemoryTag function 13-6, 14-9 TIME_STRUCT structure 16-1, 18-21
SYSRowDba function 13-7 TIME_VAL data type 16-1, 18-4
SYSRowId function 13-8 times
SYSRowIdToDba function 13-9 converting from ODBC to Velocis
SYSSessionId function 13-10 format 16-3
system administration utility 2-28 converting from Velocis to ODBC
system administration utility (Windows format 16-6
only) 2-2 SQL/ODBC structure
system handles, retrieving 13-5 (TIME_STRUCT) 18-21
SYSVAlAdd function 13-11 TIMESTAMP_STRUCT structure 16-1,
SYSValChgSign function 13-12 18-22
SYSValCompare function 13-13 TIMESTAMP_VAL data type 16-1
SYSValConvert function 13-14 TIMESTAMP_VAL structure 18-4
SYSValDiv function 13-15 timestamps
SYSValMult function 13-16 converting from ODBC to Velocis
SYSValSub function 13-17 format 16-4
converting from Velocis to ODBC
T
format 16-7
tables SQL/ODBC structure
foreign keys in 12-46 (TIMESTAMP_STRUCT) 18-22
listing indexes defined for 12-98 toolkit, dbrepair See dbrepair toolkit
locks, freeing 6-114 toolkit, server extension (C++ API) See
tags, dynamic memory server extension toolkit
allocating 10-3 transactions
allocating memory and copying aborting 6-137
strings for 10-65 begining 6-139
creating 10-7 determining if active 6-138
freeing or deallocating associated ending 6-141
memory 10-39 marking 6-142
resetting jump buffers 10-60 processing (SQL) 12-103
retrieving (from server-side UDF) rolling back 6-139, 6-143
13-6 transaction statistics (SQL) 11-95
retrieving allocated memory sizes for transaction triggers, registering 12-104
10-50 transaction type indicators (SQL)
retrieving amounts of available SQL_COMMIT 12-103
memory 10-51 SQL_ROLLBACK 12-103
testing Velocis SQL interactively 2-29

type checking, data user information structure (userinf)
filters, SQL import and export 8-2 18-25
user-defined functions, SQL 14-2 usercmp.c source file 5-1
user-defined procedures, SQL 15-2 usercmp.h header file 5-1
user-defined (SQL) function load tables
U
18-23
UCHAR data type 18-4 user-defined (SQL) procedure load
UDF See user-defined functions (UDFs), tables 18-24
SQL user-defined function (UDF) module
UDF load tables 14-1, 14-5 functions, SQL
UDF module functions See user-defined udfCheck 14-2
function (UDF) module functions, udfCleanup 14-4
SQL udfDescribeFcns 14-5
udfCheck function 14-2 udfFunc 14-7
udfCleanup function 14-4 udfInit 14-9
udfDescribeFcns function 14-5 udfReset 14-11
udfFunc function 14-7 user-defined function (UDF) module
udfInit function 14-9 functions, SQL (udf prefix) 14-1
UDFLOADTABLE structure 14-1, 14-5, user-defined functions (UDFs), SQL
18-23 checking parameter data types 14-2
udfReset function 14-11 cleaning up after 14-4
UDP See user-defined procedures implementing 14-7
(UDPs), SQL initializing 14-9
UDP load tables 15-1, 15-5 performing processing for 14-7
UDP module functions See user-defined registering 14-5
procedure (UDP) module functions, resetting running values for
SQL (aggregate UDFs only) 14-11
udpCheck function 15-2 user-defined procedure (UDP) module
udpCleanup function 15-4 functions, SQL
udpDescribeFcns function 15-5 udpCheck 15-2
udpExecute function 15-7 udpCleanup 15-4
udpInit function 15-10 udpDescribeFcns 15-5
UDPLOADTABLE structure 15-1, 15-5, udpExecute 15-7
18-24 udpInit 15-10
udpMoreResults function 15-12 udpMoreResults 15-12
UDWORD data type 18-4 user-defined procedure (UDP) module
UnloadFailure status code 17-1 functions, SQL (udp prefix) 15-1
unloading extension modules 7-14 user-defined procedures (UDPs), SQL
unpacking (converting to string) binary- checking parameter data types 15-2
coded decimals 3-13 cleaning up after 15-4
user information and device structure executing 15-7, 15-12
(USERINF_CHG) 18-26 implementing 15-7, 15-12

initializing 15-10 VAL_TOOSMALL 19-48
obtaining subsequent result sets for valerrs.h header file 3-1, 16-1
15-12 validating resource manager files 10-35
obtaining the first result set for 15-7 VALPackDate function 16-2
registering 15-5 VALPackTime function 16-3
userinf structure 18-25 VALPackTimeStamp function 16-4
USERINF_CHG structure 18-2, 18-26 VALUE structure 13-1, 14-1, 15-1, 18-4,
User’s Guide 1-4 18-27
utilities, Velocis VALUE_DESCR structure 8-1, 18-29
admin (Velocis Administrator for VALUnpackDate function 16-5
Windows) 2-2 VALUnpackTime function 16-6
dbcheck 2-3 VALUnpackTimestamp function 16-7
dbdefrag 2-5 variables, environment 10-40
dbfix 2-7 variables, local
dbimp 2-9 retrieving values of 10-43
dbreplay 2-13 setting values for 10-53
dbstat 2-15 variables, private configuration file
dchain 2-17 retrieving values of 10-46
ddlproc 2-19 setting values for 10-48
getting help for 2-1 variables, server configuration
instodbc 2-22 (velocis.ini)
instrds (NT only) 2-23 retrieving values of 10-45
keybuild 2-24 setting values for 10-47
prdbd 2-26 Velocis
rds 2-27 converting dates from ODBC format
rdsadm 2-28 16-2
rsql 2-29 converting dates to ODBC format
sddlp 2-37 16-5
vping 2-39 converting times from ODBC format
utilities, client See client utilities 16-3
utilities, server See server utilities converting times to ODBC format
UWORD data type 18-4 16-6
converting timestamps from ODBC
V
format 16-4
VAL_ return codes 16-1, 19-48 converting timestamps to ODBC
VAL_BADENV 19-48 format 16-7
VAL_INVALID 19-48 database server utility 2-27
VAL_NOMEM 19-48 installing servers (NT only) 2-23
VAL_OKAY 19-48 introduction 1-1
VAL_OVERFLOW 19-48 related documentation 1-4
VAL_OVERLOSS 19-48 testing 2-39
VAL_PRECLOSS 19-48

Velocis Administrator utility (Windows W
only) 2-2 waiting for completion of quiescent
Velocis documentation See semaphores 10-79
documentation, Velocis waiting to resume event semaphores
Velocis SQL 10-78
column attribute types 12-16 Windows 6-120
column information result set 12-20 Windows NT and Velocis as a service
testing interactively 2-29 2-23
Velocis SQL database schema compiling write locks
utility 2-37 downgrading 6-117
Velocis testing utility 2-39 freeing 6-114
Velocis utilities See utilities, Velocis writing lines to resource manager
velocis.ini 10-45, 10-47 stream files 10-32
and s_iniGet 11-61 writing messages to queues 10-59
and s_iniGetPrivate 11-63 writing to certain locations in resource
and s_iniSet 11-65 manager files 10-26
modifying 2-2 writing to current positions in resource
vping utility 2-39 manager files 10-36

Guia Oficial N°07. Vel30RM

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Guia Oficial N°07. Vel30RM

Uploaded by

Copyright:

Available Formats

Velocis

ii Centura Velocis Reference Manual

iv Centura Velocis Reference Manual

1.1 Velocis Documentation

1.1.1 About This Manual

1-2 Centura Velocis Reference Manual

1.1.2 About the Function References in this Manual

1.1.3 Related Velocis Documents

1-4 Centura Velocis Reference Manual

Table 1-1. Document Notational Conventions

Bold Text Indicates the names of functions, data structures,

1.2 Other Helpful Resources

1-6 Centura Velocis Reference Manual

Velocis Utilities 2-1

admin Windows-based administration utility

Note: Velocis Administrator is a GUI-based utility that is available

See Also rdsadm

2-2 Centura Velocis Reference Manual

dbcheck Database consistency check utility

Command -? | -h Displays the usage information for the utility.

Velocis Utilities 2-3

-p pages Defines the number of pages in the dbrepair server

See Also s_dbcheckBegin

2-4 Centura Velocis Reference Manual

dbdefrag Data file compression utility

Command -? | -h Displays the usage information for the utility.

Velocis Utilities 2-5

-q Specifies quick mode, in which the utility does not

See Also s_dbdefragBegin

2-6 Centura Velocis Reference Manual

dbfix Database repair utility

Command -? | -h Displays the usage information for the utility.

Velocis Utilities 2-7

3 = Detailed user report and summary system report

See Also s_dbfixBegin

2-8 Centura Velocis Reference Manual

dbimp Database import utility

Command -? | -h Displays the usage information for the utility.

The Language Summary section describes the commands that can

Velocis Utilities 2-9

Language Import Specification:

2-10 Centura Velocis Reference Manual

See Also Chapter 9, Velocis User’s Guide

Velocis Utilities 2-11

2-12 Centura Velocis Reference Manual

dbreplay Backup restore and roll-forward utility

Command -? | -h Displays the usage information for the utility.

Velocis Utilities 2-13

Note: If recovery is necessary because of media failure, you can

See Also s_backupBegin

2-14 Centura Velocis Reference Manual

dbstat Database analysis utility

Command -? | -h Displays the usage information for the utility.

Description The dbstat utility is a Velocis extension module that helps

Velocis Utilities 2-15

information for all databases registered in the catalog. The utility

Note: Use the numbers in the generated table to determine how

See Also s_dbstat

2-16 Centura Velocis Reference Manual

dchain Delete chain repair utility

Command -? | -h Displays the usage information for the utility.

Velocis Utilities 2-17

-n Produces the report of all modifications, without

See Also s_dchainBegin