VAX Rdb/VMS
Online Release Notes for SQL/Services
November 1990
This online document contains the release notes for SQL/Services,
a client/server software component of Rdb/VMS Version 4.0.
OPERATING SYSTEM: VMS
SOFTWARE VERSION: VAX Rdb/VMS V4.0
Digital Equipment Corporation
__________
Copyright ©1990
The following are trademarks of Digital Equipment Corporation:
ALL-IN-1, CDD/Plus, DEC, DEC/CMS, DECdecision, DECdtm, DECforms,
DECintact, DEC/MMS, DECnet, DECtp, DECtrace, DECwindows, MicroVAX,
ULTRIX, UNIBUS, VAX, VAX ACMS, VAX Ada, VAX BASIC, VAX C, VAX
CDD, VAXcluster, VAX COBOL, VAX DATATRIEVE, VAX DBMS, VAXELN, VAX
FMS, VAX FORTRAN, VAX Pascal, VAX RALLY, VAX Rdb/ELN, VAX Rdb/VMS,
VAX SPM, VAXstation, VAX TEAMDATA, VIDA, VMS, VT, and the DIGITAL
Logo.
IBM is a registered trademark of International Business Machines
Corporation; OS/2 is a trademark of International Business
Machines Corporation. Macintosh is a trademark of Apple Computer,
Inc. MS-DOS is a registered trademark of Microsoft Corporation;
This document was prepared using VAX DOCUMENT, Version 1.2
Contents
PREFACE v
CHAPTER 1 NEW FEATURES, TECHNICAL CHANGES, AND GENERAL NOTES 1-1
1.1 NEW FEATURES AND TECHNICAL CHANGES 1-1
1.2 GENERAL NOTES 1-4
1.2.1 Online Versions of the SQL/Services Release
Notes 1-4
1.2.2 Caution Against Deleting the SQLSRV$SRV
Account 1-4
1.2.3 Starting SQL/Services on Each Node of a
VAXcluster 1-5
1.2.4 DECnet Default File Access for SQL/Services 1-5
CHAPTER 2 SOFTWARE KNOWN PROBLEMS, RESTRICTIONS,
DOCUMENTATION ERRORS AND OMISSIONS 2-1
2.1 RESTRICTIONS 2-1
2.1.1 Using Group/System Rather Than Process Names 2-1
2.1.2 VMS Proxy Access to SQL/Services Server Is No
Longer Allowed 2-2
2.1.3 SERVER_LOG Parameter Is Not Supported 2-3
2.1.4 Filter Expressions in SQL/Services 2-3
2.1.5 SQLSRV_ASCII_STRING Data Type Is Not
Terminated with a NULL Character 2-3
2.1.6 Using the sqlsrv_fetch_many API Routine 2-4
2.1.7 SQL/Services V4.0 Server Uses Proxy-like and
Default Access to Authorize V3.0 or V3.1
Client Applications 2-4
2.1.8 Invalid Length Returned by SQLSRV_VARBYTE Data
Type 2-4
2.1.9 Allocating Space for SQLSRV_VARCHAR and
SQLSRV_VARBYTE Data Types 2-5
2.1.10 SQL/Services V4.0 Server Error (-2031)
Returned to V3.1 Client APIs 2-5
iii
Contents
2.1.11 Configuration File IDENT Keyword Not
Supported 2-6
2.1.12 TYPE Not CLASS Keyword Used in Configuration
File 2-6
2.2 DOCUMENTATION ERRORS AND OMISSIONS 2-6
2.2.1 SQLSRV$DEFAULT_ACCESS Logical Name Incorrectly
Documented 2-6
2.2.2 List Cursor SQLCA Return Values for
sqlsrv_open_cursor Routine 2-7
2.2.3 Documentation for sqlsrv_sqlca_sqlerrd
Routine 2-7
iv
_____________________________________________________________________
Preface
VAX Rdb/VMS Version 4.0, often referred to as Rdb/VMS in this
manual, is a general purpose database management system based on
the relational data model.
SQL/Services is a client/server software component of Rdb/VMS. It
allows application programs running on various types of comput-
ers to access Rdb/VMS or VIDA databases on other computers. For
example, an application program running on a Macintosh computer
(a client) can access an Rdb/VMS database on a VAX computer (a
server).
___________________________________________________________________
Purpose of This Manual
This online document describes new features, technical changes,
software problems and restrictions, documentation errors and
omissions, and other notes related to SQL/Services for Rdb/VMS
Version 4.0.
NOTE
The SQL/Services release notes are supplied both in
printed form in the VAX Rdb/VMS Release Notes and on-
line in SYS$HELP. The printed form of the releases notes
is prepared for production after the online form; thus,
information in the hardcopy version is more up-to-date.
___________________________________________________________________
Intended Audience
These release notes are intended for all users of SQL/Services.
v
Preface
___________________________________________________________________
Operating System Information
Information about the versions of the operating system and related
software that are compatible with this version of Rdb/VMS is
included in the Rdb/VMS media kit and the VAX Rdb/VMS Installation
Guide.
For information about the compatibility of other software products
with this version of Rdb/VMS, refer to the System Support Addendum
(SSA) that comes with the Software Product Description (SPD). You
can use the SPD/SSA to verify which versions of your operating
system are compatible with this version of Rdb/VMS.
___________________________________________________________________
Structure
This manual contains two chapters:
Chapter 1 Describes new features, technical changes, and
other general release notes about SQL/Services.
Chapter 2 Describes software problems and restrictions,
and documentation errors and omissions affecting
SQL/Services.
___________________________________________________________________
Related Manuals
The following manuals contain information related to SQL/Services.
o VAX Rdb/VMS Installation Guide
Describes how to install Rdb/VMS and SQL/Services Macintosh,
MS-DOS, OS/2, ULTRIX, ULTRIX for RISC, and VMS client
Application Programming Interface (API) software on remote
systems.
o VAX Rdb/VMS Guide to Using SQL/Services
vi
Preface
Explains how to develop application programs using SQL/Services.
Also, provides reference information about the API routines and
SQLCA and SQLDA structures used to develop client API applica-
tions.
___________________________________________________________________
Conventions
In examples, an implied carriage return occurs at the end of each
line. You must press the RETURN key at the end of a line of input.
The following convention is used in this manual:
$ The dollar sign represents the DIGITAL Command Language
prompt. This symbol indicates that the DCL interpreter
is ready for input.
___________________________________________________________________
References to Products
The Rdb/VMS documentation to which this document belongs often
refers to VAX Rdb/VMS software as Rdb/VMS.
vii
Chapter 1
New Features, Technical Changes, and General Notes
This chapter describes new features and technical changes in
SQL/Services for SQL/Services in Rdb/VMS Version 4.0. It also
provides general information to help you use SQL/Services.
1.1 New Features and Technical Changes
The new features and technical changes in SQL/Services for VAX
Rdb/VMS Version 4.0 include:
o Process Pooling
In previous versions of SQL/Services, the server on a VAX
computer created a VMS process and activated an image in that
process for each association request sent from the client
system. Process pooling software, introduced in this release,
provides a more efficient way of handling client application
requests. Using a multithreaded communications component and
an execution component consisting of pre-started, reusable
request processors, process pooling improves client application
response time (by increasing request throughput) and reduces
the load on server system resources.
o API Support
New Features, Technical Changes, and General Notes 1-1
SQL/Services has developed two new Application Programming
Interfaces (APIs), one for computers running the Macintosh
operating system and the other for computers using the IBM OS/2
operating system. The two APIs join the currently supported
MS-DOS, ULTRIX, ULTRIX for RISC, and VMS interfaces, bringing
to six the number of APIs that SQL/Services supports.
o API Routines
A new set of portable API routines provides a functional inter-
face to information previously accessed only by direct program
reference to the SQLCA and SQLDA structures. The functional
interface allows API programmers to write portable applications
across all client platforms, including Macintosh and OS/2. API
programmers can still use C language constructs to access SQLCA
and SQLDA structures directly on all platforms except on the
Macintosh. Digital recommends, however, that API application
programmers use the functional interface routines when develop-
ing applications with any of the supported APIs. There are two
primary reasons for this:
- To create fully portable applications for all API environ-
ments
- To make transparent for applications any future changes made
in the SQLCA and SQLDA structures
Finally, although at present SQL/Services allows direct access
to structures from all API environments except the Macintosh,
in the future Digital may provide access to structures through
API routines only.
o Server Access
SQL/Services API client applications can access the server
system by explicit, proxy-like, or default access. The current
release adds proxy-like and default access to the already
supported explicit access method. The two additional access
routes permit programmers (and nontechnical end users) more
convenient entry to SQL/Services. Your system management team
1-2 New Features, Technical Changes, and General Notes
can enable or disable either or both access avenues at any
time.
o List Cursors
SQL/Services now supports SQL list cursors (segmented strings),
an extension to SQL for Rdb/VMS Version 4.0. Enhancements to
the SQL/Services API for list cursors include:
- An explicit sqlsrv_declare_cursor routine
- Two new data types:
o SQLSRV_LIST_VARBYTE
o SQLSRV_VARBYTE
- Information in the SQLDA.SQLIND column and the SQLCA struc-
ture
The new sqlsrv_declare_cursor routine lets API programmers
explicitly name the cursor type (table or list) and the mode.
Table cursors let you specify three modes: update, read-only,
and insert-only. List cursors allow two modes: read-only and
insert-only. SQL/Services continues to implicitly declare
cursors as type table and mode update when an sqlsrv_open_
cursor routine is not preceded explicitly by an sqlsrv_declare_
cursor call.
o Two New Installation Questions
The Rdb/VMS Version 4.0 installation procedure displays two
new questions for SQL/Services. One question lets you choose a
User Identification Code (UIC) for the SQLSRV$SRV account, and
the other lets you name a device for the account. SQL/Services
creates the SQLSRV$SRV account to run the communication server
during request processing. It also uses the account during
installation to run the IVP.
o SQL/Services Help Available from DCL HELP Facility
New Features, Technical Changes, and General Notes 1-3
The DCL HELP facility now includes SQL/Services help informa-
tion. Type HELP SQL_SERVICES at the DCL command level prompt
for a brief introduction to SQL/Services and pointers to addi-
tional information.
1.2 General Notes
This section contains general information about using SQL/Services.
1.2.1 Online Versions of the SQL/Services Release Notes
The online version of the release notes for the SQL/Services
component of Rdb/VMS resides in the VMS SYS$HELP directory in
a file called SQLSRV$040.RELEASE_NOTES. The installation procedure
for each API copies these release notes to its client system. The
API appendixes in the VAX Rdb/VMS Installation Guide list where
the release notes are stored for each client API system.
1.2.2 Caution Against Deleting the SQLSRV$SRV Account
The SQL/Services SQLSRV$SRV account is created during the Rdb/VMS
installation procedure when you respond to the following question:
* Please enter UIC to be used for the SQLSRV$SRV account
(e.g. [ggg,mmm]:)
The UIC that you enter creates the VMS process context for the
SQLSRV$SRV account. At system startup time, SQL/Services invokes
in the SQLSRV$SRV account the executable image (SQLSRV$.EXE) for
the communication server. The SQL/Services system cannot start
without the process context provided by the SQLSRV$SRV account.
If the account is accidentally deleted, your system manager must
reinstall Rdb/VMS to recreate the SQLSRV$SRV account and then
restart SQL/Services manually with the following command:
$ @SYS$SYSTEM:SQLSRV$STARTUP.COM
1-4 New Features, Technical Changes, and General Notes
1.2.3 Starting SQL/Services on Each Node of a VAXcluster
The VAX Rdb/VMS Installation Guide describes in the section on
VAXcluster considerations how to have SQL/Services automatically
started on nodes in a VAXcluster. If at some point you decide not
to have SQL/Services running on one or more nodes in a cluster,
you can manually shut SQL/Services down without affecting the
operation of Rdb/VMS. Shut SQL/Services down at the DCL prompt
with the following command:
$ @SYS$STARTUP:SQLSRV$SHUTDOWN
Once SQL/Services is stopped on a node, you might want to comment
out the SQL/Services SQLSRV$STARTUP.COM startup command procedure
in the SQL$STARTUP.COM command procedure located in the Rdb/VMS
RMONSTART.COM file. This prevents SQL/Services from being automat-
ically started. The startup procedure for SQL, SQL/Services, and
Rdb/VMS resides in the SYS$STARTUP directory.
1.2.4 DECnet Default File Access for SQL/Services
If the initial transfer of a client installation file fails during
installation of API software, consult with your system manager to
ensure that your default DECnet account is correctly configured
for default file access. In addition, have your system manager
use the Network Control Program (NCP) to make sure that the server
node allows non-privileged access.
New Features, Technical Changes, and General Notes 1-5
Chapter 2
Software Known Problems, Restrictions, Documentation Errors and
Omissions
This chapter describes known problems and restrictions in the
software and documentation errors and omissions that affect
SQL/Services for Rdb/VMS Version 4.0.
2.1 Restrictions
This section describes the known problems and restrictions in
effect for this release of SQL/Services.
2.1.1 Using Group/System Rather Than Process Names
When you provide the file specification for an Rdb/VMS database
within the SQL/Services system, use one of the following methods
to specify a database:
o Include a group logical name.
o Use a system logical name.
o Provide a full file specification.
Process logical names are ignored in SQL/Services.
Software Known Problems, Restrictions, Documentation Errors and Omissions 2-1
Database file specifications are found in client API applications,
the SQL/Services sample application, or in configuration file
definitions.
2.1.2 VMS Proxy Access to SQL/Services Server Is No Longer Allowed
For security reasons, client API applications can no longer use
VMS proxy accounts to access the SQL/Services server system.
SQL/Services replaces VMS proxy access with two new server access
methods:
o Proxy-like access
SQL/Services provides its own proxy mechanism that you can
enable or disable as site security needs change. Your sys-
tem manager must add entries to the SQLSRV$PROXY.DAT file in
SYS$STARTUP to authorize access to SQL/Services. The system
manager can disable proxy access by deleting the SQLSRV$SRV
file, commenting out entries, or removing all entries.
o SQLSRV$SRV account
SQL/Services assigns a request to the SQLSRV$SRV account
when the request omits user name and password and when a
SQL/Services proxy access entry cannot be found for the re-
quest. You can disable use of the default account by re-
defining the SQLSRV$DEFAULT_ACCESS logical name in the
SQLSRV$STARTUP.COM file.
Refer to the VAX Rdb/VMS Guide to Using SQL/Services for informa-
tion about how applications can access SQL/Services.
2-2 Software Known Problems, Restrictions, Documentation Errors and Omissions
2.1.3 SERVER_LOG Parameter Is Not Supported
The SQL/Services SERVER_LOG parameter in the ASSOCIATE_STR struc-
ture is no longer supported. You can, however, still enable and
disable logging on the client system using the CLIENT_LOG parame-
ter of the ASSOCIATE_STR structure.
Refer to the VAX Rdb/VMS Guide to Using SQL/Services for further
information about the logging provided by SQL/Services.
2.1.4 Filter Expressions in SQL/Services
Filter expressions that contain two or more string or date scalar
functions return incorrect results in SQL/Services. This will be
fixed in a future release of Rdb/VMS.
2.1.5 SQLSRV_ASCII_STRING Data Type Is Not Terminated with a NULL
Character
SQL/Services does not terminate, with a trailing NULL charac-
ter, variables declared as data type SQLSRV_ASCII_STRING. To use
standard C library functions, you must (in your applications) ter-
minate (with a NULL character) all variables declared as SQLSRV_
ASCII_STRING data types. To allocate the extra byte for the NULL
character, either let SQL/Services allocate it (through SQLDA data
buffers) by calling the sqlsrv_allocate_sqlda routine, or allocate
your own buffers with an additional byte for the NULL terminator.
Other data types in ASCII format, such as those for numbers and
dates, already have the NULL terminator factored into the SQLLEN
field returned by the sqlsrv_prepare routine. When passing an
existing SQLDA structure into the sqlsrv_prepare routine, the
application must take into account the NULL terminator.
Software Known Problems, Restrictions, Documentation Errors and Omissions 2-3
2.1.6 Using the sqlsrv_fetch_many API Routine
SQL/Services programmers must explicitly call the Application
Programming Interface (API) sqlsrv_close_cursor routine to ter-
minate a result table stream initiated by the sqlsrv_fetch_many
routine.
This restriction will remain in affect until a later release of
SQL/Services.
2.1.7 SQL/Services V4.0 Server Uses Proxy-like and Default Access to
Authorize V3.0 or V3.1 Client Applications
Explicit access authorization is never granted to a Version 3.1
API client application seeking access to a SQL/Services Version
4.0 server; however, the SQL/Services Version 4.0 communication
server does authorize access to incoming SQL/Services Version 3.1
client application requests using either the proxy-like or default
access method.
For the SQL/Services Version 4.0 server to grant explicit access,
you must upgrade your Rdb/VMS Version 3.0 or 3.1 system to Rdb/VMS
Version 4.0. As an interim measure, should you chose to upgrade
Rdb/VMS at a later date, set up a SQLSRV$PROXY.DAT file on the
server system to link incoming user names with local server system
accounts. Refer to the VAX Rdb/VMS Guide to Using SQL/Services for
further information.
2.1.8 Invalid Length Returned by SQLSRV_VARBYTE Data Type
The SQL/Services sqlsrv_prepare routine returns incorrect SQLLEN
values for SQLSRV_VARBYTE data type fields not created with an
explicit length. Digital recommends that tables be created with
explicit values as specified by the the LIST OF BYTE VARYING
option of the CREATE TABLE statement. See the VAX Rdb/VMS SQL
Reference Manual for syntax details.
2-4 Software Known Problems, Restrictions, Documentation Errors and Omissions
When an explicit length is not specified, programmers can obtain
the valid maximum segment size within the result stream from a
call to the sqlsrv_open_cursor routine. Refer to Section 2.2.2
for the values that SQL puts in the SQLCA SQLERRD array after
successful execution of a sqlsrv_open_cursor routine for list
cursors.
Programmers are responsible for setting field lengths and allocat-
ing buffers either by direct modification of the SQLLEN field in
the SQLDA data structure or by using the sqlsrv_sqlda_bind_data
routine. You find information about the sqlsrv_sqlda_bind_data
functional interface routine in the VAX Rdb/VMS Guide to Using
SQL/Services.
2.1.9 Allocating Space for SQLSRV_VARCHAR and SQLSRV_VARBYTE Data
Types
Be sure to specify the correct length for the SQLSRV_VARCHAR and
SQLSRV_VARBYTE data types in your API applications. SQL/Services
does not issue an error message when the size of the data fields
for SQLSRV_VARCHAR and SQLSRV_VARBYTE data types exceeds the size
of the SQLLEN field in the SQLDA data structure.
2.1.10 SQL/Services V4.0 Server Error (-2031) Returned to V3.1
Client APIs
The SQL/Services Version 3.1 Application Programming Interface
(API) receives the SQLSRV_APINOTSUP (- 2031) error mnemonic when
it cannot interpret information returned by the SQL/Services
Version 4.0 server. For example, the SQL/Services Version 3.1
API receives the SQLSRV_APINOTSUP error when a Version 3.1 API
application attempts to access LIST cursor data.
Software Known Problems, Restrictions, Documentation Errors and Omissions 2-5
2.1.11 Configuration File IDENT Keyword Not Supported
Use of the IDENT keyword in the SQLSRV$CONFIG.DAT configura-
tion file is not supported for Rdb/VMS Version 4.0; however,
SQL/Services does implicitly use identifiers. SQL/Services recog-
nizes the class name specified in the database class definition
as the identifier parameter. For example, if the class name for a
database server is defined as PERSONNEL in the configuration file,
SQL/Services implicitly uses PERSONNEL as the valid identifier
parameter. Thus, you can use the PERSONNEL identifier parameter
to associate an incoming user name with a local user account as
documented in the VAX Rdb/VMS Guide to Using SQL/Services.
When the IDENT keyword is specified in the configuration file,
SQL/Services returns an error. Explicit use of the IDENT keyword,
as currently described in the VAX Rdb/VMS Guide to Using SQL
/Services, will be supported in a future release of Rdb/VMS.
2.1.12 TYPE Not CLASS Keyword Used in Configuration File
When creating a generic or database class server definition in
the SQLSRV$CONFIG.DAT configuration file, use TYPE not CLASS as
the correct token for class name. SQL/Services does not recognize
CLASS as a valid keyword in configuration file definitions.
2.2 Documentation Errors and Omissions
This section describes the errors or omissions in the VAX Rdb/VMS
Guide to Using SQL/Services for Rdb/VMS Version 4.0.
2.2.1 SQLSRV$DEFAULT_ACCESS Logical Name Incorrectly Documented
The SQLSRV$DEFAULT_ACCESS logical name used to enable or disable
application access through the SQLSRV$SRV default account was in-
correctly documented as SQLSRV_DEFAULT_ACCESS in the VAX Rdb/VMS
Guide to Using SQL/Services for Rdb/VMS Version 4.0. The documen-
tation error will be corrected in a future release of Rdb/VMS.
2-6 Software Known Problems, Restrictions, Documentation Errors and Omissions
2.2.2 List Cursor SQLCA Return Values for sqlsrv_open_cursor Routine
Section 10.4 of the VAX Rdb/VMS Guide to Using SQL/Services omit-
ted information about the values SQL puts in the second, fourth,
fifth, and sixth elements of the SQLCA SQLERRD array after suc-
cessful execution of an sqlsrv_open_cursor routine for list cur-
sors. The routine returns the following information in the SQLERRD
array:
o SQLERRD[1]: Longword length of longest actual segment
o SQLERRD[3]: Longword number of segments
o SQLERRD[4,5]: Two contiguous longwords comprising quadword
number of total bytes
The information in Section 10.4 of the VAX Rdb/VMS Guide to Using
SQL/Services will be updated in a future release of Rdb/VMS.
2.2.3 Documentation for sqlsrv_sqlca_sqlerrd Routine
SQL/Services has added a new API functional interface routine,
called sqlsrv_sqlca_sqlerrd, specifically to return list cur-
sor information from the SQLCA.SQLERRD array. Refer to the VAX
Rdb/VMS Guide to Using SQL/Services for other functional interface
routines supported by SQL/Services for Rdb/VMS Version 4.0.
Documentation for the sqlsrv_sqlca_sqlerrd routine follows:
The sqlsrv_sqlca_sqlerrd routine returns values from the
SQLCA.SQLERRD array. After the sqlsrv_open_cursor routine is
called, the sqlsrv_sqlca_sqlerrd routine returns the following
list cursor information:
o The sqlerrd_array[3] entry contains the number of list entries.
o The sqlerrd_array[4] entry contains the largest list entry
size.
Software Known Problems, Restrictions, Documentation Errors and Omissions 2-7
o The sqlerrd_array[5] entry contains the total size of all list
entries.
VAX Format
SQLSRV$SQLCA_SQLERRD associate_id ,sqlerrd_array
C_FORMAT
extern int sqlsrv_sqlca_sqlerrd(
ASSOCIATE_ID associate_id,
long int *sqlerrd_array);
Parameters
associate_id
data type: ASSOCIATE_ID
access: read
mechanism: by reference
An identifier used to distinguish one active association from all
others.
sqlerrd_array
data type: longword
access: modify
mechanism: by reference
An array of 7 longwords that are filled in with the values from
SQLERRD[0] . . . [6].
Note
o After you call SQL/Services, the SQLCA passed in on the associ-
ation contains the return status.
Errors
SQLSRV_INVASC Invalid association identifier.
2-8 Software Known Problems, Restrictions, Documentation Errors and Omissions
The sqlsrv_sqlca_sqlerrd routine will documented in the VAX
Rdb/VMS Guide to Using SQL/Services in a future release of
Rdb/VMS.
Software Known Problems, Restrictions, Documentation Errors and Omissions 2-9