├── .github └── workflows │ └── docs.yml ├── .gitignore ├── .mergify.yml ├── .readthedocs.yml ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.rst ├── DEVELOP.rst ├── LICENSE ├── README.rst └── docs ├── Makefile ├── _extra └── robots.txt ├── _include └── note.rst ├── _no_vale ├── appendices ├── a.rst ├── b.rst ├── c.rst ├── d.rst ├── e.rst ├── f.rst ├── g.rst └── index.rst ├── build.json ├── chapters ├── 01.rst ├── 02.rst ├── 03.rst ├── 04.rst ├── 05.rst ├── 06.rst ├── 07.rst ├── 08.rst ├── 09.rst ├── 10.rst ├── 11.rst ├── 12.rst ├── 13.rst ├── 14.rst ├── 15.rst ├── 16.rst ├── 17.rst ├── 18.rst ├── 19.rst ├── 20.rst ├── 21.rst ├── 22.rst ├── 23.rst ├── 24.rst ├── 25.rst ├── 26.rst ├── 27.rst ├── 28.rst ├── 29.rst ├── 30.rst ├── 31.rst ├── 32.rst ├── 33.rst ├── 34.rst ├── 35.rst ├── 36.rst ├── 37.rst ├── 38.rst ├── 39.rst ├── 40.rst ├── 41.rst ├── 42.rst ├── 43.rst ├── 44.rst ├── 45.rst ├── 46.rst ├── 47.rst ├── 48.rst ├── 49.rst ├── 50.rst ├── 51.rst ├── 52.rst ├── 53.rst └── index.rst ├── conf.py ├── index.rst ├── preface.rst └── requirements.txt /.github/workflows/docs.yml: -------------------------------------------------------------------------------- 1 | name: docs 2 | on: 3 | pull_request: ~ 4 | push: 5 | branches: 6 | - main 7 | 8 | # Skip running redundant builds. 9 | concurrency: 10 | group: ${{ github.workflow }}-${{ github.ref }} 11 | cancel-in-progress: true 12 | 13 | jobs: 14 | documentation: 15 | name: Build docs on ${{ matrix.os }} 16 | runs-on: ${{ matrix.os }} 17 | 18 | strategy: 19 | matrix: 20 | os: [ubuntu-latest, macos-latest] 21 | 22 | steps: 23 | - name: Acquire sources 24 | uses: actions/checkout@v4 25 | 26 | - name: Set up Python 27 | uses: actions/setup-python@v4 28 | with: 29 | python-version: '3.11' 30 | 31 | - name: Build docs 32 | run: | 33 | cd docs && make check 34 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .build 2 | .clone 3 | .crate-docs 4 | .DS_Store 5 | .env 6 | .style 7 | *.lint 8 | -------------------------------------------------------------------------------- /.mergify.yml: -------------------------------------------------------------------------------- 1 | --- 2 | queue_rules: 3 | - name: default 4 | conditions: 5 | - check-success~=^Build docs on ubuntu-latest 6 | - check-success~=^Build docs on macos-latest 7 | - check-success~=docs/readthedocs.org 8 | 9 | pull_request_rules: 10 | - name: automatic merge 11 | conditions: 12 | - label=ready-to-merge 13 | - '#approved-reviews-by>=1' 14 | - status-success~=^Build docs on ubuntu-latest 15 | - status-success~=^Build docs on macos-latest 16 | - status-success~=docs/readthedocs.org 17 | actions: 18 | queue: 19 | method: rebase 20 | name: default 21 | -------------------------------------------------------------------------------- /.readthedocs.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | 3 | build: 4 | os: "ubuntu-22.04" 5 | tools: 6 | python: "3.11" 7 | 8 | sphinx: 9 | builder: html 10 | configuration: docs/conf.py 11 | fail_on_warning: true 12 | 13 | python: 14 | install: 15 | - requirements: docs/requirements.txt 16 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, sex characteristics, gender identity and expression, 9 | level of experience, education, socio-economic status, nationality, personal 10 | appearance, race, religion, or sexual identity and orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at support@crate.io. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 72 | 73 | [homepage]: https://www.contributor-covenant.org 74 | 75 | For answers to common questions about this code of conduct, see 76 | https://www.contributor-covenant.org/faq 77 | -------------------------------------------------------------------------------- /CONTRIBUTING.rst: -------------------------------------------------------------------------------- 1 | ============ 2 | Contributing 3 | ============ 4 | 5 | Thank you for your interest in contributing. 6 | 7 | Please see the CrateDB `contribution guide`_ for more information. Everything 8 | in the CrateDB contribution guide applies to this repository. 9 | 10 | That this is a digital copy of a book that has already gone to print. As such, 11 | we will only accept changes that affect the building or the presentation of the 12 | work. Errata should be submitted elsewhere. 13 | 14 | .. _contribution guide: https://github.com/crate/crate/blob/master/CONTRIBUTING.rst 15 | -------------------------------------------------------------------------------- /DEVELOP.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | Developer Guide 3 | =============== 4 | 5 | The project is written using `Sphinx`_ and `ReStructuredText`_. 6 | 7 | 8 | Working on the project 9 | ====================== 10 | 11 | You will need a recent installation of Python 3. 12 | 13 | Change into the ``docs`` directory: 14 | 15 | .. code-block:: console 16 | 17 | $ cd docs 18 | 19 | For help, run: 20 | 21 | .. code-block:: console 22 | 23 | $ make 24 | 25 | Crate Docs Build 26 | 27 | Run `make `, where is one of: 28 | 29 | dev Run a Sphinx development server that builds and lints the 30 | documentation as you edit the source files 31 | 32 | html Build the static HTML output 33 | 34 | check Build, test, and lint the documentation 35 | 36 | reset Reset the build cache 37 | 38 | You must install `fswatch`_ to use the ``dev`` target. 39 | 40 | 41 | Continuous integration and deployment 42 | ===================================== 43 | 44 | |build| |rtd| 45 | 46 | This project uses GitHub Actions to run make check from the docs directory. 47 | 48 | Also, Read the Docs automatically rebuilds the documentation whenever an active docs branch is updated. 49 | 50 | To make changes to the RTD configuration (e.g., to activate or deactivate a release version), please contact an admin. 51 | 52 | .. _fswatch: https://github.com/emcrisostomo/fswatch 53 | .. _Read the Docs: http://readthedocs.org 54 | .. _ReStructuredText: http://docutils.sourceforge.net/rst.html 55 | .. _Sphinx: http://sphinx-doc.org/ 56 | 57 | 58 | .. |build| image:: https://img.shields.io/endpoint.svg?color=blue&url=https%3A%2F%2Fraw.githubusercontent.com%2Fcrate%2Fsql-99%2Fmaster%2Fdocs%2Fbuild.json 59 | :alt: Build version 60 | :target: https://github.com/crate/sql-99/blob/main/docs/build.json 61 | 62 | .. |rtd| image:: https://readthedocs.org/projects/sql-99/badge/?version=latest 63 | :alt: Read The Docs status 64 | :scale: 100% 65 | :target: https://sql-99.readthedocs.io/en/latest/?badge=latest 66 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | SQL-99 Complete, Really 2 | Copyright (c) 2005-2016 Trudy Pelzer & Peter Gulutzan. 3 | All rights reserved. 4 | 5 | Redistribution and use in source and 'compiled' forms (PDF, PostScript, HTML, 6 | RTF, etc), with or without modification, are permitted provided that the 7 | following conditions are met: 8 | 9 | 1. Redistributions of source code must retain the above copyright notice, this 10 | list of conditions and the following disclaimer as the first lines of this file 11 | unmodified. 12 | 13 | 2. Redistributions in compiled form (transformed to other DTDs, converted to 14 | PDF, PostScript, HTML, RTF, and other formats) must reproduce the above 15 | copyright notice, this list of conditions and the following disclaimer in the 16 | documentation and/or other materials provided with the distribution. 17 | 18 | 3. The name of the author may not be used to endorse or promote products 19 | derived from this documentation without specific prior written permission. 20 | 21 | THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED 22 | WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 23 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO 24 | EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 | EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 26 | OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27 | INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 29 | IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE 30 | POSSIBILITY OF SUCH DAMAGE. 31 | 32 | 33 | =============================================================================== 34 | 35 | Designations used by companies to distinguish their products are often claimed 36 | as trademarks. In all instances where authors are aware of a trademark claim, 37 | the product name appears in initial capital letters, in all capital letters, or 38 | in accordance with the vendor's capitalization preference. Readers should 39 | contact the appropriate companies for more complete information on trademarks 40 | and trademark registrations. All trademarks and registered trademarks in this 41 | book are the property of their respective holders. 42 | 43 | Copyright (c) 1999 by Ocelot Computer Services Incorporated, except where 44 | noted otherwise. Published by Ocelot Computer Services Incorporated. All rights 45 | reserved. No part of this publication may reproduced or distributed in any form 46 | or by any means, or stored in a database or retrieval system, without the prior 47 | written permission of the publisher; with the exception that the program 48 | listings may be entered, stored, and executed in a computer system, but they 49 | may not be reproduced for publication. 50 | 51 | The programs in this book are presented for instructional value. The programs 52 | have been carefully tested, but are not guaranteed for any particular purpose. 53 | The publisher does not offer any warranties and does not guarantee the 54 | accuracy, adequacy, or completeness of any information herein and is not 55 | responsible for any errors or omissions. The publisher assumes no liability for 56 | damages resulting from the use of the information in this book or for any 57 | infringement of the intellectual property rights of third parties that would 58 | result from the use of this information. 59 | 60 | Trademarks: 61 | 62 | Access: Microsoft Corp. 63 | DB2: International Business Machines Corp. 64 | dBASE IV: Inprise Corporation 65 | Delphi: Inprise Corporation 66 | Informix: Informix Corporation 67 | Ingres: Computer Associates International Inc. 68 | Java: Sun Microsystems Inc. 69 | Ocelot, OCELOT DBMS: Ocelot Computer Services Inc. 70 | Oracle: Oracle Corp. 71 | Paradox: Inprise Corporation 72 | SQL Server: Sybase, Inc. 73 | SQL/DS: International Business Machines Corp. 74 | Unicode: Unicode, Inc. 75 | Windows, Windows95, WindowsNT, SQL Server: Microsoft Corp. 76 | 77 | All trademarks (those above and any others mentioned in this book) are the 78 | property of their respective owners. 79 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | SQL-99 Complete, Really 3 | ======================= 4 | 5 | A digital copy of `SQL-99 Complete, Really`_. 6 | 7 | 8 | Contributing 9 | ============ 10 | 11 | This project is primarily maintained by Crate.io_, but we welcome community 12 | contributions! 13 | 14 | See the `developer docs`_ and the `contribution docs`_ for more information. 15 | 16 | 17 | Help 18 | ==== 19 | 20 | Looking for more help? 21 | 22 | - Read the `project docs`_ 23 | - Check out our `support channels`_ 24 | 25 | 26 | .. _contribution docs: CONTRIBUTING.rst 27 | .. _Crate.io: http://crate.io/ 28 | .. _developer docs: DEVELOP.rst 29 | .. _project docs: https://crate.io/docs/sql-99/en/latest/ 30 | .. _SQL-99 Complete, Really: https://openlibrary.org/books/OL8128443M/SQL-99_Complete_Really 31 | .. _support channels: https://crate.io/support/ 32 | -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | # Licensed to Crate (https://crate.io) under one or more contributor license 2 | # agreements. See the NOTICE file distributed with this work for additional 3 | # information regarding copyright ownership. Crate licenses this file to you 4 | # under the Apache License, Version 2.0 (the "License"); you may not use this 5 | # file except in compliance with the License. You may obtain a copy of the 6 | # License at 7 | # 8 | # http://www.apache.org/licenses/LICENSE-2.0 9 | # 10 | # Unless required by applicable law or agreed to in writing, software 11 | # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 12 | # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 13 | # License for the specific language governing permissions and limitations under 14 | # the License. 15 | # 16 | # However, if you have executed another commercial license agreement with Crate 17 | # these terms will supersede the license and you may use the software solely 18 | # pursuant to the terms of the relevant commercial agreement. 19 | 20 | 21 | # ============================================================================= 22 | # Crate Docs 23 | # ============================================================================= 24 | 25 | # The Crate Docs project provides a common set of tools for producing the 26 | # Crate.io documentation. See for more 27 | # information. 28 | 29 | # This file is taken from the demo Sphinx project available at 30 | # . This demo docs project 31 | # provides a reference implementation that should be copied for all Sphinx 32 | # projects at Crate.io. 33 | 34 | # The Crate Docs build system works by centralizing its core components in the 35 | # `crate-docs` repository. At build time, this Makefile creates a copy of the 36 | # this project under the `.crate-docs` directory. This Makefile is an interface 37 | # for those core components. 38 | 39 | 40 | # Upgraded instructions 41 | # ----------------------------------------------------------------------------- 42 | 43 | # You must pin your Sphinx project to a specific version of the Crate Docs 44 | # project. You can do this by editing the `build.json` file. Change the JSON 45 | # `message` value to the desired release number. A list of releases is 46 | # available at . 47 | 48 | # Although care has been taken to restrict changes to the core components, you 49 | # may occasionally need to update your project to match the reference 50 | # implementation. Check the release notes for any special instructions. 51 | 52 | 53 | # Project-specific customization 54 | # ============================================================================= 55 | 56 | # If you want to customize the build system for your Sphinx project, add lines 57 | # to this section. 58 | 59 | 60 | # Build system integration 61 | # ============================================================================= 62 | 63 | # This is a boilerplate section is required for integration with the Crate Docs 64 | # build system. All Sphinx projects using a the same Crate Docs version 65 | # should have exactly the same boilerplate. 66 | 67 | # IF YOU ARE EDITING THIS FILE IN A REAL SPHINX PROJECT, YOU SHOULD NOT MAKE 68 | # ANY CHANGES TO THIS SECTION. 69 | 70 | # If you want to make changes to the boilerplate, please make a pull request on 71 | # the demo Sphinx project in the Crate Docs repository available at 72 | # . 73 | 74 | .EXPORT_ALL_VARIABLES: 75 | 76 | DOCS_DIR := docs 77 | TOP_DIR := .. 78 | BUILD_JSON := build.json 79 | BUILD_REPO := https://github.com/crate/crate-docs.git 80 | LATEST_BUILD := https://github.com/crate/crate-docs/releases/latest 81 | CLONE_DIR := .crate-docs 82 | SRC_DIR := $(CLONE_DIR)/common-build 83 | SELF_SRC := $(TOP_DIR)/common-build 84 | SELF_MAKEFILE := $(SELF_SRC)/rules.mk 85 | SRC_MAKE := $(MAKE) -f $(SRC_DIR)/rules.mk 86 | 87 | # Parse the JSON file 88 | BUILD_VERSION := $(shell cat $(BUILD_JSON) | \ 89 | python -c 'import json, sys; print(json.load(sys.stdin)["message"])') 90 | 91 | ifeq ($(BUILD_VERSION),) 92 | $(error No build version specified in `$(BUILD_JSON)`.) 93 | endif 94 | 95 | # This is a non-essential check so we timeout after only two seconds so as not 96 | # to frustrate the user when there are network issues 97 | LATEST_VERSION := $(shell curl -sI --connect-timeout 2 '$(LATEST_BUILD)' | \ 98 | grep -i 'Location:' | grep -Eoh '[^/]+$$') 99 | 100 | # Skip if no version could be determined (i.e., because of a network error) 101 | ifneq ($(LATEST_VERSION),) 102 | # Only issue a warning if there is a version mismatch 103 | ifneq ($(BUILD_VERSION),$(LATEST_VERSION)) 104 | define version_warning 105 | You are using Crate Docs version $(BUILD_VERSION), however version \ 106 | $(LATEST_VERSION) is available. You should consider upgrading. Follow the \ 107 | instructions in `Makefile` and then run `make reset`. 108 | endef 109 | endif 110 | endif 111 | 112 | # Default rule 113 | .PHONY: help 114 | help: $(CLONE_DIR) 115 | @ $(MAKE) version-warn 116 | @ $(SRC_MAKE) $@ 117 | 118 | .PHONY: version-warn 119 | version-warn: 120 | @ # Because version numbers may vary in length, we must wrap the warning 121 | @ # message at run time to be sure of correct output 122 | @ if test -n '$(version_warning)'; then \ 123 | printf '\033[33m'; \ 124 | echo '$(version_warning)' | fold -w 79 -s; \ 125 | printf '\033[00m\n'; \ 126 | fi 127 | 128 | ifneq ($(wildcard $(SELF_MAKEFILE)),) 129 | # The project detects itself and fakes an install of its own core build rules 130 | # so that it can test itself 131 | $(CLONE_DIR): 132 | @ printf '\033[1mInstalling the build system...\033[00m\n' 133 | @ mkdir -p $@ 134 | @ cp -R $(SELF_SRC) $(SRC_DIR) 135 | @ printf 'Created: $(CLONE_DIR)\n' 136 | else 137 | # All other projects install a versioned copy of the core build rules 138 | $(CLONE_DIR): 139 | @ printf '\033[1mInstalling the build system...\033[00m\n' 140 | @ git clone --depth=1 -c advice.detachedHead=false \ 141 | --branch=$(BUILD_VERSION) $(BUILD_REPO) $(CLONE_DIR) 142 | @ printf 'Created: $(CLONE_DIR)\n' 143 | endif 144 | 145 | # Don't pass through this target 146 | .PHONY: Makefile 147 | Makefile: 148 | 149 | # By default, pass targets through to the core build rules 150 | .PHONY: 151 | %: $(CLONE_DIR) 152 | @ $(MAKE) version-warn 153 | @ $(SRC_MAKE) $@ 154 | 155 | .PHONY: reset 156 | reset: 157 | @ printf '\033[1mResetting the build system...\033[00m\n' 158 | @ rm -rf $(CLONE_DIR) 159 | @ printf 'Removed: $(CLONE_DIR)\n' 160 | -------------------------------------------------------------------------------- /docs/_extra/robots.txt: -------------------------------------------------------------------------------- 1 | User-agent: * 2 | Disallow: 3 | 4 | Sitemap: https://sql-99.readthedocs.io/en/latest/site.xml 5 | -------------------------------------------------------------------------------- /docs/_include/note.rst: -------------------------------------------------------------------------------- 1 | .. NOTE:: 2 | 3 | You are reading a digital copy of *SQL-99 Complete, Really*, a book that 4 | documents the `SQL-99 standard`_. 5 | 6 | The book and the standard does not reflect the features of CrateDB, 7 | we are just publishing it as a service for the community and for reference 8 | purposes. 9 | 10 | On the one hand, CrateDB does not implement the SQL-99 standard thoroughly, 11 | on the other hand, it extends the standard for implementing cluster features 12 | and others. 13 | 14 | For more information specific to CrateDB, check out the `CrateDB 15 | Reference`_ documentation. 16 | 17 | .. _CrateDB Reference: https://cratedb.com/docs/crate/reference/en/latest/general/index.html 18 | .. _SQL-99 standard: https://en.wikipedia.org/wiki/SQL:1999 19 | -------------------------------------------------------------------------------- /docs/_no_vale: -------------------------------------------------------------------------------- 1 | Existence of this file disables Vale lint checks 2 | -------------------------------------------------------------------------------- /docs/appendices/d.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | =========================================== 4 | Appendix D -- Incompatibilities with SQL-92 5 | =========================================== 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | SQL3 is compatible with the former version of the Standard (SQL-92) except in 10 | the following cases. 11 | 12 | * In SQL-92, a had a deprecated alternative 13 | ``...`` (i.e.: a parameter list not surrounded by 14 | parentheses and with the component parameter declarations not separated by 15 | commas). SQL3 does not contain this option. 16 | 17 | * In SQL-92, if one or more rows deleted or updated through some Cursor are 18 | later updated or deleted through some other Cursor by a , by an or by some or 20 | of some , no exception 21 | condition is raised and no completion condition (other than successful 22 | completion) is raised. In SQL3, a completion condition is raised: 23 | warning-cursor operation conflict. 24 | 25 | * In SQL-92, there were two s provided: the deprecated 26 | ``SQLCODE`` and ``SQLSTATE``. SQL3 does not support the ``SQLCODE`` and ``SQLCODE`` is no longer a reserved . 28 | 29 | * SQL-92 allowed you to omit the semicolon at the end of ; 30 | listing this as a deprecated feature. In SQL3, the semicolon at the end of 31 | is mandatory. 32 | 33 | * In SQL-92, it was possible for applications to define new Character sets, 34 | Collations and Translations. In SQL3, those capabilities are limited to 35 | defining new Character sets, Collations and Translations that are identical to 36 | existing Character sets, Collations and Translations, respectively, except for 37 | their names and other minor details. 38 | 39 | * In SQL-92, it was possible for applications to specify the Character set 40 | associated with an using: ``_``. 41 | SQL3 no longer supports that capability. 42 | 43 | * In SQL-92, it was possible to sort a Cursor by a Column's ordinal position 44 | in the Cursor. SQL3 no longer supports that capability. 45 | 46 | * SQL3 contains more reserved s than SQL-92. The new reserved 47 | s are: 48 | 49 | :: 50 | 51 | ABS 52 | ACTION 53 | AFTER 54 | AGGREGATE 55 | ALIAS 56 | ARRAY 57 | BEFORE 58 | BINARY 59 | BLOB 60 | BOOLEAN 61 | BREADTH 62 | CALL 63 | CARDINALITY 64 | CLOB 65 | COMPLETION 66 | CONCATENATE 67 | CUBE 68 | CURRENT_PATH 69 | CYCLE 70 | DATA 71 | DEPTH 72 | DEREF 73 | DESTROY 74 | DICTIONARY 75 | EACH 76 | EQUALS 77 | EVERY 78 | FACTOR 79 | FREE 80 | GENERAL 81 | GROUPING 82 | HOLD 83 | HOST 84 | IGNORE 85 | INITIALIZE 86 | ITERATE 87 | LESS 88 | LARGE 89 | LIMIT 90 | LOCATOR 91 | MOD 92 | MODIFIES 93 | MODIFY 94 | NCLOB 95 | NEW 96 | NO 97 | NONE 98 | OBJECT 99 | OFF 100 | OLD 101 | OPERATION 102 | OPERATOR 103 | ORDINALITY 104 | OVERLAY 105 | PARAMETER 106 | PARAMETERS 107 | PATH 108 | PREORDER 109 | READS 110 | RECURSIVE 111 | REF 112 | REFERENCING 113 | REPLACE 114 | RESULT 115 | RETURN 116 | RETURNS 117 | ROLLUP 118 | ROLE 119 | ROUTINE 120 | ROW 121 | SAVEPOINT 122 | SEARCH 123 | SENSITIVE 124 | SEQUENCE 125 | SESSION 126 | SETS 127 | SIMILAR 128 | SPACE 129 | SPECIFIC 130 | SPECIFICTYPE 131 | SQLEXCEPTION 132 | SQLWARNING 133 | START 134 | STATE 135 | STRUCTURE 136 | SUBLIST 137 | SYMBOL 138 | TERM 139 | TERMINATE 140 | THE 141 | TREAT 142 | TRIGGER 143 | TYPE 144 | UNDER 145 | VARIABLE 146 | WITHOUT 147 | -------------------------------------------------------------------------------- /docs/appendices/e.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | =========================== 4 | Appendix E -- SQL Web Sites 5 | =========================== 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | You will get millions of hits if you submit the keyword SQL to any Internet 10 | search engine. You will get only 12 hits from this list. But they all have one 11 | interesting common feature: FREE STUFF. Our list of SQL web sites includes: 12 | 13 | * Private companies which produce SQL databases or SQL-related programs, 14 | and which allow downloads of real working programs. 15 | 16 | * Both government and private bodies which produce SQL-related 17 | standards. 18 | 19 | * Sites which offer timely and real SQL news. 20 | 21 | Our selection is primarily of English-speaking sites. As URLs change, and as 22 | new sites match our criteria, we will update a copy of this list at our own 23 | web site: https://web.archive.org/web/20021015234703/http://ourworld.compuserve.com/homepages/OCELOTSQL/sites.htm 24 | 25 | So probably your best way to keep up-to-date is to add our web site to your 26 | favourite places, and click links from there. 27 | 28 | Here's the list: 29 | 30 | * | **Beagle SQL** 31 | | http\://www.beaglesql.com/ (dead) 32 | | Strictly a work in progress. Linux oriented. 33 | 34 | * | **Gnu SQL** 35 | | http\://www.ispras.ru/~kml/gss (dead) 36 | | Alpha. The usual gnu software license. 37 | 38 | * | **Intelligent Enterprise Journal** 39 | | http\://www.intelligententerprise.com/ (dead) 40 | | An online regular database magazine. 41 | 42 | * | **ISO** 43 | | ftp\://jerry.ece.umassd.edu/ (dead) 44 | | This is the archive site for ISO standards committee minutes and memoranda. 45 | 46 | * | **Microsoft** 47 | | https://msdn.microsoft.com/en-us/dn308572.aspx 48 | | You can get the ODBC manual from here, as a .hlp file. 49 | 50 | * | **miniSQL** 51 | | http://www.hughes.com.au/ 52 | | A Unix-oriented SQL-89 implementation. 53 | 54 | * | **NIST** 55 | | http\://speckle.ncsl.nist.gov/~ftp/sql-testing (dead) 56 | | A large group of SQL conformance tests (C source code). Somewhat dated. 57 | 58 | * | **MySQL** 59 | | https://www.mysql.com/ 60 | | Another Unix-oriented SQL-89 implementation. 61 | 62 | * | **Ocelot** 63 | | http\://ourworld.compuserve.com/homepages/OCELOTSQL (dead) 64 | | Any errata for this book, plus updated copy of this list, plus downloads. 65 | 66 | * | **Oracle** 67 | | http://www.oracle.com/ 68 | | Apparently you can download 30-day free trials (we didn't try). 69 | 70 | * | **PostreSQL** 71 | | http://www.postgresql.org/ 72 | | One of the few "free" SQL implementations that supports UDTs. 73 | 74 | * | **Sun** 75 | | https://www.oracle.com/technetwork/java/javase/tech/index-jsp-136101.html 76 | | Get a copy of the test suite for the JDBC here. 77 | 78 | * | **Unicode** 79 | | http://www.unicode.org/ 80 | | Look for "code charts". 81 | 82 | * | **Yard** 83 | | http\://www.yard.de/ (dead) 84 | | "Yard SQL" is free for educational institutions. 85 | -------------------------------------------------------------------------------- /docs/appendices/g.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | ==================== 4 | Appendix G -- Errata 5 | ==================== 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | This concise errata list concerns apparent errors in some of our source 10 | literature, such as the SQL standard documents or the ODBC manual. We do not 11 | intend this as a comment. Like any errata list, its sole use is to help you 12 | avoid confusion if you happen to read one of those texts. And, like any errata 13 | list, it's ephemeral. At some time, the original documents will cease to 14 | contain these errors. 15 | 16 | .. rubric:: Table of Contents 17 | 18 | .. contents:: 19 | :local: 20 | 21 | SQL Foundation 22 | ============== 23 | 24 | * The data type and size of ``CURRENT_ROLE`` is not defined, but we have 25 | assumed that it's supposed to match the data type and size defined for 26 | ``CURRENT_USER``. 27 | 28 | * The Standard declares that precision is the number of "significant digits". 29 | We have to assume they don't use the usual definition of significant. 30 | 31 | * The Standard speaks of valid datetime or interval results "according to the 32 | Gregorian calendar". But the Gregorian calendar only validates dates. We 33 | assume they mean "based on a 24 hour clock" for times, with adjustments 34 | according to the Gregorian calendar in the case of timestamps and (where 35 | applicable) intervals. 36 | 37 | * The word "satisfies" means "is ``TRUE``" when the context is the ``HAVING`` 38 | clause, or "is not ``FALSE``" when the context is a constraint. But it is not 39 | clear what "satisfies" means when the context is a ``WHEN`` clause or a 40 | view's ``WITH CHECK OPTION`` clause. Therefore it is not possible to be sure 41 | whether these clauses are "satisfied" if the search conditions that they 42 | refer to are ``UNKNOWN``. 43 | 44 | * SQL3's ``BOOLEAN`` data type should have four values: ``TRUE``, ``FALSE``, 45 | ``UNKNOWN`` and ``NULL``. 46 | 47 | * For "effect of replacing rows in base tables", the trigger event is defined 48 | as ``DELETE``. We assume that ``UPDATE`` is meant. 49 | 50 | * The ``DROP TABLE ... CASCADE`` definition fails to specify that all dependent 51 | triggers will also be dropped. The ``DROP TABLE ... RESTRICT`` definition 52 | fails to specify that, if there are dependent triggers, the drop will fail. 53 | Since analogous statements are true for ``DROP VIEW``, we assume that they 54 | should also be true for ``DROP TABLE``. 55 | 56 | * The Standard states six times that the following statement, or a slight 57 | variation thereof, is "implicit" (in column definitions etc.): 58 | 59 | :: 60 | 61 | "CREATE TRIGGER BTN BEFORE DELETE ON TND 62 | FOR EACH STATEMENT 63 | SET CONSTRAINT CCN DEFERRED" 64 | 65 | But ``SET CONSTRAINT`` statements are illegal within triggers. 66 | 67 | * According to the Standard, ``DROP TRIGGER`` is legal in Core SQL; but 68 | ``CREATE TRIGGER`` is illegal. We assume that the intent is not to include 69 | ``DROP TRIGGER`` in Core SQL either. 70 | 71 | * In the description of there is a reference to an 72 | ``SQLSTATE error 'Data exception - invalid interval format'``; this error 73 | does not appear in the list of ``SQLSTATE`` exception conditions so we 74 | haven't been able to provide an ``SQLSTATE`` code for it. 75 | 76 | * The ``ASCII_FULL`` character set does not include the ``\0`` character. This 77 | contradicts FIPS, and makes casts from bit strings difficult. 78 | 79 | * The Standard's Section 9.7 has no mention of 80 | ``BOOLEAN``. Neither does Section 10.14. ``BOOLEAN`` appears to have been 81 | forgotten in many places. 82 | 83 | * There is an initial definition of "subtype". The Standard's description of 84 | UDTs is comprehensible only if this definition is ignored. 85 | 86 | * The Standard's definition of "direct subtype" is confusing: 87 | 88 | "A type ``T(a)`` 89 | is a direct subtype of a type ``T(b)`` if ``T(a)`` is a proper subtype of 90 | ``T(b)`` and there does not exist a type ``T(c)`` such that ``T(c)`` is a 91 | proper subtype of ``T(b)`` and a proper subtype of ``T(a)``." 92 | 93 | Perhaps it should read: 94 | 95 | "A type ``T(a)`` is a direct subtype of a type ``T(b)`` if ``T(a)`` is a 96 | proper subtype of ``T(b)`` and there does not exist a type ``T(c)`` such that 97 | ``T(c)`` is a proper subtype of ``T(b)`` and a proper supertype of ``T(a)``." 98 | 99 | If this emendation is correct, then the terms "every direct supertype" and 100 | "every direct supertable" are misleading; more English are the terms "the 101 | direct supertype" and "the direct supertable", passim. 102 | 103 | * The ``CREATE TYPE`` definition contains a contradiction: 104 | 105 | :: 106 | 107 | "4) If is not specified, then shall be specified. 108 | 5) If is not specified, then NOT FINAL shall be specified. 109 | 6) If specifies , then: 110 | a) ... 111 | b) FINAL shall be specified. 112 | c) shall not be specified." 113 | 114 | We have made no assumption as to the Standard's intent here. 115 | 116 | * The ``BNF`` nonterminal is defined differently in two 117 | separate sections. We have made no assumption as to which definition is the 118 | correct one. 119 | 120 | * For the ``NEW`` statement, the Standard contains this suspicious looking 121 | grammer: 122 | 123 | :: 124 | 125 | " ::= NEW 126 | 127 | ::= " 128 | 129 | is not used elsewhere. We assume that the definition is 130 | actually "``NEW`` ". 131 | 132 | If this assumption is incorrect, the first syntax rule for the ``NEW`` 133 | statement seems like it would work only for the main option: 134 | 135 | "1) Let ``RN`` be the immediately contained in the . Let ``MN`` be the immediately contained in 137 | ``RN``." 138 | 139 | Possibly what is meant is: 140 | 141 | "1) Let ``RN`` be the immediately contained in the or . Let ``MN`` be the 143 | immediately contained in ``RN``." 144 | 145 | * This note looks out of place, and in any case is superseded by Note 243: 146 | 147 | "NOTE 242 - The comparison categories of two user-defined types in the same 148 | type family must be the same." 149 | 150 | Possibly what is meant is: 151 | 152 | "NOTE 242 - The comparison forms of two user-defined types in the same 153 | type family must be the same." 154 | 155 | * The ``INFORMATION_SCHEMA.ATTRIBUTES`` view definition contains references to 156 | ``TABLE_CATALOG`` and ``COLUMN_DEFAULT`` columns -- neither of which are 157 | applicable here. We assume they should be ``UDT_CATALOG`` and 158 | ``ATTRIBUTE_DEFAULT``. 159 | 160 | * The ``DEFINITION_SCHEMA.ATTRIBUTES`` base table is also defined as having two 161 | columns -- ``TABLE_CATALOG`` and ``TABLE_SCHEMA`` -- which are not applicable 162 | here. We assume they should be ``UDT_CATALOG`` and ``UDT_SCHEMA``. 163 | 164 | Also, this table's columns ``USER_DEFINED_TYPE_CATALOG``, 165 | ``USER_DEFINED_TYPE_SCHEMA`` and ``USER_DEFINED_TYPE_NAME`` are defined on 166 | domain ``INFORMATION_SCHEMA.CHARACTER_DATA``. 167 | 168 | But everywhere else, such columns are defined on domain 169 | ``INFORMATION_SCHEMA.SQL_IDENTIFIER``. We assume the intent is to be 170 | consistent here as well. 171 | 172 | * The ``NUMERIC_PRECISION_RADIX`` value for datetime / interval data types is 173 | unclear. The ``GetTypeInfo`` description of the ODBC 3.0 manual says: "If the 174 | data type is an approximate numeric type, this column contains the value 175 | ``2`` to indicate that ``COLUMN_SIZE`` specifies a number of bits. For exact 176 | numeric types, this column contains the value ``10`` to indicate that 177 | ``COLUMN_SIZE`` specifies a number of decimal digits. Otherwise, this column 178 | is ``NULL``." 179 | 180 | The same section in the SQL/CLI document says: 181 | 182 | :: 183 | 184 | "r) The value of NUM_PREC_RADIX is 185 | Case: 186 | i) If the value of PRECISION is the value of a precision, then the radix of that precision. 187 | ii) Otherwise, the null value." 188 | 189 | While the definition of the ``DEFINITION_SCHEMA.DATA_TYPE_DESCRIPTOR`` base 190 | table, where this information is stored has this constraint: 191 | 192 | :: 193 | 194 | " CHECK ( 195 | ... 196 | DATA_TYPE IN ( 'DATE', 'TIME', 'TIMESTAMP', 197 | 'TIME WITH TIME ZONE', 'TIMESTAMP WITH TIME ZONE' ) 198 | ... 199 | AND ( NUMERIC_PRECISION, NUMERIC_PRECISION_RADIX ) IS NOT NULL" 200 | 201 | From the above quotes, some disagreements are visible: 202 | 203 | (a) The writers of ODBC thought datetime/interval radices are nullable. 204 | 205 | (b) The SQL/CLI writers had no idea ``PRECISION`` is a nonexistent column 206 | but agree that radices can be nullable if a data type has no precision. 207 | 208 | (c) The foundation writers thought datetime/interval radices couldn't be ``NULL``. 209 | 210 | For ``GET_TYPE_INFO``, we assume the first two quotes reflect the true 211 | intent: that ``NUMERIC_PRECISION_RADIX`` value for datetimes and intervals is 212 | ``NULL``. 213 | 214 | * The definition of the ``INFORMATION_SCHEMA.ROLE_ROUTINE_GRANTS`` view 215 | contains: 216 | 217 | :: 218 | 219 | "SELECT 220 | ... 221 | ROUTINE_CATALOG, ROUTINE_SCHEMA, ROUTINE_NAME 222 | ... 223 | FROM ROUTINE_PRIVILEGES" 224 | 225 | But these three columns do not exist in the ``ROUTINE_PRIVILEGES`` table. We 226 | assume these columns should be omitted from the view. 227 | 228 | * The definition of the ``INFORMATION_SCHEMA.ROLE_USER_DEFINED_TYPE_GRANTS`` 229 | view contains: 230 | 231 | :: 232 | 233 | "SELECT 234 | ... 235 | OBJECT_TYPE 236 | ... 237 | FROM DEFINITION_SCHEMA.USER_DEFINED_TYPE_PRIVILEGES" 238 | 239 | But this column does not exist the in ``USER_DEFINED_TYPE_PRIVILEGES`` table. 240 | We assume this column should be omitted from the view. 241 | 242 | SQL/CLI 243 | ======= 244 | 245 | * The "Description of CLI item descriptors" says that ``DEFERRED`` is true if 246 | the octet length pointer points to ``SQL NULL DATA``. 247 | 248 | * For ``SQLGetTypeInfo``, ``NULL`` values are returned for ``sql_prefix`` and 249 | ``sql_suffix`` -- i.e.: ``NULL`` is used to mean "blank string". In other 250 | fields it means N/A. 251 | 252 | * For ``SQLExecute`` and ``SQLExecute``, the general rules are ordered in such 253 | a way that input parameters will be checked for consistency ``AFTER`` 254 | execution. We assume that checking should take place before execution. The 255 | embedded SQL document has parameter-checking in the logical place. 256 | 257 | * The ``SQLDisconnect`` function description contains a reference to an 258 | exception "active SQL-statement"; we assume this should read "active 259 | SQL-transaction". 260 | 261 | * The ``SQLGetData`` function description contains a reference to ``IP`` and 262 | ``DP``, which do not exist. 263 | 264 | * The ``SQLSetDescField`` function description suggests that it is illegal to 265 | set the ``SQL_DESC_TYPE`` field to ``SQL_SMALLINT``, ``SQL_INTEGER``, 266 | ``SQL_REAL`` or ``SQL_DOUBLE_PRECISION`` (or several other legal data types). 267 | This is clearly an oversight. 268 | 269 | * The ``SQLSetDescField`` function description fails to state that the 270 | ``RecordNumber`` parameter should be ignored if ``FieldIdentifier`` is 271 | ``SQL_DESC_COUNT``. We assume this is the case. 272 | 273 | * The ``SQLGetDescRec`` function description is ambiguous about the field to be 274 | used as the source for Length. 275 | 276 | * For ``SQLGetDiagField``, the Standard says ``SQL_DIAG_MORE`` is associated 277 | with a return of ``'Y'`` or ``'N'``. But ``SQL_DIAG_MORE`` is not defined as 278 | a string. 279 | 280 | * For ``SQLGetLength``: exception "Invalid argument value" is undefined. 281 | 282 | * For ``SQLColumns``: for a , the value is taken 283 | from ``INFORMATION_SCHEMA.COLUMNS.NUMERIC_PRECISION``. The value is actually 284 | in ``INFORMATION_SCHEMA.COLUMNS.DATETIME_PRECISION`` and we assume this is 285 | the intent. Also: the ``SQL_DATA_TYPE`` column has been forgotten; we assume 286 | it is included. Also: for calculating ``SQL_DATETIME_SUB``, the Standard says 287 | one is supposed to use ``INFORMATION_SCHEMA.COLUMNS.DATA_TYPE`` to look up a 288 | ``'Code'`` -- however, the information is actually in found in 289 | ``INFORMATION_SCHEMA.COLUMNS.INTERVAL_TYPE``; we assume this is the intent. 290 | 291 | * There is an implicit assumption that ``CAST`` is possible between two 292 | character sets (otherwise, why bother having character set in the 293 | descriptor IDA?). But ``CAST`` is illegal if repertoires differ. 294 | -------------------------------------------------------------------------------- /docs/appendices/index.rst: -------------------------------------------------------------------------------- 1 | .. _appendices: 2 | 3 | ========== 4 | Appendices 5 | ========== 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | .. rubric:: Table of Contents 10 | 11 | .. toctree:: 12 | :maxdepth: 3 13 | 14 | a 15 | b 16 | c 17 | d 18 | e 19 | f 20 | g 21 | -------------------------------------------------------------------------------- /docs/build.json: -------------------------------------------------------------------------------- 1 | { 2 | "schemaVersion": 1, 3 | "label": "docs build", 4 | "message": "2.1.1" 5 | } 6 | -------------------------------------------------------------------------------- /docs/chapters/12.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | ============================= 4 | Chapter 12 -- Reference types 5 | ============================= 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | [Obscure Rule] applies for this entire chapter. 10 | 11 | In SQL, a is a pointer; a scalar constructed SQL . 12 | It points to a row of a Base table that haas the *with* ``REF`` *value* 13 | property -- that is, a points to a UDT value. Unless you are 14 | familiar with Object-Oriented Programming,, this chapter will probably not be 15 | fully comprehensible until you have read Chapter 27 "User-Defined Types". 16 | 17 | .. rubric:: Table of Contents 18 | 19 | .. contents:: 20 | :local: 21 | 22 | Reference s 23 | ====================== 24 | 25 | A is defined by a descriptor that contains three pieces of 26 | information: 27 | 28 | 1. The 's name: ``REF``. 29 | 30 | 2. The name of the UDT that the is based on. (The UDT is known 31 | as the referenced type.) 32 | 33 | 3. The scope of the : a (possibly empty) list of the names of 34 | the Base tables that make up the 's scope. 35 | 36 | *REF* 37 | ..... 38 | 39 | The required syntax for a specification is as follows. 40 | 41 | :: 42 | 43 | ::= 44 | REF () 45 | [ SCOPE [reference scope check] ] 46 | ::= 47 | REFERENCES ARE [NOT] CHECKED 48 | [ ON DELETE 49 | {CASCADE | SET NULL | SET DEFAULT | RESTRICT | NO ACTION} ] 50 | 51 | A specification defines a pointer: its value is a value that 52 | references some site. (A site either does or does not have a ``REF`` value.) 53 | For example, this ``REF`` specification defines a based on a 54 | UDT (the "referenced type") called ``my_udt``: 55 | 56 | :: 57 | 58 | REF(my_udt) 59 | 60 | As already mentioned, a ``REF`` is a pointer. The value in a ``REF`` coloumn 61 | "refers" to a row in a Base table that has the *with* ``REF`` *value* property 62 | (this is a known as a *typed table*). The row that the ``REF`` value points to 63 | contains a value of the UDT that the ``REF`` Column is based on. 64 | 65 | If you're putting a ``REF`` specification in an SQL-Schema statement, the 66 | that owns the containing Schema must have the ``USAGE`` 67 | Privilege on "". If you're putting a ``REF`` specification in any 68 | other SQL statement, then your current must have the 69 | ``USAGE`` Privilege on "". 70 | 71 | For each site that has a ``REF`` value and is defined to hold a value of the 72 | referenced UDT, there is exactly one ``REF`` value -- at any time, it is 73 | distinct from the ``REF`` value of any other site in your SQL-environment. The 74 | of the ``REF`` value is ``REF`` (UDT). 75 | 76 | [NON-PORTABLE] The data type and size of a ``REF`` value in an application 77 | program must be some number of octets but is non-standard because the SQL 78 | Standard requires implementors to define the octet-length of a ``REF`` value. 79 | 80 | A ``REF`` value might have a scope: it determines the effect of a dereference 81 | operator on that value. A ``REF`` value's scope is a list of Base table names 82 | and consists of every row in every one of those Base tables. The optional 83 | ``SCOPE`` clause of a specification identifies ``REF``'s 84 | scope. Each Table named in the ``SCOPE`` clause must be a referenceable Base 85 | table with a structured type that is the same as the structured type of the UDT 86 | that ``REF`` is based on. Here is an examples: 87 | 88 | :: 89 | 90 | CREATE TABLE Table_1 ( 91 | column_1 SMALLINT, 92 | column_2 REF(my_udt) SCOPE Table_2); 93 | 94 | If you omit the ``SCOPE`` clause, the scope defaults to the Table that owns the 95 | Column you're defining. 96 | 97 | If your ``REF`` specification with a ``SCOPE`` clause is part of a , it must include this : ``REFERENCES ARE 99 | [NOT] CHECKED ON DELETE NO ACTION``. If a ``REF`` specification with a 100 | ``SCOPE`` clause is part of a , it must include a with or without the optional ``ON DELETE`` sub-clause. The 102 | clause may not be used under any other circumstances. 103 | 104 | A is a subtype of a if (*a*) both are s and (*b*) the UDT referenced by the first is a subtype 106 | of the UDT referenced by the second . 107 | 108 | If you want to restrict your code to Core SQL, don't use the ``REF`` . 110 | 111 | Reference Operations 112 | ==================== 113 | 114 | A is compatible with, and comparable to, all other s of the same referenced type -- that is, s are mutually 116 | comparable and mutually assignable if they are based on the same UDT. 117 | 118 | *CAST* 119 | ...... 120 | 121 | In SQL, ``CAST`` is a scalar operator that converts a given scalar value to a 122 | given scalar . ``CAST``, howver, can´t be used with s. To cast ``REF`` values, you´ll have to use a user-defined cast. 124 | 125 | It isn't, of course, possible to convert the values of every into 126 | the values of every other . You can cast a source 127 | to a UDT target and to any SQL predefined target (except for 128 | s and s) provided that a user-defined cast exist for 129 | this purpose and your current has the ``EXECUTE`` Privilege 130 | on that user-defined cast. When you cast a to any legal 131 | target, your DBMS incokes the user-defined cast. When you cast a to any legal target, your DBMS invokes the user-defined cast routine´s 133 | argument. The cast result in the value returned by the user-defined cast. 134 | 135 | *Assignment* 136 | ------------ 137 | 138 | In SQL, when a is assigned to a target, the 139 | assignment is straightforward -- however, assignment is possible only if your 140 | source's UDT is a subtype of the UDT of your target. 141 | 142 | [Obscure Rule] Since only SQL accepts null values, if your source is ``NULL``, 143 | then your target's value is not changed. Instead, your DBMS will set its 144 | indicator parameter to -1, to indicate that an assignment of the null value was 145 | attempted. If your target doesn't have an indicator parameter, the assignment 146 | will fail: your DBMS will return the ``SQLSTATE error 22002 "data 147 | exception-null value, no indicator parameter"``. Going the other way, there are 148 | two ways to assign a null value to an SQL-data target. Within SQL, you can use 149 | the ``NULL`` in an ``INSERT`` or an ``UPDATE`` statement to indicate 150 | that the target should be set to ``NULL``; that is, if your source is ``NULL``, 151 | your DBMS will set your target to vNULL``. Outside of SQL, if your source has 152 | an indicator parameter that is set to -1, your DBMS will set your target to 153 | ``NULL`` (regardless of the value of the source). (An indicator parameter with 154 | a value less than -1 will cause an error: your DBMS will return the ``SQLSTATE 155 | error 22010 "data exception-invalid indicator parameter value"``.) We'll talk 156 | more about indicator parameters in our chapters on SQL binding styles. 157 | 158 | *Comparison* 159 | ------------ 160 | 161 | SQL provides only two scalar comparison operators -- = and <> -- to perform 162 | operations on s. Both will be familiar; there are equivalent 163 | operators in other computer languages. Two ``REF`` values are comparable if 164 | they're both based on the same UDT. If either of the comparands are ``NULL``, 165 | the result of the operation is ``UNKNOWN``. 166 | 167 | *Other Operations* 168 | ------------------ 169 | 170 | With SQL, you have several other operations that you can perform on s. 172 | 173 | Scalar functions 174 | ................ 175 | 176 | SQL provides two scalar functions that operate on or return a : 177 | the and the . 178 | 179 | ** 180 | ......................... 181 | 182 | The required syntax for a is as follows. 183 | 184 | :: 185 | 186 | ::= 187 | reference_argument -> 188 | 189 | The operates on two operands — the first must evaluate 190 | to a that has a non-empty scope and the second must be the 191 | name of an Attribute of the 's UDT. The 192 | allows you to access a Column of the row identified by a ``REF`` value; it 193 | returns a result whose is the of and 194 | whose value is the value of the system-generated Column of the Table in the 195 | 's scope (where the system-generated Column is equal to 196 | ``reference_argument``). That is, given a ``REF`` value, the returns the value at the site referenced by that ``REF`` value. If 198 | the ``REF`` value doesn't identify a site (perhaps because the site it once 199 | identified has been destroyed), the returns ``NULL``. 200 | 201 | If you want to restrict your code to Core SQL, don't use the . 203 | 204 | ** 205 | ......................... 206 | 207 | The required syntax for a is as follows. 208 | 209 | :: 210 | 211 | ::= 212 | reference_argument -> 213 | 214 | ``DEREF`` operates on any expression that evaluates to a that 215 | has a non-empty scope. It returns the value referenced by a ``REF`` value. 216 | Your current must have the ``SELECT WITH HIERARCHY`` 217 | Privilege on ``reference_argument``\'s scope Table. 218 | 219 | If you want to restrict your code to Core SQL, don't use ``DEREF``. 220 | 221 | Set Functions 222 | ............. 223 | 224 | SQL provides three set functions that operate on a : ``COUNT`` 225 | and ``GROUPING``. Since none of these operate exclusively with ``REF`` 226 | arguments, we won't discuss them here; look for them in our chapter on set 227 | functions. 228 | 229 | Predicates 230 | .......... 231 | 232 | In addition to the comparison operators, SQL provides eight other predicates 233 | that operate on s: the , the , 234 | the , the , the , the 235 | , the and the . 236 | Each will return a boolean value: either ``TRUE``, ``FALSE`` or ``UNKNOWN``. 237 | Since none of them operates strictly on s, we won't discuss 238 | them here. Look for them in our chapters on search conditions. 239 | -------------------------------------------------------------------------------- /docs/chapters/14.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | ========================= 4 | Chapter 14 -- SQL Cluster 5 | ========================= 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | The SQL Standard describes the concepts on which SQL is based in terms of 10 | Objects, such as Tables. Each SQL Object is defined in terms of the 11 | characteristics (e.g.: its name) that describe it; the Standard calls this the 12 | Object's *descriptor*. Some Objects are dependent on other Objects, e.g.: a 13 | Column is dependent on the Table it belongs to. If an Object is dropped (i.e.: 14 | destroyed), then every Object dependent on it is also dropped. The following 15 | diagram shows the main SQL Object hierarchy, illustrating, for example, that a 16 | Cluster can contain one or more Catalogs; Catalogs can contain one or more 17 | Schemas; Schemas can contain one or more Domains, Tables, Character sets, etc. 18 | 19 | :: 20 | 21 | ========= 22 | =Cluster= 23 | ========= 24 | | 25 | ============ 26 | =Catalog(s)= 27 | ============ 28 | | 29 | =========== 30 | =Schema(s)= 31 | =========== 32 | | 33 | =========== 34 | =Domain(s)= 35 | ================== 36 | =or Table(s)= 37 | =========================== 38 | =or Assertion(s)= 39 | ==================================== 40 | =or Character set(s)= 41 | ===================================== 42 | =or Collation(s)= 43 | ============================================ 44 | =or Translation(s)= 45 | ============================================ 46 | 47 | (There are several other SQL Objects; this diagram shows only the major ones.) 48 | 49 | In this chapter, we'll describe SQL Clusters in detail, and show you the syntax 50 | to use to create, alter and destroy them. 51 | 52 | .. rubric:: Table of Contents 53 | 54 | .. contents:: 55 | :local: 56 | 57 | Cluster 58 | ======= 59 | 60 | An SQL Cluster is the group of Catalogs available to an SQL-session at any 61 | point in time; that is, it contains all the SQL-data you may access through a 62 | given SQL-server. The Objects that belong to a Cluster are known as Cluster 63 | Objects; that is, they depend on some Cluster. Every Cluster Object has a name 64 | that must be unique (among Objects of its name class) within the Cluster it 65 | belongs to. The Cluster Object name class is: 66 | 67 | A Cluster may consist of zero or more of these Cluster Objects. The Cluster's 68 | name implicitly qualifies the names of the Objects that belong to it, and 69 | cannot be explicitly stated. Three SQL statements relate to Clusters: 70 | ``CONNECT``, ``SET CONNECTION`` and ``DISCONNECT``. 71 | 72 | [NON-PORTABLE] SQL does not include any ``CREATE CLUSTER``, ``OPEN CLUSTER``, 73 | ``ADD TO CLUSTER`` or ``DROP CLUSTER`` statements. The method you'll use to 74 | access a Cluster with your DBMS is thus non-standard because the SQL Standard 75 | requires implementors to define what the physical aspects of a Cluster are, 76 | whether any Catalog can be part of more than one Cluster at a time, how a 77 | Cluster comes into being, how it may be accessed and how it may be destroyed. 78 | 79 | [OCELOT Implementation] applies for the rest of this chapter. 80 | 81 | The OCELOT DBMS that comes with this book considers a Cluster to be a directory 82 | on your storage device, e.g.: this would represent a Cluster on an MS-DOS hard 83 | drive: 84 | 85 | :: 86 | 87 | C:\CLUSTER 88 | 89 | Each Cluster directory contains two files and zero or more subdirectories. The 90 | first file, called CLUSTER, contains the current definition of all the 91 | lower-level SQL Objects contained within the Catalogs that make up the Cluster. 92 | The second file, called CLUSTER.BAK, contains the definitions as they were 93 | prior to the last ``COMMIT`` statement issued during a SQL-session. Any 94 | subdirectories in the Cluster directory represent SQL Catalogs. OCELOT does not 95 | allow a Catalog to be part of multiple Clusters. 96 | 97 | OCELOT's method of creating and connecting to Clusters depends on the way you 98 | choose to begin a SQL session. 99 | 100 | - If the first SQL statement in your SQL-session is a ``CONNECT`` statement, 101 | the DBMS will search for a CLUSTER file on a directory whose name matches the 102 | ``CONNECT`` statement's . If a CLUSTER file is found on the 103 | correct directory, the file will be opened. If the correct directory is found 104 | but there is no CLUSTER file on it, a CLUSTER file will be created on that 105 | directory, and then opened. If no directory with the correct name is found, 106 | the directory will be created, then a CLUSTER file will be created on that 107 | directory, and opened. 108 | 109 | - If the first SQL statement in your SQL-session is not a ``CONNECT`` 110 | statement, the DBMS will open a CLUSTER file on a directory named OCELOT. 111 | 112 | To drop a Cluster, simply delete the CLUSTER file from your storage device. 113 | 114 | *Cluster Names* 115 | --------------- 116 | 117 | A identifies a Cluster. The required syntax for a is as follows. 119 | 120 | :: 121 | 122 | ::= 123 | string 124 | 125 | An has a maximum length of 128 octets and is either a 126 | , the name of a host character string parameter or a 127 | reference to an SQL character string parameter that conforms to the rules for 128 | an . 129 | 130 | NON-PORTABLE] A must be unique (for all Clusters) within an 131 | SQL-environment, but is non-standard because the SQL Standard requires 132 | implementors to define what a may be and which Character set 133 | it belongs to. 134 | 135 | [OCELOT Implementation] The OCELOT DBMS that comes with this book defines a 136 | as any belonging to the ``SQL_TEXT`` Character 137 | set that also follows the rules for a directory name on the operating system in 138 | use; generally it may include [drive:] and \upper-level name. 139 | 140 | Here are some examples of possible s: 141 | 142 | :: 143 | 144 | 'CLUSTER_1' 145 | -- a that is a 146 | 147 | :CLUSTER_1 148 | -- a that is a host parameter name 149 | 150 | CLUSTER_1 151 | -- a that is an SQL parameter name 152 | -------------------------------------------------------------------------------- /docs/chapters/17.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | ======================== 4 | Chapter 17 -- SQL Schema 5 | ======================== 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | The SQL Standard describes the concepts on which SQL is based in terms of 10 | Objects, such as Tables. Most of these Objects are Schema Objects; that is, 11 | they depend on some Schema. In this chapter, we'll describe SQL Schemas in 12 | detail, and show you the syntax to use to create, alter and destroy them. 13 | 14 | .. rubric:: Table of Contents 15 | 16 | .. contents:: 17 | :local: 18 | 19 | Schema 20 | ====== 21 | 22 | A Catalog may contain one or more Schemas. An SQL Schema is a named group of 23 | SQL-data that is owned by a particular . Schemas are dependent 24 | on some Catalog -- the must be unique within the Catalog the 25 | Schema belongs to -- and are created, altered and dropped using the SQL-Schema 26 | statements. The Objects that may belong to a Schema are known as Schema 27 | Objects; that is, they depend on some Schema. Every Schema Object has a name 28 | that must be unique (among Objects of its name class) within the Schema it 29 | belongs to. The Schema Object name classes are: 30 | 31 | - Base tables and Views. 32 | 33 | - Domains and UDTs. 34 | 35 | - Constraints and Assertions. 36 | 37 | - Character sets. 38 | 39 | - Collations. 40 | 41 | - Translations. 42 | 43 | - Triggers. 44 | 45 | - SQL-server Modules. 46 | 47 | - SQL-invoked routines. 48 | 49 | - Roles. 50 | 51 | A Schema may consist of zero or more of these Schema Objects. The Schema's name 52 | qualifies the names of the Objects that belong to it, and can either be 53 | explicitly stated, or a default name will be supplied by your DBMS. 54 | 55 | A Schema is defined by a descriptor that contains four pieces of information: 56 | 57 | 1. The , qualified by the of the Catalog it belongs 58 | to. 59 | 60 | 2. The that owns the Schema and its Objects. 61 | 62 | 3. The name of the Schema's default Character set. 63 | 64 | 4. The specification that defines the path for the Schema's SQL-invoked 65 | routines. 66 | 67 | 5. A descriptor for every SQL Object that belongs to the Schema. 68 | 69 | To create a Schema, use the ``CREATE SCHEMA`` statement. It specifies the 70 | enclosing Catalog, names the Schema, defines the Schema's default Character 71 | set, default path and zero or more Schema Objects, and identifies the Schema's 72 | owner. To change an existing Schema, use the appropriate ``CREATE`` / ``DROP`` 73 | / ``ALTER`` / ``GRANT`` / ``REVOKE`` statements to adjust the Schema's Objects. 74 | To destroy a Schema, use the ``DROP SCHEMA`` statement. 75 | 76 | There is a one-to-many association between Schemas and users: one 77 | can own many Schemas. For compatibility with the ODBC 78 | qualifier structure (database.owner.object) though, we recommend that a be the same as the owning and that each 80 | be allowed to own only one Schema in a Cluster. 81 | 82 | *Schema Names* 83 | -------------- 84 | 85 | A identifies a Schema. The required syntax for a is 86 | as follows. 87 | 88 | :: 89 | 90 | ::= 91 | [ . ] unqualified name 92 | 93 | A is a or a that is 94 | unique (for all Schemas) within the Catalog it belongs to. The 95 | which qualifies a names the Catalog that the Schema belongs to, 96 | and can either be explicitly stated or a default will be supplied by your DBMS, 97 | as follows: 98 | 99 | - If the unqualified is found in a Module, the default qualifier 100 | is the name of the Catalog identified in the ``SCHEMA`` clause or 101 | ``AUTHORIZATION`` clause of the ``MODULE`` statement that defines that 102 | Module. 103 | 104 | - [NON-PORTABLE] If the ``MODULE`` statement doesn't provide an explicit 105 | , or if the unqualified is not in a Module, the 106 | default qualifier is non-standard because the SQL Standard 107 | requires implementors to define the default qualifier in such cases. Your 108 | DBMS will usually define its initial default as the qualifier, 109 | but this is not required. [OCELOT Implementation] The OCELOT DBMS that comes 110 | with this book uses its initial default (OCELOT) as the 111 | qualifier in such cases. 112 | 113 | Here are some examples of s: 114 | 115 | :: 116 | 117 | SCHEMA_1 118 | --- a 119 | 120 | CATALOG_1.SCHEMA_1 121 | -- a qualified 122 | 123 | Note that the -- ``DEFINITION_SCHEMA`` -- may not be used 124 | as a . 125 | 126 | CREATE SCHEMA Statement 127 | ======================= 128 | 129 | The ``CREATE SCHEMA`` statement names a new Schema, defines the Schema's 130 | default Character set, default path and zero or more Schema Objects, and 131 | identifies the Schema's owner. The required syntax for the ``CREATE SCHEMA`` 132 | statement is: 133 | 134 | :: 135 | 136 | CREATE SCHEMA 137 | [ DEFAULT CHARACTER SET ] 138 | [ PATH {,}... ] 139 | [ ] 140 | 141 | ::= 142 | | 143 | AUTHORIZATION | 144 | AUTHORIZATION 145 | 146 | ::= 147 | CREATE DOMAIN statement(s) | 148 | CREATE TABLE statement(s) | 149 | CREATE VIEW statement(s) | 150 | CREATE ASSERTION statement(s) | 151 | CREATE CHARACTER SET statement(s) | 152 | CREATE COLLATION statement(s) | 153 | CREATE TRANSLATION statement(s) | 154 | CREATE TRIGGER statement(s) | 155 | CREATE TYPE statement)s) | 156 | CREATE PROCEDURE statement(s) | 157 | CREATE FUNCTION statement(s) | 158 | CREATE ROLE statement(s) | 159 | GRANT statement(s) 160 | 161 | ``CREATE SCHEMA`` defines a new Schema. 162 | 163 | - The names the Schema and identifies the 164 | that owns it. A that includes an explicit 165 | qualifier belongs to the Catalog named. A that 166 | does not include an explicit qualifier belongs to the 167 | SQL-session default Catalog. The must be unique within the 168 | Catalog that owns it. 169 | 170 | The may contain either a , an 171 | ``AUTHORIZATION`` clause, or both. For example, this SQL statement creates a 172 | Schema named ``BOB``, owned by ``BOB``: 173 | 174 | :: 175 | 176 | CREATE SCHEMA bob AUTHORIZATION bob; 177 | 178 | If doesn't include an explicit , the defaults to the value of the ``AUTHORIZATION`` clause's 180 | . For example, this SQL statement also creates a Schema named 181 | ``BOB``, owned by ``BOB``: 182 | 183 | :: 184 | 185 | CREATE SCHEMA AUTHORIZATION bob; 186 | 187 | If doesn't include an explicit ``AUTHORIZATION`` clause, 188 | the that owns the Schema defaults to the (or, if there is no , it defaults to 190 | the current SQL-session ). Note: The current 191 | for the creation of a Schema is normally the named in the 192 | ``AUTHORIZATION`` clause. If you omit the ``AUTHORIZATION`` clause, then the 193 | current for the creation of the Schema is the SQL-session 194 | . 195 | 196 | .. CAUTION:: 197 | 198 | The associated with ``CREATE SCHEMA`` does not become the 199 | current for subsequent SQL statements, nor does the become the default Schema. Consider these three SQL statements: 201 | 202 | :: 203 | 204 | CONNECT TO 'cluster_1' AS 'connection_1' USER 'bob'; 205 | -- establishes the SQL-session to be BOB 206 | 207 | CREATE SCHEMA sam AUTHORIZATION sam 208 | CREATE TABLE sam_1 (column1 INT); 209 | -- creates a Schema named SAM, that contains one Table, both owned by SAM 210 | 211 | INSERT INTO sam_1 VALUES (10); 212 | -- fails because the Table can't be found 213 | 214 | In this example, although the ``CREATE SCHEMA`` statement did create the 215 | Table we're trying to ``INSERT`` into, it did not change the default 216 | from ``BOB`` to ``SAM``, nor did it change the default 217 | Schema from ``BOB`` to ``SAM``. Thus, the ``INSERT`` fails because the DBMS 218 | doesn't recognize a Table named ``SAM_1`` associated with 219 | ``BOB`` in Schema ``BOB``. 220 | 221 | The optional ``DEFAULT CHARACTER SET`` clause names the Schema's default 222 | Character set: the Character set assumed for all of this Schema's Column and 223 | Domain definitions when they don't include an explicit Character set 224 | specification. For example, all three of these SQL statements create a Schema 225 | that contains a Domain whose values must belong to the ``LATIN1`` Character 226 | set: 227 | 228 | :: 229 | 230 | CREATE SCHEMA bob AUTHORIZATION bob 231 | DEFAULT CHARACTER SET INFORMATION_SCHEMA.LATIN1 232 | CREATE DOMAIN char_domain AS CHAR(12) 233 | CHARACTER SET INFORMATION_SCHEMA.LATIN1; 234 | 235 | CREATE SCHEMA bob AUTHORIZATION bob 236 | DEFAULT CHARACTER SET INFORMATION_SCHEMA.ASCII_FULL 237 | CREATE DOMAIN char_domain AS CHAR(12) 238 | CHARACTER SET INFORMATION_SCHEMA.LATIN1; 239 | 240 | CREATE SCHEMA bob AUTHORIZATION bob 241 | DEFAULT CHARACTER SET INFORMATION_SCHEMA.LATIN1 242 | CREATE DOMAIN char_domain AS CHAR(12); 243 | 244 | (In the second example, the explicit ``CHARACTER SET`` clause in ``CREATE 245 | DOMAIN`` overrides the Schema's default Character set specification.) 246 | 247 | [NON-PORTABLE] If ``CREATE SCHEMA`` doesn't include an explicit ``DEFAULT 248 | CHARACTER SET`` clause, the Schema's default Character set is non-standard 249 | because the SQL Standard requires implementors to define it. [OCELOT 250 | Implementation] The OCELOT DBMS that comes with this book always uses 251 | ``INFORMATION_SCHEMA.ASCII_FULL`` as the default Character set. 252 | 253 | The optional ``PATH`` clause names the Schema's default path: the path used to 254 | qualify unqualified s that identify s that 255 | are part of this ``CREATE SCHEMA`` statement. You must include the name of the 256 | Schema being created in the ``PATH`` clause and, if you include multiple names, 257 | all of the Schemas named must belong to the same Catalog. 258 | 259 | [NON-PORTABLE] If ``CREATE SCHEMA`` doesn't include an explicit ``PATH`` 260 | clause, the Schema's path specification must include the new Schema's name, but 261 | is otherwise non-standard because the SQL Standard requires implementors to 262 | define a path specification for the Schema. 263 | 264 | [NON-PORTABLE] Whether or not you may create a Schema is non-standard because 265 | the SQL Standard requires implementors to define what Privilege (if any) allows 266 | an to execute ``CREATE SCHEMA``. [OCELOT Implementation] The 267 | OCELOT DBMS that comes with this book allows any to execute 268 | ``CREATE SCHEMA``. 269 | 270 | The only separator between the SQL statements that make up the is white space. For example, this is a single SQL statement that creates 272 | a Schema: 273 | 274 | :: 275 | 276 | CREATE SCHEMA sam AUTHORIZATION sam 277 | DEFAULT CHARACTER SET INFORMATION_SCHEMA.LATIN1 278 | CREATE DOMAIN dept_domain AS CHAR(3) 279 | CREATE TABLE department (dept dept_domain, name1 CHAR(10)) 280 | CREATE TABLE employee (empname CHAR(20), dept dept_domain) 281 | GRANT SELECT ON department TO bob; 282 | 283 | If you want to restrict your code to Core SQL, don't use a ``DEFAULT CHARACTER 284 | SET`` clause or a ``PATH`` clause in your ``CREATE SCHEMA`` statements and 285 | don't include any of the following in your : ``CREATE 286 | ASSERTION`` statements, ``CREATE CHARACTER SET`` statements, ``CREATE 287 | COLLATION`` statements, ``CREATE DOMAIN`` statements, ``CREATE TRANSLATION`` 288 | statements, ``CREATE TYPE`` statements, ``CREATE ROLE`` statements or ``GRANT`` 289 | statements to Roles. 290 | 291 | DROP SCHEMA Statement 292 | ===================== 293 | 294 | The ``DROP SCHEMA`` statement destroys an entire Schema. The required syntax 295 | for the ``DROP SCHEMA`` statement is: 296 | 297 | :: 298 | 299 | DROP SCHEMA {RESTRICT | CASCADE} 300 | 301 | The must identify an existing Schema whose owner is either the 302 | current or a Role that the current may use. 303 | That is, only the that owns the Schema may drop it. 304 | 305 | The effect of ``DROP SCHEMA`` ``RESTRICT``, e.g.: 306 | 307 | :: 308 | 309 | DROP SCHEMA catalog_1.schema_1 RESTRICT; 310 | 311 | is that the Schema named ``CATALOG_1.SCHEMA_1`` will be destroyed, providing 312 | that (*a*) it doesn't contain any Objects, (*b*) it isn't referred to in any 313 | SQL routine and (*c*) it isn't referred to in the path specification of any 314 | other Schema. That is, ``RESTRICT`` ensures that only an empty Schema, on which 315 | nothing else depends, can be destroyed. 316 | 317 | The effect of ``DROP SCHEMA`` ``CASCADE``, e.g.: 318 | 319 | :: 320 | 321 | DROP SCHEMA catalog_1.schema_1 CASCADE; 322 | 323 | is that the Schema named ``CATALOG_1.SCHEMA_1`` will be destroyed -- as will 324 | all of the Schema's Objects (with a ``CASCADE`` drop behaviour for Tables, 325 | Views, Domains, Collations, Roles, UDTs and SQL-invoked routines) and any SQL 326 | routines (with a ``CASCADE`` drop behaviour) and path specifications that 327 | depend on this Schema. 328 | 329 | If you want to restrict your code to Core SQL, don't use the ``DROP SCHEMA`` 330 | statement. 331 | -------------------------------------------------------------------------------- /docs/chapters/21.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | =============================== 4 | Chapter 21 -- SQL Character Set 5 | =============================== 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | [Obscure Rule] applies to this entire chapter. 10 | 11 | In this chapter, we'll describe SQL Character sets in detail, and show you the 12 | syntax to use to create, alter and destroy them. 13 | 14 | .. rubric:: Table of Contents 15 | 16 | .. contents:: 17 | :local: 18 | 19 | Character Set 20 | ============= 21 | 22 | A Schema may contain zero or more Character sets. As we explained in our 23 | chapter on character strings, an *SQL Character set* is a combination of a 24 | character repertoire (a set of characters) and a Form-of-use (the repertoire's 25 | internal encoding scheme). Character sets are dependent on some Schema -- the 26 | must be unique within the Schema the Character set belongs 27 | to. User-defined Character sets are created and dropped using standard SQL 28 | statements. 29 | 30 | In SQL, a Character set may be a Character set defined by a national or 31 | international standard, by your DBMS or by a user of SQL-data. 32 | 33 | Standard-defined Character sets consist of a set of characters predefined by 34 | some standards body and have a default Collation that is the order of the 35 | characters in the relevant standard. The default Collation has the ``PAD 36 | SPACE`` characteristic. The SQL Standard requires a DBMS to support, at a 37 | minimum, these standard-defined Character sets: ``SQL_CHARACTER``, 38 | ``GRAPHIC_IRV`` (also called ``ASCII_GRAPHIC``), ``LATIN1``, ``ISO8BIT`` (also 39 | called ``ASCII_FULL``) and ``UNICODE`` (also called ``ISO10646``). 40 | 41 | Implementation-defined Character sets consist of a set of characters predefined 42 | by your DBMS and have a default Collation that is also defined by your DBMS. 43 | The default Collation may have either the ``PAD SPACE`` characteristic or the 44 | ``NO PAD`` characteristic. The SQL Standard requires a DBMS to support, at a 45 | minimum, this implementation-defined Character set: ``SQL_TEXT``. 46 | 47 | [NON-PORTABLE] The complete set of predefined Character sets supported by a 48 | DBMS is non-standard because the SQL Standard allows implementors to include 49 | support for other Character sets, in addition to the required ones. 50 | 51 | [OCELOT Implementation] The OCELOT DBMS that comes with this book provides 52 | support for seven other predefined Character sets, based on commonly available 53 | MS-Windows codepages. They are: 54 | 55 | +-------------------+-----------------------------------+ 56 | | ``CODEPAGE_0437`` | MS-DOS West European codepage 437 | 57 | +-------------------+-----------------------------------+ 58 | | ``CODEPAGE_085`` | MS-DOS International codepage 850 | 59 | +-------------------+-----------------------------------+ 60 | | ``CODEPAGE_1250`` | MS-Windows Latin II codepage 1250 | 61 | +-------------------+-----------------------------------+ 62 | | ``CODEPAGE_1251`` | MS-Windows Cyrillic codepage 1251 | 63 | +-------------------+-----------------------------------+ 64 | | ``CODEPAGE_125`` | MS-Windows Greek codepage 1253 | 65 | +-------------------+-----------------------------------+ 66 | | ``CODEPAGE_1254`` | MS-Windows Turkish codepage 1254 | 67 | +-------------------+-----------------------------------+ 68 | | ``CODEPAGE_1257`` | MS-Windows Baltic codepage 1257 | 69 | +-------------------+-----------------------------------+ 70 | 71 | The pre-defined Character sets provided by your DBMS belong to 72 | ``INFORMATION_SCHEMA`` (as do Collations defined by standards and Collations, 73 | Translations and Form-of-use conversions defined by your DBMS). The SQL special 74 | grantee, ``PUBLIC``, always has a ``USAGE`` Privilege on every predefined 75 | Character set provided by your DBMS. For details on the predefined Character 76 | sets, see our chapter on characters. 77 | 78 | Every Character set has a default Collation: it specifies the rules that 79 | determine the results of comparisons between the Character set's characters in 80 | the absence of an explicit ``COLLATE`` clause. 81 | 82 | A Character set is defined by a descriptor that contains three pieces of 83 | information: 84 | 85 | 1. The , qualified by the of the Schema it 86 | belongs to. 87 | 88 | 2. A list of the characters that belong to the Character set. 89 | 90 | 3. The name of the Character set's default Collation. (This may be the 91 | Form-of-use encoding scheme for the Character set's repertoire.) 92 | 93 | User-defined Character sets may belong to any Schema owned by the creator. To 94 | create a Character set, use the ``CREATE CHARACTER SET`` statement (either as a 95 | stand-alone SQL statement or within a ``CREATE SCHEMA`` statement). ``CREATE 96 | CHARACTER SET`` specifies the enclosing Schema, names the Character set and 97 | identifies the Character set's repertoire and default Collation. To destroy a 98 | Character set, use the ``DROP CHARACTER SET`` statement. To change an existing 99 | Character set, drop and then redefine it. 100 | 101 | There is a one-to-many association between Character sets and Collations: one 102 | Character set can have many possible Collations defined for it, although only 103 | one can be its default Collation. 104 | 105 | *Character set names* 106 | --------------------- 107 | 108 | A identifies a Character set. The required syntax for a 109 | is: 110 | 111 | :: 112 | 113 | ::= 114 | [ . ] unqualified name 115 | 116 | A is a that is unique (for all 117 | Character sets) within the Schema it belongs to. The which 118 | qualifies a names the Schema that the Character set 119 | belongs to and can either be explicitly stated, or it will default to 120 | ``INFORMATION_SCHEMA``; that is, an unqualified is always 121 | assumed to belong to ``INFORMATION_SCHEMA`` -- even if a ``CREATE CHARACTER 122 | SET`` statement is part of a ``CREATE SCHEMA`` statement. (User-defined 123 | Character sets may not belong to ``INFORMATION_SCHEMA``. Therefore, when 124 | defining, using or dropping a user-defined Character set, always provide an 125 | explicit qualifier for the .) 126 | 127 | Here are some examples of s: 128 | 129 | :: 130 | 131 | LATIN1 132 | -- a predefined 133 | 134 | SCHEMA_1.CHARACTER_SET_1 135 | -- a simple qualified user-defined 136 | 137 | CATALOG_1.SCHEMA_1.CHARACTER_SET_1 138 | -- a fully qualified user-defined 139 | 140 | If you want to restrict your code to Core SQL, don't use any s. 142 | 143 | CREATE CHARACTER SET Statement 144 | ============================== 145 | 146 | The ``CREATE CHARACTER SET`` statement names a new user-defined Character set 147 | and specifies the Character set's repertoire and default Collation. The 148 | required syntax for the ``CREATE CHARACTER SET`` statement is: 149 | 150 | 151 | 152 | :: 153 | 154 | CREATE CHARACTER SET user-defined [ AS ] 155 | GET predefined 156 | [ COLLATE ] 157 | 158 | ``CREATE CHARACTER SET`` defines a new user-defined Character set. A 159 | Character set is owned by the Schema it belongs to. 160 | 161 | The user-defined identifies the new Character set and the 162 | Schema that it belongs to. A that includes an explicit 163 | qualifier belongs to the Schema named. A 164 | that does not include an explicit qualifier belongs to 165 | ``INFORMATION_SCHEMA``. Since a user-defined Character set can't belong to 166 | ``INFORMATION_SCHEMA``, always provide an explicit qualifier when 167 | you're creating a Character set. 168 | 169 | If ``CREATE CHARACTER SET`` is part of a ``CREATE SCHEMA`` statement, the 170 | must include the of the Schema being 171 | created; that is, it isn't possible to create a Character set belonging to a 172 | different Schema from within ``CREATE SCHEMA``. For example, this SQL statement 173 | will not return an error because the explicitly includes a 174 | qualifying that matches the name of the Schema being created: 175 | 176 | :: 177 | 178 | CREATE SCHEMA bob 179 | CREATE CHARACTER SET bob.charset_1 AS GET LATIN1; 180 | -- creates a Character set called BOB.CHARSET_1 in Schema BOB 181 | 182 | But this SQL statement will return an error because the 183 | explicitly includes a qualifying that is different from the name 184 | of the Schema being created: 185 | 186 | :: 187 | 188 | CREATE SCHEMA bob 189 | CREATE CHARACTER SET sam.charset_1 AS GET LATIN1; 190 | -- tries to create a Character set belonging to Schema SAM inside Schema BOB; illegal syntax 191 | 192 | If ``CREATE CHARACTER SET`` is executed as a stand-alone SQL statement, the 193 | current must either be the owner of the Schema that this new 194 | Character set belongs to, or the Schema's owner must be a Role that the current 195 | may use. That is, only the owner of a Schema can create 196 | Character sets for that Schema. In addition to creating a Character set, 197 | ``CREATE CHARACTER SET`` also causes the SQL special grantor, "``_SYSTEM``", to 198 | grant a grantable ``USAGE`` Privilege on the new Character set to the Schema 199 | owner (that is, the ``AS`` in the ``GET`` 218 | clause is noise and can be omitted. For example, these two SQL statements are 219 | equivalent: 220 | 221 | :: 222 | 223 | CREATE CHARACTER SET bob.charset_1 AS GET LATIN1; 224 | 225 | CREATE CHARACTER SET bob.charset_1 GET LATIN1; 226 | 227 | The optional ``COLLATE`` clause of the ``CREATE CHARACTER SET`` statement 228 | allows you to define a default Collation for your user-defined Character set 229 | that is different from the default Collation of its source Character set. Your 230 | current must have the ``USAGE`` Privilege on the Collation 231 | named. Here is an example: 232 | 233 | :: 234 | 235 | CREATE CHARACTER SET bob.charset_1 AS GET LATIN1 236 | COLLATE bob.collation_1; 237 | 238 | This SQL statement defines a new user-defined Character set, called 239 | ``BOB.CHARSET_1``. It contains the same characters as ``LATIN1`` does, but is 240 | slightly different because its default Collation won't be ``LATIN1``\'s default 241 | Collation -- instead, its default Collation is a Collation named 242 | ``BOB.COLLATION_1``. 243 | 244 | If you want to restrict your code to Core SQL, don't use the ``CREATE 245 | CHARACTER SET`` statement. 246 | 247 | DROP CHARACTER SET Statement 248 | ============================ 249 | 250 | The ``DROP CHARACTER SET`` statement destroys a user-defined Character set. 251 | The required syntax for the ``DROP CHARACTER SET`` statement is: 252 | 253 | :: 254 | 255 | DROP CHARACTER SET 256 | 257 | The must identify an existing Character set whose owner is 258 | either the current or a Role that the current 259 | may use. That is, only the that owns the 260 | Character set may drop it, and so it isn't possible to drop any of the 261 | predefined Character sets provided by your DBMS. 262 | 263 | The effect of ``DROP CHARACTER SET`` , e.g.: 264 | 265 | :: 266 | 267 | DROP CHARACTER SET bob.charset_1; 268 | 269 | is that the user-defined Character set named ``BOB.CHARSET_1`` is destroyed, 270 | provided that the Character set is not referred to in any View definition, 271 | Constraint or Assertion definition, Collation definition, Translation 272 | definition or SQL routine. That is, ``DROP CHARACTER SET`` ensures that only a 273 | Character set with no dependent Objects can be destroyed. If the Character set 274 | is used by any other Object, ``DROP CHARACTER SET`` will fail. 275 | 276 | If successful, ``DROP CHARACTER SET`` has a two-fold effect. 277 | 278 | 1. The Character set named is destroyed. 279 | 280 | 2. The ``USAGE`` Privilege held on the Character set by the 281 | that owns it is revoked (by the SQL special grantor, 282 | "``_SYSTEM``") with a ``CASCADE`` revoke behaviour, so that the ``USAGE`` 283 | Privilege held on the Character set by any other is 284 | also revoked. 285 | 286 | If you want to restrict your code to Core SQL, don't use the ``DROP 287 | CHARACTER SET`` statement. 288 | -------------------------------------------------------------------------------- /docs/chapters/22.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | =========================== 4 | Chapter 22 -- SQL Collation 5 | =========================== 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | [Obscure Rule] applies to this entire chapter. 10 | 11 | In this chapter, we'll describe SQL Collations in detail, and show you the 12 | syntax to use to create, alter and destroy them. 13 | 14 | .. rubric:: Table of Contents 15 | 16 | .. contents:: 17 | :local: 18 | 19 | Collation 20 | ========= 21 | 22 | A Schema may contain zero or more Collations. An *SQL Collation* is a set of 23 | rules that determines the result when characters from a Character set are 24 | compared. Collations are dependent on some Schema -- the must 25 | be unique within the Schema the Collation belongs to. User-defined Collations 26 | are created and dropped using standard SQL statements. 27 | 28 | In SQL, a Collation may be a Collation defined by a national or 29 | international standard, by your DBMS or by a user of SQL-data. 30 | 31 | Standard-defined Collations are collating sequences predefined for a character 32 | repertoire by some standards body. The SQL Standard requires a DBMS to provide 33 | a default Collation (based on the character repertoire order) for each of the 34 | standard-defined Character sets it supports. In each case, the default 35 | Collation has the ``PAD SPACE`` characteristic. 36 | 37 | Implementation-defined Collations are collating sequences predefined for a 38 | character repertoire by your DBMS. These Collations may have either the ``PAD 39 | SPACE`` characteristic or the ``NO PAD`` characteristic. The SQL Standard 40 | requires a DBMS to provide a default Collation, called ``SQL_TEXT``, for the 41 | ``SQL_TEXT`` Character set. 42 | 43 | [NON-PORTABLE] The complete set of predefined Collations provided by a DBMS is 44 | non-standard because the SQL Standard allows implementors to include support 45 | for other Collations, in addition to the required ones. It also requires 46 | implementors *(a)* to define the names for the standard-defined and (except for 47 | ``SQL_TEXT``) the implementation-defined Collations it provides and *(b)* to 48 | define the ``PAD SPACE`` characteristic for each implementation-defined 49 | Collations it provides. 50 | 51 | [OCELOT Implementation] The OCELOT DBMS that comes with this book provides a 52 | ``SQL_TEXT`` Collation that follows the order of the Unicode Form-of-use codes. 53 | The ``SQL_TEXT`` Collation has the ``PAD SPACE`` characteristic and is the 54 | default Collation for both the ``SQL_TEXT`` Character set and the ``UNICODE`` 55 | Character set. It also provides eleven other predefined Collations, all with 56 | the ``PAD SPACE`` characteristic. They are: 57 | 58 | +-------------------+-------------------------------------------------------+ 59 | | ``SQL_CHARACTER`` | default Collation for Character set ``SQL_CHARACTER`` | 60 | +-------------------+-------------------------------------------------------+ 61 | | ``GRAPHIC_IRV`` | default Collation for Character set ``GRAPHIC_IRV`` | 62 | +-------------------+-------------------------------------------------------+ 63 | | ``LATIN1`` | default Collation for Character set ``LATIN1`` | 64 | +-------------------+-------------------------------------------------------+ 65 | | ``ISO8BIT`` | default Collation for Character set ``ISO8BIT`` | 66 | +-------------------+-------------------------------------------------------+ 67 | | ``CODEPAGE_0437`` | default Collation for Character set ``CODEPAGE_0437`` | 68 | +-------------------+-------------------------------------------------------+ 69 | | ``CODEPAGE_0850`` | default Collation for Character set ``CODEPAGE_0850`` | 70 | +-------------------+-------------------------------------------------------+ 71 | | ``CODEPAGE_1250`` | default Collation for Character set ``CODEPAGE_1250`` | 72 | +-------------------+-------------------------------------------------------+ 73 | | ``CODEPAGE_1251`` | default Collation for Character set ``CODEPAGE_1251`` | 74 | +-------------------+-------------------------------------------------------+ 75 | | ``CODEPAGE_1253`` | default Collation for Character set ``CODEPAGE_1253`` | 76 | +-------------------+-------------------------------------------------------+ 77 | | ``CODEPAGE_1254`` | default Collation for Character set ``CODEPAGE_1254`` | 78 | +-------------------+-------------------------------------------------------+ 79 | | ``CODEPAGE_1257`` | default Collation for Character set ``CODEPAGE_1257`` | 80 | +-------------------+-------------------------------------------------------+ 81 | 82 | The pre-defined Collations provided by your DBMS belong to 83 | ``INFORMATION_SCHEMA``. The SQL special grantee, ``PUBLIC``, always has a 84 | ``USAGE`` Privilege on every predefined Collation provided by your DBMS. 85 | 86 | A Collation is defined by a descriptor that contains three pieces of 87 | information: 88 | 89 | 1. The , qualified by the of the Schema it 90 | belongs to. 91 | 92 | 2. The name of the Character set on which the Collation operates. 93 | 94 | 3. Whether the ``NO PAD`` or the ``PAD SPACE`` characteristic applies to the 95 | Collation. 96 | 97 | User-defined Collations may belong to any Schema owned by the creator. To 98 | create a Collation, use the ``CREATE COLLATION`` statement (either as a 99 | stand-alone SQL statement or within a ``CREATE SCHEMA`` statement). ``CREATE 100 | COLLATION`` specifies the enclosing Schema, names the Collation and defines the 101 | Collation's Character set and ``PAD`` characteristic. To destroy a Collation, 102 | use the ``DROP COLLATION`` statement. To change an existing Collation, drop and 103 | then redefine it. 104 | 105 | There is a one-to-many association between Character sets and Collations: one 106 | Character set can have many possible Collations defined for it, although only 107 | one can be its default Collation. 108 | 109 | The default Collation for a Character set is the Collation that will be used to 110 | compare characters belonging to that Character set in the absence of an 111 | explicit specification to the contrary and can either be a Collation defined 112 | for the Character set or the Form-of-use encoding scheme for that Character 113 | set's repertoire -- that is, the default Collation for a Character set can be 114 | defined to be the order of the characters in the character repertoire. (For 115 | example, in the 7-bit ASCII character set, the decimal code for the letter 116 | ``A`` is ``65`` and the decimal code for the letter ``B`` is ``66``. This is a 117 | happy coincidence; it allows your DBMS to discover that ``'A'`` is less than 118 | ``'B'`` by merely executing a CMP: a machine-code numeric comparison. And 119 | that's what is meant by "the order of the characters in the repertoire". Note 120 | that, since the decimal code for the letter ``a`` is ``97``, it follows that 121 | ``'A'`` is less than ``'a'`` -- that is, character repertoire order specifies a 122 | case-sensitive collating sequence.) 123 | 124 | *Collation Names* 125 | ----------------- 126 | 127 | A identifies a Collation. The required syntax for a 128 | is: 129 | 130 | :: 131 | 132 | ::= 133 | [ . ] unqualified name 134 | 135 | A is a or a that 136 | is unique (for all Collations) within the Schema it belongs to. The which qualifies a names the Schema that the Collation 138 | belongs to and can either be explicitly stated, or it will default to 139 | ``INFORMATION_SCHEMA``; that is, an unqualified is always 140 | assumed to belong to ``INFORMATION_SCHEMA`` -- even if a ``CREATE COLLATION`` 141 | statement is part of a ``CREATE SCHEMA`` statement. (User-defined Collations 142 | may not belong to ``INFORMATION_SCHEMA``. Therefore, when defining, using or 143 | dropping a user-defined Collation, always provide an explicit 144 | qualifier for the .) 145 | 146 | Here are some examples of possible s: 147 | 148 | :: 149 | 150 | SQL_TEXT 151 | -- a predefined 152 | 153 | SCHEMA_1.COLLATION_1 154 | -- a simple qualified user-defined 155 | 156 | CATALOG_1.SCHEMA_1.COLLATION_1 157 | -- a fully qualified user-defined 158 | 159 | *Form-of-Use Conversion Names* 160 | ------------------------------ 161 | 162 | A identifies a character repertoire's encoding 163 | scheme -- the one-to-one mapping scheme between each character in the 164 | repertoire and a set of internal codes (usually 8-bit values) that define how 165 | the repertoire's characters are encoded as numbers. These codes are also used 166 | to specify the order of the characters within the repertoire and so can be used 167 | to specify the default Collation for a Character set. Supported Forms-of- use 168 | are all predefined by your DBMS and thus belong to ``INFORMATION_SCHEMA``. SQL 169 | provides no ability to define your own Forms-of-use. The required syntax for a 170 | is: 171 | 172 | :: 173 | 174 | ::= 175 | [ INFORMATION_SCHEMA. ] unqualified name 176 | 177 | A is a or a that is unique (for all Forms-of-user) within 179 | ``INFORMATION_SCHEMA``. The which qualifies a names the Schema that the Form-of-use belongs to and can 181 | either be explicitly stated, or it will default to ``INFORMATION_SCHEMA``: the 182 | only Schema that may own a Form-of-use. 183 | 184 | Here are some examples of possible s: 185 | 186 | :: 187 | 188 | FORM_1 189 | -- a possible 190 | 191 | INFORMATION_SCHEMA.FORM_1 192 | -- a simple qualified possible 193 | 194 | CATALOG_1.INFORMATION_SCHEMA.FORM_1 195 | -- a fully qualified possible 196 | 197 | [NON-PORTABLE] The Forms-of-use available for use is non-standard because the 198 | SQL Standard requires implementors to define which (if any) Forms-of-use they 199 | will explicitly provide. 200 | 201 | [OCELOT Implementation] The OCELOT DBMS that comes with this book provides 202 | no explicit Forms-of use. 203 | 204 | If you want to restrict your code to Core SQL, don't use any s or s. 206 | 207 | CREATE COLLATION Statement 208 | ========================== 209 | 210 | The ``CREATE COLLATION`` statement names a new user-defined Collation and 211 | specifies the Collation's ``PAD`` characteristic and the Character set that the 212 | Collation is for. The required syntax for the ``CREATE COLLATION`` statement 213 | is: 214 | 215 | :: 216 | 217 | CREATE COLLATION user-defined 218 | FOR 219 | FROM existing [ {NO PAD | PAD SPACE} ] 220 | 221 | ``CREATE COLLATION`` defines a new user-defined Collation. A Collation is 222 | owned by the Schema it belongs to. 223 | 224 | The user-defined identifies the new Collation and the Schema 225 | that it belongs to. A that includes an explicit 226 | qualifier belongs to the Schema named. A that does not 227 | include an explicit qualifier belongs to ``INFORMATION_SCHEMA``. 228 | Since a user-defined Collation can't belong to ``INFORMATION_SCHEMA``, always 229 | provide an explicit qualifier when you're creating a Collation. 230 | 231 | If ``CREATE COLLATION`` is part of a ``CREATE SCHEMA`` statement, the 232 | must include the of the Schema being created; 233 | that is, it isn't possible to create a Collation belonging to a different 234 | Schema from within ``CREATE SCHEMA``. For example, this SQL statement will not 235 | return an error because the explicitly includes a qualifying 236 | that matches the name of the Schema being created: 237 | 238 | :: 239 | 240 | CREATE SCHEMA bob 241 | CREATE COLLATION bob.collation_1 FOR bob.charset_1 FROM SQL_TEXT; 242 | -- creates a Collation called BOB.COLLATION_1 in Schema BOB 243 | 244 | But this SQL statement will return an error because the 245 | explicitly includes a qualifying that is different from the name 246 | of the Schema being created: 247 | 248 | :: 249 | 250 | CREATE SCHEMA bob 251 | CREATE COLLATION sam.collation_1 FOR bob.charset_1 FROM SQL_TEXT; 252 | -- tries to create a Collation belonging to Schema SAM inside Schema BOB; illegal syntax 253 | 254 | If ``CREATE COLLATION`` is executed as a stand-alone SQL statement, the current 255 | must either be the owner of the Schema that this new View 256 | belongs to, or the Schema's owner must be a Role that the current 257 | may use. That is, only the owner of a Schema can create 258 | Collations for that Schema. In addition to creating a Collation, ``CREATE 259 | COLLATION`` also causes the SQL special grantor, "``_SYSTEM``", to grant the 260 | ``USAGE`` Privilege on the new Collation to the Schema owner 261 | (that is, the also has a grantable ``USAGE`` Privilege on 263 | the Collation named in the ``FROM`` clause of the ``CREATE COLLATION`` 264 | statement. 265 | 266 | A user-defined Collation must be defined to operate on a Character set. The 267 | ``FOR`` clause of the ``CREATE COLLATION`` statement names that Character set. 268 | must be the name of an existing Character set for which 269 | the current has the ``USAGE`` Privilege. 270 | 271 | A user-defined Collation must also be defined as using the collating sequence 272 | of an existing Collation that is already defined for the Character set named in 273 | the ``FOR`` clause of the ``CREATE COLLATION`` statement. The ``FROM`` clause 274 | of the ``CREATE COLLATION`` statement names this Collation source. The existing 275 | must be the name of an existing Collation for which the 276 | current has the ``USAGE`` Privilege. For example, this SQL 277 | statement: 278 | 279 | :: 280 | 281 | CREATE COLLATION bob.collation_1 FOR bob.charset_1 FROM SQL_TEXT; 282 | 283 | defines a new user-defined Collation, called ``BOB.COLLATION_1``, in the Schema 284 | named ``BOB``. Except for its name, the Collation ``BOB. COLLATION_1`` will be 285 | exactly the same as the ``SQL_TEXT`` Collation -- that is, it is not truly 286 | possible to "create" new Collations, merely to rename (and possibly assign a 287 | new ``PAD`` characteristic to) them. To define a new Collation, the ``CREATE 288 | COLLATION`` statement must use some pre-existing Collation as a Collation 289 | source -- and, ultimately, all Collations can only be based on some pre-defined 290 | Collation provided by your DBMS. 291 | 292 | The optional ``PAD`` characteristic clause of the ``CREATE COLLATION`` 293 | statement allows you to define a ``PAD`` characteristic for your user-defined 294 | Collation that is different from the ``PAD`` characteristic of its source 295 | Collation. If you omit the ``PAD`` clause, your new Collation will have the 296 | same ``PAD`` characteristic as its source Collation does. For example, this SQL 297 | statement: 298 | 299 | :: 300 | 301 | CREATE COLLATION bob.collation_1 FOR bob.charset_1 FROM SQL_TEXT; 302 | 303 | defines a new user-defined Collation that will have the same ``PAD`` 304 | characteristic as Collation ``SQL_TEXT`` does; that is, except for its name, 305 | ``BOB.COLLATION_1`` is exactly like ``SQL_TEXT``. This SQL statement: 306 | 307 | :: 308 | 309 | CREATE COLLATION bob.collation_1 FOR bob.charset_1 FROM SQL_TEXT 310 | PAD SPACE; 311 | 312 | defines a new user-defined Collation that will have the ``PAD SPACE`` 313 | characteristic. And this SQL statement: 314 | 315 | :: 316 | 317 | CREATE COLLATION bob.collation_1 FOR bob.charset_1 FROM SQL_TEXT 318 | NO PAD; 319 | 320 | defines a new user-defined Collation that will have the ``NO PAD`` 321 | characteristic. 322 | 323 | A Collation's ``PAD`` characteristic affects the result when two strings of 324 | unequal size are compared. If the Collation in effect for a comparison has the 325 | ``PAD SPACE`` characteristic, the shorter string is padded with spaces (on the 326 | right) until it's the same length as the larger string; then the comparison is 327 | done. If the Collation in effect for a comparison has the ``NO PAD`` 328 | characteristic, the shorter string is padded with some other character before 329 | the comparison is done. In this case, the result is that the shorter comparand 330 | will evaluate as less than the longer comparand if they contain the same 331 | characters for their common length -- see our chapter on character strings. 332 | 333 | If you want to restrict your code to Core SQL, don't use the ``CREATE 334 | COLLATION`` statement. 335 | 336 | DROP COLLATION Statement 337 | ======================== 338 | 339 | The ``DROP COLLATION`` statement destroys a user-defined Collation. The 340 | required syntax for the ``DROP COLLATION`` statement is: 341 | 342 | :: 343 | 344 | DROP COLLATION {RESTRICT | CASCADE} 345 | 346 | The must identify an existing Collation whose owner is either 347 | the current or a Role that the current may 348 | use. That is, only the that owns the Collation may drop it, 349 | and so it isn't possible to drop any of the predefined Collations provided by 350 | your DBMS. 351 | 352 | The effect of ``DROP COLLATION`` ``RESTRICT``, e.g.: 353 | 354 | :: 355 | 356 | DROP COLLATION bob.collation_1 RESTRICT; 357 | 358 | is that the user-defined Collation named ``BOB.COLLATION_1`` is destroyed, 359 | provided that the Collation is not referred to in any View definition, 360 | Constraint or Assertion definition or SQL routine. That is, ``DROP COLLATION`` 361 | ensures that only a Collation with no dependent Views, Constraints, Assertions 362 | or SQL routines can be destroyed. If the Collation is used by any of these 363 | Objects, ``DROP COLLATION ... RESTRICT`` will fail. 364 | 365 | The effect of ``DROP COLLATION`` ``CASCADE``, e.g.: 366 | 367 | :: 368 | 369 | DROP COLLATION bob.collation_1 CASCADE; 370 | 371 | is that the user-defined Collation named ``BOB.COLLATION_1`` is destroyed. 372 | 373 | If successful, ``DROP COLLATION`` has a six-fold effect. 374 | 375 | 1. The Collation named is destroyed. 376 | 377 | 2. The ``USAGE`` Privilege held on the Collation by the 378 | that owns it is revoked (by the SQL special grantor, "``_SYSTEM``") with 379 | a ``CASCADE`` revoke behaviour, so that the ``USAGE`` Privilege held on 380 | the Collation by any other is also revoked. 381 | 382 | 3. The definition of any other Collation that named this Collation is 383 | amended, so that it no longer refers to it. The effect is that each 384 | Collation that was based on the dropped Collation will subsequently use 385 | the Form-of-use encoding scheme for the repertoire of its Character set 386 | as a collating sequence. 387 | 388 | 4. The definition of any Character set that named this Collation is amended, 389 | so that it no longer refers to it. The effect is that each Character set 390 | that used the dropped Collation as its default Collation will subsequently 391 | use the Form-of-use encoding scheme for its repertoire as a default 392 | Collation. 393 | 394 | 5. The definition of any Column, Domain, View, Constraint or Assertion 395 | that named this Collation is amended, so that it no longer refers to it. The 396 | effect is that each Column or Domain that used the dropped Collation as its 397 | default Collation will subsequently use the default Collation of its 398 | Character set as a default Collation. 399 | 400 | 6. Every SQL routine that names this Collation is dropped with a ``CASCADE`` 401 | drop behaviour. If you want to restrict your code to Core SQL, don't use 402 | the ``DROP COLLATION`` statement. 403 | -------------------------------------------------------------------------------- /docs/chapters/23.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | ============================= 4 | Chapter 23 -- SQL Translation 5 | ============================= 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | [Obscure Rule] applies to this entire chapter. 10 | 11 | In this chapter, we'll describe SQL Translations in detail, and show you the 12 | syntax to use to create, alter and destroy them. 13 | 14 | .. rubric:: Table of Contents 15 | 16 | .. contents:: 17 | :local: 18 | 19 | Translation 20 | =========== 21 | 22 | A Schema may contain zero or more Translations. An *SQL Translation* is a set 23 | of rules that maps the characters from a source Character set to the characters 24 | of a target Character set; effectively translating source strings into target 25 | strings. Any pair of Character sets may have zero or more Translations defined 26 | to translate strings belonging to one (the source Character set) into strings 27 | belonging to the other (the target Character set). Translations are dependent 28 | on some Schema -- the must be unique within the Schema the 29 | Translation belongs to. User-defined Translations are created and dropped using 30 | standard SQL statements. 31 | 32 | In SQL, a Translation may be a Translation defined by a national or 33 | international standard, by your DBMS or by a user of SQL-data. 34 | 35 | Standard-defined Translations are translations predefined for two character 36 | repertoires by some standards body. Implementation-defined Translations are 37 | translations predefined for two Character sets by your DBMS. The pre-defined 38 | Translations provided by your DBMS belong to ``INFORMATION_SCHEMA``. The SQL 39 | special grantee, ``PUBLIC``, always has a ``USAGE`` Privilege on every 40 | predefined Translation provided by your DBMS. 41 | 42 | [NON-PORTABLE] The set of predefined Translations provided by a DBMS is 43 | non-standard because the SQL Standard has no required Translations: it requires 44 | implementors to define any Translations supported. 45 | 46 | [OCELOT Implementation] The OCELOT DBMS that comes with this book provides a 47 | Translation named ``OCELOT``. It translates ``SQL_TEXT`` strings to 48 | ``ASCII_FULL`` strings. 49 | 50 | A Translation is defined by a descriptor that contains four pieces of 51 | information: 52 | 53 | 1. The , qualified by the of the Schema it 54 | belongs to. 55 | 56 | 2. The name of the Translation's source Character set: the Character set 57 | from which it translates. 58 | 59 | 3. The name of the Translation's target Character set: the Character set to 60 | which it translates. 61 | 62 | 4. The mapping scheme for the Translation. 63 | 64 | Two character strings may be compared or assigned to one another only if they 65 | both belong to the same Character set. The way to force a comparison or 66 | assignment between strings from different Character sets is to use the 67 | ``TRANSLATE`` function, which uses a Translation defined for the Character sets 68 | as an argument. 69 | 70 | User-defined Translations may belong to any Schema owned by the creator. To 71 | create a Translation, use the ``CREATE TRANSLATION`` statement (either as a 72 | stand-alone SQL statement or within a ``CREATE SCHEMA`` statement). ``CREATE 73 | TRANSLATION`` specifies the enclosing Schema, names the Translation and defines 74 | the Translation's source Character set, target Character set and Translation 75 | source. To destroy a Translation, use the ``DROP TRANSLATION`` statement. To 76 | change an existing Translation, drop and then redefine it. 77 | 78 | There is a one-to-many relationship between Translations and Character sets: a 79 | Translation may translate the characters of only one pair of Character sets, 80 | but a Character set can be named as either the source or the target for many 81 | different Translations. 82 | 83 | *Translation Names* 84 | ------------------- 85 | 86 | A identifies a Translation. The required syntax for a 87 | is: 88 | 89 | :: 90 | 91 | ::= 92 | [ . ] unqualified name 93 | 94 | A is a or a that 95 | is unique (for all Translations) within the Schema it belongs to. The which qualifies a names the Schema that the 97 | Translation belongs to and can either be explicitly stated, or it will default 98 | to ``INFORMATION_SCHEMA``; that is, an unqualified is always 99 | assumed to belong to ``INFORMATION_SCHEMA`` -- even if a ``CREATE TRANSLATION`` 100 | statement is part of a ``CREATE SCHEMA`` statement. (User-defined Translations 101 | may not belong to ``INFORMATION_SCHEMA``. Therefore, when defining, using or 102 | dropping a user-defined Translation, always provide an explicit 103 | qualifier for the .) 104 | 105 | Here are some examples of possible s: 106 | 107 | :: 108 | 109 | TRANSLATION_1 110 | -- a 111 | 112 | SCHEMA_1.TRANSLATION_1 113 | -- a simple qualified 114 | 115 | CATALOG_1.SCHEMA_1.TRANSLATION_1 116 | -- a fully qualified 117 | 118 | If you want to restrict your code to Core SQL, don't use any s. 120 | 121 | CREATE TRANSLATION Statement 122 | ============================ 123 | 124 | The ``CREATE TRANSLATION`` statement names a new user-defined Translation and 125 | specifies the Translation's source and target Character sets as well as the 126 | Translation's source. The required syntax for the ``CREATE TRANSLATION`` 127 | statement is: 128 | 129 | :: 130 | 131 | CREATE TRANSLATION user-defined 132 | FOR source 133 | TO target 134 | FROM 135 | 136 | ::= 137 | existing | 138 | 139 | 140 | ``CREATE TRANSLATION`` defines a new user-defined Translation. A Translation 141 | is owned by the Schema it belongs to. 142 | 143 | The user-defined identifies the new Translation and the 144 | Schema that it belongs to. A that includes an explicit 145 | qualifier belongs to the Schema named. A that 146 | does not include an explicit qualifier belongs to 147 | ``INFORMATION_SCHEMA``. Since a user-defined Translation can't belong to 148 | ``INFORMATION_SCHEMA``, always provide an explicit qualifier when 149 | you're creating a Translation. 150 | 151 | If ``CREATE TRANSLATION`` is part of a ``CREATE SCHEMA`` statement, the 152 | must include the of the Schema being created; 153 | that is, it isn't possible to create a Translation belonging to a different 154 | Schema from within ``CREATE SCHEMA``. For example, this SQL statement will not 155 | return an error because the explicitly includes a qualifying 156 | that matches the name of the Schema being created: 157 | 158 | :: 159 | 160 | CREATE SCHEMA bob 161 | CREATE TRANSLATION bob.translation_1 162 | FOR SQL_CHARACTER TO LATIN1 FROM function_name; 163 | -- creates a Translation called BOB.TRANSLATION_1 in Schema BOB 164 | 165 | But this SQL statement will return an error because the 166 | explicitly includes a qualifying that is different from the name 167 | of the Schema being created: 168 | 169 | :: 170 | 171 | CREATE SCHEMA bob 172 | CREATE TRANSLATION sam.translation_1 173 | FOR SQL_CHARACTER TO LATIN1 FROM function_name; 174 | -- tries to create a Translation belonging to Schema SAM inside Schema BOB; illegal syntax 175 | 176 | If ``CREATE TRANSLATION`` is executed as a stand-alone SQL statement, the 177 | current must either be the owner of the Schema that this new 178 | Translation belongs to, or the Schema's owner must be a Role that the current 179 | may use. That is, only the owner of a Schema can create 180 | Translations for that Schema. In addition to creating a Translation, ``CREATE 181 | TRANSLATION`` also causes the SQL special grantor, "``_SYSTEM``", to grant the 182 | ``USAGE`` Privilege on the new Translation to the Schema owner 183 | (that is, the also has a grantable ``USAGE`` 185 | Privilege on both the Translation's source Character set and its target 186 | Character set. 187 | 188 | A user-defined Translation must be defined to operate on a pair of Character 189 | sets. The ``FOR`` clause of the ``CREATE TRANSLATION`` statement names the 190 | source Character set; the ``TO`` clause names the target Character set. In each 191 | case, must be the name of an existing Character set for 192 | which the current has the ``USAGE`` Privilege. 193 | 194 | A user-defined Translation must also be defined as using a source mapping 195 | scheme: it defines the source and target Character sets' corresponding pairs of 196 | characters. The ``FROM`` clause of the ``CREATE TRANSLATION`` statement names 197 | this Translation source. If the ``FROM`` clause names some other Translation as 198 | the new Translation's source, the existing must be the name 199 | of an existing Translation for which the current has the 200 | ``USAGE`` Privilege and whose source Character set and target Character set are 201 | the same as the source and target Character sets you're defining for the new 202 | Translation. For example, this SQL statement: 203 | 204 | :: 205 | 206 | CREATE TRANSLATION bob.translation_2 207 | FOR SQL_CHARACTER TO LATIN1 FROM bob.translation_1; 208 | 209 | defines a new user-defined Translation, called ``BOB.TRANSLATION_2``, in the 210 | Schema named ``BOB``. Except for its name, the Translation 211 | ``BOB.TRANSLATION_2`` will be exactly the same as the ``BOB.TRANSLATION_1`` 212 | Translation -- that is, it is not truly possible to "create" new Translations 213 | with this format, merely to rename them. The other option for specifying a 214 | Translation source is to use a that names an 215 | SQL-invoked function for which the current has the 216 | ``EXECUTE`` Privilege. The function named must *(a)* have one character string 217 | parameter whose Character set is this Translation's source Character set and 218 | *(b)* return a character string that belongs to this Translation's target 219 | Character set. 220 | 221 | If you want to restrict your code to Core SQL, don't use the ``CREATE 222 | TRANSLATION`` statement. 223 | 224 | DROP TRANSLATION Statement 225 | ========================== 226 | 227 | The ``DROP TRANSLATION`` statement destroys a user-defined Translation. The 228 | required syntax for the ``DROP TRANSLATION`` statement is: 229 | 230 | :: 231 | 232 | DROP TRANSLATION 233 | 234 | The must identify an existing Translation whose owner is 235 | either the current or a Role that the current 236 | may use. That is, only the that owns the 237 | Translation may drop it, and so it isn't possible to drop any of the predefined 238 | Translations provided by your DBMS. 239 | 240 | The effect of ``DROP TRANSLATION`` , e.g.: 241 | 242 | :: 243 | 244 | DROP TRANSLATION bob.translation_1; 245 | 246 | is that the user-defined Translation named ``BOB.TRANSLATION_1`` is destroyed, 247 | provided that the Translation is not referred to in any View definition, 248 | Constraint or Assertion definition, Collation definition, other Translation 249 | definition or SQL routine. That is, ``DROP TRANSLATION`` ensures that only a 250 | Translation with no dependent Objects can be destroyed. If the Translation is 251 | used by any other Object, ``DROP TRANSLATION`` will fail. 252 | 253 | If successful, ``DROP TRANSLATION`` has a two-fold effect. 254 | 255 | 1. The Translation named is destroyed. 256 | 257 | 2. The ``USAGE`` Privilege held on the Translation by the 258 | that owns it is revoked (by the SQL special grantor, "``_SYSTEM``") with a 259 | ``CASCADE`` revoke behaviour, so that the ``USAGE`` Privilege held on the 260 | Translation by any other is also revoked. 261 | 262 | If you want to restrict your code to Core SQL, don't use the ``DROP 263 | TRANSLATION`` statement. 264 | -------------------------------------------------------------------------------- /docs/chapters/28.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | ================================================= 4 | Chapter 28 -- Introduction to SQL-data operations 5 | ================================================= 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | In this chapter, we'll describe some common SQL constructs. We'll be using 10 | these constructs in the following chapters, to describe how operations on SQL- 11 | data work. [Obscure Rule] applies to everything we talk about here, but the 12 | definitions are a necessary evil for understanding some of what lies ahead. 13 | 14 | .. rubric:: Table of Contents 15 | 16 | .. contents:: 17 | :local: 18 | 19 | 20 | ===================== 21 | 22 | A is a scalar expression that specifies either a 23 | , a host language variable parameter or an SQL parameter as a source 24 | for a data value. The required syntax for a is: 25 | 26 | :: 27 | 28 | ::= 29 | | 30 | 31 | 32 | ::= 33 | [ [ INDICATOR ] ] | 34 | | 35 | | 36 | CURRENT_PATH | 37 | CURRENT_ROLE | 38 | CURRENT_USER | 39 | SESSION_USER | 40 | SYSTEM_USER | 41 | USER | 42 | VALUE 43 | 44 | ::= 45 | | 46 | | 47 | 48 | 49 | A specifies a value that is not selected from a Table -- 50 | that is, a is either the value represented by a 51 | , the value represented by a host language variable or the value 52 | represented by an SQL parameter. A simple is either a 53 | , the value of a host language variable or the value of an SQL 54 | parameter: it may not be the null value. If a does 55 | evaluate to ``NULL``, the SQL statement that contains it will fail: your DBMS 56 | will return the ``SQLSTATE error 22004 "data exception-null value not 57 | allowed"``. 58 | 59 | A host parameter specification identifies a host parameter (or a host parameter 60 | and its indicator) in an SQL-client Module. If the indicator for a host 61 | parameter is set to a negative number, that means the value represented by the 62 | host parameter is ``NULL``. If the indicator is set to any other number, that 63 | means the value represented by the host parameter is the current value of that 64 | host parameter. The required syntax for a is: 65 | 66 | :: 67 | 68 | ::= 69 | : 70 | 71 | A is a or a 72 | preceded by a colon (for example, ``:param_name``) -- it identifies a host 73 | language parameter, so the name you choose must also, of course, be a valid 74 | parameter name in that host language. Each must be 75 | defined in the SQL-client Module that you use it in. The indicator for a host 76 | parameter has to be an integer type. We'll talk more about host parameters and 77 | variables in our chapters on binding styles. 78 | 79 | An identifies a parameter of an SQL-invoked routine, 80 | so it can be the name of a function that returns only one value (for example, 81 | ``CURRENT_ROLE``) or an . (For the syntax of an , see our chapter on SQL-invoked routines.) The value 83 | represented by an is the current value of that SQL 84 | parameter. 85 | 86 | An identifies an element of an array; see out chapter on 87 | s. The value represented by an is the 88 | current value of that element in that particular array. 89 | 90 | ``CURRENT_ROLE``, ``CURRENT_USER``, ``SESSION_USER``, ``SYSTEM_USER`` and 91 | ``USER`` all identify an ; see our chapter on that SQL Object. 92 | The value represented by any of these functions is the current value returned 93 | by that function: each returns an ``SQL_TEXT`` character string whose value 94 | represents an . 95 | 96 | ``CURRENT_PATH`` identifies a list that helps your DBMS track 97 | routines. In the list, both the s and their qualifying s are s and multiple s are separated by 99 | commas. 100 | 101 | [NON-PORTABLE] The result of ``CURRENT_PATH`` is non-standard because the SQL 102 | Standard requires implementors to define whether the result string is fixed 103 | length or variable length and the result string's fixed length or maximum 104 | length (as applicable). 105 | 106 | [OCELOT Implementation] The OCELOT DBMS that comes with this book has 107 | ``CURRENT_PATH`` return a variable length ``SQL_TEXT`` string. The result has a 108 | maximum length of 128 octets. 109 | 110 | ``VALUE`` identifies an instance of a data value and can only be used in a 111 | Domain definition; see our chapter on Domains. 112 | 113 | [Obscure Rule] If the of a is character 114 | string, the character string it represents has a coercibility attribute of 115 | ``COERCIBLE``. 116 | 117 | If you want to restrict your code to Core SQL, don't use an 118 | or ``CURRENT_PATH`` to specify a value. 119 | 120 | 121 | ================== 122 | 123 | A is a scalar expression that specifies a data value. In 124 | this book, we most often use the term ``scalar_expression`` to show you where a 125 | is allowed in SQL syntax. The required syntax for a is: 127 | 128 | :: 129 | 130 | ::= 131 | | 132 | | 133 | | 134 | | 135 | 136 | | 137 | | 138 | | 139 | | 140 | 141 | A specifies a value that may or may not be selected from a 142 | Table -- that is, it may be a or it may be the result of 143 | an expression on SQL-data that returns a single number, character string, bit 144 | string, ``BLOB``, date, time, timestamp, interval, Boolean value, UDT value, 145 | row of data, ``REF`` value or array. The of a is 146 | determined by the of the value it evaluates to. 147 | 148 | The following SQL constructs all qualify as s; each can 149 | optionally include a Collation specification (i.e.: ``COLLATE`` ) to force a collating sequence for the value represented by the , provided that value's is character string: 152 | 153 | * A : represents the value of that Column. 154 | 155 | * A set function specification: represents the value returned by that function. 156 | 157 | * A scalar subquery: represents the value returned by that subquery. 158 | 159 | * A ``CASE`` expression: represents the value returned by that expression. 160 | 161 | * A ``CAST`` specification: represents the value as ``CAST`` to the target 162 | . 163 | 164 | * A : represents the value as modified. 165 | 166 | * A : represents the value returned by that function. 167 | 168 | * An : represents the value of that array. 169 | 170 | * A : represents the value returned by that routine. 171 | 172 | * A : represents the value of that Field of a particular row. 173 | 174 | * A and a : represents the value 175 | returned by that method. 176 | 177 | If you want to restrict your code to Core SQL, don't use a 178 | that evaluates to a Boolean value, an array, an interval or a ``REF`` value, 179 | don't use a to specify a value and don't use the 180 | ``COLLATE`` clause to force a collating sequence for any value. 181 | 182 | 183 | ======================= 184 | 185 | A defines an ordered set of values that make up one 186 | row of data. The required syntax for a is: 187 | 188 | :: 189 | 190 | ::= 191 | | 192 | ( [ {,} ... ]) | 193 | } 194 | 195 | A constructs a row of data values in one of three 196 | possible ways: 197 | 198 | 1. By evaluating a single , for example, the ``'GOODBYE'``. In this case, the may 200 | not be enclosed in parentheses. This rule is explicitly stated in the SQL 201 | Standard to resolve a syntactic ambiguity: in certain circumstances, the 202 | syntax: () is permitted. 203 | 204 | 2. By evaluating two or more comma-delimited s enclosed in 205 | parentheses, for example: (``'GOODBYE',10``). 206 | 207 | 3. By evaluating a , for example: 208 | 209 | :: 210 | 211 | ... (SELECT column_2, column_5 FROM Table_2) 212 | 213 | The s of the Column(s) of a are the s of the (s) or the Column(s) of the that 215 | make up the . If a is derived 216 | from a , then the degree (i.e.: the number of Columns) of the 217 | is the degree of the Table that results from the 218 | evaluation of the ; otherwise, the degree of the is the number of s that make up the . 221 | 222 | In this case, if the number of rows returned by the is zero, the 223 | result is a single row containing null values for every Column of the . If the number of rows returned by the subquery is one, the result is 225 | that single row. (Note: a may not return more than one row.) 226 | 227 | 228 | ====================== 229 | 230 | A is a scalar expression that specifies a host language 231 | variable parameter, an SQL parameter or a Column as the target for a data 232 | value. The required syntax for a is: 233 | 234 | :: 235 | 236 | ::= 237 | [ [ INDICATOR ] ] | 238 | | 239 | 240 | 241 | A specifies a place to put a value. Most often, this 242 | will be a (as in an ``INSERT`` statement), but you can also 243 | assign values to an output SQL parameter (see our chapter on SQL-invoked 244 | routines) or to a variable in a host language program (see our chapters on 245 | binding styles). A is either a host language 246 | variable, an output SQL parameter or a "known not nullable" Column: it may not 247 | be the null value. 248 | -------------------------------------------------------------------------------- /docs/chapters/34.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | ==================================== 4 | Chapter 34 -- Sorting Search Results 5 | ==================================== 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | In SQL, you can only sort search results returned by a Cursor. However, when 10 | you're using Direct SQL, you're always using an implied Cursor, and so we'll 11 | describe the ``ORDER BY`` clause now. 12 | 13 | .. rubric:: Table of Contents 14 | 15 | .. contents:: 16 | :local: 17 | 18 | ORDER BY Clause 19 | =============== 20 | 21 | The required syntax for the ``ORDER BY`` clause is: 22 | 23 | :: 24 | 25 | [ ORDER BY ] 26 | 27 | ::= 28 | [ {, }... ] 29 | 30 | ::= 31 | [ COLLATE ] [ {ASC | DESC} ] 32 | 33 | ::= scalar_expression 34 | 35 | An ``ORDER BY`` clause may optionally appear after a : it 36 | specifies the order rows should have when returned from that query (if you omit 37 | the clause, your DBMS will return the rows in some random order). The query in 38 | question may, of course, be a ``VALUES`` statement, a ``TABLE`` statement or 39 | (most commonly) a ``SELECT`` statement. (For now, we are ignoring the 40 | possibility that the SQL statement is ``DECLARE CURSOR``, since that is 41 | strictly a matter for "SQL in Host Programs", a later chapter.) 42 | 43 | The ``ORDER BY`` clause provides your DBMS with a list of items to sort, and 44 | the order in which to sort them: either ascending order (``ASC``, the default) 45 | or descending order (``DESC``). It must follow a because it 46 | operates on the final Table that results from the evaluation of the query; it 47 | cannot operate on any interim result Tables at all. The you specify 48 | can be any expression that evaluates to a single value that identifies a Column 49 | of the final result Table -- this is almost always a . Here's a 50 | simple example: 51 | 52 | :: 53 | 54 | SELECT column_1 55 | FROM Table_1 56 | ORDER BY column_1; 57 | 58 | This SQL statement retrieves all ``COLUMN_1`` values from ``TABLE_1``, 59 | returning them in ascending order. This SQL statement does exactly the same: 60 | 61 | :: 62 | 63 | SELECT column_1 64 | FROM Table_1 65 | ORDER BY column_1 ASC; 66 | 67 | This SQL statement also retrieves all ``COLUMN_1`` values from ``TABLE_1`` 68 | -- but returns them in descending order: 69 | 70 | :: 71 | 72 | SELECT column_1 73 | FROM Table_1 74 | ORDER BY column_1 DESC; 75 | 76 | The optional sort s ``ASC`` and ``DESC`` stand respectively for 77 | "ascending order" and "descending order". Some examples of ascending order are 78 | {``1,2,3``} and {``'A','B','C'``}; examples of descending order are {``3,2,1``} 79 | and {``'C','B','A'``}. If you omit the sort , it defaults to ``ASC``. 80 | 81 | Note that, because ``ORDER BY`` may operate only on a final result, you can't 82 | put it in a subquery or before a set function -- that is, these two SQL 83 | statements are illegal: 84 | 85 | :: 86 | 87 | SELECT column_1 88 | FROM Table_1 89 | WHERE column_1 > ANY 90 | (SELECT column_1 91 | FROM Table_2 92 | ORDER BY column2); 93 | 94 | SELECT column_1 95 | FROM Table_1 96 | ORDER BY column_1 97 | UNION ALL 98 | SELECT column_1 99 | FROM Table_2; 100 | 101 | An ``ORDER BY`` is normally the name of a Column in the query's 102 | select list. It cannot be a -- the SQL-92 option of putting an 103 | integer after ``ORDER BY``, to identify a Column by its ordinal position in the 104 | result Table, is not allowed in SQL3. The can, however, be an 105 | expression that evaluates to a Column of the result Table (even if that Column 106 | isn't in the select list). Since this is the case, it is useful to remember 107 | that such Column expressions may be given explicit names using "[``AS`` ]" clauses. The "[``AS`` ]" clause can also be useful for 109 | "unioned" ``SELECT``\s. For example: 110 | 111 | :: 112 | 113 | SELECT column_1 AS column_1_or_column_2 114 | FROM Table_1 115 | UNION ALL 116 | SELECT column_2 AS column_1_or_column_2 117 | FROM Table_2 118 | ORDER BY column_1_or_column_2; 119 | 120 | Whatever way you identify the result Columns you want to sort though, they may 121 | not have a of ``BLOB``, ``CLOB`` or ``NCLOB``. For a 122 | with a character string , you may also specify an explicit Collation 123 | for your DBMS to use when sorting that Column's values. 124 | 125 | If ``ORDER BY`` contains multiple s, the primary ordering is by the 126 | first , the secondary ordering is by the second and so on 127 | -- this is called *major-to-minor ordering*. For example, here's an extract 128 | from a telephone book: 129 | 130 | +----------+---------------+----------+ 131 | | Dunbar L | 11407 141 Ave | 456-4478 | 132 | +----------+---------------+----------+ 133 | | Duncan J | 9419 101A Ave | 423-0541 | 134 | +----------+---------------+----------+ 135 | | Duncan J | 14705 103 Ave | 452-9565 | 136 | +----------+---------------+----------+ 137 | | Duncan J | 4911 40 Ave | 450-6289 | 138 | +----------+---------------+----------+ 139 | | Duncan L | 9110 150 St | 486-2075 | 140 | +----------+---------------+----------+ 141 | 142 | As one would expect in a telephone book, the entries are sorted *(a)* by 143 | surname and then *(b)* by first initial. In SQL, this order would be 144 | accomplished with a ``SELECT`` statement like this one: 145 | 146 | :: 147 | 148 | SELECT surname, initial, address, phone 149 | FROM Clients 150 | ORDER BY surname, initial; 151 | 152 | *Sorting NULLs* 153 | --------------- 154 | 155 | It isn't usually possible to make meaningful comparisons with null values, so 156 | the following comparison rules are applicable only in the context of an ``ORDER 157 | BY`` clause: 158 | 159 | * A ``NULL`` is "equal" to a ``NULL`` for sorting purposes. 160 | 161 | * [NON-PORTABLE] Either a ``NULL`` is greater than all non-null values or a 162 | ``NULL`` is less than all non-null values -- it's non-standard because the 163 | SQL Standard requires implementors to define whether ``NULL``\s sort high or 164 | low. Most vendors say "``NULL``\s are greater than all non-null values" -- in 165 | this case, a Table with these rows: {``7,5,-1,NULL``} will end up in this 166 | order: {``-1,5,7,NULL``} if you ask for an ascending sort. 167 | 168 | [OCELOT Implementation] The OCELOT DBMS that comes with this book sorts 169 | ``NULL``\s low: a ``NULL`` is less than all non-null values. 170 | 171 | *The Effect of DESC* 172 | -------------------- 173 | 174 | We've already said that if you put the ``DESC`` after a , 175 | the ordering will be *reversed* for that . Unfortunately, we have to 176 | belabor what appears to be an obvious and simple fact, because some pundits 177 | have mis-stated it. The following statements, taken from SQL books available at 178 | your book store, are drivel: 179 | 180 | * "``DESC`` is a sticky flag, so if you say "``ORDER BY`` a ``DESC, b``" then 181 | both ``a`` and ``b`` will appear in descending order." If anyone knows how 182 | this myth got started, please write to us: we're curious. 183 | 184 | * "If a vendor says that ``NULL``\s are greater than non-``NULL``\s, then (for 185 | standard SQL) they should appear last, even if ``DESC`` is specified." In 186 | other words -- taking the example we used in the last section -- if you asked 187 | for an ascending sort of a Table with these rows: {``7,5,-1,NULL``}, you'd 188 | get {``- 1,5,7,NULL``} and if you asked for a descending sort you'd get 189 | {``7,5,-1,NULL``}. In fact, standard SQL requires that the descending result 190 | be what a sane person would expect: {``NULL,7,5,-1``}. 191 | 192 | *Deprecated SQL-92 Syntax* 193 | -------------------------- 194 | 195 | The following examples, taken from real working programs, illustrate syntax 196 | that you should avoid or change for SQL3. 197 | 198 | :: 199 | 200 | SELECT E.dept FROM Employees E 201 | WHERE age < 21 202 | ORDER BY E.dept; 203 | 204 | Get rid of any s in an ``ORDER BY`` clause -- the actual name 205 | of the Column in the select list is merely ``DEPT``, despite appearances. Use 206 | an ``AS`` clause to give the Column another name if there is resulting 207 | ambiguity. 208 | 209 | :: 210 | 211 | SELECT balance, (balance - amount) FROM Accounts 212 | ORDER BY 1, 2; 213 | 214 | Get rid of any Column ordinal position references in an ``ORDER BY`` clause -- 215 | using ordinals as Column numbers is frowned on by SQL-92 and banned by SQL3. 216 | Again, the solution is to use an ``AS`` clause, so the Columns have explicit 217 | names -- for example: 218 | 219 | :: 220 | 221 | SELECT balance, (balance - amount) AS balance_minus_amount 222 | FROM Accounts 223 | ORDER BY balance, balance_minus_amount; 224 | 225 | *SQL3 features* 226 | --------------- 227 | 228 | These three SQL statements, which are illegal in SQL-92, are legal in SQL3: 229 | 230 | :: 231 | 232 | SELECT column_1 FROM Table_1 233 | ORDER BY column_2; 234 | 235 | The ``COLUMN_2`` is not in the select list, but it does belong to 236 | ``TABLE_1`` so this type of ``ORDER BY`` works, provided that the query does 237 | not contain ``DISTINCT``, a grouped Table, a set function or a set operator. 238 | 239 | :: 240 | 241 | SELECT column_1 + 5 FROM Table_1 242 | ORDER BY column_1 + 5; 243 | 244 | The "``COLUMN_1 + 5``" is an unnamed value expression, but this type 245 | of ``ORDER BY`` is legal because "``COLUMN_1 + 5``" appears in the query's 246 | select list. Your DBMS will find it by comparing the expressions, rather than 247 | comparing s. 248 | 249 | :: 250 | 251 | SELECT char_column FROM Table_1 252 | ORDER BY char_column COLLATE Schema_1.Polish; 253 | 254 | The ``COLLATE`` clause specified for the overrides whatever default 255 | Collation ``CHAR_COLUMN`` has. 256 | 257 | Essentially, these SQL3 "features" let you write sloppy code. We advise that 258 | you stick with the SQL-92 rule that all s must be names of Columns in 259 | the result select list. These three SQL statements, equivalent to the ones 260 | we've just shown you, are better code -- and are legal in both SQL-92 and 261 | SQL3: 262 | 263 | :: 264 | 265 | SELECT column_1, column_2 FROM Table_1 266 | ORDER BY column_2; 267 | 268 | SELECT column_1 + 5 AS column_1_plus_5 FROM Table_1 269 | ORDER BY column_1_plus_5; 270 | 271 | SELECT column_1 COLLATE Schema_1.Polish AS colpolish FROM Table_1 272 | ORDER BY colpolish; 273 | 274 | *Sorted Retrievals* 275 | ------------------- 276 | 277 | Here's some examples of sorted retrievals, using the sample database we 278 | defined in our chapter on "Simple Search Conditions". To retrieve an 279 | alphabetical list of departments, either of these SQL statements will work: 280 | 281 | :: 282 | 283 | SELECT dept FROM Department ORDER BY dept ASC; 284 | 285 | SELECT dept FROM Department ORDER BY dept; 286 | 287 | The result is: 288 | 289 | +----------+ 290 | | ``DEPT`` | 291 | +----------+ 292 | | A | 293 | +----------+ 294 | | B | 295 | +----------+ 296 | | C | 297 | +----------+ 298 | | D | 299 | +----------+ 300 | | E | 301 | +----------+ 302 | 303 | ``ORDER BY`` defaults to a sort in ascending order when no sort order is 304 | specified. 305 | 306 | To retrieve departments in descending order: 307 | 308 | :: 309 | 310 | SELECT dept FROM Department ORDER BY dept DESC; 311 | 312 | This time, the result is: 313 | 314 | +----------+ 315 | | ``DEPT`` | 316 | +----------+ 317 | | E | 318 | +----------+ 319 | | D | 320 | +----------+ 321 | | C | 322 | +----------+ 323 | | B | 324 | +----------+ 325 | | A | 326 | +----------+ 327 | 328 | To find an alphabetic list of employee names grouped by their departments 329 | sorted in descending order (retrieve multiple Columns with nested sort 330 | levels): 331 | 332 | :: 333 | 334 | SELECT dept,surname FROM Employee ORDER BY dept DESC,surname; 335 | 336 | The result is: 337 | 338 | +----------+---------------+ 339 | | ``DEPT`` | ``SURNAME`` | 340 | +----------+---------------+ 341 | | E | FRANCIS | 342 | +----------+---------------+ 343 | | E | OLSEN | 344 | +----------+---------------+ 345 | | D | MORGAN | 346 | +----------+---------------+ 347 | | C | JONES | 348 | +----------+---------------+ 349 | | B | JONES | 350 | +----------+---------------+ 351 | | B | MARSH | 352 | +----------+---------------+ 353 | | B | TURNER | 354 | +----------+---------------+ 355 | | B | WARREN | 356 | +----------+---------------+ 357 | | A | KOO | 358 | +----------+---------------+ 359 | | A | SMITH | 360 | +----------+---------------+ 361 | 362 | To find employee numbers and rates for employees with employee numbers less 363 | than 20, and to sort these by employee number within descending pay rate 364 | order, within descending location order: 365 | 366 | :: 367 | 368 | SELECT empnum,rate,location FROM Payroll WHERE empnum<20 369 | ORDER BY location DESC,rate DESC,empnum; 370 | 371 | The result is: 372 | 373 | +------------+----------+----------------+ 374 | | ``EMPNUM`` | ``RATE`` | ``LOCATION`` | 375 | +------------+----------+----------------+ 376 | | 3 | 5.00 | WAREHOUSE | 377 | +------------+----------+----------------+ 378 | | 4 | 8.00 | BASEMENT | 379 | +------------+----------+----------------+ 380 | | 10 | 16.00 | 16TH FLOOR | 381 | +------------+----------+----------------+ 382 | | 11 | 16.00 | 16TH FLOOR | 383 | +------------+----------+----------------+ 384 | | 2 | 5.00 | 16TH FLOOR | 385 | +------------+----------+----------------+ 386 | | 1 | 6.00 | 10TH FLOOR | 387 | +------------+----------+----------------+ 388 | 389 | To sort employee numbers in descending order within the daily pay rate: 390 | 391 | :: 392 | 393 | SELECT empnum,'Daily Rate=' AS comment, RATE*8 AS d_rate FROM Payroll 394 | ORDER BY d_rate,empnum DESC; 395 | 396 | The result is: 397 | 398 | +------------+-----------------+------------+ 399 | | ``EMPNUM`` | ``COMMENT`` | ``D_RATE`` | 400 | +------------+-----------------+------------+ 401 | | 3 | Daily Rate= | 40.00 | 402 | +------------+-----------------+------------+ 403 | | 2 | Daily Rate= | 40.00 | 404 | +------------+-----------------+------------+ 405 | | 1 | Daily Rate= | 48.00 | 406 | +------------+-----------------+------------+ 407 | | 4 | Daily Rate= | 64.00 | 408 | +------------+-----------------+------------+ 409 | | 35 | Daily Rate= | 72.00 | 410 | +------------+-----------------+------------+ 411 | | 20 | Daily Rate= | 72.00 | 412 | +------------+-----------------+------------+ 413 | | 40 | Daily Rate= | 128.00 | 414 | +------------+-----------------+------------+ 415 | | 11 | Daily Rate= | 128.00 | 416 | +------------+-----------------+------------+ 417 | | 10 | Daily Rate= | 128.00 | 418 | +------------+-----------------+------------+ 419 | | 28 | Daily Rate= | ``NULL`` | 420 | +------------+-----------------+------------+ 421 | 422 | Dialects 423 | ======== 424 | 425 | All SQL DBMSs support the ``ORDER BY`` clause. Some of them even allow the 426 | "``ORDER BY`` " syntax described above as an SQL3 feature, or some 427 | variant thereof -- we expect they all will fairly soon. 428 | -------------------------------------------------------------------------------- /docs/chapters/41.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | ==================================== 4 | Chapter 41 -- SQL/CLI: env Functions 5 | ==================================== 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | In this chapter, we'll describe the first essential CLI resource: the ``env``. 10 | For CLI programs, the ``env`` is the all-encompassing context area -- all CLI 11 | programs begin by establishing an ``env``. The ``env`` contains some 12 | information directly ("attributes" and "diagnostics"), but what's important is 13 | that an ``env`` contains zero or more ``dbcs`` (although there's no point in 14 | having an ``env`` without a ``dbc``). Here's a closeup view of an ``env``: 15 | 16 | :: 17 | 18 | ---------------------- 19 | - [env Attributes] - 20 | - [env Diagnostics] - 21 | ---------------------- 22 | | | 23 | | | 24 | v v 25 | ... to dbcs 26 | 27 | .. rubric:: Table of Contents 28 | 29 | .. contents:: 30 | :local: 31 | 32 | Null Termination 33 | ================ 34 | 35 | Traditionally, there have been three ways to define character strings: 36 | 37 | 1. They are fixed length. Example: a COBOL ``PIC X(5)`` variable. 38 | 39 | 2. They are variable length and a separate variable tells us the size. Example: 40 | the 16-bit octet-length -- ``SIZE%`` -- in a BASIC string ``var$``, or the 41 | 8-bit octet-length which is the first byte of a Turbo Pascal string. 42 | 43 | 3. They are variable length and the end is marked by a termination code. 44 | Example: the 8-bit byte ``= '\0'`` which ends strings in C programs. This 45 | code, which in a wide-character string would be a 16-bit word ``0x0000``, is 46 | the null terminator. Inprise Pascal (Delphi) uses the same convention for 47 | ``PChar`` variables. 48 | 49 | We've assumed that any DBMS which supports C/Pascal interfaces will go with 50 | null termination. That affects the CLI in only one way: you can receive 51 | null-terminated strings from the DBMS whenever Character String Retrieval is 52 | called for. Going the other way -- passing null-terminated strings to the DBMS 53 | -- is legal regardless of the setting of ``NULL TERMINATION``. That's because 54 | you indicate null termination of input strings using ``SQL_NTS`` for "size". 55 | 56 | Sixteen of the CLI functions accept an input-string parameter. In these 57 | functions, the parameter immediately following the input-string parameter is 58 | the *input-string length* -- for example: 59 | 60 | :: 61 | 62 | (... input_string, input_string_length); 63 | 64 | The input length should be the number of octets in the input string, not 65 | including the null termination octet(s). However, you can pass ``SQL_NTS 66 | (-3)`` instead -- this stands for "null terminated string" -- and let 67 | the DBMS calculate the string size. Remember, though, that programs 68 | which pass ``SQL_NTS`` are many nanoseconds slower than programs which 69 | pass an absolute length. 70 | 71 | There are six CLI functions for creating ``envs``, dropping ``envs``, 72 | getting ``env`` attributes and setting ``env`` attributes. Their 73 | descriptions follow. 74 | 75 | SQLAllocHandle(SQL_HANDLE_ENV,...) 76 | ================================== 77 | 78 | **Function Prototype:** 79 | 80 | :: 81 | 82 | SQLRETURN SQLAllocHandle( 83 | SQLSMALLINT HandleType, /* 16-bit input = SQL_HANDLE_ENV */ 84 | SQLINTEGER InputHandle, /* 32-bit input */ 85 | SQLINTEGER *OutputHandle /* pointer to 32-bit output, a henv */ 86 | ); 87 | 88 | **Job:** Allocate an ``env``. 89 | 90 | * How to make an ``env`` 91 | 92 | Usually the first SQL-related instruction is the call to make an ``env``: 93 | 94 | :: 95 | 96 | #include "sqlcli.h" 97 | SQLHENV henv; /* declare a henv, name it: henv */ 98 | SQLRETURN sqlreturn; /* code returned by SQL function */ 99 | ... 100 | sqlreturn = SQLAllocHandle(SQL_HANDLE_ENV,SQL_NULL_HANDLE,&henv); 101 | ... 102 | 103 | The first parameter (``HandleType``) is ``SQL_HANDLE_ENV``. 104 | 105 | The second parameter (``InputHandle``) doesn't matter here. As a style 106 | note: we follow a convention that "if the parameter value doesn't matter 107 | then use a constant containing the word ``NULL``. This convention helps 108 | make it clear that the value we're passing has no significance. 109 | 110 | The third parameter (``*OutputHandle``) must be an address of an 111 | environment handle. As explained before, we prefer to call an 112 | environment handle a "``henv``". But use a descriptive name for your 113 | program variable if you have one. 114 | 115 | If the function succeeds: you have a new ``env``. Keep the ``henv``, 116 | you'll need it later for input to other functions. 117 | 118 | * Testing for error returns 119 | 120 | [Obscure Rule] Error-testing is a bit unusual because the DBMS may put 121 | something into ``OutputHandle`` even if the function fails. This annotated code 122 | snippet shows the scenarios: 123 | 124 | :: 125 | 126 | sqlreturn = SQLAllocHandle(SQL_ALLOC_ENV,SQL_HANDLE_NULL,&henv); 127 | if (sqlreturn < 0) { 128 | /* There was an error so SQLAllocHandle returned a negative value. */ 129 | if (sqlreturn == SQL_NULL_HANDLE) { /* SQL_NULL_HANDLE=-2 */ 130 | /* SQL_HANDLE_ENV is not a valid code -- an "impossible" error */ } 131 | else { 132 | /* sqlreturn must be SQL_ERROR (-1), the only other possibility */ 133 | if (&henv==0) 134 | /* The problem is "invalid use of null pointer" -- the last parameter -- OutputHandle -- was zero. This error too is "impossible". */ 135 | if (henv<>SQL_NULL_HENV) { 136 | /* The DBMS has placed a "skeleton env handle" in henv. It's not good for much, but you can use henv to get an error message with the SQLGetDiagRec function. */ } 137 | else { 138 | /* The DBMS has placed zero in henv. There was an error, there is no skeleton env handle to get error messages with. You'll have to guess that there wasn't enough memory. */ } } 139 | else { 140 | /* There was no error. */ } 141 | 142 | There are several other possible errors/exception conditions that the 143 | ``SQLAllocHandle`` function might "raise". If they occur, the function will 144 | return a negative number: -2 (``SQL_INVALID_HANDLE``) or -1 (``SQL_ERROR``). 145 | For more detailed information, look up the ``SQLSTATE`` codes beginning with 146 | ``HY``, ``HY001`` or ``HY014`` in our chapter on SQL/CLI diagnostics. 147 | 148 | **Algorithm:** 149 | 150 | :: 151 | 152 | If (HandleType == SQL_HANDLE_ENV) { 153 | The DBMS allocates an object in memory. The DBMS creates a 32-bit handle for this object, its unique identifier. The DBMS puts the handle in the memory location addressed by OutputHandle. } 154 | 155 | **Notes:** 156 | 157 | * This is one of several ``SQLAllocHandle`` variants. The ``HandleType`` input 158 | parameter may contain any one of: 159 | 160 | +--------------------------------+------------------------------------+ 161 | | (implementation-defined) | <1 | 162 | +--------------------------------+------------------------------------+ 163 | | ``SQL_HANDLE_ENV`` | 1 ``/* handle of an ``env */`` | 164 | +--------------------------------+------------------------------------+ 165 | | ``SQL_HANDLE_DBC`` | 2 ``/* handle of a ``dbc */`` | 166 | +--------------------------------+------------------------------------+ 167 | | ``SQL_HANDLE_HSTMT`` | 3 ``/* handle of a ``stmt */`` | 168 | +--------------------------------+------------------------------------+ 169 | | ``SQL_HANDLE_DESC`` | 4 ``* handle of a ``desc */`` | 170 | +--------------------------------+------------------------------------+ 171 | | (implementation-defined) | >100 | 172 | +--------------------------------+------------------------------------+ 173 | 174 | In discussions of other CLI functions, we will usually ignore the 175 | "implementation-defined" possibilities. 176 | 177 | **ODBC:** The ``SQLAllocHandle`` function is new in ODBC 3.0. Error 178 | information will not be available until you call the "connect" function. 179 | 180 | SQLAllocEnv 181 | =========== 182 | 183 | **Function prototype:** 184 | 185 | :: 186 | 187 | SQLRETURN SQLAllocEnv( 188 | SQLHENV *henv /* pointer to 32-bit output, a henv */ 189 | ); 190 | 191 | **Job:** Make an ``env``. 192 | 193 | **Algorithm:** 194 | 195 | :: 196 | 197 | sqlreturn = SQLAllocEnv(&henv); 198 | 199 | is the same as 200 | 201 | :: 202 | 203 | sqlreturn = SQLAllocHandle(SQL_HANDLE_ENV,SQL_NULL_HANDLE,&henv); 204 | 205 | **Notes:** 206 | 207 | * Implicit Calls 208 | 209 | In the algorithm description, the words "is the same as" mean that, in effect, 210 | the DBMS calls ``SQLAllocHandle`` when you call ``SQLAllocEnv``. So you have 211 | called ``SQLAllocHandle`` indirectly, or -- as the Standard puts it -- 212 | "implicitly". For purposes of interpreting the somewhat legalistic Standard, it 213 | makes absolutely no difference whether you perform an operation explicitly or 214 | implicitly. 215 | 216 | * Obsolescent Handle Functions 217 | 218 | ``SQLAllocEnv`` is one of six functions -- ``SQLAllocEnv``, ``SQLFreeEnv``, 219 | ``SQLAllocConnect``, ``SQLFreeConnect``, ``SQLAllocStmt``, ``SQLFreeStmt`` - 220 | which are nowadays, mostly redundant. They are a legacy of the days when there 221 | were only three kinds of resources: ``env``, ``dbc`` and ``stmt``. Mostly, you 222 | will see them in programs written for early versions of ODBC. The Standard does 223 | not "deprecate" these functions, so we may assume that they will continue to be 224 | part of standard SQL for the indefinite future. However, their presence will 225 | make a program look old-fashioned. The only exception is ``SQLFreeStmt``, which 226 | has a few useful options. 227 | 228 | **Example:** 229 | 230 | :: 231 | 232 | #include "sqlcli.h" 233 | SQLHENV henv; 234 | SQLRETURN sqlreturn; 235 | ... 236 | sqlreturn = SQLAllocEnv(&henv); 237 | if (sqlreturn == SQL_ERROR) { 238 | printf("Error: could not make an env.\n"); 239 | exit(1); } 240 | 241 | **ODBC:** The ``SQLAllocEnv`` routine has been in ODBC since version 1.0. The 242 | ODBC 3.0 manual deprecates it, suggesting that users should switch to using 243 | ``SQLAllocHandle(SQL_HANDLE_ENV,...)``. 244 | 245 | SQLGetEnvAttr 246 | ============= 247 | 248 | **Function Prototype:** 249 | 250 | :: 251 | 252 | SQLRETURN SQLGetEnvAttr( 253 | SQLHENV henv, /* 32-bit input */ 254 | SQLINTEGER Attribute, /* 32-bit input */ 255 | SQLPOINTER Value, /* ANY* pointer to output */ 256 | SQLINTEGER BufferLength, /* 32-bit input */ 257 | SQLINTEGER *StringLength); /* 32-bit pointer to output */ 258 | 259 | **Job:** Get an ``env`` attribute. At the moment there is only one standard 260 | ``env`` attribute: a flag saying whether strings are null-terminated. The flag 261 | has this ``#define`` in ``sqlcli.h``: 262 | 263 | :: 264 | 265 | #define SQL_ATTR_OUTPUT_NTS 10001 /* NULL TERMINATION env attribute */ 266 | 267 | **Algorithm:** 268 | 269 | :: 270 | 271 | If (henv is not a henv or env is a skeleton env) 272 | return with error: CLI-specific condition - invalid handle 273 | Empty env's diagnostics area. 274 | If (Attribute <> SQL_ATTR_OUTPUT_NTS) 275 | return with error: HY092 CLI-specific condition-invalid attribute identifier 276 | Set *Value = env's NULL TERMINATION env attribute 277 | /* This value is 1 (TRUE) if the DBMS uses null termination; it is 0 (FALSE) if not. */ 278 | 279 | **Notes:** 280 | 281 | * The ``BufferLength??`` and ``StringLength`` parameters are unused. They're 282 | there in case a future edition of the SQL Standard requires more information. 283 | Or, as with all functions, there is a chance that your particular DBMS stores 284 | attribute information that the Standard doesn't officially require. 285 | 286 | **Example:** 287 | 288 | :: 289 | 290 | #include "sqlcli.h" 291 | SQLHENV henv; 292 | SQLINTEGER attribute; 293 | ... 294 | SQLGetEnvAttr(henv,SQL_ATTR_OUTPUT_NTS,&attribute,NULL,NULL); 295 | 296 | **ODBC:** The ``SQLGetEnvAttr`` function is new in ODBC 3.0. There are also 297 | a few other ``env`` options which are specific to ODBC. 298 | 299 | SQLSetEnvAttr 300 | ============= 301 | 302 | **Function Prototype:** 303 | 304 | :: 305 | 306 | SQLRETURN SQLSetEnvAttr( 307 | SQLHENV henv, /* 32-bit input -- env handle */ 308 | SQLINTEGER Attribute, /* 32-bit input */ 309 | SQLPOINTER Value, /* ANY* input */ 310 | SQLINTEGER StringLength /* 32-bit input */ 311 | ); 312 | 313 | **Job:** Set an ``env`` attribute. At the moment there is only one standard 314 | ``env`` attribute -- whether output strings are null-terminated -- see the 315 | discussion of the ``SQLGetEnvAttr`` function for some detailed remarks on the 316 | subject of Null Termination. It is probably sufficient to know that you do not 317 | want to change this attribute if you program in C or Pascal. 318 | 319 | **Algorithm:** 320 | 321 | :: 322 | 323 | If (henv is not a henv) or (env is skeleton env) 324 | return with error: CLI-specific condition-invalid handle 325 | Empty the env's diagnostics area. 326 | If (there is a dbc in this env) 327 | /* You should call SQLSetEnvAttr before calling SQLAllocHandle(SQL_HANDLE_DBC,...) */ 328 | return with error: HY011 CLI-specific condition-attribute cannot be set now 329 | If (Attribute <> SQL_ATTR_OUTPUT_NTS) 330 | return with error: HY092 CLI-specific condition-invalid attribute identifier 331 | If (Attribute == SQL_ATTR_OUTPUT_NTS) 332 | /* in sqlcli.h there is a line: "#define 10001 SQL_ATTR_OUTPUT_NTS" */ 333 | If (*Value == TRUE) then set env's NULL TERMINATION attribute = TRUE. 334 | Else If (*Value == FALSE) then set NULL TERMINATION attribute = FALSE. 335 | Else return with error: HY024 CLI-specific condition-invalid attribute value 336 | 337 | **Notes:** 338 | 339 | * There might be some other, implementation-defined, ``env`` attributes. 340 | That is why there is a ``StringLength`` parameter -- in case there is an 341 | implementation-defined attribute which is represented as a character string. 342 | 343 | **Example:** 344 | 345 | :: 346 | 347 | #include "sqlcli.h" 348 | SQLHENV henv; 349 | SQLINTEGER Value=1; 350 | void main () 351 | { 352 | if (SQLAllocHandle(SQL_HANDLE_ENV,SQL_NULL_HANDLE,&henv)<0) { 353 | printf("Error: can't create the env\n"); 354 | exit(1); } 355 | if (SQLSetEnvAttr(henv,SQL_ATTR_OUTPUT_NTS,&Value,NULL)<0) { 356 | printf("Error: can't set the NULL TERMINATION env attribute\n"); 357 | exit(1); } 358 | exit(0); } 359 | 360 | **ODBC:** The ``SQLSetEnvAttr`` function is new in ODBC 3.0. It is 361 | impossible to change the ``NULL TERMINATION env`` attribute. There are 362 | other attributes. For example, to explicitly state that your application is 363 | written for ODBC version 3.0, say: 364 | 365 | :: 366 | 367 | version = SQL_OV_ODBC3; /* 00000003L */ 368 | SQLSetEnvAttr(henv,SQL_ATTR_ODBC_VERSION,&version,NULL); 369 | 370 | SQLFreeHandle(SQL_HANDLE_ENV,...) 371 | ================================= 372 | 373 | **Function Prototype:** 374 | 375 | :: 376 | 377 | SQLRETURN SQLFreeHandle( 378 | SQLSMALLINT HandleType, /* 16-bit input */ 379 | SQLINTEGER Handle /* 32-bit input (must be a henv) */ 380 | ); 381 | 382 | **Job:** Destroy an ``env``. This is the reverse of the 383 | ``SQLAllocHandle(SQL_HANDLE_ENV,...)`` function. 384 | 385 | **Algorithm:** 386 | 387 | :: 388 | 389 | If (Handle is not a henv) 390 | return error: CLI-specific condition-invalid handle 391 | Empty the env's diagnostics area. 392 | If (there is a dbc associated with the env) 393 | return error: HY010 CLI-specific condition-function sequence error 394 | Deallocate env and anything associated with it, such as RAM. 395 | The handle is now invalid. 396 | 397 | **Notes:** 398 | 399 | * This is usually the last function call in a CLI program. 400 | 401 | **Example:** 402 | 403 | :: 404 | 405 | #include "sqlcli.h" 406 | SQLHENV henv; 407 | ... 408 | SQLFreeHandle(SQL_HANDLE_ENV,henv); 409 | 410 | **ODBC:** The ``SQLFreeHandle`` function is new in ODBC 3.0. 411 | 412 | SQLFreeEnv 413 | ========== 414 | 415 | **Function Prototype:** 416 | 417 | :: 418 | 419 | SQLRETURN SQLFreeEnv( 420 | SQLHENV henv /* 32-bit input */ 421 | ); 422 | 423 | **Job:** Destroy an ``env``. This is the reverse of the ``SQLAllocEnv`` 424 | function. ``SQLFreeEnv`` is redundant. 425 | 426 | **Algorithm:** 427 | 428 | :: 429 | 430 | sqlreturn = SQLFreeEnv(henv); 431 | 432 | is the same thing as 433 | 434 | :: 435 | 436 | sqlreturn = SQLFreeHandle(SQL_HANDLE_ENV,henv); 437 | 438 | **Notes:** 439 | 440 | * The Standard does not say that the ``SQLFreeEnv`` function is 441 | deprecated. All DBMSs should support it. 442 | 443 | **Example:** 444 | 445 | :: 446 | 447 | #include "sqlcli.h" 448 | SQLHENV henv; 449 | ... 450 | SQLAllocEnv(&henv); 451 | ... 452 | SQLFreeEnv(henv); 453 | /* henv is now an invalid handle */ 454 | ... 455 | 456 | **ODBC:** The ``SQLFreeEnv`` function has been in ODBC since version 1.0. 457 | The ODBC 3 manual deprecates it, suggesting that users should switch to 458 | using ``SQLFreeHandle(SQL_HANDLE_ENV,...)``. 459 | 460 | And that's it for the ``env`` functions. In the next chapter, we'll take a look 461 | at the ``dbc`` functions. 462 | -------------------------------------------------------------------------------- /docs/chapters/49.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | =================================================== 4 | Chapter 49 -- SQL/CLI: Deferred Parameter Functions 5 | =================================================== 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | This short chapter describes an option for passing input parameters after 10 | execution begins. [Obscure Rule] applies for the whole thing. 11 | 12 | The concept behind deferred parameters is illustrated by these two flow charts: 13 | 14 | :: 15 | 16 | Processing immediate parameters Processing Deferred parameters 17 | 18 | -------------------- -------------- 19 | - SQLBindParameter - - SQLExecute - 20 | -------------------- -------------- 21 | | | 22 | ---------------- / \ 23 | - SQLExecute - / \ 24 | ---------------- /need \ yes -------------- 25 | / data? \___ - SQLParam - 26 | \ / - + - 27 | \ / - SQLPutData - 28 | | -------------- 29 | | no 30 | -------------------------- 31 | - SQLExecute (continued) - 32 | -------------------------- 33 | 34 | Briefly stated: in the immediate-parameter situation all necessary information 35 | is supplied before SQL statement execution begins; in the deferred-parameter 36 | situation the execution is interrupted and the host supplies the missing 37 | information by calling ``SQLParam`` and ``SQLPutData``. 38 | 39 | Programmers can survive with immediate parameters alone. Indeed, in all the 40 | previous chapters we have assumed that deferred parameters won't happen -- had 41 | we allowed for them, we would have had to do some things differently. 42 | 43 | The reasons for use of deferred parameters are: 44 | 45 | * Long strings can be passed a piece at a time. This was an important thing in 46 | the days of 16-bit operating systems, when the maximum string size was 47 | effectively limited by the segment size. 48 | 49 | * Microsoft uses deferred parameters in ODBC examples and test programs. 50 | 51 | These are the days of 32-bit operating systems. Passing large buffers is no 52 | longer a problem. However, deferred parameters are still part of the standard 53 | SQL CLI. You might see them in legacy code, or in some exotic applications (for 54 | example, packet transfers). You will not see deferred parameters in embedded 55 | SQL or PSM applications. 56 | 57 | .. rubric:: Table of Contents 58 | 59 | .. contents:: 60 | :local: 61 | 62 | How to Pass Deferred Parameters 63 | =============================== 64 | 65 | The mechanism for passing deferred parameters involves a package of signals 66 | and functions: 67 | 68 | * Setting the last parameter ``= SQL_DATA_AT_EXEC (-2)``. Technically: 69 | 70 | :: 71 | 72 | Set *(APD.IDA[n].SQL_DESC_OCTET_LENGTH_POINTER) = -2 73 | 74 | For example: 75 | 76 | :: 77 | 78 | #include "sqlcli.h" 79 | SQLHSTMT hstmt; 80 | SQLHDESC hdesc; 81 | SQLINTEGER dp = SQL_DATA_AT_EXEC; 82 | ... 83 | SQLGetStmtAttr(hstmt,SQL_ATTR_IMP_PARAM_DESC,&hdesc,NULL,NULL); 84 | SQLSetDescField(hdesc,1,SQL_DESC_OCTET_LENGTH_POINTER,&dp,NULL); 85 | 86 | * Looking for ``SQL_NEED_DATA`` after ``SQLExecDirect`` or ``SQLExecDirect`` 87 | -- for example: 88 | 89 | :: 90 | 91 | sqlreturn = SQLExecute(hstmt); 92 | if (sqlreturn == SQL_NEED_DATA) /* deferred parameter seen ... */ 93 | 94 | * Looping -- calling ``SQLParamData`` for each parameter and calling 95 | ``SQLPutData`` for each piece of data in each parameter. 96 | 97 | The two CLI functions needed for deferred parameter support are 98 | ``SQLParamData`` and ``SQLPutData``; their descriptions follow. We'll also 99 | describe ``SQLCancel`` in this chapter -- it might be used to cancel functions 100 | which are waiting for deferred parameters (hence its inclusion here), but might 101 | have unrelated uses as well. 102 | 103 | SQLParamData 104 | ============ 105 | 106 | **Function Prototype:** 107 | 108 | :: 109 | 110 | SQLRETURN SQLParamData( 111 | SQLHSTMT hstmt, /* 32-bit input */ 112 | SQLPOINTER *Value /* pointer to ANY* output */ 113 | ); 114 | 115 | **Job:** Check whether a deferred parameter value is needed. If so: interrupt; 116 | if not: continue with previously-interrupted statement execution. 117 | 118 | **Algorithm:** 119 | 120 | :: 121 | 122 | If (no deferred parameter number is associated with stmt) 123 | return error: HY010 CLI-specific condition-function sequence error 124 | /* A "deferred parameter" is an APD.IDA for which DEFERRED is true. 125 | DEFERRED is true if: 126 | *(APD.IDA[n].SQL_DESC_OCTET_POINTER) == SQL_DATA_AT_EXEC, i.e. -2. */ 127 | If there is a deferred parameter, but no deferred parameter value: 128 | /* i.e.: if we have not already gotten the value in a prior call 129 | to SQLParamData */ 130 | If (APD.IDA[n].SQL_DESC_DATA_POINTER is not a null pointer) 131 | return error: HY010 CLI-specific condition-function sequence error 132 | Set data-pointer value = Value (temporarily, for SQLPutData to see) 133 | return exception: HY(no subclass) CLI-specific condition-dynamic parameter 134 | value needed 135 | /* Since there are no [more] deferred parameter values, execution can 136 | proceed. Restart the SQLExecute or SQLExecDirect process which was 137 | interrupted when deferred parameters were encountered. */ 138 | 139 | **Notes:** 140 | 141 | * ``SQLParamData`` is needed if ``SQLExecute`` or ``SQLExecDirect`` returns 142 | ``SQL_NEED_DATA (+99)``. In its turn, ``SQLParamData`` causes a further 143 | generation of ``SQL_NEED_DATA`` (if there are more parameters to process), or 144 | else it finishes off the execution that began with ``SQLExecute`` or 145 | ``SQLExecDirect``. 146 | 147 | * If ``SQL_NEED_DATA`` has been returned, the deferred parameter must be dealt 148 | with. You will get an error if you attempt to call any of these functions -- 149 | ``SQLCopyDesc``, ``SQLFreeHandle``, ``SQLEndTran``, ``SQLDisconnect``, 150 | ``SQLGetDescField``, ``SQLGetDescRec``, ``SQLSetDescField``, 151 | ``SQLSetDescRec`` -- using the same ``hstmt``, or using a ``hdesc`` 152 | associated with the deferred parameter. A ``stmt`` with a deferred parameter 153 | is considered to be "active". An active ``stmt`` may be cancelled (with the 154 | ``SQLCancel`` function), but the only recommended action is to call 155 | ``SQLParamData``. 156 | 157 | * ``SQL_NEED_DATA`` is a positive value ``(+99)``. Therefore, if you use 158 | deferred parameters, you must not use the blithe code we've used in our 159 | examples so far: 160 | 161 | :: 162 | 163 | if (sqlreturn < 0) /* error */ 164 | if (sqlreturn >= 0) /* all's well, must be warning or success */ 165 | 166 | As we said earlier, some of your operating assumptions must change if this 167 | option is used. 168 | 169 | * Do not confuse ``SQLParamData`` with ``SQLGetParamData``. 170 | 171 | **Example:** See next section, on ``SQLPutData``. 172 | 173 | **ODBC:** ``SQLParamData`` has been around since ODBC 1.0. 174 | 175 | SQLPutData 176 | ========== 177 | 178 | **Function Prototype:** 179 | 180 | :: 181 | 182 | SQLRETURN SQLPutData ( 183 | SQLHSTMT hstmt, /* 32-bit input */ 184 | SQLPOINTER Data, /* pointer to ANY* input */ 185 | SQLINTEGER StrLen_Or_Ind /* pointer to indicator|octet-length */ 186 | ); 187 | 188 | **Algorithm:** 189 | 190 | :: 191 | 192 | If (there is no deferred parameter associated with stmt) 193 | return error: HY010 CLI-specific condition-function sequence error 194 | If (there is no SQL_DESC_DATA_POINTER value) 195 | /* the data-pointer value should have been supplied by SQLBindParameter */ 196 | return error: HY010 CLI-specific condition-function sequence error 197 | /* At this point, we have enough data (via the current APD fields plus 198 | the Data and StrLen_Or_Ind parameters) to complete the input parameter 199 | description. For details of what input-parameter description process 200 | looks like, see SQLBindParameter. */ 201 | 202 | **Notes:** 203 | 204 | * ``SQLPutData`` is used only in association with ``SQLParamData``. 205 | 206 | * ``SQLPutData`` can be used repeatedly if (for a long character or binary 207 | string) the data must be supplied in pieces. 208 | 209 | * Nullness trumps deferrability. If there's an indicator and it's ``-1 210 | (SQL_NULL_DATA)``, then the parameter passed is ``NULL`` -- there is no 211 | deferring. 212 | 213 | **Example:** In the following example, we will pass ``CHAR(4)`` parameters in 214 | four separate pieces, one character at a time. This is absurdly small -- 215 | usually pieces are at least 2 kilobytes -- but it illustrates the method 216 | nicely. Try to imagine that the data is input from some large file, or 217 | pipeline. The algorithm works like this: 218 | 219 | * Application initializes in the usual way. 220 | 221 | * Application prepares an ``INSERT`` statement. 222 | 223 | * Applications calls ``SQLBindParameter`` for two ``SQL_DATA_AT_EXEC`` 224 | parameters. The application identifies the parameters as #1 and #2 -- later, 225 | those values will be retrieved by ``SQLParamData``. Thus the values identify 226 | which parameter is being processed. 227 | 228 | * Application calls ``SQLExecute`` for the prepared ``INSERT`` statement. DBMS 229 | returns ``SQL_NEED_DATA`` because ``SQL_DATA_AT_EXEC`` parameters exist. 230 | 231 | * Application calls ``SQLParamData``. DBMS returns ``SQL_NEED_DATA`` because 232 | ``SQL_DATA_AT_EXEC`` parameters exist. DBMS also fills in the parameter 233 | number -- #1 -- from ``SQLBindParameter`` pass. Loop: 234 | 235 | * Application calls ``SQLPutData`` for the next piece. 236 | 237 | * Loop ends when the application has no more pieces. 238 | 239 | * Application calls ``SQLParamdata`` again. DBMS returns ``SQL_SUCCESS`` 240 | because there are no more parameters to process. 241 | 242 | * Application cleans up in the usual way. 243 | 244 | :: 245 | 246 | #include 247 | #include 248 | #include "sqlcli.h" 249 | 250 | #define MAX_DATA_LENGTH 1 251 | 252 | void main () 253 | { 254 | SQLHENV henv; 255 | SQLHDBC hdbc; 256 | SQLHSTMT hstmt; 257 | SQLRETURN rc; 258 | SQLCHAR OutData[1]; 259 | SQLCHAR InData[]="abcd"; 260 | SQLSMALLINT Param1 = 1, Param2 = 2; 261 | SQLINTEGER Param1Length, Param2Length; 262 | SQLPOINTER pToken; 263 | int offset; 264 | 265 | SQLAllocHandle(SQL_HANDLE_ENV,SQL_NULL_HANDLE,&henv); 266 | SQLAllocHandle(SQL_HANDLE_DBC,henv,&hdbc); 267 | rc=SQLConnect(hdbc,"OCELOT",SQL_NTS,"OCELOT",SQL_NTS,"",SQL_NTS); 268 | SQLAllocHandle(SQL_HANDLE_STMT,hdbc,&hstmt); 269 | 270 | rc=SQLExecDirect( 271 | hstmt,"CREATE TABLE Tests(big_col_1 CHAR(4),big_col_2 CHAR(4))",SQL_NTS); 272 | 273 | rc=SQLPrepare( 274 | hstmt,"INSERT INTO Tests(big_col_1,big_col_2) VALUES(?,?)",SQL_NTS); 275 | 276 | /* There are two Columns. There are two ?s. There will be two parameters. 277 | Bind them with SQLBindParameter. Don't pass a buffer address (which is 278 | what you would usually do). Instead, pass 1 and 2 (Param1 contains 1 279 | and Param2 contains 2.) */ 280 | 281 | SQLBindParameter( 282 | hstmt,1,SQL_PARAM_MODE_IN,SQL_CHAR,SQL_CHAR,4,0,&Param1, 283 | MAX_DATA_LENGTH,&Param1Length); 284 | SQLBindParameter( 285 | hstmt,2,SQL_PARAM_MODE_IN,SQL_CHAR,SQL_CHAR,4,0,&Param2, 286 | MAX_DATA_LENGTH,&Param2Length); 287 | 288 | /* Set Param1Length and Param2Length = SQL_DATA_AT_EXEC; the DBMS will see 289 | this because we passed addresses of Param1Length and Param2Length. */ 290 | 291 | Param1Length = Param2Length = SQL_DATA_AT_EXEC; 292 | 293 | rc=SQLExecute(hstmt); 294 | 295 | /* For data-at-execution parameters, call SQLParamData to get the */ 296 | /* parameter number set by SQLBindParameter. Call InitUserData. */ 297 | /* Call GetUserData and SQLPutData repeatedly to get and put all */ 298 | /* data for the parameter. Call SQLParamData to finish processing */ 299 | /* this parameter and start processing the next parameter. */ 300 | 301 | while (rc == SQL_NEED_DATA) { 302 | rc = SQLParamData(hstmt,&pToken); 303 | if (rc == SQL_NEED_DATA) { 304 | for (offset=0;offset<=3;++offset) { /* "Initialize" */ 305 | OutData[0] = InData[offset]; /* "Get" */ 306 | SQLPutData(hstmt,OutData,1); } } } /* "Put" */ 307 | 308 | SQLEndTran(SQL_HANDLE_DBC,hdbc,SQL_COMMIT); /* commit */ 309 | 310 | SQLFreeHandle(SQL_HANDLE_STMT,hstmt); /* cleanup + exit */ 311 | SQLDisconnect(hdbc); 312 | SQLFreeHandle(SQL_HANDLE_DBC,hdbc); 313 | SQLFreeHandle(SQL_HANDLE_ENV,henv); } 314 | 315 | **ODBC:** ``SQLPutData`` has been around since ODBC 1.0. 316 | 317 | SQLCancel 318 | ========= 319 | 320 | **Function Prototype:** 321 | 322 | :: 323 | 324 | SQLRETURN SQLCancel( 325 | SQLHSTMT hstmt /* 32-bit input */ 326 | ); 327 | 328 | **Job:** (Try to) stop a currently-executing function. There are two things 329 | that "currently-executing" might mean: 330 | 331 | * Scenario #1: The ``hstmt`` is associated with a deferred parameter. 332 | 333 | * Scenario #2: A routine associated with the ``stmt`` might be running 334 | "concurrently". For example, in an MS-Windows environment, you might call a 335 | CLI function in one thread, but now you're in another thread, and the 336 | function is still running. You know what the ``stmt`` handle is and you want 337 | to stop the function. 338 | 339 | **Algorithm:** 340 | 341 | For Scenario #1: 342 | 343 | :: 344 | 345 | Clear the diagnostics area. 346 | Disassociate the statement source and parameter number from the stmt. 347 | 348 | It is now possible to call ``SQLEndTran``, ``SQLDisconnect``, 349 | ``SQLFreeHandle``, etc. -- otherwise, you would have to fill in the 350 | deferred-parameter values. See the description of deferred parameters. 351 | 352 | For Scenario #2 353 | 354 | :: 355 | 356 | The server receives the request to cancel. 357 | The server tries to cancel. 358 | If (cancel fails) 359 | /* Reasons for failure might be: communication problem, or the 360 | function is doing a "commit" (which can't be interrupted). */ 361 | return error: HY018: CLI-Specific condition-Server declined the cancellation 362 | request 363 | If (cancel succeeds) 364 | The server returns: okay. 365 | 366 | The cancelled routine can leave diagnostics behind, if it was running 367 | asynchronously. (However, in ODBC, a routine which was cancelled from another 368 | thread will leave no diagnostics behind.) 369 | 370 | **Notes:** 371 | 372 | * A "successful completion" of this function doesn't mean much; it only means 373 | that the server has seen and accepted the request to cancel. More significant 374 | is the return that the cancelled function returns: ``HY008 CLI-specific 375 | condition-operation cancelled.`` 376 | 377 | * We believe that ``SQLCancel`` is used most frequently for the situation 378 | described as "Scenario #1". For the situation described as "Scenario #2", 379 | there is heavy dependence on operating-system features so it is not possible 380 | to specify exactly how ``SQLCancel`` works in standard SQL. 381 | 382 | * The cancelled routine might have already done some diagnostics and the 383 | diagnostics area is not cleared. Other than that, a cancelled routine leaves 384 | no effect. 385 | 386 | **Example:** This example shows the use of ``SQLCancel`` against an active 387 | process with deferred parameters. 388 | 389 | :: 390 | 391 | #include "sqlcli.h" 392 | SQLHSTMT hstmt; 393 | ... 394 | if (SQLExecute(hstmt) == SQL_NEED_DATA) { 395 | SQLCancel(hstmt); } 396 | 397 | This example shows the use of ``SQLCancel`` against an asynchronous process on 398 | another thread. It works like this: suppose you are shutting down, and there is 399 | some asynch/other-thread function that you've given up on. To make sure you are 400 | cancelling, you have to check two things: "Did ``SQLCancel`` work?" (that tells 401 | you that the server accepts the request to cancel), and "Did the cancelled 402 | function fail? (that tells you that the server succeeded in cancelling). 403 | 404 | :: 405 | 406 | /* Start asynch/other-thread/waiting function */ 407 | ... 408 | Call again, using the same hstmt. 409 | If (SQL_STILL_EXECUTING) { 410 | Call SQLCancel. 411 | If ("00000" i.e. "successful completion") { 412 | /* !! Do not assume the routine is cancelled !! */ 413 | Call again. 414 | If (SQL_STILL_EXECUTING) { 415 | /* Cancellation request has not yet succeeded. Wait. */ 416 | /* loop here */ 417 | If (SQL_ERROR and "HY008" i.e. "operation cancelled") { 418 | /* The cancellation is complete. The statement is over. */ 419 | If (anything else) { 420 | /* Probably the function finished normally, i.e. the */ 421 | /* SQLCancel arrived too late. The statement is over. */ 422 | 423 | **ODBC:** The ``SQLCancel`` function has been around since ODBC 1.0. In ODBC 424 | 2.x, ``SQLCancel(StatementHandle)`` was precisely the same as 425 | ``SQLFreeStmt(StatementHandle,SQL_CLOSE)`` if there was no asynch running. That 426 | is no longer so! If you want to close a Cursor, with ODBC 3.x or with the 427 | standard CLI, you must use ``SQLCloseCursor (hstmt)``. 428 | 429 | And that's it for the CLI deferred parameter functions. In the next chapter, 430 | we'll take a look at the locator functions. 431 | -------------------------------------------------------------------------------- /docs/chapters/50.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | ======================================== 4 | Chapter 50 -- SQL/CLI: Locator Functions 5 | ======================================== 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | In this chapter, we'll describe the CLI locator functions: ``SQLGetLength``, 10 | ``SQLGetPosition`` and ``SQLGetSubstring``. These functions are used with 11 | locators of ``BLOB``\s and ``CLOB``\s. They are new in SQL3; as far as we know, 12 | no DBMS supports them. Our description is therefore fairly brief. 13 | 14 | .. rubric:: Table of Contents 15 | 16 | .. contents:: 17 | :local: 18 | 19 | What is a Locator? 20 | ================== 21 | 22 | When you assign the value of a ``BLOB``, ``CLOB``, ``NCLOB``, ``UDT`` or 23 | ``ARRAY`` to an embedded host language variable or a host language parameter, 24 | your DBMS generates and assigns a locator to the target, to uniquely identify a 25 | value of the corresponding type. The locator is a 4-octet, non-zero integer 26 | (that is, locators are 32-bit ``INT``\s), and exists only until the current 27 | transaction ends (unless it is held). 28 | 29 | Locators have certain properties. 30 | 31 | * A locator may be either valid or invalid. 32 | 33 | * A locator may be a holdable locator. 34 | 35 | When a locator is initially created, it is marked valid and (if applicable) not 36 | holdable. You have to execute a ``HOLD LOCATOR`` statement before the end of 37 | the transaction in which a locator is created if you want that locator to be 38 | holdable. A non-holdable locator remains valid until the end of the transaction 39 | in which it was generated, unless it is explicitly made invalid by a ``FREE 40 | LOCATOR`` statement or a ``ROLLBACK WITH SAVEPOINT`` statement. A holdable 41 | locator may remain valid beyond the end of the transaction in which it was 42 | generated; it becomes invalid when you execute a ``FREE LOCATOR`` statement, a 43 | ``ROLLBACK WITH SAVEPOINT`` statement with a ``SAVEPOINT`` clause or if the 44 | transaction in which it is generated (or any subsequent transaction) is rolled 45 | back. All locators are made invalid when the current SQL-session ends. 46 | 47 | The following items can have the "data type" ``LOCATOR``: a host variable, a 48 | host parameter, an SQL parameter in an external routine and a value returned by 49 | external function. To specify an item as a locator, add the s ``AS 50 | LOCATOR`` to the specification. According to the SQL Standard, this then allows 51 | the passing of very large data values "without transferring the entire value to 52 | and from the SQL-agent". That is -- if you're dealing with an image, why do 53 | this: 54 | 55 | * DBMS reads into DBMS memory 56 | 57 | * DBMS transfers to host language memory 58 | 59 | * host language writes copy 60 | 61 | The procedure could do it without transfers, with a locator. 62 | 63 | Standard SQL provides two statements for use with locators. Brief descriptions 64 | of each follow. 65 | 66 | *FREE LOCATOR Statement* 67 | ------------------------ 68 | 69 | The ``FREE LOCATOR`` statement removes the association between a locator 70 | variable or parameter and the value represented by that locator. The required 71 | syntax for the ``FREE LOCATOR`` statement is: 72 | 73 | :: 74 | 75 | FREE LOCATOR :host_parameter_name> [ {,:host_parameter_name}... ] 76 | 77 | The ``FREE LOCATOR`` statement frees one or more locators -- that is, it marks 78 | the locators identified by the s as invalid. 79 | 80 | If you want to restrict your code to Core SQL, don't use the ``FREE LOCATOR`` 81 | statement. 82 | 83 | *HOLD LOCATOR Statement* 84 | ------------------------ 85 | 86 | The ``HOLD LOCATOR`` statement marks a locator variable or parameter as a 87 | holdable locator. The required syntax for the ``HOLD LOCATOR`` statement is: 88 | 89 | :: 90 | 91 | HOLD LOCATOR :host_parameter_name> [ {,:host_parameter_name}... ] 92 | 93 | The ``HOLD LOCATOR`` statement lets you change the status of one or more 94 | locators from non-holdable to holdable. The difference between the two status 95 | has to do with when a locator becomes invalid: a non-holdable locator remains 96 | valid until the end of the transaction in which it was generated (unless it is 97 | explicitly made invalid), while a holdable locator may remain valid beyond the 98 | end of the transaction in which it was generated. All locators are made invalid 99 | when the current SQL-session ends. 100 | 101 | If you want to restrict your code to Core SQL, don't use the ``HOLD LOCATOR`` 102 | statement. 103 | 104 | The rest of this chapter describes the three CLI locator functions. 105 | 106 | SQLGetLength 107 | ============ 108 | 109 | **Function Prototype:** 110 | 111 | :: 112 | 113 | SQLRETURN SQLGetLength( 114 | SQLHSTMT hstmt, /* 32-bit input */ 115 | SQLSMALLINT LocatorType, /* 16-bit input */ 116 | SQLINTEGER Locator, /* 32-bit input */ 117 | SQLINTEGER *StringLength, /* pointer to 32-bit output */ 118 | SQLINTEGER *IndicatorValue /* pointer to 32-bit output */ 119 | ); 120 | 121 | **Job:** Return the length of the value represented by a ``BLOB``, ``CLOB``, 122 | ``NCLOB``, ``UDT`` or ``ARRAY`` locator. 123 | 124 | **Algorithm:** 125 | 126 | :: 127 | 128 | If (there is a prepared statement associated with hstmt) 129 | return error: HY010 CLI-specific condition-function sequence error 130 | If (LocatorType is not SQL_BLOB_LOCATOR or SQL_CLOB_LOCATOR or SQL_UDT_LOCATOR 131 | or SQL_ARRAY_LOCATOR) 132 | return error: CLI-specific condition-invalid argument value 133 | If (Locator does not refer to a Locator) 134 | return error: 0F001 locator exception-invalid specification 135 | If (LocatorType==SQL_BLOB_LOCATOR and Locator doesn't refer to a BLOB) 136 | Or (LocatorType==SQL_CLOB_LOCATOR and Locator doesn't refer to a CLOB) 137 | Or (LocatorType==SQL_UDT_LOCATOR and Locator doesn't refer to a UDT) 138 | Or (LocatorType==SQL_ARRAY_LOCATOR and Locator doesn't refer to an ARRAY) 139 | return error: dynamic SQL error-restricted data type attribute violation 140 | 141 | Case: 142 | If (the Large Object's value is NULL) 143 | If (IndicatorValue is a null pointer) 144 | return error: data exception-null value, no indicator parameter 145 | Set *IndicatorValue = SQL_NULL_DATA i.e. -1 146 | Else 147 | If (IndicatorValue is not a null pointer) 148 | Set *IndicatorValue = 0 149 | If (LocatorType == SQL_BLOB_LOCATOR) 150 | Set *StringLength = length of BLOB, in octets 151 | If (LocatorType==SQL_CLOB_LOCATOR) 152 | Set *StringLength = length of CLOB, in characters 153 | If (LocatorType==SQL_UDT_LOCATOR) 154 | Set *StringLength = length of UDT, in octets 155 | If (LocatorType==SQL_ARRAY_LOCATOR) 156 | Set *StringLength = length of ARRAY, in octets 157 | 158 | **Notes:** 159 | 160 | * The octet length and the character length will be the same value only if 161 | 8-bit Character sets are in use. 162 | 163 | **Example:** 164 | 165 | :: 166 | 167 | #include "sqlcli.h" 168 | ... 169 | SQLINTEGER lob; /* large object locator */ 170 | SQLINTEGER len; /* length */ 171 | SQLINTEGER ind; /* indicator */ 172 | ... 173 | SQLGetLength(hstmt,SQL_CLOB_LOCATOR,lob,&len,&ind); 174 | 175 | **ODBC:** Since this is an SQL3 function, it is not in ODBC 3.0. 176 | 177 | SQLGetPosition 178 | ============== 179 | 180 | **Function Prototype:** 181 | 182 | :: 183 | 184 | SQLRETURN SQLGetPosition( 185 | SQLHSTMT StatementHandle, /* 32-bit input */ 186 | SQLSMALLINT LocatorType, /* 16-bit input */ 187 | SQLINTEGER SourceLocator, /* 32-bit input */ 188 | SQLINTEGER SearchLocator, /* 32-bit input */ 189 | SQLCHAR *SearchLiteral, /* pointer to *ANY */ 190 | SQLINTEGER SearchLiteralLength, /* 32-bit input */ 191 | SQLINTEGER FromPosition, /* 32-bit input */ 192 | SQLINTEGER *LocatedAt, /* pointer to 32-bit integer */ 193 | SQLINTEGER *IndicatorValue /* pointer to 32-bit integer */ 194 | ); 195 | 196 | **Job:** Return the position of a passed string within a ``BLOB``, ``CLOB``, 197 | ``NCLOB``, ``UDT`` or ``ARRAY``. 198 | 199 | **Algorithm:** 200 | 201 | :: 202 | 203 | if (stmt is associated with a prepared or executed statement) 204 | return error: HY010 CLI-specific condition-function sequence error 205 | If (LocatorType is not SQL_BLOB_LOCATOR or SQL_CLOB_LOCATOR or 206 | SQL_UDT_LOCATOR or SQL_ARRAY_LOCATOR) 207 | return error: CLI-specific condition-invalid argument value 208 | If (Locator does not refer to a Locator) 209 | return error: 0F001 locator exception-invalid specification 210 | If (LocatorType==SQL_BLOB_LOCATOR and Locator doesn't refer to a BLOB) 211 | Or (LocatorType==SQL_CLOB_LOCATOR and Locator doesn't refer to a CLOB) 212 | Or (LocatorType==SQL_UDT_LOCATOR and Locator doesn't refer to a UDT) 213 | Or (LocatorType==SQL_ARRAY_LOCATOR and Locator doesn't refer to an ARRAY) 214 | return error: dynamic SQL error-restricted data type attribute violation 215 | If (the Large Object's value is NULL) 216 | If (IndicatorValue is a null pointer) 217 | return error: data exception-null value, no indicator parameter 218 | Set *IndicatorValue = SQL_NULL_DATA i.e. -1 219 | Else 220 | If (IndicatorValue is not a null pointer) 221 | Set *IndicatorValue = 0; 222 | Set *LocatedAt = position of string within the BLOB or CLOB or NCLOB or UDT 223 | or ARRAY. 224 | 225 | **ODBC:** Since this is an SQL3 function, it is not in ODBC 3.0. 226 | 227 | SQLGetSubstring 228 | =============== 229 | 230 | **Function Prototype:** 231 | 232 | :: 233 | 234 | SQLRETURN SQLGetSubString( 235 | SQLHSTMT StatementHandle, /* 32-bit input */ 236 | SQLSMALLINT LocatorType, /* 16-bit input */ 237 | SQLINTEGER SourceLocator, /* 32-bit input */ 238 | SQLINTEGER FromPosition, /* 32-bit input */ 239 | SQLINTEGER ForLength, /* 32-bit input */ 240 | SQLSMALLINT TargetType, /* 16-bit input */ 241 | SQLPOINTER TargetValue /* pointer to output */ 242 | SQLINTEGER BufferLength, /* 32-bit input */ 243 | SQLINTEGER *StringLength, /* pointer to integer output */ 244 | SQLINTEGER *IndicatorValue); /* pointer to integer output */ 245 | 246 | **Job:** Extract a portion of a ``BLOB``, ``CLOB``, ``NCLOB``, ``UDT`` or 247 | ``ARRAY``, returning the result as a string or, alternatively, as a new 248 | ``BLOB``, ``CLOB``, ``NCLOB``, ``UDT`` or ``ARRAY``. 249 | 250 | **Algorithm:** 251 | 252 | :: 253 | 254 | if (stmt is associated with a prepared or executed statement) 255 | return error: HY010 CLI-specific condition-function sequence error 256 | If (LocatorType is not SQL_BLOB_LOCATOR or SQL_CLOB_LOCATOR or 257 | SQL_UDT_LOCATOR or SQL_ARRAY_LOCATOR) 258 | return error: CLI-specific condition-invalid argument value 259 | If (Locator does not refer to a Locator) 260 | return error: 0F001 locator exception-invalid specification 261 | If (LocatorType==SQL_BLOB_LOCATOR and Locator doesn't refer to a BLOB) 262 | Or (LocatorType==SQL_CLOB_LOCATOR and Locator doesn't refer to a CLOB) 263 | Or (LocatorType==SQL_UDT_LOCATOR and Locator doesn't refer to a UDT) 264 | Or (LocatorType==SQL_ARRAY_LOCATOR and Locator doesn't refer to an ARRAY) 265 | return error: dynamic SQL error-restricted data type attribute violation 266 | If (the Large Object's value is NULL) 267 | If (IndicatorValue is a null pointer) 268 | return error: data exception-null value, no indicator parameter 269 | Set *IndicatorValue = SQL_NULL_DATA i.e. -1 270 | Else 271 | If (IndicatorValue is not a null pointer) 272 | Set *IndicatorValue = 0; 273 | Transfer the substring from the BLOB, CLOB, NCLOB, UDT or ARRAY to 274 | TargetValue, using a procedure analogous to Character Retrieval Procedure. 275 | 276 | **ODBC:** Since this is an SQL3 function, it is not in ODBC 3.0. 277 | 278 | And that's it for the CLI locator functions. In the next (and final) chapter 279 | on the CLI, we'll take a look at the Catalog functions. 280 | -------------------------------------------------------------------------------- /docs/chapters/52.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | ================================== 4 | Chapter 52 -- Module Binding Style 5 | ================================== 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | SQL DBMSs communicate with SQL applications through a common programming 10 | language interface that is invoked through one of the SQL Standard-defined 11 | binding styles, or interface options. There are three main approaches to 12 | writing complete programs with SQL: 13 | 14 | 1. With embedded SQL, you can put SQL statements directly into host programs. 15 | We described this binding style earlier. 16 | 17 | 2. With SQL/CLI, you can call a SQL DBMS's library from a host program. This 18 | binding style was the subject of the last several chapters. 19 | 20 | 3. With the Module language, you can dispense with host programs and write 21 | entire Modules in SQL. You'll still have to call these Modules from one of 22 | the standard host languages though. The Module language binding style is the 23 | subject of this chapter. 24 | 25 | Because we believe that SQL/CLI will quickly become the SQL interface of 26 | choice, this chapter omits large amounts of detail, in favour of providing the 27 | necessary detail in our chapters on SQL/CLI. 28 | 29 | .. NOTE:: 30 | 31 | The SQL Standard actually describes three kinds of SQL Module, each of which 32 | has certain characteristics and contains various kinds of Module Objects 33 | (principally, routines). An SQL-client Module contains only 34 | externally-invoked procedures, an SQL-session Module contains only SQL 35 | statements prepared in that SQL-session and an SQL-server Module -- the 36 | SQL/PSM type -- is a Schema Object that contains only SQL-invoked routines. 37 | 38 | .. rubric:: Table of Contents 39 | 40 | .. contents:: 41 | :local: 42 | 43 | SQL-client Modules 44 | ================== 45 | 46 | SQL-client Modules are programming modules that contain externally-invoked 47 | procedures -- that is, SQL procedures that are invoked by a host language. 48 | Generally speaking, this methodology is really the basic SQL binding style: all 49 | of the binding styles -- direct SQL, embedded SQL, CLI or SQL-client Modules -- 50 | at least conceptually, involve a program module. Before SQL/PSM came on the 51 | scene, SQL "module language" was the only way to identify SQL Modules. But now, 52 | with the advent of SQL/PSM and (far better) of SQL/CLI, we believe this method 53 | of utilizing SQL will rapidly become obsolete and so we give only a brief 54 | description here. 55 | 56 | An SQL-client Module is an Object -- a programming module -- that you define 57 | with SQL's module language: a subset of SQL that allows you to write database 58 | routines in pure SQL. It contains SQL statements that will operate on your 59 | SQL-data, and you link it (in some implementation-defined way) with modules of 60 | code in one or more of the Standard's host languages. The database routines are 61 | called *externally-invoked procedures* because they are invoked by the host 62 | language program to which you link the Module they belong to. 63 | 64 | MODULE Statement 65 | ================ 66 | 67 | The ``MODULE`` statement defines an SQL-client Module. The required syntax for 68 | the ``MODULE`` statement is: 69 | 70 | :: 71 | 72 | ::= 73 | MODULE [ ] 74 | NAMES ARE 75 | LANGUAGE {ADA | C |COBOL | FORTRAN | MUMPS | PASCAL | PLI} 76 | 77 | [ PATH {,}... ] 78 | [ TRANSFORM GROUP { | { FOR TYPE } , ...} ] 79 | [ DECLARE TABLE statement(s) ] 80 | ... 81 | 82 | ::= 83 | SCHEMA | 84 | AUTHORIZATION | 85 | SCHEMA AUTHORIZATION 86 | 87 | ::= 88 | DECLARE CURSOR statement(s) | 89 | PROCEDURE statement(s) 90 | 91 | An SQL-client Module doesn't have to be named (unless the Module's ``LANGUAGE`` 92 | clause specifies ADA, in which case you must give the Module a valid Ada 93 | library unit name); your SQL-environment can contain multiple unnamed SQL- 94 | client Modules. If you do name an SQL-client Module, though, you must give it a 95 | unique name (for all SQL-client Modules) in your SQL-environment. A is a or a . 97 | 98 | The optional ``NAMES ARE`` clause provides the name of the Module's default 99 | Character set: the Character set that your DBMS will use for any character 100 | strings in the Module that don't include an explicit Character set 101 | specification. If you omit this clause, the Module's default Character set is 102 | chosen by your DBMS, and must contain at least every . 103 | 104 | The ``LANGUAGE`` clause provides the name of the host language that will invoke 105 | the routines this Module contains. 106 | 107 | The Module authorization clause provides either the Module's default Schema, 108 | the Module's or both (at least one must be included). 109 | 110 | * ``SCHEMA`` provides an explicit -- this will be 111 | the default qualifier for any Objects referred to in the Module 112 | without explicit qualifiers. If you omit this clause, the default defaults to the value in the ``AUTHORIZATION`` clause. 114 | 115 | * ``AUTHORIZATION`` provides an explicit to 116 | be the owner of the Module -- this will be the whose 117 | Privileges will be checked when the Module's SQL statements are executed. If 118 | you omit this clause, your DBMS will treat the SQL-session 119 | as the Module's owner at runtime. 120 | 121 | The optional ``PATH`` clause provides a list of s that will be 122 | used as the Module's default path -- that is, the qualifying s 123 | that will be used for any unqualified s in this Module. You can 124 | name zero or more Schemas in this clause (your DBMS will pick the one that 125 | matches the unqualified routine best at runtime); each Schema in the list must 126 | belong to the same Catalog that this Module's default Schema belongs to. If you 127 | omit this clause, it will default to a list of Schemas, containing at least 128 | this Module's default Schema, chosen by your DBMS. 129 | 130 | The optional ``TRANSFORM GROUP`` clause provides a for each UDT 131 | parameter that has no locator; see our chapter on UDTs. 132 | 133 | You can declare zero or more temporary Tables for the Module. Each will be 134 | visible only to the Module you declare them in. 135 | 136 | The clause is the meat of the Module -- it contains the SQL 137 | statements that do the work you need done on your SQL-data. You can declare 138 | zero or more Cursors here (see our chapter on embedded SQL), as well as one or 139 | more externally-invoked procedures (with the ``PROCEDURE`` statement, see 140 | below). 141 | 142 | If you want to restrict your code to Core SQL, don't use the ``NAMES ARE`` 143 | clause, the ``PATH`` clause, the ``TRANSFORM GROUP`` clause or any ``DECLARE 144 | TABLE`` statements in a ``MODULE`` statement. 145 | 146 | PROCEDURE Statement 147 | =================== 148 | 149 | The ``PROCEDURE`` statement defines an externally-invoked procedure. The 150 | required syntax for the ``PROCEDURE`` statement is: 151 | 152 | :: 153 | 154 | PROCEDURE 155 | {( [ {,}... ] ) | 156 | ...}; 157 | SQL procedure statement; 158 | 159 | ::= 160 | : [ AS LOCATOR ] | 161 | SQLSTATE 162 | 163 | An externally-invoked procedure is an SQL procedure that is called from a host 164 | language program. It belongs to an SQL-client Module, and must have a 165 | that is unique (for all procedures) within that Module. A 166 | is a or a and 167 | should conform to the host language you'll be calling it from. 168 | 169 | Each procedure has to contain a list of one or more parameter declarations, 170 | terminated with a semicolon -- ``SQLSTATE`` is always mandatory. Your list 171 | should be enclosed in parentheses, with each parameter declaration separated 172 | from the next by a comma (though our syntax diagram shows that both the 173 | parentheses and the commas are currently optional, this is a deprecated feature 174 | in the Standard, so avoid it). Other than ``SQLSTATE``, each parameter has a 175 | name (preceded by a colon), a and -- if it is a ``BLOB``, ``CLOB``, 176 | ``NCLOB``, ``UDT`` or ``ARRAY`` -- an optional ``AS LOCATOR`` indicator. A call 177 | of an externally-invoked procedure has to supply the same number of arguments 178 | as the parameter declarations in the procedure. 179 | 180 | Each procedure has to contain exactly one SQL procedure statement, terminated 181 | with a semicolon. This is the SQL statement that gets executed when the 182 | procedure is called. An SQL procedure statement is any executable SQL statement 183 | -- this includes all the SQL-Schema statements, the SQL-data statements, the 184 | SQL-control statements, the SQL-transaction statements, the SQL-Connection 185 | statements, the SQL-session statements and the SQL diagnostics statement. 186 | 187 | If you calling the procedure from: 188 | 189 | **Ada** -- then use only these s in your s: ``CHARACTER``, ``BIT``, ``SMALLINT``, ``INTEGER``, ``REAL``, 191 | ``DOUBLE PRECISION``, declare ``SQLSTATE``\'s base type as 192 | ``SQL_STANDARD.SQLSTATE_TYPE``, and identify the procedure by its , as if it was declared within an Ada library unit specification that has 194 | a name equal to the name of the SQL-client Module that contains the procedure. 195 | 196 | **C** -- then use only these s in your s: ``CHARACTER``, ``CHARACTER VARYING``, ``BIT``, ``INTEGER``, 198 | ``SMALLINT``, ``REAL``, ``DOUBLE PRECISION``, and declare ``SQLSTATE`` as a C 199 | ``char`` with length 6. 200 | 201 | **COBOL** -- then use only these s in your s: ``CHARACTER``, ``BIT``, ``NUMERIC``, ``INTEGER``, ``SMALLINT``, 203 | and declare ``SQLSTATE`` as a COBOL ``PICTURE X(5)``. 204 | 205 | **Fortran** -- then use only these s in your s: ``CHARACTER``, ``BIT``, ``INTEGER``, ``REAL``, ``DOUBLE 207 | PRECISION``, and declare ``SQLSTATE`` as a Fortran ``CHARACTER`` with length 5. 208 | 209 | **MUMPS** -- then use only these s in your s: ``CHARACTER VARYING``, ``INTEGER``, ``DECIMAL``, ``REAL``, and 211 | declare ``SQLSTATE`` as a MUMPS character with maximum length greater than or 212 | equal to 5. 213 | 214 | **Pascal** -- then use only these s in your s: ``CHARACTER``, ``BIT``, ``INTEGER``, ``REAL``, and declare 216 | ``SQLSTATE`` as a Pascal ``PACKED ARRAY [1..5] OF CHAR``. 217 | 218 | **PL/I** -- then use only these s in your s: ``CHARACTER``, ``CHARACTER VARYING``, ``BIT``, ``BIT VARYING``, 220 | ``DECIMAL``, ``INTEGER``, ``SMALLINT``, ``FLOAT``, and declare ``SQLSTATE`` as 221 | a PL/I ``CHARACTER(5)``. 222 | 223 | For a list of the correspondences between SQL s and host data types, 224 | see "Host Variables" in our chapter on embedded SQL. 225 | 226 | Here's an example of an SQL-client Module: 227 | 228 | :: 229 | 230 | MODULE module_1 231 | NAMES ARE ASCII_FULL 232 | LANGUAGE C 233 | SCHEMA catalog_1.schema_1 AUTHORIZATION bob 234 | DECLARE LOCAL TEMPORARY TABLE Table_1 ( 235 | COLUMN_1 INTEGER, COLUMN_2 CHARACTER VARYING(25)) 236 | ON COMMIT DELETE ROWS; 237 | PROCEDURE proc_1 ( 238 | :var_1 INTEGER, :var_2 CHARACTER VARYING(25)); 239 | INSERT INTO Table_1 (column_1, column_2) 240 | VALUES (:var_1, :var_2); 241 | PROCEDURE proc_2 ( 242 | :var_1 INTEGER); 243 | UPDATE Table_2 SET 244 | column_3 = column_3*:var_1 WHERE column_3 IN 245 | (SELECT column_1 FROM Table_1; 246 | -------------------------------------------------------------------------------- /docs/chapters/index.rst: -------------------------------------------------------------------------------- 1 | .. _chapters: 2 | 3 | ======== 4 | Chapters 5 | ======== 6 | 7 | .. include:: ../_include/note.rst 8 | 9 | .. rubric:: Table of Contents 10 | 11 | .. toctree:: 12 | :maxdepth: 3 13 | :titlesonly: 14 | 15 | 01 16 | 02 17 | 03 18 | 04 19 | 05 20 | 06 21 | 07 22 | 08 23 | 09 24 | 10 25 | 11 26 | 12 27 | 13 28 | 14 29 | 15 30 | 16 31 | 17 32 | 18 33 | 19 34 | 20 35 | 21 36 | 22 37 | 23 38 | 24 39 | 25 40 | 26 41 | 27 42 | 28 43 | 29 44 | 30 45 | 31 46 | 32 47 | 33 48 | 34 49 | 35 50 | 36 51 | 37 52 | 38 53 | 39 54 | 40 55 | 41 56 | 42 57 | 43 58 | 44 59 | 45 60 | 46 61 | 47 62 | 48 63 | 49 64 | 50 65 | 51 66 | 52 67 | 53 68 | -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | from crate.theme.rtd.conf.sql_99 import * 2 | 3 | html_theme_options.update({ 4 | "canonical_url": "https://sql-99.readthedocs.io", 5 | }) 6 | 7 | # Disable version chooser. 8 | html_context.update({ 9 | "display_version": False, 10 | "current_version": None, 11 | "versions": [], 12 | }) 13 | -------------------------------------------------------------------------------- /docs/index.rst: -------------------------------------------------------------------------------- 1 | .. _index: 2 | 3 | ======================== 4 | SQL-99 Complete, Really 5 | ======================== 6 | 7 | .. include:: _include/note.rst 8 | 9 | .. rubric:: Table of Contents 10 | 11 | .. toctree:: 12 | :maxdepth: 3 13 | 14 | preface 15 | chapters/index 16 | appendices/index 17 | -------------------------------------------------------------------------------- /docs/preface.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: text 2 | 3 | ======= 4 | Preface 5 | ======= 6 | 7 | .. include:: _include/note.rst 8 | 9 | If you've ever used a relational database product, chances are that you're 10 | already familiar with SQL -- the internationally-accepted, standard programming 11 | language for databases which is supported by the vast majority of relational 12 | database management system (DBMS) products available today. You may also have 13 | noticed that, despite the large number of "reference" works that claim to 14 | describe standard SQL, not a single one provides a complete, accurate and 15 | example-filled description of the entire SQL Standard. This book was written to 16 | fill that void. 17 | 18 | .. rubric:: Table of Contents 19 | 20 | .. contents:: 21 | :local: 22 | 23 | Who Should Read this Book? 24 | ========================== 25 | 26 | This book will be valuable to anyone who works with a DBMS that supports SQL. 27 | While our emphasis is on programming with SQL, you do not need to be a 28 | programmer to learn SQL from our examples. We do assume you know something 29 | about Windows and something about C, but our main concern is that you are 30 | interested in using "ANSI Standard SQL" in your projects. This is both a 31 | beginner's and an advanced-user's book. Our hope is that a beginner will be 32 | able to avoid the traditional "for beginners" books which, sadly, contain so 33 | much drivel that it is impossible to advance from them without re-learning 34 | everything. 35 | 36 | Your Windows knowledge needn't be extensive, as we won't be getting into the 37 | details of the Windows Application Programming Interface (API). We'll touch 38 | only on things that occur in all versions of Windows, and occasionally 39 | analogize with Windows concepts and terms. 40 | 41 | As for C, we assume you can read simple C programs, even if your favourite 42 | programming language is something else. We want to show you examples of SQL as 43 | it's used in programming projects -- that is, in company with a "host language" 44 | -- and C seemed the convenient choice. All example programs shown provided are 45 | short. 46 | 47 | What's In It? 48 | ============= 49 | 50 | World's Longest SQL Poem (for obvious reasons) 51 | ---------------------------------------------- 52 | 53 | :: 54 | 55 | All the snake-oil peddlers say, there's a fast and easy way, 56 | To get your SQL program up and running, 57 | But they're silent re the traps, that cause subtly buggy apps, 58 | For to catch the unaware a chasm's yawning! 59 | 60 | Date-arithmetic exceptions, auto-rollbacked disconnections, 61 | Bit precisions, overflows, collate coercions, 62 | And how NULL affects your summing, for to keep your DB humming, 63 | You must know what happens in all vendors' versions! 64 | 65 | Should this field be DOUBLE PRECISION? 66 | Will logic rules soon see revision? 67 | By the ANSI:Databases sub-committee? 68 | When you DROP should you CASCADE? 69 | How are NATURAL joins made? 70 | Re UNIQUE-keys matching check the nitty-gritty! 71 | 72 | Yeah the true and standard facts, you'll avoid those later hacks 73 | That make Structured Query Language such a bore, 74 | You'll find tips and charts aplenty, in this one-thousand-and-twenty 75 | Four page volume (with an index), and yet more! 76 | 77 | -- Author anon (also for obvious reasons) 78 | 79 | This book describes the SQL syntax a DBMS must support to comply with the 80 | International Organization for Standardization (ISO) document ISO/IEC 81 | 9075:1999 Database Language SQL, also adopted as the American National 82 | Standards Institute (ANSI) document X3.135-1999 Database Language SQL -- 83 | familiarly known as SQL3, standard SQL or ANSI SQL. We will use the more 84 | familiar terms "SQL" or "SQL3" to describe Standard-conforming SQL in this book, 85 | rather than the formal term SQL-99. 86 | 87 | It's true that some features discussed in this book aren't in . That's no reason to ignore them, because sooner or later they 89 | will be there, due to pressure on serious vendors to adhere to the SQL 90 | Standard. 91 | 92 | Why Read It? 93 | ------------ 94 | 95 | You need to know SQL so you've been looking for an accurate reference work 96 | that describes the entire SQL Standard by way of examples. This is that book. 97 | 98 | How much of what you need to know is in this book? Well, it's impossible for a 99 | single book to contain everything you need. We guarantee that the coverage is 100 | complete for the SQL language itself, and is adequate for subjects that 101 | closely relate to SQL. Let's express "what you will know" as a percentage of 102 | "what you should know", with an assumption that you're an average person: 103 | 104 | :: 105 | 106 | ## SQL3 Standard "foundation" 90% 107 | ## Earlier ANSI and ISO Standards 100% 108 | ## SQL/CLI 100% 109 | ## Embedded SQL and host languages 40% 110 | ## Object orientation (UDTs) 20% 111 | ## Relational database theory 10% 112 | ## Design 10% 113 | ## Quirks of specific vendors' dialects 5% 114 | 115 | "Complete" does not mean that everything which could be said about SQL 116 | will be said here. SQL is big. More exactly, it means that we will 117 | never refer you to further published material saying "the details are in the 118 | official standard document" or "further discussion is outside the scope of 119 | this book". 120 | 121 | Further Information 122 | ------------------- 123 | 124 | When you look at our Table of Contents, you'll see that this book 125 | includes several Appendices, but only on the accompanying CD-ROM, 126 | to keep the book from becoming too unwieldy. Of the Appendix files, 127 | we especially recommend Appendix F, the Glossary. It provides 128 | definitions for all the SQL technical terms we use. 129 | -------------------------------------------------------------------------------- /docs/requirements.txt: -------------------------------------------------------------------------------- 1 | crate-docs-theme 2 | --------------------------------------------------------------------------------