Order Number: AA-GQ93H-TE
VAX Rdb/VMS
Release Notes
December 1990
This document contains the Release Notes for VAX Rdb/VMS Version
4.0. It describes new and changed features; software errors fixed;
and problems, restrictions, and other information relating to
Version 4.0.
Revision/Update Information This manual is a revision and super-
sedes previous versions.
Operating System: VMS
Software Version: VAX Rdb/VMS Version 4.0
Digital Equipment Corporation
__________
Copyright ©1984, 1985, 1986, 1987, 1988, 1989, 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
RMS, VAX SCAN, VAX SPM, VAXstation, VAX TEAMDATA, VIDA, VMS, VT,
and the DIGITAL Logo.
IBM and OS/2 are registered trademarks of International Business
Machines Corporation. Macintosh is a trademark of Apple Computer,
Inc. MS-DOS is a registered trademark of Microsoft Corporation.
This document is available in printed and online versions.
This document was prepared using VAX DOCUMENT, Version 1.2
Contents
PREFACE xvii
CHAPTER 1 NEW AND CHANGED FEATURES 1-1
1.1 TWO-PHASE COMMIT PROTOCOL 1-1
1.1.1 Using SQL with Distributed Transactions 1-3
1.1.2 Using RDBPRE with Distributed Transactions 1-4
1.1.3 Using RDML with Distributed Transactions 1-5
1.1.4 RMU Enhancements 1-7
1.1.5 DISTRIBTRAN Privilege 1-8
1.2 NEW SECURITY FEATURES 1-8
1.3 DYNAMIC OPTIMIZATION 1-12
1.4 OTHER OPTIMIZER ENHANCEMENTS 1-19
1.4.1 More Efficient Strategies for Queries Whose
WHERE Expression Has OR Booleans 1-19
1.4.2 Improved Performance for Tables Stored in
Mixed Format Storage Areas 1-20
1.4.3 Optimization and Aggregates 1-20
1.4.4 Constraint Evaluation 1-22
1.5 JOURNALING OF METADATA UPDATES 1-23
1.6 MULTIPLE SEGMENTED STRING STORAGE AREAS 1-24
1.7 LOCK TIMEOUT MECHANISM 1-26
1.8 COMPRESSED INDEXES 1-26
1.9 NEW DATA TYPE-SQL TINYINT AND RDO SIGNED BYTE 1-31
1.10 EXPORT NOW SUPPORTS THE DATA OPTION 1-32
1.11 IMPORT NOW SUPPORTS DATA AND TRACE OPTIONS 1-33
1.12 RDB/VMS V4.0 GIVES SPECIAL TREATMENT FOR CDD/PLUS
DICTIONARIES 1-35
iii
Contents
1.13 SHOW STORAGE AREA SHOWS A DIFFERENT STORAGE AREA
ALLOCATION 1-37
1.14 SETTING LINE LENGTHS FOR A FILE OR OUTPUT DEVICE 1-38
1.15 CHANGES TO RUN-UNIT JOURNAL (RUJ) FILES 1-38
1.16 CHANGE TO BATCH-UPDATE AND EXCLUSIVE TRANSACTION
BEHAVIOR 1-40
1.17 DECTRACE SUPPORT FOR TRIGGER AND CONSTRAINT
STATISTICS 1-40
1.18 SQL: NEW AND CHANGED FEATURES AND STATEMENTS 1-40
1.18.1 Support for the Two-Phase Commit Protocol 1-40
1.18.2 New SQL Syntax 1-41
1.18.3 String Concatenation Operator 1-45
1.18.4 Substring Manipulation 1-45
1.18.5 SQL Supports Segmented Strings 1-46
1.18.6 Computed Columns in Tables 1-47
1.18.7 SQL Changes Values Used in SQLERRD Array 1-48
1.18.8 Module Language Record Support 1-49
1.18.9 SQL C Precompiler Supports VARCHAR Host
Variables 1-51
1.18.10 SQL Statements Have Been Updated to Support
VAX Data Distributor V2.2 1-52
1.18.11 Diagnostic Messages for Obsolete Features 1-52
1.18.12 Sample Programs in Precompiled SQL and SQL
Module Language 1-52
1.19 RDO: NEW AND CHANGED FEATURES AND STATEMENTS 1-53
1.19.1 Support for the Two-Phase Commit Protocol 1-54
1.19.2 RDO Changes for CDD/Plus Compatibility 1-54
1.19.3 RDO SHOW DATABASE Statement Displays the Node
Name for Remote Databases 1-54
1.20 RDBPRE: NEW AND CHANGED FEATURES AND STATEMENTS 1-55
1.20.1 Support for the Two-Phase Commit Protocol 1-55
1.20.2 RDBPRE/MESSAGE_MAP Works for BASIC 1-55
1.21 RDML: NEW AND CHANGED FEATURES AND STATEMENTS 1-55
1.21.1 Support for the Two-Phase Commit Protocol 1-55
iv
Contents
1.21.2 Support for Internationalization 1-56
1.22 RMU: NEW AND CHANGED FEATURES AND STATEMENTS 1-56
1.22.1 RMU/ALTER Command 1-57
1.22.2 RMU/BACKUP Command 1-57
1.22.3 RMU/CLOSE/PATH Command 1-60
1.22.4 RMU/CONVERT Command 1-60
1.22.5 RMU/COPY_DATABASE Command 1-64
1.22.6 RMU/DUMP/AFTER_JOURNAL Command 1-65
1.22.7 RMU/DUMP/AFTER_JOURNAL/STATE=PREPARED 1-65
1.22.8 RMU/DUMP/BACKUP_FILE/LABEL=(label-name-list)
Command 1-65
1.22.9 RMU/DUMP/USERS/STATE=BLOCKED Command 1-65
1.22.10 RMU/MOVE_AREA Command 1-65
1.22.11 RMU/OPEN/PATH Command 1-66
1.22.12 RMU/RECOVER/RESOLVE Command 1-67
1.22.13 RMU/REPAIR Command 1-67
1.22.14 RMU/RESOLVE Command 1-67
1.22.15 RMU/RESTORE/LABEL=(label-name-list) Command 1-67
1.22.16 Security Auditing 1-68
1.22.17 RMU/SHOW STATISTICS Command 1-68
1.23 SQL/SERVICES: NEW AND CHANGED FEATURES 1-69
1.23.1 Process Pooling 1-70
1.23.2 API Support 1-70
1.23.3 API Routines 1-70
1.23.4 Server Access 1-71
1.23.5 List Cursors 1-71
1.23.6 SQL/Services VMS API Linkable Libraries 1-72
1.23.7 Two New Installation Questions 1-72
1.23.8 SQL/Services Help Available from DCL HELP
Facility 1-72
1.24 CHANGES RELATED TO THE SAMPLE PERSONNEL DATABASE 1-73
1.25 NEW AND CHANGED RDB/VMS LOGICAL NAMES 1-74
1.25.1 Disabling the Two-Phase Commit Protocol with
the New SQL$DISABLE_CONTEXT Logical Name 1-74
1.25.2 Lock Timeout Mechanism Using a New
RDM$BIND_LOCK_TIMEOUT_INTERVAL Logical Name 1-74
v
Contents
1.25.3 Restricting the Creation of Databases Using
the New RDBVMS$CREATE_DB Logical Name 1-75
1.25.4 Remote Access to Rdb/VMS Using a New Logical
Name RDB$REMOTE_BUFFER_SIZE 1-75
1.25.5 Changes to the RDM$BIND_BUFFERS Logical Name 1-76
1.25.6 Changes to the
RDMS$BIND_SEGMENTED_STRING_BUFFER
Logical Name 1-76
1.25.7 RDMS$AUTO_READY Logical Name Is No Longer
Used 1-77
1.26 OBSOLETE STATEMENTS AND FEATURES 1-78
1.26.1 SQL Obsolete Features 1-78
1.26.2 RDO Obsolete Statements and Features 1-81
1.26.3 SQL/Services Obsolete Features 1-82
1.27 SUMMARY OF DOCUMENTATION ADDITIONS AND CHANGES 1-84
CHAPTER 2 SOFTWARE ERRORS FIXED 2-1
2.1 SOFTWARE ERRORS FIXED THAT APPLY TO ALL INTERFACES 2-1
2.1.1 EXPORT Statement Did Not Save the Maximum
Storage Area Allocation 2-1
2.1.2 During IMPORT, Storage Areas Were Always
Created Using the Default Page Size of 2
Blocks 2-2
2.1.3 IMPORT Did Not Restore the RDB$SYSTEM Storage
Area Correctly 2-2
2.1.4 Rdb/VMS V4.0 Requires That Certain Constraints
Be Redefined 2-4
2.1.5 Constraints Were Not Always Executed As
Required 2-6
2.1.6 Too Many Constraints Could Be Selected or
Executed 2-6
2.1.7 Constraints Could Be Executed Too Many Times 2-7
2.1.8 Indexes or Constraints Could Be Ignored by
Trigger Actions 2-7
2.1.9 Indexes or Constraints Could Be Defined When
Illegal Due to Active Queries 2-7
vi
Contents
2.1.10 The Combination of Using a Trigger and
Disabling Compression Did Not Update the
Index 2-8
2.1.11 Triggers Can No Longer Delete Subject Table
Rows 2-8
2.1.12 VAX Data Distributor Replications and
Triggered Actions Were Not Performing at the
Right Time 2-8
2.1.13 DBADM (ADMINISTRATOR) Privilege Was Granted by
Rdb/VMS Default Protection 2-9
2.1.14 CHANGE FIELD (RDO) or ALTER DOMAIN (SQL) Could
Cause Query ACCVIOs 2-9
2.1.15 A Problem Existed with Disabled Compression
and the Store Clause of the SQL ALTER and RDO
CHANGE STORAGE MAP Statements 2-9
2.1.16 Defining a Database with a Buffer Size of 1
Caused a Bugcheck 2-10
2.1.17 View Optimization Has Been Restored in V4.0 2-10
2.1.18 RDB$DBKEY_LENGTH System Relation Field Was
Incorrect for Certain Views 2-11
2.1.19 Errors Retrying Failed Multidatabase
Transactions 2-12
2.1.20 Problem with Exclusive Locking on a Multifile
Database Produced a Bugcheck 2-13
2.1.21 Non-Fatal Bugcheck Resulted from Rdb/VMS
Overflowing the EXEC STACK 2-13
2.1.22 The RMUCONVERT.EXE File No Longer Exists 2-14
2.1.23 Remote Access to a V3.n Database and Starting
a Transaction Reserving Many Relations Caused
the Buffer to Be Exceeded and the Statement to
Fail 2-14
2.1.24 RDML and RDBPRE Applications Stored Segmented
Strings in the Default Storage Area Even When
a Storage Area Was Already Defined 2-15
2.1.25 Storing a Segmented String Greater in Size
than 65,508 Bytes Caused a Bugcheck 2-16
2.1.26 Programs with Calls to Both Rdb/VMS and DBMS
Returned Link Errors 2-16
vii
Contents
2.1.27 Problem with Partitioned Indexes 2-17
2.1.28 Retrieving Records Using a Multisegmented
Partitioned Sorted Index on Uniform Storage
Areas Caused a Bugcheck to Occur 2-17
2.1.29 Queries with FIRST n Containing Aggregates and
SORT Executed Incorrectly 2-18
2.1.30 A Bugcheck Was Generated When the Query
Optimizer Tried to Match a Computed Field
Before Evaluating the Expression 2-18
2.1.31 Query Optimizer Chose to Use a Hashed Index
When It Should Not Have 2-18
2.1.32 VALID IF Statements Might Not Compile or
Evaluate Properly for DEFAULT VALUEs 2-19
2.1.33 A STARTING WITH Predicate on a Descending
Index Returned No Data 2-19
2.1.34 A Query Using Sort Returned Rows in Field Size
Order for VARCHAR Fields with a Collating
Sequence Specified 2-19
2.1.35 A Compiled Query Returned Incorrect Data When
Using an Index 2-20
2.1.36 Wrong Result Was Returned by a Query with a
Predicate on a Computed Field 2-21
2.1.37 Query Did Not Use an Index-Only Retrieval Even
If All the Fields Were in an Index 2-22
2.1.38 A Join Query Matched Nulls to Zeros or Blanks
and Produced Incorrect Results 2-22
2.1.39 Batch-Update or Exclusive Transactions Failed
When RDB$SYSTEM Was Read-Only 2-23
2.2 SQL SOFTWARE ERRORS FIXED 2-24
2.2.1 SQL$.EXE Failed to Return Status on Failure of
an Import Operation 2-24
2.2.2 SQL Did Not Correctly Detect Errors in a
CREATE INDEX Statement 2-24
2.2.3 Generated Constraint Names and Check Option
Constraint Names Were Not Checked 2-25
2.2.4 SQL Quantified Predicates Did Not Function in
Trigger WHEN Predicates 2-25
viii
Contents
2.2.5 Problem with INTEGRATE Statement When SQL
Database Is Defined with DICTIONARY IS
REQUIRED Clause 2-25
2.2.6 Problems with INTEGRATE SCHEMA . . . CREATE
PATH in SQL 2-26
2.2.7 Short Char Variable Was Not Padded Correctly 2-27
2.2.8 SQL C Precompiler Generated Incorrect Code 2-27
2.2.9 SQLPRE Changed Names of the SQLDAs to
Uppercase 2-28
2.2.10 SQL$PRE Hung in Batch Mode When an Invalid
File Name Was Given 2-28
2.3 RDO AND RDBPRE SOFTWARE ERRORS FIXED 2-28
2.3.1 RDO EXPORT Now Prints the Reason for Failure 2-28
2.3.2 IMPORT Statement Could Fail to Import Views or
Tables with COMPUTED BY Fields 2-29
2.3.3 RDO IMPORT Statement Did Not Support
ANSI-Style Protection 2-29
2.3.4 RDO IMPORT Would Appear to Stall in an
Infinite Loop 2-30
2.3.5 RDO DEFINE STORAGE MAP DESCRIPTION IS Clause
Was Ignored 2-30
2.3.6 RDO SHOW RELATION Failed with INVALID_BLR for
VIDA Databases 2-30
2.3.7 Views with FIRST n Could Use Outer Query
Booleans for Indexed Retrieval 2-31
2.3.8 Problem Creating a View with a WITH CHECK
OPTION Clause Without a WHERE Predicate in the
SELECT Clause 2-32
2.3.9 Problem with Multikey Partitioned Indexes 2-32
2.3.10 Index Scan Problem Caused a FOR Loop to Loop
Infinitely 2-32
2.3.11 A Bugcheck Resulted When Using the PLACE Verb
Within a FOR Loop Using RDO 2-32
2.3.12 The /NOINITIALIZE Qualifier in FORTRAN
Required That Four Characters Be Specified 2-33
2.3.13 RDBPRE BASIC Preprocessor Generated Ambiguous
Code 2-33
ix
Contents
2.3.14 When You Entered an ACL Entry, an Argument to
the Position Clause Could Not Exceed 255 2-34
2.3.15 COMPUTED BY Clause in Aggregate Subqueries
Produced Bugcheck Dumps 2-34
2.3.16 Query on System Relations Caused a Loop 2-34
2.4 RDML SOFTWARE ERRORS FIXED 2-35
2.4.1 RDML Did Not Recover from Statistical Function
Keywords Used as Host Variables 2-35
2.4.2 RDML Did Not Display the Names of Context
Variables Improperly Referenced by SORTED BY
and REDUCED TO Clauses 2-36
2.4.3 RDML Context Variables Could Not Be Named the
Same as the Relation 2-36
2.4.4 Using Concatenated Expression Failed in C with
Invalid Operand Error 2-37
2.4.5 RDML REDUCED TO Clause Generated BLR in
Reverse Order 2-37
2.4.6 RDML Generated Incorrect Code for a STORE
Statement in a Pascal Program 2-38
2.4.7 In SORTED BY or REDUCED TO Clauses RDML
Did Not Check That Only Local Fields Were
Included 2-38
2.4.8 Incompatible Data Types in VAX Pascal
Generated Code 2-38
2.4.9 DECLARE_VARIABLE Restriction Removed 2-41
2.5 RMU SOFTWARE ERRORS FIXED 2-41
2.5.1 Problem Existed with the RMU/LOAD Operation 2-41
2.5.2 RMU/BACKUP and VMS DCL COPY of Single-File
Databases Made the Database Unusable 2-42
2.5.3 RMU/BACKUP/ONLINE Had Lock Conflict Problems 2-42
2.5.4 RMU/BACKUP/ONLINE Waited Indefinitely for a
Quiet Point Lock 2-42
2.5.5 RMU/BACKUP/ONLINE /CHECKSUM_VERIFICATION
Qualifier Would Occasionally Fail 2-43
2.5.6 A By-Area Backup Was Always Performed Against
the Last Full Backup 2-43
x
Contents
2.5.7 Problem Existed with RMU By-Area Backup
Function 2-43
2.5.8 Problem Existed with RMU/BACKUP or RMU/RESTORE
with More Than 268 Database Storage Areas 2-44
2.5.9 CHANGE FIELD COLLATING_SEQUENCE Did Not Work
on RMU/RESTORE Command That Used Convert 2-44
2.5.10 Problem Existed with RMU/RESTORE/INCREMENTAL
and Adding a Storage Area 2-45
2.5.11 RMU/RESTORE Did Not Ignore Logical Areas
Outside the Range of 1 to 16,384 and Produced
a Bugcheck 2-45
2.5.12 RMU/RECOVER By-Area Did Not Work Correctly 2-45
2.5.13 RMU/RECOVER By-Area Command Has Changed
Semantics 2-46
2.5.14 RMU/VERIFY Could Not Verify the Root File If
the AIJ File Was Open 2-47
2.5.15 Errors Occurred During RMU/VERIFY 2-47
2.5.16 Database Verification Returned %RMU-W-BADDBPRO
Error 2-47
2.5.17 RMU/REPAIR Corrupted Databases 2-48
CHAPTER 3 KNOWN PROBLEMS, RESTRICTIONS, AND OTHER NOTES 3-1
3.1 KNOWN PROBLEMS AND RESTRICTIONS FOR ALL INTERFACES 3-1
3.1.1 Improving the Performance of the EXPORT
Operation Using the DCL SET Command to Change
the Default Extend Parameter Value 3-1
3.1.2 Undetected Deadlock with Distributed
Transactions 3-2
3.1.3 Restrictions on Distributed Transactions
Related to the DISTRIBTRAN Security
Privilege 3-3
3.1.4 SNAPSHOTS DEFERRED May Stall Transactions 3-3
3.1.5 PLACEMENT VIA INDEX Clause Prohibits Shadow
Clustering 3-4
3.1.6 Using the CREATE INDEX Statement Locks the
Database If Snapshots Are Deferred 3-5
xi
Contents
3.1.7 Source Attributes for Storage Maps Are Not
Saved in Pre-V3.1 SQL IMPORT Operations 3-5
3.1.8 RDB$SYSTEM Storage Area Cannot Be Read-Only
When a Relation Is Readied in Exclusive or
Batch-Update Mode 3-7
3.1.9 Joined Relations Do Not Allow "MODIFY" If
Using the WITH Clause 3-8
3.1.10 Using RDML/C to Update a VIEW Returns Errors 3-10
3.1.11 Range Query Returns Unexpected Results 3-11
3.1.12 DECLARE and START Stream Are No Longer Allowed
for Certain Views 3-12
3.1.13 A Clarification of the Storage Algorithm for
Mixed Pages 3-12
3.1.14 Adjustment of Cardinalities in V4.0 Is Likely
to Cause Poorer Optimizer Performance 3-13
3.1.15 SELECT on SCHEMA (READ on DATABASE) ACE Is Now
Required 3-13
3.1.16 Rdb/VMS Network Link Failure Does Not Allow
FINISH to Tidy Up Transactions 3-14
3.1.17 Passwords for the RDB$REMOTE Account in UAF
and for the RDBSERVER Object in NCP Must Be
the Same 3-14
3.1.18 RDB$REMOTE Account Is Now Non-Privileged 3-15
3.1.19 VAX Data Distributor Copy Processes Do
Not Process Database Pages Ahead of an
Application 3-15
3.1.20 Setting an Appropriate WSEXTENT Relative to
WSQUOTA for SORT/MERGE Operations 3-16
3.1.21 Attempting to Acquire a Lock Could Cause an
Infinite Loop 3-17
3.2 SQL KNOWN PROBLEMS AND RESTRICTIONS 3-17
3.2.1 SQL Applications Involved in Distributed
Transactions Must Have DISTRIBTRAN Privilege 3-17
3.2.2 SQL Allows False Redefinition of the DATE Data
Type 3-18
3.2.3 Problem Adding a New Field to CDO Defined
Record and Not to Last Position 3-19
xii
Contents
3.2.4 Module Language Passes Extraneous Characters
with Inexact Dynamic Descriptors 3-20
3.2.5 Close List Cursor Before Fetching Rows from
Table Cursor 3-21
3.2.6 SELECT Statement with GROUP BY Clause Did Not
Return Date Fields in EDIT STRING Format 3-22
3.2.7 When Using the BETWEEN Operator, You Should
Specify the Lower Value First 3-23
3.2.8 Cautions on Using ANY, ALL, or IN Clauses in
Constraint Definitions 3-24
3.2.9 SQL Does Not Recognize a Record During SQL
Precompile Time 3-24
3.2.10 An SQLMOD Query Returns Empty Rows 3-25
3.2.11 Input VARCHAR Parameter Actual Value Is Longer
Than Procedure Parameter 3-26
3.2.12 Release of Cursor Statements Referencing
Prepared Statements Causes Problems 3-27
3.2.13 SQL Does Not Translate Logical Names
Referencing Source Databases 3-27
3.2.14 Problem with Transferring a Table to an
Existing Database Containing the Same Table
Name 3-28
3.3 RDO AND RDBPRE KNOWN PROBLEMS AND RESTRICTIONS 3-29
3.3.1 RDO SHOW USERS and SHOW MONITOR Statements Do
Not Work for Remotely Accessed Databases 3-30
3.4 RDML KNOWN PROBLEMS AND RESTRICTIONS 3-30
3.4.1 RDML Generates an Error Message When
Attempting to Store or Modify Read-Only
(COMPUTED BY) Fields 3-30
3.5 RMU KNOWN PROBLEMS AND RESTRICTIONS 3-31
3.5.1 Non-Updatable Fields Cannot Be Unloaded Using
the RMU/UNLOAD Command 3-31
3.5.2 Single-File Databases Require the /ROOT
Qualifier When Using the RMU/MOVE_AREA
Command 3-32
xiii
Contents
3.5.3 The RMU/BACKUP/AFTER_JOURNAL /CONTINUOUS
/UNTIL="TOMORROW:+00:50" Command Fails for
V3.1A and VMS V5.3 or V5.4 3-32
3.5.4 Shortened Form of RMU/RESTORE Command Does Not
Work Properly 3-32
3.5.5 Installing RMU with Privileges 3-33
3.5.6 The Returned DCL $STATUS Is Inconsistent
Between RMU Commands 3-33
3.6 SQL/SERVICES KNOWN PROBLEMS AND RESTRICTIONS 3-34
3.6.1 SQL/Services Database Class Server Is Not
Supported in Rdb/VMS V4.0 3-34
3.6.2 SQL/Services V4.0 Server Uses Proxy-Like and
Default Access to Authorize V3.0 or V3.1
Client Applications 3-35
3.6.3 Invalid Length Is Returned by SQLSRV_VARBYTE
Data Type 3-35
3.6.4 Allocating Space for SQLSRV_VARCHAR and
SQLSRV_VARBYTE Data Types 3-36
3.6.5 SQL/Services V4.0 Server Error -2031 Returned
to V3.1 Client APIs 3-36
3.6.6 TYPE Not CLASS Keyword Used in Configuration
File 3-36
3.6.7 SQLSRV_ASCII_STRING Data Type Is Not
Terminated with a NULL Character 3-37
3.6.8 Filter Expressions Return Incorrect Results 3-37
3.6.9 Using Group/System-Not Process-Logical Names
in SQL/Services 3-37
3.6.10 API sqlsrv_fetch_many Routine 3-38
3.6.11 SQLSRV$SRV Default Account Must Be Present for
SQL/Services to Start Automatically 3-38
3.6.12 DECnet Default File Access for SQL/Services 3-38
3.7 CDD/PLUS RESTRICTIONS 3-39
3.7.1 Minimum Supported Version of CDD/Plus 3-39
3.7.2 Using CDD/Plus with PERSONNEL.COM 3-39
3.7.3 Some Views Are Not Accepted by VAX CDD/Plus
V4.2 3-39
xiv
Contents
3.7.4 GRANT and REVOKE Statements Generate
MBLRSYNERR Message If Attached by Path Name 3-40
3.7.5 Using CDD/Plus to Specify Collating
Sequences 3-40
3.8 RESTRICTIONS LIFTED BY CDD/PLUS VERSION 4.2 3-41
3.8.1 Incompatibilities Between Rdb/VMS V4.0 and
CDD/Plus That Have Been Lifted by VAX CDD/Plus
Version 4.2 3-41
3.9 RDB/VMS DOCUMENTATION ERRORS AND OMISSIONS 3-41
3.9.1 Error in Table D-1, Fields in the SQLDA 3-41
3.9.2 Error in COL-DEFINITION Syntax Diagram 3-43
3.9.3 Cursors Containing ORDER BY Clauses Are Not
Read-Only 3-44
3.9.4 LIST OF BYTE VARYING Segment Size Correction 3-44
3.9.5 LIST OF BYTE VARYING in SQLTYPE Field of
SQLDA 3-44
3.9.6 Value Returned by AVG Function 3-45
3.9.7 NULL Characters May Terminate Character Data
Type Columns 3-45
3.9.8 ORDER BY and LIMIT TO Clauses Are Missing from
SQL Quick Reference Guide 3-45
3.9.9 INSERT Statement Can Be Triggered 3-46
3.9.10 PRINT Statement Is Missing from Table 2-8 3-46
3.9.11 SQL$PRE FORTRAN AVG Function Returns Rounded
Integer Value 3-46
3.9.12 Error Exists in Privilege Table 3-47
3.9.13 Clarification of Constraint Semantics 3-47
3.9.14 Declaration of the Distributed Transaction
Identifier (TID) in FORTRAN Is Incorrect 3-47
3.9.15 Using RDML and the Two-Phase Commit Protocol
by Calling the DECdtm System Service Calls
Implicitly and Explicitly Is Not Fully
Documented 3-48
3.9.16 REQUEST_HANDLE Clause in Rdb/ELN VAXELN Pascal
Applications 3-48
3.9.17 Host Language Multipath Statements and RDML
Update Statements 3-48
xv
Contents
3.9.18 C Host Variable Syntax Diagram 3-51
3.9.19 Method to Create Dummy AIJ or RUJ Files to
Replace One of These Missing Files Is No
Longer Supported 3-51
3.9.20 Improving the Performance of Import/Export
Operations 3-52
3.9.21 Changes to RMU/ALTER That Are Not Documented
in V4.0 3-52
3.9.22 Description of the Storage Algorithm for
Storing Records in Mixed Storage Areas When
Target Pages Are Selected 3-54
3.10 SQL/SERVICES DOCUMENTATION ERRORS AND OMISSIONS 3-56
3.10.1 SQLSRV$DEFAULT_ACCESS Logical Name Is
Incorrectly Documented 3-57
3.10.2 API sqlsrv_sqlca_sqlerrd Routine Is Omitted 3-57
3.10.3 List Cursor SQLCA Return Values for
sqlsrv_open_cursor Routine 3-58
3.10.4 SQL/Services sqlsrv_sqlda_bind_data Routine
Error 3-59
3.11 RESTRICTIONS RETAINED FROM V3.1 3-60
3.11.1 Object Modules Created with V3.1 and V4.0 Are
Not Downward-Compatible 3-60
3.11.2 FIRST n Is Not Considered During
Optimization 3-60
3.11.3 Do Not Add Fields to Relations, Define
Indexes, Triggers, and Other Database Objects
Based on System Relation Fields 3-61
3.11.4 Performance Considerations for Using VARYING
STRING or COLLATING SEQUENCE Attribute for
Index Keys 3-61
3.11.5 Sorting or Implied Sorting for Projection on a
Dbkey Is Not Worthwhile 3-63
3.11.6 Many Attaches to and Detaches from the Same or
Multiple Databases While Using Search Lists
to Point to the Database Use Up I/O Channel
Quota 3-63
xvi
Contents
3.11.7 Do Not Disable ASTs If You Want to Access a
Database Remotely 3-64
3.11.8 Unexpected Setting of the NULL Attribute After
an IMPORT Operation 3-65
3.11.9 IMPORT Statement Generates Bugcheck Dumps If
the Index Definition Fails 3-66
3.11.10 IMPORT Statement Failed to Complete Index
Definition with Users Attached to the
Database 3-67
3.11.11 Using LIB$DT_INPUT_FORMAT to Change Date Input
Format Sometimes Causes Access Violation 3-68
3.11.12 Operations on F-Floating Data Round to Whole
Numbers 3-68
3.11.13 Rdb/VMS Interaction with Data Distributor V2.1
May Generate Bugcheck Dumps 3-69
3.11.14 Batch-Update Transactions Can Cause a Bugcheck
Dump to Occur If an Index Definition Fails 3-69
3.11.15 Rdb/VMS Logical Name, RDMS$BIND_WORK_VM, Has
an Upper Limit of 65,000 Bytes 3-70
3.11.16 Reserving a Table in Exclusive Mode May
Prevent Operations from Being Performed on
Other Tables in the Same Storage Area 3-70
3.11.17 There Is a Problem Defining COLLATING SEQUENCE
IS NORWEGIAN NORWEGIAN 3-70
3.11.18 Rdb/VMS and VMS Debugger Interaction 3-72
3.11.19 RDB$DBKEY_LENGTH System Field Incorrect for
Certain Views 3-74
3.11.20 Problem with the Use of Virtual Memory 3-75
3.11.21 Using the /USERS_MAX and /NODES_MAX Qualifiers
with the RMU/RESTORE Command Requires Both
Qualifiers on the First Line of DCL Input 3-75
3.11.22 A Snapshot File Name, File Type, or Version
Number Cannot Be Changed for Single-File
Databases 3-76
3.11.23 There Is a 17-Character Limit for File Names
When You Back Up Databases to Tape 3-76
xvii
Contents
3.11.24 RMU/DUMP/BACKUP Command Specifying a Value of
1 or 2 for the /ACTIVE_IO Qualifier Causes the
AIJ Dump to Stall 3-77
3.11.25 RMU/SHOW STATISTICS Command Does Not Record
All Statistics in the Binary File 3-78
3.11.26 Dumping the AIJ File Is Incompatible with
Normal Usage 3-79
3.11.27 RMU/RESTORE Command May Initialize the SPAM
Thresholds in One or More Storage Areas 3-79
3.11.28 Correction to the Usage Note on Constraints
with the CREATE TABLE Statement 3-80
3.11.29 Using Rdb/VMS from a VMS Detached Process 3-80
3.11.30 Disable VAX SQL/Services V1.0 Startup
Procedure 3-82
3.11.31 DDL Statements Cannot Refer to Objects Before
Their Creation 3-82
3.11.32 Deleting Metadata in Rdb/VMS 3-83
3.11.33 SQL Schema Compilation Fails on the First
Fatal Error 3-83
3.11.34 COMMENT ON Statement Cannot Be Used in CREATE
SCHEMA Statement 3-84
3.11.35 Dynamic Cursors Cannot Access Views Created
with GROUP BY or UNION Clause 3-84
3.11.36 Cannot Use INCLUDE Statement in Variable
Declaration 3-84
3.11.37 SQL Ada Precompiler Does Not Support the
Correct Overloading of Subprograms 3-85
3.11.38 SQL Precompiler Does Not Evaluate Expressions
in Variable Declarations or Understand
Literals 3-86
3.11.39 SQL Ada Precompiler Does Not Support Named
Literals or Ranges 3-87
3.11.40 Limiting Length of File Names 3-87
3.11.41 Limiting Number of Continuation Lines per
Record 3-87
3.11.42 SQL Module Language Processor Fails on the
First Fatal Error 3-88
3.11.43 Database Handle Problem on START_STREAM 3-88
xviii
Contents
3.11.44 RDO CHANGE INDEX Restriction Is Now Signaled 3-88
3.11.45 Problem of Different Optimizations of the Same
Query from Different Environments 3-89
3.11.46 Restrictions on Using Missing Value Fields in
Nested Queries 3-90
3.11.47 STORE WITHIN and DISABLE/ENABLE COMPRESSION
Clauses Cannot Both Be Specified 3-91
3.11.48 Variables Cannot Be Database Handles 3-92
3.11.49 RDML Run-Time Object Library No Longer
Requires You to Link with VAXCRTL or VAXCRTLG
Object Libraries or Shareable Images 3-95
3.11.50 RDML/EPascal Ignores /LINKAGE=PROGRAM_SECTION
Qualifier 3-95
3.11.51 RDML/Pascal Does Not Understand Some Character
String Value Expressions 3-95
3.11.52 RDML/Pascal Does Not Accept All Possible Valid
Pascal Host Language Variables 3-96
3.11.53 RDML Does Not Allow Nested Comments 3-96
3.11.54 C Host Variables 3-97
3.11.55 C String Continuation Character 3-98
3.11.56 Path Name and the DATABASE Statement 3-98
3.12 DSRI NOTES AND RESTRICTIONS RETAINED FROM V3.1 3-99
3.12.1 RCI Instantiation Number Must Be Zero for
Remote Access 3-99
3.12.2 Context Variables That Are Not Unique Within a
Request Cause Invalid BLR 3-99
3.13 CDD/PLUS RESTRICTIONS RETAINED FROM RDB/VMS V3.1 3-100
3.13.1 CDD/Plus COMPUTED BY Fields Are Not Currently
Supported in Rdb/VMS Relations or Views 3-101
3.13.2 EXPORT WITH NOEXTENSIONS Statement Can Corrupt
the CDD$DATABASE 3-101
xix
Contents
APPENDIX A PROCESS POOLING A-1
A.1 PROCESS POOLING OVERVIEW A-2
A.2 PROCESS POOLING COMPONENTS A-3
A.3 COMMUNICATION SERVER PROCESS A-6
A.3.1 The Default Configuration File A-7
A.3.2 Modifying the Configuration File A-13
A.3.2.1 Procedures for Modifying the Configuration FileA-13
A.3.2.2 Rules for Modifying the Configuration File A-14
A.4 EXECUTION SERVER PROCESSES A-15
A.4.1 Choosing an Execution Server Process A-15
A.4.2 Generic Class Execution Server Processes A-17
A.4.3 Database Class Execution Server Processes A-17
A.4.3.1 System Management Tasks: Setting Up Database
Servers A-18
A.4.3.2 Programmer Tasks: Setting Up Database Servers A-22
A.4.4 The Dynamic Nature of Execution Servers A-23
A.5 METHODS OF SERVER ACCESS A-25
A.6 HOW TO ENABLE SERVER ACCESS A-26
A.6.1 Explicit Access A-26
A.6.2 SQL/Services Proxy Access A-27
A.6.3 SQLSRV$SRV Default Account Access A-28
A.7 REINITIALIZING PROXY AND DEFAULT ACCESS A-28
EXAMPLES
A-1 Definition of Generic Execution Server Process A-8
A-2 Definition of Database Execution Server Process A-9
xx
Contents
TABLES
1 Database Terms xviii
1-1 Sample Programs in Precompiled SQL and SQL Module
Language 1-52
1-2 Obsolete Keywords for DECLARE and SET
TRANSACTION 1-80
1-3 Obsolete Statements 1-82
3-1 Fields in the SQLDA 3-42
A-1 Process Pooling Components A-5
A-2 Configuration File Parameters A-10
A-3 Methods of Accessing the Server System A-25
xxi
_____________________________________________________________________
Preface
VAX Rdb/VMS software, Version 4.0, often referred to as V4.0 in
this manual, is a general-purpose database management system based
on the relational data model.
This manual describes new and changed features; problems fixed in
this release; and current problems, restrictions, and other notes.
NOTE
The release notes are supplied in printed form, Bookreader
form, and in online form (in SYS$HELP). For V4.0, the
online and Bookreader forms are prepared for production
after the printed form; thus, information in the online and
Bookreader forms is more up-to-date.
The version previous to V4.0 is referred to throughout
this manual as Version 3.1 or V3.1. The term "Version 3.1"
refers to Version 3.1 and any updates to Version 3.1; thus,
for example, a reference to "the Version 3.1 behavior" of a
statement refers to the behavior under Version 3.1 and any
of its updates.
References to a specific update (for example, Version 3.1A
or Version 3.1B) are made only where it is necessary to be
precise.
___________________________________________________________________
Intended Audience
These Release Notes are intended for all users of Rdb/VMS, and
should be read to supplement information contained in the Rdb/VMS
documentation set.
xvii
Preface
To get the most out of this manual, you should be familiar with
Rdb/VMS, data processing procedures, and basic database management
concepts and terminology.
___________________________________________________________________
A Note on the Terminology
When the SQL, RDO, and RDML interfaces use different terms to
describe the same entity or concept, this manual uses the SQL
term, unless the discussion is specifically about RDO or RDML.
(This is also true of most of the other manuals in the Rdb/VMS
documentation set.) For example, this manual normally uses table
instead of relation, column instead of field (of a relation), and
row instead of record.
Thus, the notes of problems fixed may use different database terms
to mean the same thing. Table 1 shows some of the different terms
used.
Table_1:_Database_Terms___________________________________________
SQL______________RDO,_RDML________ANSI/ISO_SQL_STANDARD___________
Alias Context vari- Alias
able
Authorization Database handle Authorization identifier
identifier
Column Field Column
Column select Record selec- Column select expression
expression tion expression
Domain Global field Domain (SQL2)[1]
__________________________________________________________________
[1]SQL2 is the industry standard currently being developed.
xviii
Preface
Table_1_(Cont.):_Database_Terms___________________________________
SQL______________RDO,_RDML________ANSI/ISO_SQL_STANDARD___________
Parameter Host language Parameter
variable
Predicate Conditional Predicate
expression
READ ONLY READ_ONLY READ ONLY
READ WRITE READ_WRITE READ WRITE
Result table Record stream Result table
Row Record Row
Storage area Storage area N/A[2]
Storage map Storage map N/A[2]
Table Relation Table
__________________________________________________________________
[2]N/A means that the term is not applicable or not used with the
listed product, standard, or system.
__________________________________________________________________
___________________________________________________________________
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.
xix
Preface
For compatibility information about other software products used
with this version of Rdb/VMS, refer to the System Support Addendum
(SSA) that is included 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 three chapters and one appendix:
Chapter 1 Summarizes the new and changed features of Rdb/VMS
V4.0.
Chapter 2 Describes known software errors in versions prior to
V4.0 that were fixed in V4.0.
Chapter 3 Describes problems, restrictions, and workarounds
known to exist in Rdb/VMS. This chapter also in-
cludes restrictions retained from previous versions of
Rdb/VMS.
Appendix A Describes how process pooling works and the way to
manage pooling at your site. It also describes how
the communication server authorizes client application
access to the server system.
___________________________________________________________________
Related Manuals
For more information on VAX Rdb/VMS, see the following manuals in
the Rdb/VMS documentation set:
o VAX Rdb/VMS Introduction and Master Index
xx
Preface
Introduces Rdb/VMS and explains major terms and concepts.
Includes a glossary, a directory of Rdb/VMS documentation,
and a master index that combines entries from all the Rdb/VMS
manuals.
o VAX Rdb/VMS Guide to Distributed Transactions
Describes the two-phase commit protocol and distributed trans-
actions, explains how to start and complete distributed trans-
actions using SQL, RDBPRE, and RDML, and how to recover from
unresolved transactions using RMU commands.
o VAX Rdb/VMS Guide to Database Design and Definition
Explains how to design a logical database and how to trans-
late that design into a physical database using Rdb/VMS data
definition statements.
o VAX Rdb/VMS Guide to Database Maintenance and Performance
Provides guidelines for maintaining good database performance
and explains how to use the database maintenance utilities to
perform backup and recovery operations, restore journals, and
analyze the database.
xxi
Preface
o VAX Rdb/VMS Guide to Database Tuning
Introduces the concept of tuning, and explores how tuning the
system, the database, and the application can affect database
performance. Outlines a series of steps to follow in identify-
ing, analyzing, isolating, and solving a performance problem,
and in monitoring the resulting solution. Includes a set of
decision trees that provide an organized approach to solving
some common database tuning problems.
o VAX Rdb/VMS Guide to Using RDO, RDBPRE, and RDML
Describes how to use the features of Rdb/VMS to retrieve,
store, change, and erase data. Shows how to write programs that
use Rdb/VMS as a data access method; contains information on
writing programs in high-level languages that are supported by
Rdb/VMS preprocessors, including Relational Data Manipulation
Language (RDML); and describes Callable RDO, an interactive
utility for languages without preprocessors.
o VAX Rdb/VMS Guide to Using SQL
Introduces the Rdb/VMS SQL (structured query language) in-
terface, and shows how to retrieve, store, and update data
interactively and through application programs.
o VAX Rdb/VMS Guide to Using SQL/Services
Describes how to develop application programs that use
SQL/Services, a client/server software component of Rdb/VMS
that allows programs, from various remote computers running
the MS-DOS, OS/2, ULTRIX, ULTRIX for RISC, or VMS operating
systems, to access Rdb/VMS or VIDA databases on a VMS server
system.
o VAX Rdb/VMS SQL Reference Manual
Provides reference material and a complete description of the
statements, the interactive, dynamic, and module language in-
terfaces, and the syntax for SQL, the structured query language
interface for Rdb/VMS.
xxii
Preface
o VAX Rdb/VMS SQL Quick Reference Guide
Summarizes the information in the VAX Rdb/VMS SQL Reference
Manual.
o VAX Rdb/VMS RDO and RMU Reference Manual
Provides reference material and a complete description of the
statements and syntax of the Rdb/VMS Relational Database
Operator (RDO) interface and the commands of the Rdb/VMS
Management Utility (RMU).
o RDML Reference Manual
Describes the syntax and use of the Relational Data Manipulation
Language (RDML), which can be embedded in VAX C or VAX Pascal
programs to access Rdb/VMS or Rdb/ELN databases.
xxiii
Preface
o VAX Rdb/VMS Installation Guide
Describes how to install Rdb/VMS and SQL/Services Application
Programming Interface (API) Software.
___________________________________________________________________
Conventions
In examples, an implied carriage return occurs at the end of each
line, unless otherwise noted. You must press the RETURN key at the
end of a line of input.
Often in examples the prompts are not shown. Generally, they are
shown where it is important to depict an interactive sequence
exactly; otherwise, they are omitted in order to focus full atten-
tion on the statements or commands themselves.
This section explains the conventions used in this manual:
<CTRL/x> This symbol in examples tells you to press the CTRL
(control) key and hold it down while pressing the speci-
fied letter key.
<RETURN> This symbol in examples indicates the RETURN key.
<TAB> This symbol in examples indicates the TAB key.
A vertical ellipsis in an example means that information
. not directly related to the example has been omitted.
.
.
. . . A horizontal ellipsis in statements or commands means
that parts of the statement or command not directly
related to the example have been omitted.
xxiv
Preface
< > Angle brackets enclose user-supplied names.
[ ] Brackets enclose optional clauses from which you can
choose one or none.
$ 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 products by their abbreviated names:
o DECdecision software is referred to as DECdecision.
o DEC RdbExpert for VMS software is referred to as RdbExpert.
o DECtrace for VMS software is referred to as DECtrace.
o The SQL interface is referred to as VAX SQL whenever it is
correct to refer to Version 2.0 or earlier of SQL. The use of
SQL by itself indicates the SQL interface now included as part
of VAX Rdb/VMS V3.1 and higher.
o VAX ACMS software is referred to as ACMS.
o VAX Ada software is referred to as Ada.
o VAX BASIC software is referred to as BASIC.
o VAX C software is referred to as C.
o VAX CDD/Plus software is referred to as CDD/Plus, the data
dictionary, or the dictionary.
xxv
Preface
o VAX COBOL software is referred to as COBOL.
o VAX Data Distributor software is referred to as Data Distributor.
o VAX DATATRIEVE software is referred to as DATATRIEVE.
o VAX DBMS software is referred to as VAX DBMS.
o VAX FORTRAN software is referred to as FORTRAN.
o VAX Pascal and VAXELN Pascal software are referred to as
Pascal. When the use of a statement is not the same in both
the VAXELN and VMS environments, that statement is specified as
VAXELN Pascal or VAX Pascal.
o VAX PL/I software is referred to as PL/I.
o VAX RALLY software is referred to as RALLY.
o VAX Rdb/ELN software is referred to as Rdb/ELN.
o VAX Rdb/VMS software is referred to as Rdb/VMS. Version 4.0 of
VAX Rdb/VMS software is often referred to as V4.0.
o VAX TDMS software is referred to as TDMS.
o VAX TEAMDATA software is referred to as TEAMDATA.
o VIDA software is referred to as VIDA.
xxvi
Chapter 1
New and Changed Features
This chapter provides a summary of the new features and technical
changes in VAX Rdb/VMS Version 4.0.
Section 1.1 through Section 1.17 describe new and changed features
that apply to all Rdb/VMS interfaces. The other sections describe
new features and specific changes to each interface, changes to
the sample personnel database, new and changed Rdb/VMS logical
names, obsolete statements and features for each interface, and a
summary of additions and changes to the documentation.
1.1 Two-Phase Commit Protocol
The two-phase commit protocol coordinates the activity of com-
ponents of a transaction to ensure that every required operation
is completed before a transaction is made permanent, even if the
transaction is a distributed transaction. A distributed transac-
tion groups more than one database or database attachment into one
transaction, even if the databases are located on different nodes.
If one operation in a transaction cannot be completed, none of the
operations are completed. This "all or nothing" approach guaran-
tees that distributed databases remain logically consistent with
one another. This feature has been implemented for all Rdb/VMS
interfaces: SQL, RDO, RDBPRE, and RDML.
New and Changed Features 1-1
The major benefit of using the two-phase commit protocol is that
you can divide a large Rdb/VMS database into several smaller
databases, or you can create applications that access several
different databases, without compromising the integrity or consis-
tency of your data.
For more information, see the VAX Rdb/VMS Guide to Distributed
Transactions.
NOTE
Rdb/VMS V4.0 requires VMS V5.4, which includes DECdtm
Services, in order to run the two-phase commit protocol.
Rdb/VMS returns the following error if you attempt to use
DECdtm Services while running under VMS Version 5.3:
%RDB-F-NODECDTM, DETdtm is not installed on your system
Rdb/VMS may attempt to invoke DECdtm Services implicitly if
you use the SQL interface and access two or more databases
in a transaction. This causes the previous error to be re-
turned if you are running VMS Version 5.3. You can disable
the two-phase commit protocol and avoid this error message
by defining the following logical name:
$ DEFINE SQL$DISABLE_CONTEXT TRUE
However, be sure to deassign this logical name after you
install VMS Version 5.4 to receive the benefit of two-phase
commit.
Section 1.1.1 to Section 1.1.5 document the new features and
changes that support the two-phase commit protocol.
1-2 New and Changed Features
1.1.1 Using SQL with Distributed Transactions
Beginning with Rdb/VMS V4.0, when you recompile an application
program using the SQL module processor or the SQL precompiler,
transactions use the two-phase commit protocol by default in one
of the following ways:
o By implicitly calling DECdtm system service calls
For application programs that were compiled under Rdb/VMS
V3.1 or earlier, use the two-phase commit protocol simply by
recompiling your programs. When you do, Rdb/VMS invokes the
DECdtm system service calls for your application.
o By explicitly calling the DECdtm system service calls and using
variables to pass the value of the distributed transaction
identifier (TID)
How you pass the value of the distributed TID to the applica-
tion depends upon whether you are using precompiled SQL or the
SQL module language. You must write new application programs or
modify existing programs to incorporate the following:
- In SQL module language
You must declare a context structure in the host language
program and you must pass it by reference to module proce-
dures that contain certain statements.
The context structure contains the distributed TID as one of
its elements.
In addition, you must use the /CONTEXT qualifier in the SQL
module processor command line when you process the program.
The /CONTEXT qualifier tells SQL that it should execute
module language procedures in the context of a particular
distributed transaction.
- In precompiled SQL
New and Changed Features 1-3
You must declare a context structure that contains the
distributed TID as one of its elements. In addition, you
must include a USING CONTEXT clause in most executable SQL
statements involved in the distributed transaction. The
USING CONTEXT clause associates a context structure with
a particular SQL statement and tells SQL that it should
execute the SQL statement in the context of a particular
distributed transaction.
1.1.2 Using RDBPRE with Distributed Transactions
To use the two-phase commit protocol with RDBPRE, you must either
recompile any existing application programs that were compiled
with Rdb/VMS V3.1 or earlier, or you must write new application
programs. With RDBPRE, the two-phase commit protocol is not the
default.
Applications can use the two-phase commit protocol by calling
the DECdtm system service calls implicitly or explicitly. RDBPRE
provides the following ways for application programs to use the
two-phase commit protocol:
o By implicitly calling DECdtm system services calls in the
following two ways:
- For application programs that were written under Rdb/VMS
V3.1 or earlier, use the two-phase commit protocol simply by
recompiling your programs. You must use the /DISTRIBUTED_
TRANSACTION qualifier in the precompiler command line. When
you do this, Rdb/VMS invokes the DECdtm system service calls
for your application.
- For new application programs that invoke only Rdb/VMS
databases, or Rdb/VMS databases and VIDA databases, use
the DISTRIBUTED_TRANSACTION keyword in the START_TRANSACTION
statement. When you do this, Rdb/VMS invokes the DECdtm
system service calls for your application. For example,
1-4 New and Changed Features
to recompile the COBOL program SAMPLE.RCO with the RDBPRE
preprocessor, use the following command:
$ RUN SYS$SYSTEM:RDBPRE
INPUT FILE> SAMPLE /COBOL /DISTRIBUTED_TRANSACTION
o By explicitly calling the DECdtm system service calls and using
variables to pass the value of the distributed transaction
identifier (TID)
If your application starts a distributed transaction that
includes other read/write database management products that
support the two-phase commit protocol, your application must
explicitly invoke the DECdtm system service calls. For example,
if your application starts a distributed transaction using
Rdb/VMS and VAX DBMS, your application must explicitly call
SYS$START_TRANS and SYS$END_TRANS.
In addition, you must use the full DISTRIBUTED_TRANSACTION
clause in the START_TRANSACTION statement.
1.1.3 Using RDML with Distributed Transactions
The implementation of RDML with distributed transactions is very
similar to using RDBPRE with distributed transactions. See the
VAX Rdb/VMS Guide to Distributed Transactions for a complete
description of using RDBPRE with distributed transactions and
the RDML Reference Manual and the VAX Rdb/VMS Guide to Using RDO,
RDBPRE, and RDML for more information.
To use the two-phase commit protocol with RDML, you must either
recompile any existing application programs that were compiled
with Rdb/VMS V3.1 or earlier, or you must write new application
programs. With RDML, the two-phase commit protocol is not the
default.
New and Changed Features 1-5
Applications can use the two-phase commit protocol by calling
the DECdtm system service calls implicitly or explicitly. RDML
provides the following ways for application programs to use the
two-phase commit protocol:
o By implicitly calling DECdtm system services calls in the
following two ways:
- For application programs that were written under Rdb/VMS
V3.1 or earlier, use the two-phase commit protocol simply by
recompiling your programs. You must use the /DISTRIBUTED_
TRANSACTION qualifier in the precompiler command line. When
you do this, Rdb/VMS invokes the DECdtm system service calls
for your application.
- For new application programs that invoke only Rdb/VMS
databases, or Rdb/VMS databases and VIDA databases, use
the DISTRIBUTED_TRANSACTION keyword in the START_TRANSACTION
statement. When you do this, Rdb/VMS invokes the DECdtm sys-
tem service calls for your application. For example, to re-
compile the C program SAMPLE.RC with the RDML preprocessor,
use the following command:
$ RDML :== $RDML/C
$ RDML
SOURCE FILE> SAMPLE /DISTRIBUTED_TRANSACTION
o By explicitly calling the DECdtm system service calls and using
variables to pass the value of the distributed transaction
identifier (TID)
If your application starts a distributed transaction that
includes other read/write database management products that
support the two-phase commit protocol, your application must
explicitly invoke the DECdtm system service calls. For example,
if your application starts a distributed transaction using
Rdb/VMS and VAX DBMS, your application must explicitly call
SYS$START_TRANS and SYS$END_TRANS.
1-6 New and Changed Features
In addition, you must use the full DISTRIBUTED_TRANSACTION
clause in the START_TRANSACTION statement.
1.1.4 RMU Enhancements
To support Rdb/VMS distributed transactions, two new RMU commands
(RMU/RECOVER/RESOLVE and RMU/RESOLVE) have been added, and the
RMU/DUMP command has been enhanced. These changes are as follows:
o RMU/RECOVER/RESOLVE
In the after-image journal file, you can modify the state of
records that are associated with blocked distributed trans-
actions. The RMU/RECOVER/RESOLVE command allows you either to
commit or abort blocked transactions in the after-image journal
file. See the RMU/RECOVER/RESOLVE command in the VAX Rdb/VMS
RDO and RMU Reference Manual for details.
o RMU/RESOLVE
You can modify the state of unresolved distributed transac-
tions in the database. The RMU/RESOLVE command allows you to
either commit or abort unresolved transactions in the database.
See the RMU/RESOLVE command in the VAX Rdb/VMS RDO and RMU
Reference Manual for details.
o RMU/DUMP/AFTER_JOURNAL/STATE=PREPARED
You can use the /STATE=PREPARED qualifier of the RMU/DUMP
/AFTER_JOURNAL command to generate a list of records associated
with unresolved transactions in the AIJ file. Depending upon
your application, you might need to generate the list for more
than one AIJ file. See the RMU/DUMP command in the VAX Rdb/VMS
RDO and RMU Reference Manual for details.
o RMU/DUMP/USER/STATE=BLOCKED
New and Changed Features 1-7
You can generate a list of unresolved distributed transactions
using the /USER/STATE=BLOCKED qualifiers of the RMU/DUMP com-
mand. See the RMU/DUMP command in the VAX Rdb/VMS RDO and RMU
Reference Manual for details.
1.1.5 DISTRIBTRAN Privilege
The DISTRIBTRAN privilege has been added to Rdb/VMS for all inter-
faces. This privilege allows distributed transactions that use the
two-phase commit protocol to be run on a particular database by a
particular user. If you want to start a distributed transaction on
a particular database, you must have the DISTRIBTRAN privilege for
that database or schema. Note that converted or imported databases
do not inherit this privilege automatically.
1.2 New Security Features
Rdb/VMS now includes support for the following new security fea-
tures:
o Default protection
Some enhancements to Rdb/VMS security access cause a major
change to the way in which Rdb/VMS grants default access privi-
leges to new tables. When new tables are created they will now
have a default PUBLIC access of NONE. The database will also
have default PUBLIC access of NONE. To override the default
PUBLIC access for newly created tables, provide a DATABASE
identifier with the name DEFAULT. The access that is given
to this identifier will then be assigned to any newly created
tables. This is shown in the following example:
SQL> GRANT SELECT, INSERT
cont> ON SCHEMA AUTHORIZATION TEST
cont> TO [DEFAULT];
See the VAX Rdb/VMS Guide to Database Design and Definition for
more information on default protection.
1-8 New and Changed Features
o Schema SELECT privilege
You cannot attach to an Rdb/VMS database unless you have the
schema SELECT privilege (SQL) or the READ privilege (RDO).
For more information on the SELECT privilege, see the GRANT
statement in the VAX Rdb/VMS SQL Reference Manual. For more
information on the READ privilege, see the DEFINE PROTECTION
statement in the VAX Rdb/VMS RDO and RMU Reference Manual.
o Privileges that have override capability (role privileges)
The SQL DBADM and OPERATOR (RDO ADMINISTRATOR and OPERATOR)
database privileges are role-oriented in Rdb/VMS Version 4.0.
The SECURITY privilege has the ability to override the SQL
DBCTRL (RDO CONTROL) privilege for the database, tables, and
views.
For an explanation of the tasks that can be accomplished with
these database privileges, see the GRANT statement in the VAX
Rdb/VMS SQL Reference Manual and the VAX Rdb/VMS Guide to
Database Design and Definition. For more information on the
DEFINE PROTECTION statement, see the VAX Rdb/VMS RDO and RMU
Reference Manual.
o RMU privileges
Several RMU commands require different privileges than they did
with previous versions of Rdb/VMS. The privileges required for
each RMU command are documented in the Usage Notes for the RMU
command's description in the VAX Rdb/VMS RDO and RMU Reference
Manual, and in the VAX Rdb/VMS Guide to Database Design and
Definition.
The reason that some required privileges for RMU commands
have changed is to decrease dependency on the use of elevated
VMS privileges. Many commands now use Rdb/VMS role-oriented
privileges wherever possible.
New and Changed Features 1-9
With V4.0, RMU performs tape label verification and no longer
requires SYSPRV for RMU/RESTORE or RMU/DUMP/BACKUP. All that is
be required is read access to the backup file (or tape volume
set). The change to handle tape label verification allows these
RMU commands to work without the elevated VMS SYSPRV privilege
(file/tape read access is sufficient).
o Security auditing
The RMU/SET AUDIT command enables Rdb/VMS security auditing.
When security auditing is enabled, Rdb/VMS sends security
alarm messages to terminals that have been enabled as security
operators and makes entries in the database security audit
journal whenever specified audit events are detected.
The RMU/SHOW AUDIT command displays the set of security audit-
ing characteristics that have been established with the RMU/SET
AUDIT command.
The RMU/LOAD/AUDIT command allows you to load records from an
Rdb/VMS audit journal into an Rdb/VMS relation.
You can obtain information about the audit characteristics of a
particular database by dumping the header of the database root
file, as shown in the following example.
1-10 New and Changed Features
$ RMU/DUMP/HEADER MF_PERSONNEL
.
.
.
Database parameters
.
.
.
Security auditing parameters:
- Security auditing is disabled
- Security alarm is disabled
- No audit journal filename is specified
- No alarm name is specified
- Synchronous audit record flushing is disabled
- Audit every access
.
.
.
Security audit context information is also output in the KODA
portion of a bugcheck dump file immediately following the
physical I/O (PIO) context information.
For more information on security auditing, see the description
of the RMU/SET AUDIT and RMU/SHOW AUDIT commands in the VAX
Rdb/VMS RDO and RMU Reference Manual. A tutorial on using
security auditing is in the VAX Rdb/VMS Guide to Database
Maintenance and Performance.
Some of these new security features affect Rdb/VMS installa-
tion. See the VAX Rdb/VMS Installation Guide for details.
New and Changed Features 1-11
1.3 Dynamic Optimization
Dynamic optimization is a new strategy for accessing a single
table at the leaf level of the execution tree to deliver the
best performance for each instance of the table access. Dynamic
optimization improves upon traditional optimization techniques by
providing better methods of:
o Correctly choosing index access or sequential access
o Using the correct index or combination of indexes
WARNING
Dynamic optimization now attempts to approach optimal query
performance by relying heavily on the statistics collected
during query execution. If index and table cardinalities
are artificially shifted away from their correct values,
they will contradict dynamically collected statistics and
cause quite an unpredictable selection of strategies and
sequence of their evaluation. Hence any adjustment of car-
dinalities in V4.0 will most probably result in poorer
optimizer performance.
The query optimizer uses two aspects of dynamic optimization:
o Dynamic OR optimization
o Dynamic leaf-level optimization
Dynamic OR optimization significantly improves performance of
OR index retrieval in cases where two or more index ranges are
specified on the same index by the user. The most practical cases
fall into this category.
The benefits of performing these dynamic OR operations are:
o There is one open/close operation (instead of INDEX SCAN).
1-12 New and Changed Features
o There are N*Log2(N)+N comparisons for sort and collapsing key
ranges instead of (N - 1)/2 * Retrievals comparisons (assuming
singletons.)
o The substantial overhead of traveling through N-way concatena-
tion of multiple streams is eliminated.
o There are no unnecessary I/O operations for overlapping ranges.
o The result always comes up in sorted index order.
Implementing the dynamic OR optimization technique has resulted in
new notation for high Ikey and low Ikey segments that can be seen
in output that displays as part of the index retrieval strategy.
See the VAX Rdb/VMS Guide to Database Maintenance and Performance
for more information on notation changes.
With the addition of dynamic optimization as a new strategy for
accessing a single table at the leaf level of an execution tree,
you should no longer avoid the use of the BETWEEN relational
operator. The BETWEEN relational operator performs as expected
in V4.0.
The example, (X BETWEEN X AND Z) still translates to:
((X >= Y) AND (X <= Z)) OR ((X >= Z) AND (X <= Y))
However, with dynamic optimization, the two X ranges (one in-
verted) are merged either during compilation of the query or at
query execution time into a single range (note that one of the
two ranges is empty). Therefore, a single scan of an index fetches
all the required data. So the BETWEEN operator now performs as
expected.
In versions previous to V4.0, use of the BETWEEN relational opera-
tor caused two separate index scans to take place (with one of the
two scans returning zero data as expected). The result of the two
scans was then merged. The merging of data spoiled the index key
order of the data and sometimes forced an extra sort of the data.
New and Changed Features 1-13
The primary benefit of dynamic leaf-level optimization is to
provide near-optimal performance for each instance of the table
access even within the same query run regardless of:
o The data distribution
o The columns correlation
o When zero or small numbers of selected rows are delivered in
one instance
o When all or many rows are delivered in the other instance of
the same leaf execution
Dynamic leaf-level optimization is much different from the tradi-
tional data access techniques found in Rdb/VMS V3.1 and previous
versions. These techniques unavoidably made mistakes (sometimes
fatal) in choosing between index or sequential access or in se-
lecting the wrong index or wrong combination of indexes.
Four leaf types comprise dynamic leaf-level optimization:
o Background-only leaf
The most important component of dynamic optimization is a
background process that scans ranges of one or more indexes
and delivers a list of dbkeys to be used at the final stage
of retrieval for fetching data rows. Each index scan continues
only to the point where random data row fetches done by an
already built portion of a dbkey list become more expensive
than a sequential retrieval. If such a cost break point is
reached, this index scan is abandoned and other indexes are
tried. If all indexes are abandoned, a sequential retrieval is
then performed.
When at least one dbkey list is successfully built before
reaching a cost break point, the dbkey lists of the other
index scans do not need to include the dbkeys missing from any
previously completed dbkey lists. Such AND logic operations
of dbkey lists leads to a quick reduction of the complete
1-14 New and Changed Features
dbkey lists' sizes, hence cutting the biggest cost portion
of retrieval, that is, the cost of random data row fetches.
The AND logic operations of dbkey lists is done either by dbkey
bitmap filtering or by direct checking against the stored dbkey
lists in the buffers. The bitmap filtering technique is used
for long dbkey lists which are stored into temporary tables.
Index ranges are scanned interactively in ascending order
of their estimated selectivities. This insures faster dbkey
list reduction, which leads to a faster exclusion of long
index scans with a potential scan cost exceeding the cost
of the final data row fetches based on the shortest complete
dbkey list. To compensate for inaccuracy of the selectivity
estimates, at each iteration, two indexes (current and next)
are scanned simultaneously for a short while. If one of the two
scans completes during this period, the first to finish takes
over; otherwise the scan of the current index of this iteration
continues alone until it succeeds or is rejected.
The background process provides a reliable way for delivering
the shortest dbkey list (the result of AND logical operations)
or selects a sequential scan as the optimal strategy for the
final stage of delivering the data rows. However, when the
cost of providing optimality becomes higher than the profit,
the perfectness of the final strategy is sacrificed in favor
of balancing experimental and productive costs. The ultimate
criterion of this self-sensing background optimization is to
minimize the total cost of retrieving the entire collection of
requested data rows. This case of dynamic leaf-level optimiza-
tion is called the background-only total time optimization:
Delivers a list of dbkeys or selects a sequential scan - BgrOnly leaf type
o Fast-first leaf
In contrast to total time optimization, some queries or user
applications may only need to look at the first or first sev-
eral data rows of a potentially large resulting set of rows.
For example, the EXISTS predicate only checks for the presence
of the first data row, and an interactive user typically looks
New and Changed Features 1-15
at the first screen or the first several screens, not thousands
of them, before canceling the query.
In this case, dynamic optimization runs the background process
"borrowing" dbkeys from it, fetches and delivers data rows, and
allows the user or query operators like EXISTS to end the re-
trieval when it is convenient. However, such "borrowing" takes
place for only a limited time because of the potential overhead
of unproductive fetches. Above this limit, the background pro-
cess takes over, stops data delivery, and continues in the most
efficient manner for total time optimization. This method of
optimizing the speed of delivering the first several rows (and
total delivery time when the user does not care to terminate
the query after receiving the first several rows) is called the
fast-first optimization:
Fast-first several rows delivery is required - FFirst leaf type
o Sorted-leaf
The query's ORDERED BY clause or the query's execution strategy
requirements may request a specific order of retrieval when
an index exists that is capable of providing this order. Such
a sorted index is scanned to the end of its range, fetching
and delivering rows while scanning. When other useful indexes
are present, dynamic optimization takes on the form of a par-
allel run of the "sorted" index scan and a background process
based on these other useful indexes. The "sorted" index scan is
called a foreground process because it is visible and control-
lable from outside of the retrieval. Parallelism is imitated by
quick switching between the foreground and background processes
allowing for synchronization of the speed of the two processes.
When the background process completes any of its index scans, a
filter built at this scan is immediately used by the foreground
process for rejecting the dbkeys not in the filter before
fetching a data row. The benefit of foreground filtering can be
substantial because again, row fetches comprise the most costly
part of retrieval. The reason for parallel running is to avoid
the extra background cost when the foreground range is small
1-16 New and Changed Features
and the foreground finishes earlier than the background. This
type of optimization is called sorted dynamic optimization:
Rows are needed in sorted index order - Sorted leaf type
CAUTION
With the sorted-leaf strategy, the execution trace lines
may incorrectly show some extra 'CUT and/or 'ABA words
at the ends of lines.
o Index-only leaf
Quite often an index is available containing all restrictions
and resulting columns within itself. If, in addition to such an
"index-only" index, other useful indexes are also available,
dynamic optimization scans the index-only index in parallel
with a running background process. This is a direct competition
between the two processes. No extra filtering is needed for
an index-only scan because the index contains all the columns
required for full restriction evaluation and therefore does not
need to perform any fetches. The parallel run is limited and is
used only for detecting the first to finish in order not to pay
a very high price for an incorrect selection of a background
strategy versus the foreground index retrieval scan.
On the background side, its quick success is determined with
only a fraction of the total expense, which includes the costly
final stage fetches. Because of this, the "experimental" double
run overhead is still only a relatively small portion of the
cost incurred by an incorrect strategy selection. This type of
optimization is called index-only dynamic optimization:
Only the columns from an index-only key are needed - NdxOnly leaf type
Two new debug flags, in combination with the "S" (access strategy
print) debug flag, allow you to observe the behavior of dynamic
optimization.
New and Changed Features 1-17
o The "E" debug flag prints the execution trace dump that con-
sists of:
- One line at the conclusion or termination of each background
index
- One line at the conclusion or termination of the foreground
index
- One line at the conclusion or termination of the final
phase
In certain situations, any of the preceding lines may be absent
in the "E" debug flag dump, indicating that a given phase was
not needed for a given leaf run. However, at least one line is
always printed.
o The "\" debug flag sets the internal dbkey buffer size to a
very small (testing) value of 10 dbkeys. This allows you to
test dynamic optimization with small tables by forcing the
usage of temporary tables for storing dbkey lists.
WARNING
The "\" debug flag should be used only for testing or
problem solving. It is not intended for production use
because it slows down the system.
Note that the phrase Card=(cardinality-value) appears in the
display output when you perform queries with the access strategy
flag "S" set. The cardinality displays on the Leaf# lines in the
output and provides the values for relations from which rows are
retrieved. For example, it appears as follows:
Leaf#01 FFirst RDB$RELATIONS Card=19
This indicates that the cardinality of (number of records in)
relation RDB$RELATIONS is 19.
1-18 New and Changed Features
For more information on dynamic optimization, see Chapter 17 on
the query optimizer and RDMS$DEBUG_FLAGS in the VAX Rdb/VMS Guide
to Database Maintenance and Performance.
1.4 Other Optimizer Enhancements
Section 1.4.1 through Section 1.4.4 describe enhancements to the
query optimizer.
1.4.1 More Efficient Strategies for Queries Whose WHERE Expression
Has OR Booleans
The optimizer will generate more efficient strategies for queries
whose WHERE expression has OR Booleans. In particular, the same
efficient strategies will be produced independent of how the join
Booleans are specified with respect to the OR Booleans within
the WHERE expression. For instance, the same strategies will be
produced for the following two queries whose WHERE expressions are
in different form but are equivalent.
SELECT *
FROM EMPLOYEES E, SALARY_HISTORY S
WHERE (E.EMPLOYEE_ID = S.EMPLOYEE_ID AND E.EMPLOYEE_ID = '00166')
OR
(E.EMPLOYEE_ID = S.EMPLOYEE_ID AND E.EMPLOYEE_ID = '00200')
SELECT *
FROM EMPLOYEES E, SALARY_HISTORY S
WHERE E.EMPLOYEE_ID = S.EMPLOYEE_ID AND (E.EMPLOYEE_ID = '00166'
OR
E.EMPLOYEE_ID = '00200')
Before V4.0, the strategies produced for these two queries were
different and highly dependent on how join Booleans were speci-
fied in relation to OR Booleans within the WHERE expression. The
strategy produced for the first query whose WHERE expression is
in disjunctive normal form (DNF) was highly inefficient. In V4.0,
New and Changed Features 1-19
the optimizer factors the common join Booleans out of the OR ex-
pression, thus producing a more efficient strategy for the first
query.
1.4.2 Improved Performance for Tables Stored in Mixed Format Storage
Areas
Starting with V4.0, for a table stored in a mixed format storage
area the optimizer will consider each of its sorted indexes as a
potential index retrieval method. This is done to avoid a sequen-
tial scan of the table, which causes each page in the mixed format
area to be accessed.
As an example, consider the following query:
SELECT LAST_NAME FROM EMPLOYEES;
In versions prior to V4.0, a sequential retrieval of the EMPLOYEES
table was done. This was because the optimizer did not consider
an index as useful if none of its index segments was referenced
in the query. Therefore, for the preceding query, the index EMP_
EMPLOYEE_ID was never used to retrieve data from the EMPLOYEES
table.
For the same query in V4.0, the optimizer chooses the EMP_
EMPLOYEE_ID index to do index retrieval of the EMPLOYEES table.
However, if the size of the table is large relative to the size of
the mixed storage area, then the optimizer may choose sequential
scan of the table as the optimal method of retrieval.
1.4.3 Optimization and Aggregates
The following changes have been made to aggregates:
o Aggregates are joined at optimal positions in the solution
plan.
1-20 New and Changed Features
Aggregates are now joined at the outermost possible position
in the solution plan, allowing faster execution of queries
involving aggregates that return invariant values, or have
dependencies on contexts that are outermost to the query in
which they are specified. This effectively un-nests many cases
of nested aggregates.
o Queries involving numerous aggregates are optimized faster
Queries involving many aggregation functions, for instance
printing a table with numerous COMPUTED BY fields whose value
expressions contain aggregates, now optimize within a reason-
able amount of time (instead of hours).
o ANY and UNIQUE Booleans use retrieval limits
The ANY class Booleans (RDO ANY; SQL ANY, SOME, and ALL) now
terminate the query on the first row that matches the Boolean
query criteria; and the RDO UNIQUE Boolean now terminates the
query on the second matching row (it previously selected all
matching rows and evaluated count against 0 or 1). The use of
the limit retrievals can be seen in strategy dumps where the
aggregate is now represented as:
for ANY : Aggregate-F1
for UNIQUE : Aggregate-F2
o Better match strategies are produced when matching aggregates
The match strategy with inner leg as the aggregate eliminates
the need for a temporary table when not sorting, and uses zig-
zag matching with any index that can be used for the match
criteria.
New and Changed Features 1-21
1.4.4 Constraint Evaluation
The following improvements have been made to constraint evalua-
tion:
o Constraint evaluation on a MODIFY or UPDATE clause
Rdb/VMS evaluates constraints on a MODIFY or UPDATE clause
only when the column values change. Rdb/VMS no longer evaluates
constraints if the columns referenced by the constraints have
not actually been modified.
o Constraints consume less compilation and execution resources
Constraint compilation for any given update request now takes
up to 50% less time, and the resultant constraint execution
structures take up to 50% less virtual memory. In addition, the
number of constraints queued for deferred execution (CHECK ON
COMMIT) is frequently less, by a factor of the number of rows
updated per the request.
o Constraints execute reliably
Prior to V4.0, constraints might not be executed as required,
could be executed too many times, and too many constraints
might be selected or executed (see Chapter 2 for details).
o FOREIGN KEY constraints optimized for verb time evaluation
Updates and deletions to PRIMARY KEY values referenced by
FOREIGN KEY constraints no longer cause a full scan of the
PRIMARY KEY table when the FOREIGN KEY constraint is executed
at verb time. Such constraints are optimized to compare the
FOREIGN KEY column values against only the old values of the
PRIMARY KEY columns. This optimization is not available for
constraints whose evaluation is deferred until SQL statement
end or COMMIT.
o DELETE CONSTRAINT 'active query' diagnostic was misleading
1-22 New and Changed Features
Attempts to delete a constraint in RDO might return an excep-
tion indicating that queries involving a table referenced in
the constraint were active. Although this situation can oc-
cur, the far more common case is that the constraint occurs
in the list of constraints deferred till COMMIT time, and the
transaction must first be terminated before the constraint can
be deleted. This situation is indicated by the following new
exception.
CMTCONNOTDEL cannot delete constraint 'constraint-name'
queued for COMMIT evaluation
1.5 Journaling of Metadata Updates
Most metadata updates are journaled in both RUJ and AIJ files and
execute in a read/write transaction (including storage area and
schema updates)
These metadata updates complete the transaction with an explicit
COMMIT or ROLLBACK statement except for storage area and schema
updates, which complete with an implicit commit operation.
NOTE
In V4.0, if no AIJ records for a transaction are submitted
to the AIJ file, a rollback record is not written. In ver-
sions previous to V4.0, any write operation to a database
page followed by a rollback would have written a rollback
record for this transaction to the AIJ file.
The following changes to the database parameters are not jour-
naled:
o Changing the number of users
o Changing the number of nodes
o Adding or deleting a storage area
New and Changed Features 1-23
o Changing the name of the AIJ file
NOTE
If you plan to change any of the database parameters that
are not journaled in your database application, Digital
recommends that you back up your database before attempting
these changes. This is because if the change fails for some
reason while not being journaled, the database will become
corrupt on a rollforward after a restore operation. If you
have backed up your database, you can restore your database
from the backup copy.
Once you have made these changes, it is necessary to
backup your database again in case you have to restore
your database from the backup at some time in the future.
1.6 Multiple Segmented String Storage Areas
You can now define multiple storage areas to be used for segmented
strings, specifying some areas as read, some as write, and some
as read/write. You can specify segmented strings to be stored in
tables or as separate fields in storage areas using the storage
map statement.
The following is an example of the SQL syntax for this feature:
CREATE STORAGE MAP name
STORE LISTS IN area1 FOR (TABLE1,TABLE2)
IN area2 FOR (table1.column)
IN RDB$SYSTEM;
The RDO syntax for this feature is:
1-24 New and Changed Features
DEFINE STORAGE MAP name FOR SEGMENTED STRINGS
STORE
WITHIN area1 FOR relation1, relation2;
WITHIN area2 FOR relation1.field;
RDB$SYSTEM
END.
In the preceding examples, segmented strings for relation1
and relation2 are stored within area1, segmented strings for
table1.column or relation1.field are stored in area2, and other
segmented strings are stored in the RDB$SYSTEM storage area. Note
that the default storage area selected with the SQL CREATE SCHEMA
or RDO DEFINE DATABASE statement must be named and must remain the
default.
If a relation is named for more than one storage area, Rdb/VMS
selects an area at random.
If multiple areas do not have any relations specified, the storage
area to be used is selected at random. However, RDB$SYSTEM or
whatever area was specified as the default at database creation is
used for the system relations' segmented strings.
Options normally used by storage maps, such as ENABLE COMPRESSION
and WITH LIMIT OF clauses cannot be used with multiple storage
area segmented strings.
The CHANGE STORAGE MAP statement can delete an area only if there
are no segmented strings in the area. You cannot move a segment
from one area to another. Changing the area or areas assigned to
a relation has no effect on current segmented strings, only on
future storage.
New and Changed Features 1-25
1.7 Lock Timeout Mechanism
To help avoid distributed deadlock, Rdb/VMS provides the new
logical name, RDM$BIND_LOCK_TIMEOUT_INTERVAL, to set the amount of
time a transaction waits for locks to be released.
Another method that Rdb/VMS provides to set the amount of time a
transaction waits for locks to be released is the WAIT <interval>
clause of the SET TRANSACTION or DECLARE TRANSACTION statement.
See the VAX Rdb/VMS Guide to Distributed Transactions for more
information.
1.8 Compressed Indexes
Work has been done to improve the functionality of Rdb/VMS sorted
and hashed indexes. As a result, Rdb/VMS is able to provide
smaller index nodes. There are three new types of index compres-
sion that are possible:
o Compressed key suffixes in indexes
Users can now specify that the "first n" characters of a cer-
tain key are to be used in the index. For example, to place an
index on a 100-byte field that is generally unique to the first
20 bytes, you could specify the first 20 bytes and save as much
as 80 bytes per entry.
Compressed key suffixes also enable the user to use fields
longer than 254 characters as index keys.
o Null bit bitwise compression
Rdb/VMS uses only a single bit (the lowest bit of the null
byte) to maintain null bit information within a database.
o Numeric integers bitwise compression
1-26 New and Changed Features
Rdb/VMS has reduced the number of bits needed to store indexes
of all-numeric fields by translating the field values into a
more compactly encoded form.
Index compression results in the following benefits:
o Much lower storage requirements for some applications
o Fewer I/O operations to retrieve data, since more user index
nodes may be included in buffers
o More efficient index-only retrieval, since more data may rea-
sonably be included in an index
In SQL, to create a compressed index for columns that use the CHAR
or VARCHAR data types, use the SIZE IS clause of the CREATE INDEX
statement for the column or columns being indexed, as shown in the
examples. Also, to create a compressed index on CHAR or VARCHAR
data type columns, you must not use the unique clause, which is
the default.
In SQL:
CREATE INDEX PS_DESCRIPTION ON PRODUCT_SCHEDULE
(PRODUCT_DESCR SIZE IS 30);
In RDO, to create a compressed index for columns that use the TEXT
or VARYING STRING data types, use the SIZE IS clause of the DEFINE
INDEX statement for the column or columns being indexed, as shown
in the examples. Also, to create a compressed index on TEXT or
VARYING STRING data type columns, you must use the DUPLICATES ARE
ALLOWED clause, which is the default.
In RDO:
New and Changed Features 1-27
DEFINE INDEX PS_DESCRIPTION
DESCRIPTION IS
/*
Product description starts with
30 characters of unique identification
*/
FOR PRODUCT_SCHEDULE.
PRODUCT_DESCR SIZE IS 30.
END.
In both SQL and RDO, the column size must be the same length or
greater in length than the value specified in the SIZE IS clause.
In the RDO example at the end of this section, the COUNTRY and
CITY columns must be of data type TEXT or VARYING TEXT, and they
must be equal to or larger than 10 and 5 characters in length,
respectively.
In SQL, to create a compressed index for columns that use TINYINT,
SMALLINT, and INTEGER data types, use the MAPPING VALUES clause
of the CREATE INDEX statement for the column or columns being
indexed, as shown in the examples. You can use the UNIQUE clause
with an integer compressed index. In the examples, PRODUCT_ID,
YEAR_NUMBER, and PRODUCT_DESCR are the three columns that are
defined with the UNIQUE clause.
In SQL:
CREATE UNIQUE INDEX PS_DATE_2 ON PRODUCT SCHEDULE
(PRODUCT_ID,
YEAR_NUMBER MAPPING VALUES 1970 to 2070,
PRODUCT_DESCR SIZE is 20);
In RDO, to create a compressed index for columns that use SIGNED
BYTE, SIGNED WORD, and SIGNED LONGWORD data types, use the MAPPING
VALUES clause of the DEFINE INDEX statement for the column or
columns being indexed, as shown in the examples. You can use
the DUPLICATES ARE NOT ALLOWED clause with an integer compressed
index. In the examples, PRODUCT_ID, YEAR_NUMBER, and PRODUCT_DESCR
are the three columns that are defined with the DUPLICATES ARE NOT
ALLOWED clause.
1-28 New and Changed Features
In RDO:
DEFINE INDEX PS_DATE_2 FOR PRODUCT_SCHEDULE
DUPLICATES ARE NOT ALLOWED.
PRODUCT_ID.
YEAR_NUMBER MAPPING VALUES 1970 to 2070.
PRODUCT_DESCR SIZE IS 20.
END.
Note that you can mix mapped and unmapped columns, but the most
storage space is gained by building indexes of multiple columns of
data type in SQL of SMALLINT and INTEGER or in RDO of SIGNED WORD
or SIGNED LONGWORD. Rdb/VMS attempts to pack all such fields into
the smallest possible space.
The following additional RDO examples define several text and
integer compressed indexes.
!
! Define the integer compressed index PORT_NUM_CINDEX on the PORT_NUM
! field of the PORT relation:
!
DEFINE INDEX PORT_NUM_CINDEX FOR PORT DUPLICATES NOT ALLOWED.
PORT_NUM MAPPING VALUES 90 TO 1000.
END.
!
! Define the text compressed index PORT_COUNTRY_CITY_INDEX on the
! COUNTRY and CITY fields of the PORT relation:
!
DEFINE INDEX PORT_COUNTRY_CITY_CINDEX FOR PORT.
COUNTRY SIZE 10.
CITY SIZE 5.
END.
New and Changed Features 1-29
!
! Produce a list of ports sorted by COUNTRY and CITY name from
! the PORT relation:
!
FOR P IN PORT SORTED BY P.COUNTRY, P.CITY PRINT P.* END_FOR
!
! Define the integer compressed index CHANNEL_DEPTH_CINDEX on the
! CHANNEL_DEPTH field of the PORT relation:
!
DEFINE INDEX CHANNEL_DEPTH_CINDEX FOR PORT.
CHANNEL_DEPTH MAPPING VALUES 20 TO 100.
END.
!
! Define the integer compressed index DISTANCE_CINDEX on the
! DISTANCE field of the PORT relation:
!
DEFINE INDEX DISTANCE_CINDEX FOR PORT.
DISTANCE MAPPING VALUES 0 TO 30000.
END.
!
! Define the integer compressed index TRANS_COST_CINDEX on the
! TRANS_COST field of the PORT relation:
!
DEFINE INDEX TRANS_COST_CINDEX FOR PORT.
TRANS_COST MAPPING VALUES 0 TO 10000.
END.
!
! Define the integer compressed index PNUM_CDEP_DIST_TCOST_CINDEX
! on the PORT_NUM, CHANNEL_DEPTH, DISTANCE, and TRANS_COST fields
! of the PORT relation:
!
DEFINE INDEX PNUM_CDEP_DIST_TCOST_CINDEX FOR PORT
DUPLICATES NOT ALLOWED.
PORT_NUM MAPPING VALUES 100 TO 1000.
CHANNEL_DEPTH MAPPING VALUES 20 TO 100.
DISTANCE MAPPING VALUES 0 TO 30000.
TRANS_COST MAPPING VALUES 0 TO 10000.
END.
1-30 New and Changed Features
!
! Define the CHANNEL_DEPTH_DESC_CINDEX index on the CHANNEL_DEPTH
! field of the PORT relation. The DESCENDING keyword causes descending
! index segments to be created for the CHANNEL_DEPTH field.
!
DEFINE INDEX CHANNEL_DEPTH_DESC_CINDEX FOR PORT.
CHANNEL_DEPTH DESCENDING MAPPING VALUES 20 TO 100.
END.
1.9 New Data Type-SQL TINYINT and RDO SIGNED BYTE
A new data type, TINYINT (SQL) and SIGNED BYTE (RDO), has been
added to Rdb/VMS. This data type occupies a single byte and can
be used for data with small ranges and limited values. The values
(unscaled) must fall in the range -128 through 127.
Some examples of columns where this data type can be useful in-
clude:
o Ages
o Department codes
o Status information
o Tax rates (if range is 0.00 to 12.7)
o Number of children
o Mortgage payment 'days of grace'
VAX CDD/Plus does not currently support SIGNED BYTE for Rdb/VMS
databases. Therefore, you must define the field while attached
by FILENAME. This will be corrected in a version of VAX CDD/Plus
after Version 4.2.
Some example definitions using this new data type in SQL and RDO
are as follows:
New and Changed Features 1-31
In SQL:
CREATE DOMAIN DEPARTMENT_CODE TINYINT DEFAULT -128;
CREATE DOMAIN STATUS TINYINT;
CREATE DOMAIN TAX_RATE TINYINT(1);
CREATE TABLE PAYMENT_DUE
(ACCOUNT ACCOUNT_NUMBER,
AMOUNT MONEY,
DAYS_OF_GRACE TINYINT,
CHECK(DAYS_OF_GRACE BETWEEN 0 AND 31));
In RDO:
DEFINE FIELD AGE
DATATYPE SIGNED BYTE
VALID IF (AGE > 0) AND (AGE NOT MISSING).
DEFINE FIELD NUMBER_CHILDREN
DATATYPE SIGNED BYTE
VALID IF (NUMBER_CHILDREN >= 0) OR (NUMBER_CHILDREN MISSING).
DEFINE FIELD DEPARTMENT_CODE
DATATYPE SIGNED BYTE SCALE 1
MISSING_VALUE -1280.
1.10 EXPORT Now Supports the DATA Option
A new option has been added to the SQL and RDO EXPORT statements.
o DATA and NO DATA
Export allows a database to be exported without the data. This
new feature of the EXPORT statement simplifies the task of
creating a duplicate copy of a database, and it allows a DBA to
experiment with storage areas and storage maps.
In SQL, the new NO DATA option can be specified with either the
EXTENSIONS or NO EXTENSIONS option. The default option is DATA.
1-32 New and Changed Features
SQL> EXPORT SCHEMA
cont> FILENAME db-root-file
cont> INTO rbr-file
cont> WITH EXTENSIONS, NO DATA;
In RDO, the new NODATA option can be specified with either the
EXTENSIONS or NOEXTENSIONS option. The default option is DATA.
RDO> EXPORT db-root-file
cont> INTO rbr-file
cont> WITH EXTENSIONS, NODATA
1.11 IMPORT Now Supports DATA and TRACE Options
New options have been added to the SQL and RDO IMPORT statements.
o DATA and NO DATA
The IMPORT NO DATA option is similar to the EXPORT NO DATA op-
tion. The IMPORT NO DATA option allows a database administrator
to create an empty database with the same characteristics as an
existing database.
IMPORT reads the interchange file (RBR) and skips over any
data in the file. The resulting database is useful for testing
IMPORT options and creating testing databases.
The default is DATA.
In SQL:
SQL> IMPORT SCHEMA
cont> FROM PERSONNEL.RBR
cont> FILENAME PERSONNEL
cont> NO DATA;
In RDO:
RDO> IMPORT PERSONNEL.RBR INTO PERSONNEL
cont> NOACL NOBATCH_UPDATE NODATA
cont> END IMPORT.
New and Changed Features 1-33
o TRACE and NOTRACE
Several phases of the IMPORT operation require disk I/O op-
erations and can be time consuming. The significant phases
include:
- Loading the data from the RBR file
This phase requires I/O operations to the RBR file, the
database storage areas, and possibly index lookups if the
PLACEMENT VIA INDEX clause is used in a storage map.
- Defining indexes
This phase requires reading data from the database and
sorting it before creating the index.
- Defining constraints
When constraints are defined they must be validated against
the existing data that required I/O operations to the
database storage areas.
The TRACE option allows the database administrator to deter-
mine which phase and which entities require the most resources.
After each relation, index, and constraint is defined statis-
tics are displayed showing page faults, CPU time, and direct
I/O operations used. A final statistics line summarizes the
total disk I/O operations used and the total time of the IMPORT
operation.
The default for the IMPORT statement is NO TRACE.
In SQL:
SQL> IMPORT SCHEMA
cont> FROM PERSONNEL.RBR
cont> FILENAME PERSONNEL
cont> DATA TRACE;
1-34 New and Changed Features
In RDO:
RDO> IMPORT PERSONNEL.RBR INTO PERSONNEL
cont> TRACE
cont> END IMPORT.
1.12 Rdb/VMS V4.0 Gives Special Treatment for CDD/Plus Dictionaries
Three changes have been made to Rdb/VMS V4.0 to better support
CDD/Plus dictionary databases.
o CDD/Plus flags new databases
CDD/Plus dictionary databases (CDD$DATABASE.RDB) are now
flagged as special databases by Rdb/VMS.
o Changes to the EXPORT statement
This flag is saved in the interchange file (RBR) by the SQL and
RDO EXPORT operation.
The EXPORT statement option WITH NOEXTENSIONS is not permitted
for CDD/Plus dictionary databases. Attempts to use the WITH
NOEXTENSIONS option result in an error message as shown in
the next example. (Using this option on CDD/Plus dictionaries
caused numerous CDD/Plus dictionary database corruptions be-
cause the NULL bit settings were lost by this type of EXPORT
operation.)
The EXPORT option WITH NODATA is also not permitted for
CDD/Plus dictionary databases. Attempts to use the WITH NODATA
option result in an error message as shown in the next example.
The metadata without the data is not useful for CDD/Plus.
o Changes to the IMPORT statement
This flag is restored by the SQL and RDO IMPORT operation.
New and Changed Features 1-35
If the flag is set, then the IMPORT NODATA option is illegal.
This will prevent creation of unusable dictionary databases.
NOTE
CDD/Plus dictionary databases created prior to V4.0 are not
flagged as special databases. A future version of CDD/Plus
will set this flag as part of its upgrade procedure.
The following examples show error messages generated if illegal
operations are attempted on CDD/Plus dictionary databases.
$ RDO
!
! Try to do an EXPORT with NODATA (Should FAIL with RDO-F-EXP_CDD_NODATA)
!
EXPORT TEST$CDD:CDD$DATABASE.RDB INTO TEST_EXPORT.RBR WITH NODATA
%RDO-F-DELBACKUP, EXPORT errors, interchange file deleted
-RDO-F-EXP_CDD_NODATA, Exporting a CDD dictionary with NODATA is not allowed
!
! Try to do an EXPORT with NOEXTENSIONS (Should FAIL with RDO-F-EXP_CDD_NOEXT)
!
EXPORT TEST$CDD:CDD$DATABASE.RDB INTO TEST_EXPORT.RBR WITH NOEXTENSIONS
%RDO-F-DELBACKUP, EXPORT errors, interchange file deleted
-RDO-F-EXP_CDD_NOEXT, Exporting a CDD dictionary with NOEXTENSIONS is
not allowed
!
! Try to do an EXPORT with DATA (Should SUCCEED) and then try and
! do an IMPORT
!
EXPORT TEST$CDD:CDD$DATABASE.RDB INTO TEST_EXPORT.RBR WITH DATA, EXTENSIONS
1-36 New and Changed Features
!
! IMPORT the database with NODATA (Should FAIL with RDO-F-IMP_CDD_NODATA)
!
IMPORT TEST_EXPORT.RBR
INTO TEST$SCRATCH:TEST_IMPORT.RDB
DICTIONARY IS NOT USED
NODATA
END IMPORT.
Exported by Rdb/VMS V4.0-0 Export/Import utility
A component of Rdb/VMS V4.0-0
Previous name was TEST$CDD:CDD$DATABASE.RDB
It was logically exported on 16-APR-1990 17:00:10.95
Database page size is 8 blocks
Database NUMBER OF USERS is 200
Database NUMBER OF VAXCLUSTER NODES is 16
Database NUMBER OF DBR BUFFERS is 20
Database SNAPSHOT is ENABLED
Database SNAPSHOT is IMMEDIATE
Database BUFFER SIZE is 24 blocks
Database NUMBER OF BUFFERS is 30
IMPORTing STORAGE AREA: RDB$SYSTEM
%RDO-F-IMP_CDD_NODATA, Importing a CDD dictionary with NODATA is not allowed
1.13 SHOW STORAGE AREA Shows a Different Storage Area Allocation
In SQL and RDO, the SHOW STORAGE AREA statement now displays
the current maximum area allocation for the storage area, not
the initial allocation as in previous releases of Rdb/VMS. This
provides the database administrator with a much better picture of
storage area disk usage.
New and Changed Features 1-37
1.14 Setting Line Lengths for a File or Output Device
In SQL and RDO, you can specify the default line length in the
interactive interfaces for output from the SQL SELECT and RDO
PRINT statements by using either the SQL SET LINE LENGTH or RDO
SET LINE_LENGTH statement.
RDO> SET LINE_LENGTH n !underscore
SQL> SET LINE LENGTH n !no underscore in SQL
This statement allows you to specify an alternate line length for
a file or alternate output device.
1.15 Changes to Run-Unit Journal (RUJ) Files
The following changes have been made to RUJ file default creation:
o RUJ file naming convention changed
The RUJ file naming convention is changed to:
<database_name>$<timestamp generated number>.RUJ
This prevents multiple versions of RUJ files from using the
same file name and the possibility of RUJ files being lost due
to a random purge of directories.
o RUJ file placement changed
RUJ file placement no longer defaults to SYS$LOGIN. The RUJ
files now default to their own top level directory [RDM$RUJ]
on the device in which SYS$LOGIN is defined. This alleviates
the problem of RUJ files being scattered around in users'
directories. If a system manager wishes to change the default
placement semantics, the RDMS$RUJ logical name can be defined
systemwide to SYS$LOGIN, and the "old" placement schemes used
by Rdb/VMS versions previous to V4.0 are used.
1-38 New and Changed Features
The RDMS$RUJ logical name used for RUJ placement has not
changed. The [RDM$RUJ] directory is created automatically by
the first user on the disk that creates an RUJ file. It will
remain there indefinitely. It is owned by the [SYSTEM] iden-
tifier. Be certain that the [SYSTEM] identifier has write (W)
and execute (E) privileges to create this top level directory
[RDM$RUJ]. You can create ACLs on it if you wish, as the users
are given privileges internal to Rdb/VMS to create or delete
RUJ files. The RUJ files created within the directory are owned
by the individual users.
CAUTION
In Section 9.3 of the VAX Rdb/VMS Guide to Database
Maintenance and Performance, information is presented de-
scribing what you can do if you have lost your AIJ file
because of a disk drive problem. A solution is documented
suggesting you can create a dummy AIJ file in the direc-
tory where the root file says it should be located to get
your database up and running again. Though not documented,
this method can also be used for missing RUJ files in ver-
sions previous to V3.1. The risk involved in this method is
that your database may be left inconsistent and no message
displays to indicate this fact.
Beginning with V3.1 this technique is no longer sup-
ported because it could leave your database inconsis-
tent. Beginning with V4.0, RMU/ALTER has syntax (see
Section 3.9.21) to support this technique as a workaround.
However, the database is marked as "eternally corrupt." The
only method of clearing an "eternally corrupt" database is
to restore and recover from a clean backup and AIJ file.
New and Changed Features 1-39
1.16 Change to Batch-Update and Exclusive Transaction Behavior
The following change has been made to batch update and exclusive
transaction behavior:
o Batch and exclusive update transactions cannot be started if
RDB$SYSTEM is read-only. When a transaction reserves a relation
in exclusive or batch-update mode and the SYSTEM area is read-
only, you now receive the error message:
BATCH or EXCLUSIVE UPDATE access is not allowed if RDB$SYSTEM is READ ONLY
Because Rdb/VMS now does not allow exclusive transactions
from starting when the database is read-only, active read-only
transactions can proceed without being affected.
See Section 2.1.39 for more information.
1.17 DECtrace Support for Trigger and Constraint Statistics
Rdb/VMS has provided DECtrace with support for trigger and con-
straint statistics.
1.18 SQL: New and Changed Features and Statements
SQL provides LSE template support for most of these new features
and statements in both interactive SQL and module language. See
the VAX Rdb/VMS SQL Reference Manual for more information.
See information in Section 1.1 through Section 1.17 for additional
new and changed SQL features.
1.18.1 Support for the Two-Phase Commit Protocol
SQL supports the two-phase commit protocol. See Section 1.1
for more information. See the VAX Rdb/VMS Guide to Distributed
Transactions for more information.
1-40 New and Changed Features
1.18.2 New SQL Syntax
The following SQL statements and language elements are new for
Rdb/VMS V4.0:
o ALTER TABLE and CREATE TABLE
The ALTER TABLE and CREATE TABLE statements accept the new
COMPUTED BY clause, which associates a value expression with a
column name in a table definition.
o BETWEEN predicate
SQL now evaluates the BETWEEN predicate to comply with the
ANSI/ISO standard. In the following example, you must specify
the lower value (value2) before the higher one (value3).
value1 BETWEEN value2 AND value3
o LIMIT TO argument
The LIMIT TO argument has been added to the select-expression
clause of the SQL SELECT statement and the SQL DECLARE CURSOR
statement.
o COMPUTED BY clause
The COMPUTED BY clause has been added to the SQL CREATE TABLE
statement and the SQL ALTER TABLE statement.
o CURRENT_TIMESTAMP user literal
You can use the CURRENT_TIMESTAMP user literal anywhere that
an expression is allowed in SQL to specify the date and time
currently defined in Rdb/VMS.
The following example of an SQL command inserts the date into
the JOB_START field of an employees record:
SQL> INSERT INTO EMPLOYEES(JOB_START ...)
VALUES (CURRENT_TIMESTAMP, ...);
o CREATE VIEW and DECLARE CURSOR
New and Changed Features 1-41
The CREATE VIEW and DECLARE CURSOR statements accept the new
LIMIT TO argument, which limits the number of rows in the
result table.
1-42 New and Changed Features
o DECLARE CURSOR Statement, Extended Dynamic
SQL Version 4.0 documentation includes a new section on the
extended dynamic DECLARE CURSOR statement. In Version 3.1
and earlier documentation, this statement was included in the
description and syntax diagram in the section on DECLARE CURSOR
Statement, Dynamic.
o DECLARE TRANSACTION and SET TRANSACTION
The DECLARE TRANSACTION and SET TRANSACTION statements accept
the new WAIT <interval> clause. The WAIT <interval> clause lets
you set the amount of time a transaction waits for locks to be
released, to help you avoid distributed deadlock.
o Segmented string support
The following SQL statements have new syntax that lets you
manipulate lists, the SQL equivalent of segmented strings:
- DECLARE CURSOR
- Dynamic DECLARE CURSOR
- FETCH
- INSERT
- OPEN
These statements and the Extended Dynamic DECLARE CURSOR state-
ment also have new syntax that lets you distinguish between
read-only cursors, insert-only cursors, and update cursors.
For information about when to use each cursor mode, see the VAX
Rdb/VMS SQL Reference Manual.
The sample program, SQL$RESUMES.SCO, demonstrates the use of
lists. Using SQL$RESUMES, a user can load resumes from a file
into the database, and then later display the resume. You can
find this program in RDM$DEMO.
New and Changed Features 1-43
Additional details about lists and list cursors appears in
Section 1.18.5.
o SELECT (select expression clause)
The SELECT statement accepts the new LIMIT TO argument, which
limits the number of rows in the result table.
o SET DEFAULT CONSTRAINT MODE
The SET DEFAULT CONSTRAINT MODE statement allows you to set
the default for constraint evaluation. After you execute this
statement, any transactions that are started have the initial
constraint evaluation mode you set. Before you issue this
statement, the default mode is set to off.
SET DEFAULT CONSTRAINT [ MODE ] { ON | OFF}
1-44 New and Changed Features
o SHOW CONSTRAINT MODE
This statement displays the default setting for constraint
evaluation. If there is a current transaction, the SHOW
CONSTRAINT statement displays the constraint evaluation mode
for the current transaction.
1.18.3 String Concatenation Operator
The SQL string concatenation operator (|), is an arithmetic oper-
ator that lets you link two value expressions with character data
types. The value expressions must be one of the three character
data types: CHAR, VARCHAR, or LONG VARCHAR.
If the value of either of the concatenated expressions is null,
then the result of the concatenation is also null. Otherwise the
result of the concatenation is the value of the first expression
followed by the value of the second expression. If the resulting
string exceeds 65535 bytes (the maximum string length SQL allows),
SQL signals a truncation error, unless all of the characters to
the right of the 65535th character are spaces. In this case, the
result will be the leftmost 65535 characters.
1.18.4 Substring Manipulation
You can use substrings to manipulate portions of character value
expressions. For example, you can use substrings to select records
in which the value in a column matches a certain number of charac-
ters in the substring. A substring must have the data type CHAR,
VARCHAR, or LONG VARCHAR.
To specify a substring, you must specify the value expression,
and the FROM keyword, followed by the start position of the value
expression. You can optionally add a FOR clause after the FROM
clause to specify the length of the value expression after the
start position.
New and Changed Features 1-45
If you specify a length longer than the string, SQL returns only
valid characters in the string, and terminates the returned sub-
string after the last valid character.
If either operand of the substring is the null value, the result-
ing value is also null.
The following example uses a substring in the WHERE clause of a
SELECT statement. One of the SELECT statement conditions is that
four characters starting at position nine must equal the string
"Math", which is extracted using the substring feature.
SQL> SELECT * FROM DEGREES WHERE SUBSTRING(DEGREE_FIELD
cont> FROM 9 FOR 4) = 'Math' AND YEAR_GIVEN > 1980;
1.18.5 SQL Supports Segmented Strings
The SQL data type LIST of BYTE VARYING, like the RDO data type
SEGMENTED STRING, lets you handle large data objects with a seg-
mented internal structure.
List cursors enable users to scan a very large data structure from
within a language that does not provide support for objects of
such size. Because lists exist as a set of elements within a row,
a cursor must refer to a table cursor because the table cursor
provides the row context.
When you specify a table cursor that provides row context for a
list cursor, you must be sure to specify the column name, as shown
in the following example:
DECLARE ONE INSERT ONLY TABLE CURSOR FOR SELECT EMPLOYEE_ID, RESUME
FROM RESUMES;
DECLARE TWO INSERT ONLY LIST CURSOR FOR SELECT RESUME
WHERE CURRENT OF ONE;
1-46 New and Changed Features
This feature allows dynamic users to get all metadata for all
columns, which contrasts with previous versions of Rdb/VMS when
this was not the case. If you fetch a table cursor that references
a list cursor column name, SQL returns the segmented string ID.
NOTE
The value returned is not guaranteed to be valid across all
releases. Segmented string IDs cannot be used outside of
the scope of the cursor.
You can see the contents of the list column if you open and fetch
the appropriate list cursor after fetching the table cursor. (Be
sure to close the list cursor before you attempt to fetch a new
row from the table cursor.) For more information on this, see
Section 3.2.5.
You must check the indicator from the table cursor fetch to find
out if a list is null. SQLCODE returns end-of-stream on the first
fetch of a null list.
You should be aware of the following features:
o Read-only table cursors are valuable in dynamic and interactive
statements because they do not retrieve database keys.
1.18.6 Computed Columns in Tables
In SQL you can associate a value expression with a column name in
a table definition.
o In the CREATE TABLE statement, SQL now allows a value expres-
sion in a table's column definition (the clause where you spec-
ify either base data type or domain name). Specify each value
expression with the keywords COMPUTED BY.
o In the ALTER TABLE statement, you can specify a value expres-
sion in the add-col-definition clause. However, you cannot
specify a value expression in the alter-col-definition clause.
New and Changed Features 1-47
You can use the COMPUTED BY clause to create a table with one
or more computed columns or to alter a table to add one or more
computed columns.
Examples of computed columns are as follows:
SQL> CREATE TABLE TABLE1 (A INT, B INT, C COMPUTED BY A + B, D);
SQL> CREATE TABLE TABLE2 (A INT, C COMPUTED BY (SELECT MAX (B) FROM
TABLE1));
SQL> ALTER TABLE TABLE1 ADD COLUMN D COMPUTED BY B-A;
You cannot refer to a column before you define it. The following
example is invalid:
SQL> CREATE TABLE TABLE3 (C COMPUTED BY (A+B), A INT, B INT)
1.18.7 SQL Changes Values Used in SQLERRD Array
The SQLERRD[x] field of the SQLCA is a zero-based array of six
integers. The only elements of the array that SQL uses are the
second through sixth elements (SQLERRD[1], SQLERRD[2], SQLERRD[3],
SQLERRD[4], and SQLERRD[5]) in the display from SHOW SQLCA. The
remainder of the elements are provided for compatibility with DB2.
SQL puts a value in the third element (SQLERRD[2]) after success-
ful execution of the following statements:
o INSERT: the number of rows stored by the statement
o UPDATE: the number of rows modified by the statement
o DELETE: the number of rows deleted by the statement
o FETCH: the number of the row on which the cursor is currently
positioned
o OPEN: zero
1-48 New and Changed Features
o SELECT: the number of rows in the result table formed by the
SELECT statement (Note: SQLERRD is not updated for dynamic
SELECT statements.)
SQL puts the following values in the second, fourth, fifth, and
sixth elements successful execution of an OPEN statement that
opens a list cursor:
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 in all list segments
SQL puts no meaningful data in the sixth element of the SQLERRD
array after successful execution of a FETCH statement within a
list cursor. For a FETCH statement within a list cursor, you
must pass an indicator parameter to receive information about
the length or truncation of data in segments.
1.18.8 Module Language Record Support
SQL Version 4.0 allows you to pass records and indicator arrays
to SQL module language procedures and retrieve CDD/Plus record
declarations. This new functionality enables ACMS users to write
task definitions that call SQL module procedures directly and
also provides integration for DECforms applications, which pass
information through record structures.
Module language syntax for record support has the following for-
mat.
New and Changed Features 1-49
MODULE -+-------->--------+-> LANGUAGE language-name -+
+-> module-name --+ |
+------------------------------------------------------+
+-> AUTHORIZATION auth-id --+------------>-----------+-+
++-> declare-statement -++ |
+--------- <-----------+ |
+------------------------------------------------------+
++-> PROCEDURE procedure-name +-> param-decl +-> ; sql-statement ; -+->
| +----+------+--+ |
| +-- , <+ |
+--------------------------------<---------------------------------+
param-decl =
-+-> parameter -+-> data-type ---++--------------->-------------+-+->
| +-> domain-name -++-> BY DESCRIPTOR +----->----++ |
| +-> record-type -+ +-> CHECK -+ |
+-> SQLCA -------------------------------------------------------+
+-> SQLCODE -----------------------------------------------------+
+-+--------------+----> SQLDA -----------------------------------+
+-> parameter -+
--> RECORD -++-> item-name --+-> data-type ----+--++-> END RECORD ->
|| +-> record-type --+ ||
|+-------------+--------+-------------+|
| +-- , <--+ |
| |
+--> FROM path-name -------------------+
| |
+--> INDICATOR ARRAY OF ---+ |
+--------------------------+ |
+> array-length -> exact-numeric-type -+
exact-numeric-type=
-------+--> SMALLINT ---+----+--------+----------------+->
+--> INTEGER ----+ +-> n ---+ |
+--> QUADWORD ---+ |
+--> TINYINT ----+ |
+--> DECIMAL --+-+----------------------------+-+
+--> NUMERIC --+ +-> ( --> n -+--------+-> ) -+
+-> , n -+
1-50 New and Changed Features
A record definition cannot contain an SQLDA or an SQLCODE.
You should have at least as many elements in your indicator array
as in the record definition. If a record reference has an indi-
cator, it must be an indicator array. You can only use indicator
arrays on the right side of the INDICATOR keyword. You cannot
use indicator arrays as a record. You cannot refer to individual
elements within an indicator array. For this reason, you cannot
use indicator arrays in UPDATE statements or in WHERE clauses. An
indicator array cannot be contained within another record.
You can use decimal and numeric fields for indicators. The module
language standard for COBOL does not permit binary data types.
Each element name in a record must be different from any other
element name at the same level in the same record declaration.
The path name represents the location of a record description
within the dictionary. A record description cannot contain repeat-
ing items (OCCURS, arrays). It can contain only valid Rdb/VMS or
SQL data types.
When you refer to an element within a parameter declaration in a
procedure, the reference must be fully qualified. In other words,
it must include the parameter name and all intervening element
names, separated with periods.
When you include a CDD/Plus record that contains character strings
in a C module, the module language assumes that the last char-
acter of the string is for the null character. For example, if
a CDD/Plus character string is 10 characters, you can fit only a
9-character SQL field in it in a C module.
1.18.9 SQL C Precompiler Supports VARCHAR Host Variables
The SQL C precompiler now supports VARCHAR host variables. To
declare a VARCHAR, use the following syntax:
$SQL_VARCHAR(max_length_of_varchar)
New and Changed Features 1-51
For example, the following statement defines a VARCHAR variable
that is a word length followed by 10 bytes of data.
$SQL_VARCHAR(10) x, y, z;
1.18.10 SQL Statements Have Been Updated to Support VAX Data
Distributor V2.2
SQL statements in the VAX Rdb/VMS SQL Reference Manual have been
updated to support VAX Data Distributor V2.2.
1.18.11 Diagnostic Messages for Obsolete Features
When you use obsolete SQL syntax, you receive a diagnostic mes-
sage. Appendix H in the VAX Rdb/VMS SQL Reference Manual lists
the obsolete features and those features that supersede them, and
tells how to suppress the diagnostic messages.
1.18.12 Sample Programs in Precompiled SQL and SQL Module Language
Table 1-1 lists the sample SQL programs, whether they are written
in precompiled SQL or SQL module language, and the host languages
in which they are written.
Table 1-1: Sample Programs in Precompiled SQL and SQL Module
___________Language_______________________________________________
Precompiled SQL
SQL Module
Sample_Program_____Ada__COBOL_C__FORTRANPascalPL/I_Language_______
SQL$ALL_ X X X X X X Ada
DATATYPES
SQL$DIST_TRANS X X COBOL, FORTRAN
1-52 New and Changed Features
Table 1-1 (Cont.): Sample Programs in Precompiled SQL and SQL
___________________Module_Language________________________________
Precompiled SQL
SQL Module
Sample_Program_____Ada__COBOL_C__FORTRANPascalPL/I_Language_______
SQL$DYNAMIC Ada, C, PL/I
SQL$INSERT_ COBOL
DEGREES
SQL$LOAD_ X X X
EMPLOYEES
SQL$LOAD_JOBHIST X X X X X Ada
SQL$LOAD_JOBS X
SQL$LOAD_SALHIST X
SQL$MULTI_STMT_DYN Ada
SQL$REPORT X X X X X Ada
SQL$RESUMES X X
SQL$TERMINATE X X X X X Ada, BASIC,
___________________________________________________Pascal_________
1.19 RDO: New and Changed Features and Statements
See information in Section 1.1 through Section 1.17 for additional
new and changed RDO features.
New and Changed Features 1-53
1.19.1 Support for the Two-Phase Commit Protocol
RDO supports the two-phase commit protocol. See Section 1.1
for more information. See the VAX Rdb/VMS Guide to Distributed
Transactions for more information.
1.19.2 RDO Changes for CDD/Plus Compatibility
The RDO SHOW FIELD and SHOW RELATION statements have been enhanced
to provide full path name displays.
1.19.3 RDO SHOW DATABASE Statement Displays the Node Name for Remote
Databases
The RDO SHOW DATABASE statement displays the node name if the
database is accessed remotely. For example:
RDO> DATABASE FILE 'VAXA"SMITH SECRET"::DISK1:[SMITH.DATABASES]PM'
RDO> SHOW DATABASE RDB$DBHANDLE
Database with db_handle RDB$DBHANDLE (default handle)
File: DISK1:[SMITH.DATABASES]PM.RDB;1
This database is accessed remotely on node VAXA
Default segmented string storage area: RDB$SYSTEM
Number of users: 4
Number of nodes: 16
Buffer Size (blocks/buffer): 6
Number of Buffers: 20
Number of Recovery Buffers: 20
Snapshots are Enabled Immediate
Dictionary Not Required
ACL based protections
RDO> Exit
1-54 New and Changed Features
1.20 RDBPRE: New and Changed Features and Statements
See information in Section 1.1 through Section 1.17 for additional
new and changed RDBPRE features.
1.20.1 Support for the Two-Phase Commit Protocol
RDBPRE supports the two-phase commit protocol. See Section 1.1
for more information. See the VAX Rdb/VMS Guide to Distributed
Transactions for more information.
1.20.2 RDBPRE/MESSAGE_MAP Works for BASIC
The /MESSAGE_MAP qualifier of the RDBPRE preprocessor command
line currently works for BASIC. The /MESSAGE_MAP qualifier is
used to declare variables as global, so that a message compiled in
one module is still recognized in a called procedure in another
module.
See Section 1.1 for more information on compiling RDBPRE applica-
tions for distributed transactions.
1.21 RDML: New and Changed Features and Statements
See information in Section 1.1 through Section 1.17 for additional
new and changed RDML features.
1.21.1 Support for the Two-Phase Commit Protocol
RDML supports the two-phase commit protocol. See Section 1.1 and
the RDML Reference Manual for more information.
New and Changed Features 1-55
1.21.2 Support for Internationalization
RDML supports internationalization in the following areas:
o Digital multinational character set (MCS) characters in
database object names
Database object names that can be referred to from RDML include
context variables, relations, fields, and constraint names.
See the RDML Reference Manual for more information.
o Date and time literals appearing in RDML queries
These date and time literals are converted at compile time
using the VMS V5.0 RTL routine LIB$CONVERT_DATE_STRING.
If the logical name SYS$LANGUAGE is set to the appropriate
language (SPANISH in the following example) and appropriate
LIB$DT_INPUT_FORMAT is defined, then RDML compiles the query.
If the language or input format is set incorrectly, RDML gener-
ates an appropriate date conversion error.
FOR E IN EMPLOYEES
WITH E.BIRTHDAY = '1 abril, 1990'
END_FOR
o Date and time support for headers in RDML programs
If the logical name SYS$LANGUAGE is set to the appropriate
language and the logical name LIB$DT_FORMAT is defined, the
date and time appearing in RDML listing files is formatted
using the formats specified in LIB$DT_FORMAT.
1.22 RMU: New and Changed Features and Statements
Rdb/VMS Management Utility (RMU) commands and qualifiers that are
new for Rdb/VMS V4.0 appear in the following sections. See the VAX
Rdb/VMS RDO and RMU Reference Manual for detailed descriptions of
these commands and qualifiers.
1-56 New and Changed Features
1.22.1 RMU/ALTER Command
The RMU/ALTER command invokes the RdbALTER utility, which allows
you to patch a database or move it from one device to another. The
RdbALTER chapter in the VAX Rdb/VMS RDO and RMU Reference Manual
provides syntax and a description of each RdbALTER command. A
tutorial on using the RdbALTER utility is in the VAX Rdb/VMS Guide
to Database Maintenance and Performance. See Section 3.9.21 of the
Release Notes for a description of additional RMU/ALTER features
that are not documented in V4.0.
1.22.2 RMU/BACKUP Command
The RMU/BACKUP command includes the following new and changed
qualifiers:
o /OWNER=user-id
The /OWNER=user-id qualifier specifies the OWNER of the volume
set (the user that is permitted to restore the database). The
"user-id" is a VMS user id. It has the form "[group_name,user_
name]", "[name]","[n,m]","name", or "%Xhhhhhhhh". The default
value for the OWNER is the user's own "user-id". This qualifier
is incompatible with a disk backup. When used with tapes, the
qualifier applies to all continuation volumes, and to the
initial volume only if /REWIND was specified. (If /REWIND
is not specified, the BACKUP command appends the file to a
previously labeled tape, so the first volume of the file may
have a different protection.)
o /TAPE_EXPIRATION=date-time
The /TAPE_EXPIRATION=date-time qualifier specifies the ex-
piration date of the backup file. The default value for this
qualifier is "NOW". That is, the tape may be overwritten imme-
diately. This is also incompatible with disk backup.
o Semantics for the /INCLUDE and /EXCLUDE qualifiers of the
RMU/BACKUP command have changed
New and Changed Features 1-57
If neither the /INCLUDE and /EXCLUDE qualifiers are speci-
fied in an RMU/BACKUP command, a full and complete backup is
performed.
The /INCLUDE, /EXCLUDE, and /INCLUDE/EXCLUDE qualifiers with no
storage area list specified are all equivalent to specifying
neither qualifier. They include all storage areas in the backup
file and exclude none.
The /INCLUDE=area-list qualifier includes only those storage
areas specified in the list and excludes all other storage
areas from the backup file. This means that the qualifiers
/INCLUDE=area-list and /EXCLUDE are equivalent.
The qualifier /EXCLUDE=area-list excludes only those storage
areas specified in the list and includes all other storage ar-
eas. This means that the qualifiers /INCLUDE and /EXCLUDE=area-
list are equivalent.
The qualifiers /EXCLUDE=area-list and /INCLUDE=area-list,
when used together on the same RMU/BACKUP command line, are
considered an error.
o Changes to the /INCREMENTAL qualifier
The RMU/BACKUP/INCREMENTAL command now allows incremental
backups by area. The /INCREMENTAL=BY_AREA qualifier changes
dates. The RMU/BACKUP/INCREMENTAL command determines the extent
of the backup to be performed. The four possible options are:
- /NOINCREMENTAL (full backup)
If you do not specify any of the possible incremental op-
tions, the default is the /NOINCREMENTAL option. With the
/NOINCREMENTAL option, a full and complete backup of the
database is performed.
- /INCREMENTAL
If you specify the /INCREMENTAL option, an incremental
backup of the storage areas that have changed since the
last full backup of the database is performed.
1-58 New and Changed Features
- /INCREMENTAL=COMPLETE
If you specify the /INCREMENTAL=COMPLETE option, you get an
incremental backup of the storage areas that have changed
since the last full and complete backup of the database was
performed. Selecting the /INCREMENTAL=COMPLETE option is the
same as selecting the /INCREMENTAL option.
- /INCREMENTAL=BY_AREA
The /INCREMENTAL=BY_AREA option determines the time window
in which changes to the database should be included in the
backup.
/INCREMENTAL=COMPLETE means from last full and com-
plete backup. /INCREMENTAL=BY_AREA means from last full
area backup independent of whether it was complete. The
/INCREMENTAL=BY_AREA option backs up those database pages
that have changed in each selected storage area since the
last full backup of the area. The last full backup of the
area is the later of the following:
* The last full and complete backup of the database
* The last full by-area backup of the area
With an incremental by-area backup, each storage area could
have been backed up in a different time window.
Following a full database backup, each subsequent incremental
backup replaces all previous incremental backups.
A backup plus the last incremental backup gives you the current
state of the database. The /FULL qualifier changes the backup
date in the root file affecting all future incremental backups.
The /AREA qualifier changes the date relative to the areas
being backed up. This behavior affects future /INCREMENTAL
backups to those areas.
o /LOCK_TIMEOUT=seconds qualifier of the RMU/BACKUP/ONLINE com-
mand
New and Changed Features 1-59
The /LOCK_TIMEOUT=seconds qualifier determines the maximum
time the backup operation waits for the quiet point lock dur-
ing online backup operations. When you specify the /LOCK_
TIMEOUT=seconds qualifier, you must specify the number of
seconds to wait for the quiet point lock. If the time limit
expires, an error is signaled and the backup operation fails.
When the /LOCK_TIMEOUT=seconds qualifier is not specified, the
backup operation waits indefinitely for the quiet point lock
during an online backup operation.
The /LOCK_TIMEOUT=seconds qualifier is ignored for offline
backup operations.
For more information, see Section 2.5.7.
1.22.3 RMU/CLOSE/PATH Command
The /PATH qualifier has been added to the RMU/CLOSE command.
Use the /PATH qualifier to close a database by specifying the
database's path name.
1.22.4 RMU/CONVERT Command
Rdb/VMS includes a new database conversion utility that converts
V3.0, V3.0A, V3.0B, V3.1, V3.1A, and V3.1B databases to V4.0.
The mode of operation for this utility is entirely different than
conversion operations in previous versions of Rdb/VMS. Unlike the
previous RMU/CONVERT command, there is no RMUCONVERT executable.
The syntax of the new RMU/CONVERT command is:
RMU/CONVERT[/[NO]COMMIT][/[NO]ROLLBACK][/[NO]CONFIRM]/PATH database-list
o /COMMIT
1-60 New and Changed Features
Causes the conversion to be committed. That is, after you
specify the option /COMMIT, the database is at V4.0 and cannot
be returned to the previous version. /NOCOMMIT permits the
database either to be committed to V4.0 or rolled back to the
previous version at a later time. /COMMIT is the default.
New and Changed Features 1-61
o /ROLLBACK
Returns the converted but not yet committed database to the
previous version. This is useful if you want to return to
the previous version for technical or business reasons.
The /NOROLLBACK qualifier inhibits the rollback function.
/NOROLLBACK is the default.
o /CONFIRM
Enables interaction with the user. It causes confirmation to
be sought before the operation begins and if after-image jour-
naling must be disabled. /NOCONFIRM inhibits the confirmation
requests. The default is /CONFIRM if the CONVERT command is
executed interactively, and /NOCONFIRM if the CONVERT command
is executed from a batch job.
o /PATH
Indicates that the database is being specified by the CDD/Plus
path name and not by its file specification. This assumes that
the CDD/Plus dictionary database has already been converted.
o database-list parameter
Specifies a list of databases to be converted. An item of the
list may be either the file specification of a database root
file (wild cards are allowed), or a CDD/Plus path name with a
/PATH qualifier (wild cards not allowed).
In the following example, RMU/CONVERT converts all the databases
in DISK:[ME] and its subdirectories and the SPECIAL_DB identified
by its CDD/Plus path name.
RMU/CONVERT DISK:[ME...]*.RDB,CDD$TOP.ME.SPECIAL_DB/PATH
In addition, note the following changes in the conversion process:
o The RMU/CONVERT command was designed so that if the conversion
is incomplete (for example as a result of a system crash or
1-62 New and Changed Features
Rdb/VMS MONITOR shutdown) it can be reexecuted later. Half-
converted databases that are essentially corrupted are no
longer possible.
o The RMU/CONVERT command operates by creating a converted copy
of the system relations and indexes. This implies that the
RDB$SYSTEM storage area may grow during the conversion, but
it is no longer likely that the system relations will be frag-
mented by the conversion process.
o Because a copy of the system relations is made, the time taken
by the conversion is proportional to the size of the system
relations. Conversion typically requires only a few minutes per
database, but if the database has very large system relations
the conversion can be costly. If the problem is a large number
of versions of some relations, it might be more efficient to
use the EXPORT/IMPORT operation to convert the database.
o After the conversion, both copies of the system relations
are stored in the database. The /COMMIT qualifier selects
the converted copy and deletes the original copy, while the
/ROLLBACK clause selects the original copy and deletes the
converted copy. Either the commit or rollback operations can be
performed at a later time if the /NOCOMMIT clause was selected
when the database was converted.
o While both copies of the system relations exist, the database
is usable under V4.0, but not under the earlier version. DDL
operations to the database are not allowed. This last restric-
tion is required to insure that both copies remain consistent.
After the commit or rollback operation completes, DDL opera-
tions are once again enabled.
o RMU/CONVERT requires that the RMU executable be installed with
SYSPRV privilege or that the user performing the conversion
have SYSPRV enabled.
New and Changed Features 1-63
See the VAX Rdb/VMS Installation Guide and the Before You Install
letter provided with the V4.0 software for more information about
converting your database to this version of Rdb/VMS.
1.22.5 RMU/COPY_DATABASE Command
The RMU/COPY_DATABASE command can be used to create a duplicate
database. Like the RMU/RESTORE command, the RMU/COPY_DATABASE com-
mand allows you to modify certain area parameters when the move
is performed. As with the RMU/BACKUP command, all the files are
processed simultaneously. The RMU/COPY_DATABASE command has per-
formance similar to that of the RMU/BACKUP command and eliminates
the inconvenience of having to use intermediate storage media.
RMU/COPY_DATABASE requires ADMIN or OPER Rdb privilege, and access
to the database files. The latter requires use of default ACLs,
SYSPRV, or installation of the RMU image with SYSPRV.
The syntax for RMU/COPY_DATABASE is:
RMU/COPY_DATABASE
[/[NO]AFTER_JOURNAL [=file-spec]]
[/PAGE_BUFFERS=n]
[/DIRECTORY=directory-spec]
[/OPTION=file-spec]
[/NODES_MAX=n]
[/USERS_MAX=n]
[/[NO]LOG]
[/ROOT=file-spec]
[/[NO]CHECKSUM_VERIFICATION]
[/BLOCKS_PER_PAGE=n]
[/FILE=file-spec]
[/THRESHOLDS=(n,n,n)]
[/SNAPSHOTS=FILE=file-spec]
[/[NO]ONLINE]
root-file-spec
storage-area-list
1-64 New and Changed Features
1.22.6 RMU/DUMP/AFTER_JOURNAL Command
The RMU/DUMP/AFTER_JOURNAL command contains changed output format
for the AIJ file.
1.22.7 RMU/DUMP/AFTER_JOURNAL/STATE=PREPARED
You can use the /STATE=PREPARED qualifier of the RMU/DUMP/AFTER_
JOURNAL command to generate a list of records associated with
unresolved transactions in the AIJ file. Depending upon your
application, you might need to generate the list for more than
one AIJ file.
1.22.8 RMU/DUMP/BACKUP_FILE/LABEL=(label-name-list) Command
The RMU/DUMP/BACKUP_FILE command includes a /LABEL=(label-name-
list) qualifier.
1.22.9 RMU/DUMP/USERS/STATE=BLOCKED Command
You can generate a list of unresolved distributed transactions
using the /USERS/STATE=BLOCKED qualifiers of the RMU/DUMP command.
See the RMU/DUMP command in the VAX Rdb/VMS RDO and RMU Reference
Manual for details.
1.22.10 RMU/MOVE_AREA Command
The RMU/MOVE_AREA command permits you to relocate one or more
areas, and optionally the root file, to different disks. Like
RMU/RESTORE, it permits the modification of certain area parame-
ters when the move is performed. As with the RMU/BACKUP command,
all the files are processed simultaneously. The performance of
the RMU/MOVE_AREA command is similar to that of RMU/BACKUP and
eliminates the inconvenience of having to use intermediate storage
media.
New and Changed Features 1-65
RMU/MOVE_AREA requires ADMIN or OPER Rdb/VMS privilege and access
to the database files. The latter requires use of default ACLs,
SYSPRV, or installation of the RMU image with SYSPRV.
The syntax for RMU/MOVE_AREA is:
RMU/MOVE_AREA
[/[NO]AFTER_JOURNAL[=file-spec]]
[/PAGE_BUFFERS=n]
[/[NO]AREA]
[/DIRECTORY=directory-spec]
[/OPTION=file-spec]
[/NODES_MAX=n]
[/USERS_MAX=n]
[/[NO]LOG]
[/ROOT=file-spec]
[/[NO]CHECKSUM_VERIFICATION]
[/BLOCKS_PER_PAGE=n]
[/FILE=file-spec]
[/THRESHOLDS=(n,n,n)]
[/SNAPSHOTS=FILE=file-spec]
root-file-spec
storage-area-list
1.22.11 RMU/OPEN/PATH Command
The /PATH qualifier has been added to the RMU/OPEN command.
Use the /PATH qualifier to open a database by specifying the
database's path name. See the RMU/OPEN command in the VAX Rdb/VMS
RDO and RMU Reference Manual for details.
1-66 New and Changed Features
1.22.12 RMU/RECOVER/RESOLVE Command
In the after-image journal file, you can modify the state of
records that are associated with blocked distributed transactions.
The RMU/RECOVER/RESOLVE command allows you to either commit or
abort blocked transactions in the after-image journal file. See
the RMU/RECOVER/RESOLVE command in the VAX Rdb/VMS RDO and RMU
Reference Manual for details.
1.22.13 RMU/REPAIR Command
The RMU/REPAIR command allows you to repair several types of SPAM
page corruption and ABM page errors. It also repairs page tail
errors to the satisfaction of RMU/VERIFY and corrects performance
problems that might otherwise have to be corrected by exporting
and importing the database.
1.22.14 RMU/RESOLVE Command
You can modify the state of unresolved distributed transactions
in the database. The RMU/RESOLVE command allows you to either
commit or abort unresolved transactions in the database. See
the RMU/RESOLVE command in the VAX Rdb/VMS RDO and RMU Reference
Manual for details.
1.22.15 RMU/RESTORE/LABEL=(label-name-list) Command
The RMU/RESTORE command now includes a /LABEL=(label-name-list)
qualifier. This is analogous to the /LABEL qualifier on the BACKUP
command. It specifies the order in which the tapes were written.
Normally, the /LABEL qualifier on the RESTORE command will be a
duplicate of the qualifier used on the BACKUP command.
New and Changed Features 1-67
1.22.16 Security Auditing
Rdb/VMS now gives you the ability to enable security auditing for
a database, to display the security auditing that is enabled for
the database, and to load records from an audit journal into an
Rdb/VMS relation, using the following commands:
o RMU/SET AUDIT
The RMU/SET AUDIT command enables Rdb/VMS security auditing
to send security alarm messages and to make entries in the
database security audit journal whenever specified audit events
are detected by Rdb/VMS.
o RMU/SHOW AUDIT
The RMU/SHOW AUDIT command displays the set of security au-
diting characteristics that have been established with the
RMU/SET AUDIT command.
o RMU/LOAD/AUDIT
The RMU/LOAD/AUDIT command allows you to load records from an
Rdb/VMS audit journal into an Rdb/VMS relation.
See Section 1.2 for more information on security auditing. See the
information for the RMU/SET AUDIT, RMU/SHOW AUDIT, and RMU/LOAD
/AUDIT commands for more information on the new auditing features
that can be enabled for your Rdb/VMS database.
1.22.17 RMU/SHOW STATISTICS Command
A change has been made in Rdb/VMS V4.0 so that now only processes
on the node on which the RMU/SHOW STATISTICS command is being run
can take up a line on the stall messages display. In Rdb/VMS V3.1
and lower, database users on another node in a VAXcluster take up
blank lines in the RMU/SHOW STATISTICS stall display. Wasted space
on the stall display minimized the number of processes that could
be observed.
1-68 New and Changed Features
For Rdb/VMS V4.0, an additional change has been made so that the
stall screen displays only processes that are actively stalling.
Once a process finishes stalling, it disappears from the screen.
Processes that are still stalling, appear nearer to the top of
the display, so that the longest stalling processes appear at
the top of the display. Newer stalling processes are added to the
end of the display. Thus, all users on this node share the same
stall display lines; only the actively stalling processes appear.
This allows you to monitor many more stalling processes than
before. Now, the only constraint to the number of concurrently
stalling processes you can observe is the number of lines in your
RMU/SHOW STATISTICS display. A database with no stalling processes
occurring will show a blank stall messages display.
In Rdb/VMS V3.1 and lower, once a process attaches to the
database, it holds a particular line on the stall statistics
display regardless of whether it is stalling or not. The first
column ("Process . . . ") contains the process ID (PID) and stream
ID (STID) to identify that user. If that process stalls, the stall
message appears on the line along with the time when the stall
began. Once the stall completes, only the "since . . . " column is
deleted, leaving the old stall message on the screen, even though
the stall is over. This method limits the number of processes that
you can monitor to the number of lines on the display screen. For
databases that have hundreds of users, this method does not allow
you to observe all the desired information.
1.23 SQL/Services: New and Changed Features
The new features and technical changes in SQL/Services for VAX
Rdb/VMS Version 4.0 including process pooling, API support, API
routines, server access, list cursors, installation questions, and
Help, are discussed in the following sections.
New and Changed Features 1-69
1.23.1 Process Pooling
In previous versions of SQL/Services, the server on a VAX com-
puter 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 increas-
ing request throughput) and reduces the load on server system
resources.
1.23.2 API Support
SQL/Services has developed two new Application Programming
Interfaces (APIs), one for computers running the Macintosh op-
erating 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.
1.23.3 API Routines
A new set of portable API routines provides a functional interface
to information previously accessed only by direct program refer-
ence 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 developing applications
with any of the supported APIs. There are two primary reasons for
this:
o To create fully portable applications for all API environments
1-70 New and Changed Features
o 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.
1.23.4 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 ex-
plicit access method. The two additional access routes permit
programmers (and nontechnical end users) more convenient entry to
SQL/Services. Your system management team can enable or disable
either or both access avenues at any time.
1.23.5 List Cursors
SQL/Services now supports SQL list cursors (segmented strings), an
extension to SQL for Rdb/VMS segmented strings. Enhancements to
the SQL/Services API for list cursors include:
o An explicit sqlsrv_declare_cursor routine
o Two new data types:
- SQLSRV_LIST_VARBYTE
- SQLSRV_VARBYTE
o Information in the SQLDA.SQLIND column and the SQLCA structure
New and Changed Features 1-71
The new sqlsrv_declare_cursor routine lets API programmers ex-
plicitly 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.
1.23.6 SQL/Services VMS API Linkable Libraries
For Rdb/VMS Version 4.0, SQL/Services provides VMS API libraries
(.OLBS) with the Rdb/VMS development kit in addition to share-
able libraries shipped since the Rdb/VMS Version 3.1 release.
Programmers now have the option of linking the VMS API libraries
directly into their executable images. This allows the image to
run on Rdb/VMS run-time and interactive systems, for which the
SQL/Services shareable images are not provided.
1.23.7 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.
1.23.8 SQL/Services Help Available from DCL HELP Facility
The DCL HELP facility now includes SQL/Services help information.
Type HELP SQL_SERVICES at the DCL command level prompt for a
brief introduction to SQL/Services and pointers to additional
information.
1-72 New and Changed Features
1.24 Changes Related to the Sample Personnel Database
The following changes have been made to the sample SQL PERSONNEL
database:
o Single-file database:
- Creates a new RESUMES domain (RESUME_DOM) using LIST of BYTE
VARYING (VARBYTE) data type
- Adds a new RESUMES table
The RESUMES table contains the EMPLOYEE_ID and RESUME
columns.
- Loads three rows of the RESUMES table
o Multifile database:
- Creates a new RESUMES domain (RESUME_DOM) using LIST of BYTE
VARYING (VARBYTE) data type
- Adds a new RESUMES table
The RESUMES table contains the EMPLOYEE_ID and RESUME
columns.
- PERSONNEL.COM loads three rows of the RESUMES table.
- Adds two new storage areas, RESUME_LISTS and RESUMES
The RESUME_LISTS storage area contains the RESUME column of
the RESUMES table.
The RESUMES storage area contains the EMPLOYEE_ID column
of the RESUMES table. The EMPLOYEE_ID column has a UNIQUE
constraint defined for it.
New and Changed Features 1-73
1.25 New and Changed Rdb/VMS Logical Names
This section describes new Rdb/VMS logical names and changes to
other Rdb/VMS logical names.
1.25.1 Disabling the Two-Phase Commit Protocol with the New
SQL$DISABLE_CONTEXT Logical Name
You can disable the two-phase commit protocol by defining the
logical name SQL$DISABLE_CONTEXT to be "TRUE", as shown in the
following example:
$ DEFINE SQL$DISABLE_CONTEXT TRUE
This logical name is useful for turning off distributed trans-
actions when you want to run batch-update transactions. Because
batch-update transactions do not write to recovery-unit journal
(RUJ) files, batch-update transactions cannot be rolled back and
therefore cannot be used in a distributed transaction. For more
information on using this logical name, see Section 4.1.1 in the
VAX Rdb/VMS Guide to Distributed Transactions.
1.25.2 Lock Timeout Mechanism Using a New
RDM$BIND_LOCK_TIMEOUT_INTERVAL Logical Name
A new logical name, RDM$BIND_LOCK_TIMEOUT_INTERVAL, can be used
to set the amount of time a transaction waits for locks to be re-
leased. Using this logical name helps avoid distributed deadlock.
NOTE
Another method that Rdb/VMS provides to set the amount of
time a transaction waits for locks to be released is the
WAIT <interval> clause of the SET TRANSACTION or DECLARE
TRANSACTION statement.
See the VAX Rdb/VMS Guide to Distributed Transactions for more
information.
1-74 New and Changed Features
1.25.3 Restricting the Creation of Databases Using the New
RDBVMS$CREATE_DB Logical Name
You can restrict the creation of databases by users by defining
the RDBVMS$CREATE_DB logical name, and a rights identifier of the
same name.
WARNING
When you define this logical name, other installed Digital
and third-party products will not be able to use Rdb/VMS to
create Rdb/VMS databases. Therefore you must deassign this
logical name whenever users of such products need to create
an Rdb/VMS database.
To restrict the creation of Rdb/VMS databases, you must first
define the SYSTEM/EXECUTIVE logical name RDBVMS$CREATE_DB by
entering the following command:
$ DEFINE/SYSTEM/EXECUTIVE RDBVMS$CREATE_DB
Use the rights identifier, RDBVMS$CREATE_DB, to control which
users will be able to create databases using the SQL CREATE SCHEMA
or RDO DEFINE DATABASE statements. For more information on using
this logical name, adding the RDBVMS$CREATE_DB rights identifier,
and restrictions on its use, see Section 6.10 of the VAX Rdb/VMS
Guide to Database Design and Definition.
1.25.4 Remote Access to Rdb/VMS Using a New Logical Name
RDB$REMOTE_BUFFER_SIZE
Prior to V4.0 of Rdb/VMS, the buffer size of network transfers was
limited to 1024 bytes. With V4.0, the buffer size is increased to
a default setting of 2048 bytes.
Also, by setting the logical name RDB$REMOTE_BUFFER_SIZE before
running an application you can increase the buffer size to your
system quota limits. For example, to increase the buffer size to
10,000 bytes, enter:
New and Changed Features 1-75
$ DEFINE RDB$REMOTE_BUFFER_SIZE 10000
You cannot set the buffer size to less than 2048 bytes. Accessing
a database with an earlier version than V4.0 reduces the buffer
size to 1024 bytes. Accessing a V4.0 database from a V3.n version
of Rdb/VMS also sets the buffer size to 1024 bytes.
It may be desirable to increase the buffer size if you transfer
large data blocks in or out of the database. Increasing the buffer
size reduces the number of network I/O operations used when large
data transfers are made.
1.25.5 Changes to the RDM$BIND_BUFFERS Logical Name
For the RDM$BIND_BUFFERS logical name, you can specify a value
between 2 and 32,768. In V3.1, the upper limit was 1024.
1.25.6 Changes to the RDMS$BIND_SEGMENTED_STRING_BUFFER Logical Name
When using the RDML and RDBPRE precompilers, be sure to define a
sufficiently large value for the RDMS$BIND_SEGMENTED_STRING_BUFFER
logical name. An adequate buffer size is needed to store large
segmented strings (using segmented string storage maps) in storage
areas other than the default RDB$SYSTEM storage area. The minimum
acceptable value for the RDMS$BIND_SEGMENTED_STRING_BUFFER logical
name must be equal to the sum of the length of the segments of
the segmented string. For example, if you know that the sum of the
length of the segments is one megabyte, then 1,048,576 bytes is an
acceptable value for this logical name.
You must specify the logical name value because when RDML and
RDBPRE precompilers store segmented strings, Rdb/VMS does not know
which table contains the string until after the entire string is
stored. Rdb/VMS buffers the entire segmented string, if possible,
and does not store it until the STORE statement executes.
1-76 New and Changed Features
If the segmented string remains buffered, it is stored in the
appropriate storage area. If the string is not buffered (because
it is larger than the defined value for the logical name or the
default value of 10,000 bytes), it is not stored in the default
storage area and the following exception message is displayed:
%RDB-F-IMP_EXC, facility-specific limit exceeded
-RDMS-E-SEGSTR_AREA_INC, segmented string was stored incorrectly
To avoid this error, set the value of the RDMS$BIND_SEGMENTED_
STRING_BUFFER logical name to a sufficiently large value. Note
that a value of up to 500 MB can be specified for this logical
name. See the VAX Rdb/VMS RDO and RMU Reference Manual for more
information on defining storage areas.
NOTE
The SQL interface for lists (segmented strings) does not
require you to define the value for this logical name.
Before the list is brought into the buffer, SQL knows the
column that the list is associated with and the table it is
stored in. However, for large lists, defining this logical
name with a value large enough to hold the entire list may
improve the handling performance of storing the list.
1.25.7 RDMS$AUTO_READY Logical Name Is No Longer Used
The logical name RDMS$AUTO_READY is now obsolete and therefore is
not available for V4.0. Its use was previously recommended under
only very limited circumstances to reduce the overhead of lock
management in situations where no reserving clause was specified
and a two-tiered structure of locking was in effect in which an
area is accessed for concurrent read and then upgraded to concur-
rent update. The use of the RDMS$AUTO_READY logical name defined
as "U" (Update) in this situation automatically converted all ini-
tial read requests to update requests, and thereby avoided this
two-tiered locking structure. This was recommended so that the
reserving clause would not go through and lock all the partitions
of the relations, but would auto ready them as required. Because
New and Changed Features 1-77
users accessing a relation would "ready" (lock) the individual
relation partitions only when they were accessed and in the order
in which they were accessed, a disadvantage of using this logical
name was that deadlocking potential was increased.
However, beginning with V3.1, locks are cached so that there
is no longer any benefit to using the RDMS$AUTO_READY logical
name defined as "U" (Update) in read/write transactions that do
not specify a reserving clause. Starting in V3.1 Rdb/VMS uses
an internal lock cache scheme with relation partitions; this
change provides the benefits of the RDMS$AUTO_READY logical while
minimizing the potential for deadlock.
1.26 Obsolete Statements and Features
Obsolete statements and features are items that Rdb/VMS is phas-
ing out. Over the last few releases Digital has begun moving the
database administrator commands out of RDO and into the RMU util-
ity to make these functions independent of the language being used
(RDO or SQL). This trend will continue.
Many statements were declared as obsolete but were still supported
for a period of time to give users time to change the applications
that used these statements. Those obsolete statements and features
will not be supported in the release following V4.0.
1.26.1 SQL Obsolete Features
This section describes SQL statements that were allowed in earlier
versions of SQL, but will be flagged with diagnostic messages
in SQL V4.0 when you use them in programs. SQL refers to such
statements as obsolete features, and may not support them in
future versions.
1-78 New and Changed Features
If you use the obsolete keywords, you receive a diagnostic mes-
sage.
SQL> SET TRANSACTION READ_ONLY;
1
%SQL-I-DEP_FEATURE, (1) Deprecated Feature
The following features are deprecated for V4.0:
o UNIQUE predicate
o Use of double quotation marks for string literals
Use single (') instead of double (") quotation marks to de-
limit a string.
o Not using colons before host variables in embedded SQL
In SQL statements embedded in programs to be processed by the
SQL precompiler, you must precede parameters with a colon (:)
to distinguish them from a column or table name.
In the following cases, earlier versions of SQL did not require
that a host variable be preceded by a colon:
- The INTO clause of a FETCH or singleton SELECT statement
- The VALUES clause of an INSERT statement
- The LIKE clause of a predicate
- The IN value-list clause of a predicate
- A PREPARE or EXECUTE statement
The optional colon preceding the host variable does not work
when:
- The host variable reference has more than two levels of
qualification (for example: a.b.c.d.).
New and Changed Features 1-79
- The host variable is not a standard SQL token (for example:
a lower or mixed case C variable or a COBOL variable that
contains hyphens).
For this reason, Digital recommends that you always precede pa-
rameter names with a colon. Future versions of SQL may require
that you use a colon before all host variables.
o DATABASE keyword
For V4.0 the SCHEMA keyword replaces the DATABASE keyword.
Use DECLARE SCHEMA, CREATE SCHEMA, and DROP SCHEMA statements
instead of DECLARE DATABASE, CREATE DATABASE, and DROP DATABASE
statements.
o Underscores in DECLARE TRANSACTION and SET TRANSACTION keywords
Table 1-2 lists obsolete keywords and preferred substitutes for
V4.0 SQL DECLARE and SET TRANSACTION statements.
Table_1-2:_Obsolete_Keywords_for_DECLARE_and_SET_TRANSACTION______
Obsolete
Keyword__________V4.0_Preferred_Keyword___________________________
VERB_TIME VERB TIME
COMMIT_TIME COMMIT TIME
READ_ONLY READ ONLY
READ_WRITE_______READ_WRITE_______________________________________
o Not using the CASCADE keyword
For V4.0, the CASCADE keyword is added to the DROP statement.
The default behavior for the SQL DROP TABLE and DROP VIEW
statements is to drop all items that refer to the table or
view, then to drop the table or view itself. A new keyword,
CASCADE, has been added to specifically request this behavior.
1-80 New and Changed Features
For example, if you specify DROP TABLE NO CASCADE, only the
table will be dropped. If other items (views, constraints,
indexes, etc.) refer to the specified table, the drop will
fail.
You will get an informational message in interactive SQL,
precompiled SQL, and SQL module language if you do not specify
either CASCADE or NO CASCADE.
1.26.2 RDO Obsolete Statements and Features
Table 1-3 summarizes the list of obsolete statements, the ones
that replace them, and the version in which the transition is
effective. See the VAX Rdb/VMS RDO and RMU Reference Manual for
more information.
New and Changed Features 1-81
Table_1-3:_Obsolete_Statements____________________________________
Statement_or_Feature__Replaced_by___________Effective_____________
RDO RECOVER RMU/RECOVER V3.1
RDO OPEN RMU/OPEN V3.1
RDO CLOSE RMU/CLOSE V3.1
RDO STOP MONITOR LOG RMU/MONITOR STOP V3.0
RDO REFRESH MONITOR RMU/MONITOR REOPEN V3.0
RDO SHOW MONITOR RMU/SHOW SYSTEM V3.0
RDO SHOW USERS RMU/SHOW USER V3.0
RDO BACKUP EXPORT V3.0
RDO RESTORE IMPORT V3.0
RDO SPOOL RMU/BACKUP/AFTER_ V3.0
JOURNAL
RDO_CONVERT___________RMU/CONVERT___________V3.0__________________
The VAX Rdb/VMS RDO and RMU Reference Manual includes an appendix
that shows the syntax of RDO statements no longer supported in
Rdb/VMS Version 3.1 and Rdb/VMS Version 4.0.
1.26.3 SQL/Services Obsolete Features
The following features are no longer supported in SQL/Services:
o Proxy access to SQL/Services server
1-82 New and Changed Features
For security reasons, client API applications can no longer use
proxy accounts to access the SQL/Services server system. In its
place, SQL/Services 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 (but more secure) entry to SQL/Services. Your
system management team can enable and disable either or both
access avenues at any time.
New and Changed Features 1-83
o SERVER_LOG parameter
The SQL/Services SERVER_LOG parameter in the ASSOCIATE_STR
structure is no longer supported. You can, however, still
enable and disable logging on the client system using the
CLIENT_LOG parameter of the ASSOCIATE_STR structure.
Refer to the VAX Rdb/VMS Guide to Using SQL/Services for fur-
ther information about the logging provided by SQL/Services.
1.27 Summary of Documentation Additions and Changes
This section describes the highlights of changes to the Rdb/VMS
V4.0 documentation. The reference manuals and the guides each con-
tain a technical changes and new features section in the preface
that describes specific changes in each book. You should refer to
a specific book for more specific information on changes and new
features for that book.
The following books are new to the Rdb/VMS documentation set for
V4.0:
o VAX Rdb/VMS Guide to Distributed Transactions
This new book describes the two-phase commit protocol and
distributed transactions, explains how to start and complete
distributed transactions using SQL, RDBPRE, and RDML, and how
to recover from unresolved transactions using RMU commands.
o VAX Rdb/VMS Guide to Database Tuning
This new book introduces the concept of tuning, and explores
how tuning the system, the database, and the application af-
fects database performance. It identifies a series of steps to
follow to identify, analyze, isolate, and solve a performance
problem, and to monitor the resulting solution. It includes
a set of decision trees that provide an organized approach to
solving some common database tuning problems.
1-84 New and Changed Features
Chapter 2
Software Errors Fixed
The following sections describe problems with previous versions of
the Rdb/VMS software that are fixed in Version 4.0.
The notes in this chapter may use different database terms to mean
the same thing. For example, some terms used by SQL differ from
terms used by other interfaces, such as RDO or RDML. Table 1 in
the Preface shows some of the different terms used.
2.1 Software Errors Fixed That Apply to All Interfaces
Section 2.1.1 through Section 2.1.39 describe problems fixed in
all interfaces.
2.1.1 EXPORT Statement Did Not Save the Maximum Storage Area
Allocation
In previous versions of Rdb/VMS, the storage area allocation used
by the IMPORT statement was the initial area allocation and not
the maximum allocation from the source database. If the storage
area grew during the life of the database, then using this initial
allocation caused the area to be extended and hash buckets to
overflow during the IMPORT operation.
Software Errors Fixed 2-1
The workaround was to specify new storage area allocations on the
IMPORT statement.
This problem is fixed in V4.0. The EXPORT statement now saves the
maximum storage area size so that a subsequent IMPORT operation
will allocate sufficient space for the storage area and avoid
storage area extensions, and HASHED indexes will be defined for
the larger allocation so data is redistributed more efficiently.
NOTE
EXPORT still saves the initial allocation size of the snap-
shot files (SNP), as the size is not dependent on stored
data, but rather on database activity.
2.1.2 During IMPORT, Storage Areas Were Always Created Using the
Default Page Size of 2 Blocks
RDO (and SQL) IMPORT incorrectly ignored the storage area page
size in the interchange (RBR) file.
This problem is fixed in V4.0. IMPORT now uses the saved page size
in the interchange file for each storage area.
2.1.3 IMPORT Did Not Restore the RDB$SYSTEM Storage Area Correctly
If you defined a database and explicitly created a storage area
named RDB$SYSTEM, exported the database and then imported it, the
IMPORT statement did not correctly restore that storage area using
the correct file names. The file names saved in the interchange
file (RBR) for the SNP and RDA files were not used; instead,
default file names were derived from the root file name. This
sometimes resulted in the storage area being located on another
disk and directory than was defined in the original database.
2-2 Software Errors Fixed
!
! Multi-file with explicit RDB$SYSTEM
!
DEFINE DATABASE 'DISK1:[DIR1]C0'
DICTIONARY IS NOT USED
DEFINE STORAGE AREA RDB$SYSTEM
FILENAME 'DISK2:[DIR2]C1'
END.
In the example shown here the original database contained three
files:
- DISK1:[DIR1]C0.RDB
- DISK2:[DIR2]C1.RDA
- DISK2:[DIR2]C1.SNP
After an IMPORT operation, the three files were still there but
the file names were different:
- DISK1:[DIR1]C0.RDB
- DISK1:[DIR1]C0.RDA
- DISK1:[DIR1]C0.SNP
In addition, specific storage area attributes defined for the
RDB$SYSTEM storage area became the database-wide default storage
area attributes.
This was not always a problem if the storage area only contained
metadata; however, if it also contained data, then its placement
in the same directory as the root file could be undesirable.
To avoid this problem users were advised to include an explicit
definition of the storage area RDB$SYSTEM on the IMPORT statement,
and include all the storage area attributes such as filename, page
size, allocation, and so forth.
Software Errors Fixed 2-3
This problem is fixed in V4.0.
2.1.4 Rdb/VMS V4.0 Requires That Certain Constraints Be Redefined
Certain constraints should be redefined in V4.0:
1. Constraints referencing a table twice may evaluate incorrectly.
Definitions for constraints having the following forms were
marked with improper evaluation indicators (from Rdb/VMS V2.1
and higher), allowing the constraint to be evaluated by a fetch
for the row updated, which was incorrect.
Table1 WITH (or WHERE) expression involving Table1
REQUIRE Sub-query expression involving Table1.
The WITH Boolean expression could cause the row to be excluded
from constraint evaluation. This situation occurs naturally in
the definition of a FOREIGN KEY constraint where the referenced
PRIMARY KEY is in the same table.
Or in a constraint of the form
Table1 REQUIRE Sub-query expression involving Table1.
where the sub-query expression has a non-equijoin (other than
=) predicate referencing Table1, both as main context and as
sub-query context. The following is an example constraint of
this form:
FOR T1 IN TABLE
REQUIRE NOT ANY T2 IN TABLE WITH
T1.KEY1 = T2.KEY1 AND
T1.KEY2 <> T2.KEY2 AND
T1.START_DATE >= T2.START_DATE AND
T1.START_DATE <= T2.END_DATE
For such a constraint, each time a row is modified or inserted,
it may require re-evaluation of the constraint for other rows
in the table, not just for the row being updated.
2-4 Software Errors Fixed
The net effect is that databases using this specific type of
constraint might contain data that does not meet the constraint
criteria. This problem is fixed in V4.0.
Digital strongly recommends examining the constraints defined
prior to V4.0 to determine if you are affected by this problem.
The only recommended action is to delete the constraint and
redefine it, which will cause the constraint criteria to be
applied to all relevant data, and will properly detect any
previously missed constraint violations.
2. PRIMARY KEY constraints defined using RDO were non-optimal.
PRIMARY KEY definitions declared using RDO prior to V4.0 in-
cluded an unnecessary NOT MISSING Boolean such that any PRIMARY
KEY constraint defined using V4.0 as corrected in item (1)
would not be marked for optimal selection and evaluation.
PRIMARY KEYs defined by SQL do not exhibit this problem.
The optimal definition can be obtained only by deleting the
constraint.
3. PRIMARY/UNIQUE KEY constraints with compound keys were non-
optimal.
Definitions for PRIMARY KEY and UNIQUE KEY constraints on com-
pound (multicolumn) keys were not marked for optimal selection
and evaluation.
Optimal evaluation can be obtained using the released V4.0 by
either deleting the constraint and redefining it, or importing
the database.
4. CHECK constraints using ANY (SOME), ALL, or IN may be non-
optimal.
For Rdb/VMS V3.1, a correction was made to the SQL quantified
predicates ANY (SOME), ALL, (or the IN predicate when a query
expression is used) such that the resultant queries returned
values that conform to the ANSI SQL standard. These changes
produce a functionally different query (previously a form of
the EXISTS predicate) than what was produced prior to V3.1,
Software Errors Fixed 2-5
such that the standard conforming query can no longer be selec-
tively evaluated when used in a constraint. This can produce
noticeable performance degradations.
If the semantics of the quantified predicates are not needed
for the constraint, the performance problems can be eliminated
by redefining the affected constraint with an EXISTS predicate
(or equivalent COUNT function) as shown here:
! Change this:
CHECK (T1.F1 IN (SELECT T2.F1 FROM T2))
! To this:
CHECK (EXISTS (SELECT * FROM T2 WHERE T2.F1 = T1.F1))
2.1.5 Constraints Were Not Always Executed As Required
If an update request was compiled in a transaction for which
there were deferred constraints and if that newly compiled request
was never executed, or was executed in a different transaction,
constraints requiring execution might not get executed, or might
get executed in the wrong transaction.
If a constraint violation, trigger error, or any other kind of
query error occurred in an SQL statement while SET ALL CONSTRAINTS
ON was in effect, constraints deferred for COMMIT time might be
"forgotten," or replaced with constraints that were to be executed
at verb time (CHECK ON UPDATE), or ACCVIOs could occur.
These problems are fixed in V4.0.
2.1.6 Too Many Constraints Could Be Selected or Executed
When a single update request contained multiple update verbs
(ERASE, MODIFY, or STORE for RDO; or DELETE, UPDATE, or INSERT
for SQL), it was possible that the constraints executed at each
subsequent verb would be the sum total of the constraints selected
for each verb thus far in the request.
2-6 Software Errors Fixed
Constraints optimized to fetch the updated row by dbkey and de-
ferred for COMMIT time execution could appear on the deferred list
once for every separate verb that updated a particular table.
These problems are fixed in V4.0.
2.1.7 Constraints Could Be Executed Too Many Times
If a constraint violation error occurred when deferred constraints
were executed at COMMIT time, all deferred constraints would
be reset such that they would all be executed again at the next
COMMIT.
Deferred constraints executed at the SQL end of statement due to
SET ALL CONSTRAINTS ON being in effect would be reset such that
they would be executed at every subsequent SQL end of statement
(while SET ALL CONSTRAINTS ON was in effect) until the transac-
tion was terminated by a COMMIT (all would be executed again) or
ROLLBACK statement.
These problems are fixed in V4.0.
2.1.8 Indexes or Constraints Could Be Ignored by Trigger Actions
Within a transaction, when indexes or constraints were defined af-
ter the first usage of a trigger that updated a relation mentioned
in the trigger or constraint definition, the index or constraint
was effectively ignored by the trigger action statements.
This problem is fixed in V4.0.
2.1.9 Indexes or Constraints Could Be Defined When Illegal Due to
Active Queries
Indexes or constraints could be defined, constraints could be
deleted, and transfers could be defined or deleted when there were
active compiled queries referencing the table or tables specified
in the metadata definitions.
Software Errors Fixed 2-7
This problem is fixed in V4.0.
2.1.10 The Combination of Using a Trigger and Disabling Compression
Did Not Update the Index
There was a problem in V3.1, V3.1A, and V3.1B where the combina-
tion of disabling compression on a table with a trigger caused an
index defined for that table not to get properly updated.
If you remove the disable compression or the trigger, the problem
goes away.
This problem is fixed in V4.0.
2.1.11 Triggers Can No Longer Delete Subject Table Rows
It was possible for a trigger to delete a row from the trigger
subject table causing numerous problems, the most noticeable of
which was the failure of optimized verb or commit time constraints
due to the inability to retrieve the deleted row.
This problem is fixed in V4.0. This situation is now detected and
generates the following exception:
TRIG_REQ_ERROR, error encountered by a request using triggers
TRIGNODEL, trigger 'trigger-name' cannot delete record being modified
or stored
2.1.12 VAX Data Distributor Replications and Triggered Actions Were
Not Performing at the Right Time
Triggered actions were incorrectly executing in the context of
enabled distributed database replications. This caused triggered
action replication transfers to occur before the triggering update
replication transfers, producing a "data" corrupted replication
database.
This problem is fixed in V4.0.
2-8 Software Errors Fixed
2.1.13 DBADM (ADMINISTRATOR) Privilege Was Granted by Rdb/VMS
Default Protection
When creating a brand new database, the default Rdb/VMS protection
applied is for the owner to have all privileges and for the UIC
[*,*] to have all privileges including SQL OPERATOR, DBADM (RDO
OPERATOR+ADMINISTRATOR).
This problem is fixed in V4.0. In V4.0, the default protection for
newly created databases, relations, and views is ALL access for
the creator, and NO access for [*,*]. The creator of the object is
responsible for explicitly setting the [*,*] access privileges.
For versions prior to V4.0, the suggested workaround is to issue
an SQL REVOKE statement or an RDO CHANGE PROTECTION statement
immediately after creation of these objects to remove undesirable
[*,*] access privileges given by default.
2.1.14 CHANGE FIELD (RDO) or ALTER DOMAIN (SQL) Could Cause Query
ACCVIOs
Changing or deleting a MISSING VALUE, DEFAULT VALUE (SQL only),
or VALID IF (RDO only) clause with a CHANGE FIELD (RDO) or ALTER
DOMAIN (SQL) statement could cause ACCVIOs for later executions
of previously compiled queries (generally constraints queued for
deferred evaluation), even though the change or delete operation
failed due to the existence of those queries.
This problem is fixed in V4.0.
2.1.15 A Problem Existed with Disabled Compression and the Store
Clause of the SQL ALTER and RDO CHANGE STORAGE MAP Statements
If you had compression disabled on a storage map, and used the
SQL STORE IN clause of the ALTER STORAGE MAP statement or the RDO
STORE WITHIN clause of the CHANGE STORAGE MAP statement, the data
in the table or relation could be unusable. If you tried to access
your data in RDO, for example, with the following statement, you
received this exception:
Software Errors Fixed 2-9
RDO> FOR J IN JOBS PRINT J.* END_FOR
***** Exception at 001B08A2 : RDMS$$EXE_NEXT + 000003C6
A workaround is to enable compression on the storage map, make
your desired changes using the SQL STORE IN clause of the ALTER
STORAGE MAP statement or the RDO STORE WITHIN clause of the CHANGE
STORAGE MAP statement, and then disable compression on the storage
map. Another workaround is to not disable compression.
This problem is fixed in V4.0.
2.1.16 Defining a Database with a Buffer Size of 1 Caused a Bugcheck
When a database was defined with a buffer size of 1, a bugcheck
resulted and the user process was terminated as follows:
RDO> DEFINE DATABASE TEST1 PAGE SIZE IS 1 BUFFER SIZE IS 1.
Two exceptions occurred in the RDSBUGCHK.DMP file:
***** Exception at 003458C9 : PIOFETCH$WITHIN_DB + 00000144
%RDMS-F-BUGCHECK, fatal, unexpected error detected
***** Exception at 003455DB : PIO$FETCH_UPD + 000001FD
%RDMS-F-BUGCHECK, fatal, unexpected error detected
This problem is fixed in V4.0.
2.1.17 View Optimization Has Been Restored in V4.0
Starting with Rdb/VMS V3.0B and ending with V3.1B, the optimiza-
tion of views that allowed the context values from outside a view
to be used as keys for doing index retrievals of tables defined in
a view was disabled. Now, with V4.0, this view optimization has
been restored.
2-10 Software Errors Fixed
For example, assume that a view EMP_VIEW is defined on the
EMPLOYEES table and a view SH_VIEW is defined on the SALARY_
HISTORY table. Assume also that you want to retrieve all the
salary history records for the employee with a last name of
"Toliver". Further assume that the EMPLOYEES table has only one
index on LAST_NAME, and the SALARY_HISTORY table has only one
index on EMPLOYEE_ID.
If you join the EMPLOYEES and SALARY_HISTORY tables over the
EMPLOYEE_ID column and perform the selection LAST_NAME =
"Toliver", the EMPLOYEES table is accessed first using the in-
dex on LAST_NAME. Then, the EMPLOYEE_ID value from the selected
EMPLOYEES record is passed to the query optimizer to perform a
retrieval of the SALARY_HISTORY table using the index on EMPLOYEE_
ID.
Now, if you join EMP_VIEW and SH_VIEW views over the EMPLOYEE_
ID column and perform the selection LAST_NAME = "Toliver", the
EMPLOYEES table is still accessed using the index on LAST_NAME,
but the EMPLOYEE_ID value from the selected EMP_VIEW record is
not passed to the SH_VIEW. As a result, a sequential scan of the
SALARY_HISTORY table is performed that adversely affects the query
performance.
With V4.0, the EMPLOYEE_ID value from the selected EMP_VIEW record
is passed to the SH_VIEW and, therefore, this value is used to
perform the retrieval of SALARY_HISTORY table using the index on
EMPLOYEE_ID.
2.1.18 RDB$DBKEY_LENGTH System Relation Field Was Incorrect for
Certain Views
Rdb/VMS previously assigned an incorrect value to the RDB$DBKEY_
LENGTH of the RDB$RELATIONS system relation for views defined to
retrieve values (either directly or using nested view references)
from streams defined using the SQL GROUP BY or UNION clauses.
Software Errors Fixed 2-11
This situation exists because the GROUP BY clause produces a new
table of data grouped together from the various input streams
and any associated functions. Rdb/VMS then returns rows from
this table (AGGREGATE stream) as stream values, for which there
are no dbkeys because the rows are not derived directly from the
database.
This problem is fixed in V4.0. The RDB$DBKEY_LENGTH field for such
views is now set to zero (0), as such views cannot be retrieved
by dbkey.
Views of this type that have been previously defined must be rede-
fined in order for the RDB$DBKEY_LENGTH field to be set correctly.
An attempt to retrieve rows from a view containing a GROUP BY
clause will now return the diagnostic:
VIEWNORET, view cannot be retrieved by database key
2.1.19 Errors Retrying Failed Multidatabase Transactions
Retrying failed SET TRANSACTIONS (due to lock conflicts, or dead-
locks) on multidatabase transactions can result in errors such as
RDB-E-EXCESS_TRANS. This applies to RDO as well as SQL.
In Rdb/VMS V3.1, V3.1A, and V3.1B transaction information was
not properly cleared after a multidatabase SET TRANSACTION failed
(usually due to a lock conflict or a deadlock).
If, after the failure, you attempted to retry the SET TRANSACTION,
you might have received an error such as:
%RDB-E-EXCESS_TRANS, exceeded limit of 1 transaction per
database attachment
If you attempted a ROLLBACK, you might have received an error such
as:
%SQL-F-NO_TXNOUT, No transaction outstanding
This problem is fixed in V4.0.
2-12 Software Errors Fixed
2.1.20 Problem with Exclusive Locking on a Multifile Database
Produced a Bugcheck
There was a problem with the snapshot mechanism when the same
process readied one relation for exclusive write in a mixed page
format storage area that contained two or more relations and then
tried to write to a second relation in the same storage area. The
storage area was also automatically readied in exclusive mode.
When the process tried to write to the second relation, an error
was produced because the snapshot file of the second relation was
not readied.
For example, the EMPLOYEES relation and JOB_HISTORY relation
were defined to be in the same set of storage areas, EMPIDS_LOW,
EMPIDS_MID and EMPIDS_OVER. If the EMPLOYEES relation was reserved
for exclusive write and the same process attempted to write to the
JOB_HISTORY relation, it caused an error:
START_TRAN READ_WRITE RESERVING EMPLOYEES FOR EXCLUSIVE WRITE,
JOB_HISTORY FOR WRITE, DEGREES FOR WRITE
FOR E IN EMPLOYEES WITH E.EMPLOYEE_ID="00165" ERASE E END_FOR
FOR D IN DEGREES WITH D.EMPLOYEE_ID="00165" ERASE D END_FOR
FOR JH IN JOB_HISTORY WITH JH.EMPLOYEE_ID="00165" ERASE JH END_FOR
%SYSTEM-F-BREAK, breakpoint fault at PC=00000001, PSL=00320210
A workaround was to reserve the relations in shared modes, thus
enabling the snapshot mechanism.
This problem is fixed in V4.0. The problem with the snapshot
mechanism has been fixed and there is no longer any requirement
for Rdb/VMS to ready the physical area in exclusive mode.
2.1.21 Non-Fatal Bugcheck Resulted from Rdb/VMS Overflowing the EXEC
STACK
Under certain circumstances, as a result of the number of incoming
ASTs, Rdb/VMS overflowed the VMS EXEC stack, resulting in a non-
fatal VMS SSERVEXCEPT exception.
Software Errors Fixed 2-13
The symptoms of this could be:
o The process concerned went into LEF and hung there.
o The process was deleted.
The problem could occur if you had a large number of buffers
defined and a high value for ASTLM and DIOLM.
The workaround was to:
o Reduce the number of buffers used.
o Reduce the process's DIOLM.
o Reduce the process's ASTLM.
This problem is fixed in V4.0.
2.1.22 The RMUCONVERT.EXE File No Longer Exists
The RMUCONVERT.EXE file is now obsolete, as the convert function-
ality has been moved to RMU.EXE. System managers are now given
the option to delete the obsolete RMUCONVERT.EXE file during the
installation.
2.1.23 Remote Access to a V3.n Database and Starting a Transaction
Reserving Many Relations Caused the Buffer to Be Exceeded and
the Statement to Fail
Prior to V4.0 of Rdb/VMS if you attached to a remote database,
you were limited to a buffer size of 1024 bytes minus overhead.
This limited the range of statements you could perform. If you
performed a START_TRANSACTION statement reserving many relations,
the small buffer size of 1024 bytes was exceeded and the statement
failed.
2-14 Software Errors Fixed
This problem is fixed in V4.0. With V4.0 of Rdb/VMS, there is
a default of 2048 bytes for the buffer size, which permits you
to reserve more relations in a START_TRANSACTION statement. If
the default buffer size of 2048 bytes is still too small for
your application, you can calculate the size you need and set
the appropriate buffer size using the new RDB$REMOTE_BUFFER_SIZE
logical name. The maximum value for the buffer size is your system
quota limits. See Section 1.25.4 for more information about this
new logical name.
2.1.24 RDML and RDBPRE Applications Stored Segmented Strings in the
Default Storage Area Even When a Storage Area Was Already
Defined
When Rdb/VMS stores a segmented string, it first buffers the
entire segmented string, if possible, and does not store it until
the STORE statement executes.
If the segmented string remains buffered, it is stored in the
appropriate storage area. If the string is not buffered (be-
cause it is larger than the defined value for the logical name
or the default value of 10,000 bytes), it is stored in the default
RDB$SYSTEM storage area. If this is not the desired storage area,
then it is not stored correctly.
This problem is fixed in V4.0. The following exception message
now displays if the buffer size is too small to hold the segmented
string:
%RDB-F-IMP_EXC, facility-specific limit exceeded
-RDMS-E-SEGSTR_AREA_INC, segmented string was stored incorrectly
To avoid this error, set the value of the RDMS$BIND_SEGMENTED_
STRING_BUFFER logical name to a sufficiently large value. The
minimum acceptable value for the RDMS$BIND_SEGMENTED_STRING_
BUFFER logical name must be equal to the sum of the length of
the segments of the segmented string. For example, if you know
that the sum of the length of the segments is one megabyte, then
1,048,576 bytes is an acceptable value for this logical name. Note
Software Errors Fixed 2-15
that a value of up to 500 MB can be specified for this logical
name.
You must specify the logical name value because when RDML and
RDBPRE precompilers store segmented strings, Rdb/VMS does not know
which table contains the string until after the entire string is
stored.
NOTE
The SQL interface for lists (segmented strings) does not
require you to define the value for this logical name.
Before the list is brought into the buffer, SQL knows the
column that the list is associated with and the table in
which it is stored. However, for large lists, defining this
logical name with a value large enough to hold the entire
list may improve the handling performance of storing the
list.
2.1.25 Storing a Segmented String Greater in Size than 65,508 Bytes
Caused a Bugcheck
A bugcheck was produced when you tried to store a segmented string
larger than 65,508 bytes.
This problem is fixed in V4.0. The maximum size allowed for stor-
ing the first segment of a segmented string is 65,508 bytes. The
maximum size for any subsequent segments is 65,522 bytes. If ei-
ther of these values is exceeded, an error message is returned.
2.1.26 Programs with Calls to Both Rdb/VMS and DBMS Returned Link
Errors
Linking a program that accessed both a VAX Rdb/VMS and a VAX DBMS
database returned many LINK errors. For example:
%LINK-W-MULDEF, symbol KOD$_AREA_INCONSIST multiply defined
in module DBQMSG file SYS$COMMON:[SYSLIB]DBQ.OLB;3
2-16 Software Errors Fixed
This problem is fixed in V4.0.
2.1.27 Problem with Partitioned Indexes
A partitioned index allows you to specify limits for partitioning
the index keys across multiple storage areas, as in the following
example:
CREATE INDEX EMPLOYEES_INDEX
ON EMPLOYEES(LAST_NAME)
TYPE IS SORTED
STORE USING (LAST_NAME)
IN AREA_1 WITH LIMIT OF ("MILLER")
OTHERWISE IN AREA_2;
If a table has a partitioned index and at least one other index
(partitioned or single area), the index keys for the first row
stored in the table may be erroneously stored in the wrong storage
area. This problem can lead to an inability to select the first
row stored in the table, or it can lead to an Rdb/VMS bugcheck.
If you have a table with a partitioned index and at least one
other index (partitioned or single area), you can work around this
problem by dropping the indexes on the table and recreating them.
This problem is fixed in Rdb/VMS V4.0. New tables loaded in V4.0
are not subject to this problem. However, tables that were loaded
in V3.1B will require this workaround in order to correct this
problem.
2.1.28 Retrieving Records Using a Multisegmented Partitioned Sorted
Index on Uniform Storage Areas Caused a Bugcheck to Occur
If a multisegmented, partitioned sorted index defined on two
text fields was used to retrieve records from a uniform area,
a bugcheck occurred with the following exception:
***** Exception at 00205645 : PSIISCAN$END_SCAN + 0000000D
This problem is fixed in V4.0.
Software Errors Fixed 2-17
2.1.29 Queries with FIRST n Containing Aggregates and SORT Executed
Incorrectly
Main queries with a FIRST n (or LIMIT TO) clause where the value
expression n is an aggregate, coupled with a SORT or PROJECT,
returned the wrong answers (FIRST n was applied before the SORT or
PROJECT).
This problem is fixed in V4.0.
2.1.30 A Bugcheck Was Generated When the Query Optimizer Tried to
Match a Computed Field Before Evaluating the Expression
Because the query optimizer tried to join a computed field to
another relation before evaluating its value from the expression,
a bugcheck dump was generated.
This problem is fixed in V4.0. Now all computed fields are eval-
uated as part of match loop assignments before actually matching
the records from two streams.
2.1.31 Query Optimizer Chose to Use a Hashed Index When It Should
Not Have
Queries on relations using cross products chose to use a hashed
index even if the complete key was not provided, and then returned
no results. Coding the queries with FOR loops influenced the
optimizer that decided to use a sorted index and then returned
the expected results.
This problem is fixed in V4.0.
2-18 Software Errors Fixed
2.1.32 VALID IF Statements Might Not Compile or Evaluate Properly
for DEFAULT VALUEs
It is possible to have both a RDO VALID IF and SQL DEFAULT VALUE
defined for a column (either explicitly or with a GLOBAL FIELD
or DOMAIN definition). In the situation where the table-specific
column name was not the same as the "global" name, the VALID IF
compilation would fail with an "Obsolete metadata" exception. If
the compilation succeeded because the names matched, the VALID IF
frequently would not execute properly.
This problem is fixed in V4.0.
2.1.33 A STARTING WITH Predicate on a Descending Index Returned No
Data
In V3.1B, a STARTING WITH predicate on a descending index segment
produced no result. The problem can be shown on the PERSONNEL
database by defining a descending sorted index on LAST_NAME and
then using the following query:
FOR E IN EMPLOYEES
WITH E.LAST_NAME STARTING WITH 'A'
PRINT E.LAST_NAME
END_FOR
This problem is fixed in V4.0.
2.1.34 A Query Using Sort Returned Rows in Field Size Order for
VARCHAR Fields with a Collating Sequence Specified
Rdb/VMS V3.1A and V3.1B showed a problem for queries under the
following circumstances:
o A field had a data type of VARCHAR in SQL or (VARYING STRING in
RDO).
o A specific COLLATING SEQUENCE was specified.
Software Errors Fixed 2-19
o A query used the sort (that is, the optimizer solved a query by
sorting on that field).
When these conditions were met, sort returned rows in the order
of field size (that is, the shortest first) rather than in the
expected sorted sequence.
A workaround was to define an index on the field. When a query
used this index, the correct results were returned.
This problem is fixed in V4.0.
2.1.35 A Compiled Query Returned Incorrect Data When Using an Index
A compiled query that used an OR Boolean returned wrong data
when it used an index. For example, the following compiled cursor
produced an incorrect result with different values for the INPUT_
CODE column.
DECLARE TEST_CURSOR CURSOR FOR
SELECT CODE FROM TEST WHERE
((CODE > INPUT_CODE) OR
(CODE = INPUT_CODE))
ORDER BY CODE ASC
This occurred because a new index key was not constructed for each
new value of the INPUT_CODE column. As a result, a scan of the
index was always being performed starting with the first value
used for INPUT_CODE (for example, "F"). This caused an incorrect
result to be returned when the new INPUT_CODE collated before "F".
This did not occur in interactive RDO or SQL because the query is
compiled and executed each time it is issued.
This problem is fixed in V4.0.
2-20 Software Errors Fixed
2.1.36 Wrong Result Was Returned by a Query with a Predicate on a
Computed Field
The following query shown with the strategy produced a wrong
result in V3.0 and V3.1.
SELECT * FROM TAB
WHERE (A = 10 OR B = 20) AND C = 0;
Aggregate Conjunct
OR index retrieval
Get Retrieval by index of relation TAB
Index name A_INDEX [1:1]
Conjunct Get Retrieval by index of relation TAB
Index name B_INDEX [1:1]
In the query, columns A and B have separate indexes and column C
is a computed by field. The optimizer used an OR index retrieval
strategy to solve this query. In the OR index retrieval strategy,
separate data streams were used to access data from the same
table and data from these streams was merged, removing duplicate
records. The first stream used an index on column A and the second
stream used an index on column B. After the data was merged the
predicate C = 0 was applied.
The value for the computed by field, column C, was evaluated at
the first stream instead of after the data merge. As a result, the
data from the first stream was properly filtered using the predi-
cate C = 0. But for the second stream, since the value for C was
not evaluated, the predicate C = 0 failed to filter unqualified
records. As a result, more records were output than should have
been.
This problem is fixed in V4.0.
Software Errors Fixed 2-21
2.1.37 Query Did Not Use an Index-Only Retrieval Even If All the
Fields Were in an Index
Beginning in V3.1, the following query did not use an index-only
retrieval strategy even though all the fields referenced in the
query were in an index:
SELECT EMPLOYEE_ID, DBKEY FROM EMPLOYEES;
The dbkey in the select list caused the query optimizer to not use
an index-only retrieval strategy when it could have done so.
This problem is fixed in V4.0.
2.1.38 A Join Query Matched Nulls to Zeros or Blanks and Produced
Incorrect Results
In Rdb/VMS Version 3.1B and earlier, a join query matched a column
containing null values to a column containing zero or blank values
and produced an incorrect result. Rdb/VMS assumed that a null
value was equal to a zero or blank value, whereas this comparison
should produce an "unknown" match; that is, it should not produce
any joined records.
This problem only occurred in a cross join if there were null
values in the first table column and zero/blank values in the
second table column and an index retrieval was used to access
data from the second table. In all other cases, null values were
properly evaluated as not equal to zero or blank values.
This problem is fixed in V4.0.
2-22 Software Errors Fixed
2.1.39 Batch-Update or Exclusive Transactions Failed When RDB$SYSTEM
Was Read-Only
On a database with a read-only RDB$SYSTEM storage area, batch-
update or exclusive transactions failed with the following error:
%RDB-F-IO_ERROR, input or output error
-RDMS-F-CANTWRITEDBS, error writing pages 1:552-552
-SYSTEM-F-NOPRIV, no privilege for attempted operation
The same error also occurred as an exception in a bugcheck dump:
***** Exception at 0023199E : PIOUTL$DO_IORB + 000002BE
%RDMS-F-CANTWRITEDBS, error writing pages 1:720-720
-SYSTEM-F-NOPRIV, no privilege for attempted operation
A workaround was to avoid specifying RDB$SYSTEM as read-only if
your application used exclusive or batch-update transactions.
This problem is fixed in V4.0. When a transaction reserves a
relation in exclusive or batch-update mode and the SYSTEM area
is read-only, you now get the following error message:
<BATCH or EXCLUSIVE UPDATE access is not allowed if RDB$SYSTEM is READ ONLY>
Some side effects of this solution are:
o Batch-update transactions are not allowed to start if
RDB$SYSTEM is read-only. You receive the message previously
shown.
o Because Rdb/VMS now does not allow exclusive transactions
to start when the database is read-only, active read-only
transactions can proceed without being affected.
See Section 1.16 for more information.
Software Errors Fixed 2-23
2.2 SQL Software Errors Fixed
Section 2.2.1 through Section 2.2.10 describe software errors
fixed in SQL.
2.2.1 SQL$.EXE Failed to Return Status on Failure of an Import
Operation
SQL$.EXE failed to return status on the failure of an import
operation.
The following example of an SQL IMPORT statement failed because
the buffer size was smaller than the page size. No status was
returned.
$ SET NOON
$ SQL :== $SYS$SYSTEM:SQL$
$ SQL IMPORT SCHEMA FROM [DIRNAM]PERS.RBR -
FILENAME [DIRNAM]PERS.RDB -
ALLOC IS 100 PAGES -
PAGE SIZE IS 30 BLOCKS;
$ SHO SYMBOL $STATUS
$ IF .not. $status THEN WRITE SYS$OUTPUT "import failed"
$ EXIT
This problem is fixed in V4.0.
2.2.2 SQL Did Not Correctly Detect Errors in a CREATE INDEX
Statement
SQL did not correctly detect errors in a CREATE INDEX statement
when users specified USAGE UPDATE, USAGE QUERY, or PERCENT FILL
attributes more than once.
The USAGE UPDATE, USAGE QUERY, and PERCENT FILL clauses all set
the PERCENT FILL attribute for the index.
This problem is fixed in V4.0. A message is now generated if this
attribute is specified more than once per index.
2-24 Software Errors Fixed
2.2.3 Generated Constraint Names and Check Option Constraint Names
Were Not Checked
When a statement generated a constraint name for the check con-
straint, it did not first check to make sure that its generated
name had not already been used by another constraint in the
schema.
A user-specified constraint name for check constraints was not
checked to make sure that it was not already used by another
constraint in the schema.
Both problems are fixed in V4.0.
2.2.4 SQL Quantified Predicates Did Not Function in Trigger WHEN
Predicates
Quantified predicates ALL, ANY (SOME), or their usage with pred-
icate IN (query select expression) did not execute properly when
used in the WHEN predicate of a trigger action.
This problem is fixed in V4.0.
2.2.5 Problem with INTEGRATE Statement When SQL Database Is Defined
with DICTIONARY IS REQUIRED Clause
A problem occurred with the INTEGRATE statement from SQL when
the database was defined with the dictionary required. In the
following example of an INTEGRATE statement that failed, the
user changed a data definition from CDD/Plus, which is referenced
in a database, and then tried to integrate the definition from
CDD/Plus to Rdb/VMS. The database is defined using the DICTIONARY
IS REQUIRED clause.
SQL> INTEGRATE SCHEMA PATHNAME cdd-path ALTER FILES;
%CDD-E-INTFAIL, integration failed
-RDB-E-NO_META_UPDATE, metadata update failed
-RDMS-F-CDDISREQD, CDD required for metadata updates is not being maintained
Software Errors Fixed 2-25
The workarounds were:
o Change the database so that dictionary is not required.
o Use the RDO INTEGRATE statement.
This problem is fixed in V4.0.
2.2.6 Problems with INTEGRATE SCHEMA . . . CREATE PATH in SQL
The following example illustrates an SQL problem with rolling back
changes after an unsuccessful attempt to integrate changes into
the dictionary.
SQL> INTEGRATE SCHEMA FILE MF_PERSONNEL CREATE PATH DISK1:[DICT.REPOS]
MF_PERSONNEL;
%CDD-E-NOT_FOUND_2, !AS !AS not found in !AS !AS
SQL>exit
There are uncommitted changes to this schema.
Would you like a chance to ROLLBACK these changes (No)? yes
SQL> rollback;
%SQL-F-ERRATTDEF, Could not use database file specified by SQL$DATABASE
-RDB-E-BAD_DB_FORMAT, SQL$DATABASE does not reference a database known to Rdb
-RMS-E-FNF, file not found
The symptoms of this problem were:
o SQL did not return the correct FAO arguments to the CDD-E-NOT_
FOUND_2 error message.
o After the attempt to integrate, SQL would not allow changes to
be rolled back.
This problem is fixed in V4.0.
2-26 Software Errors Fixed
2.2.7 Short Char Variable Was Not Padded Correctly
When a C string is longer than the data being retrieved into it,
ANSI requires that to end the C string that it be padded with
blanks and then null terminated. There was a problem in that the C
string was not immediately null terminated following the data.
This problem is fixed in V4.0 to meet ANSI specifications.
2.2.8 SQL C Precompiler Generated Incorrect Code
Incorrect code was generated by the SQL C Precompiler when closing
braces were on the same line as EXEC SQL statements, as follows:
if (SQLCA.SQLCODE != 0)
{ exec sql rollback;}
#ifdef DEBUG
The problem has only occurred when a C statement beginning with
the number (#) character followed an EXEC SQL statement where
the closing curly brace (}) was on the same line as the EXEC SQL
statement. In the preceding example, the C statement was on the
line starting with: #ifdef . . .
The preceding precompiled code produced incorrect C code. This
incorrect C code caused syntax errors to be generated from the VAX
C compiler.
However, a syntax error was not always produced with this problem,
as there might be times when the incorrect code generated is
syntactically acceptable to the VAX C compiler.
If your programming style included placing closing curly braces
around EXEC SQL statements, then you might want to check the code
generated by the SQL C precompiler from your programs.
A workaround was to place the closing curly brace (}) on the line
following the EXEC SQL statement.
This problem is fixed in V4.0.
Software Errors Fixed 2-27
2.2.9 SQLPRE Changed Names of the SQLDAs to Uppercase
Whenever a host variable name was generated for the host language
file, it was converted to uppercase. This caused problems in
VAX C if the host variable was declared from the SQLDA_STRUCT
structure with a lowercase name. The reference in the generated
procedure argument list did not match the declaration and the VAX
C compilation failed. Note that this problem only applied to host
variables that were prefixed with the colon (:) character.
This problem is fixed in V4.0.
2.2.10 SQL$PRE Hung in Batch Mode When an Invalid File Name Was
Given
If a mistake was made with a file name, then the SQL precompiler
hung waiting for a file name to be entered by the user; if this
was a batch job, then the batch job hung until stopped.
This problem is fixed in V4.0. Now, if a wrong file name is given,
an error message is returned and the batch job aborts.
2.3 RDO and RDBPRE Software Errors Fixed
Section 2.3.1 through Section 2.3.16 describe problems fixed in
the RDO and RDBPRE interfaces.
2.3.1 RDO EXPORT Now Prints the Reason for Failure
A problem in RDO EXPORT operations caused only the error message
to be printed if the EXPORT operation failed.
In some cases, the reason for the EXPORT failure was not printed
by RDO as shown here:
2-28 Software Errors Fixed
RDO> EXPORT DISK1:[DIR]PERSONNEL INTO SCRATCH:MF_P
%RDO-F-DELBACKUP, EXPORT errors, interchange file deleted
-RDO-F-NOBCKFIL, interchange file SCRATCH:MF_P not created
-RMS-F-DEV, error in device name or inappropriate device type for
operation
In Rdb/VMS the message would appear simply as:
RDO> EXPORT DISK1:[DIR]PERSONNEL INTO SCRATCH:MF_P
%RDO-F-DELBACKUP, EXPORT errors, interchange file deleted
This problem is fixed in V4.0. RDO now prints the primary message
and a secondary message describing the problem.
2.3.2 IMPORT Statement Could Fail to Import Views or Tables with
COMPUTED BY Fields
IMPORT could fail to import a view or table with COMPUTED BY
fields if the COMPUTED BY had a dependency on a table or view
not yet imported. This was caused by not explicitly exporting
the tables or views in the proper (RELATION_ID) order, and can be
corrected by exporting the database again, or redefining the view
or table after the IMPORT operation has completed.
This problem caused the following error during the import of a
table or view:
%RDO-E-NOVIERES, unable to IMPORT view VUE_7_UNE_VUE
-RDB-E-NO_META_UPDATE, metadata update failed
-RDB-E-OBSOLETE_METADA, request references metadata objects that no longer exists
-RDMS-F-TABNOTDEF, relation VUE_2_UNE_VUE is not defined in database
This problem is fixed in V4.0.
2.3.3 RDO IMPORT Statement Did Not Support ANSI-Style Protection
The RDO IMPORT statement did not support importing ANSI-style
protection of databases.
This problem is fixed in V4.0.
Software Errors Fixed 2-29
2.3.4 RDO IMPORT Would Appear to Stall in an Infinite Loop
The IMPORT process was functionally correct, but very slow when
re-creating the COMPUTED BY fields.
This problem is fixed. The performance of computed-by fields in
import operations is much improved.
If you cannot install Rdb/VMS V4.0, you can work around this
problem by deleting the computed-by fields before the EXPORT
operation and manually redefining them after the IMPORT operation.
Alternately, if you must import a database that was exported with
the computed-by fields defined, be sure that that you use the
RDM$BIND_BUFFERS logical name and a large WORKING SET (WSMAX) so
that the the IMPORT operation can retain all the metadata in main
memory. (For the test database, use a WSMAX parameter value equal
to 30,000, and 3,000 buffers.)
2.3.5 RDO DEFINE STORAGE MAP DESCRIPTION IS Clause Was Ignored
Although RDO accepted the DESCRIPTION IS clause for storage map
statements, the information was never stored in the database.
This problem is fixed in V4.0. The DESCRIPTION IS text is now
correctly stored in the database and can be displayed with the
SHOW STORAGE MAP statement.
2.3.6 RDO SHOW RELATION Failed with INVALID_BLR for VIDA Databases
RDO in Rdb/VMS V3.1 was enhanced to show the relation compres-
sion setting, which is determined from the RDB$FLAGS field in
RDB$RELATIONS. Unfortunately the reference was not conditional-
ized, and database systems such as VIDA, Rdb/ELN, and older ver-
sions of Rdb/VMS would generate an error when the SHOW RELATIONS
command was used.
2-30 Software Errors Fixed
RDO> SHOW VERSION
Current version of RDO is: Rdb/VMS T3.1B-1
Underlying versions are:
Database with filename /type=vida2/tab=cargo
VIDA/DB2 V1.0-A
VIDA Server For DB2 V1.0-0
MVS/XA R3.8
CICS V1.7
DB2
Rdb/Disp V3.1-1
RDO> SHOW RELATION
User Relations in Database with filename /type=vida2/tab=cargo
%RDB-F-INVALID_BLR, request BLR is incorrect at offset 185
-VIDA2-E-FIELD_NOT_FOUND, Field RDB$FLAGS is not in relation RDB$RELATIONS
In Rdb/VMS V4.0, RDO has been corrected to conditionally fetch
this field. As a workaround, you can use the SQL SHOW TABLE com-
mand as an alternative.
2.3.7 Views with FIRST n Could Use Outer Query Booleans for Indexed
Retrieval
Views that include a FIRST n clause could use Booleans from the
containing or outer queries to affect the rows retrieved by the
view.
The following view and query no longer selects and prints the row
with employee_id "00167" as it is not the first row selected by
the view.
DEFINE VIEW EV OF FIRST 1 E IN EMPLOYEES SORTED BY E.EMPLOYEE_ID.
E.EMPLOYEE_ID.
END.
FOR FIRST EV IN EV WITH EV.EMPLOYEE_ID = "00167" PRINT EV.*
END_FOR
This problem is fixed in V4.0.
Software Errors Fixed 2-31
2.3.8 Problem Creating a View with a WITH CHECK OPTION Clause
Without a WHERE Predicate in the SELECT Clause
SQL permits the WITH CHECK OPTION clause to be used without a
WHERE predicate in the SELECT clause. However, Rdb/VMS assumed
that there is always a WHERE clause in the SELECT clause and when
it was not there generated an error message.
This problem is fixed in V4.0.
2.3.9 Problem with Multikey Partitioned Indexes
When defining a multikey, partitioned index on a relation and
selecting records based on only the first attribute of the index,
records were not always found.
This problem is fixed in V4.0.
2.3.10 Index Scan Problem Caused a FOR Loop to Loop Infinitely
Scanning an index caused a FOR loop to loop infinitely. This
problem was discovered when the KEYS.RDO procedure in Appendix
A of the Introduction to Database Development (that is part of
the VAX Information Architecture documentation) was run on the
PERSONNEL.RDB sample database.
This problem is fixed in V4.0.
2.3.11 A Bugcheck Resulted When Using the PLACE Verb Within a FOR
Loop Using RDO
The following program fragment resulted in a bugcheck when the
PLACE verb was used across two databases within the FOR loop using
RDO.
2-32 Software Errors Fixed
DATA DB1 = FILE ME:PERSONNEL.RDB
DATA DB2 = FILE PERSONNEL.RDB
!
START_TRANSACTION READ_WRITE
FOR C IN DB1.EMPLOYEES
PLACE PE IN DB2.EMPLOYEES USING PE.EMPLOYEE_ID = C.EMPLOYEE_ID
PRINT PE.RDB$DB-KEY
END-PLACE
END-FOR
This problem is fixed in V4.0.
2.3.12 The /NOINITIALIZE Qualifier in FORTRAN Required That Four
Characters Be Specified
The parser incorrectly handled the FORTRAN /NOI4 qualifier. The
new option, /NOINITIALIZE, shares the same first three letters as
/NOI4. The parser recognized the three characters and accepted the
qualifier as /NOINITIALIZE. The fourth character was left hanging
and was used as part of the filename specification.
This problem is fixed in V4.0. The fix requires the user to spec-
ify four characters /NOIN for the /NOINITIALIZE option in FORTRAN
only, otherwise the parser passes it down to the compiler.
2.3.13 RDBPRE BASIC Preprocessor Generated Ambiguous Code
The RDBPRE BASIC preprocessor parser treated lines that started
with a comment character as a continuous comment.
This problem is fixed in V4.0. The parser has been changed to
treat lines that start with a comment in BASIC as a line of BASIC
code. This is now consistent with FORTRAN and COBOL.
Software Errors Fixed 2-33
2.3.14 When You Entered an ACL Entry, an Argument to the Position
Clause Could Not Exceed 255
If you used an integer higher than 255 as an argument to the
position clause when you defined entries in an Access Control
List, Rdb/VMS produced the following error message in RDO:
%LIB-F-INTOVF, integer overflow error occurs defining ACLS in RDO
The POSITION clause in the corresponding SQL statement accepted
integers higher than 255.
This problem is fixed in V4.0.
2.3.15 COMPUTED BY Clause in Aggregate Subqueries Produced Bugcheck
Dumps
Under some conditions the COMPUTED BY clause in aggregate sub-
queries produced bugcheck dumps.
This problem is fixed in V4.0.
2.3.16 Query on System Relations Caused a Loop
The following query on system relations would loop in V3.1:
2-34 Software Errors Fixed
RDO> START_TRANS READ_WRITE RESERVING
cont> RDB$RELATION_FIELDS FOR SHARED READ,
cont> RDB$INDEX_SEGMENTS FOR SHARED READ,
cont> RDB$INDICES FOR SHARED READ,
cont> KEY_FIELDS FOR EXCLUSIVE WRITE;
RDO> FOR U IN RDB$INDICES CROSS I IN RDB$INDEX_SEGMENTS WITH
cont> NOT I.RDB$FIELD_NAME STARTING WITH "RDB$" AND
cont> U.RDB$INDEX_NAME = I.RDB$INDEX_NAME
cont> STORE K IN KEY_FIELDS USING
cont> K.KEY_FIELD_NAME = I.RDB$FIELD_NAME;
cont> K.KEY_RELATION_NAME = U.RDB$RELATION_NAME;
cont> K.INDEX_FLAG = "*";
cont> END_STORE;
cont> END_FOR;
This problem is fixed in V4.0.
2.4 RDML Software Errors Fixed
Section 2.4.1 through Section 2.4.9 describe RDML software errors
that are fixed.
2.4.1 RDML Did Not Recover from Statistical Function Keywords Used
as Host Variables
In versions previous to V4.0 of Rdb/VMS, if you used a statistical
keyword (COUNT, AVERAGE, MAX, MIN, and TOTAL) as a host variable,
RDML generated an ambiguous "Fatal Preprocessor Utilities" error.
The RDML statistical functions could be used only with numeric
data types.
This problem is fixed in V4.0. When RDML encounters a value ex-
pression that follows a statistical function, it now recovers from
the error.
Software Errors Fixed 2-35
2.4.2 RDML Did Not Display the Names of Context Variables Improperly
Referenced by SORTED BY and REDUCED TO Clauses
RDML checks fields referred to by context variables in SORTED BY
and REDUCED TO clauses and indicates the line number but did not
otherwise indicate the context variable. In the following example,
the error messages did not indicate that two context variables, P
and SP, were improperly referenced:
FOR E IN EMPLOYEES CROSS JH IN JOB_HISTORY
WITH ((P.EMPLOYEE_ID =SP.EMPLOYEE_ID) AND (SP.JOB_END MISSING))
REDUCED TO P.EMPLOYEE_ID
SORTED BY P.EMPLOYEE_ID, SP.JOB_CODE, JH.DEPARTMENT_CODE
writeln( P.EMPLOYEE_ID, ' ', P.FIRST_NAME, E.LAST_NAME,
SP.JOB_CODE, ' ', SP.DEPARTMENT_CODE);
%RDML-W-NOTLOCAL, Field referenced in SORTED BY or REDUCED TO
is not in the context of query
%RDML-I-ATLINE, at line 10 in the file DISK1:[RDML]CROSS1P.RPA;
%RDML-W-NOTLOCAL, Field referenced in SORTED BY or REDUCED TO
is not in the context of query
%RDML-I-ATLINE, at line 11 in the file DISK1:[RDML]CROSS1P.RPA;
%RDML-W-NOTLOCAL, Field referenced in SORTED BY or REDUCED TO
is not in the context of query
%RDML-I-ATLINE, at line 11 in the file DISK1:[RDML]CROSS1P.RPA;
END_FOR;
This problem is fixed in V4.0.
2.4.3 RDML Context Variables Could Not Be Named the Same as the
Relation
Context variables in RDML could not be named the same as the
relation, as shown in the following example:
2-36 Software Errors Fixed
FOR EMPLOYEES IN EMPLOYEES WITH EMPLOYEES.EMPLOYEE_ID = '00123'
SORTED BY EMPLOYEES.LAST_NAME
WRITELN(EMPLOYEES.LAST_NAME);
END_FOR
This problem is fixed in V4.0.
2.4.4 Using Concatenated Expression Failed in C with Invalid Operand
Error
The following RDML query failed with invalid target for assign-
ment:
FOR R IN RELATION WITH (R.FIELD1|R.FIELD2) > host_language_variable
This problem is fixed in V4.0.
2.4.5 RDML REDUCED TO Clause Generated BLR in Reverse Order
The RDML REDUCED TO clause generated BLR in the reverse order of
the fields specified in a user query.
FOR C IN COLLEGES
CROSS ........
REDUCED TO C.COLLEGE_CODE, C.COLLEGE_NAME, C.CITY, C.STATE
Although this was logically equivalent and produced the correct
result, it affected the Rdb/VMS query optimizer strategy chosen in
this case.
RDML generated REDUCED TO C.COLLEGE_CODE, C.COLLEGE_NAME, C.CITY,
C.STATE as follows:
BLR$K_PROJECT, CHR(4),
BLR$K_FIELD, CHR(5), CHR(5), 'S', 'T', 'A', 'T', 'E',
BLR$K_FIELD, CHR(5), CHR(4), 'C', 'I', 'T', 'Y',
BLR$K_FIELD, CHR(5), CHR(12), 'C', 'O', 'L', 'L', 'E', 'G', 'E', '_', 'N', 'A', 'M', 'E',
BLR$K_FIELD, CHR(5), CHR(12), 'C', 'O', 'L', 'L', 'E', 'G', 'E', '_', 'C', 'O', 'D', 'E',
Software Errors Fixed 2-37
This problem is fixed in V4.0. The REDUCED TO clause now generates
BLR in the same order as the fields specified in the user query.
2.4.6 RDML Generated Incorrect Code for a STORE Statement in a
Pascal Program
The RDML preprocessor generated an incorrect STORE code. This
caused a STORE statement in an RDML Pascal program to fail without
an ON ERROR clause correctly trapping the error.
This problem is fixed in V4.0.
2.4.7 In SORTED BY or REDUCED TO Clauses RDML Did Not Check That
Only Local Fields Were Included
RDML did not check that only local fields were included in the
sort list of SORTED BY or REDUCED TO clauses.
This problem is fixed in V4.0. RDML now returns a warning on any
fields that are referred to within SORTED BY or REDUCED TO clauses
but are not currently defined in this query.
2.4.8 Incompatible Data Types in VAX Pascal Generated Code
Data types that are not supported by VAX Pascal (Segmented
Strings, Date) are converted to approximate host language data
types for Pascal.
These data types were often not compatible with those declared by
the application programmer, or with those generated from CDD/Plus
using the %DICTIONARY statement.
For example, the following code fragments would generate an error
when processed with the Pascal compiler.
2-38 Software Errors Fixed
PROGRAM SEGSTR_PROBLEM;
DATABASE
FILENAME 'PERSONNEL';
TYPE
%DICTIONARY 'CDD$DEFAULT.RESUMES'
VAR
RESUMES_REC: RESUMES;
BEGIN
READY;
START_TRANSACTION READ_ONLY;
FOR R IN RESUMES
GET
RESUMES_REC = R.*;
END_GET;
END_FOR;
COMMIT;
FINISH;
END.
The error message generated by the Pascal compiler was:
$ PASCAL SEGSTR_PROBLEM
00852 0 5 RESUMES_REC.RESUME := RDB$MSG_PORT_1_0.RDB$PORT_FIELD_1
1
%PASCAL-E-OPNDASSCOM, (1) Operands are not assignment compatible
%PASCAL-E-ENDDIAGS, PASCAL completed with 1 diagnostic
This restriction has been removed for RDML in Rdb/VMS V4.0. RDML
now generates the VAX Pascal type cast operator so that the as-
signments will be compatible. This assumes that the chosen data
types are of the correct length.
The data types of the host variables must follow these rules:
o Segmented string ID fields must be QUADWORD size (8 bytes in
length).
Software Errors Fixed 2-39
With this release of RDML, any 8-byte data type is acceptable.
However, Digital recommends that you use the RDML DECLARE_
VARIABLE statement to define host variables.
In general, saving the segmented string id for a segmented
string is not encouraged. Rather, you should use the FOR or
STORE statements to access segmented strings (RDML will issue
an informational diagnostic reporting this usage). However,
when using the RDML GET statement with wildcards the generated
code retrieves the segmented string id fields.
o Date fields must be a QUADWORD size (8 bytes in length).
With this release of RDML any 8-byte data type is acceptable.
However, Digital recommends that you use the RDML DECLARE_
VARIABLE statement to define host variables.
o Scaled integers
This class of data types includes SIGNED BYTE, SIGNED WORD,
SIGNED LONGWORD, and SIGNED QUADWORD, which have a negative
SCALE. Pascal does not support this type of variable, so RDML
coerces the data type to DOUBLE (G_FLOAT). The resulting value
contains data of the correct magnitude, but some precision may
be lost.
If the host variable being used to fetch the data is not of a
data type DOUBLE or REAL, then VAX Pascal generates an error
because the data types are not assignment compatible. This
remains a restriction in V4.0 of Rdb/VMS.
Use of the GET, STORE or MODIFY statements with wildcards is
not supported if the host language data type for fields as-
sociated with SCALED integers is not DOUBLE or REAL. Digital
recommends that you use the RDML DECLARE_VARIABLE statement
to define host variables. If only the name of the relation is
specified in DECLARE_VARIABLE, then a host language structure
(record) is generated (see Section 2.4.9). The record compo-
nents are compatible with those used elsewhere by RDML and can
be used with the wildcard GET, STORE and MODIFY statements.
2-40 Software Errors Fixed
2.4.9 DECLARE_VARIABLE Restriction Removed
The RDML statement DECLARE_VARIABLE was restricted in previous
versions to declaring only single fields. This restriction has
been removed, so that now the relation name alone can be speci-
fied. This will cause the entire record/structure to be declared.
The following example declares a record from EMPLOYEES, and a
single variable from EMPLOYEE_ID.
var
DECLARE_VARIABLE employees_record SAME AS EMPLOYEES;
DECLARE_VARIABLE badge_number SAME AS EMPLOYEES.EMPLOYEE_ID;
2.5 RMU Software Errors Fixed
Section 2.5.1 through Section 2.5.17 describe problems fixed in
RMU.
2.5.1 Problem Existed with the RMU/LOAD Operation
When performing an RMU/LOAD operation without constraints being
defined on the database, the operation worked fine. But when the
same operation was performed with constraints defined, it gave the
following error message:
%RDB-E-BAD_TPB_CONTENT, invalid transaction parameters in the transaction
parameter block (TPB).
The problem here was neither in RMU's construction of the TPB
nor in the definition of the constraints. The problem was that
RMU was passing a byte value to Rdb/VMS for the TPB length. The
number of constraints defined and the length of the names of the
relations used generated a 280-byte TPB. This clearly exceeded the
255-byte limit that RMU permits, thus causing the error and the
error message to be generated.
Software Errors Fixed 2-41
The workaround was to delete some constraints and redefine them
after the LOAD operation.
This problem is fixed in V4.0.
2.5.2 RMU/BACKUP and VMS DCL COPY of Single-File Databases Made the
Database Unusable
RMU/BACKUP incorrectly placed the fully expanded file specifica-
tion in the backup of the root file; thus, if you used the VMS DCL
command COPY to copy a single-file database, the database would be
unusable.
This problem is fixed in V4.0. The VMS DCL command COPY can be
used with single-file databases.
2.5.3 RMU/BACKUP/ONLINE Had Lock Conflict Problems
In previous versions of Rdb/VMS, RMU/BACKUP/ONLINE sometimes en-
countered lock conflict problems, especially if another applica-
tion used exclusive lock mode during the backup operation.
This problem is fixed in V4.0.
2.5.4 RMU/BACKUP/ONLINE Waited Indefinitely for a Quiet Point Lock
RMU/BACKUP/ONLINE would wait indefinitely for the quiet point lock
before backing up the database. This was an inconvenience.
This problem is fixed in V4.0. There is now a new /LOCK_
TIMEOUT=seconds qualifier that can be specified in an online
backup operation. This is described in Section 1.22.
2-42 Software Errors Fixed
2.5.5 RMU/BACKUP/ONLINE /CHECKSUM_VERIFICATION Qualifier Would
Occasionally Fail
When the RMU/BACKUP/ONLINE command was performed specifying the
/CHECKSUM_VERIFICATION qualifier, it would fail occasionally
because the check was not being made at the correct time.
This problem is fixed in V4.0.
2.5.6 A By-Area Backup Was Always Performed Against the Last Full
Backup
A by-area backup was always performed against the last full
backup. This created the restriction that the /INCREMENTAL quali-
fier could not be used for backing up files by areas.
This problem is fixed in V4.0. The /INCREMENTAL=COMPLETE/AREA
switch has been added to the RMU/BACKUP command. See Section 1.22
for more information on the use of these qualifiers.
2.5.7 Problem Existed with RMU By-Area Backup Function
There was a problem with the RMU/RESTORE/AREA (restore by-area)
function.
Incremental backup operations (including by-area backups) were
always relative to the last full and complete backup performed.
The following sequence of operations exhibited the problem:
1. The user performs a full and complete backup.
2. The user performs an incremental and complete backup.
3. The user restores the full and complete backup.
4. The user restores the incremental and complete backup. The
database is now in the same state as at the end of step 2.
Software Errors Fixed 2-43
5. The user performs another full and complete backup.
6. One area is lost, and the second backup is also lost.
7. A by-area restore operation from the first full backup can be
performed.
8. An incremental by-area restore operation from the incre-
mental backup cannot be performed because the second (lost)
full backup changed the last backup date and the full by-area
RESTORE operation does not record in the database the date of
the full backup that was applied.
If a complete set of journals was available from the state in Step
2 to the present time, you could recover the database using the
RMU/RECOVER command. Otherwise, you had to repeat Steps 3 and 4 to
perform the recover operation.
This problem is fixed in V4.0.
2.5.8 Problem Existed with RMU/BACKUP or RMU/RESTORE with More Than
268 Database Storage Areas
A database with more than 268 areas could be backed up or re-
stored, but the backup file could not be dumped.
This problem is fixed in V4.0.
2.5.9 CHANGE FIELD COLLATING_SEQUENCE Did Not Work on RMU/RESTORE
Command That Used Convert
If you tried to execute a CHANGE FIELD statement specifying a
collating sequence such as NORWEGIAN on a database restored and
converted from Rdb 3.0x on to Rdb/VMS V3.1A or V3.1B, then the
command did not work. No error was returned, but if you performed
a SHOW FIELD statement, no collating sequence was shown and the
ASCII (default) collating sequence was used.
2-44 Software Errors Fixed
A workaround was to perform an export/import operation of the
database and then execute the CHANGE FIELD statement.
This problem is fixed in V4.0.
2.5.10 Problem Existed with RMU/RESTORE/INCREMENTAL and Adding a
Storage Area
If the RMU/RESTORE command was used with the
/INCREMENTAL=COMPLETE (or just /INCREMENTAL) or
/INCREMENTAL=BY_AREA qualifier to add a storage area, the con-
nection between the RDA file and its snapshot file was sometimes
not properly made.
This problem is fixed in V4.0.
2.5.11 RMU/RESTORE Did Not Ignore Logical Areas Outside the Range of
1 to 16,384 and Produced a Bugcheck
While restoring a database using the RMU/RESTORE command, Rdb/VMS
produced a bugcheck with the exceptions kod$get_vm and sys-f-
roprand, and the process was deleted from the system. The prob-
lem was that the RMU/RESTORE operation did not detect that the
database was corrupt because it contained storage area IDs outside
the range of 1 to 16,384.
This problem is fixed in V4.0. The RMU/RESTORE operation now
marks logical areas with IDs outside the range of 1 to 16,384
as deleted.
2.5.12 RMU/RECOVER By-Area Did Not Work Correctly
Because RMU/RECOVER by-area is based on physical areas and not
logical areas, information was required from the RDB$SYSTEM stor-
age area, which meant that different areas could be at different
consistency levels, and the information in the RDB$SYSTEM storage
area might not be correct.
Software Errors Fixed 2-45
This problem is fixed in V4.0. In correcting this problem, the
AIJ file structure has changed. Consequently, the format for the
display of the AIJ file has also changed. See Section 1.22 for
more information.
2.5.13 RMU/RECOVER By-Area Command Has Changed Semantics
There was a restriction on the use of the RMU/RECOVER command
on RMU/RESTORE/AREA operations. The restriction was that the
RMU/RECOVER command could not recover a database in which a by-
area restore operation had placed an area in a transaction state
that was later than the state recorded in the database root file.
Consequently, if the root file was lost, you could not use an
RMU/RESTORE/AREA command (by-area restore operation) to bring the
database forward from the last full and complete backup operation
performed. In this case, you could only bring the database forward
by using either of the following two strategies:
o Use an incremental complete restore operation.
o Use the RMU/RECOVER command to apply the complete set of AIJ
files that dated back to the last full and complete backup
operation.
This restriction is still in effect, but beginning with V4.0, the
RMU/RECOVER command automatically checks the time-stamps of the
storage areas and root file to determine what to do.
When the /AREAS qualifier is specified in the RMU/RECOVER command,
it has no effect when any of the storage areas are consistent
(time-stamps match) or are ahead of the root in time (time-stamps
for the storage areas are later than the root file). In these
cases, a full recover operation is always performed. This ensures
that Rdb/VMS always succeeds in recovering the database.
2-46 Software Errors Fixed
2.5.14 RMU/VERIFY Could Not Verify the Root File If the AIJ File Was
Open
When the RMU/VERIFY operation attempted to open the after-image
journal file with incompatible RMS "sharing" attributes while
trying to verify the root file, it failed. If the AIJ file was
open (by the monitor or another user), the RMU/VERIFY operation
was not able to successfully verify the root file.
This problem is fixed in V4.0. In the meantime, all non-root
file validation can happen read-only by specifying the /NOROOT
qualifier on the RMU/VERIFY command. If it is desirable to perform
the root file verification, then this operation must be performed
when the AIJ file has been closed either by the monitor or as
a result of the last database user process detaching from the
database.
2.5.15 Errors Occurred During RMU/VERIFY
If one user was running RMU/VERIFY on a database and another
user attached to the database and locked a resource needed by
RMU/VERIFY, the RMU/VERIFY operation aborted when it attempted to
lock the resource.
This problem is fixed V4.0.
2.5.16 Database Verification Returned %RMU-W-BADDBPRO Error
During the verification of a database, RMU returned the error
%RMU-W-BADDBPRO. This was due to the method that was used to
translate device names, and the way Rdb/VMS stored the translated
names internally.
This problem does not indicate any database corruption and is
fixed in V4.0.
Software Errors Fixed 2-47
2.5.17 RMU/REPAIR Corrupted Databases
Using the RMU/REPAIR command to fix SPAMPGENT warnings resulting
from running the RMU/VERIFY command on a database resulted in a
corrupt database. This is a known problem with V3.1B.
This problem is fixed in V4.0.
2-48 Software Errors Fixed
Chapter 3
Known Problems, Restrictions, and Other Notes
This chapter describes problems and restrictions relating to
Rdb/VMS Version V4.0, and includes workarounds where appropriate.
It also contains other information, such as documentation errors
and omissions and restrictions retained from V3.1, that is not
discussed in the preceding chapters.
The notes in this chapter may use different database terms to mean
the same thing. For example, some terms used by SQL differ from
terms used by other interfaces, such as RDO or RDML. Table 1 in
the Preface shows some of the different terms used.
3.1 Known Problems and Restrictions for All Interfaces
Section 3.1.1 through Section 3.1.21 contain known problems and
restrictions for all interfaces.
3.1.1 Improving the Performance of the EXPORT Operation Using the
DCL SET Command to Change the Default Extend Parameter Value
Normally, during an EXPORT operation, the Rdb/VMS interchange file
(RBR) which uses the RMS default extent, will extend for every
three (3) blocks the RBR file grows in size. To prevent this,
define the following SET command to change the process default RMS
extent quantity:
Known Problems, Restrictions, and Other Notes 3-1
$ SET RMS_DEFAULT/EXTENT_QUANTITY=30000
Now, rather than "extending" the RBR file for every 3 blocks
(which involves many extend operations), the RMS Extend is only
invoked once per 30,000 blocks. By specifying a larger value for
the file extend parameter, the runtime of the EXPORT operation can
be significantly improved.
3.1.2 Undetected Deadlock with Distributed Transactions
When you use distributed transactions to access databases on re-
mote systems, you run a risk of encountering undetected deadlock.
Deadlock occurs when two users are locking resources that each
needs and neither user can continue until the other user ends a
transaction. When deadlock occurs on the same node or the same
cluster, the VMS lock manager detects the deadlock and issues the
deadlock error condition to one user. However, when a transaction
accesses databases on remote systems, the VMS lock manager cannot
detect the deadlock.
To help avoid distributed deadlock, Rdb/VMS provides the following
methods to set the amount of time a transaction waits for locks to
be released:
o The logical name RDMS$BIND_LOCK_TIMEOUT_INTERVAL
o The WAIT <interval> clause of the SET TRANSACTION or DECLARE
TRANSACTION statement
See the VAX Rdb/VMS Guide to Distributed Transactions for more
information.
3-2 Known Problems, Restrictions, and Other Notes
3.1.3 Restrictions on Distributed Transactions Related to the
DISTRIBTRAN Security Privilege
If you do not have the DISTRIBTRAN privilege and you try to start
a distributed transaction, Rdb/VMS returns an error and does not
start the transaction. This is especially important to remember
when you use SQL. SQL starts a distributed transaction by de-
fault when you start a transaction that attaches to more than one
database.
The following privileges override the DISTRIBTRAN privilege:
o The SQL privilege DBADM
o The RDO privilege ADMINISTRATOR
o The VMS privilege SYSPRV
o The VMS privilege BYPASS
When you start a distributed transaction that attaches to a
database on a remote node, Rdb/VMS checks that the account on
the remote node has the DISTRIBTRAN privilege. For example, if
you use a proxy account on the remote node, the proxy account must
have the DISTRIBTRAN privilege on that database.
For more information about granting privileges, see the VAX
Rdb/VMS Guide to Database Design and Definition, the VAX Rdb/VMS
SQL Reference Manual, or the VAX Rdb/VMS RDO and RMU Reference
Manual.
3.1.4 SNAPSHOTS DEFERRED May Stall Transactions
If your database has snapshots set to ENABLED DEFERRED, users may
not be able to bind to the database once you have issued one of
the following statements:
o RDO DEFINE, CHANGE, or DELETE RELATION
Known Problems, Restrictions, and Other Notes 3-3
o SQL CREATE, ALTER, or DROP TABLE
o RDO DEFINE or DELETE INDEX
o SQL CREATE or DROP INDEX
During database attach, Rdb/VMS locks certain key metadata rela-
tions and reads them to construct the metadata information cache
used to process requests against the database. When one of the
previously listed statements executes, a read-write transaction
that updates these metadata relations, any subsequent database at-
tach (equivalent to a read-only transaction) will stall until the
read-write transaction is completed. Users that were bound to the
database before the statement was issued can continue accessing
the database.
To avoid this problem, modify the database so that snapshots are
ENABLED IMMEDIATE. You can use any of the following statements to
set snapshots to ENABLED IMMEDIATE:
o SQL CREATE SCHEMA or RDO DEFINE DATABASE
o SQL ALTER SCHEMA or RDO CHANGE DATABASE
o SQL or RDO IMPORT
3.1.5 PLACEMENT VIA INDEX Clause Prohibits Shadow Clustering
Shadow clustering of records that use the PLACEMENT VIA INDEX
clause of the CREATE STORAGE MAP statement for any index to clus-
ter records in a uniform storage area does not work in Rdb/VMS
Version 3.1, Version 3.1A, Version 3.1B, or Version 4.0. The rem-
edy for this problem is being investigated for a future release.
3-4 Known Problems, Restrictions, and Other Notes
3.1.6 Using the CREATE INDEX Statement Locks the Database If
Snapshots Are Deferred
A user creating an index on a single relation in a database will
lock out all other users from attaching to the database if the
database has snapshots deferred.
The documentation states that a user creating an index on a single
relation in a database requires exclusive access to that rela-
tion. Other users may access different areas of the same database
as long as these areas are not being affected by a CREATE INDEX
statement. This is documented in V3.1 in the VAX Rdb/VMS RDO and
RMU Reference Manual on page 8-124. However, it has been found
that if the database has snapshots set to ENABLED DEFERRED, then
no users can attach to the database once the CREATE INDEX state-
ment has been started. Users that were attached to the database
prior to the start of the CREATE INDEX statement can continue
accessing the database as documented.
This is a known restriction. Use of deferred snapshots will cause
conflict when using data definition language (DDL) statements in
a production environment because snapshot copies of the system
metadata cannot be written to the snapshot file.
The workaround is to modify the database from snapshots are
ENABLED DEFERRED to snapshots are ENABLED IMMEDIATE to prevent
this problem from happening.
3.1.7 Source Attributes for Storage Maps Are Not Saved in Pre-V3.1
SQL IMPORT Operations
Versions of an EXPORT operation prior to V3.1 did not save the
source attribute for the storage maps. This was corrected in
Rdb/VMS V3.1 so that EXPORT operations save the source of the
DEFINE STORAGE MAP (or CREATE STORAGE MAP) statements. However,
this means that a database exported under V3.0 loses the storage
map source; therefore, it cannot be displayed using either SQL or
RDO.
Known Problems, Restrictions, and Other Notes 3-5
In the meantime the following RDO script may be useful in display-
ing some characteristics of the storage map.
FOR R IN RDBVMS$STORAGE_MAPS
WITH R.RDB$FLAGS > 0
SORTED BY R.RDB$RELATION_NAME
PRINT "-------------------------------------------------------------------"
PRINT "Storage Map " | R.RDBVMS$MAP_NAME
PRINT "for relation " | R.RDB$RELATION_NAME
PRINT " Source segstr-id: ", R.RDBVMS$MAP_SOURCE
FOR RA IN RDBVMS$STORAGE_MAP_AREAS
WITH RA.RDBVMS$MAP_NAME = r.RDBVMS$MAP_NAME
SORTED BY RA.RDBVMS$ORDINAL_POSITION
PRINT " Area " | RA.RDBVMS$ORDINAL_POSITION |
" is " | RA.RDBVMS$AREA_NAME, RA.RDBVMS$STORAGE_BLR
END_FOR
END_FOR
3-6 Known Problems, Restrictions, and Other Notes
NOTE
1. If the "Source segstr-id" is equal to 0:0:0, or -1:
-1: -1, then no source is saved for this storage map
(problem in V3.0*, fixed in V3.1*).
2. Each storage area is followed by a segstr-id, which
points to the storage BLR that describes the WITH LIMIT
clauses (you may like to display them as well, but it
will make sense only for TEXT or VARYING STRING fields).
3. The last storage area listed should be -1: -1: -1 be-
cause there can be no WITH LIMIT clause applied to the
last storage area because it is the last or catchall
storage area.
This problem will be investigated further in a version after V4.0,
so that the full storage map information can be displayed without
resorting to displaying the original input source.
3.1.8 RDB$SYSTEM Storage Area Cannot Be Read-Only When a Relation Is
Readied in Exclusive or Batch-Update Mode
When a relation is readied in exclusive or batch-update mode,
the RDB$SYSTEM storage area must not be read-only. An exception
message is now returned if the RDB$SYSTEM storage area is read-
only and you try to ready a relation in exclusive or batch-update
mode.
This is an Rdb/VMS restriction. Exclusive access to a relation
or index must always write to the RDB$SYSTEM storage area because
this type of access does not write the "before" images of the
modified data into the snapshot file. Consequently, a read-only
access to the same relation or index must have a way of knowing
whether the snapshot file will be capable of materializing the
generation of the data that it requires.
Known Problems, Restrictions, and Other Notes 3-7
Each exclusive access must record that it is not maintaining
snapshots on a per index or per relation basis, since this is
the unit of data for which Rdb/VMS permits the setting of the
access mode. The natural location to store the fact that snapshots
are not being maintained is with the relation or index definition,
since the definition must be accessed when the relation or index
is reserved. Storing it elsewhere would incur additional overhead.
The relation and index definitions are stored in the RDB$SYSTEM
area.
Consequently, if the RDB$SYSTEM area has been set to read-only you
are not permitted to access any relation of index in the exclusive
mode. This condition affects all database access.
3.1.9 Joined Relations Do Not Allow "MODIFY" If Using the WITH
Clause
The Rdb/VMS V3.0 and V3.1 documentation indicate that views do
not allow updates to returned data. They do not specify this
restriction on a cross of two relations from the same database.
Rdb/VMS allows it to work if you use a WITH clause.
Any field that appears in the RSE (record selection expression) is
marked as read-only. You cannot update these fields as this may
remove the record from the join, or add a new record to the join
that will not be recognized.
In general, the record stream created by a join (CROSS) is not
updatable. A workaround is to fetch the RDB$DB_KEY in the loop and
generate a separate FOR loop to modify the value. The following
example shows this situation.
#include stdio
DATABASE MAPB = FILENAME "[tseng.rdml]PERSONNEL";
3-8 Known Problems, Restrictions, and Other Notes
main()
{
READY MAPB;
START_TRANSACTION READ_WRITE;
/* RESERVING EMPLOYEES FOR SHARED WRITE;
*/
printf("Entering EMPLOYEES & JOB_HISTORY relations:\n\n");
FOR E IN EMPLOYEES
CROSS JH IN JOB_HISTORY OVER EMPLOYEE_ID
WITH (JH.EMPLOYEE_ID > "00000" OR E.FIRST_NAME STARTING WITH "A-")
SORTED BY E.LAST_NAME
FOR E1 IN EMPLOYEES WITH E1.RDB$DB_KEY = E.RDB$DB_KEY
printf("\n\n%s %s < found ",E1.FIRST_NAME ,E1.LAST_NAME);
/*1234567890 --- 10 characters max*/
MODIFY E1 USING
strcpy(E1.FIRST_NAME,"Xavier ");
printf("\n%s %s < changed",E1.FIRST_NAME,E.LAST_NAME);
END_MODIFY;
END_FOR;
END_FOR;
printf("\n\nRolling Back the modifys");
ROLLBACK;
FINISH;
printf("\n\nFinished");
}
Known Problems, Restrictions, and Other Notes 3-9
3.1.10 Using RDML/C to Update a VIEW Returns Errors
Attempting to use the RDML MODIFY function on a VIEW that accesses
a single relation, opened READ_WRITE, fails with a READ_ONLY error
if the CROSS qualifier is used. It works if there is no CROSS
qualifier.
This is a known restriction. Any field that appears in the RSE
(record selection expression) is marked as read-only. You cannot
update these fields as this may remove the record from the join,
or add a new record to the join that will not be recognized.
In general, the record stream created by a join (CROSS) is not
updatable.
As a workaround, you should fetch the RDB$DB_KEY in the loop and
generate a separate FOR loop to modify the value shown as follows:
#include stdio
DATABASE MAPB = FILENAME "[tseng.rdml]PERSONNEL";
main()
{
READY MAPB;
START_TRANSACTION READ_WRITE;
/* RESERVING EMPLOYEES FOR SHARED WRITE;
*/
printf("Entering EMPLOYEES & JOB_HISTORY relations:\n\n");
FOR E IN EMPLOYEES
CROSS JH IN JOB_HISTORY OVER EMPLOYEE_ID
WITH (JH.EMPLOYEE_ID > "00000" OR E.FIRST_NAME STARTING WITH "A-")
SORTED BY E.LAST_NAME
FOR E1 IN EMPLOYEES WITH E1.RDB$DB_KEY = E.RDB$DB_KEY
printf("\n\n%s %s < found ",E1.FIRST_NAME ,E1.LAST_NAME);
/*1234567890 --- 10 characters max*/
MODIFY E1 USING
strcpy(E1.FIRST_NAME,"Xavier ");
3-10 Known Problems, Restrictions, and Other Notes
printf("\n%s %s < changed",E1.FIRST_NAME,E.LAST_NAME);
END_MODIFY;
END_FOR;
END_FOR;
printf("\n\nRolling Back the modifys");
ROLLBACK;
FINISH;
printf("\n\nFinished");
}
3.1.11 Range Query Returns Unexpected Results
There is a problem with sequential access being unable to return
all the records in a uniform area. When a select is performed
using a sorted index, it returns the correct number of records.
The same query not using the index retrieval returns the last
two records and misses the first one. The query will work in both
cases if BETWEEN is used instead of the ">= and <=" construct in
the following case.
SQL> SELECT * FROM TB_DAY, TB_RANGE
cont> WHERE DAY >= BEGIN_DAY AND DAY <= END_DAY;
TB_DAY.DAY TB_RANGE.BEGIN_DAY TB_RANGE.END_DAY
19900501 1-MAY-1990 00:00:00.00 3-MAY-1990 00:00:00.00
19900502 1-MAY-1990 00:00:00.00 3-MAY-1990 00:00:00.00
19900503 1-MAY-1990 00:00:00.00 3-MAY-1990 00:00:00.00
3 rows selected
SQL> DROP INDEX IX_DAY;
SQL> SELECT * FROM TB_DAY, TB_RANGE
cont> WHERE DAY >= BEGIN_DAY AND DAY <= END_DAY;
TB_DAY.DAY TB_RANGE.BEGIN_DAY TB_RANGE.END_DAY
19900502 1-MAY-1990 00:00:00.00 3-MAY-1990 00:00:00.00
19900503 1-MAY-1990 00:00:00.00 3-MAY-1990 00:00:00.00
2 rows selected
Known Problems, Restrictions, and Other Notes 3-11
This problem is identical to the problem where the RSE contains
a text string with leading zeros and the database field is an
integer. The data is fetched if the field is indexed and missed if
not.
3.1.12 DECLARE and START Stream Are No Longer Allowed for Certain
Views
RDO does not allow a record stream from which data values cannot
be fetched (views that retrieve values from streams defined using
the SQL GROUP BY or UNION clauses) to be declared or started. Such
attempts produce the following exception:
VWNOFETCH view 'view-name' cannot be fetched within a stream
3.1.13 A Clarification of the Storage Algorithm for Mixed Pages
A problem was found when clustering records of two different re-
lations on one page, in a mixed storage area, and storing dupli-
cate records for one of the relations. The first duplicate record
was stored on a consecutive page, while additional records were
stored on the target page until the SPAM value indicated that the
page was full. A display of the contents of the data page showed
sufficient free space on the target page for storing the first
duplicate record. Why was the first duplicate record not stored on
the target page if there was sufficient space to store it there?
This is a known restriction in V4.0. Whenever a process holds
a lock (for example a read lock) on a page and at the same time
another process is trying to store a record on that page, the
record is stored on a nearby page.
When Rdb/VMS stores a record, it tries to optimize the storage
process. Therefore, if the page where the record would ideally
be stored is not immediately available, Rdb/VMS simply finds a
nearby page that is immediately available and stores it there.
This algorithm does quite well for many database designs.
3-12 Known Problems, Restrictions, and Other Notes
There is a trade-off between storage performance and retrieval
performance. If Rdb/VMS chose to wait during a store operation,
the resulting clustering would be good, but the storage perfor-
mance would suffer. On the other hand, if Rdb/VMS did not wait
during a store operation (as it does now), the clustering might
suffer. However, this lack of clustering happens only when other
processes holding locks on the same page at the same time that
store operations are being attempted. If the page in which the
record is actually stored is in the same buffer, the retrieval
will not incur more I/O operations.
This condition will be considered for further investigation in a
future release.
3.1.14 Adjustment of Cardinalities in V4.0 Is Likely to Cause Poorer
Optimizer Performance
In Version V4.0, dynamic optimization attempts to approach op-
timal query performance by relying heavily on the statistics
collected during query execution. If index and table cardinal-
ities are artificially shifted away from their correct values,
they will contradict the dynamically collected statistics and
cause quite unpredictable selection of strategies and sequence of
their evaluation. Hence any adjustment of cardinalities in Version
V4.0 will most probably result in poorer optimizer performance.
See Section 1.3 for more information on dynamic optimization.
3.1.15 SELECT on SCHEMA (READ on DATABASE) ACE Is Now Required
The Rdb/VMS security mechanism now requires users to have the
SELECT privilege on the SCHEMA access control entry (ACE) or READ
privilege on the DATABASE access control entry (RDO).
The SELECT schema privilege has always been enforced, but not
explicitly. A user must now have the SELECT schema privilege in
the schema ACE in order to attach to a schema.
Known Problems, Restrictions, and Other Notes 3-13
Rdb/VMS schema privileges DBADM, OPERATOR, and SECURITY; and VMS
privileges SYSPRV, BYPASS, READALL, OPERATOR, and SECURITY can
bypass this check. These privileges receive an implicit schema
SELECT privilege.
3.1.16 Rdb/VMS Network Link Failure Does Not Allow FINISH to Tidy Up
Transactions
If you have a program that attaches to a database on a remote node
and you lose the connection before the COMMIT statement is issued,
there is nothing you can do except exit the program and start
again.
The problem occurs when a program is connected to a remote
database and does an update but then just before it commits, the
network fails. When the commit executes, the SQL code shows as it
normally should that the program has lost the link. Perhaps the
user would like to wait for a minute or two, then try the trans-
action again. The problem is that when the start transaction is
issued for the second time, it fails because old information still
exists about the previous failed transaction. This occurs even
if the user issues a FINISH statement, which also fails with an
RDB-E-IO_ERROR error message.
3.1.17 Passwords for the RDB$REMOTE Account in UAF and for the
RDBSERVER Object in NCP Must Be the Same
The password for the RDB$REMOTE account in the user authorization
file (UAF) must be the same as the password for the RDB$REMOTE
account for the RDBSERVER object in the network control program
file (NCP).
If the passwords are different, then any remote operation (for
example, remote IVP) will fail.
Therefore, users must update the passwords for the RDB$REMOTE
account in two places, the UAF and NCP.
3-14 Known Problems, Restrictions, and Other Notes
3.1.18 RDB$REMOTE Account Is Now Non-Privileged
The RDB$REMOTE account is no longer a privileged account.
Therefore, a user who accesses Rdb/VMS through the RDB$REMOTE
account must now have the schema SELECT (database READ) privilege
in his/her schema (database) ACE in order to attach to a schema
(database).
3.1.19 VAX Data Distributor Copy Processes Do Not Process Database
Pages Ahead of an Application
When a copy process or a group of copy processes initiated by
VAX Data Distributor begins running after an application has
begun modifying the database, the copy processes will catch up
to the application and will not be able to process database pages
that are logically ahead of the application in the RDB$CHANGES
relation. The copy processes will all align waiting for the same
database page and will not move on until the application has
released it. This degrades the performance of each copy process
because each is being paced by the application.
When a copy process completes updates to its respective remote
database, it updates the RDB$TRANSFERS relation and then tries
to delete any RDB$CHANGES records not needed by any transfers.
During this process the RDB$CHANGES relation cannot be updated
by any application process, holding up any database updates until
the deletion process is complete. The application will stall while
waiting for RDB$CHANGES. The result is that there is contention
for RDB$CHANGES SPAM pages and data pages that severely impacts
performance throughput requiring user intervention with normal
processing.
This is a known restriction in the current release. Rdb/VMS uses
page locks as latches. These latches are held only for the dura-
tion of an action on the page and not to the end of transaction.
The page locks also have blocking asynchronous system traps (ASTs)
associated with them. Therefore, whenever a process requests a
Known Problems, Restrictions, and Other Notes 3-15
page lock, the process holding that page lock is sent a block-
ing AST (blast) by VMS. The process that receives such a blast
queues the fact that the page lock should be released as soon as
possible. However, the page lock cannot be released immediately.
Such work requests to release page locks are handled at verb
commit time. An Rdb/VMS verb is an Rdb/VMS query that executes
atomically, within a transaction. In general, one RDO statement
is a verb. Therefore, verbs that require the scan of a large
relation, for example, can be quite long. An updating application
does not release page locks until its verb has completed.
The reasons for holding on to the page locks until the end of the
verb are quite fundamental to the database management system.
This condition is being investigated further in a future release
of Rdb/VMS.
3.1.20 Setting an Appropriate WSEXTENT Relative to WSQUOTA for
SORT/MERGE Operations
If you are performing any explicit sorting operations which in-
clude projection (SQL ORDER BY and DISTINCT, and RDO SORTED BY
and REDUCE TO) or an implicit sort operation as performed by the
query optimizer and the query is taking more time than expected to
complete and you notice lots of disk accesses, you should check
your WSEXTENT and WSQUOTA parameter values to see if they are set
properly for the operation. For example, if the WSEXTENT value is
42,000 pages and the WSQUOTA value is 20,000 pages, try setting
the WSEXTENT parameter value closer to the value for WSQUOTA. That
is, WSEXTENT=WSQUOTA+2000. Sort (which is called many times during
this query execution) uses the difference between these two param-
eters (in this case 2000 pages) to allocate VM for scratch space.
This results in excessive paging when a disk-based temporary file
would be more efficient.
3-16 Known Problems, Restrictions, and Other Notes
The VMS Sort/Merge Utility Manual states that sometimes less mem-
ory is desirable for these kinds of operations. If the system is
heavily used, the VMS operating system may be unable to allocate
all the pages in the working set extent to your process. To avoid
excessive paging in a heavily used system, you could make the
working set extent lower. See the VMS Sort/Merge Utility Manual
for more information.
3.1.21 Attempting to Acquire a Lock Could Cause an Infinite Loop
In some rare cases, Rdb/VMS can go into an infinite loop while
attempting to acquire a lock. This problem occurs only during
contention situations with heavily loaded systems and will not
cause data corruption.
The process that is looping will consume the CPU and result in
performance degradation on that node. When this happens, the
process has to be stopped manually to correct the problem.
3.2 SQL Known Problems and Restrictions
Section 3.2.1 through Section 3.2.14 describe known problems and
restrictions in SQL for V4.0.
3.2.1 SQL Applications Involved in Distributed Transactions Must
Have DISTRIBTRAN Privilege
When you recompile your applications under V4.0, SQL uses the
two-phase commit protocol by default. However, you must have the
DISTRIBTRAN privilege on any database you want to involve in a
distributed transaction. See Section 3.1.3 for more information.
Known Problems, Restrictions, and Other Notes 3-17
3.2.2 SQL Allows False Redefinition of the DATE Data Type
If a DOMAIN is defined that redefines the DATE data type, SQL
returns no errors; however, it ignores the DOMAIN definition.
Using SQL (Rdb/VMS V3.0B-001), you can issue the following com-
mands to show this.
SQL> CREATE DOMAIN DATE CHAR (100);
SQL) CREATE TABLE ABC
cont> (FIELD_1 DATE,
cont> FIELD_2 DATE);
SQL>
SQL> SHOW TABLE ABC;
SQL assigns the native mode data type of DATE to the columns
FIELD_1 and FIELD_2. Table ABC will show fields FIELD_1 and FIELD_
2 as data type DATE, and not as DOMAIN date.
This continues as a restriction for V4.0. SQL allows SQL keywords
to be used as an identifier, that is, they are not reserved words.
This is an extension to the ANSI standard.
In any context where an identifier is expected, the SQL keyword
may be used, and it is understood to be an identifier. However, in
any context where the SQL keyword is allowed, it is understood to
be the keyword. In other words, when SQL expects either a particu-
lar set of keywords or an identifier, if the user attempts to use
one of those particular keywords as an identifier, precedence is
given to the keyword meaning over the identifier meaning.
This is what happens in the case of table definitions. The data
type of a column may be an SQL data type (a keyword such as
INTEGER, DATE, etc.) or a domain (identifier). In this case, since
SQL is looking for either an SQL data type name keyword or an
identifier, when it sees one of the SQL data type keywords, it has
the SQL data type meaning and not the domain meaning.
3-18 Known Problems, Restrictions, and Other Notes
A workaround for this particular problem is to use the authoriza-
tion id of the domain instead of just the domain name alone. That
is, if the schema is the default schema, the authorization id is
RDB$DBHANDLE and the statement will distinguish between the DATE
domain with the SQL data type by the same name. Similarly, in a
DECLARE <auth-id> SCHEMA statement, the <auth-id> will allow the
domain to be used.
SQL> CREATE DOMAIN DATE CHAR (100);
SQL> CREATE TABLE ABC
cont> (FIELD_1 RDB$DBHANDLE.DATE,
cont> FIELD_2 RDB$DBHANDLE.DATE);
3.2.3 Problem Adding a New Field to CDO Defined Record and Not to
Last Position
If a new field is added to a CDO defined record and not to the
last position, it causes a mismatch on field order if the record
is used as a basis for a relation. The new field will be put at
the end of the Rdb/VMS relation, which means there is no longer a
one-to-one correspondence.
This problem also causes problems for precompiled SQL code when it
passes all the fields from the relation into a storage area within
the program. However, similar constructs using RDBPRE do handle
the mapping correctly.
This problem is fixed in V4.0. An error message is now displayed.
A workaround is to use the PATHNAME qualifier to declare the
schema to ensure that the dictionary record and the table are
synchronized.
The INCLUDE FROM DICTIONARY statement builds an internal represen-
tation of the structure that the host language will get from the
dictionary; the dictionary is used to determine which fields are
in the record and in what order.
Known Problems, Restrictions, and Other Notes 3-19
If the schema is declared with the FILENAME qualifier, the pre-
compiler uses the system relations to determine which columns are
in each table and in what order. On the other hand, if the schema
is declared by PATHNAME, the precompiler uses the dictionary to
determine which columns are in each table and in what order.
When the schema is declared with the FILENAME qualifier and the
dictionary is used to define a data structure, the star of the
SELECT statement for the UPDATE_CHG cursor expands to a list of
columns in the order in which they are known to Rdb/VMS (which
never reorders them) and the dbord_rel structure contains fields
in the order in which they are known to the dictionary. They do
not match, and the FETCH statement attempts to assign values to
the wrong fields.
They do match, however, when the schema is declared by PATHNAME.
The start of the SELECT statement expands to a list of columns in
the same order as the fields of the dbord_rel structure.
The reason for the difference between SQLPRE and RDBPRE is that
RDBPRE uses a different mechanism for building the source column
list.
3.2.4 Module Language Passes Extraneous Characters with Inexact
Dynamic Descriptors
Although SQL module language processes dynamic strings correctly
in other contexts, you must use either a static descriptor or a
dynamic descriptor of exact length whenever you use the GENERAL
language.
When you create an SQL module language source file specifying the
GENERAL language, you can define character parameters that are
passed by descriptor. The restriction only applies when calling
the module language from a language that uses dynamic instead of
static string descriptors (such as BASIC or VAX SCAN), in partic-
ular when passing a parameter to an INSERT operation. Instead of
padding the string with blanks, SQL stores extraneous characters
3-20 Known Problems, Restrictions, and Other Notes
in the data field character positions after those in the original
dynamic string.
You can prevent this problem from occurring in a language such as
BASIC by putting the string definition in a MAP declaration, which
makes the string static instead of dynamic.
3.2.5 Close List Cursor Before Fetching Rows from Table Cursor
When accessing SQL segmented strings, you must be careful to
close a list cursor before you fetch the next row in the table
cursor. If you fetch some, but not all, rows from a list cursor
and move to the next row in the table cursor without closing the
list cursor, you continue to fetch rows from the previous list
cursor. SQL does not issue a warning or error message telling you
that you have opened two list cursors.
SQL>! Define a cursor of Board Manufacturing Department Managers
SQL>!
SQL> DECLARE BM_MGR CURSOR FOR
cont> SELECT EMPLOYEE_ID, RESUME FROM RESUMES R, CURRENT_INFO CI
cont> WHERE R.EMPLOYEE_ID = CI.ID AND DEPARTMENT
cont> CONTAINING "BOARD MANUFACTURING" AND JOB = "Department Manager";
SQL>!
SQL>! Define a cursor for resumes of those managers
SQL> DECLARE THE_RESUME LIST CURSOR FOR
cont> SELECT RESUME WHERE CURRENT OF BM_MGR;
SQL>!
SQL>! Build the manager's cursor
SQL> OPEN BM_MGR;
SQL>!
SQL>! Fetch the manager's row
SQL> FETCH BM_MGR;
R.EMPLOYEE_ID R.RESUME
00164 72:2:3
SQL>!
SQL>! Get part of the resume
SQL> OPEN THE_RESUME;
Known Problems, Restrictions, and Other Notes 3-21
SQL> FETCH THE_RESUME;
RESUME
This is the resume for Alvin Toliver
SQL>!
SQL>! Do not close the resume, and access the next manager
SQL> FETCH BM_MGR;
R.EMPLOYEE_ID R.RESUME
00166 72:2:9
SQL>! SQL continues to fetch from Toliver's resume (00164)
SQL>! because the list cursor was not closed.
SQL>! If it were a new resume, you would see
SQL>! a new "This is the resume for ..." line.
SQL> FETCH THE_RESUME;
RESUME
Boston, MA
3.2.6 SELECT Statement with GROUP BY Clause Did Not Return Date
Fields in EDIT STRING Format
When SQL is used to select fields using a GROUP BY clause from
a database defined as a DATE data type and have an EDIT string
associated with them, the data is returned in a format that is
different than that specified in the EDIT clause. The following
example shows this problem.
3-22 Known Problems, Restrictions, and Other Notes
SQL> CREATE TABLE FOO (
cont> FIELD1 DATE EDIT STRING "NN/DD/YYYY");
SQL> INSERT INTO FOO (FIELD1) VALUES ("08-MAR-1989");
1 row(s) inserted
SQL> INSERT INTO FOO (FIELD1) VALUES ("09-MAR-1989");
1 row(s) inserted
SQL> COMMIT;
SQL> SELECT FIELD1 FROM FOO;
FIELD1
3/08/1989
3/09/1989
2 row(s) selected
SQL> SELECT FIELD1 FROM FOO GROUP BY FIELD1;
FIELD1
8-MAR-198
9-MAR-198
2 row(s) selected
This is a restriction with V4.0. The formatting capabilities of
interactive SQL may be enhanced in a future release.
3.2.7 When Using the BETWEEN Operator, You Should Specify the Lower
Value First
SQL now evaluates the BETWEEN operator differently to comply with
the ANSI/ISO standard. When using the BETWEEN operator, you must
specify the lower value first to obtain the correct result:
BETWEEN 10 AND 20
With previous versions of SQL, the BETWEEN operator returned
the same results whether you specified the higher or lower value
first.
Known Problems, Restrictions, and Other Notes 3-23
3.2.8 Cautions on Using ANY, ALL, or IN Clauses in Constraint
Definitions
For Rdb/VMS V3.1, a change was made to correct the results re-
turned by the ANY (SOME) and ALL predicates to conform to the ANSI
SQL standard. The changes required for ANSI compliance produced
a different type of query for ANY and ALL (and for the IN predi-
cate when a query expression is used) such that the query can no
longer be selectively evaluated when used in a constraint. The
workaround for any performance problems introduced by this change
is re-creating the affected constraint with an EXISTS predicate
(or equivalent) applied to a column select expression, as shown in
the following example:
CHECK (T1.F1 IN (SELECT T2.F1 FROM T2))
- to -
CHECK (EXISTS (SELECT * FROM T2 WHERE T2.F1 = T1.F1))
- or -
CHECK ((SELECT COUNT (*) FROM T2 WHERE T2.F1 = T1.F1) <> 0)
3.2.9 SQL Does Not Recognize a Record During SQL Precompile Time
During SQL precompile time, SQL does not recognize a record used
in the program by its language process name. The error detected
is:
%SQL-F-HVNOTDECL, (1) Host variable xxx was not declared.
This problem occurs in V3.0B, V3.1, and V4.0.
When you define fields and records in CDD/Plus with CDO, and
insert a PROCESS NAME for a language with the CDO editor, SQL
is not able to use it.
3-24 Known Problems, Restrictions, and Other Notes
In COBOL for example, the COPY FROM DICTIONARY retrieves the
PROCESS NAME for COBOL as expected in spite of the PROCESSING
NAME. But, when you use the specified PROCESS NAME for COBOL in an
SQL sentence like:
EXEC SQL DECLARE xxx CURSOR FOR
SELECT ....
FROM ....
WHERE e.employee_id = :my_process_name_record.a_field
END_EXEC.
You will get the following error:
%SQL-F-HVNOTDECL, (1) Host variable A_FIELD was not declared.
If you use the processing name of the record, no error occurs on
its field but CDD/Plus has lost some of its functionality.
This is a restriction in V4.0 of Rdb/VMS. In V4.0, SQL does not
support the process name in the dictionary at this time.
3.2.10 An SQLMOD Query Returns Empty Rows
An application program that calls the SQLMOD procedure to fetch
from current of cursor receives only empty rows from Rdb/VMS when
the DECLARE CURSOR statement contains an ORDER BY clause. In other
words, no data is placed in the application buffer. This problem
only happens when all three of the following conditions are true:
o The query solution for the cursor uses a sort or a temporary
table.
o The SQLMOD program also contains a procedure that updates cur-
rent of cursor, but this procedure is not used by the applica-
tion program.
o There is a before-update trigger on the table the cursor se-
lects data from.
Known Problems, Restrictions, and Other Notes 3-25
For such a cursor, Rdb/VMS copies data into the user buffer from a
memory location instead of from the sort (or the temporary table).
The memory location does not contain any data and therefore the
application program is returned an empty row.
A workaround to this problem is to avoid use of a sort or a tempo-
rary table in the query solution of the cursor. This can be done
by defining an appropriate index so that the query solution no
longer uses the sort or the temporary table.
Another workaround is to delete the update current of cursor
procedure from the SQLMOD program if no updates are needed. If
update of cursor is required, then separate out the update cur-
rent of cursor procedure into another SQLMOD program. Note, that
the cursor that is updated should not have any ORDER BY clause.
Otherwise, the same problem may occur with this second cursor if
the query solution for it uses a sort or a temporary table.
This problem only exists in Rdb/VMS V4.0 and will be fixed in a
future release.
3.2.11 Input VARCHAR Parameter Actual Value Is Longer Than Procedure
Parameter
If a module language procedure declares a parameter intended for
input whose data type is varchar(M), and at runtime a parameter
is passed whose data type is varchar(n) (where n doesn't really
matter if the actual length N of the parameter is greater than
the declared length M in the procedure), Rdb/VMS will be passed
a varying text value of length N whose last (N-M) characters are
potentially meaningless.
This can be a problem in the following instance:
module foo
...
procedure blah
sqlcode the_name varchar(10) the_count int;
select count(*) into the_count from dogs where name = the_name;
3-26 Known Problems, Restrictions, and Other Notes
main()
{
long sqlcode;
long the_count;
struct {
short len; char value[20];
} the_name = {15, {'R','o','v','e','r',' ','t','h','e',
' ','g','r','e','a','t'} };
blah( &sqlcode, &the_name, &the_count );
}
What will happen is that the Rdb/VMS request will end up looking
not for the name "Rover the great", but rather "Rover the ^%*$#"
where the last five characters are meaningless.
This will be fixed in a future release.
3.2.12 Release of Cursor Statements Referencing Prepared Statements
Causes Problems
When a prepared statement refers to a cursor that is destroyed
by a release of its own statement, the first statement becomes
dangerous in this way. This is a known problem that has existed
since SQL V1.0.
This will be fixed in a future release.
3.2.13 SQL Does Not Translate Logical Names Referencing Source
Databases
When you create an extraction or extraction rollup transfer and
you want to use a source database that requires the /TYPE access
string, you must first enter a DECLARE SCHEMA statement for that
database. One method of referencing the source database is to
define a logical name, as shown in the following example:
Known Problems, Restrictions, and Other Notes 3-27
$ DEFINE SOURCE_DB "/TYPE=VIDA2/DATABASE=SHIPPING..."
$ SQL
SQL> DECLARE SCHEMA FILENAME SOURCE_DB;
SQL> CREATE TRANSFER FROM_SHIPPING TYPE IS EXTRACTION ...
However, SQL does not translate the logical name into the access
string when the source schema is declared by referring to a log-
ical name. In the previous example, examination of the transfer
definition will show "From . . . SOURCE_DB" instead of "From . . .
/TYPE=VIDA2/DATABASE=SHIPPING . . . ".
The transfer will fail to execute properly unless the SOURCE_DB
logical name is defined when the copy process runs. A copy process
runs as a detached process using the same VMS account that you
use to create the transfer. Therefore, the SOURCE_DB logical name
will be properly translated if you define it in your LOGIN.COM
file. The logical name can also be defined in your group or system
logical name tables. The logical name "SOURCE_DB" is used here as
an example; you can use any name you want.
3.2.14 Problem with Transferring a Table to an Existing Database
Containing the Same Table Name
If you define a transfer to an existing database and specify a
table name in the transfer definition that already exists in the
target database, SQL checks to determine if the table was created
by the current transfer.
o If the transfer owns the table, then the transfer definition is
valid.
o If the transfer does not own the table, SQL issues an error
message and the transfer fails. You must use the INTO keyword
with the table-name parameter to rename the duplicated table.
3-28 Known Problems, Restrictions, and Other Notes
However, in SQL Version 4.0, SQL looks for the source table name
in the target database instead of the table name specified in the
INTO table-name clause. Because the source table name does exist
but does not belong to the current transfer, SQL issues an error
message declaring that the transfer does not own the table.
The following example illustrates this situation. Assume that EMP_
COLLEGES in the target database PERS_1 is not owned by transfer
XYZ.
SQL> DECLARE SCHEMA FOR FILENAME "PERSONNEL";
SQL> CREATE TRANSFER XYZ TYPE IS REPLICATION
cont> MOVE TABLES
cont> SELECT * FROM COLLEGES INTO EMP_COLLEGES
cont> TO EXISTING FILENAME DISK1:[DIR1]PERS_1
cont> LOG FILE IS DISK1:[DIR1]XYZ.LOG
cont> ;
%SQL-F-TRANOTOWNER, This transfer is not the owner of table EMP_COLLEGES
You can resolve this problem by using the WITH NO CHECKING quali-
fier with the CREATE TRANSFER statement, as shown in the following
example:
SQL> DECLARE SCHEMA FOR FILENAME "PERSONNEL";
SQL> CREATE TRANSFER XYZ TYPE IS REPLICATION
cont> MOVE TABLES
cont> SELECT * FROM COLLEGES INTO EMP_COLLEGES
cont> TO EXISTING FILENAME DISK1:[DIR1]PERS_1 WITH NO CHECKING
cont> LOG FILE IS DISK1:[DIR1]XYZ.LOG
3.3 RDO and RDBPRE Known Problems and Restrictions
Section 3.3.1 describes known problems and restrictions in RDO and
RDBPRE for V4.0.
Known Problems, Restrictions, and Other Notes 3-29
3.3.1 RDO SHOW USERS and SHOW MONITOR Statements Do Not Work for
Remotely Accessed Databases
If you access a database remotely, you cannot use the RDO SHOW
USERS or SHOW MONITOR statements. The following example shows this
problem.
RDO> SHOW USERS
Database with filename ARTIC::personnel
%RDMS-F-BAD_NAME, illegal filename
-RDMS-F-NONODE, no node name is allowed in the file specification
RDO>
3.4 RDML Known Problems and Restrictions
Section 3.4.1 contains an RDML known problem and restriction for
V4.0.
3.4.1 RDML Generates an Error Message When Attempting to Store or
Modify Read-Only (COMPUTED BY) Fields
In RDML, if you use a PATHNAME clause in combination with a STORE
* clause or a MODIFY * clause on a relation containing a COMPUTED
BY Field, RDML generates the following error:
%RDML-E-READ_ONLY, Invalid attempt to update a read only field 'FLD3'
%RDML-I-ATLINE, at line 32 in the file DISK1:[TTEMP]TEST.RPA;
%RDML-I-NODMLOUTPUT, No output file generated due to errors
%RDML-I-SUMMARY, Completed with 1 Error, 0 warnings, and
1 informational message
3-30 Known Problems, Restrictions, and Other Notes
3.5 RMU Known Problems and Restrictions
Section 3.5.1 through Section 3.5.6 describe known problems and
restrictions in RMU for V4.0.
3.5.1 Non-Updatable Fields Cannot Be Unloaded Using the RMU/UNLOAD
Command
The RMU/UNLOAD command cannot be used to unload fields of a view
or relation that are COMPUTED BY fields because, in general, the
unloaded columns can be recomputed from the real fields. The
reason for this is that COMPUTED BY fields are not updatable.
Consequently, if the fields were able to be unloaded, the UNL
file could not be used to reload the data because the fields in
the file must match the updatable fields in number and data type,
which is not possible using this command.
The SQL standard says that merged fields (unioned columns) and
aggregate valued columns are not updatable. To prevent a user from
updating these columns, Rdb/VMS defines an implicit COMPUTED BY
global field (SQL domain) for each non-updatable field.
Therefore, if you want to unload a view or relation containing
COMPUTED BY fields and load them back into a compatible table in
the same or different database, you will need to write your own
SQL programs to accomplish this task.
One additional restriction is that if a view or relation contains
all COMPUTED BY fields and you attempt to unload it, an error
message is returned indicating that this is not possible.
Known Problems, Restrictions, and Other Notes 3-31
3.5.2 Single-File Databases Require the /ROOT Qualifier When Using
the RMU/MOVE_AREA Command
You must specify the /ROOT qualifier when you use the RMU/MOVE_
AREA command on a single-file database. If you omit the /ROOT
qualifier, you will receive an error message. When you specify the
/ROOT qualifier, specify the location where you want the root file
moved. For example:
RMU/MOVE_AREA/ROOT=DISK1:[DATABASE.TEST] PERSONNEL
3.5.3 The RMU/BACKUP/AFTER_JOURNAL /CONTINUOUS
/UNTIL="TOMORROW:+00:50" Command Fails for V3.1A and
VMS V5.3 or V5.4
When the RMU/BACKUP/AFTER_JOURNAL/CONTINUOUS
/UNTIL="TOMORROW:+00:50" command is performed, it works correctly
for V3.0B and VMS 5.1 or VMS 5.4 but fails with the following
errors in V3.1A and VMS V5.3 and VMS V5.4:
RMU-F-BADVALUE, invalid value "TOMORROW:+00:50"
LIB-F-AMBDATTIM, ambiguous date-time
The reason for this problem is that VMS did not make the library
routine LIB$CONVERT_DATE_STRING fully compatible with the $BINTIM
system service. Your time specification is acceptable to $BINTIM
but not to the library routine.
A workaround is to replace the part of the command "TOMORROW:+00:50:"
with the date for the following day and the command will work
correctly.
3.5.4 Shortened Form of RMU/RESTORE Command Does Not Work Properly
For V4.0 you cannot use RMU/RES to invoke the RMU/RESTORE command
as it conflicts with the RMU/RESOLVE command.
The workaround is to use RMU/REST as the shortened form of the
RMU/RESTORE command.
3-32 Known Problems, Restrictions, and Other Notes
3.5.5 Installing RMU with Privileges
After the installation, you might want to install RMU.EXE with the
VMS SYSPRV privilege. Doing so will make it possible for the RMU
image to check for applicable Rdb/VMS privileges whenever a user
enters RMU commands. If you do not install RMU.EXE with SYSPRV,
users will need VMS SYSPRV or BYPASS to execute any RMU commands.
To install RMU with SYSPRV, enter the following command:
$ INSTALL
INSTALL> ADD SYS$SYSTEM:RMU.EXE /OPEN/HEADER/PRIV=(SYSPRV)
This VMS INSTALL command requires the VMS CMKRNL privilege, be-
cause the RMU image is being installed with privileges.
If you have previously used the VMS Install utility to install
RMU.EXE, you should use the REPLACE command instead of the ADD
command on the INSTALL command line.
See the VAX Rdb/VMS Installation Guide or the VAX Rdb/VMS Guide
to Database Design and Definition for information concerning
privileges required to use RMU. See the VAX Rdb/VMS RDO and RMU
Reference Manual for more information about the RMU utility. See
the VMS Install Utility Manual for more information about the VMS
Install utility.
3.5.6 The Returned DCL $STATUS Is Inconsistent Between RMU Commands
There is an inconsistency between some RMU commands for the re-
turned $STATUS value to DCL. As shown in the following example,
some commands, such as the RMU/CONVERT command, return a sta-
tus reflecting the error, while others, such as the RMU/UNLOAD
command, always return SS$_NORMAL:
Known Problems, Restrictions, and Other Notes 3-33
$ RMU/CONVERT 'PERSONNEL.RDB'
%CLI-F-SYNTAX, error parsing 'COMMAND'
-CLI-E-ENTNF, specified entity not found in command tables
LOG $ WRITE SYS$OUTPUT $status
%X100310FC
$ write sys$output f$message(%X100310FC)
%CLI-F-SYNTAX, error parsing '!AS
$
$ RMU/UNLOAD/RMS_RECORD=FILE=NAMES PERSONNEL EMPLOYEES NAMES
%RMU-E-OUTFILDEL, Fatal error, output file deleted
-RDB-E-BAD_DB_FORMAT, PERSONNEL does not reference a database known to
Rdb
-RMS-E-FNF, file not found
$ WRITE SYS$OUTPUT $STATUS
%X10000001
This is a restriction in V4.0. The failure of RMU/UNLOAD to set
the exit status appropriately will be corrected in a future re-
lease of Rdb/VMS.
3.6 SQL/Services Known Problems and Restrictions
Section 3.6.1 through Section 3.6.12 contain known problems and
restrictions for SQL/Services.
3.6.1 SQL/Services Database Class Server Is Not Supported in Rdb/VMS
V4.0
The SQL/Services database class server is not supported in Rdb/VMS
Version 4.0 and should not be used when developing client applica-
tions. Database class execution server processes will be available
in the next release of Rdb/VMS. For Rdb/VMS Version 4.0, only the
default generic class server is supported.
Refer to the VAX Rdb/VMS Guide to Using SQL/Services for infor-
mation about how SQL/Services uses the generic class server to
process client application requests.
3-34 Known Problems, Restrictions, and Other Notes
3.6.2 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 an 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 Version 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 an 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.
3.6.3 Invalid Length Is 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 LIST OF BYTE VARYING option
of the CREATE TABLE statement. See the VAX Rdb/VMS SQL Reference
Manual for syntax details.
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 3.10.3
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 allo-
cating buffers, either by direct modification of the SQLLEN field
in the SQLDA data structure or by using the sqlsrv_sqlda_bind_
data routine. You will find information about the sqlsrv_sqlda_
Known Problems, Restrictions, and Other Notes 3-35
bind_data functional interface routine in the VAX Rdb/VMS Guide to
Using SQL/Services.
3.6.4 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.
3.6.5 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.
3.6.6 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.
3-36 Known Problems, Restrictions, and Other Notes
3.6.7 SQLSRV_ASCII_STRING Data Type Is Not Terminated with a NULL
Character
SQL/Services does not terminate with a trailing NULL character
variables declared as data type SQLSRV_ASCII_STRING. To use stan-
dard 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.
3.6.8 Filter Expressions Return Incorrect Results
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.
3.6.9 Using Group/System-Not Process-Logical Names in SQL/Services
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.
Known Problems, Restrictions, and Other Notes 3-37
Database file specifications are found in client API applications,
the SQL/Services sample application, or in configuration file
definitions.
3.6.10 API sqlsrv_fetch_many 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 effect until a later release of
SQL/Services.
3.6.11 SQLSRV$SRV Default Account Must Be Present for SQL/Services
to Start Automatically
The SQL/Services SQLSRV$SRV account is created during the Rdb/VMS
installation. At system startup time, SQL/Services executes the
SQLSRV$.EXE image in the SQLSRV$SRV account to start the communi-
cation server. If the SQLSRV$SRV account in which the communica-
tion server runs is accidentally deleted, you will have to install
Rdb/VMS again to re-create the SQLSRV$SRV account, and restart
SQL/Services manually with the following command:
$ @SYS$SYSTEM:SQLSRV$STARTUP.COM
3.6.12 DECnet Default File Access for SQL/Services
If the initial transfer of the client installation file fails,
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 ensure that the server node allows non-privileged access.
3-38 Known Problems, Restrictions, and Other Notes
3.7 CDD/Plus Restrictions
Section 3.7.1 through Section 3.7.5 describe known problems and
restrictions in CDD/Plus V4.2.
3.7.1 Minimum Supported Version of CDD/Plus
If you are running VMS Version 5.3, the minimum CDD/Plus version
number is V4.2.
If you are running VMS Version 5.4, the minimum CDD/Plus version
number is V4.2A. Running with earlier versions of CDD/Plus under
VMS Version 5.4 may lead to unexpected image exits and other
problems.
3.7.2 Using CDD/Plus with PERSONNEL.COM
If you build either the PERSONNEL or MF_PERSONNEL sample database
using the data dictionary, you will be prompted for the default
dictionary directory specification. The command procedure cur-
rently displays CDD$TOP as the default. However, if you run
CDD/Plus 4.2, which is now required with Rdb/VMS Version 4.0,
you must substitute the full dictionary directory specification
for CDD$TOP. CDD/Plus V4.2 does not recognize CDD$TOP anymore.
3.7.3 Some Views Are Not Accepted by VAX CDD/Plus V4.2
Views that contain subqueries are not accepted by VAX CDD/Plus
(V4.0, V4.1, and V4.2). Attempts to define these views will result
in the following error during the CREATE VIEW command:
Known Problems, Restrictions, and Other Notes 3-39
CREATE VIEW V5 AS
SELECT * FROM AAA
UNION
SELECT H1 FROM BBB
WHERE H1 = (SELECT G1 FROM CCC WHERE G1 > 1);
%CDD-E-BLRSYNERR, syntax error in BLR buffer at offset 0
The workaround is to attach to the database by using the FILENAME
qualifier before defining the view. This problem will be corrected
in a future version of VAX CDD/Plus.
3.7.4 GRANT and REVOKE Statements Generate MBLRSYNERR Message If
Attached by Path Name
The GRANT and REVOKE statements are not fully supported by
CDD/Plus V4.2. Attach by file name when changing access control.
3.7.5 Using CDD/Plus to Specify Collating Sequences
If you use CDO to specify a lowercase collating sequence name for
a field, Rdb/VMS incorrectly reports the following error if you
attempt to create a DOMAIN using this field:
%RDB-E-NO_META_UPDATE, metadata update failed
-RDMS-F-COLNOEXTS, there is no collating sequence named YOUR-NAME
in this database
You can work around this problem by using the CDO EDIT FIELD com-
mand and entering the collating sequence name again entirely
in uppercase characters. For instance, the collating sequence
"Danish" must be entered as "DANISH". This problem will be cor-
rected in a future version of Rdb/VMS.
3-40 Known Problems, Restrictions, and Other Notes
3.8 Restrictions Lifted by CDD/Plus Version 4.2
Section 3.8.1 describes known problems and restrictions lifted in
CDD/Plus V4.2.
3.8.1 Incompatibilities Between Rdb/VMS V4.0 and CDD/Plus That Have
Been Lifted by VAX CDD/Plus Version 4.2
Collating sequences, ascending and descending index attributes,
and view definitions containing the UNION operator, the WITH CHECK
OPTION, and the USER literal are now accepted by CDD/Plus Version
4.2.
3.9 Rdb/VMS Documentation Errors and Omissions
Section 3.9.1 through Section 3.9.22 describe documentation errors
and omissions for the Rdb/VMS documentation set.
3.9.1 Error in Table D-1, Fields in the SQLDA
The description of the SQLLEN subfield of SQLVAR is incorrect in
the V4.0 VAX Rdb/VMS SQL Reference Manual, Appendix D. The columns
in Table 3-1 provide the correct information.
Known Problems, Restrictions, and Other Notes 3-41
Table_3-1:_Fields_in_the_SQLDA_______________________________________
Field
Name:___Meaning_of_the_Field:_______Set_by:______Used_by:____________
SQLLEN A subfield of SQLVAR SQL unless Program to allocate
whose value indicates program storage with the
the length in bytes of resets, appropriate size for
the select list item or except the select list item
parameter marker. DECIMAL or or parameter marker.
For fixed-length data H_FLOAT,
types (TINYINT, SMALLINT, which can
INTEGER, QUADWORD, and only be
DECIMAL), SQLLEN is split set by
in half. user
o For TINYINT, SMALLINT,
INTEGER, and QUADWORD,
the low-order byte of
SQLLEN indicates the
length and the high-
order byte indicates
the scale (the number
of digits to the right
of the decimal point).
o For DECIMAL, the low-
order byte indicates
the precision and
the high-order byte
indicates the scale.
However, the SQLLEN
for a DECIMAL data
type can only be set
by the user; it is not
returned by SQL on a
DESCRIBE statement.
o List cursors cannot
return data in data
types that require a
scale factor.
For floating-point data
3-42 KnowneProblems,LRestrictions, and Other Notes
the length of the field
in bytes so that SQLLEN
== 4 indicates the REAL
data type and F_FLOAT,
SQLLEN == 8 indicates
DOUBLE PRECISION (G_
FLOAT), and SQLLEN ==
16 indicates the H_FLOAT
________data_type.___________________________________________________
3.9.2 Error in COL-DEFINITION Syntax Diagram
The col-definition syntax diagram shown in the Version 4.0 VAX
Rdb/VMS SQL Reference Manual SQL ALTER TABLE and SQL CREATE TABLE
statements is incorrect. The correct syntax appears in the follow-
ing diagram:
col-definition =
-> column-name ----+
|
+---------------+
|
+-+-> data-type ---+-+------------------+-+
| | | | | |
| +-> domain-name -+ +-> default-value -+ |
| |
| +---------------------------------------+
| |
| ++-------------------+-+-----------------------+-+->
| | | | | |
| ++> col-constraint ++ +-> sql-and-dtr-clause -+ |
| | | |
| +--------<--------+ |
| |
+--> COMPUTED BY value-expr -----------------------+
As the revised diagram shows, SQL allows you to use two or more
constraints together in the same column definition, as shown in
the following example:
SQL> CREATE TABLE EMPLOYEE (ID INTEGER UNIQUE NOT NULL);
You can specify a constraint name for each constraint you use, as
follows:
SQL> CREATE TABLE MANAGER
cont> (ID INTEGER UNIQUE CONSTRAINT A NOT NULL CONSTRAINT B);
Known Problems, Restrictions, and Other Notes 3-43
3.9.3 Cursors Containing ORDER BY Clauses Are Not Read-Only
In the VAX Rdb/VMS SQL Reference Manual, Section 6.22, "Usage
Notes", the fourth bullet states incorrectly that SQL considers
cursors containing the ORDER BY clause to be read-only. The SQL
interface to Rdb/VMS includes an extension to the ANSI standard
so that such cursors do allow rows to be updated and deleted
using the WHERE CURRENT OF clause as long as you do not update
the column used for ordering.
3.9.4 LIST OF BYTE VARYING Segment Size Correction
In the VAX Rdb/VMS SQL Reference Manual, Section 3.3.6, on the
LIST OF BYTE VARYING data type, states that the number of charac-
ters in a column of this type can be specified by a number n. The
maximum size for n is incorrectly specified as 65,535. The correct
maximum size is shown in Figure 3-1 of that manual. You can store
65,522 bytes in any LIST OF BYTE VARYING column, except for the
column that is the first segment of the list. The first segment of
the list has only 65,508 bytes of data storage available.
3.9.5 LIST OF BYTE VARYING in SQLTYPE Field of SQLDA
The VAX Rdb/VMS SQL Reference Manual, Table D-2, "Codes for the
SQLTYPE Field of SQLDA", incorrectly lists SEGMENTED STRING ID
as the data type for base value 508. The data type should be LIST
OF BYTE VARYING for base value 508. For example, for a DESCRIBE
statement that specifies a table cursor, SQL returns the value 509
(the base value 508 plus one to indicate that the datatype allows
null values). Note that this is true for all SQL data types, not
just the LIST OF BYTE VARYING data type.
3-44 Known Problems, Restrictions, and Other Notes
3.9.6 Value Returned by AVG Function
The VAX Rdb/VMS SQL Reference Manual, Section 3.6.1.3, describes
the behavior of the AVG function for interactive and precompiled
SQL only. In SQL Module Language and dynamic SQL, as in precom-
piled SQL, the value returned by AVG is rounded off to two decimal
places.
The value returned by the AVG function inherits its scale from
the data type of the column being averaged. If the column the AVG
function refers to has the SMALLINT data type, the result has no
scale factor.
3.9.7 NULL Characters May Terminate Character Data Type Columns
The VAX Rdb/VMS SQL Reference Manual, Section 3.3.7.2, lists
rules that apply to conversions between character data types.
The following bullet should be added to this list:
o If the column in a table is defined as CHAR or CHAR(1), the
target is not blank-filled, but is simply terminated with the
NULL character, (/0), generating a string of length 1.
If you wish to have the result left-justified and blank-filled
on the right, define the column as CHAR(n), where n is greater
than 1.
3.9.8 ORDER BY and LIMIT TO Clauses Are Missing from SQL Quick
Reference Guide
The syntax diagram for the DECLARE CURSOR statement in the SQL
Quick Reference Guide lacks subdiagrams for two clauses: the
limit-to clause and the order-by clause.
Diagrams and explanations for these clauses appear in the VAX
Rdb/VMS SQL Reference Manual section on the DECLARE CURSOR state-
ment.
Known Problems, Restrictions, and Other Notes 3-45
3.9.9 INSERT Statement Can Be Triggered
In the VAX Rdb/VMS SQL Reference Manual, Section 6.19, "CREATE
TRIGGER statement," the following statement was omitted from the
list of possible triggered statements:
o An INSERT statement
3.9.10 PRINT Statement Is Missing from Table 2-8
The PRINT statement was omitted from the VAX Rdb/VMS SQL Reference
Manual, Table 2-8. An "X" should appear in the Interactive and
Executable columns following the PRINT statement.
3.9.11 SQL$PRE FORTRAN AVG Function Returns Rounded Integer Value
The AVG function works correctly with interactive SQL, but the
value it returns with embedded SQL (FORTRAN) is a rounded integer
value and not a correct floating-point value.
This problem is about the data type of the AVG function, which
is just like division for ANSI. That is, the average or division
of exact numerics is also exact numeric and leaves the precision
/scale up to the implementation.
In both the AVG function and division cases, the scale is taken
from the dividend or the column being averaged. The precision is
the same as the dividend, or quad in the case of the AVG function.
The documentation will be made clearer on this point in the next
release.
3-46 Known Problems, Restrictions, and Other Notes
3.9.12 Error Exists in Privilege Table
Table 6-2 in the VAX Rdb/VMS Guide to Database Design and
Definition incorrectly states that VMS SYSPRV is required to suc-
cessfully execute the RMU/CONVERT command. This is not correct.
The VMS SYSPRV privilege is required only if RMU was not installed
with the VMS SYSPRV privilege.
3.9.13 Clarification of Constraint Semantics
Whenever a table column is restricted to certain values by the
use of a constraint it does not mean that null values also are
not allowed. In order not to allow a column to have null values
you should use the predicate COL IS NOT NULL in addition to other
restriction predicates in the constraint.
For example, the following constraint allows values 1, 2, 3, and
null:
CHECK ( COL IN (1, 2, 3) )
If you do not want COL to have null values use the following
constraint:
CHECK ( COL IN (1, 2, 3) AND COL IS NOT NULL)
3.9.14 Declaration of the Distributed Transaction Identifier (TID)
in FORTRAN Is Incorrect
In Section 5.3.2 and Example 5-3 of the VAX Rdb/VMS Guide to
Distributed Transactions, the declaration of the distributed
transaction identifier (TID) in FORTRAN is incorrect. To declare
the distributed TID in FORTRAN, use the following code:
INTEGER*4 DIST_TID(4)
Known Problems, Restrictions, and Other Notes 3-47
3.9.15 Using RDML and the Two-Phase Commit Protocol by Calling the
DECdtm System Service Calls Implicitly and Explicitly Is Not
Fully Documented
In the RDML Reference Manual and the VAX Rdb/VMS Guide to Using
RDO, RDBPRE, and RDML, using RDML and the two-phase commit pro-
tocol by calling the DECdtm system service calls implicitly and
explicitly is not fully documented. See Section 1.1 of the Release
Notes for a full description of using RDML with distributed trans-
actions.
3.9.16 REQUEST_HANDLE Clause in Rdb/ELN VAXELN Pascal Applications
Section 6.20 of the VAX Rdb/VMS RDML Reference Manual does
not describe the syntax for VAX Rdb/ELN applications to call
RDB$RELEASE_REQUEST in VAXELN Pascal programs. This manual should
be updated to either include the information or refer Rdb/ELN
users to Section 5.4.3 of the VAX Rdb/ELN Guide to Application
Development, where the syntax is documented as follows:
IF NOT RDB$RELEASE_REQUEST(RDB$MSG_VECTOR, REQ_HANDLE) THEN
RDML$SIGNAL_ERROR(ADDRESS(RDB$MSG_VECTOR));
3.9.17 Host Language Multipath Statements and RDML Update Statements
RDML may return unpredictable results when host language mul-
tipath statements (such as the C switch statement or the Pascal
case statement) are embedded in RDML update statements (STORE or
MODIFY). The problem occurs when a field is referenced but not
used at run time, because RDML assumes that any field mentioned
between MODIFY . . . END_MODIFY or STORE . . . END_STORE will be
updated.
In the following examples, if the program falls through to case
2 at run time, the FIRST_NAME field will be modified even though
FIRST_NAME is not referenced in case 2. Upon seeing the fields
referenced in case 1, RDML sets up a buffer for both FIRST_NAME
and LAST_NAME to be sent to the database. Because case 2 does not
3-48 Known Problems, Restrictions, and Other Notes
supply data for FIRST_NAME, RDML sends to the database whatever is
in the buffer for FIRST_NAME.
The following C code will cause unpredictable results:
FOR E IN EMPLOYEES WITH E.EMPLOYEE_ID = "00164"
MODIFY E USING
switch (i){
case '1':
strcpy (E.LAST_NAME,"Smith ");
strcpy (E.FIRST_NAME,"Andrew ");
break;
case '2':
strcpy (E.LAST_NAME, "Jones ");
break;
}
END_MODIFY;
END_FOR;
Likewise, the following Pascal code will cause unpredictable
results:
FOR E IN EMPLOYEES WITH E.EMPLOYEE_ID = '00164'
MODIFY E USING
case i of
1: E.LAST_NAME = 'Smith';
E.FIRST_NAME = 'Andrew';
2: E.LAST_NAME = 'Jones';
end;
END_MODIFY;
END_FOR;
When different fields are referenced in a multipath statement, the
RDML statement should be embedded in the host language multipath
statement as shown in the following examples.
Known Problems, Restrictions, and Other Notes 3-49
In C, the RDML statement should appear as follows:
FOR E IN EMPLOYEES WITH E.EMPLOYEE_ID = "00164"
switch(i) {
case '1':
MODIFY E USING
strcpy (E.LAST_NAME,"Smith ");
strcpy (E.FIRST_NAME,"Andrew ");
END_MODIFY;
break;
case '2':
MODIFY E USING
strcpy (E.LAST_NAME, "Jones ");
END_MODIFY;
break;
}
END_FOR;
In Pascal, the statement should be as follows:
FOR E IN EMPLOYEES WITH E.EMPLOYEE_ID = '00164'
case i of
1: MODIFY E USING
E.LAST_NAME = 'Smith';
E.FIRST_NAME = 'Andrew';
END_MODIFY;
2: MODIFY E USING
E.LAST_NAME = 'Jones';
END_MODIFY;
end;
END_FOR:
3-50 Known Problems, Restrictions, and Other Notes
3.9.18 C Host Variable Syntax Diagram
The C host variable syntax diagrams in the V4.0 RDML Reference
Manual are incomplete. They do not reflect the fact that the in-
direction operator (*) can be used in host variables. The correct
syntax appears as follows:
host-variable (in C) =
-+->---+- vax-name --+--+--------------------------->----------+--+->
| | | | | |
+-> * + | +---> . ---> field-identifier ----+ |
| | | |
| +---> [ ---> expression ---> ] --+ |
| | | |
| +---> "->" ----> host-variable ------+ |
| |
+----------<-------------------------<-------+
3.9.19 Method to Create Dummy AIJ or RUJ Files to Replace One of
These Missing Files Is No Longer Supported
In Section 9.3 of the VAX Rdb/VMS Guide to Database Maintenance
and Performance, information is presented describing what you
can do if you have lost your AIJ file to a disk drive problem. A
solution is documented suggesting you can create a dummy AIJ file
in the directory where the root file says it should be located
to get your database up and running again. Though not documented,
this method could also be used for missing RUJ files in versions
previous to V3.1. The risk involved in this method is that your
database may be left inconsistent and no message will display to
indicate this fact.
Beginning with V3.1 this technique is no longer supported because
it could leave your database inconsistent. Beginning with V4.0,
RMU/ALTER has new syntax (see Section 3.9.21 of the Release Notes)
to support this technique as a workaround. However, the database
will be marked as "eternally corrupt". The only method of clearing
Known Problems, Restrictions, and Other Notes 3-51
an "eternally corrupt" database state is to restore and recover
from a clean backup and AIJ file.
See Section 1.15 of the Release Notes for more information.
3.9.20 Improving the Performance of Import/Export Operations
When you are doing import/export operations, Digital recommends
that you use the following VMS SET command and choose a value that
is suitable for your particular import/export operation:
$ SET RMS_DEFAULT/EXTENT_QUANTITY=30000
By default, the RBR file extends for every 3 blocks in size.
This results in many extend operations. In this example, when you
specify a large value, such as 30,000 blocks, the RBR file only
invokes RMS Extend once per 30000 blocks. This command affects the
run-time performance of the EXPORT operation.
3.9.21 Changes to RMU/ALTER That Are Not Documented in V4.0
The following changes have been made to the RMU/ALTER utility and
are not documented in the V4.0 documentation:
o RMU/ALTER can be used to turn off journaling.
RMU/ALTER allows a user to turn off journaling if an AIJ file
is deleted, thereby allowing users to attach to the database. A
backup has to be performed to continue processing.
o RMU/ALTER can be used to remove RUJ files from the root file.
RMU/ALTER allows a user to remove RUJ files from the root file,
thus allowing access to the database. However, this action will
mark the database as "eternally corrupt". This will result in a
warning message in all future system management (RMU) functions
against this database. The database is either structurally
corrupt, logically corrupt (violates a constraint) or "user
data" corrupt (balance is $250.00 instead of $300.00)
3-52 Known Problems, Restrictions, and Other Notes
These changes permit users to attach to the database with the
realization that the database is corrupt in situations where the
RUJ files have been accidentally deleted. The database must be
restored and recovered from clean backups in order to guarantee
the consistency of the database contents.
The RdbALTER utility syntax to support these changes is:
o DISPLAY ROOT AIJ_FILENAME
o [DEPOSIT] ROOT AIJ_FILENAME = filename, where filename can be " "
o DISPLAY ROOT USER n RUJ_FILENAME
o [DEPOSIT] ROOT USER n RUJ_FILENAME = filename, where filename
can be " "
The only method of clearing the situation of an "eternally cor-
rupt" database is to:
o Restore and recover from a clean backup and AIJ file.
o Export and import the database (this could result in errors).
o Unload, re-create the database, and load the database (this
could result in data access errors).
The only way to ensure that all types of corruption are actually
handled is through the first option (restore and recover). The
other methods have the potential of still having "user data"
corruption. Note that the proper timing for changing the AIJ file
relative to an online incremental or full backup operation is
explained in detail in Section 9.4.3 in the VAX Rdb/VMS Guide to
Database Maintenance and Performance. Basically, the procedure
is to turn off after-image journaling, perform the backup of the
database, then turn on after-image journaling again, and continue
processing.
Known Problems, Restrictions, and Other Notes 3-53
3.9.22 Description of the Storage Algorithm for Storing Records in
Mixed Storage Areas When Target Pages Are Selected
Beginning with Rdb/VMS V3.0, the scheme for storing records was
optimized for mixed storage areas when this type of storage area
became available. When a target page is selected, the record is
stored if there is enough space to store it on that page. The
change from V2.3 (for uniform storage areas) to V3.0 (for mixed
storage areas) is that the SPAM page is not first checked to see
if the SPAM threshold entry indicates that the target page has
sufficient free space. Instead, to store data in mixed storage
areas when using a placement index or when storing duplicate
records, for example, pages are checked according to the following
algorithm:
1. Select a target page (t) and read it into the buffer as a
clump of pages (comprised of pages adjacent to the target
page). The exact number of pages depends on buffer size rela-
tive to the page size.
2. If the target page has space to store the record (using the
nominal (uncompressed) record size), the record is stored.
3. If the target page doesn't have enough space to store the
record, then the pages adjacent to the target page in the
buffer are checked for available space.
4. If a page in the buffer has space to store the record, the
record is stored.
5. If the pages in the buffer are full, fetch the SPAM page (S)
controlling the SPAM interval containing the target page.
6. Use the SPAM page to determine which pages are worth checking
for available space. The algorithm to find a page closest
to the target page that can accommodate the new entry is as
follows:
3-54 Known Problems, Restrictions, and Other Notes
-+----+----+----+----+----+----+----+----+----+----+----+----+----+----+--
|S | | | | | t | | | | | | | | |
-+----+----+----+----+----+----+----+----+----+----+----+----+----+----+--
^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^...
| | | | | | | | | | | |
10 8 6 4 2 1 3 5 7 9 11 13
(The numbers indicate the probing sequence for free space)
Check the pages closest to the target page for available space
until space is found or until the end of the SPAM interval for
the target page is reached.
7. If there is no available space in the SPAM interval (of the
target page), get the next SPAM page and perform a sequential
scan until a candidate page is found. Store the record if a
candidate page is found.
8. If no candidate page is found, repeat Step 7 until either
the end of the storage area is reached or a candidate page
is found.
9. If the end of the storage area is reached and a candidate page
is not found, start at the beginning of the storage area if the
pages in that region have not been examined.
10.If the entire storage area has been checked for free space and
none is found, the area is extended.
WARNING
Because this optimization scheme is used to store records
in mixed storage areas, for example, when you explic-
itly use a placement index or implicitly store duplicate
records, SPAM threshold settings are essentially ignored.
This means that SPAM threshold values cannot be used as
a fill factor to guarantee free space under these circum-
stances. Using SPAM thresholds in this manner is therefore
not recommended.
Known Problems, Restrictions, and Other Notes 3-55
What was not previously described was that the target page could
be selected explicitly using the PLACEMENT VIA INDEX option of the
storage map or implicitly for example, when more duplicates are
stored so each duplicate record could be stored in close proximity
to each other. SPAM thresholds are ignored under these circum-
stances. Users using SPAM thresholds as a fill factor to guarantee
free space on pages in V2.3 discovered that this guarantee was no
longer true for V3.0 and higher. This change was not documented
until V4.0 and what was documented was not completely accurate
in that even without the PLACEMENT VIA INDEX option, there was no
guarantee of free space.
In summary, the store functionality changed in V3.0 for mixed
storage areas to the detriment of users who relied on the use
of SPAM threshold settings to reserve or guarantee free space on
pages in the storage area. The V3.0 documentation was not updated
to reflect this changed behavior. For V3.1, the documentation in
Section 9.4.5.3.3 on page 9-48, in the 3rd paragraph of the VAX
Rdb/VMS Guide to Database Maintenance and Performance, did not
adequately describe this either and did not explain this storage
behavior change relative to SPAM threshold usage. For V4.0, the
documentation in Sections 11.5.2 and 16.12.4 of the VAX Rdb/VMS
Guide to Database Maintenance and Performance contains the warning
to users who use SPAM thresholds to guarantee free space that this
no longer works, but the description of the storage algorithms is
incomplete.
3.10 SQL/Services Documentation Errors and Omissions
Section 3.10.1 through Section 3.10.4 describe errors or omissions
in the VAX Rdb/VMS Guide to Using SQL/Services for Rdb/VMS Version
4.0.
3-56 Known Problems, Restrictions, and Other Notes
3.10.1 SQLSRV$DEFAULT_ACCESS Logical Name Is 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.
3.10.2 API sqlsrv_sqlca_sqlerrd Routine Is Omitted
SQL/Services has added a new API functional interface routine,
called sqlsrv_sqlca_sqlerrd, to return list cursor information
from the SQLCA.SQLERRD array. The routine was added late in the
engineering cycle and is not included in the VAX Rdb/VMS Guide
to Using SQL/Services for V4.0. 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 size of the largest
list entry.
o The sqlerrd_array[5] entry contains the total size of all list
entries.
VAX Format
SQLSRV$SQLCA_SQLERRD associate_id ,sqlerrd_array
Known Problems, Restrictions, and Other Notes 3-57
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].
Errors
SQLSRV_INVASC Invalid association identifier.
3.10.3 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 zero-based array
after successful execution of an sqlsrv_open_cursor routine for
list cursors. 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
3-58 Known Problems, Restrictions, and Other Notes
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.
3.10.4 SQL/Services sqlsrv_sqlda_bind_data Routine Error
The VAX Rdb/VMS Guide to Using SQL/Services incorrectly omits
the scale argument (scale) defined for the sqlsrv_sqlda_bind_data
functional interface routine and does not mention that the column
length (len) argument is unsigned. The functional prototype for
the routine should be documented as follows:
extern int sqlsrv_sqlda_bind_data(
SQLDA_ID sqlda_id,
short int colnum,
short int type,
unsigned short int len,
short int scale,
char *value,
short int *nullp
char *reserved);
The missing scale argument should be documented as follows:
scale
data type: word
access: write
mechanism: by value
The scale of the SQL/Services data type of the result column.
Known Problems, Restrictions, and Other Notes 3-59
3.11 Restrictions Retained from V3.1
This section begins with V3.1 restrictions pertinent to all users
and ends with restrictions specific to SQL, RDO, and RDML.
Therefore, the notes in this section may use different database
terms to mean the same thing. For example, some terms used by SQL
differ from terms used by other interfaces, such as RDO or RDML.
Table 1 in the Preface lists the different terms used.
3.11.1 Object Modules Created with V3.1 and V4.0 Are Not
Downward-Compatible
Due to enhancements in Rdb/VMS V3.1 and V4.0 (to support two-
phase commit), object modules created by the precompilers RDBPRE,
SQL$PRE, and the SQL module language compiler SQL$MOD are not com-
patible with previous versions of Rdb/VMS. Therefore, executable
images created using these object modules also will not function
correctly if run on a system with a previous version of Rdb/VMS
installed.
These precompilers now generate extra parameters for certain
calls. Attempts to move and execute these modules will result
in errors similar to the following:
%RDB-E-WRONUMARG, wrong number of arguments on call to facility
NOTE
Note that remote access through DECnet is not affected in
any way by these changes. This restriction only applies to
the movement of compiled and linked modules.
3.11.2 FIRST n Is Not Considered During Optimization
The strategies selected by the optimizer do not take into account
the potential reduction in the number of rows to be delivered that
might be stipulated by any FIRST n clause.
3-60 Known Problems, Restrictions, and Other Notes
3.11.3 Do Not Add Fields to Relations, Define Indexes, Triggers, and
Other Database Objects Based on System Relation Fields
You should not add fields to relations based on system relation
fields. In addition, you should not define indexes, triggers, and
other database objects on any system relation fields.
3.11.4 Performance Considerations for Using VARYING STRING or
COLLATING SEQUENCE Attribute for Index Keys
Database designers should be aware of the following optimizer
restrictions concerning references to fields with the COLLATING
SEQUENCE attribute, or fields whose data type is VARCHAR (VARYING
STRING). These restrictions affect performance with respect to I/O
operations.
The optimizer Index Only Retrieval and Key-Only Boolean strategies
are disabled if any field in the index has a collating sequence
defined, or is a VARYING STRING field. These two retrieval strate-
gies require Rdb/VMS to return data stored in the index node, or
perform comparisons based on the index node key fields, thus sav-
ing I/O operations to the data record. However, the original user
data cannot be reconstructed from the encoded index if these at-
tributes are used. Therefore, the optimizer forces a Retrieval by
Index strategy instead, which requires I/O operations to the data
record.
These restrictions may affect the choice of data type for fields
to be used in indexes. For example, PRODUCT_ID, which has a data
type of CHAR(20), is part of an index P_INDEX. A query that uses
STARTING WITH against PRODUCT_ID allows the user to enter a par-
tial product code. It then fetches the matched PRODUCT_ID field
for display to the user, but does not fetch any other fields. This
query would normally be optimized to reference the index PRODUCT_
ID_IX only (that is, using an Index Only Retrieval strategy).
However, if the field were defined as VARCHAR(20), the opti-
mizer would be required to reference the data record to fetch
the PRODUCT_ID. This will add some extra I/O operations to the
Known Problems, Restrictions, and Other Notes 3-61
translation query. Therefore, CHAR (TEXT) data type may be prefer-
able to VARCHAR (VARYING STRING) if the field is involved in index
retrieval.
The following example demonstrates this simple case. Note that the
optimizer strategy as displayed when the RDMS$DEBUG_FLAGS logical
is set to "S" has been inserted after each query.
SQL> SHOW TABLE PRODUCTS
Columns for table PRODUCTS:
Column Name Data Type Domain
----------- --------- ------
PRODUCT_ID_V VARCHAR(20) PRODUCT_ID_V
PRODUCT_ID_T CHAR(20) PRODUCT_ID_T
.
.
.
Indexes on table PRODUCTS:
P_INDEX_T with column PRODUCT_ID_T
duplicates are allowed
type is sorted
P_INDEX_V with column PRODUCT_ID_V
duplicates are allowed
type is sorted
.
.
.
SQL>
SQL> SELECT PRODUCT_ID_T
cont> FROM PRODUCTS
cont> WHERE PRODUCT_ID_T STARTING WITH "AAA";
Conjunct Get Index only retrieval
Retrieval by index of relation PRODUCTS Index name P_INDEX_T
00000001 Segments in low Ikey 00000001 Segments in high Ikey
0 rows selected
3-62 Known Problems, Restrictions, and Other Notes
SQL>
SQL> SELECT PRODUCT_ID_V
cont> FROM PRODUCTS
cont> WHERE PRODUCT_ID_V STARTING WITH "AAA";
Conjunct Get Retrieval by index of relation PRODUCTS
Index name P_INDEX_V 00000001 Segments in low Ikey
00000001 Segments in high Ikey
0 rows selected
SQL>
SQL> COMMIT;
NOTE
Most queries use indexes as a fast access method to refer-
ence rows (records) of data so that an I/O operation to the
data record will normally be required.
3.11.5 Sorting or Implied Sorting for Projection on a Dbkey Is Not
Worthwhile
Sorting (or any implied sorting for projection) will not sort
dbkeys in such a way that the dbkeys can be used to retrieve
records in sequential order.
The reason for this behavior is that dbkeys are treated as fixed-
length text strings of 8 * n bytes, where n in the number of ta-
bles concerned (may be one or more for views). Therefore, sorting
dbkeys will order the text bytes according to the default ASCII
collating sequence.
3.11.6 Many Attaches to and Detaches from the Same or Multiple
Databases While Using Search Lists to Point to the Database
Use Up I/O Channel Quota
Continually attaching to or detaching from the same database,
or to or from multiple databases that are referred to by log-
ical names that contain search lists, will cause your process
Known Problems, Restrictions, and Other Notes 3-63
eventually to exceed its channel quota, and a message such as
%SYSTEM-E-NOIOCHAN will be issued.
This problem may occur frequently while you are using a RALLY
application and search lists, because RALLY can attach to or
detach from a database quite frequently while the application
is running. This problem can occur elsewhere.
The problem occurs because one of the logical names that is used
to point to the database is a search list. The logical name is
SPACE$DB, which is defined to be:
"SPACE$DB" [exec] = "$1$DUA12:" (LNM$SYSTEM_TABLE)
= "$1$DUA5:"
If you remove this search list, you do not have the problem.
3.11.7 Do Not Disable ASTs If You Want to Access a Database Remotely
An Rdb/VMS routine never completes if asynchronous traps (ASTs)
are disabled and Rdb/VMS is attempting to access a database across
DECnet.
The remote interface for Rdb/VMS requires the use of ASTs in order
to send messages asynchronously. The remote interface is a client
/server model. Each program issues an AST read on the network
channel that connects them. If a message is delivered by DECnet,
the AST ensures that the message is handled immediately. If the
message is a normal database message, a new AST is issued and the
message that was received is processed normally.
The server has the capability of serving multiple remote requests;
this would not be possible with synchronous communication.
3-64 Known Problems, Restrictions, and Other Notes
3.11.8 Unexpected Setting of the NULL Attribute After an IMPORT
Operation
Section 2.2.2 of the Rdb/VMS V3.0A Release Notes suggests using
the RDO EXPORT WITH NOEXTENSIONS statement if you need to ex-
port and have the import operation create a single-file database.
However, this type of export file does not include enough infor-
mation to exactly rebuild the database contents for the NULL flag
(MISSING VALUE information) for each field (or the SQL equiva-
lent). This information is often required by applications and may
cause apparent database inconsistencies after an import operation.
See Section 3.13.2 for the effects of this problem on exporting
CDD/Plus dictionary databases.
This problem only occurs for fields that are defined without the
MISSING_VALUE attribute. This is often the case when the definer
assumes the use of the Rdb/VMS default missing value literals
(spaces for text fields, "17-NOV-1858 00:00:00.00" for dates, and
zeros for numeric fields). The IMPORT statement compares the field
values with the defined missing value for the field and sets the
NULL flag upon finding a match. If the definer did not specify a
MISSING_VALUE string, then the field is not set to NULL.
This means that after an IMPORT operation, queries testing for
IS NULL (SQL), or IS MISSING (RDO), or using the DSRI PARAMETER2
feature may retrieve different records or detect fields as not
null that are different from what might be expected previous to
the IMPORT operation or when the database was first created.
The RDO EXPORT WITH EXTENSIONS statement can be used to work
around this problem. The extensions to the original export proto-
col now record the setting of the NULL flags for each field.
In general, Digital recommends the use of the EXPORT WITH
EXTENSIONS statement in all cases, unless the target system is
Rdb/ELN or a version of Rdb/VMS prior to Version 3.1.
Known Problems, Restrictions, and Other Notes 3-65
3.11.9 IMPORT Statement Generates Bugcheck Dumps If the Index
Definition Fails
In versions of the IMPORT statement prior to Rdb/VMS V3.1, in-
dexes were created in EXCLUSIVE WRITE transactions, even if the
batch-update option was used. This meant that large recovery-unit
journal (RUJ) files could be created on some import operations.
In Rdb/VMS V3.1, indexes are defined by default within batch-
update transactions to prevent the creation of these large RUJ
files. When a failure occurs during a batch-update transaction, it
cannot be rolled back, and this leaves the database in a corrupt
state. In this case, the current implementation of the IMPORT
statement generates a bugcheck dump rather than simply reporting
the error.
If this happens, Digital suggests the use of the IMPORT NOBATCH_
UPDATE option so that failures like this will be reported cor-
rectly, and only the offending index definition will be lost.
Digital is investigating ways to report this error, rather than
generating a bugcheck dump when BATCH_UPDATE is being used.
If a bugcheck dump is generated, the following DCL command can be
used to extract the reason for the failure:
$ SEARCH/WINDOW RDSBUGCHK.DMP "** Ex"
***** Exception at 0030E307 : RDMS$$KOD_CREATE_HASHED_INDEX + 00000286
%RDB-E-NO_DUP, index field value already exists; duplicates not allowed for
CUST_ACCESS_NUMBER_KEY
In many cases, the exception will indicate the reason for the
index failure. Some common reasons are:
o An index is defined as part of the IMPORT statement that re-
quires a UNIQUE (NO DUPLICATES ALLOWED) index when duplicates
in fact do exist (as in the previous example).
User action: Change the index definition to allow duplicates.
3-66 Known Problems, Restrictions, and Other Notes
o A hashed index is defined in the database, but the storage area
has had its characteristics changed during the import operation
from mixed page format to uniform page format.
User action: None-the import operation should not change the
storage area page format characteristic.
o During the record sort for the index build, the VMS Sort util-
ity (SORT) exceeds the disk quota or fails to create a work
file.
User action: Place the sort work files on a disk with suffi-
cient disk quota. For more information see the VMS Sort/Merge
Utility Manual.
o Storage areas of different types are referenced by the same
storage map.
User action: Ensure that all storage areas referenced by a
storage map are the same type, either uniform or mixed page
format.
3.11.10 IMPORT Statement Failed to Complete Index Definition with
Users Attached to the Database
There was a problem caused by users attaching to the database be-
fore an IMPORT statement was complete. In that event, the Rdb/VMS
displayed the following messages:
RDO-E-NOIDXREV, unable to import index indexname
RDB-E-LOCKCONFLICT, request failed ..
RDB-E-NOMETAUPDATE, ...
RDMS-F-LCKCONFLCT, lock conflict on client.
These messages appeared on two of the indexes (both sorted), and
the IMPORT statement failed to create those indexes.
The behavior of the IMPORT statement requires that no other users
attach to the database while it is being imported, or alternately,
that the indexes are defined in a separate operation.
Known Problems, Restrictions, and Other Notes 3-67
3.11.11 Using LIB$DT_INPUT_FORMAT to Change Date Input Format
Sometimes Causes Access Violation
There is a known problem with the VMS V5.3 Run-Time Library func-
tion LIB$CONVERT_DATE_STRING. This is the routine Rdb/VMS uses
in precompiled programs, SQL module language, and the RDO and SQL
interactive interfaces to convert dates to internal format. When
the logical name LIB$DT_INPUT_FORMAT is used to change the date
input format, the run-time library sometimes causes an access vi-
olation that probably prevents the precompiler or module language
compiler from continuing, but does not cause any loss of data from
interactive SQL. The access violation is shown in the following
example:
%SQL-F-DATCONERR, Data conversion error
-SYSTEM-F- ACCVIO, access violation, ...
The problem is in LIB$CONVERT_DATE_STRING, in the logic that
handles meridian indicators. The only workaround is to use a
different date format.
3.11.12 Operations on F-Floating Data Round to Whole Numbers
When Rdb/VMS performs any arithmetic addition, and either or both
of the operands is in F-floating format, the result is rounded to
the nearest whole number. For example, if the statistical function
TOTAL is used on a field (or the SQL equivalent) defined as F-
floating, and if data with decimal values is stored in that field,
the result is rounded to a whole number. If the F-floating field
contained the values 4.51 and 5.01, TOTAL would return the value
10, rather than 9.52 (the actual sum).
To avoid this rounding of floating-point results, use another data
type (such as quadword) for the fields rather than the F-floating
data type.
3-68 Known Problems, Restrictions, and Other Notes
3.11.13 Rdb/VMS Interaction with Data Distributor V2.1 May Generate
Bugcheck Dumps
Under certain circumstances, Rdb/VMS generates bugcheck dumps
when interacting with VAX Data Distributor V2.1. Typically, this
situation occurs when you execute an RDO STORE, MODIFY, or ERASE
statement (or their SQL equivalents), and have many Boolean ex-
pressions on transfers for one relation. The exception for the
bugcheck is usually RDMS$$EXECUTE_ECON. The problem is that the
amount of code generated to test the Boolean expressions for the
relation is greater than 32767 bytes. A BRW instruction is used to
exit the Boolean comparison, and the BRW has a range of -32768 to
32767.
The following workarounds are suggested.
o Use fewer transfers on the relation, or use fewer Boolean
expressions.
o Create a dummy transfer to transfer the entire relation to a
local database. This will cause Rdb/VMS to ignore the Boolean
comparison, as all records must be journaled.
3.11.14 Batch-Update Transactions Can Cause a Bugcheck Dump to Occur
If an Index Definition Fails
A batch-update transaction that attempts to define an index but
fails can cause a bugcheck dump to occur. An example is a batch-
update transaction that defines an index that specifies DUPLICATES
NOT ALLOWED when, in fact, there are duplicates. The transaction
fails, causing a bugcheck dump to occur, corrupting the database.
This situation can also occur within an IMPORT statement. You
must be certain when attempting batch-update transactions in such
cases that the definitions are correct for the set of data you are
using. See Section 3.11.9 for more information about the IMPORT
statement.
Known Problems, Restrictions, and Other Notes 3-69
3.11.15 Rdb/VMS Logical Name, RDMS$BIND_WORK_VM, Has an Upper Limit
of 65,000 Bytes
The Rdb/VMS logical name, RDMS$BIND_WORK_VM, has an upper limit
of 65,000 bytes. Specifying values greater than 65,000 bytes can
produce unpredictable results.
3.11.16 Reserving a Table in Exclusive Mode May Prevent Operations
from Being Performed on Other Tables in the Same Storage
Area
Reserving a table in the exclusive mode may prevent you from
performing some operations on other tables in the same storage
area.
The workaround is to reserve the tables in the shared mode, which
enables the snapshot mechanism.
3.11.17 There Is a Problem Defining COLLATING SEQUENCE IS NORWEGIAN
NORWEGIAN
There is a problem in the collating sequence file currently pro-
vided by the VMS kit for the Norwegian language.
The following example produces a bugcheck dump:
CREATE SCHEMA ... COLLATING SEQUENCE IS NORWEGIAN NORWEGIAN;
3-70 Known Problems, Restrictions, and Other Notes
You can correct this problem on your system by doing the follow-
ing:
1. Use the command NCS/OUT=NORWEGIAN/EXT=NORWEGIAN to obtain a
file, NORWEGIAN.NCS. This file contains the following assign-
ments:
..............................................................
NORWEGIAN = CS(
SEQUENCE = (%X00-"N", "Ñ", "O"-"Z", "Æ", "Ö", "Å", "["-"`", "{"-"¿", %XD0,
%XDE, %XF0, %XFE-%XFF),
MODIFICATIONS=("a"-"z" = "A"-"Z", "À"-"Ã" = "A", "Ç" = "C", "È"-"Ë" = "E",
"Ì"-"Ï" = "I", "Ò"-"Õ" = "O", "Ø" = "Ö", "Ù"-"Û" = "U", "Ü"-"Ý" = "Y"
"à"-"ã" = "A", "Å"-"æ" = "Å"-"Æ", "ç" = "C", "è"-"ë" = "E",
"ì"-"ï" = "I", "ñ" = "Ñ", "ò"-"õ" = "O", "ö" = "Ö", "ø" = "Ö",
"ù"-"û" = "U", "ü"-"ý" = "Y", "Ä" = "AE", "×" = "OE", "ß" = "SS",
"ä" = "Ä", "÷" = "×", "" < %X00))
+ CS( SEQUENCE = (%X00-"A", "À"-"Ä", "B"-"C", "Ç", "D"-"E", "È"-"Ë",
"F"-"I", "Ì"-"Ï", "J"-"N", "Ñ", "×", "O", "Ò"-"Ö", "P"-"R", "ß",
"S"-"U", "Ù"-"Ü", "V"-"Y", "Ý", "Z", "Æ", "Ø", "Å", "["-"`", "{"-"¿",
%XD0, %XDE, %XD0, %XFE-%XFF),
MODIFICATIONS=("a"-"z" = "A"-"Z", "à"-"ï" = "À"-"Ï", "ñ"-"ý" = "Ñ"-"Ý"))
+ REVERSE(_NATIVE);
..............................................................
2. Correct the assignment: "Ä" = "AE" to "Ä" = "Æ".
3. Insert or replace the corrected definition in your NCS.NLB.
One way to insert the corrected definition is to create a file,
NORWEGIAN_CORRECTED.NCS, that contains a corrected sequence:
Known Problems, Restrictions, and Other Notes 3-71
..............................................................
NORWEGIAN_CORRECTED = CS(
SEQUENCE = (%X00-"N", "Ñ", "O"-"Z", "Æ", "Ö", "Å", "["-"`", "{"-"¿", %XD0,
%XDE, %XF0, %XFE-%XFF),
MODIFICATIONS=("a"-"z" = "A"-"Z", "À"-"Ã" = "A", "Ç" = "C", "È"-"Ë" = "E",
"Ì"-"Ï" = "I", "Ò"-"Õ" = "O", "Ø" = "Ö", "Ù"-"Û" = "U", "Ü"-"Ý" = "Y"
"à"-"ã" = "A", "Å"-"æ" = "Å"-"Æ", "ç" = "C", "è"-"ë" = "E",
"ì"-"ï" = "I", "ñ" = "Ñ", "ò"-"õ" = "O", "ö" = "Ö", "ø" = "Ö",
"ù"-"û" = "U", "ü"-"ý" = "Y", "Ä" = "Æ", "×" = "OE", "ß" = "SS",
"ä" = "Ä", "÷" = "×", "" < %X00))
+ CS( SEQUENCE = (%X00-"A", "À"-"Ä", "B"-"C", "Ç", "D"-"E", "È"-"Ë",
"F"-"I", "Ì"-"Ï", "J"-"N", "Ñ", "×", "O", "Ò"-"Ö", "P"-"R", "ß",
"S"-"U", "Ù"-"Ü", "V"-"Y", "Ý", "Z", "Æ", "Ø", "Å", "["-"`", "{"-"¿",
%XD0, %XDE, %XD0, %XFE-%XFF),
MODIFICATIONS=("a"-"z" = "A"-"Z", "à"-"ï" = "À"-"Ï", "ñ"-"ý" = "Ñ"-"Ý"))
+ REVERSE(_NATIVE);
..............................................................
4. Issue the VMS command NCS/INS NORWEGIAN_CORRECTED.
This command inserts the corrected sequence in your NCS.NLB.
You may then choose to replace the erroneous sequence in your
NCS.NLB with this corrected one.
3.11.18 Rdb/VMS and VMS Debugger Interaction
There are often reports of unexpected interaction between Rdb/VMS
and the VMS Debugger when application programmers are debugging
code. Programs running under the control of the debugger, usually
with a watchpoint enabled, may receive one of the following error
messages:
%RDB-F-BAD_DB_HANDLE, invalid database handle
%RDB-F-BAD_REQ_HANDLE, invalid request handle
%RDB-F-BAD_TRANS_HANDLE, invalid transaction handle
%RDB-F-NOARGACC_WRITE, database facility cannot write to argument !UL
%RDB-F-NOARGACC_READ, database facility cannot read argument !UL
3-72 Known Problems, Restrictions, and Other Notes
The application runs as expected if the application is modified
slightly or when no trace or watchpoints are established in the
debugger.
To explain what is happening in Rdb/VMS, it helps to understand
how the VMS Debugger implements the SET WATCH command, and this
involves some understanding of the VMS operating system.
Pages in the working set allow access to four security levels:
o Kernel mode-the most privileged
o Executive mode-most Record Management System (RMS) code, the
Rdb/VMS executive, most system services
o Supervisor mode-mostly DCL
o User mode-most user-written application code
When a watchpoint is established, the VMS Debugger changes the
protection of the page in P1 space so that the image running in
user mode will not be able to write to the specified address.
When the page is accessed by the application, an exception occurs
that is handled by the debugger's exception handler. The address
of the access violation is examined to see if it is being watched
and, if so, the debugger executes the required trace actions and
executes the failed instruction again.
Privileged code, such as the Rdb/VMS executive and the VMS system
services, performs operations on behalf of nonprivileged users
running in user mode. For security reasons, code running in execu-
tive and kernel mode must ensure that the memory locations passed
from the user application not only exist, but can also be accessed
from the user's current (usually nonprivileged) mode. The VMS in-
struction set provides two instructions to check access rights to
memory locations-PROBER (probe for read access) and PROBEW (probe
for write access).
Known Problems, Restrictions, and Other Notes 3-73
The Rdb/VMS executive uses these instructions to ensure that all
application memory locations can be accessed at the appropriate
security level (sometimes access must be at user mode). If the ac-
cess fails, Rdb/VMS will signal an error. This checking completely
bypasses the exception and trapping required by the debugger.
Therefore, the application's behavior is different because of the
changed page protections.
Usually the programmer is not actually watching any Rdb/VMS vari-
ables, such as transaction and request handles, so why does
Rdb/VMS signal an error? The protection is at the page level,
which is rather coarse, and the location being traced happens to
fall on the same page as the Rdb/VMS variables.
It is possible for a knowledgeable programmer to avoid this prob-
lem by defining a large array so that the data locations are
pushed onto separate pages. This is the reason the error mes-
sage often disappears after editing and recompiling the code or
simply recompiling with a /NOOPTIMIZE qualifier.
For more information, see the sections on watchpoint options, and
on how the debugger controls program execution in the VMS Debugger
Manual.
3.11.19 RDB$DBKEY_LENGTH System Field Incorrect for Certain Views
Rdb/VMS will assign an incorrect value to the RDB$DBKEY_LENGTH
field of the RDB$RELATIONS system relation for views defined using
functions.
This problem can cause a GET or PRINT operation of such a stream
from RDO to produce REQ_SYNC errors due to an improper prior FETCH
statement using the wrong dbkey length.
3-74 Known Problems, Restrictions, and Other Notes
3.11.20 Problem with the Use of Virtual Memory
There was a problem in the way virtual memory was allocated and
freed within Rdb/VMS. This problem showed up in certain appli-
cations that repeatedly recompiled identical information. These
applications would eventually fail because they had exhausted
their virtual memory quotas (VIRTUALPAGCNT).
A workaround to the problem, on the system experiencing the prob-
lem or in the login.com of the users experiencing the difficulty,
is to define the following logical name:
DEFINE RDMS$BIND_VM_SEGMENT 1
This definition will cause Rdb/VMS to execute a different code
path in its handling of virtual memory.
3.11.21 Using the /USERS_MAX and /NODES_MAX Qualifiers with the
RMU/RESTORE Command Requires Both Qualifiers on the First
Line of DCL Input
When the /USERS_MAX and /NODES_MAX qualifiers are used with the
RMU/RESTORE command and both appear on the second or subsequent
lines in the DCL input command, both qualifiers have been shown to
fail for both single-file and multifile databases.
Both of these qualifiers must be on the first line of DCL input or
the qualifiers will not be applied.
Avoid using these qualifiers when using the RMU/RESTORE command to
restore a single-file database. Instead, use the NUMBER OF USERS
clause and the NUMBER OF VAXCLUSTER NODES clause with the SQL or
RDO IMPORT statement. For multifile databases, use the NUMBER OF
USERS clause and the NUMBER OF VAXCLUSTER NODES clause within the
SQL ALTER SCHEMA or the RDO CHANGE DATABASE statement to change
these values.
Known Problems, Restrictions, and Other Notes 3-75
3.11.22 A Snapshot File Name, File Type, or Version Number Cannot Be
Changed for Single-File Databases
If you change the file name, file type, or version of a snap-
shot file and then try to access the database through the RDO
interface, you get the following error messages:
RDO> DATA FILE TESTRDB
%RDB-F-SYS_REQUEST, error from system services request
-RDMS-F-FILACCERR, error opening storage area file
DUA0:[TEST.RDB]TESTRDB.SNP;1
-RMS-E-FNF, file not found
RDO>
The name of the snapshot file in a single-file database is always
derived from the root file name. Users must not change the file
name, file type, or version of the snapshot file for a single-file
database.
It is possible to use logical names to relocate the snap-
shot file to another directory or device. The RMU/RESTORE
/SNAPSHOT=(FILE= . . . ) command permits this relocation. Users
must define the appropriate logical name to relocate the snapshot
file.
If you experience this restriction, simply rename the snapshot
file (using the VMS RENAME command) to its correct file name, file
type, and version number.
3.11.23 There Is a 17-Character Limit for File Names When You Back
Up Databases to Tape
When you back up your database to magnetic tape, Digital recom-
mends that you supply a name for the backup file that is 17 or
fewer characters in length. File names longer than 17 characters
may be truncated. The VMS operating system supports four file-
header labels: HDR1, HDR2, HDR3, and HDR4. In HDR1 labels, the
file identifier field contains the first 17 characters of the file
name you supply. The remainder of the file name is written into
3-76 Known Problems, Restrictions, and Other Notes
the HDR4 label, provided that this label is allowed. If no HDR4
label is supported, a file name longer than 17 characters is trun-
cated. See the information on file-header labels in the Guide to
VMS Files and Devices.
The following RMU commands are acceptable:
RMU/BACKUP/REWIND/LABEL=TAPE MF_PERSONNEL MUA0:WEDNESDAYS_BACKUP.
RMU/RESTORE/REWIND/LABEL=TAPE MUA0:WEDNESDAYS_BACKUP.
The terminating period (.) for the backup file name is not
counted as a character, and the default file type of RBF is as-
sumed. Therefore, VMS interprets the file name as WEDNESDAYS_
BACKUP, which is 17 characters in length.
The following RMU commands are not acceptable:
RMU/BACKUP/REWIND/LABEL=TAPE MF_PERSONNEL MUA0:WEDNESDAYS_BACKUP
RMU/RESTORE/REWIND/LABEL=TAPE MUA0:WEDNESDAYS_BACKUP
Because no terminating period (.) is supplied, VMS supplies a
period and a file type of RBF, and interprets the backup file name
as WEDNESDAYS_BACKUP.RBF, which is 20 characters in length.
3.11.24 RMU/DUMP/BACKUP Command Specifying a Value of 1 or 2 for the
/ACTIVE_IO Qualifier Causes the AIJ Dump to Stall
The RMU/DUMP/BACKUP command with an /ACTIVE_IO qualifier of either
1 or 2 does not seem to work; the process stalls in an LEF state.
Values 3 through 5 work properly. The two commands that fail are
shown here:
$ RMU/DUMP/BACKUP/REWIND /ACTIVE_IO=1 TEST$TAPE:MF_PERSONNEL.RBF
$
$ RMU/DUMP/BACKUP/REWIND /ACTIVE_IO=2 TEST$TAPE:MF_PERSONNEL.RBF
Known Problems, Restrictions, and Other Notes 3-77
The problem is not that the /ACTIVE_IO qualifier does not work,
but rather, that there are not enough buffers available to read
in the entire root file from the backup file before the AIJ dump
operation begins. If the /ACTIVE_IO qualifier specifies a value
that is too low, the root file cannot be buffered and the AIJ dump
stalls.
3.11.25 RMU/SHOW STATISTICS Command Does Not Record All Statistics
in the Binary File
The following restrictions were not previously documented for
the RMU/SHOW STATISTICS command. When you use the RMU/SHOW
STATISTICS/OUTPUT command, the following information is not
recorded in the binary file, and therefore cannot be replayed
using the /INPUT qualifier:
o The information contained in the Stall Messages screen
This information is highly dynamic, and is not recorded in the
binary file.
o Individual storage area I/O statistics
Currently all the file I/O statistics are combined into a
single gross value for the database.
Digital recognizes that individual file statistics are consid-
erably more useful than a single gross value for tuning in a
multifile database. The RMU/SHOW STATISTICS command will be en-
hanced in a future release of Rdb/VMS to record I/O statistics
for individual storage areas.
3-78 Known Problems, Restrictions, and Other Notes
3.11.26 Dumping the AIJ File Is Incompatible with Normal Usage
Dumping the AIJ file from one process and writing to the AIJ file
from another process are mutually exclusive actions within the
current Rdb/VMS architecture.
For example, if you try to modify a record in a database for which
after-image journaling is enabled while someone else is dumping
the AIJ file with the RMU/DUMP/AFTER command, then it is possible
for your transaction to cause a bugcheck dump when it attempts to
access the AIJ file:
***** Exception at 001F5796 : AIJ$OPEN + 000002C9
%RDMS-F-FILACCERR, error opening after-image journal file DUA0:[SMITH.RDB]M
-SYSTEM-W-ACCONFLICT, file access conflict"
To prevent this error from occurring, ensure that there are no
active users updating the database before issuing an RMU/DUMP
/AFTER command, or make a copy of the AIJ file and dump that copy.
3.11.27 RMU/RESTORE Command May Initialize the SPAM Thresholds in
One or More Storage Areas
The RMU/RESTORE command may initialize the SPAM thresholds for
some data pages of some uniform areas to values that are not
acceptable to the RMU/VERIFY command. This occurs when some of the
data pages in a logical area are restored before the logical area
definition (Area Inventory). This is not a frequent occurrence,
and when it does happen, the consequences are usually cosmetic
(the RMU/VERIFY command issues a warning message for each page
affected). However, if many pages are affected, the volume of
warnings may cause a real problem to be overlooked. Moreover, in
some cases, this may result in additional I/O operations when new
data is stored in an affected relation.
As a workaround, RMU now offers a REPAIR command that reconstructs
the SPAM pages in one or more storage areas. This corrects the
condition caused by the RMU/RESTORE command as well as other SPAM
page corruptions.
Known Problems, Restrictions, and Other Notes 3-79
The RMU/REPAIR command has the following syntax:
RMU/REPAIR [/AREA=(area-name,...)] root_filename
The default for the /AREA qualifier is an asterisk parendchar(*),
which means all the storage areas.
The RMU/REPAIR command requires VMS SYSPRV privilege. It also
requires complete and exclusive access to the database.
3.11.28 Correction to the Usage Note on Constraints with the CREATE
TABLE Statement
A usage note on page 4-145 of the VAX Rdb/VMS SQL Reference Manual
for Version 3.1 incorrectly states that "transactions that create
tables containing constraints must have EXCLUSIVE access to the
database."
In fact, Rdb/VMS only requires exclusive access to all the tables
referenced by the constraint, not to the entire database.
3.11.29 Using Rdb/VMS from a VMS Detached Process
Rdb/VMS V3.1 documentation omits necessary detail on running
Rdb/VMS from a detached process.
Applications run from detached processes must ensure that the
VMS environment is established correctly before running Rdb/VMS,
otherwise Rdb/VMS will not execute.
Attempts to attach to a database and execute an Rdb/VMS query from
applications running as detached processes will result in an error
similar to the following:
%RDB-F-SYS_REQUEST, error from system services request
-SORT-E-OPENOUT, error opening !AS as output
-RMS-F-DEV, error in device name or inappropriate device type for operation
The problem occurs because a detached process does not normally
have the logical names SYS$LOGIN, or SYS$SCRATCH defined.
3-80 Known Problems, Restrictions, and Other Notes
There are two methods that can be used to correct this:
o Solution 1:
$ RUN/DETACH/AUTHORIZE SYS$SYSTEM:LOGINOUT/INPUT=RUN-PROCEDURE
The DCL command procedure RUN-PROCEDURE runs the ACCOUNTS
application:
$ RUN ACCOUNTS_REPORT
This solution executes SYS$SYSTEM:LOGINOUT so that the default
command language interface (CLI) is activated (this is usually
DCL). This causes the logical names SYS$LOGIN and SYS$SCRATCH
to be defined for the detached process. The /AUTHORIZE quali-
fier also ensures that the users' process quota limits (PQLs)
are used from the system authorization file rather than re-
lying on the default PQL system parameters, which are often
insufficient for Rdb/VMS.
o Solution 2:
If DCL is not desired, and SYS$LOGIN and SYS$SCRATCH are not
defined, then prior to executing any Rdb/VMS statement, you
must define the following logical names:
- RDMS$BIND_WORK_FILE
Define the RDMS$BIND_WORK_FILE logical name to allow you
to reduce the overhead of disk I/O operations for matching
operations when used in conjunction with the RDMS$BIND_WORK_
VM logical name.
For more information on RDMS$BIND_WORK_FILE, see the VAX
Rdb/VMS Guide to Database Maintenance and Performance.
- SORTWORK0, SORTWORK1, and so forth
Known Problems, Restrictions, and Other Notes 3-81
The VMS Sort utility attempts to create sort work files
in SYS$SCRATCH. If the SORTWORK logical names exist, the
utility will not require the SYS$SCRATCH logical. However,
note that not all queries will require sorting, and that
some sorts will be completed in memory and so will not
necessarily require disk space.
If you use the logical RDMS$BIND_SORT_WORKFILES, you will
need to define further SORTWORK logical names as de-
scribed in the VAX Rdb/VMS Guide to Database Maintenance
and Performance.
You should also verify that sufficient process quotas are
specified on the RUN/DETACH command line, or defined as
system PQL parameters to allow Rdb/VMS to execute.
3.11.30 Disable VAX SQL/Services V1.0 Startup Procedure
If VAX SQL/Services Version 1.0 was installed on your VMS system,
log in to a privileged account, edit the SYS$MANAGER:SYSTARTUP_
V5.COM command procedure, and delete or comment out the following
line:
$ @SYS$MANAGER:SQLSRV$STARTUP.COM
SQL/Services startup now occurs in SQL$STARTUP, which is called
from RMONSTART.COM.
3.11.31 DDL Statements Cannot Refer to Objects Before Their Creation
CREATE SCHEMA and CREATE TABLE statements in programs must precede
(in the source file) all other data definition language (DDL)
statements that refer to the schema or table, respectively.
3-82 Known Problems, Restrictions, and Other Notes
3.11.32 Deleting Metadata in Rdb/VMS
There is a problem deleting metadata items in Rdb/VMS because
there are dependencies among metadata items. For example, if a
table has an index on it, that index is used in a storage map. In
the following example, T1 is a table in a mixed area that uses a
hashed index I1. If you try to drop this table T1, the index I1
will also be deleted and Rdb/VMS gives you an error message.
CREATE SCHEMA FILENAME FOO
CREATE STORAGE AREA A1
PAGED FORMAT IS MIXED
CREATE TABLE T1 ( A INTEGER, B INTEGER)
CREATE INDEX I1 ON T1 (A) STORE IN A1
CREATE STORAGE MAP M1 FOR T1 PLACEMENT VIA INDEX I1;
DROP TABLE T1;
%RDB-E-NO-META-UPDATE, metadata update failed
%RDMS-F-INDINMAP, index I1 is used in storage map definition
Whereas RDO says that you must first delete maps and indexes, then
the table; SQL says that you can just delete the table and SQL
will take care of deleting everything else for you. The problem
is that sometimes SQL tries to delete an index on which something
else is dependent.
SQL is currently reevaluating the strategy for deleting metadata
items that depend on each other. If users encounter the problem
shown in the preceding example, then they must delete the metadata
items by hand according to the rules described in the VAX Rdb/VMS
RDO and RMU Reference Manual.
3.11.33 SQL Schema Compilation Fails on the First Fatal Error
When compiling schemas, SQL fails on the first fatal error. That
means it is necessary to compile more than once to find multiple
fatal errors.
There is no way in V4.0 to avoid the inconvenience of multiple
compilations.
Known Problems, Restrictions, and Other Notes 3-83
3.11.34 COMMENT ON Statement Cannot Be Used in CREATE SCHEMA
Statement
The COMMENT ON statement cannot be used in a CREATE SCHEMA state-
ment.
3.11.35 Dynamic Cursors Cannot Access Views Created with GROUP BY or
UNION Clause
Views that contain a GROUP BY or UNION clause in their definition
cannot be accessed using dynamic cursors. Note that in interac-
tive SQL, these views may be accessed with the SELECT statement;
in precompiled SQL or SQL module language, these views may be
accessed with singleton SELECT statements and with non-dynamic
cursors. The problem shows up only with dynamic cursors. If a user
attempts to access one of these views with a dynamic cursor, the
following error will be returned when the cursor is opened:
"RDMS-F-VIEWNORET,view cannot be retrieved by database key".
The workaround for this problem is to use non-dynamic cursors to
access the view. If a dynamic cursor must be used, the statement
should access the base tables that make up the view (with the
GROUP BY and UNION clauses, as appropriate) and not the view
itself.
3.11.36 Cannot Use INCLUDE Statement in Variable Declaration
The SQL$PRE precompiler will not process an INCLUDE statement in
the middle of a variable declaration. The following segment from a
COBOL program illustrates an INCLUDE statement that does not get
processed:
01 dept_rec pic x(24).
01 commarea.
EXEC SQL INCLUDE "A.DAT" END-EXEC.
3-84 Known Problems, Restrictions, and Other Notes
3.11.37 SQL Ada Precompiler Does Not Support the Correct Overloading
of Subprograms
The SQL Ada precompiler does not support overloading (overlaying)
of subprograms correctly. It treats all of the overloaded programs
as a single name space.
There are three workarounds to this problem in the current version
of the SQL interface to Rdb/VMS:
o The best workaround is to use the module language interface
instead of the precompiler. The module language is an interface
for defining procedures to execute SQL statements. You then
import these procedures into Ada and use them as you would use
any other external subprogram. Because SQL no longer processes
the Ada program, using the module language removes all of the
compile-time restrictions imposed by the precompiler on what
Ada features you can use. The run-time performance and features
of the module language interface are identical to the run-time
performance and features of the precompiled interface.
o The second workaround is to use the separate compile-time fea-
ture of Ada for all of your loaded subprograms. Using this
approach, all of your overloaded subprograms would be precom-
piled separately so the Ada precompiler would handle the name
spaces correctly. The disadvantage of this approach is that the
SQL statements in the subprogram would not be able to refer to
types, variables, and so forth, that were declared in the main
program unit because SQL would not know anything about them.
o The third workaround is to make sure that all of the names used
in SQL statements in the overloaded procedures are unique in
all of the overloaded procedures. If you want to limit yourself
to using ANSI standard features, the names of all host language
variables used in SQL statements must be unique in the entire
file.
Known Problems, Restrictions, and Other Notes 3-85
3.11.38 SQL Precompiler Does Not Evaluate Expressions in Variable
Declarations or Understand Literals
The SQL$PRE precompiler for the C language gives the following
error message when an SQL statement refers to a host language
variable declared as a character array whose declaration includes
anything other than a straight numeric value:
%SQL-F-BAD_ARRAY, Host variable address contains an array syntax error
in its declaration.
For example, this error occurs when the declaration contains a
named constant or an expression:
#define NAME_LEN (20)
#define ADDRESS_LEN (31)
char name [NAME_LEN + 1] /* This cannot be used */
char address [ADDRESS_LEN] /* This cannot be used */
Note that this has always been a restriction.
There is a workaround that requires two actions:
1. Remove the expressions from the declarations and update the
#define line accordingly; also remove the parentheses from the
#define line:
#define NAME_LEN 21
#define ADDRESS_LEN 31
char name [NAME_LEN]
char address [ADDRESS_LEN]
2. Run the C code through the C preprocessor before invoking the
SQL precompiler. This will force all named constants to be
translated before the precompiler tries to use them:
CC/PREPROCESS=filename.SCP filename.SC
SQL$PRE/CC filename.SCP
3-86 Known Problems, Restrictions, and Other Notes
3.11.39 SQL Ada Precompiler Does Not Support Named Literals or
Ranges
The SQL Ada precompiler does not support the use of named literals
or ranges.
It is possible to avoid this restriction by using the module
language interface instead of the precompiled interface.
3.11.40 Limiting Length of File Names
Limit the length of the file name of an Ada precompiler file
(SQLADA) to 27 characters. The Ada compiler limits file names
to 31 characters; however, the SQL precompiler adds the prefix
"SQL_" to the file name to create a package name.
3.11.41 Limiting Number of Continuation Lines per Record
In precompiled FORTRAN programs, the SQL precompiler adheres to
a restriction of 98 or fewer continuation lines in a statement
if you use the /CONTINUATIONS qualifier. The default number of
continuation lines is 19.
If a program uses a record definition, the SQL precompiler unpacks
the record into individual elements and places each one on a sepa-
rate line. If the number of elements in the record is greater than
the maximum number of continuation lines, the FORTRAN compiler
generates an error.
If this happens, increase the number of continuation lines using
the /CONTINUATIONS qualifier in the FORTRAN command line. If the
record contains more elements than the maximum allowed by FORTRAN
(99 elements), you can edit the intermediate file (file type FOR)
to place more than one element on a line.
Known Problems, Restrictions, and Other Notes 3-87
3.11.42 SQL Module Language Processor Fails on the First Fatal Error
The SQL module processor fails on the first fatal error. That
means it is necessary to perform multiple compilations to find
multiple fatal errors.
There is no way in V4.0 to avoid the inconvenience of multiple
compilations.
3.11.43 Database Handle Problem on START_STREAM
Both the RDML and RDO reference manuals state that the default
database handle scope is GLOBAL. This is true except for the
following cases:
o RDBPRE
- The default database handle is declared GLOBAL by default.
INVOKE DATABASE FILENAME 'PERSONNEL'
- A named database handle is declared as LOCAL by default.
INVOKE DATABASE PERS = FILENAME 'PERSONNEL'
o RDML
- Both the default and named database handle are declared as
GLOBAL by default.
3.11.44 RDO CHANGE INDEX Restriction Is Now Signaled
In Versions 3.0A and 3.0B, Rdb/VMS allowed the user to attempt
to use the CHANGE INDEX statement on an index that was defined to
be placed in the default RDB$SYSTEM storage area of a multifile
database (that is, the DEFINE INDEX statement was used without a
STORE WITHIN clause). This statement should not have been allowed,
and in Rdb/VMS V3.1 it is a restriction.
3-88 Known Problems, Restrictions, and Other Notes
If a DEFINE INDEX statement is used to create an index in a multi-
file database, and the STORE WITHIN clause is not specified, any
attempt to use the CHANGE INDEX statement to change the storage
area in which the index is stored is not allowed:
DEFINE INDEX I1 FOR R1.
F1.
END INDEX.
CHANGE INDEX I1 STORE WITHIN STORAGE_AREA1.
This will result in the following error:
%RDB-E-NO_META_UPDATE, metadata update failed
-RDMS-F-CHGIDXNOADDMAP, INDEX may not be altered/changed to have map
In Rdb/VMS V3.1, an index without a map specification cannot be
changed to have a map.
3.11.45 Problem of Different Optimizations of the Same Query from
Different Environments
In some cases, the same query is optimized differently from dif-
ferent environments (RDO and RDBPRE/COBOL, for example). This
problem is due to the fact that queries are handled differently by
the interfaces, in this case, RDO and RDBPRE, and different BLRs
are generated.
RDBPRE is a batch environment as opposed to the interactive RDO
environment, and therefore, in some cases, can consolidate two
or more statements into one, and produces a more compact BLR than
RDO. For example, for the following query, RDBPRE will generate a
single BLR identifying three output fields:
Known Problems, Restrictions, and Other Notes 3-89
START_STREAM S USING R IN REL WITH R.FLD1 < 123
FETCH S
GET
HOST_VAR1 = R.FLD1;
HOST_VAR2 = R.FLD2;
HOST_VAR3 = R.FLD3
END_GET
An equivalent RDO query produces two BLRs, one for the START_
STREAM statement and one for the FETCH and PRINT statements:
START_STREAM S USING R IN REL WITH R.FLD1 < 123
FETCH S
PRINT R.FLD1, R.FLD2, R.FLD3
3.11.46 Restrictions on Using Missing Value Fields in Nested Queries
Within a single context, such as the context of a single request,
if an arithmetic expression contains the MISSING operator, the
resulting expression will evaluate to MISSING. In the following
example, A.FIELD_1 contains missing (unknown) values, and the
query correctly interprets the values in A.FIELD_1 as missing
(unknown), causing the expression A.FIELD_3 = VARIABLE + A.FIELD_1
to evaluate to MISSING:
RDO> FOR A IN RELATION_A
cont> MODIFY A USING
cont> A.FIELD_3 = VARIABLE + A.FIELD_1
cont> END_MODIFY
cont> END_FOR
However, in nested queries that use multiple database requests,
such as the following example, if B.FIELD_2 contains missing (un-
known) values, the expression A.FIELD_3 = VARIABLE + B.FIELD_2
returns different results. The second query (which begins with
FOR A) retrieves a value, in this case the value defined as the
field's MISSING_VALUE, from B.FIELD_2 for its RSE. However, be-
cause of RDO language limitations, the second query cannot use
3-90 Known Problems, Restrictions, and Other Notes
the fact that the field B.FIELD_2 has an unknown value and in-
stead uses the missing value defined for the field with the DEFINE
FIELD or CHANGE FIELD statement. Using this value for B.FIELD_2
instead of treating the value as unknown means that the A.FIELD_3
= VARIABLE + B.FIELD_2 expression does not evaluate to MISSING.
RDO> FOR B IN RELATION_B
cont> FOR A IN RELATION_A WITH A.FIELD_1 = B.FIELD_1
cont> MODIFY A USING
cont> A.FIELD_3 = VARIABLE + B.FIELD_2
cont> END_MODIFY
cont> END_FOR
cont> END_FOR
The workaround is to use the SQL interface to Rdb/VMS. You can
use the SQL indicator variables to detect the NULL attribute of
the column (field) and therefore set the appropriate value for the
column.
3.11.47 STORE WITHIN and DISABLE/ENABLE COMPRESSION Clauses Cannot
Both Be Specified
The STORE WITHIN and the DISABLE/ENABLE COMPRESSION clauses cannot
both be specified in the same CHANGE STORAGE MAP statement. The
restriction is shown in the following example:
Known Problems, Restrictions, and Other Notes 3-91
INVOKE DATABASE FILENAME MF_PERSONNEL
!
! The following statement is not allowed.
!
CHANGE STORAGE MAP CANDIDATES_MAP
STORE WITHIN EMPIDS_MID DISABLE COMPRESSION
END.
!
! However, this is the workaround. Use two CHANGE STORAGE MAP
! statements.
!
CHANGE STORAGE MAP CANDIDATES_MAP STORE WITHIN EMPIDS_MID
END.
CHANGE STORAGE MAP CANDIDATES_MAP DISABLE COMPRESSION
END.
!
FINISH
3.11.48 Variables Cannot Be Database Handles
The example program shown here illustrates a problem with RDML. It
is written in VAX C, and although the precompilation is clean, the
C compiler gives errors at the READY statement. This problem only
occurs when the READY statement contains a database handle that
is incorrectly specified as a variable rather than specified in a
DATABASE statement.
This program works if a database handle specified in one of the
database statements is used in the READY statement, whether the
READY statement is in a function or a main module.
3-92 Known Problems, Restrictions, and Other Notes
#include stdio
DATABASE first_db = FILENAME 'the_first';
DATABASE second_db = FILENAME 'the_second';
main()
{
one_ready(first_db);
one_ready(second_db);
printf("%d\n",first_db);
printf("%d\n",second_db);
START_TRANSACTION READ_WRITE;
COMMIT;
}
one_ready(the_handle)
unsigned long the_handle;
{
READY the_handle ON ERROR printf("an error\n"); END_ERROR;
return(the_handle);
}
The READY statement, as documented on page 6-99 of the RDML
Reference Manual (Rdb/VMS V3.0), states that the database han-
dle (or multiple database handles) used in the READY statement
must be specified in a DATABASE statement. Digital does not sup-
port user-specified database handles in RDML; database handles
are automatically declared and used in RDML as a result of their
specification in a DATABASE statement (which is really a decla-
ration). This program attempts to use a database handle that is
declared explicitly (as opposed to being specified in a DATABASE
statement), and RDML therefore does not recognize it as a database
handle. Because a READY statement by itself is valid, RDML simply
recognizes that the READY statement syntax has terminated at that
point, and so it fails to detect the ON ERROR clause later in the
same line. (It assumes that the rest of the line was host language
syntax.)
Known Problems, Restrictions, and Other Notes 3-93
To achieve the desired result of RDML recognizing your database
handle, associate a unique number with each database handle, and
use it to identify which database handle to use. The example shown
here is a possible approach:
#include <stdio.h>
DATABASE first_db = FILENAME 'PERSONNEL';
DATABASE second_db = FILENAME 'PERSONNEL';
main()
{
one_ready(1);
one_ready(2);
printf("%d\n", first_db);
printf("%d\n", second_db);
START_TRANSACTION READ_WRITE;
COMMIT;
}
one_ready(int which_handle)
{
switch (which_handle)
{
case 1:
READY first_db ON ERROR printf("an error\n"); END_ERROR;
break;
case 2:
READY second_db ON ERROR printf("an error\n"); END_ERROR;
break;
}
}
3-94 Known Problems, Restrictions, and Other Notes
3.11.49 RDML Run-Time Object Library No Longer Requires You to Link
with VAXCRTL or VAXCRTLG Object Libraries or Shareable
Images
The RDMLRTL.OLB no longer requires you to link against either the
VAXCRTL or VAXCRTLG object libraries or shareable images. However,
if you are programming in RDML/C, then you must still link against
one of these because VAX C requires it.
3.11.50 RDML/EPascal Ignores /LINKAGE=PROGRAM_SECTION Qualifier
RDML/EPascal ignores the /LINKAGE=PROGRAM_SECTION qualifier. RDML
/EPascal only supports the /LINKAGE=GLOBAL_VARIABLE mechanism for
linking multiple modules. RDML/EPascal issues a warning message in
this case.
3.11.51 RDML/Pascal Does Not Understand Some Character String Value
Expressions
RDML/Pascal does not generate the correct length for a character
string value expression in the form:
FOR E IN EMPLOYEES WITH E.LAST_NAME = ('T' | host_variable)
... some statements ...
END_FOR;
This statement generates an error in from VAX Pascal, such as:
00470 0 0 RDB$PORT_FIELD_0 : VARYING[0] OF CHAR;
1
%PASCAL-E-MAXLENRNG, (1) Max-length must be in range 1..65535
%PASCAL-E-ENDDIAGS, Pascal completed with 1 diagnostic
To avoid this problem, construct the value needed before issuing
the query, using a method such as the following:
Known Problems, Restrictions, and Other Notes 3-95
host_variable1 := 'T' + host_variable2;
FOR E IN EMPLOYEES WITH E.LAST_NAME = host_variable1
... some statements ...
END_FOR;
This method is recommended for all RDML statements when possible
because it will generally improve the performance of the query.
3.11.52 RDML/Pascal Does Not Accept All Possible Valid Pascal Host
Language Variables
RDML/Pascal does not accept all possible valid Pascal host lan-
guage variables, and it issues the following error if one it does
not accept is encountered:
%RDML-W-HOST_VARIABLE, error detected in host variable syntax
The set of possible values is limited to the syntax described
in the RDML Reference Manual, with the restriction that the
expression allowed in an array index must be a simple name or
expression. The following illustrates an unacceptable statement.
FOR E IN EMPLOYEES WITH E.EMPLOYEE_ID = emparray[empstruct.index]
... some statements...
END_FOR;
In the preceding example, empstruct.index is a reference to a
structure member. To avoid this problem, you would assign emp-
struct.index to an intermediate variable and use that variable in
the FOR statement WITH clause.
3.11.53 RDML Does Not Allow Nested Comments
The RDML C and Pascal preprocessors do not allow nested comments
and now identify such comments with an informational message.
RDML does not allow comments because they are not allowed by
the ANSI/ISO C standard or by VAX C (when you use the /STANDARD=
PORTABLE qualifier).
3-96 Known Problems, Restrictions, and Other Notes
3.11.54 C Host Variables
The following restrictions affect the use of C host variables:
o Host variables in C of the form *host_variable that appear
directly after a host variable in an RSE are not detected
correctly. For instance, *year_ptr is interpreted incorrectly
as part of the host variable emp_id in the following example:
FOR D IN DEGREES WITH D.EMPLOYEE_ID = emp_id
*year_ptr = D.YEAR_GIVEN;
END_FOR;
The workaround for this restriction is to use braces around
the host language statements, or parentheses around the WITH
clause. For example, either of the following RSEs will prepro-
cess correctly:
FOR D IN DEGREES WITH D.EMPLOYEE_ID = emp_id
{
*year_ptr = D.YEAR_GIVEN;
}
END_FOR;
FOR D IN DEGREES WITH (D.EMPLOYEE_ID = emp_id)
*year_ptr = D.YEAR_GIVEN;
END_FOR;
o Although host variables with parentheses are permitted in non-
RDML statements, they cannot be used as host variables in RDML
statements. For example, the following syntax is not permitted:
FOR E IN EMPLOYEES
WITH E.LAST_NAME = (name)[offset].element
.
.
.
END_FOR;
Known Problems, Restrictions, and Other Notes 3-97
However, the following is permitted:
FOR E IN EMPLOYEES
WITH E.LAST_NAME = name[offset].element
.
.
.
END_FOR;
3.11.55 C String Continuation Character
The C string continuation character, (a backslash, \), in string
constants followed immediately by a new line is not recognized by
RDML. Do not use this method of continuation with this version of
RDML. RDML generates an error if it finds a string constant that
does not begin and end on the same line within quotation marks.
For example, the following C lines cause a syntax error in
Rdb/ELN:
printf ("abcdefg\
hijklmnopqrstuvwxyz");
3.11.56 Path Name and the DATABASE Statement
RDML does not extract the run-time file name from the CDD when
you specify the compile-time path name option of the DATABASE
statement only. If you choose to specify the compile-time path
name, you must also supply the run-time file name. If you do not
supply the run-time file name under these conditions, RDML will
use the CDD path name as the run-time file name. For instance,
RDML will mistakenly use 'CDD$TOP.PERSONNEL' as the run-time
database file name in the following example:
DATABASE COMPILETIME PATHNAME 'CDD$TOP.PERSONNEL';
3-98 Known Problems, Restrictions, and Other Notes
However, RDML will interpret the following DATABASE statement
correctly:
DATABASE COMPILETIME PATHNAME 'CDD$TOP.PERSONNEL'
RUNTIME FILENAME 'PERSONNEL';
3.12 DSRI Notes and Restrictions Retained from V3.1
This section contains known problems and restrictions related to
the DIGITAL Standard Relational Interface (DSRI).
Digital recommends that applications avoid the use of DSRI inter-
faces to avoid version compatibility problems, and suggests the
use of the SQL interface to Rdb/VMS wherever possible.
3.12.1 RCI Instantiation Number Must Be Zero for Remote Access
DSRI allows multiple instances of a request to execute against
different databases. Rdb/VMS supports only a single instance for
each database attach. However, the Relational Call Interface (RCI)
does allow the specification of INSTANTIATION for each request.
In the current version of Rdb/VMS, this instantiation number must
have the value 0 for remote access to succeed. This problem exists
in the remote access server, so local database access is not
affected.
The Rdb/VMS precompilers always generate a value of 0 for the
instantiation number, so this restriction will be observed only by
Rdb/VMS users who use the RCI directly from application programs.
3.12.2 Context Variables That Are Not Unique Within a Request Cause
Invalid BLR
A program that contained context variables that are not unique
and ran in a Rdb/VMS V3.0 system, now generates an invalid binary
length record (BLR) error in Rdb/VMS V3.1.
Known Problems, Restrictions, and Other Notes 3-99
Due to enhancements being made to Rdb/VMS V3.1, the restric-
tion that context variables be unique within a request must be
enforced.
This restriction requires applications that generate BLR to gen-
erate a unique context variable for each BLR$K_RELATION, BLR$K_
RELATION_ID, BLR$K_FETCH, BLR$K_ERASE, BLR$K_STORE, BLR$K_STORE2,
or BLR$K_MODIFY used in a single request. These context variables
are represented as unsigned byte data types; therefore, a request
might have as many as 256 context variables.
An INVALID BLR exception is now generated under these cir-
cumstances. The exception status will be returned from the
RDB$COMPILE_REQUEST call and the message vector will contain
the offset in the BLR string of the duplicate context variable.
For example, the message vector, when formatted with SYS$PUTMSG,
appears as:
%RDB-E-INVALID_BLR, request BLR is incorrect at offset 301
NOTE
This restriction does not apply to code (BLR) generation
performed by Digital language processors, RDBPRE, RDML,
SQL$PRE, and SQL$MOD, which always generate unique context
variables when compiling requests.
3.13 CDD/Plus Restrictions Retained from Rdb/VMS V3.1
This section contains known problems and restrictions retained
from Rdb/VMS V3.1 related to CDD/Plus V4.1.
3-100 Known Problems, Restrictions, and Other Notes
3.13.1 CDD/Plus COMPUTED BY Fields Are Not Currently Supported in
Rdb/VMS Relations or Views
If you define a COMPUTED BY field in CDO and use it in a record,
that record will not be usable in Rdb/VMS. Incompatible data type
errors will occur if you try to use an RDO INTEGRATE statement
when the record containing the COMPUTED BY field will be used as
an Rdb/VMS relation.
RDO COMPUTED BY fields are computed in the context of a relation,
while CDO COMPUTED BY fields are not. The two concepts do not have
a semantic mapping. This is a restriction that did not get docu-
mented in CDD/Plus documentation. It is currently not considered
a problem but rather a possible enhancement to be considered for
some future release.
It is possible to use Rdb/VMS compatible COMPUTED BY fields in
record definitions stored in the data dictionary if they are
actually defined in RDO and then entered into the data dictionary.
The COMPUTED BY field may be defined in Rdb/VMS as part of a
relation using the INVOKE PATH option. A record with a COMPUTED
BY field defined in RDO and entered in the data dictionary can be
included in other databases.
3.13.2 EXPORT WITH NOEXTENSIONS Statement Can Corrupt the
CDD$DATABASE
Section 2.2.2 of the Rdb/VMS V3.0A Release Notes suggests using
the EXPORT WITH NOEXTENSIONS statement if you need to export
databases and have the import operation create a single-file
database. However, the export file created does not include enough
information to exactly rebuild the database contents for the NULL
flag (MISSING VALUE information) for each field. This information
is required by CDD/Plus and causes dictionary corruptions during
the import operation. See Section 3.11.8 for more information
about the IMPORT statement operation.
Known Problems, Restrictions, and Other Notes 3-101
The RDO EXPORT WITH EXTENSIONS statement can be used to work
around this problem. The extensions to the original export proto-
col include the actual setting of the NULL flags for each field.
3-102 Known Problems, Restrictions, and Other Notes
Appendix A
Process Pooling
VMS system managers who have installed either the Rdb/VMS
Version 4.0 interactive or run-time kit and want to modify the
SQL/Services server system must understand process pooling and the
methods used to access the server from remote client systems:
o Process pooling provides an efficient mechanism for applica-
tions on remote client systems to access and retrieve data from
Rdb/VMS and VIDA databases on VMS systems.
o Client API applications can gain access to the SQL/Services
server system in a number of ways, ranging from explicit user
account access to access through the default account provided
by SQL/Services. To ensure system security, each access method
can be closely controlled by the system manager at your site.
This appendix describes how process pooling works and the way to
manage pooling at your site. It also describes how the communi-
cation server authorizes client application access to the server
system.
Process Pooling A-1
A.1 Process Pooling Overview
On the VMS server system, SQL/Services separates the task of
communicating with client API requests from the operation of
executing those requests. The communication component, called the
communication server process, creates at SQL/Services startup time
the execution component, referred to as the process pool. When
Application Programming Interface (API) requests from applications
on client systems are sent to VMS server systems for processing
against an Rdb/VMS database, the communication server:
o Accepts incoming client API requests
o Assigns requests to the process pool for execution
o Accepts the results of request execution from the process pool
o Returns results to waiting client applications
The communication server is designed as a multithreaded process,
meaning that it can handle multiple requests (processes) simulta-
neously.
The process pool consists of one or more sets of processes, called
execution server processes, that execute client API requests for
the communication server. Each of the execution server processes
created and pre-started (optionally) by the communication server
at SQL/Services startup is reusable (not stopped after use) by the
communication server. Reusable execution server processes save the
communication server from creating processes every time a client
application connects to the server system. Non-reusable processes
are a costly expenditure of time and system resources.
Process pooling, with a multithreaded communication component
(communication server), and an execution component (process pool)
consisting of reusable execution server processes, decreases
client API request response time and reduces overall system re-
source utilization.
A-2 Process Pooling
A.2 Process Pooling Components
The SQL/Services configuration file contains sets of definitions.
Each definition identifies characteristics of the process pool and
specifies how many:
o Sets of execution servers are created for the process pool
o Execution server processes populate each set
The communication server reads the configuration file at
SQL/Services system startup to create the process pool from the
definitions specified in the file. A single definition creates for
the process pool one set of execution server processes, collec-
tively called a subpool. The initial process pool, specified by
the default configuration file, contains one subpool of two execu-
tion server processes; however, you can modify the configuration
file to define as many subpools for the process pool as you need.
Your system manager can define two classes of subpools (classes of
execution server processes) for the process pool:
o Generic class execution server process (Default)
The class of execution server processes that the communication
server selects by default to execute API requests. The communi-
cation server automatically creates two generic class execution
server processes at system startup time.
No modifications to client API applications are needed if you
want to use generic class servers.
o Database class execution server process (Optional)
The class of execution server process that the communication
server can create (at system startup) to execute client API
requests. The database class server provides the same function
(to execute API requests) as a generic class server but handles
requests in a more specialized way. Specialization improves API
performance and reduces load on server system resources, but
Process Pooling A-3
imposes two limitations. First, each execution server process
of the database class is pre-attached at system startup time to
a single database. Second, API client application access to the
database occurs through a single user account.
Modifications to applications and the server system are neces-
sary if you want to use database class servers.
Which class of execution server process you select depends on the
requirements of the applications at your site. You might need the
convenience or flexibility of generic servers, which require no
application or system modifications to use. You might require the
performance advantage of database class servers, even with the
restrictions imposed and the need for minor application and system
modifications. Refer to Section A.4.1 for help in making this
choice.
Figure A-1 shows the main components of process pooling.
A-4 Process Pooling
__________________________________________________________________
In Figure A-1, the process pool includes the two default generic
execution server processes automatically created by the commu-
nication server at SQL/Services system startup and two optional
database execution server processes.
Table A-1 summarizes the main components of process pooling.
Table_A-1:_Process_Pooling_Components_____________________________
Component____Description__________________________________________
Process All sets of execution server processes (subpools)
Pool that reside on the server system and that execute API
requests and return execution results.
Subpool The name given to a set of execution server processes
residing on the server system that execute requests
and return execution results. The configuration file
can define a subpool of generic or database execution
server processes.
CommunicationThe SQL/Services multithreaded process residing on a
VMS server system that accepts incoming API requests,
Server assigns requests to execution server processes, and
returns execution results to client applications.
ConfigurationA file that the communication server accesses at
server startup time to create execution server pro-
File cesses that execute API requests. The file contains
one or more definitions that configure the process
pooling environment.
Process Pooling A-5
Table_A-1_(Cont.):_Process_Pooling_Components_____________________
Component____Description__________________________________________
ConfigurationOne or more sets of parameters in the configuration
file that specify how the communication server con-
File figures the process pool. A configuration file can
Definition specify a single generic class definition or multiple
database class definitions.
Execution A set of processes created by the communication
Server server to execute API requests. The configuration
Process file, read by the communication server at system
startup, defines how many sets of execution server
processes are created and how many execution server
processes are in each server set. Execution server
processes fall into either of two classes: generic or
_____________database.____________________________________________
A.3 Communication Server Process
The communication server functions during two phases of operation.
During the initializing phase, the communication server creates
execution server processes and starts an SQL/Services program
(image) in each one to execute client API requests. Execution
server processes are created (process creation) and an image
activated (a program started) in each before the communication
server assigns them to execute API requests during the working
phase. This saves process creation and image activation time on
each client connection to the server.
Figure A-2 illustrates the phases of the communication server and
the major activities performed in each phase.
A-6 Process Pooling
__________________________________________________________________
The communication server and the execution server processes it
creates hibernate at the end of the initializing phase. The pro-
cess pool can remain in this state indefinitely so long as the
communication server does not receive requests from the client
system. The communication server can also hibernate during the
working phase whenever request activity stops.
A.3.1 The Default Configuration File
At installation time or at SQL/Services startup, the default
version of the configuration file (SQLSRV$CONFIG.DAT) is stored on
your system in the SYS$STARTUP directory. The communication server
reads the configuration file and creates the default generic class
subpool_of_execution_server_processes_shown_in_Figure_A-3.________
The dotted execution server processes in Figure A-3 indicate
that process 1 and 2 are not pre-started at SQL/Services system
startup.
Example A-1 shows the configuration file definition that generates
the default process pool.
Process Pooling A-7
Example A-1: Definition of Generic Execution Server Process
__________________________________________________________________
-- ----------------------------------------------------------
-- "GENERIC" CLASS DEFINITION
-- ----------------------------------------------------------
CLASS "GENERIC"1
MIN 02
MAX 23
IDLE 18004
-- ----------------------------------------------------------
__________________________________________________________________
Definitions in the configuration file determine the size and
characteristics of a process pool. The definition in Example A-1:
1 Specifies a set of generic execution server processes
2 Does not pre-start any generic execution server processes and
allows the number of execution server processes to drop to zero
3 Can contain no more than two execution server processes
4 Allows execution server processes to remain inactive (not
associated with a request) up to 30 minutes (1800 seconds)
before deleting them
The default configuration file also contains the definition for
a database class server. However, that definition is commented
out[1] and is ignored by the communication server during the
initializing phase. The definition is provided as a template to
help you create your own database class definitions.
_____________________
[1] Use two consecutive hyphens (--) as a prefix in the configura-
tion file to mark text that you want the communication server
to ignore.
A-8 Process Pooling
Example A-2 shows the sample database class definition included in
the default configuration file.
Example A-2: Definition of Database Execution Server Process
__________________________________________________________________
-- ----------------------------------------------------------
-- CLASS "PERSONNEL"1
-- USER "BARNEY"2
-- EXECUTE "DECLARE SCHEMA FILENAME DB$PERSONNEL"3
-- IDENT "SUPERVISOR"4
-- MIN 15
-- MAX 36
-- IDLE 18007
-- ----------------------------------------------------------
-- ----------------------------------------------------------
__________________________________________________________________
The database class execution server process definition con-
tains three more parameters (USER, EXECUTE, and IDENT) than the
generic execution server process definition. The definition in
Example A-2:
1 Specifies a set of database execution server processes and
labels them with the user-supplied name PERSONNEL
2 Allows execution server processes to run within the account
owned by the person with user name of BARNEY
3 Specifies a DECLARE SCHEMA statement to attach to the
DB$PERSONNEL database
4 Allows only those API requests with the VMS rights identifier
SUPERVISOR to use an execution server process in the database
class
5 Allows the number of execution server processes to drop to one
Process Pooling A-9
6 Can contain no more than three active execution server pro-
cesses
7 Allows execution server processes to remain inactive (not
associated with a request) up to 30 minutes (1800 seconds)
before deleting them
Table A-2 describes the parameters for creating generic and
database execution server process definitions in the SQLSRV$CONFIG.DAT
configuration file.
Table_A-2:_Configuration_File_Parameters__________________________
Parameter_Description/Parameter_and_Default_Values________________
Class One of two types of execution server processes. The
communication server creates generic execution server
processes by default.
Specify either the identifier GENERIC or a user-
specified database class name.
This parameter has no default value.
User The user name of the account within which the database
class execution server processes run.
Assign a valid VMS user name.
This parameter has no default value.
Execute A full DECLARE SCHEMA command to invoke the database
that the database execution server processes attach to
and that the client API request wants to access.
Include a full DECLARE SCHEMA command to invoke the
database, making sure to enclose the entire command line
in double (") or single (') quotation marks.
This parameter has no default value.
A-10 Process Pooling
Table_A-2_(Cont.):_Configuration_File_Parameters__________________
Parameter_Description/Parameter_and_Default_Values________________
IdentifierThe name of a VMS rights database identifier that the
communication server uses to ensure that an incoming
API request is authorized to be assigned a database
class server. The identifier in the configuration file
for a particular database must match an identifier in
the rights list for the user name associated with the
incoming API request.
Enter a valid VMS identifier.
This parameter has no default value.
Minimum The number of execution server processes that the commu-
nication server creates and pre-starts at system startup
time. It also refers to the smallest number of execution
server processes that always remain active in a pro-
cess pool. Once the number of execution server processes
reaches this bottom limit, they are no longer affected
by the IDLE parameter.
Enter a value in the range zero to n, where n represents
a number determined by the requirements of your applica-
tions and the limitations of your system resources.
This parameter has a default value of zero.
Process Pooling A-11
Table_A-2_(Cont.):_Configuration_File_Parameters__________________
Parameter_Description/Parameter_and_Default_Values________________
Maximum The largest number of execution server processes that
can be simultaneously active in the process pool. The
communication server cannot create more execution server
processes than the MAXIMUM parameter limit.
Enter a value in the range 1 to n, where n represents a
number determined by the requirements of your applica-
tions and the limitations of your system resources.
This parameter has a default value of 1.
Idle The amount of time in seconds that an execution server
process can remain inactive (not associated with a
request).
Assign a value in the range -1 to n seconds, where
n represents the maximum value allowed in a signed
longword. A -1 value indicates that you do not want
execution server processes deleted, saving you from
setting a very high idle time to keep the execution
server active indefinitely. A zero value indicates
that you want the execution server process deleted
immediately after use. A positive (+n) value defines
how long the communication server waits before deleting
the server process.
This parameter has a default value of 1800 seconds (30
__________minutes)._______________________________________________
The system manager at your site might have to change the default
configuration file, depending on the application requirements at
your site.
A-12 Process Pooling
A.3.2 Modifying the Configuration File
The configuration file at system startup time defines two generic
class execution server processes. Your site's API application
environment, however, might require a different process pool than
the one defined by the default configuration file. Section A.3.2.1
describes the procedure for modifying the configuration file, and
Section A.3.2.2 presents the rules for creating valid generic and
database class definitions.
A.3.2.1 Procedures for Modifying the Configuration File
Your system manager can change the configuration of the process
pool by performing three steps: shut down SQL/Services, edit the
configuration file, and start up SQL/Services. You must have
access to an account with SETPRV privileges to perform these
steps. Modifying the configuration file as follows:
1. Shut down SQL/Services.
To reconfigure the process pool, shut down SQL/Services as
follows:
$ @SYS$STARTUP:SQLSRV$SHUTDOWN
The system prints a series of messages indicating the status of
the shutdown and the moment shutdown occurs.
2. Change configuration file.
Use a text editor to change the configuration file. The
rules for modifying the configuration file are described in
Section A.3.2.2. When the changes are made, exit the configura-
tion file.
3. Restart SQL/Services.
Process Pooling A-13
To re-create the process pool, restart SQL/Services with the
following command:
$ @SYS$STARTUP:SQLSRV$STARTUP
The system prints a series of messages indicating the status of
the startup procedure and when startup is complete.
SQL/Services cannot start unless a valid SQLSRV$CONFIG.DAT file
exists in the SYS$STARTUP directory. If the configuration file is
accidentally deleted, you must re-create a valid SQLSRV$CONFIG.DAT
file and copy it to the SYS$STARTUP directory. Follow the rules in
Section A.3.2.2 to re-create the configuration file.
A.3.2.2 Rules for Modifying the Configuration File
The system manager at your site can modify (or re-create if neces-
sary) the configuration file by adhering to the following rules:
o Include at least the generic class definition in the configura-
tion file. Only one generic class definition is allowed in the
configuration file.
o Insert the generic class definition first in the configuration
file when database class definitions are specified.
o Place the class name parameter first in a definition. You can
list all other definition parameters in any order.
o Enter each parameter on a separate line.
o Use at least one space character to separate a parameter key-
word from its parameter value.
o Enclose each DECLARE SCHEMA command line in double (") or
single (') quotation marks.
A-14 Process Pooling
o Enter a parameter value for all parameter keywords that do not
provide a default. Table A-2 describes the default condition
for each configuration file parameter.
o Use (optionally) two successive hyphen characters (--) as the
comment token.
o Indent (optionally) parameter keywords with spaces to make
definitions readable.
A.4 Execution Server Processes
The communication server automatically assigns generic class
execution server processes to execute API requests. Only when
you modify your client API applications to use database class
execution server processes will the communication server use
that class of server instead of the default. You will have to
study your application requirements to determine which class of
execution server process best fits the needs at your site. This
section describes each server class and when you might use one
over the other.
A.4.1 Choosing an Execution Server Process
You have the choice between the convenience and flexibility of the
generic class execution server and the performance advantage that
the database class execution server processes provide:
o The generic class server requires no modification of client
API applications or system components. The communication server
automatically assigns client requests to the generic subpool of
execution server processes by default.
Process Pooling A-15
o The database class server requires modification to both client
API application and to the server system. Although programmers
have to make minor API application modifications and your sys-
tem manager must perform a few simple tasks to enable database
class servers, database class execution server processes hold a
performance advantage over generic class servers.
The performance advantage of database servers comes with two
restrictions:
o Single database attachment
During the SQL/Services initializing phase, database class
execution servers are attached once to a single Rdb/VMS or VIDA
database for the lifetime of the execution server processes in
that database class.
o Access to the database server through a single user account
Because Rdb/VMS picks up user authorization information at
database attach time, all client API application access to the
single, pre-attached database of a database class execution
server process occurs within the context of a single user
account.
In contrast, the execution server processes in the generic class
subpool are not pre-attached to a database and thus must make a
database attach every time a client API application connects to
the server system. Having execution server processes in a database
class server pre-attached to a database saves attaching to a
database on each client/server connect. This improves application
performance and reduces system resource utilization.
To clarify the distinction between generic and database servers,
suppose you have 10 terminal operators on a client system running
the same application against the same PERSONNEL database. If
the SQL/Services system manager uses the default generic class
servers, every time the block of 10 terminal operators requests
information, 10 attaches to the PERSONNEL database are made.
However, because a database execution server process is set up
A-16 Process Pooling
to pre-attach to the PERSONNEL database, then only one attach is
made for the lifetime of the execution server process rather than
an attach for each connect. As the number of connects increase,
the savings in performance increases and system load decreases.
Because SQL/Services allows API applications to contain multiple
associations, each of which can use a different class of execution
server process, you must weigh the advantages and disadvantages
of using generic or database execution server processes for each
association within each of your applications.
A.4.2 Generic Class Execution Server Processes
The communication server creates two generic execution server
processes when it reads the system-supplied configuration file
at process startup time. You can change this initial file any
time that its settings do not suit your application requirements.
Although only one generic class definition is allowed in a config-
uration file, you can define as many execution server processes
of that class as your system resources allow and your applica-
tions need. When your site must modify the configuration file
to change the definition of the generic class server, follow the
rules listed in Section A.3.2.2.
In general, generic class servers enable client API applications
to access execution server processes without program or VMS system
modification.
A.4.3 Database Class Execution Server Processes
The database execution server processes allow API requests to
be executed by processes that are pre-attached at system startup
time to a single database. For an API request to use a database
class server, a programmer must name the database in the sqlsrv_
set_server_class routine and include the routine in each appli-
cation needing a database class server. Programmers can refer to
Section A.4.3.2 for details on specifying the routine for database
servers and resetting the routine for use with generic execution
Process Pooling A-17
servers. The routine is essentially a switch that can be toggled
between server classes.
Section A.4.3.1 describes the tasks that the system manager
must perform to facilitate use of database class servers.
Section A.4.3.2 shows how programmers can select a server class in
their applications.
A.4.3.1 System Management Tasks: Setting Up Database Servers
As system manager, you must perform a number of tasks to enable
database execution server processes for client API requests at
your site. Before you review the list of tasks, however, you
must understand how the communication server handles incoming
API requests. As you read in the following discussion how the
communication server processes requests, refer to Figure A-4,
which illustrates the components that you must work with to enable
database servers on an SQL/Services system.
A-18 Process Pooling
__________________________________________________________________
Suppose that an API programmer has written an application that
needs access to a database execution server process. The communi-
cation server performs the following steps when requests come in
from that application:
1. Determines from the client API request passed by the sqlsrv_
set_server_class routine that the request requires access to
a set of database execution server processes that are pre-
attached to an Rdb/VMS database named PERSONNEL.
2. Checks to see if any database class names in the configuration
file match the PERSONNEL database class name. If no match
occurs, the communication server returns an error message to
the client application.
3. Makes sure that the user name (FOSTER) (associated with the
incoming API request) is listed in the user authorization file
(UAF) on the server system. If no match occurs between the
incoming user name and a user name in the rights list, the
communication server returns an error message to the client
application.
4. Reads the UAF rights list and compiles a list of identifiers
(SUPERVISOR) associated with the validated user name (FOSTER)
of the incoming API request.
5. Tries to match an identifier in the rights list with the iden-
tifier (SUPERVISOR) associated with the PERSONNEL class name in
the configuration file. If a match does not occur, the communi-
cation server returns an error to the client API request.
6. Assigns a database execution server process to the incoming
API request if the identifiers in the rights list and the
configuration file match. If all database execution server
processes are active, the communication server creates as many
new processes as the maximum parameter value allows.
Process Pooling A-19
With an understanding of how SQL/Services processes an API re-
quest, you can now perform the following tasks to enable database
class servers at your site.
o VMS Authorize utility tasks
- Ensure that the user names associated with incoming API re-
quests correspond to user accounts on the VMS server system.
Also, make sure that the user name (BARNEY) you specify in
the configuration file provides the proper access rights
to attach to an Rdb/VMS database. You must assign a user
name for each database class definition in the configuration
file.
- Assign identifiers in the VMS rights database to each re-
quest user name that you want given access to a database
execution server. You use the Authorize utility to associ-
ate a user name with an identifier. You must also assign an
identifier to the IDENT parameter for each database class
definition in the configuration file. When an identifier in
the configuration file for a particular class name matches
the same identifier in the rights list in the UAF, the com-
munication server is authorized to assign a request to that
database class server.
A-20 Process Pooling
o Configuration file changes
- CLASS parameter
Provide client application programmers with the names
(PERSONNEL) for the sets of database execution server pro-
cesses. Applications pass this name in the sqlsrv_set_
server_class routine included in their client applica-
tions. As system manager, you assign a name for each set
of database execution server processes in the configuration
file.
- USER parameter
Ensure that the database class definitions of database ex-
ecution server processes in the configuration file include
the user names that define the process context under which
the communication server attaches to the Rdb/VMS database.
You assign the user name to the USER parameter in the con-
figuration file.
- EXECUTE parameter
Create a DECLARE SCHEMA command to invoke the database to
which you want the database class server to attach. You
assign these commands to the EXECUTE parameter for each
database class definition in the configuration file.
- IDENT parameter
Assign identifiers in the VMS rights database to each re-
quest user name that you want given access to a database
server. You use the Authorize utility to associate a user
name and an identifier. You must also assign an identifier
to the IDENT parameter for each database class definition in
the configuration file. When an identifier in the config-
uration file for a particular class name matches the same
identifier in the rights list in the UAF, the communication
server is authorized to assign a request to that database
class server.
Process Pooling A-21
- MAX, MIN, and IDLE parameters
Assign values to the MIN, MAX, and IDLE parameters as your
applications require.
A.4.3.2 Programmer Tasks: Setting Up Database Servers
The sqlsrv_set_server_class routine allows a client application
to select the server class in which the application is processed.
Applications that exclusively use the generic class server do not
have to call the routine; the communication server automatically
assigns applications to the generic pool when applications do not
explicitly name a database class server. Thus, only applications
that use database class servers must call the routine.
Because a single application can create multiple associations,
programmers must be careful where in their applications the
sqlsrv_set_server_class routine is called. Once the routine is
called, the setting established by the call remains unchanged un-
til the routine is called again. For example, if you have three
associations in an application all using a different server class,
you must call the routine three separate times. In contrast,
if the associations all use the same server class, one call is
enough. In the first example you call the routine before each as-
sociation; in the second example you call the routine before the
first of three associations.
Follow these guidelines when using the sqlsrv_set_server_class
routine to set a server class:
o To change a database class setting to a generic class setting,
pass a C language NULL [0] value to the sqlsrv_set_server_class
routine, for example:
sqlsrv_set_server_class(null)
A-22 Process Pooling
o To change a generic class server to a database class server,
pass a database name to the sqlsrv_set_server_class routine,
for example:
sqlsrv_set_server_class("personnel")
The routine toggles between one database class and another or
between a database class and the generic class. VAX Rdb/VMS Guide
to Using SQL/Services provides programming information about the
sqlsrv_set_server_class routine.
A.4.4 The Dynamic Nature of Execution Servers
The number of generic and database execution server processes
in the process pool can expand and contract as the communication
server creates and deletes execution servers. The dynamic nature
of the pool depends on the idle time set in the configuration file
for each server class. The IDLE parameter sets the time that an
execution server process in a subpool can remain inactive (not
connected with a request). Three basic settings let you keep an
execution server process inactive indefinitely, have it deleted
immediately, or keep it inactive for a specified time before
deleting it. In general, the IDLE parameter acts as a system
resource manager by removing unproductive processes.
Process Pooling A-23
System managers can experiment with the IDLE parameter to see what
idle times work most effectively for their application environ-
ment. The three general settings for the IDLE parameter are listed
as follows:
o IDLE value n = -1
A -1 value indicates that execution servers in a subpool always
remain active. Once the communication server creates an execu-
tion server process, the process is never deleted. Thus, the
number of execution server processes in a subpool controlled by
an IDLE parameter value of -1 does not change after the maximum
number of execution server processes is reached. A -1 value
creates a static rather than a dynamic subpool.
This setting saves you from entering a high idle time when you
want execution server processes to remain active indefinitely.
o IDLE value n = 0
A zero value indicates that execution server processes are
deleted immediately after associations with API requests have
ended.
You can use this setting when a few API application accesses
are planned over an extended period, for example, a single
access at 8:00 a.m., 12:00 p.m., and 5:00 p.m.
o IDLE value n = +n
A positive IDLE value defines the amount of time that execu-
tion server processes remain idle (not associated with an API
request) before being deleted. You can assign a value equal to
the largest number allowed in a signed longword.
You can use this setting when you expect many API application
accesses over an extended time period. A positive IDLE value
enables the number of execution server processes to expand and
contract as application demand changes.
A-24 Process Pooling
A.5 Methods of Server Access
The communication server controls client application access to the
SQL/Services server system through the access options described
briefly in Table A-3.
Table_A-3:_Methods_of_Accessing_the_Server_System_________________
Access___Explanation______________________________________________
Explicit Allows application access to the server when the sqlsrv_
associate routine explicitly passes a valid node name,
user name, and password.
Proxy Allows application access when the node name is spec-
ified in a sqlsrv_associate routine call and an entry
exists for the incoming association request in the
SQLSRV$PROXY.DAT file. The proxy file resides in the
SYS$STARTUP directory.
Default Allows access to the SQLSRV$SRV default account when
proxy access is denied and the default account is en-
_________abled.___________________________________________________
In its gatekeeper role, the communication server performs a series
of authorization checks to determine whether or not to allow
client access to applications and if so, the type of access to
allow. The steps for authorizing client application access to the
server system are illustrated in Figure A-5.
Process Pooling A-25
__________________________________________________________________
A.6 How to Enable Server Access
The following sections describe how to enable client applica-
tion access to the server system by means of explicit access
(Section A.6.1), proxy-like access (Section A.6.2), and default
access (Section A.6.3).
A.6.1 Explicit Access
The communication server permits explicit access to a user account
on the server when two conditions are met:
o The client application passes the node name, user name, and
password in the sqlsrv_associate routine call.
o The node name specifies a valid server system and the user ac-
count information passed in the routine refers to an authorized
account on the server system.
If you want to allow only explicit server access to ensure maximum
system security, you must:
o Remove the SQLSRV$PROXY.DAT file in the SYS$STARTUP directory
or delete its entries, leaving an empty file.
o Use the SQLSRV_DEFAULT_ACCESS logical name to disable the
SQLSRV$SRV default account.
A-26 Process Pooling
A.6.2 SQL/Services Proxy Access
When the communication server does not find a user name or pass-
word in the sqlsrv_associate routine call, the server checks for
access authorization through entries in the SQLSRV$PROXY.DAT file
(an SQL/Services proxy file) located in the SYS$STARTUP direc-
tory. If the communication server does not find the file, finds a
file empty, or discovers that no proxy entries match the incoming
authorization information, SQL/Services proxy access is denied.
The SQL/Services proxy system uses the SQLSRV$PROXY.DAT file in
the SYS$STARTUP directory to store access entries. Entries in the
SQLSRV$PROXY.DAT file have the following format:
ADD/PROXY remote-node-name::remote-user-name local-user-name
Enter the remote node of the client system, followed by a set of
colons (::) and the user name for which you want to authorize
remote access. Finally, enter the user name of the local server
system account to which you are granting access privileges. Like
the VMS proxy system, you can use the wildcard character (*) for
the remote node or remote user name.
When you add entries to the SQLSRV$PROXY.DAT file, you must
reinitialize the system to effect the changes. You have to shut
down SQL/Services, edit the SQLSRV$PROXY.DAT file, and restart
SQL/Services. You must have access to an account with SETPRV priv-
ileges to perform these steps. Refer to Section A.7 for instruc-
tions on reinitializing the SQL/Services system to accommodate
changes in the proxy file.
To disable SQL/Services proxy access, delete the SQLSRV$PROXY.DAT
file or remove all of its entries. The changes take effect when
you reinitialize the SQL/Services system. Refer to Section A.7.
Process Pooling A-27
A.6.3 SQLSRV$SRV Default Account Access
The communication server permits access to the default account
when two conditions are met:
o Explicit access or proxy access has been denied.
o The SQLSRV$SRV default account is enabled.
The default account is enabled by default when SQL/Services is
installed. If you want to deny access to the SQLSRV$SRV account,
enter the following command at the DCL prompt:
$ DEFINE /SYSTEM /USER SQLSRV_DEFAULT_ACCESS DISABLE
You can also set the SQLSRV_DEFAULT_ACCESS logical name to disable
the default account in the SQLSRV$STARTUP.COM file. Disabling
the account from the SQL/Services startup file ensures that the
account is disabled whenever the system is running.
To enable the default account again, you must have access to an
account with SETPRV privileges. Refer to Section A.7 for instruc-
tions on reenabling the default account and reinitializing the
system to effect the change.
A.7 Reinitializing Proxy and Default Access
Perform the following steps to change the SQLSRV$PROXY.DAT file or
the default condition of the SQLSRV$SRV default account:
1. Shut down SQL/Services.
$ @SYS$STARTUP:SQLSRV$SHUTDOWN
The system prints a series of messages indicating the status of
the shutdown and the moment shutdown occurs.
2. Edit the SYS$STARTUP:SQLSRV$PROXY.DAT file or the startup file.
A-28 Process Pooling
If you want to modify the SQLSRV$PROXY.DAT file:
a. Edit the SQLSRV$PROXY.DAT file in the SYS$STARTUP directory
to add or delete entries.
b. Exit the file.
c. Go to step 3 to restart SQL/Services.
If you want to reenable the default account:
a. Use a text editor to remove (or comment out) the following
line from the SQLSRV$STARTUP.COM file in the SYS$STARTUP
directory:
$ DEFINE /SYSTEM /USER SQLSRV_DEFAULT_ACCESS DISABLE
b. Exit the file.
c. Go to step 3 to restart SQL/Services.
Removing the command to disable the default account automati-
cally enables the default account on system startup.
3. Restart SQL/Services to effect changes.
$ @SYS$STARTUP:SQLSRV$STARTUP
The system prints a series of messages indicating the status of
the startup procedure and indicates when startup is complete.
Process Pooling A-29