diff --git a/advocacy_docs/supported-open-source/postgresql/installer/04_installation_troubleshooting.mdx b/advocacy_docs/supported-open-source/postgresql/installer/04_installation_troubleshooting.mdx index ce832b89b7e..1a9b8884360 100644 --- a/advocacy_docs/supported-open-source/postgresql/installer/04_installation_troubleshooting.mdx +++ b/advocacy_docs/supported-open-source/postgresql/installer/04_installation_troubleshooting.mdx @@ -9,6 +9,12 @@ legacyRedirects: - "/edb-docs/d/postgresql/installation-getting-started/installation-guide-installers/10/PostgreSQL_Installation_Guide.1.22.html" --- +## Multi-byte characters in user name + +If your system user name or machine name contains non-ASCII characters, the installation may fail. Make sure your user name or machine name don't include multi-byte characters. + +## Installation log files + If you encounter problems during installation, consult the installation log file `install-postgresql.log` created in: - `/tmp` on Mac OS X diff --git a/build-sources.json b/build-sources.json index ced92f766f2..2c422fc0328 100644 --- a/build-sources.json +++ b/build-sources.json @@ -9,6 +9,7 @@ "efm": true, "epas": true, "pgd": true, + "pge": true, "eprs": true, "hadoop_data_adapter": true, "jdbc_connector": true, @@ -26,5 +27,6 @@ "pgpool": true, "postgis": true, "repmgr": true, - "slony": true + "slony": true, + "tde": true } diff --git a/gatsby-config.js b/gatsby-config.js index b1af5c55ff1..7d4b3194e63 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -28,6 +28,7 @@ const sourceToPluginConfig = { efm: { name: "efm", path: "product_docs/docs/efm" }, epas: { name: "epas", path: "product_docs/docs/epas" }, pgd: { name: "pgd", path: "product_docs/docs/pgd" }, + pge: { name: "pge", path: "product_docs/docs/pge" }, eprs: { name: "eprs", path: "product_docs/docs/eprs" }, hadoop_data_adapter: { name: "hadoop_data_adapter", @@ -79,6 +80,7 @@ const sourceToPluginConfig = { postgis: { name: "postgis", path: "product_docs/docs/postgis" }, repmgr: { name: "repmgr", path: "product_docs/docs/repmgr" }, slony: { name: "slony", path: "product_docs/docs/slony" }, + tde: { name: "tde", path: "product_docs/docs/tde" }, }; const externalSourcePlugins = () => { diff --git a/install_template/config.yaml b/install_template/config.yaml index 075d9e0d8f3..de56d5a86c7 100644 --- a/install_template/config.yaml +++ b/install_template/config.yaml @@ -354,53 +354,82 @@ products: - name: SLES 15 arch: ppc64le supported versions: [11, 12, 13, 14] + - name: EDB Postgres Extended Server + platforms: + - name: CentOS 7 + arch: x86_64 + supported versions: [15] + - name: AlmaLinux 8 or Rocky Linux 8 + arch: x86_64 + supported versions: [15] + - name: RHEL 7 or OL 7 + arch: x86_64 + supported versions: [15] + - name: RHEL 8 or OL 8 + arch: x86_64 + supported versions: [15] + - name: Ubuntu 18.04 + arch: x86_64 + supported versions: [15] + - name: Debian 11 + arch: x86_64 + supported versions: [15] + - name: Debian 10 + arch: x86_64 + supported versions: [15] + - name: Ubuntu 22.04 + arch: x86_64 + supported versions: [15] + - name: Ubuntu 20.04 + arch: x86_64 + supported versions: [15] - name: EDB*Plus platforms: - name: CentOS 7 arch: x86_64 - supported versions: [40] + supported versions: [41] - name: AlmaLinux 8 or Rocky Linux 8 arch: x86_64 - supported versions: [40] + supported versions: [41] - name: RHEL 7 or OL 7 arch: x86_64 - supported versions: [40] + supported versions: [41] - name: RHEL 8 or OL 8 arch: x86_64 - supported versions: [40] + supported versions: [41] - name: RHEL 8 arch: ppc64le - supported versions: [40] + supported versions: [41] - name: Ubuntu 18.04 arch: x86_64 - supported versions: [40] + supported versions: [41] - name: Debian 10 arch: x86_64 - supported versions: [40] + supported versions: [41] - name: Debian 11 arch: x86_64 - supported versions: [40] + supported versions: [41] - name: Ubuntu 18.04 arch: x86_64 - supported versions: [40] + supported versions: [41] - name: Ubuntu 20.04 arch: x86_64 - supported versions: [40] + supported versions: [41] - name: Ubuntu 22.04 arch: x86_64 - supported versions: [40] + supported versions: [41] - name: SLES 12 arch: x86_64 - supported versions: [40] + supported versions: [41] - name: SLES 12 arch: ppc64le - supported versions: [40] + supported versions: [41] - name: SLES 15 arch: x86_64 - supported versions: [40] + supported versions: [41] - name: SLES 15 arch: ppc64le - supported versions: [40] + supported versions: [41] - name: Failover Manager platforms: - name: CentOS 7 diff --git a/install_template/deploy.mjs b/install_template/deploy.mjs index c64a0cd46d8..b00517661eb 100644 --- a/install_template/deploy.mjs +++ b/install_template/deploy.mjs @@ -151,30 +151,9 @@ const moveDoc = async (product, platform, version) => { // prettier-ignore const destFilename = integralDeploymentPath || match(context, - when({product: {name: "EDB Postgres Advanced Server", version: 14}, platform: {name: "CentOS 7"}}, - (ctx) => `epas/14/epas_inst_linux/installing_epas_using_edb_repository/${fmtArchPath(ctx)}/epas_centos7_${fmtArchFilename(ctx)}.mdx`), - when({product: {name: "EDB Postgres Advanced Server", version: 14}, platform: {name: "AlmaLinux 8 or Rocky Linux 8"}}, - (ctx) => `epas/14/epas_inst_linux/installing_epas_using_edb_repository//${fmtArchPath(ctx)}/epas_other_linux8_${fmtArchFilename(ctx)}.mdx`), - when({product: {name: "EDB Postgres Advanced Server", version: 14}, platform: {name: "RHEL 7 or OL 7"}}, - (ctx) => `epas/14/epas_inst_linux/installing_epas_using_edb_repository//${fmtArchPath(ctx)}/epas_rhel7_${fmtArchFilename(ctx)}.mdx`), - when({product: {name: "EDB Postgres Advanced Server", version: 14}, platform: {name: "RHEL 8 or OL 8"}}, - (ctx) => `epas/14/epas_inst_linux/installing_epas_using_edb_repository//${fmtArchPath(ctx)}/epas_rhel8_${fmtArchFilename(ctx)}.mdx`), - when({product: {name: "EDB Postgres Advanced Server", version: 14}, platform: {name: "RHEL 8"}}, - (ctx) => `epas/14/epas_inst_linux/installing_epas_using_edb_repository//${fmtArchPath(ctx)}/epas_rhel8_${fmtArchFilename(ctx)}.mdx`), - when({product: {name: "EDB Postgres Advanced Server", version: 14}, platform: {name: "RHEL 7"}}, - (ctx) => `epas/14/epas_inst_linux/installing_epas_using_edb_repository//${fmtArchPath(ctx)}/epas_rhel7_${fmtArchFilename(ctx)}.mdx`), - when({product: {name: "EDB Postgres Advanced Server", version: 14}, platform: {name: "SLES 12"}}, - (ctx) => `epas/14/epas_inst_linux/installing_epas_using_edb_repository/${fmtArchPath(ctx)}/epas_sles12_${fmtArchFilename(ctx)}.mdx`), - when({product: {name: "EDB Postgres Advanced Server", version: 14}, platform: {name: "SLES 15"}}, - (ctx) => `epas/14/epas_inst_linux/installing_epas_using_edb_repository//${fmtArchPath(ctx)}/epas_sles15_${fmtArchFilename(ctx)}.mdx`), - when({product: {name: "EDB Postgres Advanced Server", version: 14}, platform: {name: "Debian 10"}}, - (ctx) => `epas/14/epas_inst_linux/installing_epas_using_edb_repository//${fmtArchPath(ctx)}/epas_deb10_${fmtArchFilename(ctx)}.mdx`), - when({product: {name: "EDB Postgres Advanced Server", version: 14}, platform: {name: "Debian 11"}}, - (ctx) => `epas/14/epas_inst_linux/installing_epas_using_edb_repository//${fmtArchPath(ctx)}/epas_deb11_${fmtArchFilename(ctx)}.mdx`), - when({product: {name: "EDB Postgres Advanced Server", version: 14}, platform: {name: "Ubuntu 18.04"}}, - (ctx) => `epas/14/epas_inst_linux/installing_epas_using_edb_repository//${fmtArchPath(ctx)}/epas_ubuntu18_${fmtArchFilename(ctx)}.mdx`), - when({product: {name: "EDB Postgres Advanced Server", version: 14}, platform: {name: "Ubuntu 20.04"}}, - (ctx) => `epas/14/epas_inst_linux/installing_epas_using_edb_repository//${fmtArchPath(ctx)}/epas_ubuntu20_${fmtArchFilename(ctx)}.mdx`), ); + when({product: {name: "xdb", version: 99}, platform: {name: "MS-DOS 4.0"}}, + (ctx) => `xdb/99/installing/${fmtArchPath(ctx)}/xdb_centos7_${fmtArchFilename(ctx)}.mdx`), + ); function match(context, ...conditions) { for (let test of conditions) { diff --git a/install_template/templates/platformBase/almalinux-8-or-rocky-linux-8.njk b/install_template/templates/platformBase/almalinux-8-or-rocky-linux-8.njk index 88c3efae798..71c7c2f99eb 100644 --- a/install_template/templates/platformBase/almalinux-8-or-rocky-linux-8.njk +++ b/install_template/templates/platformBase/almalinux-8-or-rocky-linux-8.njk @@ -3,4 +3,4 @@ {% set packageManagerNoninteractive = "-y" %} {% set epelRepo = "epel-release" %} {% block redhatConfig %}# Enable additional repositories to resolve dependencies: -sudo dnf config-manager --set-enabled PowerTools{% block mysqlfdw %}{% endblock mysqlfdw %}{% endblock redhatConfig %} \ No newline at end of file +sudo dnf config-manager --set-enabled powertools{% block mysqlfdw %}{% endblock mysqlfdw %}{% endblock redhatConfig %} \ No newline at end of file diff --git a/install_template/templates/products/edb*plus/base.njk b/install_template/templates/products/edb*plus/base.njk index df8f1f2fa03..f3496f7e3e0 100644 --- a/install_template/templates/products/edb*plus/base.njk +++ b/install_template/templates/products/edb*plus/base.njk @@ -1,5 +1,5 @@ {% extends "platformBase/" + platformBaseTemplate + '.njk' %} -{% set packageName %}edb-as-edbplus{% endset %} +{% set packageName %}edb-edbplus{% endset %} {% import "platformBase/_deploymentConstants.njk" as deploy %} {% block frontmatter %} {# @@ -18,7 +18,6 @@ redirects: {% endblock prodprereq %} {% block installCommand %} {{super()}} -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. {% endblock installCommand %} {% block postinstall %} ## Initial configuration diff --git a/install_template/templates/products/edb-postgres-extended-server/almalinux-8-or-rocky-linux-8.njk b/install_template/templates/products/edb-postgres-extended-server/almalinux-8-or-rocky-linux-8.njk new file mode 100644 index 00000000000..f679743551d --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/almalinux-8-or-rocky-linux-8.njk @@ -0,0 +1,5 @@ +{% extends "products/edb-postgres-extended-server/base.njk" %} +{% set platformBaseTemplate = "almalinux-8-or-rocky-linux-8" %} +{% block installCommand %} +{{ super() }} +{% endblock installCommand %} \ No newline at end of file diff --git a/install_template/templates/products/edb-postgres-extended-server/base.njk b/install_template/templates/products/edb-postgres-extended-server/base.njk new file mode 100644 index 00000000000..57dc62559f4 --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/base.njk @@ -0,0 +1,17 @@ +{% extends "platformBase/" + platformBaseTemplate + '.njk' %} +{% set packageName = packageName or 'edb-postgresextended-server edb-postgresextended-contrib' %} +{% import "platformBase/_deploymentConstants.njk" as deploy %} +{% block frontmatter %} +{# + If you modify deployment path here, please first copy the old expression + and add it to the list under "redirects:" below - this ensures we don't + break any existing links. +#} +deployPath: pge/{{ product.version }}/installing/linux_{{platform.arch}}/pge_{{deploy.map_platform[platform.name]}}.mdx +redirects: +{% endblock frontmatter %} +{% block installCommand %} +{{super()}} +Where `` is the version of EDB Postgres Extended Server you are installing. For example, if you are installing version 15, the package name would be `edb-postgresextended15`. + +{% endblock installCommand %} \ No newline at end of file diff --git a/install_template/templates/products/edb-postgres-extended-server/centos-7.njk b/install_template/templates/products/edb-postgres-extended-server/centos-7.njk new file mode 100644 index 00000000000..2b2e18eba8f --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/centos-7.njk @@ -0,0 +1,5 @@ +{% extends "products/edb-postgres-extended-server/base.njk" %} +{% set platformBaseTemplate = "centos-7" %} +{% block installCommand %} +{{ super() }} +{% endblock installCommand %} \ No newline at end of file diff --git a/install_template/templates/products/edb-postgres-extended-server/debian-10.njk b/install_template/templates/products/edb-postgres-extended-server/debian-10.njk new file mode 100644 index 00000000000..627f9c7f5cf --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/debian-10.njk @@ -0,0 +1,11 @@ +{% extends "products/edb-postgres-extended-server/debian.njk" %} +{% set platformBaseTemplate = "debian-10" %} +{% set packageName %}edb-postgresextended- edb-postgresextended--contrib{% endset %} +{% block installCommand %} +```shell +sudo {{ packageManager }} {{ packageManagerNoninteractive }} install {{ packageName }} +``` + +Where `` is the version of EDB Postgres Extended Server you are installing. For example, if you are installing version 15, the package name would be `edb-postgresextended-15`. + +{% endblock installCommand %} diff --git a/install_template/templates/products/edb-postgres-extended-server/debian-11.njk b/install_template/templates/products/edb-postgres-extended-server/debian-11.njk new file mode 100644 index 00000000000..c6889441f0f --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/debian-11.njk @@ -0,0 +1,11 @@ +{% extends "products/edb-postgres-extended-server/debian.njk" %} +{% set platformBaseTemplate = "debian-11" %} +{% set packageName %}edb-postgresextended- edb-postgresextended--contrib{% endset %} +{% block installCommand %} +```shell +sudo {{ packageManager }} {{ packageManagerNoninteractive }} install {{ packageName }} +``` + +Where `` is the version of EDB Postgres Extended Server you are installing. For example, if you are installing version 15, the package name would be `edb-postgresextended-15`. + +{% endblock installCommand %} diff --git a/install_template/templates/products/edb-postgres-extended-server/debian-9.njk b/install_template/templates/products/edb-postgres-extended-server/debian-9.njk new file mode 100644 index 00000000000..9fe692a5a8b --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/debian-9.njk @@ -0,0 +1,3 @@ +{% extends "products/edb-postgres-extended-server/debian.njk" %} +{% set platformBaseTemplate = "debian-9" %} +{% set packageName %}edb-postgresextended{% endset %} \ No newline at end of file diff --git a/install_template/templates/products/edb-postgres-extended-server/debian.njk b/install_template/templates/products/edb-postgres-extended-server/debian.njk new file mode 100644 index 00000000000..8e726cd1777 --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/debian.njk @@ -0,0 +1,4 @@ +{% extends "products/edb-postgres-extended-server/base.njk" %} +{% block debian_ubuntu %}This section steps you through getting started with your cluster including logging in, ensuring the installation was successful, connecting to your cluster, and creating the user password. + +```shell{% endblock debian_ubuntu %} \ No newline at end of file diff --git a/install_template/templates/products/edb-postgres-extended-server/rhel-7-or-ol-7.njk b/install_template/templates/products/edb-postgres-extended-server/rhel-7-or-ol-7.njk new file mode 100644 index 00000000000..0c79b0b490a --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/rhel-7-or-ol-7.njk @@ -0,0 +1,5 @@ +{% extends "products/edb-postgres-extended-server/base.njk" %} +{% set platformBaseTemplate = "rhel-7-or-ol-7" %} +{% block installCommand %} +{{ super() }} +{% endblock installCommand %} \ No newline at end of file diff --git a/install_template/templates/products/edb-postgres-extended-server/rhel-7_ppc64le.njk b/install_template/templates/products/edb-postgres-extended-server/rhel-7_ppc64le.njk new file mode 100644 index 00000000000..3592a52a7b4 --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/rhel-7_ppc64le.njk @@ -0,0 +1,6 @@ +{% extends "products/edb-postgres-extended-server/rhel-7-or-ol-7.njk" %} +{% set includePPC = true %} +{% set packageName %}edb-postgresextended{% endset %} +{% block installCommand %} +{{ super() }} +{% endblock installCommand %} \ No newline at end of file diff --git a/install_template/templates/products/edb-postgres-extended-server/rhel-8-or-ol-8.njk b/install_template/templates/products/edb-postgres-extended-server/rhel-8-or-ol-8.njk new file mode 100644 index 00000000000..9e9df9dbfd1 --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/rhel-8-or-ol-8.njk @@ -0,0 +1,5 @@ +{% extends "products/edb-postgres-extended-server/base.njk" %} +{% set platformBaseTemplate = "rhel-8-or-ol-8" %} +{% block installCommand %} +{{ super() }} +{% endblock installCommand %} \ No newline at end of file diff --git a/install_template/templates/products/edb-postgres-extended-server/rhel-8_ppc64le.njk b/install_template/templates/products/edb-postgres-extended-server/rhel-8_ppc64le.njk new file mode 100644 index 00000000000..84f94e6ebdc --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/rhel-8_ppc64le.njk @@ -0,0 +1,2 @@ +{% extends "products/edb-postgres-extended-server/rhel-8-or-ol-8.njk" %} +{% set includePPC = true %} diff --git a/install_template/templates/products/edb-postgres-extended-server/sles-12.njk b/install_template/templates/products/edb-postgres-extended-server/sles-12.njk new file mode 100644 index 00000000000..4c86e881d3c --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/sles-12.njk @@ -0,0 +1,3 @@ +{% extends "products/edb-postgres-extended-server/base.njk" %} +{% set platformBaseTemplate = "sles-12" %} +{% set packageManager = "zypper" %} diff --git a/install_template/templates/products/edb-postgres-extended-server/sles-12_ppc64le.njk b/install_template/templates/products/edb-postgres-extended-server/sles-12_ppc64le.njk new file mode 100644 index 00000000000..6cf18c8de4b --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/sles-12_ppc64le.njk @@ -0,0 +1,2 @@ +{% extends "products/edb-postgres-extended-server/sles-12.njk" %} +{% set includePPC = true %} diff --git a/install_template/templates/products/edb-postgres-extended-server/sles-15.njk b/install_template/templates/products/edb-postgres-extended-server/sles-15.njk new file mode 100644 index 00000000000..21af744f360 --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/sles-15.njk @@ -0,0 +1,3 @@ +{% extends "products/edb-postgres-extended-server/base.njk" %} +{% set platformBaseTemplate = "sles-15" %} +{% set packageManager = "zypper" %} diff --git a/install_template/templates/products/edb-postgres-extended-server/sles-15_ppc64le.njk b/install_template/templates/products/edb-postgres-extended-server/sles-15_ppc64le.njk new file mode 100644 index 00000000000..7e768c8f667 --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/sles-15_ppc64le.njk @@ -0,0 +1,2 @@ +{% extends "products/edb-postgres-extended-server/sles-15.njk" %} +{% set includePPC = true %} diff --git a/install_template/templates/products/edb-postgres-extended-server/ubuntu-18.04.njk b/install_template/templates/products/edb-postgres-extended-server/ubuntu-18.04.njk new file mode 100644 index 00000000000..e6b9757211f --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/ubuntu-18.04.njk @@ -0,0 +1,3 @@ +{% extends "products/edb-postgres-extended-server/ubuntu.njk" %} +{% set platformBaseTemplate = "ubuntu-18.04" %} +{% set packageName %}edb-postgresextended- edb-postgresextended--contrib{% endset %} diff --git a/install_template/templates/products/edb-postgres-extended-server/ubuntu-20.04.njk b/install_template/templates/products/edb-postgres-extended-server/ubuntu-20.04.njk new file mode 100644 index 00000000000..c387ca6b7eb --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/ubuntu-20.04.njk @@ -0,0 +1,3 @@ +{% extends "products/edb-postgres-extended-server/ubuntu.njk" %} +{% set platformBaseTemplate = "ubuntu-20.04" %} +{% set packageName %}edb-postgresextended- edb-postgresextended--contrib{% endset %} diff --git a/install_template/templates/products/edb-postgres-extended-server/ubuntu-22.04.njk b/install_template/templates/products/edb-postgres-extended-server/ubuntu-22.04.njk new file mode 100644 index 00000000000..8ae92600277 --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/ubuntu-22.04.njk @@ -0,0 +1,7 @@ +{% extends "products/edb-postgres-extended-server/ubuntu.njk" %} +{% set platformBaseTemplate = "ubuntu-22.04" %} +{% set packageName %}edb-postgresextended- edb-postgresextended--contrib{% endset %} +{% block frontmatter %} +{# remove this block when Ubuntu 22 is released #} +{% endblock frontmatter %} + diff --git a/install_template/templates/products/edb-postgres-extended-server/ubuntu.njk b/install_template/templates/products/edb-postgres-extended-server/ubuntu.njk new file mode 100644 index 00000000000..30c491228a9 --- /dev/null +++ b/install_template/templates/products/edb-postgres-extended-server/ubuntu.njk @@ -0,0 +1 @@ +{% extends "products/edb-postgres-extended-server/base.njk" %} diff --git a/install_template/templates/products/hadoop-foreign-data-wrapper/rhel-8-or-ol-8.njk b/install_template/templates/products/hadoop-foreign-data-wrapper/rhel-8-or-ol-8.njk index 0fa5eea26d0..318c7ec0bd0 100644 --- a/install_template/templates/products/hadoop-foreign-data-wrapper/rhel-8-or-ol-8.njk +++ b/install_template/templates/products/hadoop-foreign-data-wrapper/rhel-8-or-ol-8.njk @@ -2,6 +2,4 @@ {% set platformBaseTemplate = "rhel-8-or-ol-8" %} {% block redhatConfig %}# Enable additional repositories to resolve dependencies: sudo dnf config-manager --set-enabled PowerTools - - # Disable the built-in PostgreSQL module: - sudo dnf -qy module disable postgresql{% endblock redhatConfig %} \ No newline at end of file +{% endblock redhatConfig %} \ No newline at end of file diff --git a/install_template/templates/products/migration-toolkit/rhel-8_ppc64le.njk b/install_template/templates/products/migration-toolkit/rhel-8_ppc64le.njk index 2be7c031afe..abd6aa6ae3d 100644 --- a/install_template/templates/products/migration-toolkit/rhel-8_ppc64le.njk +++ b/install_template/templates/products/migration-toolkit/rhel-8_ppc64le.njk @@ -3,6 +3,4 @@ {% block redhatConfig %} # Enable additional repositories to resolve dependencies: ARCH=$( /bin/arch ) subscription-manager repos --enable "codeready-builder-for-rhel-8-${ARCH}-rpms" - - # Disable the built-in PostgreSQL module: - sudo dnf -qy module disable postgresql{% endblock redhatConfig %} \ No newline at end of file +{% endblock redhatConfig %} \ No newline at end of file diff --git a/product_docs/docs/edb_plus/36/03_installing_edb_plus/01_installing_prereq.mdx b/product_docs/docs/edb_plus/36/03_installing_edb_plus/01_installing_prereq.mdx deleted file mode 100644 index 2fffd9c7947..00000000000 --- a/product_docs/docs/edb_plus/36/03_installing_edb_plus/01_installing_prereq.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Installation Prerequisites" - ---- - - - -This table lists the supported corresponding EDB Postgres Advanced Server (EPAS) versions. EDB\*Plus is supported on the same platforms as EDB Postgres Advanced Server. See [Product Compatibility](https://www.enterprisedb.com/platform-compatibility#epas) for details. - -| EDB*Plus | EPAS 14 | EPAS 13 | EPAS 12 | EPAS 11 | EPAS 10 | -| -------- | ------- | ------- | ------- | ------- | ------- | -| 36 | N | N | N | Y | Y | - -Before installing EDB\*Plus, you must first install Java (version 1.7 or later). On a Linux system, you can use the `yum` package manager to install Java. Open a terminal window, assume superuser privileges, and enter: - - ```text - # yum install java - ``` - -If you are using Windows, Java installers and instructions are available online at: - - - - -You must also have credentials that allow access to the EDB repository. For information about requesting credentials, visit: - - - - -After receiving your repository credentials: - -1. Create the repository configuration file. -2. Modify the file, providing your user name and password. -3. Install EDB\*Plus. - - - - - - diff --git a/product_docs/docs/edb_plus/36/03_installing_edb_plus/02_rpm_installation.mdx b/product_docs/docs/edb_plus/36/03_installing_edb_plus/02_rpm_installation.mdx deleted file mode 100644 index 06e8fa85880..00000000000 --- a/product_docs/docs/edb_plus/36/03_installing_edb_plus/02_rpm_installation.mdx +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "Performing an RPM Installation" ---- - - - -For detailed information about creating and using EDB repositories to install Advanced Server or its supporting components, see the *EDB Postgres Advanced Server Installation Guide available* at: - -[https://www.enterprisedb.com/docs](/epas/10) - -**Creating a Repository Configuration File** - -To create the repository configuration file, assume superuser privileges, and invoke the following command: - -- On RHEL or CentOS 7: - - ```text - yum -y install https://yum.enterprisedb.com/edbrepos/edb-repo-latest.noarch.rpm - ``` - -The repository configuration file is named `edb.repo`. The file resides in `/etc/yum.repos.d`. After saving your changes to the configuration file, you can use the following command to install EDB*Plus: - -- On RHEL or CentOS 7: - - ``` - yum install edb-asxx-edbplus - ``` - -Where, `xx` is the Advanced Server version. - -When you install an RPM package that is signed by a source that is not recognized by your system, yum may ask for your permission to import the key to your local server. If prompted, and you are satisfied that the packages come from a trustworthy source, enter y, and press `Return` to continue. - -During the installation, yum may encounter a dependency that it cannot resolve. If it does, it will provide a list of the required dependencies that you must manually resolve. - - -## Configuring an RPM Installation - -After performing an RPM installation of EDB\*Plus, you must set the values of environment variables that allow -EDB\*Plus to locate your Java installation. Use the following commands to set variable values: - -```text -export JAVA_HOME= -export PATH=/bin:$PATH -``` - -By default, the `pg_hba.conf` file for the RPM installer enforces `IDENT` authentication. Before invoking EDB*Plus, you must either modify the `pg_hba.conf` file, changing the authentication method to a form other than `IDENT` (and restarting the server), or perform the following steps to ensure that an `IDENT` server is accessible: - -You must confirm that an `identd` server is installed and running. You can use the `yum` package manager to install an `identd` server by invoking the command: - -```text -yum install xinetd authd -``` - -The command should create a file named ``/etc/xinetd.d/auth`` that contains: - -```text -service auth -{ - disable = yes - socket_type = stream -wait =no -user = ident -cps = 4096 10 -instances = UNLIMITED -server = /usr/sbin/in.authd server_args = -t60 --xerror -os -} -``` - -!!! Note - If the file includes a `-E` argument at the end of the server arguments, please erase `-E`. - -Then, to start the `identd` server, invoke the following commands: - -```text -systemctl enable xinetd -systemctl start xinetd -``` - -Open the `pg_ident.conf` file and create a user mapping: - -``` -# map_name system_username postgres_username - edbas enterprisedb enterprisedb -``` - -Where: - -- The name specified in the `map_name` column is a user-defined name that will identify the mapping in the `pg_hba.conf` file. -- The name specified in the `system_username` column is `enterprisedb`. -- The name specified in the `postgres_username` column is `enterprisedb`. - -Then, open the `pg_hba.conf` file and modify the `IDENT` entries: - -- If you are using an IPv4 local connection, modify the file entry to read: - - `host all all 127.0.0.0/0 ident map=edbas` - -- If you are using an IPv6 local connection, modify the file entry to read: - - `host all all ::1/128 ident map=edbas` - -You must restart the Advanced Server service before invoking EDB\*Plus. For detailed information about controlling the Advanced Server service, see the *EDB Postgres Advanced Server Installation Guide*, available at: - -[https://www.enterprisedb.com/docs](/epas/10) - - - diff --git a/product_docs/docs/edb_plus/36/03_installing_edb_plus/03_using_gui.mdx b/product_docs/docs/edb_plus/36/03_installing_edb_plus/03_using_gui.mdx deleted file mode 100644 index df42a80b95e..00000000000 --- a/product_docs/docs/edb_plus/36/03_installing_edb_plus/03_using_gui.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "Using the Graphical Installer" ---- - - - -Graphical installers for EDB\*Plus are available via StackBuilder Plus; you can access StackBuilder Plus through your Windows or Linux start menu. After opening StackBuilder Plus and selecting the installation for which you wish to install EDB\*Plus, expand the component selection screen tree control to select and download the EDB\*Plus installer. - -![The EDB\*Plus Welcome window](../images/edb_plus_welcome.png) - -
Fig. 1: The EDB*Plus Welcome window
- - -The EDB\*Plus installer welcomes you to the setup wizard, as shown in the figure below. - -![The Installation Directory window](../images/installation_directory.png) - -
Fig. 2: The Installation Directory window
- - -Use the `Installation Directory` field to specify the directory in which you wish to install the EDB\*Plus software. Then, click `Next` to continue. - -![The Advanced Server Installation Details window](../images/advanced_server_installation_details.png) - -
Fig. 3: The Advanced Server Installation Details window
- - -Use fields on the `EDB Postgres Advanced Server Installation Details` window to identify the location of the Advanced Server host: - -- Use the `Host` field to identify the system on which Advanced Server resides. -- Use the `Port` field to identify the listener port that Advanced Server monitors for client connections. - -Then, click `Next` to continue. - -![The Ready to Install window](../images/ready_to_install.png) - -
Fig. 4: The Ready to Install window
- - -The `Ready to Install` window notifies you when the installer has all of the information needed to install EDB\*Plus on your system. Click `Next` to install EDB\*Plus. - -![The installation is complete](../images/installation_complete.png) - -
Fig. 5: The installation is complete
- - -The installer notifies you when the setup wizard has completed the EDB\*Plus installation. Click `Finish` to exit the installer. diff --git a/product_docs/docs/edb_plus/36/03_installing_edb_plus/index.mdx b/product_docs/docs/edb_plus/36/03_installing_edb_plus/index.mdx deleted file mode 100644 index 7930a6b3298..00000000000 --- a/product_docs/docs/edb_plus/36/03_installing_edb_plus/index.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Installing EDB*Plus" - ---- - -You can use an RPM installer or a graphical installer to add EDB*Plus to your Advanced Server installation. - -
- -installing_prereq rpm_installation using_gui - -
\ No newline at end of file diff --git a/product_docs/docs/edb_plus/36/04_using_edb_plus.mdx b/product_docs/docs/edb_plus/36/04_using_edb_plus.mdx deleted file mode 100644 index 4f4856304ba..00000000000 --- a/product_docs/docs/edb_plus/36/04_using_edb_plus.mdx +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: "Using EDB*Plus" ---- - - - - - -To open an EDB\*Plus command line, navigate through the `Applications` or `Start` menu to the Advanced Server menu, to the `Run SQL Command Line` menu, and select the EDB\*Plus option. You can also invoke EDB\*Plus from the operating system command line with the following command: - -```text -edbplus [ -S[ILENT ] ] [ | /NOLOG ] [ @[. ] ] -``` - -`SILENT` - - If specified, the EDB\*Plus sign-on banner is suppressed along with all prompts. - -`login` - - Login information for connecting to the database server and database. `login` takes the following form; there must be no white space within the login information. - -```text -[/][@{ | } ] -``` - - Where: - - `username` is a database username with which to connect to the database. - - `password` is the password associated with the specified `username`. If a `password` is not provided, but a password is required for authentication, a password file is used if available. If there is no password file or no entry in the password file with the matching connection parameters, then EDB\*Plus will prompt for the password. - - `connectstring` is the database connection string with the following format: - -```text -[:][/][?ssl={true | false}] -``` - - Where: - -- `host` is the hostname or IP address on which the database server resides. If neither `@connectstring` nor `@variable` nor `/NOLOG` is specified, the default host is assumed to be the localhost. - -- `port` is the port number receiving connections on the database server. If not specified, the default is `5444`. - -- `dbname` is the name of the database to connect to. If not specified the default is `edb`. - -- If `Internet Protocol version 6` (IPv6) is used for the connection instead of IPv4, then the IP address must be enclosed within square brackets (that is, `[ipv6_address]`). The following is an example using an IPv6 connection: - -```text -edbplus.sh enterprisedb/password@[fe80::20c:29ff:fe7c:78b2]:5444/edb -``` - - The `pg_hba.conf` file for the database server must contain an appropriate entry for the IPv6 connection. The following example shows an entry that allows all addresses: - -```text -# TYPE DATABASE USER ADDRESS METHOD -host all all ::0/0 md5 -``` - -For more information about the `pg_hba.conf` file, see the PostgreSQL core documentation at: - - - - If an SSL connection is desired, then include the `?ssl=true` parameter in the connection string. In such a case, the connection string must minimally include `host:port`, with or without `/dbname`. If the `ssl` parameter is not specified, the default is `false`. See [Using a Secure Sockets Layer (SSL) Connection](05_using_edb_plus_with_ssl/#using_edb_plus_with_ssl) for instructions on setting up an SSL connection. - - `variable` is a variable defined in the `login.sql` file that contains a database connection string. The `login.sql` file can be found in the `edbplus` subdirectory of the Advanced Server home directory. - -`/NOLOG` - - Specify `/NOLOG` to start EDB\*Plus without establishing a database connection. SQL commands and EDB\*Plus commands that require a database connection cannot be used in this mode. The `CONNECT` command can be subsequently given to connect to a database after starting EDB\*Plus with the `/NOLOG` option. - -`scriptfile[.ext ]` - - `scriptfile` is the name of a file residing in the current working directory, containing SQL and/or EDB\*Plus commands that will be automatically executed after startup of EDB\*Plus. `ext` is the filename extension. If the filename extension is `sql`, then the `.sql` extension may be omitted when specifying `scriptfile`. When creating a script file, always name the file with an extension, otherwise it will not be accessible by EDB\*Plus. (EDB\*Plus will always assume a `.sql` extension on filenames that are specified with no extension.) - -!!! note - When you run the commands in the following examples you may be using a newer version of EDB\*Plus and as such the EDB\*Plus build number shown in your output may be different. - -The following example shows user `enterprisedb` with password `password`, connecting to database `edb` running on a database server on the `localhost` at port `5444`. - -```text -C:\Program Files\edb\as10\edbplus>edbplus enterprisedb/password -Connected to EnterpriseDB 10.0.1 (localhost:5444/edb) AS enterprisedb - -EDB*Plus: Release 10 (Build 36.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -The following example shows user `enterprisedb` with password, `password`, connecting to database `edb` running on a database server on the `localhost` at port `5445`. - -```text -C:\Program Files\edb\as10\edbplus>edbplus enterprisedb/password@localhost:5445/edb -Connected to EnterpriseDB 10.0.1 (localhost:5445/edb) AS enterprisedb - -EDB*Plus: Release 10 (Build 36.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -Using variable `hr_5445` in the `login.sql` file, the following illustrates how it is used to connect to database `hr` on localhost at port `5445`. - -```text -C:\Program Files\edb\as10\edbplus>edbplus enterprisedb/password@hr_5445 -Connected to EnterpriseDB 10.0.1 (localhost:5445/hr) AS enterprisedb - -EDB*Plus: Release 10 (Build 36.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -The following is the content of the `login.sql` file used in the previous example. - -```text -define edb="localhost:5445/edb" -define hr_5445="localhost:5445/hr" -``` - -The following example executes a script file, `dept_query.sql` after connecting to database `edb` on server localhost at port `5444`. - -```text -C:\Program Files\edb\as10\edbplus>edbplus enterprisedb/password @dept_query -Connected to EnterpriseDB 10.0.1 (localhost:5444/edb) AS enterprisedb - -SQL> SELECT * FROM dept; - -DEPTNO DNAME LOC ------- -------------- ------------- -10 ACCOUNTING NEW YORK -20 RESEARCH DALLAS -30 SALES CHICAGO -40 OPERATIONS BOSTON - -SQL> EXIT -Disconnected from EnterpriseDB Database. -``` - -The following is the content of file `dept_query.sql` used in the previous example. - -```text -SET PAGESIZE 9999 -SET ECHO ON -SELECT * FROM dept; -EXIT -``` diff --git a/product_docs/docs/edb_plus/36/05_using_edb_plus_with_ssl.mdx b/product_docs/docs/edb_plus/36/05_using_edb_plus_with_ssl.mdx deleted file mode 100644 index 084302cae50..00000000000 --- a/product_docs/docs/edb_plus/36/05_using_edb_plus_with_ssl.mdx +++ /dev/null @@ -1,324 +0,0 @@ ---- -title: "Using a SSL Connection" ---- - - - - - -An EDB\*Plus connection to the Advanced Server database can be accomplished using secure sockets layer (SSL) connectivity. - -Using SSL requires various prerequisite configuration steps performed on the database server involved with the SSL connection as well as creation of the Java truststore and keystore on the host that will run EDB\*Plus. - -The Java *truststore* is the file containing the Certificate Authority (CA) certificates with which the Java client (EDB\*Plus) uses to verify the authenticity of the server to which it is initiating an SSL connection. - -The Java *keystore* is the file containing private and public keys and their corresponding certificates. The keystore is required for client authentication to the server, which is used for the EDB\*Plus connection. - -The following is material to which you can refer to for guidance in setting up the SSL connections: - -- For information on setting up SSL connectivity to the Advanced Server database, see the section about secure TCP connections with SSL in Chapter 18 “Server Setup and Operation” in the PostgreSQL Core Documentation located at: - - - -- For information on JDBC client connectivity using SSL, see the section on configuring the client in Chapter 4 “Using SSL” in The PostgreSQL JDBC Interface located at: - - - -The following sections provide information for the configuration steps of using SSL. - -- Configuring SSL on Advanced Server -- Configuring SSL for the EDB\*Plus client -- Requesting SSL connection to the Advanced Server database - -## Configuring SSL on Advanced Server - -This section provides an example of configuring SSL on a database server to demonstrate the use of SSL with EDB\*Plus. A self-signed certificate is used for this purpose. - -**Step 1:** Create the certificate signing request (CSR). - -In the following example the generated certificate signing request file is `server.csr`. The private key is generated as file `server.key`. - -```text -$ openssl req -new -nodes -text -out server.csr \ -> -keyout server.key -subj "/CN=enterprisedb" -Generating a 2048 bit RSA private key -.............................+++ -....................................................................+++ -writing new private key to 'server.key' ------ -``` - -!!! Note - When creating the certificate, the value specified for the common name field (designated as `CN=enterprisedb` in this example) must be the database user name that is specified when connecting to EDB\*Plus. - -In addition, user name maps can be used as defined in the `pg_ident.conf` file to permit more flexibility for the common name and database user name. Steps 8 and 9 describe the use of user name `maps`. - -**Step 2:** Generate the self-signed certificate. - -The following generates a self-signed certificate to file `server.crt` using the certificate signing request file, `server.csr`, and the private key, `server.key`, as input. - -```text -$ openssl x509 -req -days 365 -in server.csr -signkey server.key \ -> -out server.crt -Signature ok -subject=/CN=enterprisedb -Getting Private key -``` - -**Step 3:** Make a copy of the server certificate (`server.crt`) to be used as the root Certificate Authority (CA) file (`root.crt`). - -```text -$ cp server.crt root.crt -``` - -**Step 4:** Delete the now redundant certificate signing request (`server.csr`). - -```text -$ rm -f server.csr -``` - -**Step 5:** Move or copy the certificate and private key files to the Advanced Server data directory (for example, `/opt/edb/as10/data`). - -```text -$ mv root.crt /opt/edb/as10/data -$ mv server.crt /opt/edb/as10/data -$ mv server.key /opt/edb/as10/data -``` - -**Step 6:** Set the file ownership and permissions on the certificate files and private key file. - -Set the ownership to the operating system account that owns the data sub-directory of the database server. Set the permissions so that no other groups or accounts other than the owner can access these files. - -```text -$ chown enterprisedb root.crt server.crt server.key -$ chgrp enterprisedb root.crt server.crt server.key -$ chmod 600 root.crt server.crt server.key -$ ls -l -total 152 - . - . - . --rw------- 1 enterprisedb enterprisedb 985 Aug 22 11:00 root.crt --rw------- 1 enterprisedb enterprisedb 985 Aug 22 10:59 server.crt --rw------- 1 enterprisedb enterprisedb 1704 Aug 22 10:58 server.key -``` - -**Step 7:** In the `postgresql.conf` file, make the following modifications. - -```text -ssl = on -ssl_cert_file = 'server.crt' -ssl_key_file = 'server.key' -ssl_ca_file = 'root.crt' -``` - -**Step 8:** Modify the `pg_hba.conf` file to enable SSL usage on the desired database to which EDB\*Plus is to make the SSL connection. - -In the `pg_hba.conf` file, the `hostssl` type indicates the entry is used to validate SSL connection attempts from the client (EDB\*Plus). - -The authentication method is set to cert with the option `clientcert=1` in order to require an SSL certificate from the client against which authentication is performed using the common name of the certificate (`enterprisedb` in this example). - -The `map=sslusers` option specifies that a mapping named `sslusers` defined in the `pg_ident.conf` file is to be used for authentication. This mapping allows a connection to the database if the common name from the certificate and the database user name attempting the connection match the `SYSTEM-USERNAME/PG-USERNAME` pair listed in the `pg_ident.conf` file. - -The following is an example of the settings in the `pg_hba.conf` file if the database `(edb)` must use SSL connections. - -```text -# TYPE DATABASE USER ADDRESS METHOD - -# "local" is for Unix domain socket connections only -local all all md5 -# IPv4 local connections: -hostssl edb all 192.168.2.0/24 cert clientcert=1 map=sslusers -``` - -**Step 9:** The following shows the user name maps in the `pg_ident.conf` file related to the `pg_hba.conf` file by the `map=sslusers` option. These user name maps permit you to specify database user names `edbuser`, `postgres`, or `enterprisedb` when connecting with EDB\*Plus. - -```text -# MAPNAME SYSTEM-USERNAME PG-USERNAME - sslusers enterprisedb edbuser - sslusers enterprisedb postgres - sslusers enterprisedb enterprisedb -``` - -**Step 10:** Restart the database server after you have made the changes to the configuration files. - -## Configuring SSL for the EDB\*Plus Client - -After you have configured SSL on the database server, the following steps provide an example of generating certificate and keystore files for EDB\*Plus (the JDBC client). - -**Step 1:** Using files `server.crt` and `server.key` located under the database server data sub-directory, create copies of these files and move them to the host where EDB\*Plus is to be running. - -Store these files in the desired directory to contain the trusted certificate and keystore files to be generated in the following steps. The suggested location is to create a `.postgresql` sub-directory under the home user account that will invoke EDB\*Plus. Thus, these files will be under the `~/.postgresql` directory of the user account that will run EDB\*Plus. - -For this example, assume file `edb.crt` is a copy of `server.crt` and `edb.key` is a copy of `server.key`. - -**Step 2:** Create an additional copy of `edb.crt`. - -```text -$ cp edb.crt edb_root.crt -$ ls -l -total 12 --rw-r--r-- 1 user user 985 Aug 22 14:17 edb.crt --rw-r--r-- 1 user user 1704 Aug 22 14:18 edb.key --rw-r--r-- 1 user user 985 Aug 22 14:19 edb_root.crt -``` - -**Step 3:** Create a Distinguished Encoding Rules (DER) format of file `edb_root.crt`. The generated DER format of this file is `edb_root.crt.der`. The DER format of the file is required for the `keytool` program used in Step 4. - -```text -$ openssl x509 -in edb_root.crt -out edb_root.crt.der -outform der -$ ls -l -total 16 --rw-r--r-- 1 user user 985 Aug 22 14:17 edb.crt --rw-r--r-- 1 user user 1704 Aug 22 14:18 edb.key --rw-r--r-- 1 user user 985 Aug 22 14:19 edb_root.crt --rw-rw-r-- 1 user user 686 Aug 22 14:21 edb_root.crt.der -``` - -**Step 4:** Use the `keytool` program to create a keystore file `(postgresql.keystore)` using `edb_root.crt.der` as the input. This process adds the certificate of the Postgres database server to the keystore file. - -!!! Note - The file name `postgresql.keystore` is recommended so that it can be accessed in its default directory location `~/.postgresql/postgresql.keystore`, which is under the home directory of the user account invoking EDB\*Plus. Also note that the file name suffix can be `.jks` instead of `.keystore` (thus, file name `postgresql.jks`). However, in the remainder of these examples, file name `postgresql.keystore` is used. - -**For Windows only:** The path is `%APPDATA%\.postgresql\postgresql.keystore` - -The `keytool` program can be found under the `bin` subdirectory of the Java Runtime Environment installation. - -You will be prompted for a new password. Save this password as it must be specified with the PGSSLCERTPASS environment variable. - -```text -$ /usr/java/jdk1.8.0_131/jre/bin/keytool -keystore postgresql.keystore \ -> -alias postgresqlstore -import -file edb_root.crt.der -Enter keystore password: -Re-enter new password: -Owner: CN=enterprisedb -Issuer: CN=enterprisedb -Serial number: c60f40256b0e8d53 -Valid from: Tue Aug 22 10:59:25 EDT 2017 until: Wed Aug 22 10:59:25 EDT 2018 -Certificate fingerprints: - MD5: 85:0B:E9:A7:6E:4F:7C:B0:9B:D6:3A:44:55:E2:E9:8E - SHA1: DD:A6:71:24:0B:6C:F8:BC:7A:4C:89:9B:DC:22:6A:6C:B0:F5:3F:7C - SHA256: -DC:02:64:E2:B0:E9:6F:1C:FC:4F:AE:E6:18:85:0B:79:57:43:C3:C5:AE:43:0D:37 -:49:53:6D:11:69:06:46:48 - Signature algorithm name: SHA1withRSA - Version: 1 -Trust this certificate? [no]: yes -Certificate was added to keystore -``` - -**Step 5:** Create a `PKCS #12` format of the keystore file `(postgresql.p12)` using files `edb.crt` and `edb.key` as input. - -!!! Note - The file name `postgresql.p12` is recommended so that it can be accessed in its default directory location `~/.postgresql/postgresql.p12`, which is under the home directory of the user account invoking EDB\*Plus. - -**For Windows only:** The path is `%APPDATA%\.postgresql\postgresql.p12` - -You will be prompted for a new password. Save this password as it must be specified with the PGSSLKEYPASS environment variable. - -```text -$ openssl pkcs12 -export -in edb.crt -inkey edb.key -out postgresql.p12 -Enter Export Password: -Verifying - Enter Export Password: -$ ls –l -total 24 --rw-rw-r-- 1 user user 985 Aug 24 12:18 edb.crt --rw-rw-r-- 1 user user 1704 Aug 24 12:18 edb.key --rw-rw-r-- 1 user user 985 Aug 24 12:20 edb_root.crt --rw-rw-r-- 1 user user 686 Aug 24 12:20 edb_root.crt.der --rw-rw-r-- 1 user user 758 Aug 24 12:26 postgresql.keystore --rw-rw-r-- 1 user user 2285 Aug 24 12:28 postgresql.p12 -``` - -**Step 6:** If the `postgresql.keystore` and `postgresql.p12` files are not already in the `~/.postgresql` directory, move or copy them to that location. - -**For Windows only:** The directory is `%APPDATA%\.postgresql` - -**Step 7:** If the default location `~/.postgresql` is not used, then the full path (including the file name) to the `postgresql.keystore` file must be set with the `PGSSLCERT` environment variable, and the full path (including the file name) to file `postgresql.p12` must be set with the `PGSSLKEY` environment variable before invoking EDB\*Plus. - -In addition, if the generated file from Step 4 was not named `postgresql.keystore` or `postgresql.jks` then, use the `PGSSLCERT` environment variable to designate the file name and its location. Similarly, if the generated file from Step 5 was not named `postgresql.p12` then, use the `PGSSLKEY` environment variable to designate the file name and its location. - -## Requesting an SSL Connection between EDB\*Plus and the Advanced Server Database - -Be sure the following topics have been addressed in order to perform an SSL connection: - -- The trusted certificate and keystore files have been generated for both the database server and the client host to be invoking EDB\*Plus. -- The `postgresql.conf` file for the database server contains the updated configuration parameters. -- The `pg_hba.conf` file for the database server contains the required entry for permitting the SSL connection. -- For the client host, either the client’s certificate and keystore files have been placed in the user account’s `~/.postgresql` directory or the environment variables `PGSSLCERT` and `PGSSLKEY` are set before invoking EDB\*Plus. -- The `PGSSLCERTPASS` environment variable is set with a password. -- The `PGSSLKEYPASS` environment variable is set with a password - -When invoking EDB\*Plus, include the `?ssl=true` parameter in the database connection string as shown for the `connectstring` option. - -The following is an example where EDB\*Plus is invoked from a host that is remote to the database server. - -The `postgresql.conf` file of the database server contains the following modified parameters: - -```text -ssl = on -ssl_cert_file = 'server.crt' -ssl_key_file = 'server.key' -ssl_ca_file = 'root.crt' -``` - -The `pg_hba.conf` file of the database server contains the following entry for connecting from EDB\*Plus on the remote host: - -```text -# TYPE DATABASE USER ADDRESS METHOD - -# "local" is for Unix domain socket connections only -local all all md5 -# IPv4 local connections: -hostssl edb all 192.168.2.24/32 cert clientcert=1 -``` - -On the remote host where EDB\*Plus is to be invoked, the Linux user account named `user` contains the certificate and keystore files in its `~/.postgresql` directory: - -```text -[user@localhost ~]$ whoami -user -[user@localhost ~]$ cd .postgresql -[user@localhost .postgresql]$ pwd -/home/user/.postgresql -[user@localhost .postgresql]$ ls -l -total 8 --rw-rw-r-- 1 user user 758 Aug 24 12:37 postgresql.keystore --rw-rw-r-- 1 user user 2285 Aug 24 12:37 postgresql.p12 -``` - -Logged into Linux with the account named `user`, EDB\*Plus is successfully invoked with the `ssl=true` parameter: - -```text -$ export PGSSLCERTPASS=keypass -$ export PGSSLKEYPASS=exppass -$ cd /opt/edb/as10/edbplus -$ ./edbplus.sh enterprisedb/password@192.168.2.22:5444/edb?ssl=true -Connected to EnterpriseDB 10.0.1 (192.168.2.22:5444/edb) AS enterprisedb - -EDB*Plus: Release 10 (Build 36.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -Alternatively, without placing the certificate and keystore files in `~/.postgresql`, but in a different directory, EDB\*Plus can be invoked in the following manner: - -```text -$ export PGSSLCERT=/home/user/ssl/postgresql.keystore -$ export PGSSLKEY=/home/user/ssl/postgresql.p12 -$ export PGSSLCERTPASS=keypass -$ export PGSSLKEYPASS=exppass -$ cd /opt/edb/as10/edbplus -$ ./edbplus.sh enterprisedb/password@192.168.2.22:5444/edb?ssl=true -Connected to EnterpriseDB 10.0.1 (192.168.2.22:5444/edb) AS enterprisedb - -EDB*Plus: Release 10 (Build 36.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -Note that in both cases the database user name used to log into EDB\*Plus is `enterprisedb` as this is the user specified for the common name field when creating the certificate in Step 1 of [Configuring SSL on Advanced Server](#using_ssl_connection). - -Other database user names can be used if the `pg_hba.conf` file with the `map` option and the `pg_ident.conf` file are used. diff --git a/product_docs/docs/edb_plus/36/06_command_summary.mdx b/product_docs/docs/edb_plus/36/06_command_summary.mdx deleted file mode 100644 index 7bd40d1dd0a..00000000000 --- a/product_docs/docs/edb_plus/36/06_command_summary.mdx +++ /dev/null @@ -1,995 +0,0 @@ ---- -title: "Command Summary" ---- - - - -The following sections contains a summary of EDB\*Plus commands. - -## ACCEPT - -The `ACCEPT` command displays a prompt and waits for the user’s keyboard input. The value input by the user is placed in the specified variable. - -```text -ACC[EPT ] variable -``` - -The following example creates a new variable named `my_name`, accepts a value of John Smith, then displays the value using the `DEFINE` command. - -```text -SQL> ACCEPT my_name -Enter value for my_name: John Smith -SQL> DEFINE my_name -DEFINE MY_NAME = "John Smith" -``` - -## APPEND - -`APPEND` is a line editor command that appends the given text to the end of the current line in the SQL buffer. - -```text -A[PPEND ] text -``` - -In the following example, a `SELECT` command is built-in the SQL buffer using the `APPEND` command. Note that two spaces are placed between the `APPEND` command and the `WHERE` clause in order to separate `dept` and `WHERE` by one space in the SQL buffer. - -```text -SQL> APPEND SELECT * FROM dept -SQL> LIST - 1 SELECT * FROM dept -SQL> APPEND WHERE deptno = 10 -SQL> LIST - 1 SELECT * FROM dept WHERE deptno = 10 -``` - -## CHANGE - -`CHANGE` is a line editor command performs a search-and-replace on the current line in the SQL buffer. - -```text -C[HANGE ] FROM [ TO ] -``` - -If `TO/` is specified, the first occurrence of text `FROM` in the current line is changed to text `TO`. If `TO/` is omitted, the first occurrence of text `FROM` in the current line is deleted. - -The following sequence of commands makes line 3 the current line, then changes the department number in the `WHERE` clause from 20 to 30. - -```text -SQL> LIST - 1 SELECT empno, ename, job, sal, comm - 2 FROM emp - 3 WHERE deptno = 20 - 4* ORDER BY empno -SQL> 3 - 3* WHERE deptno = 20 -SQL> CHANGE /20/30/ - 3* WHERE deptno = 30 -SQL> LIST - 1 SELECT empno, ename, job, sal, comm - 2 FROM emp - 3 WHERE deptno = 30 - 4* ORDER BY empno -``` - -## CLEAR - -The `CLEAR` command removes the contents of the SQL buffer, deletes all column definitions set with the `COLUMN` command, or clears the screen. - -```text -CL[EAR ] [ BUFF[ER ] | SQL | COL[UMNS ] | SCR[EEN ] ] -``` - -`BUFFER | SQL` - - Clears the SQL buffer. - -`COLUMNS` - - Removes column definitions. - -`SCREEN` - - Clears the screen. This is the default if no options are specified. - -## COLUMN - -The `COLUMN` command controls output formatting. The formatting attributes set by using the `COLUMN` command remain in effect only for the duration of the current session. - -```text -COL[UMN ] - [ column - { CLE[AR ] | - { FOR[MAT ] spec | - HEA[DING ] text | - { OFF | ON } - } [...] - } - ] -``` - -If the `COLUMN` command is specified with no subsequent options, formatting options for current columns in effect for the session are displayed. - -If the `COLUMN` command is followed by a column name, then the column name may be followed by one of the following: - -1. No other options -2. `CLEAR` -3. Any combination of `FORMAT`, `HEADING`, and one of `OFF` or `ON` - -`column` - - Name of a column in a table to which subsequent column formatting options are to apply. If no other options follow `column`, then the current column formatting options if any, of `column` are displayed. - -`CLEAR` - - The `CLEAR` option reverts all formatting options back to their defaults for `column`. If the `CLEAR` option is specified, it must be the only option specified. - -`spec` - - Format specification to be applied to `column`. For character columns, `spec` takes the following format: - -`n` - - `n` is a positive integer that specifies the column width in characters within which to display the data. Data in excess of `n` will wrap around with the specified column width. - - For numeric columns, `spec` is comprised of the following elements. - -| Element | Description | -| ------- | ------------------------------------------ | -| `$` | Display a leading dollar sign. | -| `,` | Display a comma in the indicated position. | -| `.` | Marks the location of the decimal point. | -| `0` | Display leading zeros. | -| `9` | Number of significant digits to display. | - - If loss of significant digits occurs due to overflow of the format, then all #’s are displayed. - -`text` - - Text to be used for the column heading of `column`. - -`OFF | ON` - - If `OFF` is specified, formatting options are reverted back to their defaults, but are still available within the session. If `ON` is specified, the formatting options specified by previous `COLUMN` commands for `column` within the session are re-activated. - -The following example shows the effect of changing the display width of the `job` column. - -```text -SQL> SET PAGESIZE 9999 -SQL> COLUMN job FORMAT A5 -SQL> COLUMN job -COLUMN JOB ON -FORMAT A5 -wrapped -SQL> SELECT empno, ename, job FROM emp; - -EMPNO ENAME JOB ------ ---------- ----- - 7369 SMITH CLERK - 7499 ALLEN SALES - MAN - - 7521 WARD SALES - MAN - - 7566 JONES MANAG - ER - - 7654 MARTIN SALES - MAN - - 7698 BLAKE MANAG - ER - - 7782 CLARK MANAG - ER - - 7788 SCOTT ANALY - ST - - 7839 KING PRESI - DENT - - 7844 TURNER SALES - MAN - - 7876 ADAMS CLERK - 7900 JAMES CLERK - 7902 FORD ANALY - ST - - 7934 MILLER CLERK - -14 rows retrieved. -``` - -The following example applies a format to the `sal` column. - -```text -SQL> COLUMN sal FORMAT $99,999.00 -SQL> COLUMN -COLUMN JOB ON -FORMAT A5 -wrapped - -COLUMN SAL ON -FORMAT $99,999.00 -wrapped -SQL> SELECT empno, ename, job, sal FROM emp; - -EMPNO ENAME JOB SAL ------ ---------- ----- ----------- - 7369 SMITH CLERK $800.00 - 7499 ALLEN SALES $1,600.00 - MAN - - 7521 WARD SALES $1,250.00 - MAN - - 7566 JONES MANAG $2,975.00 - ER - - 7654 MARTIN SALES $1,250.00 - MAN - - 7698 BLAKE MANAG $2,850.00 - ER - - 7782 CLARK MANAG $2,450.00 - ER - - 7788 SCOTT ANALY $3,000.00 - ST - - 7839 KING PRESI $5,000.00 - DENT - - 7844 TURNER SALES $1,500.00 - MAN - - 7876 ADAMS CLERK $1,100.00 - 7900 JAMES CLERK $950.00 - 7902 FORD ANALY $3,000.00 - ST - - 7934 MILLER CLERK $1,300.00 - -14 rows retrieved. -``` - -## CONNECT - -Change the database connection to a different user and/or connect to a different database. There must be no white space between any of the parameters following the `CONNECT` command. - -```text -CON[NECT] [/][@{ | } ] -``` - -Where: - - `username` is a database username with which to connect to the database. - - `password` is the password associated with the specified `username`. If a `password` is not provided, but a password is required for authentication, a search is made for a password file, first in the home directory of the Linux operating system account invoking EDB\*Plus (or in the `%APPDATA%\postgresql\` directory for Windows) and then at the location specified by the `PGPASSFILE` environment variable. The password file is `.pgpass` on Linux hosts and `pgpass.conf` on Windows hosts. The following is an example on a Windows host: - -```text -C:\Users\Administrator\AppData\Roaming\postgresql\pgpass.conf -``` - - If a password file cannot be located, or it does not have an entry matching the EDB\*Plus connection parameters, then EDB\*Plus will prompt for the password. For more information about password files, see the PostgreSQL core documentation at: - - - -!!! Note - When a password is not required, EDB\*Plus does not prompt for a password such as when the `trust` authentication method is specified in the `pg_hba.conf` file. - -For more information about the `pg_hba.conf` file and authentication methods, see the PostgreSQL core documentation at - - `connectstring` is the database connection string. See [Using EDB\*Plus](04_using_edb_plus/#using_edb_plus) for further information on the database connection string. - - `variable` is a variable defined in the `login.sql` file that contains a database connection string. The `login.sql` file can be found in the `edbplus` subdirectory of the Advanced Server home directory. - -In the following example, the database connection is changed to database `edb` on the localhost at port `5445` with username `smith`. - -```text -SQL> CONNECT smith/mypassword@localhost:5445/edb -Disconnected from EnterpriseDB Database. -Connected to EnterpriseDB 10.0.1 (localhost:5445/edb) AS smith -``` - -From within the session shown above, the connection is changed to username `enterprisedb`. Also note that the host defaults to the localhost, the port defaults to `5444` (which is not the same as the port previously used), and the database defaults to `edb`. - -```text -SQL> CONNECT enterprisedb/password -Disconnected from EnterpriseDB Database. -Connected to EnterpriseDB 10.0.1 (localhost:5444/edb) AS enterprisedb -``` - -## DEFINE - -The `DEFINE` command creates or replaces the value of a *user variable* (also called a *substitution variable*). - -```text -DEF[INE ] [ variable [ = text ] ] -``` - -If the `DEFINE` command is given without any parameters, all current variables and their values are displayed. - -If `DEFINE variable` is given, only `variable` is displayed with its value. - -`DEFINE variable = text` assigns `text` to `variable.text` may be optionally enclosed within single or double quotation marks. Quotation marks must be used if `text` contains space characters. - -The following example defines two variables, `dept` and `name`. - -```text -SQL> DEFINE dept = 20 -SQL> DEFINE name = 'John Smith' -SQL> DEFINE -DEFINE EDB = "localhost:5445/edb" -DEFINE DEPT = "20" -DEFINE NAME = "John Smith" -``` - -!!! Note - The variable `EDB` is read from the `login.sql` file located in the `edbplus` subdirectory of the Advanced Server home directory. - -## DEL - -`DEL` is a line editor command that deletes one or more lines from the SQL buffer. - -```text -DEL [ n | n m | n * | n L[AST ] | * | * n | * L[AST ] | L[AST ] ] -``` - -The parameters specify which lines are to be deleted from the SQL buffer. Two parameters specify the start and end of a range of lines to be deleted. If the `DEL` command is given with no parameters, the current line is deleted. - -`n` - - n is an integer representing the `n`th line - -`n m` - - `n` and `m` are integers where `m` is greater than `n` representing the `n`th through the `m`th lines - -`*` - - Current line - -`LAST` - - Last line - -In the following example, the fifth and sixth lines containing columns `sal` and `comm`, respectively, are deleted from the `SELECT` command in the SQL buffer. - -```text -SQL> LIST - 1 SELECT - 2 empno - 3 ,ename - 4 ,job - 5 ,sal - 6 ,comm - 7 ,deptno - 8* FROM emp -SQL> DEL 5 6 -SQL> LIST - 1 SELECT - 2 empno - 3 ,ename - 4 ,job - 5 ,deptno - 6* FROM emp -``` - -## DESCRIBE - -The `DESCRIBE` command displays: - -- A list of columns, column data types, and column lengths for a table or view -- A list of parameters for a procedure or function -- A list of procedures and functions and their respective parameters for a package - -The `DESCRIBE` command will also display the structure of the database object referred to by a synonym. The syntax is: - -```text -DESC[RIBE] [ schema.]object -``` - -`schema` - - Name of the schema containing the object to be described. - -`object` - - Name of the table, view, procedure, function, or package to be displayed, or the synonym of an object. - -## DISCONNECT - -The `DISCONNECT` command closes the current database connection, but does not terminate EDB\*Plus. - -```text -DISC[ONNECT ] -``` - -## EDIT - -The `EDIT` command invokes an external editor to edit the contents of an operating system file or the SQL buffer. - -```text -ED[IT ] [ filename[.ext ] ] -``` - -`filename[.ext ]` - - `filename` is the name of the file to open with an external editor. `ext` is the filename extension. If the filename extension is `sql`, then the `.sql` extension may be omitted when specifying `filename`. `EDIT` always assumes a `.sql` extension on filenames that are specified with no extension. If the filename parameter is omitted from the `EDIT` command, the contents of the SQL buffer are brought into the editor. - -## EXECUTE - -The `EXECUTE` command executes an SPL procedure from EDB\*Plus. - -```text -EXEC[UTE ] spl_procedure [ ([ parameters ]) ] -``` - -`spl_procedure` - - The name of the SPL procedure to be executed. - -`parameters` - - Comma-delimited list of parameters. If there are no parameters, then a pair of empty parentheses may optionally be specified. - -## EXIT - -The `EXIT` command terminates the EDB\*Plus session and returns control to the operating system. `QUIT` is a synonym for `EXIT`. Specifying no parameters is equivalent to `EXIT SUCCESS COMMIT`. - -```text -{ EXIT | QUIT } -[ SUCCESS | FAILURE | WARNING | value | variable ] -[ COMMIT | ROLLBACK ]SUCCESS | FAILURE |WARNING] -``` - -Returns an operating system dependent return code indicating successful operation, failure, or warning for `SUCCESS, FAILURE`, and `WARNING`, respectively. The default is `SUCCESS`. - -`value` - - An integer value that is returned as the return code. - -`variable` - - A variable created with the `DEFINE` command whose value is returned as the return code. - -`COMMIT | ROLLBACK` - - If `COMMIT` is specified, uncommitted updates are committed upon exit. If `ROLLBACK` is specified, uncommitted updates are rolled back upon exit. The default is `COMMIT`. - -## GET - -The `GET` command loads the contents of the given file to the SQL buffer. - -```text -GET filename[.ext ] [ LIS[T ] | NOL[IST ] ] -``` - -`filename[.ext ]` - - `filename` is the name of the file to load into the SQL buffer. `ext` is the filename extension. If the filename extension is `sql`, then the `.sql` extension may be omitted when specifying `filename`. `GET` always assumes a `.sql` extension on filenames that are specified with no extension. - -`LIST | NOLIST` - - If `LIST` is specified, the content of the SQL buffer is displayed after the file is loaded. If `NOLIST` is specified, no listing is displayed. The default is `LIST`. - -## HELP - -The `HELP` command obtains an index of topics or help on a specific topic. The question mark `(?)` is synonymous with specifying `HELP`. - -```text -{ HELP | ? } { INDEX | topic } -``` - -`INDEX` - - Displays an index of available topics. - -`topic` - - The name of a specific topic – e.g., an EDB\*Plus command, for which help is desired. - -## HOST - -The `HOST` command executes an operating system command from EDB\*Plus. - -```text -HO[ST ] [os_command] -``` - -`os_command` - - The operating system command to be executed. If you do not provide an operating system command, EDB\*Plus pauses execution and opens a new shell prompt. When the shell exits, EDB\*Plus resumes execution. - -## INPUT - -The `INPUT` line editor command adds a line of text to the SQL buffer after the current line. - -```text -I[NPUT ] text -``` - -The following sequence of `INPUT` commands constructs a `SELECT` command. - -```text -SQL> INPUT SELECT empno, ename, job, sal, comm -SQL> INPUT FROM emp -SQL> INPUT WHERE deptno = 20 -SQL> INPUT ORDER BY empno -SQL> LIST - 1 SELECT empno, ename, job, sal, comm - 2 FROM emp - 3 WHERE deptno = 20 - 4* ORDER BY empno -``` - -## LIST - -`LIST` is a line editor command that displays the contents of the SQL buffer. - -```text -L[IST] [ n | n m | n * | n L[AST] | * | * n | * L[AST] | L[AST] ] -``` - -The buffer does not include a history of the EDB\*Plus commands. - -`n` - - `n` represents the buffer line number. - -`n m` - - `n m` displays a list of lines between `n` and `m`. - -`n *` - - `n *` displays a list of lines that range between line `n` and the current line. - -`n L[AST]` - - `n L[AST]` displays a list of lines that range from line `n` through the last line in the buffer. - -`*` - - `*` displays the current line. - -`* n` - - `* n` displays a list of lines that range from the current line through line `n`. - -`* L[AST]` - - `* L[AST]` displays a list of lines that range from the current line through the last line. - -`L[AST]` - - `L[AST]` displays the last line. - -## PASSWORD - -Use the `PASSWORD` command to change your database password. - -```text -PASSW[ORD] [user_name] -``` - -You must have sufficient privileges to use the `PASSWORD` command to change another user's password. The following example demonstrates using the `PASSWORD` command to change the password for a user named `acctg`: - -```text -SQL> PASSWORD acctg -Changing password for acctg - New password: - New password again: -Password successfully changed. -``` - -## PAUSE - -The `PAUSE` command displays a message, and waits for the user to press `ENTER`. - -```text -PAU[SE] [optional_text] -``` - -`optional_text` specifies the text that will be displayed to the user. If the `optional_text` is omitted, Advanced Server will display two blank lines. If you double quote the `optional_text` string, the quotes will be included in the output. - -## PROMPT - -The `PROMPT` command displays a message to the user before continuing. - -```text -PRO[MPT] [message_text] -``` - -`message_text` specifies the text displayed to the user. Double quote the string to include quotes in the output. - -## QUIT - -The `QUIT` command terminates the session and returns control to the operating system. `QUIT` is a synonym for `EXIT`. - -```text -QUIT - -[SUCCESS | FAILURE | WARNING | value | sub_variable] - -[COMMIT | ROLLBACK] -``` - -The default value is `QUIT SUCCESS COMMIT`. - -## REMARK - -Use `REMARK` to include comments in a script. - -```text -REM[ARK] [optional_text] -``` - -You may also use the following convention to include a comment: - -```text -/* - * This is an example of a three line comment. - */ -``` - -## SAVE - -Use the `SAVE` command to write the SQL Buffer to an operating system file. - -```text -SAV[E] file_name -[CRE[ATE] | REP[LACE] | APP[END]] -``` - -`file_name` - - `file_name` specifies the name of the file (including the path) where the buffer contents are written. If you do not provide a file extension, `.sql` is appended to the end of the file name. - -`CREATE` - - Include the `CREATE` keyword to create a new file. A new file is created *only* if a file with the specified name does not already exist. This is the default. - -`REPLACE` - - Include the `REPLACE` keyword to specify that Advanced Server should overwrite an existing file. - -`APPEND` - - Include the `APPEND` keyword to specify that Advanced Server should append the contents of the SQL buffer to the end of the specified file. - -The following example saves the contents of the SQL buffer to a file named `example.sql`, located in the `temp` directory: - -```text -SQL> SAVE C:\example.sql CREATE -File "example.sql" written. -``` - -## SET - -Use the `SET` command to specify a value for a session level variable that controls EDB\*Plus behavior. The following forms of the `SET` command are valid: - -**SET AUTOCOMMIT** - -Use the `SET AUTOCOMMIT` command to specify commit behavior for Advanced Server transactions. - -```text -SET AUTO[COMMIT] - -{ON | OFF | IMMEDIATE | statement_count} -``` - -Please note that EDB\*Plus always automatically commits DDL statements. - -`ON` - - Specify `ON` to turn `AUTOCOMMIT` behavior on. - -`OFF` - - Specify `OFF` to turn `AUTOCOMMIT` behavior off. - -`IMMEDIATE` - - `IMMEDIATE` has the same effect as `ON`. - -`statement_count` - - Include a value for `statement_count` to instruct EDB\*Plus to issue a commit after the specified count of successful SQL statements. - -**SET COLUMN SEPARATOR** - -Use the `SET COLUMN SEPARATOR` command to specify the text that Advanced Server displays between columns. - -```text -SET COLSEP column_separator -``` - -The default value of `column_separator` is a single space. - -**SET ECHO** - -Use the `SET ECHO` command to specify if SQL and EDB\*Plus script statements should be displayed onscreen as they are executed. - -```text -SET ECHO {ON | OFF} -``` - -The default value is `OFF`. - -**SET FEEDBACK** - -The `SET FEEDBACK` command controls the display of interactive information after a SQL statement executes. - -```text -SET FEED[BACK] {ON | OFF | row_threshold} -``` - -`row_threshold` - - Specify an integer value for `row_threshold`. Setting `row_threshold` to `0` is same as setting `FEEDBACK` to `OFF`. Setting `row_threshold` equal `1` effectively sets `FEEDBACK` to `ON`. - -**SET FLUSH** - -Use the `SET FLUSH` command to control display buffering. - -```text -SET FLU[SH] {ON | OFF} -``` - -Set `FLUSH` to `OFF` to enable display buffering. If you enable buffering, messages bound for the screen may not appear until the script completes. Please note that setting `FLUSH` to `OFF` will offer better performance. - -Set `FLUSH` to `ON` to disable display buffering. If you disable buffering, messages bound for the screen appear immediately. - -**SET HEADING** - -Use the `SET HEADING` variable to specify if Advanced Server should display column headings for `SELECT` statements. - -```text -SET HEA[DING] {ON | OFF} -``` - -**SET HEAD SEPARATOR** - -The `SET HEADSEP` command sets the new heading separator character used by the `COLUMN HEADING` command. The default is `'|'`. - -```text -SET HEADS[EP] -``` - -**SET LINESIZE** - -Use the `SET LINESIZE` command to specify the width of a line in characters. - -```text -SET LIN[ESIZE] width_of_line -``` - -`width_of_line` - - The default value of `width_of_line` is `132`. - -**SET NEWPAGE** - -Use the `SET NEWPAGE` command to specify how many blank lines are printed after a page break. - -```text -SET NEWP[AGE] lines_per_page -``` - -`lines_per_page` - - The default value of `lines_per_page` is `1`. - -**SET NULL** - -Use the `SET NULL` command to specify a string that is displayed to the user when a `NULL` column value is displayed in the output buffer. - -```text -SET NULL null_string -``` - -**SET PAGESIZE** - -Use the `SET PAGESIZE` command to specify the number of printed lines that fit on a page. - -```text -SET PAGES[IZE] line_count -``` - -Use the `line_count` parameter to specify the number of lines per page. - -**SET SQLCASE** - -The `SET SQLCASE` command specifies if SQL statements transmitted to the server should be converted to upper or lower case. - -```text -SET SQLC[ASE] {MIX[ED] | UP[PER] | LO[WER]} -``` - -`UPPER` - - Specify `UPPER` to convert the command text to uppercase. - -`LOWER` - - Specify `LOWER` to convert the command text to lowercase. - -`MIXED` - - Specify `MIXED` to leave the case of SQL commands unchanged. The default is `MIXED`. - -**SET PAUSE** - -The `SET PAUSE` command is most useful when included in a script; the command displays a prompt and waits for the user to press `Return`. - -```text -SET PAU[SE] {ON | OFF} -``` - -If `SET PAUSE` is `ON`, the message `Hit ENTER to continue…` will be displayed before each command is executed. - -**SET SPACE** - -Use the `SET SPACE` command to specify the number of spaces to display between columns: - -```text -SET SPACE number_of_spaces -``` - -**SET SQLPROMPT** - -Use `SET SQLPROMPT` to set a value for a user-interactive prompt: - -```text -SET SQLP[ROMPT] "prompt" -``` - -By default, `SQLPROMPT` is set to `"SQL> "` - -**SET TERMOUT** - -Use the `SET TERMOUT` command to specify if command output should be displayed onscreen. - -```text -SET TERM[OUT] {ON | OFF} -``` - -**SET TIMING** - -The `SET TIMING` command specifies if Advanced Server should display the execution time for each SQL statement after it is executed. - -```text -SET TIMI[NG] {ON | OFF} -``` - -**SET TRIMSPOOL** - -Use the `SET TRIMSPOOL` command to remove trailing spaces from each line in the output file specified by the `SPOOL` command. - -```text -SET TRIMS[POOL] {ON | OFF} -``` - -The default value is `OFF`. - -**SET VERIFY** - -Specifies if both the old and new values of a SQL statement are displayed when a substitution variable is encountered. - -```text -SET VER[IFY] { ON | OFF } -``` - -## SHOW - -Use the `SHOW` command to display current parameter values. - -```text -SHO[W] {ALL | parameter_name} -``` - -Display the current parameter settings by including the `ALL` keyword: - -```Text -SQL> SHOW ALL -autocommit OFF -colsep " " -define "&" -echo OFF -FEEDBACK ON for 6 row(s). -flush ON -heading ON -headsep "|" -linesize 78 -newpage 1 -null " " -pagesize 14 -pause OFF -serveroutput OFF -spool OFF -sqlcase MIXED -sqlprompt "SQL> " -sqlterminator ";" -suffix ".sql" -termout ON -timing OFF -verify ON -USER is "enterprisedb" -HOST is "localhost" -PORT is "5444" -DATABASE is "edb" -VERSION is "10.0.0" -``` - -Or display a specific parameter setting by including the `parameter_name` in the `SHOW` command: - -```text -SQL> SHOW VERSION -VERSION is "10.0.0" -``` - -## SPOOL - -The `SPOOL` command sends output from the display to a file. - -```text -SP[OOL] output_file | OFF -``` - -Use the `output_file` parameter to specify a path name for the output file. - -## START - -Use the `START` command to run an EDB\*Plus script file; `START` is an alias for `@` command. - -```text -STA[RT] script_file -``` - -Specify the name of a script file in the `script_file` parameter. - -## UNDEFINE - -The `UNDEFINE` command erases a user variable created by the `DEFINE` command. - -```text -UNDEF[INE] variable_name [ variable_name...] -``` - -Use the `variable_name` parameter to specify the name of a variable or variables. - -## WHENEVER SQLERROR - -The `WHENEVER SQLERROR` command provides error handling for SQL errors or PL/SQL block errors. The syntax is: - -```text -WHENEVER SQLERROR - {CONTINUE[COMMIT|ROLLBACK|NONE] - |EXIT[SUCCESS|FAILURE|WARNING|n|sub_variable] - [COMMIT|ROLLBACK]} -``` - -If Advanced Server encounters an error during the execution of a SQL command or PL/SQL block, EDB\*Plus performs the action specified in the `WHENEVER SQLERROR` command: - - Include the `CONTINUE` clause to instruct EDB\*Plus to perform the specified action before continuing. - - Include the `COMMIT` clause to instruct EDB\*Plus to `COMMIT` the current transaction before exiting or continuing. - - Include the `ROLLBACK` clause to instruct EDB\*Plus to `ROLLBACK` the current transaction before exiting or continuing. - - Include the `NONE` clause to instruct EDB\*Plus to continue without committing or rolling back the transaction. - - Include the `EXIT` clause to instruct EDB\*Plus to perform the specified action and exit if it encounters an error. - - Use the following options to specify a status code that EDB\*Plus will return before exiting: - -```text -[SUCCESS|FAILURE|WARNING|n|sub_variable] -``` - - Please note that EDB\*Plus supports substitution variables, but does not support bind variables. diff --git a/product_docs/docs/edb_plus/36/edbplus_rel_notes/edbplus3600_rel_notes.mdx b/product_docs/docs/edb_plus/36/edbplus_rel_notes/edbplus3600_rel_notes.mdx deleted file mode 100644 index 710c915828d..00000000000 --- a/product_docs/docs/edb_plus/36/edbplus_rel_notes/edbplus3600_rel_notes.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Version 36.0.0" ---- - - -New features, enhancements, bug fixes, and other changes in EDB*Plus 36.0.0 include: - -| Type | Description | -| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| Enhancement | Support for EDB Postgres Advanced Server 10.0.0 | -| Enhancement | EDB Postgres Advanced Server support of Internet Protocol version 6 (IPv6) to log into EDB\*Plus. | -| Enhancement | EDB Postgres Advanced Server support of a Secure Sockets Layer (SSL) connection from EDB\*Plus to the EDB Postgres Advanced Server database. | \ No newline at end of file diff --git a/product_docs/docs/edb_plus/36/edbplus_rel_notes/edbplus3602_rel_notes.mdx b/product_docs/docs/edb_plus/36/edbplus_rel_notes/edbplus3602_rel_notes.mdx deleted file mode 100644 index 54bb2dd8aac..00000000000 --- a/product_docs/docs/edb_plus/36/edbplus_rel_notes/edbplus3602_rel_notes.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Version 36.0.2" ---- - - -New features, enhancements, bug fixes, and other changes in EDB*Plus 36.0.2 include: - -| Type | Description | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Enhancement | The display format for a decimal point is now compatible with Oracle SQL*Plus [Support Ticket #75092]. | -| Security Fix | The EDB JDBC driver in EDB*Plus is upgraded to version 42.3.2.1. This upgrade fixes the CVE-2022-21724 vulnerability reported in older versions of the EDB JDBC driver. | -| Bug Fix | Describe command no linger fails for a schema qualified SYNONYM name [Support Ticket #72994]. | \ No newline at end of file diff --git a/product_docs/docs/edb_plus/36/edbplus_rel_notes/index.mdx b/product_docs/docs/edb_plus/36/edbplus_rel_notes/index.mdx deleted file mode 100644 index 40b7ba80e89..00000000000 --- a/product_docs/docs/edb_plus/36/edbplus_rel_notes/index.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "Release Notes" -navigation: -- edbplus3602_rel_notes -- edbplus3600_rel_notes ---- - -EDB\*Plus is a utility program that provides a command line user interface to EDB Postgres Advanced Server. - -The EDB\*Plus documentation describes the latest version of EDB\*Plus Version 36. The release notes in this section provide information on what was new in each release. - -| Version | Release Date | -| -------------------------------------- | ------------ | -| [36.0.2](edbplus3602_rel_notes.mdx) | 2022 Apr 04 | -| [36.0.0](edbplus3600_rel_notes.mdx) | 2018 Nov 28 | \ No newline at end of file diff --git a/product_docs/docs/edb_plus/36/images/advanced_server_installation_details.png b/product_docs/docs/edb_plus/36/images/advanced_server_installation_details.png deleted file mode 100755 index 3638e7d551f..00000000000 --- a/product_docs/docs/edb_plus/36/images/advanced_server_installation_details.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:a9c152dfd15132f11750917e10b0a8dd3646bfcf5f4d9a3525066f68ebd807d3 -size 19239 diff --git a/product_docs/docs/edb_plus/36/images/edb_plus_welcome_1.png b/product_docs/docs/edb_plus/36/images/edb_plus_welcome_1.png deleted file mode 100755 index ea2a26270ab..00000000000 --- a/product_docs/docs/edb_plus/36/images/edb_plus_welcome_1.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:2b1c56ab042cb3f2ea94a6fc8177bb9176fdd0bc42ca36e23c43594993dd6637 -size 34974 diff --git a/product_docs/docs/edb_plus/36/images/installation_complete.png b/product_docs/docs/edb_plus/36/images/installation_complete.png deleted file mode 100755 index 30281ba5583..00000000000 --- a/product_docs/docs/edb_plus/36/images/installation_complete.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:3836a996fa7052af22f4a23e24903594d4edf866c3e2696a6cbc0de8f1db4e03 -size 37674 diff --git a/product_docs/docs/edb_plus/36/images/installation_directory.png b/product_docs/docs/edb_plus/36/images/installation_directory.png deleted file mode 100755 index 0e4ab726341..00000000000 --- a/product_docs/docs/edb_plus/36/images/installation_directory.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:7c9a3d397f6c345f80a95362c407c1b72b0414c5934a8e8ef20d6c04a4980469 -size 71722 diff --git a/product_docs/docs/edb_plus/36/images/ready_to_install.png b/product_docs/docs/edb_plus/36/images/ready_to_install.png deleted file mode 100755 index a73f573adc5..00000000000 --- a/product_docs/docs/edb_plus/36/images/ready_to_install.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:ddd7dc4e8a4a8e40f9194e5f7971d3fc01c9c6130de1d3a62fc528a2a018c666 -size 15785 diff --git a/product_docs/docs/edb_plus/36/index.mdx b/product_docs/docs/edb_plus/36/index.mdx deleted file mode 100644 index 521faa990df..00000000000 --- a/product_docs/docs/edb_plus/36/index.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -navTitle: EDB*Plus -title: "EDB*Plus" - -directoryDefaults: - description: "EDB*Plus Documentation and release notes." -navigation: -- edbplus_rel_notes -- 03_installing_edb_plus ---- - -EDB\*Plus is a utility program that provides a command line user interface to EDB Postgres Advanced Server. EDB\*Plus accepts SQL commands, SPL anonymous blocks, and EDB\*Plus commands. - -EDB\*Plus commands are compatible with Oracle SQL\*Plus commands and provide various capabilities including: - -- Querying certain database objects -- Executing stored procedures -- Formatting output from SQL commands -- Executing batch scripts -- Executing OS commands -- Recording output \ No newline at end of file diff --git a/product_docs/docs/edb_plus/37/03_installing_edb_plus/01_installing_prereq.mdx b/product_docs/docs/edb_plus/37/03_installing_edb_plus/01_installing_prereq.mdx deleted file mode 100644 index 17a909cf117..00000000000 --- a/product_docs/docs/edb_plus/37/03_installing_edb_plus/01_installing_prereq.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "Installation Prerequisites" - ---- - - - -This table lists the EDB*Plus versions and their supported corresponding EDB Postgres Advanced Server (EPAS) versions. EDB\*Plus is supported on the same platforms as EDB Postgres Advanced Server. See [Product Compatibility](https://www.enterprisedb.com/platform-compatibility#epas) for details. - -| EDB*Plus | EPAS 14 | EPAS 13 | EPAS 12 | EPAS 11 | EPAS 10 | -| -------- | ------- | ------- | ------- | ------- | ------- | -| 37 | N | N | Y | Y | Y | -| 36 | N | N | N | Y | Y | - - -Before installing EDB\*Plus, you must first install Java (version 1.7 or later). On a Linux system, you can use the `yum` package manager to install Java. Open a terminal window, assume superuser privileges, and enter: - - ```text - # yum install java - ``` - -If you are using Windows, Java installers and instructions are available online at: - - - - -You must also have credentials that allow access to the EDB repository. For information about requesting credentials, visit: - - - - -After receiving your repository credentials: - -1. Create the repository configuration file. -2. Modify the file, providing your user name and password. -3. Install EDB\*Plus. - - - - - - diff --git a/product_docs/docs/edb_plus/37/03_installing_edb_plus/02_rpm_installation.mdx b/product_docs/docs/edb_plus/37/03_installing_edb_plus/02_rpm_installation.mdx deleted file mode 100644 index aa86c08aeea..00000000000 --- a/product_docs/docs/edb_plus/37/03_installing_edb_plus/02_rpm_installation.mdx +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: "Performing an RPM Installation" ---- - - - -For detailed information about creating and using EDB repositories to install Advanced Server or its supporting components, see the *EDB Postgres Advanced Server Installation Guide available* at: - - - -**Creating a Repository Configuration File** - -To create the repository configuration file, assume superuser privileges, and invoke the following command: - -- On RHEL or CentOS 7: - - ```text - yum -y install https://yum.enterprisedb.com/edbrepos/edb-repo-latest.noarch.rpm - ``` - -- On RHEL/Rocky Linux/AlmaLinux 8: - - ```text - dnf -y install https://yum.enterprisedb.com/edbrepos/edb-repo-latest.noarch.rpm - ``` - -The repository configuration file is named `edb.repo`. The file resides in `/etc/yum.repos.d`. After saving your changes to the configuration file, you can use the following command to install EDB*Plus: - -- On RHEL or CentOS 7: - - ``` - yum install edb-asxx-edbplus - ``` - -- On RHEL/Rocky Linux/AlmaLinux 8: - - ``` - dnf install edb-asxx-edbplus - ``` - -Where, `xx` is the Advanced Server version. - -When you install an RPM package that is signed by a source that is not recognized by your system, yum may ask for your permission to import the key to your local server. If prompted, and you are satisfied that the packages come from a trustworthy source, entery, and press `Return` to continue. - -During the installation, yum may encounter a dependency that it cannot resolve. If it does, it will provide a list of the required dependencies that you must manually resolve. - - -## Configuring an RPM Installation - -After performing an RPM installation of EDB\*Plus, you must set the values of environment variables that allow -EDB\*Plus to locate your Java installation. Use the following commands to set variable values: - -```text -export JAVA_HOME= -export PATH=/bin:$PATH -``` - -By default, the `pg_hba.conf` file for the RPM installer enforces `IDENT` authentication. Before invoking EDB*Plus, you must either modify the `pg_hba.conf` file, changing the authentication method to a form other than `IDENT` (and restarting the server), or perform the following steps to ensure that an `IDENT` server is accessible: - -You must confirm that an `identd` server is installed and running. You can use the `yum` package manager to install an `identd` server by invoking the command: - -- On RHEL or CentOS 7: - - ```text - yum install xinetd authd - ``` - -- On RHEL or CentOS 8: - - ```text - dnf install xinetd authd - ``` - -The command should create a file named ``/etc/xinetd.d/auth`` that contains: - -```text -service auth -{ - disable = yes - socket_type = stream -wait =no -user = ident -cps = 4096 10 -instances = UNLIMITED -server = /usr/sbin/in.authd server_args = -t60 --xerror -os -} -``` - -!!! Note - If the file includes a `-E` argument at the end of the server arguments, please erase `-E`. - -Then, to start the `identd` server, invoke the following commands: - -```text -systemctl enable xinetd -systemctl start xinetd -``` - -Open the `pg_ident.conf` file and create a user mapping: - -``` -# map_name system_username postgres_username - edbas enterprisedb enterprisedb -``` - -Where: - -- The name specified in the `map_name` column is a user-defined name that will identify the mapping in the `pg_hba.conf` file. -- The name specified in the `system_username` column is `enterprisedb`. -- The name specified in the `postgres_username` column is `enterprisedb`. - -Then, open the `pg_hba.conf` file and modify the `IDENT` entries: - -- If you are using an IPv4 local connection, modify the file entry to read: - - `host all all 127.0.0.0/0 ident map=edbas` - -- If you are using an IPv6 local connection, modify the file entry to read: - - `host all all ::1/128 ident map=edbas` - -You must restart the Advanced Server service before invoking EDB\*Plus. For detailed information about controlling the Advanced Server service, see the *EDB Postgres Advanced Server Installation Guide*, available at: - - - - - diff --git a/product_docs/docs/edb_plus/37/03_installing_edb_plus/03_using_gui.mdx b/product_docs/docs/edb_plus/37/03_installing_edb_plus/03_using_gui.mdx deleted file mode 100644 index 4c762b85740..00000000000 --- a/product_docs/docs/edb_plus/37/03_installing_edb_plus/03_using_gui.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "Using the Graphical Installer" ---- - - - -Graphical installers for EDB\*Plus are available via StackBuilder Plus; you can access StackBuilder Plus through your Windows or Linux start menu. After opening StackBuilder Plus and selecting the installation for which you wish to install EDB\*Plus, expand the component selection screen tree control to select and download the EDB\*Plus installer. - -![The EDB\*Plus Welcome window](../images/edb_plus_welcome_1.png) - -
Fig. 1: The EDB*Plus Welcome window
- - -The EDB\*Plus installer welcomes you to the setup wizard, as shown in the figure below. - -![The Installation Directory window](../images/installation_directory.png) - -
Fig. 2: The Installation Directory window
- - -Use the `Installation Directory` field to specify the directory in which you wish to install the EDB\*Plus software. Then, click `Next` to continue. - -![The Advanced Server Installation Details window](../images/advanced_server_installation_details.png) - -
Fig. 3: The Advanced Server Installation Details window
- - -Use fields on the `EDB Postgres Advanced Server Installation Details` window to identify the location of the Advanced Server host: - -- Use the `Host` field to identify the system on which Advanced Server resides. -- Use the `Port` field to identify the listener port that Advanced Server monitors for client connections. - -Then, click `Next` to continue. - -![The Ready to Install window](../images/ready_to_install.png) - -
Fig. 4: The Ready to Install window
- - -The `Ready to Install` window notifies you when the installer has all of the information needed to install EDB\*Plus on your system. Click `Next` to install EDB\*Plus. - -![The installation is complete](../images/installation_complete.png) - -
Fig. 5: The installation is complete
- - -The installer notifies you when the setup wizard has completed the EDB\*Plus installation. Click `Finish` to exit the installer. diff --git a/product_docs/docs/edb_plus/37/03_installing_edb_plus/index.mdx b/product_docs/docs/edb_plus/37/03_installing_edb_plus/index.mdx deleted file mode 100644 index 7930a6b3298..00000000000 --- a/product_docs/docs/edb_plus/37/03_installing_edb_plus/index.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Installing EDB*Plus" - ---- - -You can use an RPM installer or a graphical installer to add EDB*Plus to your Advanced Server installation. - -
- -installing_prereq rpm_installation using_gui - -
\ No newline at end of file diff --git a/product_docs/docs/edb_plus/37/04_using_edb_plus.mdx b/product_docs/docs/edb_plus/37/04_using_edb_plus.mdx deleted file mode 100644 index efb0e96065f..00000000000 --- a/product_docs/docs/edb_plus/37/04_using_edb_plus.mdx +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: "Using EDB*Plus" ---- - - - - - -To open an EDB\*Plus command line, navigate through the `Applications` or `Start` menu to the Advanced Server menu, to the `Run SQL Command Line` menu, and select the EDB\*Plus option. You can also invoke EDB\*Plus from the operating system command line with the following command: - -```text -edbplus [ -S[ILENT ] ] [ | /NOLOG ] [ @[. ] ] -``` - -`SILENT` - - If specified, the EDB\*Plus sign-on banner is suppressed along with all prompts. - -`login` - - Login information for connecting to the database server and database. `login` takes the following form; there must be no white space within the login information. - -```text -[/][@{ | } ] -``` - - Where: - - `username` is a database username with which to connect to the database. - - `password` is the password associated with the specified `username`. If a `password` is not provided, but a password is required for authentication, a password file is used if available. If there is no password file or no entry in the password file with the matching connection parameters, then EDB\*Plus will prompt for the password. - - `connectstring` is the database connection string with the following format: - -```text -[:][/][?ssl={true | false}] -``` - - Where: - -- `host` is the hostname or IP address on which the database server resides. If neither `@connectstring` nor `@variable` nor `/NOLOG` is specified, the default host is assumed to be the localhost. - -- `port` is the port number receiving connections on the database server. If not specified, the default is `5444`. - -- `dbname` is the name of the database to connect to. If not specified the default is `edb`. - -- If `Internet Protocol version 6` (IPv6) is used for the connection instead of IPv4, then the IP address must be enclosed within square brackets (that is, `[ipv6_address]`). The following is an example using an IPv6 connection: - -```text -edbplus.sh enterprisedb/password@[fe80::20c:29ff:fe7c:78b2]:5444/edb -``` - - The `pg_hba.conf` file for the database server must contain an appropriate entry for the IPv6 connection. The following example shows an entry that allows all addresses: - -```text -# TYPE DATABASE USER ADDRESS METHOD -host all all ::0/0 md5 -``` - -For more information about the `pg_hba.conf` file, see the PostgreSQL core documentation at: - - - - If an SSL connection is desired, then include the `?ssl=true` parameter in the connection string. In such a case, the connection string must minimally include `host:port`, with or without `/dbname`. If the `ssl` parameter is not specified, the default is `false`. See [Using a Secure Sockets Layer (SSL) Connection](05_using_edb_plus_with_ssl/#using_edb_plus_with_ssl) for instructions on setting up an SSL connection. - - `variable` is a variable defined in the `login.sql` file that contains a database connection string. The `login.sql` file can be found in the `edbplus` subdirectory of the Advanced Server home directory. - -`/NOLOG` - - Specify `/NOLOG` to start EDB\*Plus without establishing a database connection. SQL commands and EDB\*Plus commands that require a database connection cannot be used in this mode. The `CONNECT` command can be subsequently given to connect to a database after starting EDB\*Plus with the `/NOLOG` option. - -`scriptfile[.ext ]` - - `scriptfile` is the name of a file residing in the current working directory, containing SQL and/or EDB\*Plus commands that will be automatically executed after startup of EDB\*Plus. `ext` is the filename extension. If the filename extension is `sql`, then the `.sql` extension may be omitted when specifying `scriptfile`. When creating a script file, always name the file with an extension, otherwise it will not be accessible by EDB\*Plus. (EDB\*Plus will always assume a `.sql` extension on filenames that are specified with no extension.) - -!!! note - When you run the commands in the following examples you may be using a newer version of EDB\*Plus and as such the EDB\*Plus build number shown in your output may be different. - -The following example shows user `enterprisedb` with password `password`, connecting to database `edb` running on a database server on the `localhost` at port `5444`. - -```text -C:\Program Files\edb\as11\edbplus>edbplus enterprisedb/password -Connected to EnterpriseDB 11.1.7 (localhost:5444/edb) AS enterprisedb - -EDB*Plus: Release 11 (Build 37.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -The following example shows user `enterprisedb` with password, `password`, connecting to database `edb` running on a database server on the `localhost` at port `5445`. - -```text -C:\Program Files\edb\as11\edbplus>edbplus enterprisedb/password@localhost:5445/edb -Connected to EnterpriseDB 11.1.7 (localhost:5445/edb) AS enterprisedb - -EDB*Plus: Release 11 (Build 37.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -Using variable `hr_5445` in the `login.sql` file, the following illustrates how it is used to connect to database `hr` on localhost at port `5445`. - -```text -C:\Program Files\edb\as11\edbplus>edbplus enterprisedb/password@hr_5445 -Connected to EnterpriseDB 11.1.7 (localhost:5445/hr) AS enterprisedb - -EDB*Plus: Release 11 (Build 37.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -The following is the content of the `login.sql` file used in the previous example. - -```text -define edb="localhost:5445/edb" -define hr_5445="localhost:5445/hr" -``` - -The following example executes a script file, `dept_query.sql` after connecting to database `edb` on server localhost at port `5444`. - -```text -C:\Program Files\edb\as11\edbplus>edbplus enterprisedb/password @dept_query -Connected to EnterpriseDB 11.1.7 (localhost:5444/edb) AS enterprisedb - -SQL> SELECT * FROM dept; - -DEPTNO DNAME LOC ------- -------------- ------------- -10 ACCOUNTING NEW YORK -20 RESEARCH DALLAS -30 SALES CHICAGO -40 OPERATIONS BOSTON - -SQL> EXIT -Disconnected from EnterpriseDB Database. -``` - -The following is the content of file `dept_query.sql` used in the previous example. - -```text -SET PAGESIZE 9999 -SET ECHO ON -SELECT * FROM dept; -EXIT -``` diff --git a/product_docs/docs/edb_plus/37/05_using_edb_plus_with_ssl.mdx b/product_docs/docs/edb_plus/37/05_using_edb_plus_with_ssl.mdx deleted file mode 100644 index b0a39eef7ab..00000000000 --- a/product_docs/docs/edb_plus/37/05_using_edb_plus_with_ssl.mdx +++ /dev/null @@ -1,324 +0,0 @@ ---- -title: "Using a SSL Connection" ---- - - - - - -An EDB\*Plus connection to the Advanced Server database can be accomplished using secure sockets layer (SSL) connectivity. - -Using SSL requires various prerequisite configuration steps performed on the database server involved with the SSL connection as well as creation of the Java truststore and keystore on the host that will run EDB\*Plus. - -The Java *truststore* is the file containing the Certificate Authority (CA) certificates with which the Java client (EDB\*Plus) uses to verify the authenticity of the server to which it is initiating an SSL connection. - -The Java *keystore* is the file containing private and public keys and their corresponding certificates. The keystore is required for client authentication to the server, which is used for the EDB\*Plus connection. - -The following is material to which you can refer to for guidance in setting up the SSL connections: - -- For information on setting up SSL connectivity to the Advanced Server database, see the section about secure TCP connections with SSL in Chapter 18 “Server Setup and Operation” in the PostgreSQL Core Documentation located at: - - - -- For information on JDBC client connectivity using SSL, see the section on configuring the client in Chapter 4 “Using SSL” in The PostgreSQL JDBC Interface located at: - - - -The following sections provide information for the configuration steps of using SSL. - -- Configuring SSL on Advanced Server -- Configuring SSL for the EDB\*Plus client -- Requesting SSL connection to the Advanced Server database - -## Configuring SSL on Advanced Server - -This section provides an example of configuring SSL on a database server to demonstrate the use of SSL with EDB\*Plus. A self-signed certificate is used for this purpose. - -**Step 1:** Create the certificate signing request (CSR). - -In the following example the generated certificate signing request file is `server.csr`. The private key is generated as file `server.key`. - -```text -$ openssl req -new -nodes -text -out server.csr \ -> -keyout server.key -subj "/CN=enterprisedb" -Generating a 2048 bit RSA private key -.............................+++ -....................................................................+++ -writing new private key to 'server.key' ------ -``` - -!!! Note - When creating the certificate, the value specified for the common name field (designated as `CN=enterprisedb` in this example) must be the database user name that is specified when connecting to EDB\*Plus. - -In addition, user name maps can be used as defined in the `pg_ident.conf` file to permit more flexibility for the common name and database user name. Steps 8 and 9 describe the use of user name `maps`. - -**Step 2:** Generate the self-signed certificate. - -The following generates a self-signed certificate to file `server.crt` using the certificate signing request file, `server.csr`, and the private key, `server.key`, as input. - -```text -$ openssl x509 -req -days 365 -in server.csr -signkey server.key \ -> -out server.crt -Signature ok -subject=/CN=enterprisedb -Getting Private key -``` - -**Step 3:** Make a copy of the server certificate (`server.crt`) to be used as the root Certificate Authority (CA) file (`root.crt`). - -```text -$ cp server.crt root.crt -``` - -**Step 4:** Delete the now redundant certificate signing request (`server.csr`). - -```text -$ rm -f server.csr -``` - -**Step 5:** Move or copy the certificate and private key files to the Advanced Server data directory (for example, `/opt/edb/as11/data`). - -```text -$ mv root.crt /opt/edb/as11/data -$ mv server.crt /opt/edb/as11/data -$ mv server.key /opt/edb/as11/data -``` - -**Step 6:** Set the file ownership and permissions on the certificate files and private key file. - -Set the ownership to the operating system account that owns the data sub-directory of the database server. Set the permissions so that no other groups or accounts other than the owner can access these files. - -```text -$ chown enterprisedb root.crt server.crt server.key -$ chgrp enterprisedb root.crt server.crt server.key -$ chmod 600 root.crt server.crt server.key -$ ls -l -total 152 - . - . - . --rw------- 1 enterprisedb enterprisedb 985 Aug 22 11:00 root.crt --rw------- 1 enterprisedb enterprisedb 985 Aug 22 10:59 server.crt --rw------- 1 enterprisedb enterprisedb 1704 Aug 22 10:58 server.key -``` - -**Step 7:** In the `postgresql.conf` file, make the following modifications. - -```text -ssl = on -ssl_cert_file = 'server.crt' -ssl_key_file = 'server.key' -ssl_ca_file = 'root.crt' -``` - -**Step 8:** Modify the `pg_hba.conf` file to enable SSL usage on the desired database to which EDB\*Plus is to make the SSL connection. - -In the `pg_hba.conf` file, the `hostssl` type indicates the entry is used to validate SSL connection attempts from the client (EDB\*Plus). - -The authentication method is set to cert with the option `clientcert=1` in order to require an SSL certificate from the client against which authentication is performed using the common name of the certificate (`enterprisedb` in this example). - -The `map=sslusers` option specifies that a mapping named `sslusers` defined in the `pg_ident.conf` file is to be used for authentication. This mapping allows a connection to the database if the common name from the certificate and the database user name attempting the connection match the `SYSTEM-USERNAME/PG-USERNAME` pair listed in the `pg_ident.conf` file. - -The following is an example of the settings in the `pg_hba.conf` file if the database `(edb)` must use SSL connections. - -```text -# TYPE DATABASE USER ADDRESS METHOD - -# "local" is for Unix domain socket connections only -local all all md5 -# IPv4 local connections: -hostssl edb all 192.168.2.0/24 cert clientcert=1 map=sslusers -``` - -**Step 9:** The following shows the user name maps in the `pg_ident.conf` file related to the `pg_hba.conf` file by the `map=sslusers` option. These user name maps permit you to specify database user names `edbuser`, `postgres`, or `enterprisedb` when connecting with EDB\*Plus. - -```text -# MAPNAME SYSTEM-USERNAME PG-USERNAME - sslusers enterprisedb edbuser - sslusers enterprisedb postgres - sslusers enterprisedb enterprisedb -``` - -**Step 10:** Restart the database server after you have made the changes to the configuration files. - -## Configuring SSL for the EDB\*Plus Client - -After you have configured SSL on the database server, the following steps provide an example of generating certificate and keystore files for EDB\*Plus (the JDBC client). - -**Step 1:** Using files `server.crt` and `server.key` located under the database server data sub-directory, create copies of these files and move them to the host where EDB\*Plus is to be running. - -Store these files in the desired directory to contain the trusted certificate and keystore files to be generated in the following steps. The suggested location is to create a `.postgresql` sub-directory under the home user account that will invoke EDB\*Plus. Thus, these files will be under the `~/.postgresql` directory of the user account that will run EDB\*Plus. - -For this example, assume file `edb.crt` is a copy of `server.crt` and `edb.key` is a copy of `server.key`. - -**Step 2:** Create an additional copy of `edb.crt`. - -```text -$ cp edb.crt edb_root.crt -$ ls -l -total 12 --rw-r--r-- 1 user user 985 Aug 22 14:17 edb.crt --rw-r--r-- 1 user user 1704 Aug 22 14:18 edb.key --rw-r--r-- 1 user user 985 Aug 22 14:19 edb_root.crt -``` - -**Step 3:** Create a Distinguished Encoding Rules (DER) format of file `edb_root.crt`. The generated DER format of this file is `edb_root.crt.der`. The DER format of the file is required for the `keytool` program used in Step 4. - -```text -$ openssl x509 -in edb_root.crt -out edb_root.crt.der -outform der -$ ls -l -total 16 --rw-r--r-- 1 user user 985 Aug 22 14:17 edb.crt --rw-r--r-- 1 user user 1704 Aug 22 14:18 edb.key --rw-r--r-- 1 user user 985 Aug 22 14:19 edb_root.crt --rw-rw-r-- 1 user user 686 Aug 22 14:21 edb_root.crt.der -``` - -**Step 4:** Use the `keytool` program to create a keystore file `(postgresql.keystore)` using `edb_root.crt.der` as the input. This process adds the certificate of the Postgres database server to the keystore file. - -!!! Note - The file name `postgresql.keystore` is recommended so that it can be accessed in its default directory location `~/.postgresql postgresql.keystore`, which is under the home directory of the user account invoking EDB\*Plus. Also note that the file name suffix can be `.jks` instead of `.keystore` (thus, file name `postgresql.jks`). However, in the remainder of these examples, file name `postgresql.keystore` is used. - -**For Windows only:** The path is `%APPDATA%\.postgresql\postgresql.keystore` - -The `keytool` program can be found under the `bin` subdirectory of the Java Runtime Environment installation. - -You will be prompted for a new password. Save this password as it must be specified with the PGSSLCERTPASS environment variable. - -```text -$ /usr/java/jdk1.8.0_131/jre/bin/keytool -keystore postgresql.keystore \ -> -alias postgresqlstore -import -file edb_root.crt.der -Enter keystore password: -Re-enter new password: -Owner: CN=enterprisedb -Issuer: CN=enterprisedb -Serial number: c60f40256b0e8d53 -Valid from: Tue Aug 22 10:59:25 EDT 2017 until: Wed Aug 22 10:59:25 EDT 2018 -Certificate fingerprints: - MD5: 85:0B:E9:A7:6E:4F:7C:B0:9B:D6:3A:44:55:E2:E9:8E - SHA1: DD:A6:71:24:0B:6C:F8:BC:7A:4C:89:9B:DC:22:6A:6C:B0:F5:3F:7C - SHA256: -DC:02:64:E2:B0:E9:6F:1C:FC:4F:AE:E6:18:85:0B:79:57:43:C3:C5:AE:43:0D:37 -:49:53:6D:11:69:06:46:48 - Signature algorithm name: SHA1withRSA - Version: 1 -Trust this certificate? [no]: yes -Certificate was added to keystore -``` - -**Step 5:** Create a `PKCS #12` format of the keystore file `(postgresql.p12)` using files `edb.crt` and `edb.key` as input. - -!!! Note - The file name `postgresql.p12` is recommended so that it can be accessed in its default directory location `~/.postgresql/postgresql.p12`, which is under the home directory of the user account invoking EDB\*Plus. - -**For Windows only:** The path is `%APPDATA%\.postgresql\postgresql.p12` - -You will be prompted for a new password. Save this password as it must be specified with the PGSSLKEYPASS environment variable. - -```text -$ openssl pkcs12 -export -in edb.crt -inkey edb.key -out postgresql.p12 -Enter Export Password: -Verifying - Enter Export Password: -$ ls –l -total 24 --rw-rw-r-- 1 user user 985 Aug 24 12:18 edb.crt --rw-rw-r-- 1 user user 1704 Aug 24 12:18 edb.key --rw-rw-r-- 1 user user 985 Aug 24 12:20 edb_root.crt --rw-rw-r-- 1 user user 686 Aug 24 12:20 edb_root.crt.der --rw-rw-r-- 1 user user 758 Aug 24 12:26 postgresql.keystore --rw-rw-r-- 1 user user 2285 Aug 24 12:28 postgresql.p12 -``` - -**Step 6:** If the `postgresql.keystore` and `postgresql.p12` files are not already in the `~/.postgresql` directory, move or copy them to that location. - -**For Windows only:** The directory is `%APPDATA%\.postgresql` - -**Step 7:** If the default location `~/.postgresql` is not used, then the full path (including the file name) to the `postgresql.keystore` file must be set with the `PGSSLCERT` environment variable, and the full path (including the file name) to file `postgresql.p12` must be set with the `PGSSLKEY` environment variable before invoking EDB\*Plus. - -In addition, if the generated file from Step 4 was not named `postgresql.keystore` or `postgresql.jks` then, use the `PGSSLCERT` environment variable to designate the file name and its location. Similarly, if the generated file from Step 5 was not named `postgresql.p12` then, use the `PGSSLKEY` environment variable to designate the file name and its location. - -## Requesting an SSL Connection between EDB\*Plus and the Advanced Server Database - -Be sure the following topics have been addressed in order to perform an SSL connection: - -- The trusted certificate and keystore files have been generated for both the database server and the client host to be invoking EDB\*Plus. -- The `postgresql.conf` file for the database server contains the updated configuration parameters. -- The `pg_hba.conf` file for the database server contains the required entry for permitting the SSL connection. -- For the client host, either the client’s certificate and keystore files have been placed in the user account’s `~/.postgresql` directory or the environment variables `PGSSLCERT` and `PGSSLKEY` are set before invoking EDB\*Plus. -- The `PGSSLCERTPASS` environment variable is set with a password. -- The `PGSSLKEYPASS` environment variable is set with a password - -When invoking EDB\*Plus, include the `?ssl=true` parameter in the database connection string as shown for the `connectstring` option in [Using EDB\*Plus](04_using_edb_plus/#using_edb_plus). - -The following is an example where EDB\*Plus is invoked from a host that is remote to the database server. - -The `postgresql.conf` file of the database server contains the following modified parameters: - -```text -ssl = on -ssl_cert_file = 'server.crt' -ssl_key_file = 'server.key' -ssl_ca_file = 'root.crt' -``` - -The `pg_hba.conf` file of the database server contains the following entry for connecting from EDB\*Plus on the remote host: - -```text -# TYPE DATABASE USER ADDRESS METHOD - -# "local" is for Unix domain socket connections only -local all all md5 -# IPv4 local connections: -hostssl edb all 192.168.2.24/32 cert clientcert=1 -``` - -On the remote host where EDB\*Plus is to be invoked, the Linux user account named `user` contains the certificate and keystore files in its `~/.postgresql` directory: - -```text -[user@localhost ~]$ whoami -user -[user@localhost ~]$ cd .postgresql -[user@localhost .postgresql]$ pwd -/home/user/.postgresql -[user@localhost .postgresql]$ ls -l -total 8 --rw-rw-r-- 1 user user 758 Aug 24 12:37 postgresql.keystore --rw-rw-r-- 1 user user 2285 Aug 24 12:37 postgresql.p12 -``` - -Logged into Linux with the account named `user`, EDB\*Plus is successfully invoked with the `ssl=true` parameter: - -```text -$ export PGSSLCERTPASS=keypass -$ export PGSSLKEYPASS=exppass -$ cd /opt/edb/as11/edbplus -$ ./edbplus.sh enterprisedb/password@192.168.2.22:5444/edb?ssl=true -Connected to EnterpriseDB 11.0.1 (192.168.2.22:5444/edb) AS enterprisedb - -EDB*Plus: Release 11 (Build 37.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -Alternatively, without placing the certificate and keystore files in `~/.postgresql`, but in a different directory, EDB\*Plus can be invoked in the following manner: - -```text -$ export PGSSLCERT=/home/user/ssl/postgresql.keystore -$ export PGSSLKEY=/home/user/ssl/postgresql.p12 -$ export PGSSLCERTPASS=keypass -$ export PGSSLKEYPASS=exppass -$ cd /opt/edb/as11/edbplus -$ ./edbplus.sh enterprisedb/password@192.168.2.22:5444/edb?ssl=true -Connected to EnterpriseDB 11.0.1 (192.168.2.22:5444/edb) AS enterprisedb - -EDB*Plus: Release 11 (Build 37.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -Note that in both cases the database user name used to log into EDB\*Plus is `enterprisedb` as this is the user specified for the common name field when creating the certificate in Step 1 of [Configuring SSL on Advanced Server](#using_ssl_connection). - -Other database user names can be used if the `pg_hba.conf` file with the `map` option and the `pg_ident.conf` file are used. diff --git a/product_docs/docs/edb_plus/37/06_command_summary.mdx b/product_docs/docs/edb_plus/37/06_command_summary.mdx deleted file mode 100644 index 044bfc0ffbe..00000000000 --- a/product_docs/docs/edb_plus/37/06_command_summary.mdx +++ /dev/null @@ -1,997 +0,0 @@ ---- -title: "Command Summary" ---- - - - -The following sections contains a summary of EDB\*Plus commands. - -## ACCEPT - -The `ACCEPT` command displays a prompt and waits for the user’s keyboard input. The value input by the user is placed in the specified variable. - -```text -ACC[EPT ] variable -``` - -The following example creates a new variable named `my_name`, accepts a value of John Smith, then displays the value using the `DEFINE` command. - -```text -SQL> ACCEPT my_name -Enter value for my_name: John Smith -SQL> DEFINE my_name -DEFINE MY_NAME = "John Smith" -``` - -## APPEND - -`APPEND` is a line editor command that appends the given text to the end of the current line in the SQL buffer. - -```text -A[PPEND ] text -``` - -In the following example, a `SELECT` command is built-in the SQL buffer using the `APPEND` command. Note that two spaces are placed between the `APPEND` command and the `WHERE` clause in order to separate `dept` and `WHERE` by one space in the SQL buffer. - -```text -SQL> APPEND SELECT * FROM dept -SQL> LIST - 1 SELECT * FROM dept -SQL> APPEND WHERE deptno = 10 -SQL> LIST - 1 SELECT * FROM dept WHERE deptno = 10 -``` - -## CHANGE - -`CHANGE` is a line editor command performs a search-and-replace on the current line in the SQL buffer. - -```text -C[HANGE ] FROM [ TO ] -``` - -If `TO/` is specified, the first occurrence of text `FROM` in the current line is changed to text `TO`. If `TO/` is omitted, the first occurrence of text `FROM` in the current line is deleted. - -The following sequence of commands makes line 3 the current line, then changes the department number in the `WHERE` clause from 20 to 30. - -```text -SQL> LIST - 1 SELECT empno, ename, job, sal, comm - 2 FROM emp - 3 WHERE deptno = 20 - 4* ORDER BY empno -SQL> 3 - 3* WHERE deptno = 20 -SQL> CHANGE /20/30/ - 3* WHERE deptno = 30 -SQL> LIST - 1 SELECT empno, ename, job, sal, comm - 2 FROM emp - 3 WHERE deptno = 30 - 4* ORDER BY empno -``` - -## CLEAR - -The `CLEAR` command removes the contents of the SQL buffer, deletes all column definitions set with the `COLUMN` command, or clears the screen. - -```text -CL[EAR ] [ BUFF[ER ] | SQL | COL[UMNS ] | SCR[EEN ] ] -``` - -`BUFFER | SQL` - - Clears the SQL buffer. - -`COLUMNS` - - Removes column definitions. - -`SCREEN` - - Clears the screen. This is the default if no options are specified. - -## COLUMN - -The `COLUMN` command controls output formatting. The formatting attributes set by using the `COLUMN` command remain in effect only for the duration of the current session. - -```text -COL[UMN ] - [ column - { CLE[AR ] | - { FOR[MAT ] spec | - HEA[DING ] text | - { OFF | ON } - } [...] - } - ] -``` - -If the `COLUMN` command is specified with no subsequent options, formatting options for current columns in effect for the session are displayed. - -If the `COLUMN` command is followed by a column name, then the column name may be followed by one of the following: - -1. No other options -2. `CLEAR` -3. Any combination of `FORMAT`, `HEADING`, and one of `OFF` or `ON` - -`column` - - Name of a column in a table to which subsequent column formatting options are to apply. If no other options follow `column`, then the current column formatting options if any, of `column` are displayed. - -`CLEAR` - - The `CLEAR` option reverts all formatting options back to their defaults for `column`. If the `CLEAR` option is specified, it must be the only option specified. - -`spec` - - Format specification to be applied to `column`. For character columns, `spec` takes the following format: - -`n` - - `n` is a positive integer that specifies the column width in characters within which to display the data. Data in excess of `n` will wrap around with the specified column width. - - For numeric columns, `spec` is comprised of the following elements. - - Table - Numeric Column Format Elements - -| Element | Description | -| ------- | ------------------------------------------ | -| `$` | Display a leading dollar sign. | -| `,` | Display a comma in the indicated position. | -| `.` | Marks the location of the decimal point. | -| `0` | Display leading zeros. | -| `9` | Number of significant digits to display. | - - If loss of significant digits occurs due to overflow of the format, then all #’s are displayed. - -`text` - - Text to be used for the column heading of `column`. - -`OFF | ON` - - If `OFF` is specified, formatting options are reverted back to their defaults, but are still available within the session. If `ON` is specified, the formatting options specified by previous `COLUMN` commands for `column` within the session are re-activated. - -The following example shows the effect of changing the display width of the `job` column. - -```text -SQL> SET PAGESIZE 9999 -SQL> COLUMN job FORMAT A5 -SQL> COLUMN job -COLUMN JOB ON -FORMAT A5 -wrapped -SQL> SELECT empno, ename, job FROM emp; - -EMPNO ENAME JOB ------ ---------- ----- - 7369 SMITH CLERK - 7499 ALLEN SALES - MAN - - 7521 WARD SALES - MAN - - 7566 JONES MANAG - ER - - 7654 MARTIN SALES - MAN - - 7698 BLAKE MANAG - ER - - 7782 CLARK MANAG - ER - - 7788 SCOTT ANALY - ST - - 7839 KING PRESI - DENT - - 7844 TURNER SALES - MAN - - 7876 ADAMS CLERK - 7900 JAMES CLERK - 7902 FORD ANALY - ST - - 7934 MILLER CLERK - -14 rows retrieved. -``` - -The following example applies a format to the `sal` column. - -```text -SQL> COLUMN sal FORMAT $99,999.00 -SQL> COLUMN -COLUMN JOB ON -FORMAT A5 -wrapped - -COLUMN SAL ON -FORMAT $99,999.00 -wrapped -SQL> SELECT empno, ename, job, sal FROM emp; - -EMPNO ENAME JOB SAL ------ ---------- ----- ----------- - 7369 SMITH CLERK $800.00 - 7499 ALLEN SALES $1,600.00 - MAN - - 7521 WARD SALES $1,250.00 - MAN - - 7566 JONES MANAG $2,975.00 - ER - - 7654 MARTIN SALES $1,250.00 - MAN - - 7698 BLAKE MANAG $2,850.00 - ER - - 7782 CLARK MANAG $2,450.00 - ER - - 7788 SCOTT ANALY $3,000.00 - ST - - 7839 KING PRESI $5,000.00 - DENT - - 7844 TURNER SALES $1,500.00 - MAN - - 7876 ADAMS CLERK $1,100.00 - 7900 JAMES CLERK $950.00 - 7902 FORD ANALY $3,000.00 - ST - - 7934 MILLER CLERK $1,300.00 - -14 rows retrieved. -``` - -## CONNECT - -Change the database connection to a different user and/or connect to a different database. There must be no white space between any of the parameters following the `CONNECT` command. - -```text -CON[NECT] [/][@{ | } ] -``` - -Where: - - `username` is a database username with which to connect to the database. - - `password` is the password associated with the specified `username`. If a `password` is not provided, but a password is required for authentication, a search is made for a password file, first in the home directory of the Linux operating system account invoking EDB\*Plus (or in the `%APPDATA%\postgresql\` directory for Windows) and then at the location specified by the `PGPASSFILE` environment variable. The password file is `.pgpass` on Linux hosts and `pgpass.conf` on Windows hosts. The following is an example on a Windows host: - -```text -C:\Users\Administrator\AppData\Roaming\postgresql\pgpass.conf -``` - - If a password file cannot be located, or it does not have an entry matching the EDB\*Plus connection parameters, then EDB\*Plus will prompt for the password. For more information about password files, see the PostgreSQL core documentation at: - - - -!!! Note - When a password is not required, EDB\*Plus does not prompt for a password such as when the `trust` authentication method is specified in the `pg_hba.conf` file. - -For more information about the `pg_hba.conf` file and authentication methods, see the PostgreSQL core documentation at - - `connectstring` is the database connection string. See [Using EDB\*Plus](04_using_edb_plus/#using_edb_plus) for further information on the database connection string. - - `variable` is a variable defined in the `login.sql` file that contains a database connection string. The `login.sql` file can be found in the `edbplus` subdirectory of the Advanced Server home directory. - -In the following example, the database connection is changed to database `edb` on the localhost at port `5445` with username `smith`. - -```text -SQL> CONNECT smith/mypassword@localhost:5445/edb -Disconnected from EnterpriseDB Database. -Connected to EnterpriseDB 11.0.1 (localhost:5445/edb) AS smith -``` - -From within the session shown above, the connection is changed to username `enterprisedb`. Also note that the host defaults to the localhost, the port defaults to `5444` (which is not the same as the port previously used), and the database defaults to `edb`. - -```text -SQL> CONNECT enterprisedb/password -Disconnected from EnterpriseDB Database. -Connected to EnterpriseDB 11.0.1 (localhost:5444/edb) AS enterprisedb -``` - -## DEFINE - -The `DEFINE` command creates or replaces the value of a *user variable* (also called a *substitution variable*). - -```text -DEF[INE ] [ variable [ = text ] ] -``` - -If the `DEFINE` command is given without any parameters, all current variables and their values are displayed. - -If `DEFINE variable` is given, only `variable` is displayed with its value. - -`DEFINE variable = text` assigns `text` to `variable.text` may be optionally enclosed within single or double quotation marks. Quotation marks must be used if `text` contains space characters. - -The following example defines two variables, `dept` and `name`. - -```text -SQL> DEFINE dept = 20 -SQL> DEFINE name = 'John Smith' -SQL> DEFINE -DEFINE EDB = "localhost:5445/edb" -DEFINE DEPT = "20" -DEFINE NAME = "John Smith" -``` - -!!! Note - The variable `EDB` is read from the `login.sql` file located in the `edbplus` subdirectory of the Advanced Server home directory. - -## DEL - -`DEL` is a line editor command that deletes one or more lines from the SQL buffer. - -```text -DEL [ n | n m | n * | n L[AST ] | * | * n | * L[AST ] | L[AST ] ] -``` - -The parameters specify which lines are to be deleted from the SQL buffer. Two parameters specify the start and end of a range of lines to be deleted. If the `DEL` command is given with no parameters, the current line is deleted. - -`n` - - n is an integer representing the `n`th line - -`n m` - - `n` and `m` are integers where `m` is greater than `n` representing the `n`th through the `m`th lines - -`*` - - Current line - -`LAST` - - Last line - -In the following example, the fifth and sixth lines containing columns `sal` and `comm`, respectively, are deleted from the `SELECT` command in the SQL buffer. - -```text -SQL> LIST - 1 SELECT - 2 empno - 3 ,ename - 4 ,job - 5 ,sal - 6 ,comm - 7 ,deptno - 8* FROM emp -SQL> DEL 5 6 -SQL> LIST - 1 SELECT - 2 empno - 3 ,ename - 4 ,job - 5 ,deptno - 6* FROM emp -``` - -## DESCRIBE - -The `DESCRIBE` command displays: - -- A list of columns, column data types, and column lengths for a table or view -- A list of parameters for a procedure or function -- A list of procedures and functions and their respective parameters for a package - -The `DESCRIBE` command will also display the structure of the database object referred to by a synonym. The syntax is: - -```text -DESC[RIBE] [ schema.]object -``` - -`schema` - - Name of the schema containing the object to be described. - -`object` - - Name of the table, view, procedure, function, or package to be displayed, or the synonym of an object. - -## DISCONNECT - -The `DISCONNECT` command closes the current database connection, but does not terminate EDB\*Plus. - -```text -DISC[ONNECT ] -``` - -## EDIT - -The `EDIT` command invokes an external editor to edit the contents of an operating system file or the SQL buffer. - -```text -ED[IT ] [ filename[.ext ] ] -``` - -`filename[.ext ]` - - `filename` is the name of the file to open with an external editor. `ext` is the filename extension. If the filename extension is `sql`, then the `.sql` extension may be omitted when specifying `filename`. `EDIT` always assumes a `.sql` extension on filenames that are specified with no extension. If the filename parameter is omitted from the `EDIT` command, the contents of the SQL buffer are brought into the editor. - -## EXECUTE - -The `EXECUTE` command executes an SPL procedure from EDB\*Plus. - -```text -EXEC[UTE ] spl_procedure [ ([ parameters ]) ] -``` - -`spl_procedure` - - The name of the SPL procedure to be executed. - -`parameters` - - Comma-delimited list of parameters. If there are no parameters, then a pair of empty parentheses may optionally be specified. - -## EXIT - -The `EXIT` command terminates the EDB\*Plus session and returns control to the operating system. `QUIT` is a synonym for `EXIT`. Specifying no parameters is equivalent to `EXIT SUCCESS COMMIT`. - -```text -{ EXIT | QUIT } -[ SUCCESS | FAILURE | WARNING | value | variable ] -[ COMMIT | ROLLBACK ]SUCCESS | FAILURE |WARNING] -``` - -Returns an operating system dependent return code indicating successful operation, failure, or warning for `SUCCESS, FAILURE`, and `WARNING`, respectively. The default is `SUCCESS`. - -`value` - - An integer value that is returned as the return code. - -`variable` - - A variable created with the `DEFINE` command whose value is returned as the return code. - -`COMMIT | ROLLBACK` - - If `COMMIT` is specified, uncommitted updates are committed upon exit. If `ROLLBACK` is specified, uncommitted updates are rolled back upon exit. The default is `COMMIT`. - -## GET - -The `GET` command loads the contents of the given file to the SQL buffer. - -```text -GET filename[.ext ] [ LIS[T ] | NOL[IST ] ] -``` - -`filename[.ext ]` - - `filename` is the name of the file to load into the SQL buffer. `ext` is the filename extension. If the filename extension is `sql`, then the `.sql` extension may be omitted when specifying `filename`. `GET` always assumes a `.sql` extension on filenames that are specified with no extension. - -`LIST | NOLIST` - - If `LIST` is specified, the content of the SQL buffer is displayed after the file is loaded. If `NOLIST` is specified, no listing is displayed. The default is `LIST`. - -## HELP - -The `HELP` command obtains an index of topics or help on a specific topic. The question mark `(?)` is synonymous with specifying `HELP`. - -```text -{ HELP | ? } { INDEX | topic } -``` - -`INDEX` - - Displays an index of available topics. - -`topic` - - The name of a specific topic – e.g., an EDB\*Plus command, for which help is desired. - -## HOST - -The `HOST` command executes an operating system command from EDB\*Plus. - -```text -HO[ST ] [os_command] -``` - -`os_command` - - The operating system command to be executed. If you do not provide an operating system command, EDB\*Plus pauses execution and opens a new shell prompt. When the shell exits, EDB\*Plus resumes execution. - -## INPUT - -The `INPUT` line editor command adds a line of text to the SQL buffer after the current line. - -```text -I[NPUT ] text -``` - -The following sequence of `INPUT` commands constructs a `SELECT` command. - -```text -SQL> INPUT SELECT empno, ename, job, sal, comm -SQL> INPUT FROM emp -SQL> INPUT WHERE deptno = 20 -SQL> INPUT ORDER BY empno -SQL> LIST - 1 SELECT empno, ename, job, sal, comm - 2 FROM emp - 3 WHERE deptno = 20 - 4* ORDER BY empno -``` - -## LIST - -`LIST` is a line editor command that displays the contents of the SQL buffer. - -```text -L[IST] [ n | n m | n * | n L[AST] | * | * n | * L[AST] | L[AST] ] -``` - -The buffer does not include a history of the EDB\*Plus commands. - -`n` - - `n` represents the buffer line number. - -`n m` - - `n m` displays a list of lines between `n` and `m`. - -`n *` - - `n *` displays a list of lines that range between line `n` and the current line. - -`n L[AST]` - - `n L[AST]` displays a list of lines that range from line `n` through the last line in the buffer. - -`*` - - `*` displays the current line. - -`* n` - - `* n` displays a list of lines that range from the current line through line `n`. - -`* L[AST]` - - `* L[AST]` displays a list of lines that range from the current line through the last line. - -`L[AST]` - - `L[AST]` displays the last line. - -## PASSWORD - -Use the `PASSWORD` command to change your database password. - -```text -PASSW[ORD] [user_name] -``` - -You must have sufficient privileges to use the `PASSWORD` command to change another user's password. The following example demonstrates using the `PASSWORD` command to change the password for a user named `acctg`: - -```text -SQL> PASSWORD acctg -Changing password for acctg - New password: - New password again: -Password successfully changed. -``` - -## PAUSE - -The `PAUSE` command displays a message, and waits for the user to press `ENTER`. - -```text -PAU[SE] [optional_text] -``` - -`optional_text` specifies the text that will be displayed to the user. If the `optional_text` is omitted, Advanced Server will display two blank lines. If you double quote the `optional_text` string, the quotes will be included in the output. - -## PROMPT - -The `PROMPT` command displays a message to the user before continuing. - -```text -PRO[MPT] [message_text] -``` - -`message_text` specifies the text displayed to the user. Double quote the string to include quotes in the output. - -## QUIT - -The `QUIT` command terminates the session and returns control to the operating system. `QUIT` is a synonym for `EXIT`. - -```text -QUIT - -[SUCCESS | FAILURE | WARNING | value | sub_variable] - -[COMMIT | ROLLBACK] -``` - -The default value is `QUIT SUCCESS COMMIT`. - -## REMARK - -Use `REMARK` to include comments in a script. - -```text -REM[ARK] [optional_text] -``` - -You may also use the following convention to include a comment: - -```text -/* - * This is an example of a three line comment. - */ -``` - -## SAVE - -Use the `SAVE` command to write the SQL Buffer to an operating system file. - -```text -SAV[E] file_name -[CRE[ATE] | REP[LACE] | APP[END]] -``` - -`file_name` - - `file_name` specifies the name of the file (including the path) where the buffer contents are written. If you do not provide a file extension, `.sql` is appended to the end of the file name. - -`CREATE` - - Include the `CREATE` keyword to create a new file. A new file is created *only* if a file with the specified name does not already exist. This is the default. - -`REPLACE` - - Include the `REPLACE` keyword to specify that Advanced Server should overwrite an existing file. - -`APPEND` - - Include the `APPEND` keyword to specify that Advanced Server should append the contents of the SQL buffer to the end of the specified file. - -The following example saves the contents of the SQL buffer to a file named `example.sql`, located in the `temp` directory: - -```text -SQL> SAVE C:\example.sql CREATE -File "example.sql" written. -``` - -## SET - -Use the `SET` command to specify a value for a session level variable that controls EDB\*Plus behavior. The following forms of the `SET` command are valid: - -**SET AUTOCOMMIT** - -Use the `SET AUTOCOMMIT` command to specify commit behavior for Advanced Server transactions. - -```text -SET AUTO[COMMIT] - -{ON | OFF | IMMEDIATE | statement_count} -``` - -Please note that EDB\*Plus always automatically commits DDL statements. - -`ON` - - Specify `ON` to turn `AUTOCOMMIT` behavior on. - -`OFF` - - Specify `OFF` to turn `AUTOCOMMIT` behavior off. - -`IMMEDIATE` - - `IMMEDIATE` has the same effect as `ON`. - -`statement_count` - - Include a value for `statement_count` to instruct EDB\*Plus to issue a commit after the specified count of successful SQL statements. - -**SET COLUMN SEPARATOR** - -Use the `SET COLUMN SEPARATOR` command to specify the text that Advanced Server displays between columns. - -```text -SET COLSEP column_separator -``` - -The default value of `column_separator` is a single space. - -**SET ECHO** - -Use the `SET ECHO` command to specify if SQL and EDB\*Plus script statements should be displayed onscreen as they are executed. - -```text -SET ECHO {ON | OFF} -``` - -The default value is `OFF`. - -**SET FEEDBACK** - -The `SET FEEDBACK` command controls the display of interactive information after a SQL statement executes. - -```text -SET FEED[BACK] {ON | OFF | row_threshold} -``` - -`row_threshold` - - Specify an integer value for `row_threshold`. Setting `row_threshold` to `0` is same as setting `FEEDBACK` to `OFF`. Setting `row_threshold` equal `1` effectively sets `FEEDBACK` to `ON`. - -**SET FLUSH** - -Use the `SET FLUSH` command to control display buffering. - -```text -SET FLU[SH] {ON | OFF} -``` - -Set `FLUSH` to `OFF` to enable display buffering. If you enable buffering, messages bound for the screen may not appear until the script completes. Please note that setting `FLUSH` to `OFF` will offer better performance. - -Set `FLUSH` to `ON` to disable display buffering. If you disable buffering, messages bound for the screen appear immediately. - -**SET HEADING** - -Use the `SET HEADING` variable to specify if Advanced Server should display column headings for `SELECT` statements. - -```text -SET HEA[DING] {ON | OFF} -``` - -**SET HEAD SEPARATOR** - -The `SET HEADSEP` command sets the new heading separator character used by the `COLUMN HEADING` command. The default is `'|'`. - -```text -SET HEADS[EP] -``` - -**SET LINESIZE** - -Use the `SET LINESIZE` command to specify the width of a line in characters. - -```text -SET LIN[ESIZE] width_of_line -``` - -`width_of_line` - - The default value of `width_of_line` is `132`. - -**SET NEWPAGE** - -Use the `SET NEWPAGE` command to specify how many blank lines are printed after a page break. - -```text -SET NEWP[AGE] lines_per_page -``` - -`lines_per_page` - - The default value of `lines_per_page` is `1`. - -**SET NULL** - -Use the `SET NULL` command to specify a string that is displayed to the user when a `NULL` column value is displayed in the output buffer. - -```text -SET NULL null_string -``` - -**SET PAGESIZE** - -Use the `SET PAGESIZE` command to specify the number of printed lines that fit on a page. - -```text -SET PAGES[IZE] line_count -``` - -Use the `line_count` parameter to specify the number of lines per page. - -**SET SQLCASE** - -The `SET SQLCASE` command specifies if SQL statements transmitted to the server should be converted to upper or lower case. - -```text -SET SQLC[ASE] {MIX[ED] | UP[PER] | LO[WER]} -``` - -`UPPER` - - Specify `UPPER` to convert the command text to uppercase. - -`LOWER` - - Specify `LOWER` to convert the command text to lowercase. - -`MIXED` - - Specify `MIXED` to leave the case of SQL commands unchanged. The default is `MIXED`. - -**SET PAUSE** - -The `SET PAUSE` command is most useful when included in a script; the command displays a prompt and waits for the user to press `Return`. - -```text -SET PAU[SE] {ON | OFF} -``` - -If `SET PAUSE` is `ON`, the message `Hit ENTER to continue…` will be displayed before each command is executed. - -**SET SPACE** - -Use the `SET SPACE` command to specify the number of spaces to display between columns: - -```text -SET SPACE number_of_spaces -``` - -**SET SQLPROMPT** - -Use `SET SQLPROMPT` to set a value for a user-interactive prompt: - -```text -SET SQLP[ROMPT] "prompt" -``` - -By default, `SQLPROMPT` is set to `"SQL> "` - -**SET TERMOUT** - -Use the `SET TERMOUT` command to specify if command output should be displayed onscreen. - -```text -SET TERM[OUT] {ON | OFF} -``` - -**SET TIMING** - -The `SET TIMING` command specifies if Advanced Server should display the execution time for each SQL statement after it is executed. - -```text -SET TIMI[NG] {ON | OFF} -``` - -**SET TRIMSPOOL** - -Use the `SET TRIMSPOOL` command to remove trailing spaces from each line in the output file specified by the `SPOOL` command. - -```text -SET TRIMS[POOL] {ON | OFF} -``` - -The default value is `OFF`. - -**SET VERIFY** - -Specifies if both the old and new values of a SQL statement are displayed when a substitution variable is encountered. - -```text -SET VER[IFY] { ON | OFF } -``` - -## SHOW - -Use the `SHOW` command to display current parameter values. - -```text -SHO[W] {ALL | parameter_name} -``` - -Display the current parameter settings by including the `ALL` keyword: - -```Text -SQL> SHOW ALL -autocommit OFF -colsep " " -define "&" -echo OFF -FEEDBACK ON for 6 row(s). -flush ON -heading ON -headsep "|" -linesize 78 -newpage 1 -null " " -pagesize 14 -pause OFF -serveroutput OFF -spool OFF -sqlcase MIXED -sqlprompt "SQL> " -sqlterminator ";" -suffix ".sql" -termout ON -timing OFF -verify ON -USER is "enterprisedb" -HOST is "localhost" -PORT is "5444" -DATABASE is "edb" -VERSION is "11.0.0" -``` - -Or display a specific parameter setting by including the `parameter_name` in the `SHOW` command: - -```text -SQL> SHOW VERSION -VERSION is "11.0.0" -``` - -## SPOOL - -The `SPOOL` command sends output from the display to a file. - -```text -SP[OOL] output_file | OFF -``` - -Use the `output_file` parameter to specify a path name for the output file. - -## START - -Use the `START` command to run an EDB\*Plus script file; `START` is an alias for `@` command. - -```text -STA[RT] script_file -``` - -Specify the name of a script file in the `script_file` parameter. - -## UNDEFINE - -The `UNDEFINE` command erases a user variable created by the `DEFINE` command. - -```text -UNDEF[INE] variable_name [ variable_name...] -``` - -Use the `variable_name` parameter to specify the name of a variable or variables. - -## WHENEVER SQLERROR - -The `WHENEVER SQLERROR` command provides error handling for SQL errors or PL/SQL block errors. The syntax is: - -```text -WHENEVER SQLERROR - {CONTINUE[COMMIT|ROLLBACK|NONE] - |EXIT[SUCCESS|FAILURE|WARNING|n|sub_variable] - [COMMIT|ROLLBACK]} -``` - -If Advanced Server encounters an error during the execution of a SQL command or PL/SQL block, EDB\*Plus performs the action specified in the `WHENEVER SQLERROR` command: - - Include the `CONTINUE` clause to instruct EDB\*Plus to perform the specified action before continuing. - - Include the `COMMIT` clause to instruct EDB\*Plus to `COMMIT` the current transaction before exiting or continuing. - - Include the `ROLLBACK` clause to instruct EDB\*Plus to `ROLLBACK` the current transaction before exiting or continuing. - - Include the `NONE` clause to instruct EDB\*Plus to continue without committing or rolling back the transaction. - - Include the `EXIT` clause to instruct EDB\*Plus to perform the specified action and exit if it encounters an error. - - Use the following options to specify a status code that EDB\*Plus will return before exiting: - -```text -[SUCCESS|FAILURE|WARNING|n|sub_variable] -``` - - Please note that EDB\*Plus supports substitution variables, but does not support bind variables. diff --git a/product_docs/docs/edb_plus/37/edbplus_rel_notes/edbplus3700_rel_notes.mdx b/product_docs/docs/edb_plus/37/edbplus_rel_notes/edbplus3700_rel_notes.mdx deleted file mode 100644 index 60c3b7bcffa..00000000000 --- a/product_docs/docs/edb_plus/37/edbplus_rel_notes/edbplus3700_rel_notes.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Version 37.0.0" ---- - - -New features, enhancements, bug fixes, and other changes in EDB*Plus 37.0.0 include: - -| Type | Description | -| ----------- | -------------------------------------------------------------- | -| Enhancement | Support for EDB Postgres Advanced Server 11.1.7. | \ No newline at end of file diff --git a/product_docs/docs/edb_plus/37/edbplus_rel_notes/edbplus3701_rel_notes.mdx b/product_docs/docs/edb_plus/37/edbplus_rel_notes/edbplus3701_rel_notes.mdx deleted file mode 100644 index 50d935bf51a..00000000000 --- a/product_docs/docs/edb_plus/37/edbplus_rel_notes/edbplus3701_rel_notes.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Version 37.0.1" ---- - - -New features, enhancements, bug fixes, and other changes in EDB*Plus 37.0.1 include: - -| Type | Description | -| ----------- | -----------------------------------------| -| Change | Updated the jline.jar file. | \ No newline at end of file diff --git a/product_docs/docs/edb_plus/37/edbplus_rel_notes/edbplus3702_rel_notes.mdx b/product_docs/docs/edb_plus/37/edbplus_rel_notes/edbplus3702_rel_notes.mdx deleted file mode 100644 index 936bbf9d4e0..00000000000 --- a/product_docs/docs/edb_plus/37/edbplus_rel_notes/edbplus3702_rel_notes.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Version 37.0.2" ---- - - -New features, enhancements, bug fixes, and other changes in EDB*Plus 37.0.2 include: - -| Type | Description | -| ------------ | ---------------------------------------------------------------------------------------| -| Enhancement | The display format for a decimal point is now compatible with Oracle SQL*Plus [Support Ticket #75092]. | -| Security Fix | The EDB JDBC driver in EDB*Plus is upgraded to version 42.3.2.1. This upgrade fixes the CVE-2022-21724 vulnerability reported in older versions of the EDB JDBC driver. | -| Bug Fix | Describe command no linger fails for a schema qualified SYNONYM name [Support Ticket #72994]. | \ No newline at end of file diff --git a/product_docs/docs/edb_plus/37/edbplus_rel_notes/index.mdx b/product_docs/docs/edb_plus/37/edbplus_rel_notes/index.mdx deleted file mode 100644 index 2b5ea825539..00000000000 --- a/product_docs/docs/edb_plus/37/edbplus_rel_notes/index.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Release Notes" -navigation: -- edbplus3702_rel_notes -- edbplus3701_rel_notes -- edbplus3700_rel_notes ---- - -EDB\*Plus is a utility program that provides a command line user interface to EDB Postgres Advanced Server. - -The EDB\*Plus documentation describes the latest version of EDB\*Plus Version 39. The release notes in this section provide information on what was new in each release. - -| Version | Release Date | -| -------------------------------------- | ------------ | -| [37.0.2](edbplus3702_rel_notes.mdx) | 2022 Mar 28 | -| [37.0.1](edbplus3701_rel_notes.mdx) | 2021 Mar 31 | -| [37.0.0](edbplus3700_rel_notes.mdx) | 2018 Nov 28 | \ No newline at end of file diff --git a/product_docs/docs/edb_plus/37/images/advanced_server_installation_details.png b/product_docs/docs/edb_plus/37/images/advanced_server_installation_details.png deleted file mode 100755 index 3638e7d551f..00000000000 --- a/product_docs/docs/edb_plus/37/images/advanced_server_installation_details.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:a9c152dfd15132f11750917e10b0a8dd3646bfcf5f4d9a3525066f68ebd807d3 -size 19239 diff --git a/product_docs/docs/edb_plus/37/images/edb_plus_welcome.png b/product_docs/docs/edb_plus/37/images/edb_plus_welcome.png deleted file mode 100755 index c526c78eabf..00000000000 --- a/product_docs/docs/edb_plus/37/images/edb_plus_welcome.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:4f557131b686992e3d8a9f7d0f40ddd14dcdde8a6ee7fb90af3ef57860194024 -size 56911 diff --git a/product_docs/docs/edb_plus/37/images/edb_plus_welcome_1.png b/product_docs/docs/edb_plus/37/images/edb_plus_welcome_1.png deleted file mode 100755 index ea2a26270ab..00000000000 --- a/product_docs/docs/edb_plus/37/images/edb_plus_welcome_1.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:2b1c56ab042cb3f2ea94a6fc8177bb9176fdd0bc42ca36e23c43594993dd6637 -size 34974 diff --git a/product_docs/docs/edb_plus/37/images/installation_complete.png b/product_docs/docs/edb_plus/37/images/installation_complete.png deleted file mode 100755 index 30281ba5583..00000000000 --- a/product_docs/docs/edb_plus/37/images/installation_complete.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:3836a996fa7052af22f4a23e24903594d4edf866c3e2696a6cbc0de8f1db4e03 -size 37674 diff --git a/product_docs/docs/edb_plus/37/images/installation_directory.png b/product_docs/docs/edb_plus/37/images/installation_directory.png deleted file mode 100755 index 0e4ab726341..00000000000 --- a/product_docs/docs/edb_plus/37/images/installation_directory.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:7c9a3d397f6c345f80a95362c407c1b72b0414c5934a8e8ef20d6c04a4980469 -size 71722 diff --git a/product_docs/docs/edb_plus/37/images/ready_to_install.png b/product_docs/docs/edb_plus/37/images/ready_to_install.png deleted file mode 100755 index a73f573adc5..00000000000 --- a/product_docs/docs/edb_plus/37/images/ready_to_install.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:ddd7dc4e8a4a8e40f9194e5f7971d3fc01c9c6130de1d3a62fc528a2a018c666 -size 15785 diff --git a/product_docs/docs/edb_plus/37/index.mdx b/product_docs/docs/edb_plus/37/index.mdx deleted file mode 100644 index f8201de6d47..00000000000 --- a/product_docs/docs/edb_plus/37/index.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -navTitle: EDB*Plus -title: "EDB*Plus" - -directoryDefaults: - description: "EDB*Plus Documentation and release notes." -navigation: -- edbplus_rel_notes -- 03_installing_edb_plus ---- - -EDB\*Plus is a utility program that provides a command line user interface to EDB Postgres Advanced Server. EDB\*Plus accepts SQL commands, SPL anonymous blocks, and EDB\*Plus commands. - -EDB\*Plus commands are compatible with Oracle SQL\*Plus commands and provide various capabilities including: - -- Querying certain database objects -- Executing stored procedures -- Formatting output from SQL commands -- Executing batch scripts -- Executing OS commands -- Recording output - - diff --git a/product_docs/docs/edb_plus/38/01_release_notes/09_edbplus38.01_rel_notes.mdx b/product_docs/docs/edb_plus/38/01_release_notes/09_edbplus38.01_rel_notes.mdx deleted file mode 100644 index 9767f92e776..00000000000 --- a/product_docs/docs/edb_plus/38/01_release_notes/09_edbplus38.01_rel_notes.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -navTitle: Version 38.0.1 -title: "Version 38.0.1" ---- - -New features, enhancements, bug fixes, and other changes in EDB*Plus 38.0.1 include: - -| Type | Description | -| ------------ | ---------------------------------------------------------------------------------------| -| Enhancement | The display format for a decimal point is now compatible with Oracle SQL*Plus [Support Ticket #75092]. | -| Security Fix | The EDB JDBC driver in EDB*Plus is upgraded to version 42.3.2.1. This upgrade fixes the CVE-2022-21724 vulnerability reported in older versions of the EDB JDBC driver. | -| Bug Fix | Describe command no linger fails for a schema qualified SYNONYM name [Support Ticket #72994]. | diff --git a/product_docs/docs/edb_plus/38/01_release_notes/10_edbplus38_rel_notes.mdx b/product_docs/docs/edb_plus/38/01_release_notes/10_edbplus38_rel_notes.mdx deleted file mode 100644 index 9cb34558642..00000000000 --- a/product_docs/docs/edb_plus/38/01_release_notes/10_edbplus38_rel_notes.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -navTitle: Version 38.0.0 -title: "Version 38.0.0" ---- - -New features, enhancements, bug fixes, and other changes in EDB*Plus 38.0.0 include: - -| Type | Description | -| ------------ | ---------------------------------------------------------------------------------------| -| Enhancement | Support for EDB Postgres Advanced Server 12.1.1. | \ No newline at end of file diff --git a/product_docs/docs/edb_plus/38/01_release_notes/index.mdx b/product_docs/docs/edb_plus/38/01_release_notes/index.mdx deleted file mode 100644 index 330e53cc1c4..00000000000 --- a/product_docs/docs/edb_plus/38/01_release_notes/index.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Release Notes" ---- - -EDB\*Plus is a utility program that provides a command line user interface to EDB Postgres Advanced Server. - -The EDB\*Plus documentation describes the latest version of EDB\*Plus Version 38. The release notes in this section provide information on what was new in each release. - -| Version | Release Date | -| -------------------------------------- | ------------ | -| [38.0.1](09_edbplus38.01_rel_notes.mdx)| 2022 Mar 23 | -| [38.0.0](10_edbplus38_rel_notes.mdx) | 2019 Dec 10 | \ No newline at end of file diff --git a/product_docs/docs/edb_plus/38/02_installation/01_installing_prereq.mdx b/product_docs/docs/edb_plus/38/02_installation/01_installing_prereq.mdx deleted file mode 100644 index c70f0936779..00000000000 --- a/product_docs/docs/edb_plus/38/02_installation/01_installing_prereq.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "Installation Prerequisites" ---- - - - -This table lists the EDB*Plus versions and their supported corresponding EDB Postgres Advanced Server (EPAS) versions. EDB\*Plus is supported on the same platforms as EDB Postgres Advanced Server. See [Product Compatibility](https://www.enterprisedb.com/platform-compatibility#epas) for details. - -| EDB*Plus | EPAS 14 | EPAS 13 | EPAS 12 | EPAS 11 | EPAS 10 | -| -------- | ------- | ------- | ------- | ------- | ------- | -| 38 | N | Y | Y | Y | Y | -| 37 | N | N | Y | Y | Y | -| 36 | N | N | N | Y | Y | - - -Before installing EDB\*Plus, you must first install Java (version 1.7 or later). On a Linux system, you can use the `yum` package manager to install Java. Open a terminal window, assume superuser privileges, and enter: - -- On RHEL or CentOS 7: - - ```text - # yum install java - ``` - -- On RHEL or CentOS 8: - - ```text - # dnf install java - ``` - -If you are using Windows, Java installers and instructions are available online at: - - - - -You must also have credentials that allow access to the EDB repository. For information about requesting credentials, visit: - - - - -After receiving your repository credentials: - -1. Create the repository configuration file. -2. Modify the file, providing your user name and password. -3. Install EDB\*Plus. - - - - - - diff --git a/product_docs/docs/edb_plus/38/02_installation/02_rpm_installation.mdx b/product_docs/docs/edb_plus/38/02_installation/02_rpm_installation.mdx deleted file mode 100644 index 7819d95053b..00000000000 --- a/product_docs/docs/edb_plus/38/02_installation/02_rpm_installation.mdx +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: "Performing an RPM Installation" ---- - - - - -For detailed information about creating and using EDB repositories to install Advanced Server or its supporting components, see the *EDB Postgres Advanced Server Installation Guide available* at: - - - -**Creating a Repository Configuration File** - -To create the repository configuration file, assume superuser privileges, and invoke the following command: - -- On RHEL or CentOS 7: - - ```text - yum -y install https://yum.enterprisedb.com/edbrepos/edb-repo-latest.noarch.rpm - ``` - -- On RHEL/Rocky Linux/AlmaLinux 8: - - ```text - dnf -y install https://yum.enterprisedb.com/edbrepos/edb-repo-latest.noarch.rpm - ``` - -The repository configuration file is named `edb.repo`. The file resides in `/etc/yum.repos.d`. After saving your changes to the configuration file, you can use the following command to install EDB*Plus: - -- On RHEL or CentOS 7: - - ``` - yum install edb-asxx-edbplus - ``` - -- On RHEL/Rocky Linux/AlmaLinux 8: - - ``` - dnf install edb-asxx-edbplus - ``` - -Where, `xx` is the Advanced Server version. - -When you install an RPM package that is signed by a source that is not recognized by your system, yum may ask for your permission to import the key to your local server. If prompted, and you are satisfied that the packages come from a trustworthy source, entery, and press `Return` to continue. - -During the installation, yum may encounter a dependency that it cannot resolve. If it does, it will provide a list of the required dependencies that you must manually resolve. - - -## Configuring an RPM Installation - -After performing an RPM installation of EDB\*Plus, you must set the values of environment variables that allow -EDB\*Plus to locate your Java installation. Use the following commands to set variable values: - -```text -export JAVA_HOME= -export PATH=/bin:$PATH -``` - -By default, the `pg_hba.conf` file for the RPM installer enforces `IDENT` authentication. Before invoking EDB*Plus, you must either modify the `pg_hba.conf` file, changing the authentication method to a form other than `IDENT` (and restarting the server), or perform the following steps to ensure that an `IDENT` server is accessible: - -You must confirm that an `identd` server is installed and running. You can use the `yum` package manager to install an `identd` server by invoking the command: - -- On RHEL or CentOS 7: - - ```text - yum install xinetd authd - ``` - -- On RHEL/Rocky Linux/AlmaLinux 8: - - ```text - dnf install xinetd authd - ``` - -The command should create a file named ``/etc/xinetd.d/auth`` that contains: - -```text -service auth -{ - disable = yes - socket_type = stream -wait =no -user = ident -cps = 4096 10 -instances = UNLIMITED -server = /usr/sbin/in.authd server_args = -t60 --xerror -os -} -``` - -!!! Note - If the file includes a `-E` argument at the end of the server arguments, please erase `-E`. - -Then, to start the `identd` server, invoke the following commands: - -```text -systemctl enable xinetd -systemctl start xinetd -``` - -Open the `pg_ident.conf` file and create a user mapping: - -``` -# map_name system_username postgres_username - edbas enterprisedb enterprisedb -``` - -Where: - -- The name specified in the `map_name` column is a user-defined name that will identify the mapping in the `pg_hba.conf` file. -- The name specified in the `system_username` column is `enterprisedb`. -- The name specified in the `postgres_username` column is `enterprisedb`. - -Then, open the `pg_hba.conf` file and modify the `IDENT` entries: - -- If you are using an IPv4 local connection, modify the file entry to read: - - `host all all 127.0.0.0/0 ident map=edbas` - -- If you are using an IPv6 local connection, modify the file entry to read: - - `host all all ::1/128 ident map=edbas` - -You must restart the Advanced Server service before invoking EDB\*Plus. For detailed information about controlling the Advanced Server service, see the *EDB Postgres Advanced Server Installation Guide*, available at: - -[https://www.enterprisedb.com/docs](/epas/12/) - - - diff --git a/product_docs/docs/edb_plus/38/02_installation/03_using_gui.mdx b/product_docs/docs/edb_plus/38/02_installation/03_using_gui.mdx deleted file mode 100644 index 63600a8e596..00000000000 --- a/product_docs/docs/edb_plus/38/02_installation/03_using_gui.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "Using the Graphical Installer" ---- - - - - -Graphical installers for EDB\*Plus are available via StackBuilder Plus; you can access StackBuilder Plus through your Windows or Linux start menu. After opening StackBuilder Plus and selecting the installation for which you wish to install EDB\*Plus, expand the component selection screen tree control to select and download the EDB\*Plus installer. - -![The EDB\*Plus Welcome window](../images/edb_plus_welcome_1.png) - -
Fig. 1: The EDB*Plus Welcome window
- - -The EDB\*Plus installer welcomes you to the setup wizard, as shown in the figure below. - -![The Installation Directory window](../images/installation_directory.png) - -
Fig. 2: The Installation Directory window
- - -Use the `Installation Directory` field to specify the directory in which you wish to install the EDB\*Plus software. Then, click `Next` to continue. - -![The Advanced Server Installation Details window](../images/advanced_server_installation_details.png) - -
Fig. 3: The Advanced Server Installation Details window
- - -Use fields on the `EDB Postgres Advanced Server Installation Details` window to identify the location of the Advanced Server host: - -- Use the `Host` field to identify the system on which Advanced Server resides. -- Use the `Port` field to identify the listener port that Advanced Server monitors for client connections. - -Then, click `Next` to continue. - -![The Ready to Install window](../images/ready_to_install.png) - -
Fig. 4: The Ready to Install window
- - -The `Ready to Install` window notifies you when the installer has all of the information needed to install EDB\*Plus on your system. Click `Next` to install EDB\*Plus. - -![The installation is complete](../images/installation_complete.png) - -
Fig. 5: The installation is complete
- - -The installer notifies you when the setup wizard has completed the EDB\*Plus installation. Click `Finish` to exit the installer. diff --git a/product_docs/docs/edb_plus/38/02_installation/index.mdx b/product_docs/docs/edb_plus/38/02_installation/index.mdx deleted file mode 100644 index 3b495295dd2..00000000000 --- a/product_docs/docs/edb_plus/38/02_installation/index.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Installing EDB*Plus" - ---- - -You can use an RPM installer or a graphical installer to add EDB*Plus to your Advanced Server installation. - - - -
- -installing_prereq rpm_installation using_gui - -
\ No newline at end of file diff --git a/product_docs/docs/edb_plus/38/04_using_edb_plus.mdx b/product_docs/docs/edb_plus/38/04_using_edb_plus.mdx deleted file mode 100644 index 36ea7a33bfa..00000000000 --- a/product_docs/docs/edb_plus/38/04_using_edb_plus.mdx +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: "Using EDB*Plus" ---- - - - - - -To open an EDB\*Plus command line, navigate through the `Applications` or `Start` menu to the Advanced Server menu, to the `Run SQL Command Line` menu, and select the EDB\*Plus option. You can also invoke EDB\*Plus from the operating system command line with the following command: - -```text -edbplus [ -S[ILENT ] ] [ | /NOLOG ] [ @[. ] ] -``` - -`SILENT` - - If specified, the EDB\*Plus sign-on banner is suppressed along with all prompts. - -`login` - - Login information for connecting to the database server and database. `login` takes the following form; there must be no white space within the login information. - -```text -[/][@{ | } ] -``` - - Where: - - `username` is a database username with which to connect to the database. - - `password` is the password associated with the specified `username`. If a `password` is not provided, but a password is required for authentication, a password file is used if available. If there is no password file or no entry in the password file with the matching connection parameters, then EDB\*Plus will prompt for the password. - - `connectstring` is the database connection string with the following format: - -```text -[:][/][?ssl={true | false}] -``` - - Where: - - `host` is the hostname or IP address on which the database server resides. If neither `@connectstring` nor `@variable` nor `/NOLOG` is specified, the default host is assumed to be the localhost. `port` is the port number receiving connections on the database server. If not specified, the default is `5444`. `dbname` is the name of the database to connect to. If not specified the default is `edb`. If `Internet Protocol version 6` (IPv6) is used for the connection instead of IPv4, then the IP address must be enclosed within square brackets (that is, `[ipv6_address]`). The following is an example using an IPv6 connection: - -```text -edbplus.sh enterprisedb/password@[fe80::20c:29ff:fe7c:78b2]:5444/edb -``` - - The `pg_hba.conf` file for the database server must contain an appropriate entry for the IPv6 connection. The following example shows an entry that allows all addresses: - -```text -# TYPE DATABASE USER ADDRESS METHOD -host all all ::0/0 md5 -``` - -For more information about the `pg_hba.conf` file, see the PostgreSQL core documentation at: - - - - If an SSL connection is desired, then include the `?ssl=true` parameter in the connection string. In such a case, the connection string must minimally include `host:port`, with or without `/dbname`. If the `ssl` parameter is not specified, the default is `false`. See [Using a Secure Sockets Layer (SSL) Connection](05_using_edb_plus_with_ssl/#using_edb_plus_with_ssl) for instructions on setting up an SSL connection. - - `variable` is a variable defined in the `login.sql` file that contains a database connection string. The `login.sql` file can be found in the `edbplus` subdirectory of the Advanced Server home directory. - -`/NOLOG` - - Specify `/NOLOG` to start EDB\*Plus without establishing a database connection. SQL commands and EDB\*Plus commands that require a database connection cannot be used in this mode. The `CONNECT` command can be subsequently given to connect to a database after starting EDB\*Plus with the `/NOLOG` option. - -`scriptfile[.ext ]` - - `scriptfile` is the name of a file residing in the current working directory, containing SQL and/or EDB\*Plus commands that will be automatically executed after startup of EDB\*Plus. `ext` is the filename extension. If the filename extension is `sql`, then the `.sql` extension may be omitted when specifying `scriptfile`. When creating a script file, always name the file with an extension, otherwise it will not be accessible by EDB\*Plus. (EDB\*Plus will always assume a `.sql` extension on filenames that are specified with no extension.) - -!!! Note - When you run the commands in the following examples you may be using a newer version of EDB\*Plus and as such the EDB\*Plus build number shown in your output may be different. - -The following example shows user `enterprisedb` with password `password`, connecting to database `edb` running on a database server on the `localhost` at port `5444`. - -```text -C:\Program Files\edb\as12\edbplus>edbplus enterprisedb/password -Connected to EnterpriseDB 12.1.2 (localhost:5444/edb) AS enterprisedb - -EDB*Plus: Release 12 (Build 38.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -The following example shows user `enterprisedb` with password, `password`, connecting to database `edb` running on a database server on the `localhost` at port `5445`. - -```text -C:\Program Files\edb\as12\edbplus>edbplus enterprisedb/password@localhost:5445/edb -Connected to EnterpriseDB 12.1.2 (localhost:5445/edb) AS enterprisedb - -EDB*Plus: Release 12 (Build 38.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -Using variable `hr_5445` in the `login.sql` file, the following illustrates how it is used to connect to database `hr` on localhost at port `5445`. - -```text -C:\Program Files\edb\as12\edbplus>edbplus enterprisedb/password@hr_5445 -Connected to EnterpriseDB 12.1.2 (localhost:5445/hr) AS enterprisedb - -EDB*Plus: Release 12 (Build 38.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -The following is the content of the `login.sql` file used in the previous example. - -```text -define edb="localhost:5445/edb" -define hr_5445="localhost:5445/hr" -``` - -The following example executes a script file, `dept_query.sql` after connecting to database `edb` on server localhost at port `5444`. - -```text -C:\Program Files\edb\as12\edbplus>edbplus enterprisedb/password @dept_query -Connected to EnterpriseDB 12.0.1 (localhost:5444/edb) AS enterprisedb - -SQL> SELECT * FROM dept; - -DEPTNO DNAME LOC ------- -------------- ------------- -10 ACCOUNTING NEW YORK -20 RESEARCH DALLAS -30 SALES CHICAGO -40 OPERATIONS BOSTON - -SQL> EXIT -Disconnected from EnterpriseDB Database. -``` - -The following is the content of file `dept_query.sql` used in the previous example. - -```text -SET PAGESIZE 9999 -SET ECHO ON -SELECT * FROM dept; -EXIT -``` diff --git a/product_docs/docs/edb_plus/38/05_using_edb_plus_with_ssl.mdx b/product_docs/docs/edb_plus/38/05_using_edb_plus_with_ssl.mdx deleted file mode 100644 index c13deae67fa..00000000000 --- a/product_docs/docs/edb_plus/38/05_using_edb_plus_with_ssl.mdx +++ /dev/null @@ -1,324 +0,0 @@ ---- -title: "Using a SSL Connection" ---- - - - - - -An EDB\*Plus connection to the Advanced Server database can be accomplished using secure sockets layer (SSL) connectivity. - -Using SSL requires various prerequisite configuration steps performed on the database server involved with the SSL connection as well as creation of the Java truststore and keystore on the host that will run EDB\*Plus. - -The Java *truststore* is the file containing the Certificate Authority (CA) certificates with which the Java client (EDB\*Plus) uses to verify the authenticity of the server to which it is initiating an SSL connection. - -The Java *keystore* is the file containing private and public keys and their corresponding certificates. The keystore is required for client authentication to the server, which is used for the EDB\*Plus connection. - -The following is material to which you can refer to for guidance in setting up the SSL connections: - -- For information on setting up SSL connectivity to the Advanced Server database, see the section about secure TCP connections with SSL in Chapter 18 “Server Setup and Operation” in the PostgreSQL Core Documentation located at: - - - -- For information on JDBC client connectivity using SSL, see the section on configuring the client in Chapter 4 “Using SSL” in The PostgreSQL JDBC Interface located at: - - - -The following sections provide information for the configuration steps of using SSL. - -- Configuring SSL on Advanced Server -- Configuring SSL for the EDB\*Plus client -- Requesting SSL connection to the Advanced Server database - -## Configuring SSL on Advanced Server - -This section provides an example of configuring SSL on a database server to demonstrate the use of SSL with EDB\*Plus. A self-signed certificate is used for this purpose. - -**Step 1:** Create the certificate signing request (CSR). - -In the following example the generated certificate signing request file is `server.csr`. The private key is generated as file `server.key`. - -```text -$ openssl req -new -nodes -text -out server.csr \ -> -keyout server.key -subj "/CN=enterprisedb" -Generating a 2048 bit RSA private key -.............................+++ -....................................................................+++ -writing new private key to 'server.key' ------ -``` - -!!! Note - When creating the certificate, the value specified for the common name field (designated as `CN=enterprisedb` in this example) must be the database user name that is specified when connecting to EDB\*Plus. - -In addition, user name maps can be used as defined in the `pg_ident.conf` file to permit more flexibility for the common name and database user name. Steps 8 and 9 describe the use of user name `maps`. - -**Step 2:** Generate the self-signed certificate. - -The following generates a self-signed certificate to file `server.crt` using the certificate signing request file, `server.csr`, and the private key, `server.key`, as input. - -```text -$ openssl x509 -req -days 365 -in server.csr -signkey server.key \ -> -out server.crt -Signature ok -subject=/CN=enterprisedb -Getting Private key -``` - -**Step 3:** Make a copy of the server certificate (`server.crt`) to be used as the root Certificate Authority (CA) file (`root.crt`). - -```text -$ cp server.crt root.crt -``` - -**Step 4:** Delete the now redundant certificate signing request (`server.csr`). - -```text -$ rm -f server.csr -``` - -**Step 5:** Move or copy the certificate and private key files to the Advanced Server data directory (for example, `/opt/edb/as12/data`). - -```text -$ mv root.crt /opt/edb/as12/data -$ mv server.crt /opt/edb/as12/data -$ mv server.key /opt/edb/as12/data -``` - -**Step 6:** Set the file ownership and permissions on the certificate files and private key file. - -Set the ownership to the operating system account that owns the data sub-directory of the database server. Set the permissions so that no other groups or accounts other than the owner can access these files. - -```text -$ chown enterprisedb root.crt server.crt server.key -$ chgrp enterprisedb root.crt server.crt server.key -$ chmod 600 root.crt server.crt server.key -$ ls -l -total 152 - . - . - . --rw------- 1 enterprisedb enterprisedb 985 Aug 22 11:00 root.crt --rw------- 1 enterprisedb enterprisedb 985 Aug 22 10:59 server.crt --rw------- 1 enterprisedb enterprisedb 1704 Aug 22 10:58 server.key -``` - -**Step 7:** In the `postgresql.conf` file, make the following modifications. - -```text -ssl = on -ssl_cert_file = 'server.crt' -ssl_key_file = 'server.key' -ssl_ca_file = 'root.crt' -``` - -**Step 8:** Modify the `pg_hba.conf` file to enable SSL usage on the desired database to which EDB\*Plus is to make the SSL connection. - -In the `pg_hba.conf` file, the `hostssl` type indicates the entry is used to validate SSL connection attempts from the client (EDB\*Plus). - -The authentication method is set to cert with the option `clientcert=1` in order to require an SSL certificate from the client against which authentication is performed using the common name of the certificate (`enterprisedb` in this example). - -The `map=sslusers` option specifies that a mapping named `sslusers` defined in the `pg_ident.conf` file is to be used for authentication. This mapping allows a connection to the database if the common name from the certificate and the database user name attempting the connection match the `SYSTEM-USERNAME/PG-USERNAME` pair listed in the `pg_ident.conf` file. - -The following is an example of the settings in the `pg_hba.conf` file if the database `(edb)` must use SSL connections. - -```text -# TYPE DATABASE USER ADDRESS METHOD - -# "local" is for Unix domain socket connections only -local all all md5 -# IPv4 local connections: -hostssl edb all 192.168.2.0/24 cert clientcert=1 map=sslusers -``` - -**Step 9:** The following shows the user name maps in the `pg_ident.conf` file related to the `pg_hba.conf` file by the `map=sslusers` option. These user name maps permit you to specify database user names `edbuser`, `postgres`, or `enterprisedb` when connecting with EDB\*Plus. - -```text -# MAPNAME SYSTEM-USERNAME PG-USERNAME - sslusers enterprisedb edbuser - sslusers enterprisedb postgres - sslusers enterprisedb enterprisedb -``` - -**Step 10:** Restart the database server after you have made the changes to the configuration files. - -## Configuring SSL for the EDB\*Plus Client - -After you have configured SSL on the database server, the following steps provide an example of generating certificate and keystore files for EDB\*Plus (the JDBC client). - -**Step 1:** Using files `server.crt` and `server.key` located under the database server data sub-directory, create copies of these files and move them to the host where EDB\*Plus is to be running. - -Store these files in the desired directory to contain the trusted certificate and keystore files to be generated in the following steps. The suggested location is to create a `.postgresql` sub-directory under the home user account that will invoke EDB\*Plus. Thus, these files will be under the `~/.postgresql` directory of the user account that will run EDB\*Plus. - -For this example, assume file `edb.crt` is a copy of `server.crt` and `edb.key` is a copy of `server.key`. - -**Step 2:** Create an additional copy of `edb.crt`. - -```text -$ cp edb.crt edb_root.crt -$ ls -l -total 12 --rw-r--r-- 1 user user 985 Aug 22 14:17 edb.crt --rw-r--r-- 1 user user 1704 Aug 22 14:18 edb.key --rw-r--r-- 1 user user 985 Aug 22 14:19 edb_root.crt -``` - -**Step 3:** Create a Distinguished Encoding Rules (DER) format of file `edb_root.crt`. The generated DER format of this file is `edb_root.crt.der`. The DER format of the file is required for the `keytool` program used in Step 4. - -```text -$ openssl x509 -in edb_root.crt -out edb_root.crt.der -outform der -$ ls -l -total 16 --rw-r--r-- 1 user user 985 Aug 22 14:17 edb.crt --rw-r--r-- 1 user user 1704 Aug 22 14:18 edb.key --rw-r--r-- 1 user user 985 Aug 22 14:19 edb_root.crt --rw-rw-r-- 1 user user 686 Aug 22 14:21 edb_root.crt.der -``` - -**Step 4:** Use the `keytool` program to create a keystore file `(postgresql.keystore)` using `edb_root.crt.der` as the input. This process adds the certificate of the Postgres database server to the keystore file. - -!!! Note - The file name `postgresql.keystore` is recommended so that it can be accessed in its default directory location `~/.postgresql postgresql.keystore`, which is under the home directory of the user account invoking EDB\*Plus. Also note that the file name suffix can be `.jks` instead of `.keystore` (thus, file name `postgresql.jks`). However, in the remainder of these examples, file name `postgresql.keystore` is used. - -**For Windows only:** The path is `%APPDATA%\.postgresql\postgresql.keystore` - -The `keytool` program can be found under the `bin` subdirectory of the Java Runtime Environment installation. - -You will be prompted for a new password. Save this password as it must be specified with the PGSSLCERTPASS environment variable. - -```text -$ /usr/java/jdk1.8.0_131/jre/bin/keytool -keystore postgresql.keystore \ -> -alias postgresqlstore -import -file edb_root.crt.der -Enter keystore password: -Re-enter new password: -Owner: CN=enterprisedb -Issuer: CN=enterprisedb -Serial number: c60f40256b0e8d53 -Valid from: Tue Aug 22 10:59:25 EDT 2017 until: Wed Aug 22 10:59:25 EDT 2018 -Certificate fingerprints: - MD5: 85:0B:E9:A7:6E:4F:7C:B0:9B:D6:3A:44:55:E2:E9:8E - SHA1: DD:A6:71:24:0B:6C:F8:BC:7A:4C:89:9B:DC:22:6A:6C:B0:F5:3F:7C - SHA256: -DC:02:64:E2:B0:E9:6F:1C:FC:4F:AE:E6:18:85:0B:79:57:43:C3:C5:AE:43:0D:37 -:49:53:6D:11:69:06:46:48 - Signature algorithm name: SHA1withRSA - Version: 1 -Trust this certificate? [no]: yes -Certificate was added to keystore -``` - -**Step 5:** Create a `PKCS #12` format of the keystore file `(postgresql.p12)` using files `edb.crt` and `edb.key` as input. - -!!! Note - The file name `postgresql.p12` is recommended so that it can be accessed in its default directory location `~/.postgresql/postgresql.p12`, which is under the home directory of the user account invoking EDB\*Plus. - -**For Windows only:** The path is `%APPDATA%\.postgresql\postgresql.p12` - -You will be prompted for a new password. Save this password as it must be specified with the PGSSLKEYPASS environment variable. - -```text -$ openssl pkcs12 -export -in edb.crt -inkey edb.key -out postgresql.p12 -Enter Export Password: -Verifying - Enter Export Password: -$ ls –l -total 24 --rw-rw-r-- 1 user user 985 Aug 24 12:18 edb.crt --rw-rw-r-- 1 user user 1704 Aug 24 12:18 edb.key --rw-rw-r-- 1 user user 985 Aug 24 12:20 edb_root.crt --rw-rw-r-- 1 user user 686 Aug 24 12:20 edb_root.crt.der --rw-rw-r-- 1 user user 758 Aug 24 12:26 postgresql.keystore --rw-rw-r-- 1 user user 2285 Aug 24 12:28 postgresql.p12 -``` - -**Step 6:** If the `postgresql.keystore` and `postgresql.p12` files are not already in the `~/.postgresql` directory, move or copy them to that location. - -**For Windows only:** The directory is `%APPDATA%\.postgresql` - -**Step 7:** If the default location `~/.postgresql` is not used, then the full path (including the file name) to the `postgresql.keystore` file must be set with the `PGSSLCERT` environment variable, and the full path (including the file name) to file `postgresql.p12` must be set with the `PGSSLKEY` environment variable before invoking EDB\*Plus. - -In addition, if the generated file from Step 4 was not named `postgresql.keystore` or `postgresql.jks` then, use the `PGSSLCERT` environment variable to designate the file name and its location. Similarly, if the generated file from Step 5 was not named `postgresql.p12` then, use the `PGSSLKEY` environment variable to designate the file name and its location. - -## Requesting an SSL Connection between EDB\*Plus and the Advanced Server Database - -Be sure the following topics have been addressed in order to perform an SSL connection: - -- The trusted certificate and keystore files have been generated for both the database server and the client host to be invoking EDB\*Plus. -- The `postgresql.conf` file for the database server contains the updated configuration parameters. -- The `pg_hba.conf` file for the database server contains the required entry for permitting the SSL connection. -- For the client host, either the client’s certificate and keystore files have been placed in the user account’s `~/.postgresql` directory or the environment variables `PGSSLCERT` and `PGSSLKEY` are set before invoking EDB\*Plus. -- The `PGSSLCERTPASS` environment variable is set with a password. -- The `PGSSLKEYPASS` environment variable is set with a password - -When invoking EDB\*Plus, include the `?ssl=true` parameter in the database connection string as shown for the `connectstring` option in [Using EDB\*Plus](04_using_edb_plus/#using_edb_plus). - -The following is an example where EDB\*Plus is invoked from a host that is remote to the database server. - -The `postgresql.conf` file of the database server contains the following modified parameters: - -```text -ssl = on -ssl_cert_file = 'server.crt' -ssl_key_file = 'server.key' -ssl_ca_file = 'root.crt' -``` - -The `pg_hba.conf` file of the database server contains the following entry for connecting from EDB\*Plus on the remote host: - -```text -# TYPE DATABASE USER ADDRESS METHOD - -# "local" is for Unix domain socket connections only -local all all md5 -# IPv4 local connections: -hostssl edb all 192.168.2.24/32 cert clientcert=1 -``` - -On the remote host where EDB\*Plus is to be invoked, the Linux user account named `user` contains the certificate and keystore files in its `~/.postgresql` directory: - -```text -[user@localhost ~]$ whoami -user -[user@localhost ~]$ cd .postgresql -[user@localhost .postgresql]$ pwd -/home/user/.postgresql -[user@localhost .postgresql]$ ls -l -total 8 --rw-rw-r-- 1 user user 758 Aug 24 12:37 postgresql.keystore --rw-rw-r-- 1 user user 2285 Aug 24 12:37 postgresql.p12 -``` - -Logged into Linux with the account named `user`, EDB\*Plus is successfully invoked with the `ssl=true` parameter: - -```text -$ export PGSSLCERTPASS=keypass -$ export PGSSLKEYPASS=exppass -$ cd /opt/edb/as12/edbplus -$ ./edbplus.sh enterprisedb/password@192.168.2.22:5444/edb?ssl=true -Connected to EnterpriseDB 12.0.1 (192.168.2.22:5444/edb) AS enterprisedb - -EDB*Plus: Release 12 (Build 38.0.1) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -Alternatively, without placing the certificate and keystore files in `~/.postgresql`, but in a different directory, EDB\*Plus can be invoked in the following manner: - -```text -$ export PGSSLCERT=/home/user/ssl/postgresql.keystore -$ export PGSSLKEY=/home/user/ssl/postgresql.p12 -$ export PGSSLCERTPASS=keypass -$ export PGSSLKEYPASS=exppass -$ cd /opt/edb/as12/edbplus -$ ./edbplus.sh enterprisedb/password@192.168.2.22:5444/edb?ssl=true -Connected to EnterpriseDB 12.0.1 (192.168.2.22:5444/edb) AS enterprisedb - -EDB*Plus: Release 12 (Build 38.0.1) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -Note that in both cases the database user name used to log into EDB\*Plus is `enterprisedb` as this is the user specified for the common name field when creating the certificate in Step 1 of [Configuring SSL on Advanced Server](#using_ssl_connection). - -Other database user names can be used if the `pg_hba.conf` file with the `map` option and the `pg_ident.conf` file are used as described in Steps 8 and 9 of [Configuring SSL on Advanced Server](#using_ssl_connection). diff --git a/product_docs/docs/edb_plus/38/06_command_summary.mdx b/product_docs/docs/edb_plus/38/06_command_summary.mdx deleted file mode 100644 index 718499404a1..00000000000 --- a/product_docs/docs/edb_plus/38/06_command_summary.mdx +++ /dev/null @@ -1,992 +0,0 @@ ---- -title: "Command Summary" ---- - - - -The following sections contains a summary of EDB\*Plus commands. - -## ACCEPT - -The `ACCEPT` command displays a prompt and waits for the user’s keyboard input. The value input by the user is placed in the specified variable. - -```text -ACC[EPT ] variable -``` - -The following example creates a new variable named `my_name`, accepts a value of John Smith, then displays the value using the `DEFINE` command. - -```text -SQL> ACCEPT my_name -Enter value for my_name: John Smith -SQL> DEFINE my_name -DEFINE MY_NAME = "John Smith" -``` - -## APPEND - -`APPEND` is a line editor command that appends the given text to the end of the current line in the SQL buffer. - -```text -A[PPEND ] text -``` - -In the following example, a `SELECT` command is built-in the SQL buffer using the `APPEND` command. Note that two spaces are placed between the `APPEND` command and the `WHERE` clause in order to separate `dept` and `WHERE` by one space in the SQL buffer. - -```text -SQL> APPEND SELECT * FROM dept -SQL> LIST - 1 SELECT * FROM dept -SQL> APPEND WHERE deptno = 10 -SQL> LIST - 1 SELECT * FROM dept WHERE deptno = 10 -``` - -## CHANGE - -`CHANGE` is a line editor command performs a search-and-replace on the current line in the SQL buffer. - -```text -C[HANGE ] FROM [ TO ] -``` - -If `TO/` is specified, the first occurrence of text `FROM` in the current line is changed to text `TO`. If `TO/` is omitted, the first occurrence of text `FROM` in the current line is deleted. - -The following sequence of commands makes line 3 the current line, then changes the department number in the `WHERE` clause from 20 to 30. - -```text -SQL> LIST - 1 SELECT empno, ename, job, sal, comm - 2 FROM emp - 3 WHERE deptno = 20 - 4* ORDER BY empno -SQL> 3 - 3* WHERE deptno = 20 -SQL> CHANGE /20/30/ - 3* WHERE deptno = 30 -SQL> LIST - 1 SELECT empno, ename, job, sal, comm - 2 FROM emp - 3 WHERE deptno = 30 - 4* ORDER BY empno -``` - -## CLEAR - -The `CLEAR` command removes the contents of the SQL buffer, deletes all column definitions set with the `COLUMN` command, or clears the screen. - -```text -CL[EAR ] [ BUFF[ER ] | SQL | COL[UMNS ] | SCR[EEN ] ] -``` - -`BUFFER | SQL` - - Clears the SQL buffer. - -`COLUMNS` - - Removes column definitions. - -`SCREEN` - - Clears the screen. This is the default if no options are specified. - -## COLUMN - -The `COLUMN` command controls output formatting. The formatting attributes set by using the `COLUMN` command remain in effect only for the duration of the current session. - -```text -COL[UMN ] - [ column - { CLE[AR ] | - { FOR[MAT ] spec | - HEA[DING ] text | - { OFF | ON } - } [...] - } - ] -``` - -If the `COLUMN` command is specified with no subsequent options, formatting options for current columns in effect for the session are displayed. - -If the `COLUMN` command is followed by a column name, then the column name may be followed by one of the following: - -1. No other options -2. `CLEAR` -3. Any combination of `FORMAT`, `HEADING`, and one of `OFF` or `ON` - -`column` - - Name of a column in a table to which subsequent column formatting options are to apply. If no other options follow `column`, then the current column formatting options if any, of `column` are displayed. - -`CLEAR` - - The `CLEAR` option reverts all formatting options back to their defaults for `column`. If the `CLEAR` option is specified, it must be the only option specified. - -`spec` - - Format specification to be applied to `column`. For character columns, `spec` takes the following format: - -`n` - - `n` is a positive integer that specifies the column width in characters within which to display the data. Data in excess of `n` will wrap around with the specified column width. - - For numeric columns, `spec` is comprised of the following elements. - -| Element | Description | -| ------- | ------------------------------------------ | -| `$` | Display a leading dollar sign. | -| `,` | Display a comma in the indicated position. | -| `.` | Marks the location of the decimal point. | -| `0` | Display leading zeros. | -| `9` | Number of significant digits to display. | - - If loss of significant digits occurs due to overflow of the format, then all #’s are displayed. - -`text` - - Text to be used for the column heading of `column`. - -`OFF | ON` - - If `OFF` is specified, formatting options are reverted back to their defaults, but are still available within the session. If `ON` is specified, the formatting options specified by previous `COLUMN` commands for `column` within the session are re-activated. - -The following example shows the effect of changing the display width of the `job` column. - -```text -SQL> SET PAGESIZE 9999 -SQL> COLUMN job FORMAT A5 -SQL> COLUMN job -COLUMN JOB ON -FORMAT A5 -wrapped -SQL> SELECT empno, ename, job FROM emp; - -EMPNO ENAME JOB ------ ---------- ----- - 7369 SMITH CLERK - 7499 ALLEN SALES - MAN - - 7521 WARD SALES - MAN - - 7566 JONES MANAG - ER - - 7654 MARTIN SALES - MAN - - 7698 BLAKE MANAG - ER - - 7782 CLARK MANAG - ER - - 7788 SCOTT ANALY - ST - - 7839 KING PRESI - DENT - - 7844 TURNER SALES - MAN - - 7876 ADAMS CLERK - 7900 JAMES CLERK - 7902 FORD ANALY - ST - - 7934 MILLER CLERK - -14 rows retrieved. -``` - -The following example applies a format to the `sal` column. - -```text -SQL> COLUMN sal FORMAT $99,999.00 -SQL> COLUMN -COLUMN JOB ON -FORMAT A5 -wrapped - -COLUMN SAL ON -FORMAT $99,999.00 -wrapped -SQL> SELECT empno, ename, job, sal FROM emp; - -EMPNO ENAME JOB SAL ------ ---------- ----- ----------- - 7369 SMITH CLERK $800.00 - 7499 ALLEN SALES $1,600.00 - MAN - - 7521 WARD SALES $1,250.00 - MAN - - 7566 JONES MANAG $2,975.00 - ER - - 7654 MARTIN SALES $1,250.00 - MAN - - 7698 BLAKE MANAG $2,850.00 - ER - - 7782 CLARK MANAG $2,450.00 - ER - - 7788 SCOTT ANALY $3,000.00 - ST - - 7839 KING PRESI $5,000.00 - DENT - - 7844 TURNER SALES $1,500.00 - MAN - - 7876 ADAMS CLERK $1,100.00 - 7900 JAMES CLERK $950.00 - 7902 FORD ANALY $3,000.00 - ST - - 7934 MILLER CLERK $1,300.00 - -14 rows retrieved. -``` - -## CONNECT - -Change the database connection to a different user and/or connect to a different database. There must be no white space between any of the parameters following the `CONNECT` command. - -```text -CON[NECT] [/][@{ | } ] -``` - -Where: - - `username` is a database username with which to connect to the database. - - `password` is the password associated with the specified `username`. If a `password` is not provided, but a password is required for authentication, a search is made for a password file, first in the home directory of the Linux operating system account invoking EDB\*Plus (or in the `%APPDATA%\postgresql\` directory for Windows) and then at the location specified by the `PGPASSFILE` environment variable. The password file is `.pgpass` on Linux hosts and `pgpass.conf` on Windows hosts. The following is an example on a Windows host: - -```text -C:\Users\Administrator\AppData\Roaming\postgresql\pgpass.conf -``` - - If a password file cannot be located, or it does not have an entry matching the EDB\*Plus connection parameters, then EDB\*Plus will prompt for the password. For more information about password files, see the PostgreSQL core documentation at: - - - - **Note**: When a password is not required, EDB\*Plus does not prompt for a password such as when the `trust` authentication method is specified in the `pg_hba.conf` file. For more information about the `pg_hba.conf` file and authentication methods, see the PostgreSQL core documentation at - - `connectstring` is the database connection string. See [Using EDB\*Plus](04_using_edb_plus/#using_edb_plus) for further information on the database connection string. - - `variable` is a variable defined in the `login.sql` file that contains a database connection string. The `login.sql` file can be found in the `edbplus` subdirectory of the Advanced Server home directory. - -In the following example, the database connection is changed to database `edb` on the localhost at port `5445` with username `smith`. - -```text -SQL> CONNECT smith/mypassword@localhost:5445/edb -Disconnected from EnterpriseDB Database. -Connected to EnterpriseDB 12.0.1 (localhost:5445/edb) AS smith -``` - -From within the session shown above, the connection is changed to username `enterprisedb`. Also note that the host defaults to the localhost, the port defaults to `5444` (which is not the same as the port previously used), and the database defaults to `edb`. - -```text -SQL> CONNECT enterprisedb/password -Disconnected from EnterpriseDB Database. -Connected to EnterpriseDB 12.0.1 (localhost:5444/edb) AS enterprisedb -``` - -## DEFINE - -The `DEFINE` command creates or replaces the value of a *user variable* (also called a *substitution variable*). - -```text -DEF[INE ] [ variable [ = text ] ] -``` - -If the `DEFINE` command is given without any parameters, all current variables and their values are displayed. - -If `DEFINE variable` is given, only `variable` is displayed with its value. - -`DEFINE variable = text` assigns `text` to `variable.text` may be optionally enclosed within single or double quotation marks. Quotation marks must be used if `text` contains space characters. - -The following example defines two variables, `dept` and `name`. - -```text -SQL> DEFINE dept = 20 -SQL> DEFINE name = 'John Smith' -SQL> DEFINE -DEFINE EDB = "localhost:5445/edb" -DEFINE DEPT = "20" -DEFINE NAME = "John Smith" -``` - -!!! Note - The variable `EDB` is read from the `login.sql` file located in the `edbplus` subdirectory of the Advanced Server home directory. - -## DEL - -`DEL` is a line editor command that deletes one or more lines from the SQL buffer. - -```text -DEL [ n | n m | n * | n L[AST ] | * | * n | * L[AST ] | L[AST ] ] -``` - -The parameters specify which lines are to be deleted from the SQL buffer. Two parameters specify the start and end of a range of lines to be deleted. If the `DEL` command is given with no parameters, the current line is deleted. - -`n` - - n is an integer representing the `n`th line - -`n m` - - `n` and `m` are integers where `m` is greater than `n` representing the `n`th through the `m`th lines - -`*` - - Current line - -`LAST` - - Last line - -In the following example, the fifth and sixth lines containing columns `sal` and `comm`, respectively, are deleted from the `SELECT` command in the SQL buffer. - -```text -SQL> LIST - 1 SELECT - 2 empno - 3 ,ename - 4 ,job - 5 ,sal - 6 ,comm - 7 ,deptno - 8* FROM emp -SQL> DEL 5 6 -SQL> LIST - 1 SELECT - 2 empno - 3 ,ename - 4 ,job - 5 ,deptno - 6* FROM emp -``` - -## DESCRIBE - -The `DESCRIBE` command displays: - -- A list of columns, column data types, and column lengths for a table or view -- A list of parameters for a procedure or function -- A list of procedures and functions and their respective parameters for a package - -The `DESCRIBE` command will also display the structure of the database object referred to by a synonym. The syntax is: - -```text -DESC[RIBE] [ schema.]object -``` - -`schema` - - Name of the schema containing the object to be described. - -`object` - - Name of the table, view, procedure, function, or package to be displayed, or the synonym of an object. - -## DISCONNECT - -The `DISCONNECT` command closes the current database connection, but does not terminate EDB\*Plus. - -```text -DISC[ONNECT ] -``` - -## EDIT - -The `EDIT` command invokes an external editor to edit the contents of an operating system file or the SQL buffer. - -```text -ED[IT ] [ filename[.ext ] ] -``` - -`filename[.ext ]` - - `filename` is the name of the file to open with an external editor. `ext` is the filename extension. If the filename extension is `sql`, then the `.sql` extension may be omitted when specifying `filename`. `EDIT` always assumes a `.sql` extension on filenames that are specified with no extension. If the filename parameter is omitted from the `EDIT` command, the contents of the SQL buffer are brought into the editor. - -## EXECUTE - -The `EXECUTE` command executes an SPL procedure from EDB\*Plus. - -```text -EXEC[UTE ] spl_procedure [ ([ parameters ]) ] -``` - -`spl_procedure` - - The name of the SPL procedure to be executed. - -`parameters` - - Comma-delimited list of parameters. If there are no parameters, then a pair of empty parentheses may optionally be specified. - -## EXIT - -The `EXIT` command terminates the EDB\*Plus session and returns control to the operating system. `QUIT` is a synonym for `EXIT`. Specifying no parameters is equivalent to `EXIT SUCCESS COMMIT`. - -```text -{ EXIT | QUIT } -[ SUCCESS | FAILURE | WARNING | value | variable ] -[ COMMIT | ROLLBACK ]SUCCESS | FAILURE |WARNING] -``` - -Returns an operating system dependent return code indicating successful operation, failure, or warning for `SUCCESS, FAILURE`, and `WARNING`, respectively. The default is `SUCCESS`. - -`value` - - An integer value that is returned as the return code. - -`variable` - - A variable created with the `DEFINE` command whose value is returned as the return code. - -`COMMIT | ROLLBACK` - - If `COMMIT` is specified, uncommitted updates are committed upon exit. If `ROLLBACK` is specified, uncommitted updates are rolled back upon exit. The default is `COMMIT`. - -## GET - -The `GET` command loads the contents of the given file to the SQL buffer. - -```text -GET filename[.ext ] [ LIS[T ] | NOL[IST ] ] -``` - -`filename[.ext ]` - - `filename` is the name of the file to load into the SQL buffer. `ext` is the filename extension. If the filename extension is `sql`, then the `.sql` extension may be omitted when specifying `filename`. `GET` always assumes a `.sql` extension on filenames that are specified with no extension. - -`LIST | NOLIST` - - If `LIST` is specified, the content of the SQL buffer is displayed after the file is loaded. If `NOLIST` is specified, no listing is displayed. The default is `LIST`. - -## HELP - -The `HELP` command obtains an index of topics or help on a specific topic. The question mark `(?)` is synonymous with specifying `HELP`. - -```text -{ HELP | ? } { INDEX | topic } -``` - -`INDEX` - - Displays an index of available topics. - -`topic` - - The name of a specific topic – e.g., an EDB\*Plus command, for which help is desired. - -## HOST - -The `HOST` command executes an operating system command from EDB\*Plus. - -```text -HO[ST ] [os_command] -``` - -`os_command` - - The operating system command to be executed. If you do not provide an operating system command, EDB\*Plus pauses execution and opens a new shell prompt. When the shell exits, EDB\*Plus resumes execution. - -## INPUT - -The `INPUT` line editor command adds a line of text to the SQL buffer after the current line. - -```text -I[NPUT ] text -``` - -The following sequence of `INPUT` commands constructs a `SELECT` command. - -```text -SQL> INPUT SELECT empno, ename, job, sal, comm -SQL> INPUT FROM emp -SQL> INPUT WHERE deptno = 20 -SQL> INPUT ORDER BY empno -SQL> LIST - 1 SELECT empno, ename, job, sal, comm - 2 FROM emp - 3 WHERE deptno = 20 - 4* ORDER BY empno -``` - -## LIST - -`LIST` is a line editor command that displays the contents of the SQL buffer. - -```text -L[IST] [ n | n m | n * | n L[AST] | * | * n | * L[AST] | L[AST] ] -``` - -The buffer does not include a history of the EDB\*Plus commands. - -`n` - - `n` represents the buffer line number. - -`n m` - - `n m` displays a list of lines between `n` and `m`. - -`n *` - - `n *` displays a list of lines that range between line `n` and the current line. - -`n L[AST]` - - `n L[AST]` displays a list of lines that range from line `n` through the last line in the buffer. - -`*` - - `*` displays the current line. - -`* n` - - `* n` displays a list of lines that range from the current line through line `n`. - -`* L[AST]` - - `* L[AST]` displays a list of lines that range from the current line through the last line. - -`L[AST]` - - `L[AST]` displays the last line. - -## PASSWORD - -Use the `PASSWORD` command to change your database password. - -```text -PASSW[ORD] [user_name] -``` - -You must have sufficient privileges to use the `PASSWORD` command to change another user's password. The following example demonstrates using the `PASSWORD` command to change the password for a user named `acctg`: - -```text -SQL> PASSWORD acctg -Changing password for acctg - New password: - New password again: -Password successfully changed. -``` - -## PAUSE - -The `PAUSE` command displays a message, and waits for the user to press `ENTER`. - -```text -PAU[SE] [optional_text] -``` - -`optional_text` specifies the text that will be displayed to the user. If the `optional_text` is omitted, Advanced Server will display two blank lines. If you double quote the `optional_text` string, the quotes will be included in the output. - -## PROMPT - -The `PROMPT` command displays a message to the user before continuing. - -```text -PRO[MPT] [message_text] -``` - -`message_text` specifies the text displayed to the user. Double quote the string to include quotes in the output. - -## QUIT - -The `QUIT` command terminates the session and returns control to the operating system. `QUIT` is a synonym for `EXIT`. - -```text -QUIT - -[SUCCESS | FAILURE | WARNING | value | sub_variable] - -[COMMIT | ROLLBACK] -``` - -The default value is `QUIT SUCCESS COMMIT`. - -## REMARK - -Use `REMARK` to include comments in a script. - -```text -REM[ARK] [optional_text] -``` - -You may also use the following convention to include a comment: - -```text -/* - * This is an example of a three line comment. - */ -``` - -## SAVE - -Use the `SAVE` command to write the SQL Buffer to an operating system file. - -```text -SAV[E] file_name -[CRE[ATE] | REP[LACE] | APP[END]] -``` - -`file_name` - - `file_name` specifies the name of the file (including the path) where the buffer contents are written. If you do not provide a file extension, `.sql` is appended to the end of the file name. - -`CREATE` - - Include the `CREATE` keyword to create a new file. A new file is created *only* if a file with the specified name does not already exist. This is the default. - -`REPLACE` - - Include the `REPLACE` keyword to specify that Advanced Server should overwrite an existing file. - -`APPEND` - - Include the `APPEND` keyword to specify that Advanced Server should append the contents of the SQL buffer to the end of the specified file. - -The following example saves the contents of the SQL buffer to a file named `example.sql`, located in the `temp` directory: - -```text -SQL> SAVE C:\example.sql CREATE -File "example.sql" written. -``` - -## SET - -Use the `SET` command to specify a value for a session level variable that controls EDB\*Plus behavior. The following forms of the `SET` command are valid: - -**SET AUTOCOMMIT** - -Use the `SET AUTOCOMMIT` command to specify commit behavior for Advanced Server transactions. - -```text -SET AUTO[COMMIT] - -{ON | OFF | IMMEDIATE | statement_count} -``` - -Please note that EDB\*Plus always automatically commits DDL statements. - -`ON` - - Specify `ON` to turn `AUTOCOMMIT` behavior on. - -`OFF` - - Specify `OFF` to turn `AUTOCOMMIT` behavior off. - -`IMMEDIATE` - - `IMMEDIATE` has the same effect as `ON`. - -`statement_count` - - Include a value for `statement_count` to instruct EDB\*Plus to issue a commit after the specified count of successful SQL statements. - -**SET COLUMN SEPARATOR** - -Use the `SET COLUMN SEPARATOR` command to specify the text that Advanced Server displays between columns. - -```text -SET COLSEP column_separator -``` - -The default value of `column_separator` is a single space. - -**SET ECHO** - -Use the `SET ECHO` command to specify if SQL and EDB\*Plus script statements should be displayed onscreen as they are executed. - -```text -SET ECHO {ON | OFF} -``` - -The default value is `OFF`. - -**SET FEEDBACK** - -The `SET FEEDBACK` command controls the display of interactive information after a SQL statement executes. - -```text -SET FEED[BACK] {ON | OFF | row_threshold} -``` - -`row_threshold` - - Specify an integer value for `row_threshold`. Setting `row_threshold` to `0` is same as setting `FEEDBACK` to `OFF`. Setting `row_threshold` equal `1` effectively sets `FEEDBACK` to `ON`. - -**SET FLUSH** - -Use the `SET FLUSH` command to control display buffering. - -```text -SET FLU[SH] {ON | OFF} -``` - -Set `FLUSH` to `OFF` to enable display buffering. If you enable buffering, messages bound for the screen may not appear until the script completes. Please note that setting `FLUSH` to `OFF` will offer better performance. - -Set `FLUSH` to `ON` to disable display buffering. If you disable buffering, messages bound for the screen appear immediately. - -**SET HEADING** - -Use the `SET HEADING` variable to specify if Advanced Server should display column headings for `SELECT` statements. - -```text -SET HEA[DING] {ON | OFF} -``` - -**SET HEAD SEPARATOR** - -The `SET HEADSEP` command sets the new heading separator character used by the `COLUMN HEADING` command. The default is `'|'`. - -```text -SET HEADS[EP] -``` - -**SET LINESIZE** - -Use the `SET LINESIZE` command to specify the width of a line in characters. - -```text -SET LIN[ESIZE] width_of_line -``` - -`width_of_line` - - The default value of `width_of_line` is `132`. - -**SET NEWPAGE** - -Use the `SET NEWPAGE` command to specify how many blank lines are printed after a page break. - -```text -SET NEWP[AGE] lines_per_page -``` - -`lines_per_page` - - The default value of `lines_per_page` is `1`. - -**SET NULL** - -Use the `SET NULL` command to specify a string that is displayed to the user when a `NULL` column value is displayed in the output buffer. - -```text -SET NULL null_string -``` - -**SET PAGESIZE** - -Use the `SET PAGESIZE` command to specify the number of printed lines that fit on a page. - -```text -SET PAGES[IZE] line_count -``` - -Use the `line_count` parameter to specify the number of lines per page. - -**SET SQLCASE** - -The `SET SQLCASE` command specifies if SQL statements transmitted to the server should be converted to upper or lower case. - -```text -SET SQLC[ASE] {MIX[ED] | UP[PER] | LO[WER]} -``` - -`UPPER` - - Specify `UPPER` to convert the command text to uppercase. - -`LOWER` - - Specify `LOWER` to convert the command text to lowercase. - -`MIXED` - - Specify `MIXED` to leave the case of SQL commands unchanged. The default is `MIXED`. - -**SET PAUSE** - -The `SET PAUSE` command is most useful when included in a script; the command displays a prompt and waits for the user to press `Return`. - -```text -SET PAU[SE] {ON | OFF} -``` - -If `SET PAUSE` is `ON`, the message `Hit ENTER to continue…` will be displayed before each command is executed. - -**SET SPACE** - -Use the `SET SPACE` command to specify the number of spaces to display between columns: - -```text -SET SPACE number_of_spaces -``` - -**SET SQLPROMPT** - -Use `SET SQLPROMPT` to set a value for a user-interactive prompt: - -```text -SET SQLP[ROMPT] "prompt" -``` - -By default, `SQLPROMPT` is set to `"SQL> "` - -**SET TERMOUT** - -Use the `SET TERMOUT` command to specify if command output should be displayed onscreen. - -```text -SET TERM[OUT] {ON | OFF} -``` - -**SET TIMING** - -The `SET TIMING` command specifies if Advanced Server should display the execution time for each SQL statement after it is executed. - -```text -SET TIMI[NG] {ON | OFF} -``` - -**SET TRIMSPOOL** - -Use the `SET TRIMSPOOL` command to remove trailing spaces from each line in the output file specified by the `SPOOL` command. - -```text -SET TRIMS[POOL] {ON | OFF} -``` - -The default value is `OFF`. - -**SET VERIFY** - -Specifies if both the old and new values of a SQL statement are displayed when a substitution variable is encountered. - -```text -SET VER[IFY] { ON | OFF } -``` - -## SHOW - -Use the `SHOW` command to display current parameter values. - -```text -SHO[W] {ALL | parameter_name} -``` - -Display the current parameter settings by including the `ALL` keyword: - -```Text -SQL> SHOW ALL -autocommit OFF -colsep " " -define "&" -echo OFF -FEEDBACK ON for 6 row(s). -flush ON -heading ON -headsep "|" -linesize 78 -newpage 1 -null " " -pagesize 14 -pause OFF -serveroutput OFF -spool OFF -sqlcase MIXED -sqlprompt "SQL> " -sqlterminator ";" -suffix ".sql" -termout ON -timing OFF -verify ON -USER is "enterprisedb" -HOST is "localhost" -PORT is "5444" -DATABASE is "edb" -VERSION is "12.0.0" -``` - -Or display a specific parameter setting by including the `parameter_name` in the `SHOW` command: - -```text -SQL> SHOW VERSION -VERSION is "12.0.0" -``` - -## SPOOL - -The `SPOOL` command sends output from the display to a file. - -```text -SP[OOL] output_file | OFF -``` - -Use the `output_file` parameter to specify a path name for the output file. - -## START - -Use the `START` command to run an EDB\*Plus script file; `START` is an alias for `@` command. - -```text -STA[RT] script_file -``` - -Specify the name of a script file in the `script_file` parameter. - -## UNDEFINE - -The `UNDEFINE` command erases a user variable created by the `DEFINE` command. - -```text -UNDEF[INE] variable_name [ variable_name...] -``` - -Use the `variable_name` parameter to specify the name of a variable or variables. - -## WHENEVER SQLERROR - -The `WHENEVER SQLERROR` command provides error handling for SQL errors or PL/SQL block errors. The syntax is: - -```text -WHENEVER SQLERROR - {CONTINUE[COMMIT|ROLLBACK|NONE] - |EXIT[SUCCESS|FAILURE|WARNING|n|sub_variable] - [COMMIT|ROLLBACK]} -``` - -If Advanced Server encounters an error during the execution of a SQL command or PL/SQL block, EDB\*Plus performs the action specified in the `WHENEVER SQLERROR` command: - - Include the `CONTINUE` clause to instruct EDB\*Plus to perform the specified action before continuing. - - Include the `COMMIT` clause to instruct EDB\*Plus to `COMMIT` the current transaction before exiting or continuing. - - Include the `ROLLBACK` clause to instruct EDB\*Plus to `ROLLBACK` the current transaction before exiting or continuing. - - Include the `NONE` clause to instruct EDB\*Plus to continue without committing or rolling back the transaction. - - Include the `EXIT` clause to instruct EDB\*Plus to perform the specified action and exit if it encounters an error. - - Use the following options to specify a status code that EDB\*Plus will return before exiting: - -```text -[SUCCESS|FAILURE|WARNING|n|sub_variable] -``` - - Please note that EDB\*Plus supports substitution variables, but does not support bind variables. diff --git a/product_docs/docs/edb_plus/38/images/advanced_server_installation_details.png b/product_docs/docs/edb_plus/38/images/advanced_server_installation_details.png deleted file mode 100755 index 3638e7d551f..00000000000 --- a/product_docs/docs/edb_plus/38/images/advanced_server_installation_details.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:a9c152dfd15132f11750917e10b0a8dd3646bfcf5f4d9a3525066f68ebd807d3 -size 19239 diff --git a/product_docs/docs/edb_plus/38/images/edb_plus_welcome.png b/product_docs/docs/edb_plus/38/images/edb_plus_welcome.png deleted file mode 100755 index c526c78eabf..00000000000 --- a/product_docs/docs/edb_plus/38/images/edb_plus_welcome.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:4f557131b686992e3d8a9f7d0f40ddd14dcdde8a6ee7fb90af3ef57860194024 -size 56911 diff --git a/product_docs/docs/edb_plus/38/images/edb_plus_welcome_1.png b/product_docs/docs/edb_plus/38/images/edb_plus_welcome_1.png deleted file mode 100755 index ea2a26270ab..00000000000 --- a/product_docs/docs/edb_plus/38/images/edb_plus_welcome_1.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:2b1c56ab042cb3f2ea94a6fc8177bb9176fdd0bc42ca36e23c43594993dd6637 -size 34974 diff --git a/product_docs/docs/edb_plus/38/images/installation_complete.png b/product_docs/docs/edb_plus/38/images/installation_complete.png deleted file mode 100755 index 30281ba5583..00000000000 --- a/product_docs/docs/edb_plus/38/images/installation_complete.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:3836a996fa7052af22f4a23e24903594d4edf866c3e2696a6cbc0de8f1db4e03 -size 37674 diff --git a/product_docs/docs/edb_plus/38/images/installation_directory.png b/product_docs/docs/edb_plus/38/images/installation_directory.png deleted file mode 100755 index 4955f065d23..00000000000 --- a/product_docs/docs/edb_plus/38/images/installation_directory.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:0665e04df295f27a6f846cbeba326697eddc760ba96404b98a77b11e27c516f8 -size 89526 diff --git a/product_docs/docs/edb_plus/38/images/ready_to_install.png b/product_docs/docs/edb_plus/38/images/ready_to_install.png deleted file mode 100755 index a73f573adc5..00000000000 --- a/product_docs/docs/edb_plus/38/images/ready_to_install.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:ddd7dc4e8a4a8e40f9194e5f7971d3fc01c9c6130de1d3a62fc528a2a018c666 -size 15785 diff --git a/product_docs/docs/edb_plus/38/index.mdx b/product_docs/docs/edb_plus/38/index.mdx deleted file mode 100644 index 7d8bef86375..00000000000 --- a/product_docs/docs/edb_plus/38/index.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "EDB*Plus" -description: EDB\*Plus provides a command line user interface to EDB Postgres Advanced Server. -navTitle: EDB*Plus - ---- - -EDB\*Plus is a utility program that provides a command line user interface to EDB Postgres Advanced Server. EDB\*Plus accepts SQL commands, SPL anonymous blocks, and EDB\*Plus commands. - -EDB\*Plus commands are compatible with Oracle SQL\*Plus commands and provide various capabilities including: - -- Querying certain database objects -- Executing stored procedures -- Formatting output from SQL commands -- Executing batch scripts -- Executing OS commands -- Recording output diff --git a/product_docs/docs/edb_plus/39/02a_release_notes/07_edbplus39.03_rel_notes.mdx b/product_docs/docs/edb_plus/39/02a_release_notes/07_edbplus39.03_rel_notes.mdx deleted file mode 100644 index 596c9b576ab..00000000000 --- a/product_docs/docs/edb_plus/39/02a_release_notes/07_edbplus39.03_rel_notes.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -navTitle: Version 39.0.3 -title: "EDB*Plus Version 39.0.3 Release Notes" ---- - -New features, enhancements, bug fixes, and other changes in EDB*Plus 39.0.3 include: - -| Type | Description | -| ------------ | ---------------------------------------------------------------------------------------| -| Security Fix | The EDB JDBC Driver in EDB*Plus is upgraded to version 42.3.2.1. This upgrade fixes the CVE-2022-21724 vulnerability reported in older versions of EDB JDBC Driver. | diff --git a/product_docs/docs/edb_plus/39/02a_release_notes/08_edbplus39.02_rel_notes.mdx b/product_docs/docs/edb_plus/39/02a_release_notes/08_edbplus39.02_rel_notes.mdx deleted file mode 100644 index 348de4fd2af..00000000000 --- a/product_docs/docs/edb_plus/39/02a_release_notes/08_edbplus39.02_rel_notes.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Version 39.0.2 ---- - -New features, enhancements, bug fixes, and other changes in EDB*Plus 39.0.2 include: - -| Type | Description | -| ------------ | ---------------------------------------------------------------------------------------| -| Enhancement | The display format for a decimal point is now compatible with Oracle SQL*Plus [75092]. | -| Bug Fix | Describe command no longer fails for a schema qualified SYNONYM name [72994]. | - diff --git a/product_docs/docs/edb_plus/39/02a_release_notes/09_edbplus39.01_rel_notes.mdx b/product_docs/docs/edb_plus/39/02a_release_notes/09_edbplus39.01_rel_notes.mdx deleted file mode 100644 index 51fbacf2f1e..00000000000 --- a/product_docs/docs/edb_plus/39/02a_release_notes/09_edbplus39.01_rel_notes.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Version 39.0.1 ---- - -New features, enhancements, bug fixes, and other changes in EDB*Plus 39.0.1 include: - -| Type | Description | -| ------- | ----------------------------------------------------------------------------------------------------------------- | -| Bug Fix | Correction to handle single quotes [‘] properly in the script output. | -| Bug Fix | Correct line number being reported for the error encountered related to the execution of the procedure/code. | -| Bug Fix | Prompt user to enter the password on the second attempt. | -| Bug Fix | Help index now loads the “edbPLUS” topic. | diff --git a/product_docs/docs/edb_plus/39/02a_release_notes/10_edbplus39.00_rel_notes.mdx b/product_docs/docs/edb_plus/39/02a_release_notes/10_edbplus39.00_rel_notes.mdx deleted file mode 100644 index c8799f538a7..00000000000 --- a/product_docs/docs/edb_plus/39/02a_release_notes/10_edbplus39.00_rel_notes.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Version 39.0.0" ---- - -New features, enhancements, bug fixes, and other changes in EDB*Plus 39.00 include: - -| Type | Description | -| ----------- | -------------------------------------------------------------- | -| Enhancement | Support for EDB Postgres Advanced Server 13.1.4. | \ No newline at end of file diff --git a/product_docs/docs/edb_plus/39/02a_release_notes/index.mdx b/product_docs/docs/edb_plus/39/02a_release_notes/index.mdx deleted file mode 100644 index 841b94d5dd2..00000000000 --- a/product_docs/docs/edb_plus/39/02a_release_notes/index.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Release Notes" ---- - -EDB\*Plus is a utility program that provides a command line user interface to EDB Postgres Advanced Server. - -The EDB\*Plus documentation describes the latest version of EDB\*Plus Version 39. The release notes in this section provide information on what was new in each release. - -| Version | Release Date | -| -------------------------------------- | ------------ | -| [39.0.3](07_edbplus39.03_rel_notes.mdx)| 2022 Mar 10 | -| [39.0.2](08_edbplus39.02_rel_notes.mdx)| 2022 Feb 18 | -| [39.0.1](09_edbplus39.01_rel_notes.mdx)| 2021 Aug 12 | -| [39.0.0](10_edbplus39.00_rel_notes.mdx)| 2020 Dec 12 | \ No newline at end of file diff --git a/product_docs/docs/edb_plus/39/03_installing_edb_plus.mdx b/product_docs/docs/edb_plus/39/03_installing_edb_plus.mdx deleted file mode 100644 index a750e8838a6..00000000000 --- a/product_docs/docs/edb_plus/39/03_installing_edb_plus.mdx +++ /dev/null @@ -1,382 +0,0 @@ ---- -title: "Installing EDB*Plus" -redirects: - - "01_installing_prereq" - - "02_rpm_installation" - - "03_using_gui" -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/39/installing_edb_plus.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/38/installing_edb_plus.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-guide/36/installing_edb_plus.html" ---- - - - -This table lists the EDB*Plus versions and their supported corresponding EDB Postgres Advanced Server (EPAS) versions. EDB\*Plus is supported on the same platforms as EDB Postgres Advanced Server. See [Product Compatibility](https://www.enterprisedb.com/platform-compatibility#epas) for details. - -| EDB*Plus | EPAS 14 | EPAS 13 | EPAS 12 | EPAS 11 | EPAS 10 | -| -------- | ------- | ------- | ------- | ------- | ------- | -| 39 | N | Y | Y | Y | Y | -| 38 | N | Y | Y | Y | Y | -| 37 | N | N | Y | Y | Y | -| 36 | N | N | N | Y | Y | - - -You can use an RPM installer or a graphical installer to add EDB\*Plus to your Advanced Server installation. - -## Installation Prerequisites - -Before installing EDB\*Plus, you must first install Java (version 1.8 or later). On a Linux system, you can use the `yum` package manager to install Java. Open a terminal window, assume superuser privileges, and enter: - -- On RHEL or CentOS 7: - - ```text - # yum -y install java - ``` - -- On RHEL/Rocky Linux/AlmaLinux 8: - - ```text - # dnf -y install java - ``` - -If you are using Windows, Java installers and instructions are available online at: - - - -You must also have credentials that allow access to the EDB repository. For information about requesting credentials, visit: - - - -After receiving your repository credentials: - -1. Create the repository configuration file. -2. Modify the file, providing your user name and password. -3. Install EDB\*Plus. - -For detailed information about creating and using EDB repositories to install Advanced Server or its supporting components, see the *EDB Postgres Advanced Server Installation Guide* available at: - -[https://www.enterprisedb.com/docs](/epas/latest/) - -## Installing EDB\*Plus on a CentOS Host - -You can use an RPM package to install EDB\*Plus on a CentOS host. - -- To install the repository configuration file, assume superuser privileges, and invoke one of the following platform-specific commands: - - On CentOS 7: - - ```text - yum -y install https://yum.enterprisedb.com/edbrepos/edb-repo-latest.noarch.rpm - ``` - - On Rocky Linux/AlmaLinux 8: - - ```text - dnf -y install https://yum.enterprisedb.com/edbrepos/edb-repo-latest.noarch.rpm - ``` - -- Replace the `USERNAME:PASSWORD` variable in the following command with the username and password of a registered EDB user: - - ```text - sed -i "s@:@USERNAME:PASSWORD@" /etc/yum.repos.d/edb.repo - ``` - -- Before installing EDB\*Plus, you must install the `epel-release` package: - - On CentOS 7: - - ```text - yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm - ``` - - On Rocky Linux/AlmaLinux 8: - - ```text - dnf -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm - ``` - -- For Rocky Linux/AlmaLinux 8, enable the PowerTools repository to satisfy package dependencies: - - ```text - dnf config-manager --set-enabled PowerTools - ``` - -- The repository configuration file is named `edb.repo`. The file resides in `/etc/yum.repos.d`. After saving your changes to the configuration file, you can use the following command to install EDB\*Plus: - - On CentOS 7: - - ```text - yum -y install edb-asxx-edbplus - ``` - - On Rocky Linux/AlmaLinux 8: - - ```text - dnf -y install edb-asxx-edbplus - ``` - -Where, `xx` is the Advanced Server version. - -When you install an RPM package that is signed by a source that is not recognized by your system, `yum` may ask for your permission to import the key to your local server. If prompted, and you are satisfied that the packages come from a trustworthy source, enter `y`, and press `Return` to continue. - -During the installation, `yum` may encounter a dependency that it cannot resolve. If it does, it will provide a list of the required dependencies that you must manually resolve. - -## Installing EDB\*Plus on a RHEL Host - -You can use an RPM package to install EDB\*Plus on a RHEL host. - -- To install the repository configuration file, assume superuser privileges, and invoke one of the following platform-specific commands: - - On RHEL 7: - - ```text - yum -y install https://yum.enterprisedb.com/edbrepos/edb-repo-latest.noarch.rpm - ``` - - On RHEL 8: - - ```text - dnf -y install https://yum.enterprisedb.com/edbrepos/edb-repo-latest.noarch.rpm - ``` - -- Replace the `USERNAME:PASSWORD` variable in the following command with the username and password of a registered EDB user: - - ```text - sed -i "s@:@USERNAME:PASSWORD@" /etc/yum.repos.d/edb.repo - ``` - -- Before installing EDB\*Plus, you must install the `epel-release` package: - - On RHEL 7: - - ```text - yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm - ``` - - On RHEL 8: - - ```text - dnf -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm - ``` - -- Enable the repository: - - On RHEL7, enable the `optional, extras`, and `HA` repositories to satisfy package dependencies: - - ```text - subscription-manager repos --enable "rhel-*-optional-rpms" --enable "rhel-*-extras-rpms" --enable "rhel-ha-for-rhel-*-server-rpms" - ``` - - On RHEL 8, enable the `codeready-builder-for-rhel-8-*-rpms` repository to satisfy package dependencies: - - ```text - ARCH=$( /bin/arch ) - - subscription-manager repos --enable "codeready-builder-for-rhel-8-${ARCH}-rpms" - ``` - -- The repository configuration file is named `edb.repo`. The file resides in `/etc/yum.repos.d`. After saving your changes to the configuration file, you can use the following command to install EDB\*Plus: - - On RHEL 7: - - ```text - yum -y install edb-asxx-edbplus - ``` - - On RHEL 8: - - ```text - dnf -y install edb-asxx-edbplus - ``` - -Where, `xx` is the Advanced Server version. - -When you install an RPM package that is signed by a source that is not recognized by your system, `yum` may ask for your permission to import the key to your local server. If prompted, and you are satisfied that the packages come from a trustworthy source, enter `y`, and press `Return` to continue. - -During the installation, `yum` may encounter a dependency that it cannot resolve. If it does, it will provide a list of the required dependencies that you must manually resolve. - - -## Installing EDB\*Plus on a Debian or Ubuntu Host - -To install EDB\*Plus on a Debian or Ubuntu host, you must have credentials that allow access to the EDB repository. To request credentials for the repository, visit: - - - -The following steps will walk you through using the EDB apt repository to install a debian package. When using the commands, replace the `username` and `password` with the credentials provided by EDB. - -- Assume superuser privileges: - - ```text - sudo su - - ``` - -- Configure the EDB repository: - - On Ubuntu 18, and Ubuntu 20: - - ```text - sh -c 'echo "deb https://USERNAME:PASSWORD@apt.enterprisedb.com/$(lsb_release -cs)-edb/ $(lsb_release -cs) main" > /etc/apt/sources.list.d/edb-$(lsb_release -cs).list' - ``` - - On Debian 10: - - a. Set up the EDB repository: - - ```text - sh -c 'echo "deb [arch=amd64] https://apt.enterprisedb.com/$(lsb_release -cs)-edb/ $(lsb_release -cs) main" > /etc/apt/sources.list.d/edb-$(lsb_release -cs).list' - ``` - - b. Substitute your EDB credentials for the `username` and `password` placeholders in the following command: - - ```text - sh -c 'echo "machine apt.enterprisedb.com login password " > /etc/apt/auth.conf.d/edb.conf' - ``` - -- Add support to your system for secure APT repositories: - - ```text - apt-get -y install apt-transport-https - ``` - -- Add the EDB signing key: - - ```text - wget -q -O - https://apt.enterprisedb.com/edb-deb.gpg.key | sudo apt-key add - - ``` - -- Update the repository metadata: - - ```text - apt-get update - ``` - -- Install Debian package: - - ```text - apt-get -y install edb-asxx-edbplus - ``` - -Where, `xx` is the Advanced Server version. - -## Configuring an RPM Installation - -After performing an RPM installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation. Use the following commands to set variable values: - -```text -export JAVA_HOME= -export PATH=/bin:$PATH -``` - -By default, the `pg_hba.conf` file for the RPM installer enforces `IDENT` authentication. Before invoking EDB\*Plus, you must either modify the `pg_hba.conf` file, changing the authentication method to a form other than `IDENT` (and restarting the server), or perform the following steps to ensure that an `IDENT` server is accessible: - -You must confirm that an `identd` server is installed and running. You can use the `yum` package manager to install an `identd` server by invoking the command: - -- On RHEL or CentOS 7: - - ```text - yum -y install xinetd authd - ``` - -- On RHEL/Rocky Linux/AlmaLinux 8: - - ```text - dnf -y install xinetd authd - ``` - -The command should create a file named `/etc/xinetd.d/auth` that contains: - -```text -service auth -{ - disable = yes - socket_type = stream -wait =no -user = ident -cps = 4096 10 -instances = UNLIMITED -server = /usr/sbin/in.authd server_args = -t60 --xerror –os -} -``` - -!!! Note - If the file includes a `-E` argument at the end of the server arguments, please erase `-E`. - -Then, to start the `identd` server, invoke the following commands: - -```text -systemctl enable xinetd -systemctl start xinetd -``` - -Open the `pg_ident.conf` file and create a user mapping: - -```text -# map_name system_username postgres_username - edbas enterprisedb enterprisedb -``` - -Where: - -- The name specified in the `map_name` column is a user-defined name that will identify the mapping in the `pg_hba.conf` file. -- The name specified in the `system_username` column is `enterprisedb`. -- The name specified in the `postgres_username` column is `enterprisedb`. - -Then, open the `pg_hba.conf` file and modify the `IDENT` entries: - -- If you are using an IPv4 local connection, modify the file entry to read: - - `host all all 127.0.0.0/0 ident map=edbas` - -- If you are using an IPv6 local connection, modify the file entry to read: - - `host all all ::1/128 ident map=edbas` - -You must restart the Advanced Server service before invoking EDB\*Plus. For detailed information about controlling the Advanced Server service, see the *EDB Postgres Advanced Server Installation Guide*, available at: - -[https://www.enterprisedb.com/docs](/epas/latest/) - -## Using the Graphical Installer - -Graphical installers for EDB\*Plus are available via StackBuilder Plus; you can access StackBuilder Plus through your Windows or Linux start menu. After opening StackBuilder Plus and selecting the installation for which you wish to install EDB\*Plus, expand the component selection screen tree control to select and download the EDB\*Plus installer. - -![The EDBPlus Welcome window*](images/edb_plus_welcome.png) - -
Fig. 1: The EDB*Plus Welcome window
- - -The EDB\*Plus installer welcomes you to the setup wizard, as shown in the figure below. - -![The Installation Directory window](images/installation_directory.png) - -
Fig. 2: The Installation Directory window
- - -Use the `Installation Directory` field to specify the directory in which you wish to install the EDB\*Plus software. Then, click `Next` to continue. - -![The Advanced Server Installation Details window](images/advanced_server_installation_details.png) - -
Fig. 3: The Advanced Server Installation Details window
- - -Use fields on the `EDB Postgres Advanced Server Installation Details` window to identify the location of the Advanced Server host: - -- Use the `Host` field to identify the system on which Advanced Server resides. -- Use the `Port` field to identify the listener port that Advanced Server monitors for client connections. - -Then, click `Next` to continue. - -![The Ready to Install window](images/ready_to_install.png) - -
Fig. 4: The Ready to Install window
- - -The `Ready to Install` window notifies you when the installer has all of the information needed to install EDB\*Plus on your system. Click `Next` to install EDB\*Plus. - -![The installation is complete](images/installation_complete.png) - -
Fig. 5: The installation is complete
- - -The installer notifies you when the setup wizard has completed the EDB\*Plus installation. Click `Finish` to exit the installer. diff --git a/product_docs/docs/edb_plus/39/04_using_edb_plus.mdx b/product_docs/docs/edb_plus/39/04_using_edb_plus.mdx deleted file mode 100644 index 34cafc0a8ae..00000000000 --- a/product_docs/docs/edb_plus/39/04_using_edb_plus.mdx +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: "Using EDB*Plus" -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/39/using_edb_plus.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/38/using_edb_plus.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-guide/36/using_edb_plus.html" ---- - - - - - -To open an EDB\*Plus command line, navigate through the `Applications` or `Start` menu to the Advanced Server menu, to the `Run SQL Command Line` menu, and select the EDB\*Plus option. You can also invoke EDB\*Plus from the operating system command line with the following command: - -```text -edbplus [ -S[ILENT ] ] [ | /NOLOG ] [ @[. ] ] -``` - -`SILENT` - - If specified, the EDB\*Plus sign-on banner is suppressed along with all prompts. - -`login` - - Login information for connecting to the database server and database. `login` takes the following form; there must be no white space within the login information. - -```text -[/][@{ | } ] -``` - - Where: - - `username` is a database username with which to connect to the database. - - `password` is the password associated with the specified `username`. If a `password` is not provided, but a password is required for authentication, a password file is used if available. If there is no password file or no entry in the password file with the matching connection parameters, then EDB\*Plus will prompt for the password. - - `connectstring` is the database connection string with the following format: - -```text -[:][/][?ssl={true | false}] -``` - - Where: - - `host` is the hostname or IP address on which the database server resides. If neither `@connectstring` nor `@variable` nor `/NOLOG` is specified, the default host is assumed to be the localhost. `port` is the port number receiving connections on the database server. If not specified, the default is `5444`. `dbname` is the name of the database to connect to. If not specified the default is `edb`. If `Internet Protocol version 6` (IPv6) is used for the connection instead of IPv4, then the IP address must be enclosed within square brackets (that is, `[ipv6_address]`). The following is an example using an IPv6 connection: - -```text -edbplus.sh enterprisedb/password@[fe80::20c:29ff:fe7c:78b2]:5444/edb -``` - - The `pg_hba.conf` file for the database server must contain an appropriate entry for the IPv6 connection. The following example shows an entry that allows all addresses: - -```text -# TYPE DATABASE USER ADDRESS METHOD -host all all ::0/0 md5 -``` - -For more information about the `pg_hba.conf` file, see the PostgreSQL core documentation at: - - - - If an SSL connection is desired, then include the `?ssl=true` parameter in the connection string. In such a case, the connection string must minimally include `host:port`, with or without `/dbname`. If the `ssl` parameter is not specified, the default is `false`. See [Using a Secure Sockets Layer (SSL) Connection](05_using_edb_plus_with_ssl/#using_edb_plus_with_ssl) for instructions on setting up an SSL connection. - - `variable` is a variable defined in the `login.sql` file that contains a database connection string. The `login.sql` file can be found in the `edbplus` subdirectory of the Advanced Server home directory. - -`/NOLOG` - - Specify `/NOLOG` to start EDB\*Plus without establishing a database connection. SQL commands and EDB\*Plus commands that require a database connection cannot be used in this mode. The `CONNECT` command can be subsequently given to connect to a database after starting EDB\*Plus with the `/NOLOG` option. - -`scriptfile[.ext ]` - - `scriptfile` is the name of a file residing in the current working directory, containing SQL and/or EDB\*Plus commands that will be automatically executed after startup of EDB\*Plus. `ext` is the filename extension. If the filename extension is `sql`, then the `.sql` extension may be omitted when specifying `scriptfile`. When creating a script file, always name the file with an extension, otherwise it will not be accessible by EDB\*Plus. (EDB\*Plus will always assume a `.sql` extension on filenames that are specified with no extension.) - -!!! note - When you run the commands in the following examples you may be using a newer version of EDB\*Plus and as such the EDB\*Plus build number shown in your output may be different. - -The following example shows user `enterprisedb` with password `password`, connecting to database `edb` running on a database server on the `localhost` at port `5444`. - -```text -C:\Program Files\edb\as13\edbplus>edbplus enterprisedb/password -Connected to EnterpriseDB 13.1.4 (localhost:5444/edb) AS enterprisedb - -EDB*Plus: Release 13 (Build 39.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -The following example shows user `enterprisedb` with password, `password`, connecting to database `edb` running on a database server on the `localhost` at port `5445`. - -```text -C:\Program Files\edb\as13\edbplus>edbplus enterprisedb/password@localhost:5445/edb -Connected to EnterpriseDB 13.1.4 (localhost:5445/edb) AS enterprisedb - -EDB*Plus: Release 13 (Build 39.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -Using variable `hr_5445` in the `login.sql` file, the following illustrates how it is used to connect to database `hr` on localhost at port `5445`. - -```text -C:\Program Files\edb\as13\edbplus>edbplus enterprisedb/password@hr_5445 -Connected to EnterpriseDB 13.1.4 (localhost:5445/hr) AS enterprisedb - -EDB*Plus: Release 13 (Build 39.0.0) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -The following is the content of the `login.sql` file used in the previous example. - -```text -define edb="localhost:5445/edb" -define hr_5445="localhost:5445/hr" -``` - -The following example executes a script file, `dept_query.sql` after connecting to database `edb` on server localhost at port `5444`. - -```text -C:\Program Files\edb\as13\edbplus>edbplus enterprisedb/password @dept_query -Connected to EnterpriseDB 13.1.4 (localhost:5444/edb) AS enterprisedb - -SQL> SELECT * FROM dept; - -DEPTNO DNAME LOC ------- -------------- ------------- -10 ACCOUNTING NEW YORK -20 RESEARCH DALLAS -30 SALES CHICAGO -40 OPERATIONS BOSTON - -SQL> EXIT -Disconnected from EnterpriseDB Database. -``` - -The following is the content of file `dept_query.sql` used in the previous example. - -```text -SET PAGESIZE 9999 -SET ECHO ON -SELECT * FROM dept; -EXIT -``` diff --git a/product_docs/docs/edb_plus/39/05_using_edb_plus_with_ssl.mdx b/product_docs/docs/edb_plus/39/05_using_edb_plus_with_ssl.mdx deleted file mode 100644 index 7e3f07dd217..00000000000 --- a/product_docs/docs/edb_plus/39/05_using_edb_plus_with_ssl.mdx +++ /dev/null @@ -1,329 +0,0 @@ ---- -title: "Using a SSL Connection" -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/39/using_edb_plus_with_ssl.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/38/using_edb_plus_with_ssl.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-guide/36/using_edb_plus_with_ssl.html" ---- - - - - - -An EDB\*Plus connection to the Advanced Server database can be accomplished using secure sockets layer (SSL) connectivity. - -Using SSL requires various prerequisite configuration steps performed on the database server involved with the SSL connection as well as creation of the Java truststore and keystore on the host that will run EDB\*Plus. - -The Java *truststore* is the file containing the Certificate Authority (CA) certificates with which the Java client (EDB\*Plus) uses to verify the authenticity of the server to which it is initiating an SSL connection. - -The Java *keystore* is the file containing private and public keys and their corresponding certificates. The keystore is required for client authentication to the server, which is used for the EDB\*Plus connection. - -The following is material to which you can refer to for guidance in setting up the SSL connections: - -- For information on setting up SSL connectivity to the Advanced Server database, see the section about secure TCP connections with SSL in Chapter 18 “Server Setup and Operation” in the PostgreSQL Core Documentation located at: - - - -- For information on JDBC client connectivity using SSL, see the section on configuring the client in Chapter 4 “Using SSL” in The PostgreSQL JDBC Interface located at: - - - -The following sections provide information for the configuration steps of using SSL. - -- Configuring SSL on Advanced Server -- Configuring SSL for the EDB\*Plus client -- Requesting SSL connection to the Advanced Server database - -## Configuring SSL on Advanced Server - -This section provides an example of configuring SSL on a database server to demonstrate the use of SSL with EDB\*Plus. A self-signed certificate is used for this purpose. - -**Step 1:** Create the certificate signing request (CSR). - -In the following example the generated certificate signing request file is `server.csr`. The private key is generated as file `server.key`. - -```text -$ openssl req -new -nodes -text -out server.csr \ -> -keyout server.key -subj "/CN=enterprisedb" -Generating a 2048 bit RSA private key -.............................+++ -....................................................................+++ -writing new private key to 'server.key' ------ -``` - -!!! Note - When creating the certificate, the value specified for the common name field (designated as `CN=enterprisedb` in this example) must be the database user name that is specified when connecting to EDB\*Plus. - -In addition, user name maps can be used as defined in the `pg_ident.conf` file to permit more flexibility for the common name and database user name. Steps 8 and 9 describe the use of user name `maps`. - -**Step 2:** Generate the self-signed certificate. - -The following generates a self-signed certificate to file `server.crt` using the certificate signing request file, `server.csr`, and the private key, `server.key`, as input. - -```text -$ openssl x509 -req -days 365 -in server.csr -signkey server.key \ -> -out server.crt -Signature ok -subject=/CN=enterprisedb -Getting Private key -``` - -**Step 3:** Make a copy of the server certificate (`server.crt`) to be used as the root Certificate Authority (CA) file (`root.crt`). - -```text -$ cp server.crt root.crt -``` - -**Step 4:** Delete the now redundant certificate signing request (`server.csr`). - -```text -$ rm -f server.csr -``` - -**Step 5:** Move or copy the certificate and private key files to the Advanced Server data directory (for example, `/opt/edb/as13/data`). - -```text -$ mv root.crt /opt/edb/as13/data -$ mv server.crt /opt/edb/as13/data -$ mv server.key /opt/edb/as13/data -``` - -**Step 6:** Set the file ownership and permissions on the certificate files and private key file. - -Set the ownership to the operating system account that owns the data sub-directory of the database server. Set the permissions so that no other groups or accounts other than the owner can access these files. - -```text -$ chown enterprisedb root.crt server.crt server.key -$ chgrp enterprisedb root.crt server.crt server.key -$ chmod 600 root.crt server.crt server.key -$ ls -l -total 152 - . - . - . --rw------- 1 enterprisedb enterprisedb 985 Aug 22 11:00 root.crt --rw------- 1 enterprisedb enterprisedb 985 Aug 22 10:59 server.crt --rw------- 1 enterprisedb enterprisedb 1704 Aug 22 10:58 server.key -``` - -**Step 7:** In the `postgresql.conf` file, make the following modifications. - -```text -ssl = on -ssl_cert_file = 'server.crt' -ssl_key_file = 'server.key' -ssl_ca_file = 'root.crt' -``` - -**Step 8:** Modify the `pg_hba.conf` file to enable SSL usage on the desired database to which EDB\*Plus is to make the SSL connection. - -In the `pg_hba.conf` file, the `hostssl` type indicates the entry is used to validate SSL connection attempts from the client (EDB\*Plus). - -The authentication method is set to cert with the option `clientcert=1` in order to require an SSL certificate from the client against which authentication is performed using the common name of the certificate (`enterprisedb` in this example). - -The `map=sslusers` option specifies that a mapping named `sslusers` defined in the `pg_ident.conf` file is to be used for authentication. This mapping allows a connection to the database if the common name from the certificate and the database user name attempting the connection match the `SYSTEM-USERNAME/PG-USERNAME` pair listed in the `pg_ident.conf` file. - -The following is an example of the settings in the `pg_hba.conf` file if the database `(edb)` must use SSL connections. - -```text -# TYPE DATABASE USER ADDRESS METHOD - -# "local" is for Unix domain socket connections only -local all all md5 -# IPv4 local connections: -hostssl edb all 192.168.2.0/24 cert clientcert=1 map=sslusers -``` - -**Step 9:** The following shows the user name maps in the `pg_ident.conf` file related to the `pg_hba.conf` file by the `map=sslusers` option. These user name maps permit you to specify database user names `edbuser`, `postgres`, or `enterprisedb` when connecting with EDB\*Plus. - -```text -# MAPNAME SYSTEM-USERNAME PG-USERNAME - sslusers enterprisedb edbuser - sslusers enterprisedb postgres - sslusers enterprisedb enterprisedb -``` - -**Step 10:** Restart the database server after you have made the changes to the configuration files. - -## Configuring SSL for the EDB\*Plus Client - -After you have configured SSL on the database server, the following steps provide an example of generating certificate and keystore files for EDB\*Plus (the JDBC client). - -**Step 1:** Using files `server.crt` and `server.key` located under the database server data sub-directory, create copies of these files and move them to the host where EDB\*Plus is to be running. - -Store these files in the desired directory to contain the trusted certificate and keystore files to be generated in the following steps. The suggested location is to create a `.postgresql` sub-directory under the home user account that will invoke EDB\*Plus. Thus, these files will be under the `~/.postgresql` directory of the user account that will run EDB\*Plus. - -For this example, assume file `edb.crt` is a copy of `server.crt` and `edb.key` is a copy of `server.key`. - -**Step 2:** Create an additional copy of `edb.crt`. - -```text -$ cp edb.crt edb_root.crt -$ ls -l -total 12 --rw-r--r-- 1 user user 985 Aug 22 14:17 edb.crt --rw-r--r-- 1 user user 1704 Aug 22 14:18 edb.key --rw-r--r-- 1 user user 985 Aug 22 14:19 edb_root.crt -``` - -**Step 3:** Create a Distinguished Encoding Rules (DER) format of file `edb_root.crt`. The generated DER format of this file is `edb_root.crt.der`. The DER format of the file is required for the `keytool` program used in Step 4. - -```text -$ openssl x509 -in edb_root.crt -out edb_root.crt.der -outform der -$ ls -l -total 16 --rw-r--r-- 1 user user 985 Aug 22 14:17 edb.crt --rw-r--r-- 1 user user 1704 Aug 22 14:18 edb.key --rw-r--r-- 1 user user 985 Aug 22 14:19 edb_root.crt --rw-rw-r-- 1 user user 686 Aug 22 14:21 edb_root.crt.der -``` - -**Step 4:** Use the `keytool` program to create a keystore file `(postgresql.keystore)` using `edb_root.crt.der` as the input. This process adds the certificate of the Postgres database server to the keystore file. - -!!! Note - The file name `postgresql.keystore` is recommended so that it can be accessed in its default directory location `~/.postgresql postgresql.keystore`, which is under the home directory of the user account invoking EDB\*Plus. Also note that the file name suffix can be `.jks` instead of `.keystore` (thus, file name `postgresql.jks`). However, in the remainder of these examples, file name `postgresql.keystore` is used. - -**For Windows only:** The path is `%APPDATA%\.postgresql\postgresql.keystore` - -The `keytool` program can be found under the `bin` subdirectory of the Java Runtime Environment installation. - -You will be prompted for a new password. Save this password as it must be specified with the PGSSLCERTPASS environment variable. - -```text -$ /usr/java/jdk1.8.0_131/jre/bin/keytool -keystore postgresql.keystore \ -> -alias postgresqlstore -import -file edb_root.crt.der -Enter keystore password: -Re-enter new password: -Owner: CN=enterprisedb -Issuer: CN=enterprisedb -Serial number: c60f40256b0e8d53 -Valid from: Tue Aug 22 10:59:25 EDT 2017 until: Wed Aug 22 10:59:25 EDT 2018 -Certificate fingerprints: - MD5: 85:0B:E9:A7:6E:4F:7C:B0:9B:D6:3A:44:55:E2:E9:8E - SHA1: DD:A6:71:24:0B:6C:F8:BC:7A:4C:89:9B:DC:22:6A:6C:B0:F5:3F:7C - SHA256: -DC:02:64:E2:B0:E9:6F:1C:FC:4F:AE:E6:18:85:0B:79:57:43:C3:C5:AE:43:0D:37 -:49:53:6D:11:69:06:46:48 - Signature algorithm name: SHA1withRSA - Version: 1 -Trust this certificate? [no]: yes -Certificate was added to keystore -``` - -**Step 5:** Create a `PKCS #12` format of the keystore file `(postgresql.p12)` using files `edb.crt` and `edb.key` as input. - -!!! Note - The file name `postgresql.p12` is recommended so that it can be accessed in its default directory location `~/.postgresql/postgresql.p12`, which is under the home directory of the user account invoking EDB\*Plus. - -**For Windows only:** The path is `%APPDATA%\.postgresql\postgresql.p12` - -You will be prompted for a new password. Save this password as it must be specified with the PGSSLKEYPASS environment variable. - -```text -$ openssl pkcs12 -export -in edb.crt -inkey edb.key -out postgresql.p12 -Enter Export Password: -Verifying - Enter Export Password: -$ ls –l -total 24 --rw-rw-r-- 1 user user 985 Aug 24 12:18 edb.crt --rw-rw-r-- 1 user user 1704 Aug 24 12:18 edb.key --rw-rw-r-- 1 user user 985 Aug 24 12:20 edb_root.crt --rw-rw-r-- 1 user user 686 Aug 24 12:20 edb_root.crt.der --rw-rw-r-- 1 user user 758 Aug 24 12:26 postgresql.keystore --rw-rw-r-- 1 user user 2285 Aug 24 12:28 postgresql.p12 -``` - -**Step 6:** If the `postgresql.keystore` and `postgresql.p12` files are not already in the `~/.postgresql` directory, move or copy them to that location. - -**For Windows only:** The directory is `%APPDATA%\.postgresql` - -**Step 7:** If the default location `~/.postgresql` is not used, then the full path (including the file name) to the `postgresql.keystore` file must be set with the `PGSSLCERT` environment variable, and the full path (including the file name) to file `postgresql.p12` must be set with the `PGSSLKEY` environment variable before invoking EDB\*Plus. - -In addition, if the generated file from Step 4 was not named `postgresql.keystore` or `postgresql.jks` then, use the `PGSSLCERT` environment variable to designate the file name and its location. Similarly, if the generated file from Step 5 was not named `postgresql.p12` then, use the `PGSSLKEY` environment variable to designate the file name and its location. - -## Requesting an SSL Connection between EDB\*Plus and the Advanced Server Database - -Be sure the following topics have been addressed in order to perform an SSL connection: - -- The trusted certificate and keystore files have been generated for both the database server and the client host to be invoking EDB\*Plus. -- The `postgresql.conf` file for the database server contains the updated configuration parameters. -- The `pg_hba.conf` file for the database server contains the required entry for permitting the SSL connection. -- For the client host, either the client’s certificate and keystore files have been placed in the user account’s `~/.postgresql` directory or the environment variables `PGSSLCERT` and `PGSSLKEY` are set before invoking EDB\*Plus. -- The `PGSSLCERTPASS` environment variable is set with a password. -- The `PGSSLKEYPASS` environment variable is set with a password - -When invoking EDB\*Plus, include the `?ssl=true` parameter in the database connection string as shown for the `connectstring` option in [Using EDB\*Plus](04_using_edb_plus/#using_edb_plus). - -The following is an example where EDB\*Plus is invoked from a host that is remote to the database server. - -The `postgresql.conf` file of the database server contains the following modified parameters: - -```text -ssl = on -ssl_cert_file = 'server.crt' -ssl_key_file = 'server.key' -ssl_ca_file = 'root.crt' -``` - -The `pg_hba.conf` file of the database server contains the following entry for connecting from EDB\*Plus on the remote host: - -```text -# TYPE DATABASE USER ADDRESS METHOD - -# "local" is for Unix domain socket connections only -local all all md5 -# IPv4 local connections: -hostssl edb all 192.168.2.24/32 cert clientcert=1 -``` - -On the remote host where EDB\*Plus is to be invoked, the Linux user account named `user` contains the certificate and keystore files in its `~/.postgresql` directory: - -```text -[user@localhost ~]$ whoami -user -[user@localhost ~]$ cd .postgresql -[user@localhost .postgresql]$ pwd -/home/user/.postgresql -[user@localhost .postgresql]$ ls -l -total 8 --rw-rw-r-- 1 user user 758 Aug 24 12:37 postgresql.keystore --rw-rw-r-- 1 user user 2285 Aug 24 12:37 postgresql.p12 -``` - -Logged into Linux with the account named `user`, EDB\*Plus is successfully invoked with the `ssl=true` parameter: - -```text -$ export PGSSLCERTPASS=keypass -$ export PGSSLKEYPASS=exppass -$ cd /opt/edb/as13/edbplus -$ ./edbplus.sh enterprisedb/password@192.168.2.22:5444/edb?ssl=true -Connected to EnterpriseDB 13.0.1 (192.168.2.22:5444/edb) AS enterprisedb - -EDB*Plus: Release 13 (Build 39.0.3) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -Alternatively, without placing the certificate and keystore files in `~/.postgresql`, but in a different directory, EDB\*Plus can be invoked in the following manner: - -```text -$ export PGSSLCERT=/home/user/ssl/postgresql.keystore -$ export PGSSLKEY=/home/user/ssl/postgresql.p12 -$ export PGSSLCERTPASS=keypass -$ export PGSSLKEYPASS=exppass -$ cd /opt/edb/as13/edbplus -$ ./edbplus.sh enterprisedb/password@192.168.2.22:5444/edb?ssl=true -Connected to EnterpriseDB 13.0.1 (192.168.2.22:5444/edb) AS enterprisedb - -EDB*Plus: Release 13 (Build 39.0.3) -Copyright (c) 2008-2021, EnterpriseDB Corporation. All rights reserved. - -SQL> -``` - -Note that in both cases the database user name used to log into EDB\*Plus is `enterprisedb` as this is the user specified for the common name field when creating the certificate in Step 1 of [Configuring SSL on Advanced Server](#using_ssl_connection). - -Other database user names can be used if the `pg_hba.conf` file with the `map` option and the `pg_ident.conf` file are used as described in Steps 8 and 9 of [Configuring SSL on Advanced Server](#using_ssl_connection). diff --git a/product_docs/docs/edb_plus/39/06_command_summary.mdx b/product_docs/docs/edb_plus/39/06_command_summary.mdx deleted file mode 100644 index ad22ca71519..00000000000 --- a/product_docs/docs/edb_plus/39/06_command_summary.mdx +++ /dev/null @@ -1,997 +0,0 @@ ---- -title: "Command Summary" -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/39/command_summary.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/38/command_summary.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-guide/36/command_summary.html" ---- - - - -The following sections contains a summary of EDB\*Plus commands. - -## ACCEPT - -The `ACCEPT` command displays a prompt and waits for the user’s keyboard input. The value input by the user is placed in the specified variable. - -```text -ACC[EPT ] variable -``` - -The following example creates a new variable named `my_name`, accepts a value of John Smith, then displays the value using the `DEFINE` command. - -```text -SQL> ACCEPT my_name -Enter value for my_name: John Smith -SQL> DEFINE my_name -DEFINE MY_NAME = "John Smith" -``` - -## APPEND - -`APPEND` is a line editor command that appends the given text to the end of the current line in the SQL buffer. - -```text -A[PPEND ] text -``` - -In the following example, a `SELECT` command is built-in the SQL buffer using the `APPEND` command. Note that two spaces are placed between the `APPEND` command and the `WHERE` clause in order to separate `dept` and `WHERE` by one space in the SQL buffer. - -```text -SQL> APPEND SELECT * FROM dept -SQL> LIST - 1 SELECT * FROM dept -SQL> APPEND WHERE deptno = 10 -SQL> LIST - 1 SELECT * FROM dept WHERE deptno = 10 -``` - -## CHANGE - -`CHANGE` is a line editor command performs a search-and-replace on the current line in the SQL buffer. - -```text -C[HANGE ] FROM [ TO ] -``` - -If `TO/` is specified, the first occurrence of text `FROM` in the current line is changed to text `TO`. If `TO/` is omitted, the first occurrence of text `FROM` in the current line is deleted. - -The following sequence of commands makes line 3 the current line, then changes the department number in the `WHERE` clause from 20 to 30. - -```text -SQL> LIST - 1 SELECT empno, ename, job, sal, comm - 2 FROM emp - 3 WHERE deptno = 20 - 4* ORDER BY empno -SQL> 3 - 3* WHERE deptno = 20 -SQL> CHANGE /20/30/ - 3* WHERE deptno = 30 -SQL> LIST - 1 SELECT empno, ename, job, sal, comm - 2 FROM emp - 3 WHERE deptno = 30 - 4* ORDER BY empno -``` - -## CLEAR - -The `CLEAR` command removes the contents of the SQL buffer, deletes all column definitions set with the `COLUMN` command, or clears the screen. - -```text -CL[EAR ] [ BUFF[ER ] | SQL | COL[UMNS ] | SCR[EEN ] ] -``` - -`BUFFER | SQL` - - Clears the SQL buffer. - -`COLUMNS` - - Removes column definitions. - -`SCREEN` - - Clears the screen. This is the default if no options are specified. - -## COLUMN - -The `COLUMN` command controls output formatting. The formatting attributes set by using the `COLUMN` command remain in effect only for the duration of the current session. - -```text -COL[UMN ] - [ column - { CLE[AR ] | - { FOR[MAT ] spec | - HEA[DING ] text | - { OFF | ON } - } [...] - } - ] -``` - -If the `COLUMN` command is specified with no subsequent options, formatting options for current columns in effect for the session are displayed. - -If the `COLUMN` command is followed by a column name, then the column name may be followed by one of the following: - -1. No other options -2. `CLEAR` -3. Any combination of `FORMAT`, `HEADING`, and one of `OFF` or `ON` - -`column` - - Name of a column in a table to which subsequent column formatting options are to apply. If no other options follow `column`, then the current column formatting options if any, of `column` are displayed. - -`CLEAR` - - The `CLEAR` option reverts all formatting options back to their defaults for `column`. If the `CLEAR` option is specified, it must be the only option specified. - -`spec` - - Format specification to be applied to `column`. For character columns, `spec` takes the following format: - -`n` - - `n` is a positive integer that specifies the column width in characters within which to display the data. Data in excess of `n` will wrap around with the specified column width. - - For numeric columns, `spec` is comprised of the following elements. - -| Element | Description | -| ------- | ------------------------------------------ | -| `$` | Display a leading dollar sign. | -| `,` | Display a comma in the indicated position. | -| `.` | Marks the location of the decimal point. | -| `0` | Display leading zeros. | -| `9` | Number of significant digits to display. | - - If loss of significant digits occurs due to overflow of the format, then all #’s are displayed. - -`text` - - Text to be used for the column heading of `column`. - -`OFF | ON` - - If `OFF` is specified, formatting options are reverted back to their defaults, but are still available within the session. If `ON` is specified, the formatting options specified by previous `COLUMN` commands for `column` within the session are re-activated. - -The following example shows the effect of changing the display width of the `job` column. - -```text -SQL> SET PAGESIZE 9999 -SQL> COLUMN job FORMAT A5 -SQL> COLUMN job -COLUMN JOB ON -FORMAT A5 -wrapped -SQL> SELECT empno, ename, job FROM emp; - -EMPNO ENAME JOB ------ ---------- ----- - 7369 SMITH CLERK - 7499 ALLEN SALES - MAN - - 7521 WARD SALES - MAN - - 7566 JONES MANAG - ER - - 7654 MARTIN SALES - MAN - - 7698 BLAKE MANAG - ER - - 7782 CLARK MANAG - ER - - 7788 SCOTT ANALY - ST - - 7839 KING PRESI - DENT - - 7844 TURNER SALES - MAN - - 7876 ADAMS CLERK - 7900 JAMES CLERK - 7902 FORD ANALY - ST - - 7934 MILLER CLERK - -14 rows retrieved. -``` - -The following example applies a format to the `sal` column. - -```text -SQL> COLUMN sal FORMAT $99,999.00 -SQL> COLUMN -COLUMN JOB ON -FORMAT A5 -wrapped - -COLUMN SAL ON -FORMAT $99,999.00 -wrapped -SQL> SELECT empno, ename, job, sal FROM emp; - -EMPNO ENAME JOB SAL ------ ---------- ----- ----------- - 7369 SMITH CLERK $800.00 - 7499 ALLEN SALES $1,600.00 - MAN - - 7521 WARD SALES $1,250.00 - MAN - - 7566 JONES MANAG $2,975.00 - ER - - 7654 MARTIN SALES $1,250.00 - MAN - - 7698 BLAKE MANAG $2,850.00 - ER - - 7782 CLARK MANAG $2,450.00 - ER - - 7788 SCOTT ANALY $3,000.00 - ST - - 7839 KING PRESI $5,000.00 - DENT - - 7844 TURNER SALES $1,500.00 - MAN - - 7876 ADAMS CLERK $1,100.00 - 7900 JAMES CLERK $950.00 - 7902 FORD ANALY $3,000.00 - ST - - 7934 MILLER CLERK $1,300.00 - -14 rows retrieved. -``` - -## CONNECT - -Change the database connection to a different user and/or connect to a different database. There must be no white space between any of the parameters following the `CONNECT` command. - -```text -CON[NECT] [/][@{ | } ] -``` - -Where: - - `username` is a database username with which to connect to the database. - - `password` is the password associated with the specified `username`. If a `password` is not provided, but a password is required for authentication, a search is made for a password file, first in the home directory of the Linux operating system account invoking EDB\*Plus (or in the `%APPDATA%\postgresql\` directory for Windows) and then at the location specified by the `PGPASSFILE` environment variable. The password file is `.pgpass` on Linux hosts and `pgpass.conf` on Windows hosts. The following is an example on a Windows host: - -```text -C:\Users\Administrator\AppData\Roaming\postgresql\pgpass.conf -``` - - If a password file cannot be located, or it does not have an entry matching the EDB\*Plus connection parameters, then EDB\*Plus will prompt for the password. For more information about password files, see the PostgreSQL core documentation at: - - - - **Note**: When a password is not required, EDB\*Plus does not prompt for a password such as when the `trust` authentication method is specified in the `pg_hba.conf` file. For more information about the `pg_hba.conf` file and authentication methods, see the PostgreSQL core documentation at - - `connectstring` is the database connection string. See [Using EDB\*Plus](04_using_edb_plus/#using_edb_plus) for further information on the database connection string. - - `variable` is a variable defined in the `login.sql` file that contains a database connection string. The `login.sql` file can be found in the `edbplus` subdirectory of the Advanced Server home directory. - -In the following example, the database connection is changed to database `edb` on the localhost at port `5445` with username `smith`. - -```text -SQL> CONNECT smith/mypassword@localhost:5445/edb -Disconnected from EnterpriseDB Database. -Connected to EnterpriseDB 13.0.1 (localhost:5445/edb) AS smith -``` - -From within the session shown above, the connection is changed to username `enterprisedb`. Also note that the host defaults to the localhost, the port defaults to `5444` (which is not the same as the port previously used), and the database defaults to `edb`. - -```text -SQL> CONNECT enterprisedb/password -Disconnected from EnterpriseDB Database. -Connected to EnterpriseDB 13.0.1 (localhost:5444/edb) AS enterprisedb -``` - -## DEFINE - -The `DEFINE` command creates or replaces the value of a *user variable* (also called a *substitution variable*). - -```text -DEF[INE ] [ variable [ = text ] ] -``` - -If the `DEFINE` command is given without any parameters, all current variables and their values are displayed. - -If `DEFINE variable` is given, only `variable` is displayed with its value. - -`DEFINE variable = text` assigns `text` to `variable.text` may be optionally enclosed within single or double quotation marks. Quotation marks must be used if `text` contains space characters. - -The following example defines two variables, `dept` and `name`. - -```text -SQL> DEFINE dept = 20 -SQL> DEFINE name = 'John Smith' -SQL> DEFINE -DEFINE EDB = "localhost:5445/edb" -DEFINE DEPT = "20" -DEFINE NAME = "John Smith" -``` - -!!! Note - The variable `EDB` is read from the `login.sql` file located in the `edbplus` subdirectory of the Advanced Server home directory. - -## DEL - -`DEL` is a line editor command that deletes one or more lines from the SQL buffer. - -```text -DEL [ n | n m | n * | n L[AST ] | * | * n | * L[AST ] | L[AST ] ] -``` - -The parameters specify which lines are to be deleted from the SQL buffer. Two parameters specify the start and end of a range of lines to be deleted. If the `DEL` command is given with no parameters, the current line is deleted. - -`n` - - n is an integer representing the `n`th line - -`n m` - - `n` and `m` are integers where `m` is greater than `n` representing the `n`th through the `m`th lines - -`*` - - Current line - -`LAST` - - Last line - -In the following example, the fifth and sixth lines containing columns `sal` and `comm`, respectively, are deleted from the `SELECT` command in the SQL buffer. - -```text -SQL> LIST - 1 SELECT - 2 empno - 3 ,ename - 4 ,job - 5 ,sal - 6 ,comm - 7 ,deptno - 8* FROM emp -SQL> DEL 5 6 -SQL> LIST - 1 SELECT - 2 empno - 3 ,ename - 4 ,job - 5 ,deptno - 6* FROM emp -``` - -## DESCRIBE - -The `DESCRIBE` command displays: - -- A list of columns, column data types, and column lengths for a table or view -- A list of parameters for a procedure or function -- A list of procedures and functions and their respective parameters for a package - -The `DESCRIBE` command will also display the structure of the database object referred to by a synonym. The syntax is: - -```text -DESC[RIBE] [ schema.]object -``` - -`schema` - - Name of the schema containing the object to be described. - -`object` - - Name of the table, view, procedure, function, or package to be displayed, or the synonym of an object. - -## DISCONNECT - -The `DISCONNECT` command closes the current database connection, but does not terminate EDB\*Plus. - -```text -DISC[ONNECT ] -``` - -## EDIT - -The `EDIT` command invokes an external editor to edit the contents of an operating system file or the SQL buffer. - -```text -ED[IT ] [ filename[.ext ] ] -``` - -`filename[.ext ]` - - `filename` is the name of the file to open with an external editor. `ext` is the filename extension. If the filename extension is `sql`, then the `.sql` extension may be omitted when specifying `filename`. `EDIT` always assumes a `.sql` extension on filenames that are specified with no extension. If the filename parameter is omitted from the `EDIT` command, the contents of the SQL buffer are brought into the editor. - -## EXECUTE - -The `EXECUTE` command executes an SPL procedure from EDB\*Plus. - -```text -EXEC[UTE ] spl_procedure [ ([ parameters ]) ] -``` - -`spl_procedure` - - The name of the SPL procedure to be executed. - -`parameters` - - Comma-delimited list of parameters. If there are no parameters, then a pair of empty parentheses may optionally be specified. - -## EXIT - -The `EXIT` command terminates the EDB\*Plus session and returns control to the operating system. `QUIT` is a synonym for `EXIT`. Specifying no parameters is equivalent to `EXIT SUCCESS COMMIT`. - -```text -{ EXIT | QUIT } -[ SUCCESS | FAILURE | WARNING | value | variable ] -[ COMMIT | ROLLBACK ]SUCCESS | FAILURE |WARNING] -``` - -Returns an operating system dependent return code indicating successful operation, failure, or warning for `SUCCESS, FAILURE`, and `WARNING`, respectively. The default is `SUCCESS`. - -`value` - - An integer value that is returned as the return code. - -`variable` - - A variable created with the `DEFINE` command whose value is returned as the return code. - -`COMMIT | ROLLBACK` - - If `COMMIT` is specified, uncommitted updates are committed upon exit. If `ROLLBACK` is specified, uncommitted updates are rolled back upon exit. The default is `COMMIT`. - -## GET - -The `GET` command loads the contents of the given file to the SQL buffer. - -```text -GET filename[.ext ] [ LIS[T ] | NOL[IST ] ] -``` - -`filename[.ext ]` - - `filename` is the name of the file to load into the SQL buffer. `ext` is the filename extension. If the filename extension is `sql`, then the `.sql` extension may be omitted when specifying `filename`. `GET` always assumes a `.sql` extension on filenames that are specified with no extension. - -`LIST | NOLIST` - - If `LIST` is specified, the content of the SQL buffer is displayed after the file is loaded. If `NOLIST` is specified, no listing is displayed. The default is `LIST`. - -## HELP - -The `HELP` command obtains an index of topics or help on a specific topic. The question mark `(?)` is synonymous with specifying `HELP`. - -```text -{ HELP | ? } { INDEX | topic } -``` - -`INDEX` - - Displays an index of available topics. - -`topic` - - The name of a specific topic – e.g., an EDB\*Plus command, for which help is desired. - -## HOST - -The `HOST` command executes an operating system command from EDB\*Plus. - -```text -HO[ST ] [os_command] -``` - -`os_command` - - The operating system command to be executed. If you do not provide an operating system command, EDB\*Plus pauses execution and opens a new shell prompt. When the shell exits, EDB\*Plus resumes execution. - -## INPUT - -The `INPUT` line editor command adds a line of text to the SQL buffer after the current line. - -```text -I[NPUT ] text -``` - -The following sequence of `INPUT` commands constructs a `SELECT` command. - -```text -SQL> INPUT SELECT empno, ename, job, sal, comm -SQL> INPUT FROM emp -SQL> INPUT WHERE deptno = 20 -SQL> INPUT ORDER BY empno -SQL> LIST - 1 SELECT empno, ename, job, sal, comm - 2 FROM emp - 3 WHERE deptno = 20 - 4* ORDER BY empno -``` - -## LIST - -`LIST` is a line editor command that displays the contents of the SQL buffer. - -```text -L[IST] [ n | n m | n * | n L[AST] | * | * n | * L[AST] | L[AST] ] -``` - -The buffer does not include a history of the EDB\*Plus commands. - -`n` - - `n` represents the buffer line number. - -`n m` - - `n m` displays a list of lines between `n` and `m`. - -`n *` - - `n *` displays a list of lines that range between line `n` and the current line. - -`n L[AST]` - - `n L[AST]` displays a list of lines that range from line `n` through the last line in the buffer. - -`*` - - `*` displays the current line. - -`* n` - - `* n` displays a list of lines that range from the current line through line `n`. - -`* L[AST]` - - `* L[AST]` displays a list of lines that range from the current line through the last line. - -`L[AST]` - - `L[AST]` displays the last line. - -## PASSWORD - -Use the `PASSWORD` command to change your database password. - -```text -PASSW[ORD] [user_name] -``` - -You must have sufficient privileges to use the `PASSWORD` command to change another user's password. The following example demonstrates using the `PASSWORD` command to change the password for a user named `acctg`: - -```text -SQL> PASSWORD acctg -Changing password for acctg - New password: - New password again: -Password successfully changed. -``` - -## PAUSE - -The `PAUSE` command displays a message, and waits for the user to press `ENTER`. - -```text -PAU[SE] [optional_text] -``` - -`optional_text` specifies the text that will be displayed to the user. If the `optional_text` is omitted, Advanced Server will display two blank lines. If you double quote the `optional_text` string, the quotes will be included in the output. - -## PROMPT - -The `PROMPT` command displays a message to the user before continuing. - -```text -PRO[MPT] [message_text] -``` - -`message_text` specifies the text displayed to the user. Double quote the string to include quotes in the output. - -## QUIT - -The `QUIT` command terminates the session and returns control to the operating system. `QUIT` is a synonym for `EXIT`. - -```text -QUIT - -[SUCCESS | FAILURE | WARNING | value | sub_variable] - -[COMMIT | ROLLBACK] -``` - -The default value is `QUIT SUCCESS COMMIT`. - -## REMARK - -Use `REMARK` to include comments in a script. - -```text -REM[ARK] [optional_text] -``` - -You may also use the following convention to include a comment: - -```text -/* - * This is an example of a three line comment. - */ -``` - -## SAVE - -Use the `SAVE` command to write the SQL Buffer to an operating system file. - -```text -SAV[E] file_name -[CRE[ATE] | REP[LACE] | APP[END]] -``` - -`file_name` - - `file_name` specifies the name of the file (including the path) where the buffer contents are written. If you do not provide a file extension, `.sql` is appended to the end of the file name. - -`CREATE` - - Include the `CREATE` keyword to create a new file. A new file is created *only* if a file with the specified name does not already exist. This is the default. - -`REPLACE` - - Include the `REPLACE` keyword to specify that Advanced Server should overwrite an existing file. - -`APPEND` - - Include the `APPEND` keyword to specify that Advanced Server should append the contents of the SQL buffer to the end of the specified file. - -The following example saves the contents of the SQL buffer to a file named `example.sql`, located in the `temp` directory: - -```text -SQL> SAVE C:\example.sql CREATE -File "example.sql" written. -``` - -## SET - -Use the `SET` command to specify a value for a session level variable that controls EDB\*Plus behavior. The following forms of the `SET` command are valid: - -**SET AUTOCOMMIT** - -Use the `SET AUTOCOMMIT` command to specify commit behavior for Advanced Server transactions. - -```text -SET AUTO[COMMIT] - -{ON | OFF | IMMEDIATE | statement_count} -``` - -Please note that EDB\*Plus always automatically commits DDL statements. - -`ON` - - Specify `ON` to turn `AUTOCOMMIT` behavior on. - -`OFF` - - Specify `OFF` to turn `AUTOCOMMIT` behavior off. - -`IMMEDIATE` - - `IMMEDIATE` has the same effect as `ON`. - -`statement_count` - - Include a value for `statement_count` to instruct EDB\*Plus to issue a commit after the specified count of successful SQL statements. - -**SET COLUMN SEPARATOR** - -Use the `SET COLUMN SEPARATOR` command to specify the text that Advanced Server displays between columns. - -```text -SET COLSEP column_separator -``` - -The default value of `column_separator` is a single space. - -**SET ECHO** - -Use the `SET ECHO` command to specify if SQL and EDB\*Plus script statements should be displayed onscreen as they are executed. - -```text -SET ECHO {ON | OFF} -``` - -The default value is `OFF`. - -**SET FEEDBACK** - -The `SET FEEDBACK` command controls the display of interactive information after a SQL statement executes. - -```text -SET FEED[BACK] {ON | OFF | row_threshold} -``` - -`row_threshold` - - Specify an integer value for `row_threshold`. Setting `row_threshold` to `0` is same as setting `FEEDBACK` to `OFF`. Setting `row_threshold` equal `1` effectively sets `FEEDBACK` to `ON`. - -**SET FLUSH** - -Use the `SET FLUSH` command to control display buffering. - -```text -SET FLU[SH] {ON | OFF} -``` - -Set `FLUSH` to `OFF` to enable display buffering. If you enable buffering, messages bound for the screen may not appear until the script completes. Please note that setting `FLUSH` to `OFF` will offer better performance. - -Set `FLUSH` to `ON` to disable display buffering. If you disable buffering, messages bound for the screen appear immediately. - -**SET HEADING** - -Use the `SET HEADING` variable to specify if Advanced Server should display column headings for `SELECT` statements. - -```text -SET HEA[DING] {ON | OFF} -``` - -**SET HEAD SEPARATOR** - -The `SET HEADSEP` command sets the new heading separator character used by the `COLUMN HEADING` command. The default is `'|'`. - -```text -SET HEADS[EP] -``` - -**SET LINESIZE** - -Use the `SET LINESIZE` command to specify the width of a line in characters. - -```text -SET LIN[ESIZE] width_of_line -``` - -`width_of_line` - - The default value of `width_of_line` is `132`. - -**SET NEWPAGE** - -Use the `SET NEWPAGE` command to specify how many blank lines are printed after a page break. - -```text -SET NEWP[AGE] lines_per_page -``` - -`lines_per_page` - - The default value of `lines_per_page` is `1`. - -**SET NULL** - -Use the `SET NULL` command to specify a string that is displayed to the user when a `NULL` column value is displayed in the output buffer. - -```text -SET NULL null_string -``` - -**SET PAGESIZE** - -Use the `SET PAGESIZE` command to specify the number of printed lines that fit on a page. - -```text -SET PAGES[IZE] line_count -``` - -Use the `line_count` parameter to specify the number of lines per page. - -**SET SQLCASE** - -The `SET SQLCASE` command specifies if SQL statements transmitted to the server should be converted to upper or lower case. - -```text -SET SQLC[ASE] {MIX[ED] | UP[PER] | LO[WER]} -``` - -`UPPER` - - Specify `UPPER` to convert the command text to uppercase. - -`LOWER` - - Specify `LOWER` to convert the command text to lowercase. - -`MIXED` - - Specify `MIXED` to leave the case of SQL commands unchanged. The default is `MIXED`. - -**SET PAUSE** - -The `SET PAUSE` command is most useful when included in a script; the command displays a prompt and waits for the user to press `Return`. - -```text -SET PAU[SE] {ON | OFF} -``` - -If `SET PAUSE` is `ON`, the message `Hit ENTER to continue…` will be displayed before each command is executed. - -**SET SPACE** - -Use the `SET SPACE` command to specify the number of spaces to display between columns: - -```text -SET SPACE number_of_spaces -``` - -**SET SQLPROMPT** - -Use `SET SQLPROMPT` to set a value for a user-interactive prompt: - -```text -SET SQLP[ROMPT] "prompt" -``` - -By default, `SQLPROMPT` is set to `"SQL> "` - -**SET TERMOUT** - -Use the `SET TERMOUT` command to specify if command output should be displayed onscreen. - -```text -SET TERM[OUT] {ON | OFF} -``` - -**SET TIMING** - -The `SET TIMING` command specifies if Advanced Server should display the execution time for each SQL statement after it is executed. - -```text -SET TIMI[NG] {ON | OFF} -``` - -**SET TRIMSPOOL** - -Use the `SET TRIMSPOOL` command to remove trailing spaces from each line in the output file specified by the `SPOOL` command. - -```text -SET TRIMS[POOL] {ON | OFF} -``` - -The default value is `OFF`. - -**SET VERIFY** - -Specifies if both the old and new values of a SQL statement are displayed when a substitution variable is encountered. - -```text -SET VER[IFY] { ON | OFF } -``` - -## SHOW - -Use the `SHOW` command to display current parameter values. - -```text -SHO[W] {ALL | parameter_name} -``` - -Display the current parameter settings by including the `ALL` keyword: - -```Text -SQL> SHOW ALL -autocommit OFF -colsep " " -define "&" -echo OFF -FEEDBACK ON for 6 row(s). -flush ON -heading ON -headsep "|" -linesize 78 -newpage 1 -null " " -pagesize 14 -pause OFF -serveroutput OFF -spool OFF -sqlcase MIXED -sqlprompt "SQL> " -sqlterminator ";" -suffix ".sql" -termout ON -timing OFF -verify ON -USER is "enterprisedb" -HOST is "localhost" -PORT is "5444" -DATABASE is "edb" -VERSION is "13.0.0" -``` - -Or display a specific parameter setting by including the `parameter_name` in the `SHOW` command: - -```text -SQL> SHOW VERSION -VERSION is "13.0.0" -``` - -## SPOOL - -The `SPOOL` command sends output from the display to a file. - -```text -SP[OOL] output_file | OFF -``` - -Use the `output_file` parameter to specify a path name for the output file. - -## START - -Use the `START` command to run an EDB\*Plus script file; `START` is an alias for `@` command. - -```text -STA[RT] script_file -``` - -Specify the name of a script file in the `script_file` parameter. - -## UNDEFINE - -The `UNDEFINE` command erases a user variable created by the `DEFINE` command. - -```text -UNDEF[INE] variable_name [ variable_name...] -``` - -Use the `variable_name` parameter to specify the name of a variable or variables. - -## WHENEVER SQLERROR - -The `WHENEVER SQLERROR` command provides error handling for SQL errors or PL/SQL block errors. The syntax is: - -```text -WHENEVER SQLERROR - {CONTINUE[COMMIT|ROLLBACK|NONE] - |EXIT[SUCCESS|FAILURE|WARNING|n|sub_variable] - [COMMIT|ROLLBACK]} -``` - -If Advanced Server encounters an error during the execution of a SQL command or PL/SQL block, EDB\*Plus performs the action specified in the `WHENEVER SQLERROR` command: - - Include the `CONTINUE` clause to instruct EDB\*Plus to perform the specified action before continuing. - - Include the `COMMIT` clause to instruct EDB\*Plus to `COMMIT` the current transaction before exiting or continuing. - - Include the `ROLLBACK` clause to instruct EDB\*Plus to `ROLLBACK` the current transaction before exiting or continuing. - - Include the `NONE` clause to instruct EDB\*Plus to continue without committing or rolling back the transaction. - - Include the `EXIT` clause to instruct EDB\*Plus to perform the specified action and exit if it encounters an error. - - Use the following options to specify a status code that EDB\*Plus will return before exiting: - -```text -[SUCCESS|FAILURE|WARNING|n|sub_variable] -``` - - Please note that EDB\*Plus supports substitution variables, but does not support bind variables. diff --git a/product_docs/docs/edb_plus/39/images/edb_plus_welcome.png b/product_docs/docs/edb_plus/39/images/edb_plus_welcome.png deleted file mode 100755 index c526c78eabf..00000000000 --- a/product_docs/docs/edb_plus/39/images/edb_plus_welcome.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:4f557131b686992e3d8a9f7d0f40ddd14dcdde8a6ee7fb90af3ef57860194024 -size 56911 diff --git a/product_docs/docs/edb_plus/39/images/installation_directory.png b/product_docs/docs/edb_plus/39/images/installation_directory.png deleted file mode 100755 index e9e71920170..00000000000 --- a/product_docs/docs/edb_plus/39/images/installation_directory.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:b39c529e783b4a42453d2dd8ff0729549ca0d9cd61047a6dedaa4cb04ba56f05 -size 15499 diff --git a/product_docs/docs/edb_plus/39/index.mdx b/product_docs/docs/edb_plus/39/index.mdx deleted file mode 100644 index ce7528e4d74..00000000000 --- a/product_docs/docs/edb_plus/39/index.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "EDB*Plus" -description: EDB\*Plus provides a command line user interface to EDB Postgres Advanced Server. -navTitle: EDB*Plus - -legacyRedirects: - - "/edb-docs/p/edbplus/39" - - "/edb-docs/p/edbplus/38" - - "/edb-docs/p/edbplus/36" - -directoryDefaults: - description: "EDB*Plus Documentation and release notes." -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/39/index.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/39/conclusion.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/39/genindex.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/39/introduction.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/38/conclusion.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/38/introduction.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/38/genindex.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-users-guide/38/index.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-guide/36/index.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-guide/36/whats_new.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-guide/36/genindex.html" - - "/edb-docs/d/edbplus/user-guides/edbplus-guide/36/conclusion.html" ---- - -EDB\*Plus is a utility program that provides a command line user interface to EDB Postgres Advanced Server. EDB\*Plus accepts SQL commands, SPL anonymous blocks, and EDB\*Plus commands. - -EDB\*Plus commands are compatible with Oracle SQL\*Plus commands and provide various capabilities including: - -- Querying certain database objects -- Executing stored procedures -- Formatting output from SQL commands -- Executing batch scripts -- Executing OS commands -- Recording output - -
- -introduction edb_plus installing_edb_plus using_edb_plus using_edb_plus_with_ssl command_summary conclusion - -
diff --git a/product_docs/docs/edb_plus/40/02_release_notes/09_edbplus_40.01_rel_notes.mdx b/product_docs/docs/edb_plus/40/02_release_notes/09_edbplus_40.01_rel_notes.mdx deleted file mode 100644 index 75abef661da..00000000000 --- a/product_docs/docs/edb_plus/40/02_release_notes/09_edbplus_40.01_rel_notes.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "Version 40.0.1" ---- - -New features, enhancements, bug fixes, and other changes in EDB*Plus 40.0.1 include: - -| Type | Description | -| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Enhancement | The display format for a decimal point is now compatible with Oracle SQL*Plus [75092]. | -| Security fix | The EDB JDBC Driver in EDB*Plus is upgraded to version 42.3.2.1. This upgrade fixes the CVE-2022-21724 vulnerability reported in older versions of EDB JDBC Driver. | -| Bug fix | Describe command no longer fails for a schema qualified SYNONYM name [72994]. | diff --git a/product_docs/docs/edb_plus/40/02_release_notes/10_edbplus_40_rel_notes.mdx b/product_docs/docs/edb_plus/40/02_release_notes/10_edbplus_40_rel_notes.mdx deleted file mode 100644 index 4ae54e86a6c..00000000000 --- a/product_docs/docs/edb_plus/40/02_release_notes/10_edbplus_40_rel_notes.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Version 40.0.0" ---- - -New features, enhancements, bug fixes, and other changes in EDB*Plus 40.0.0 include: - -| Type | Description | -| ----------- | -------------------------------------------------------------- | -| Enhancement | Support for EDB Postgres Advanced Server 14.1.0. | \ No newline at end of file diff --git a/product_docs/docs/edb_plus/40/02_release_notes/index.mdx b/product_docs/docs/edb_plus/40/02_release_notes/index.mdx deleted file mode 100644 index ef19f137de6..00000000000 --- a/product_docs/docs/edb_plus/40/02_release_notes/index.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Release notes" - ---- - -EDB\*Plus is a utility program that provides a command line interface to EDB Postgres Advanced Server. - -The EDB\*Plus documentation describes the latest version of EDB\*Plus Version 40. The release notes provide information on what was new in each release. - -| Version | Release Date | -| --------------------------------------- | ------------ | -| [40.0.1](09_edbplus_40.01_rel_notes.mdx)| 2022 Mar 02 | -| [40.0.0](10_edbplus_40_rel_notes.mdx) | 2021 Dec 02 | \ No newline at end of file diff --git a/product_docs/docs/edb_plus/40/02a_supported_platforms.mdx b/product_docs/docs/edb_plus/40/02a_supported_platforms.mdx deleted file mode 100644 index 0ba3b9ab07c..00000000000 --- a/product_docs/docs/edb_plus/40/02a_supported_platforms.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Supported platforms" ---- - -This table lists the EDB\*Plus versions and their supported corresponding EDB Postgres Advanced Server versions. EDB\*Plus is supported on the same platforms as EDB Postgres Advanced Server. See [Product Compatibility](https://www.enterprisedb.com/platform-compatibility#epas) for details. - -| EDB*Plus | EPAS 14 | EPAS 13 | EPAS 12 | EPAS 11 | -| -------- | ------- | ------- | ------- | ------- | -| 40 | Y | Y | Y | Y | -| 39 | N | Y | Y | Y | -| 38 | N | Y | Y | Y | -| 37 | N | N | Y | Y | -| 36 | N | N | N | Y | - diff --git a/product_docs/docs/edb_plus/40/images/advanced_server_installation_details.png b/product_docs/docs/edb_plus/40/images/advanced_server_installation_details.png deleted file mode 100755 index 4a64fc203b1..00000000000 --- a/product_docs/docs/edb_plus/40/images/advanced_server_installation_details.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:9dcb64989a3a2b6e1c683721818a3230d89596b566f3d9acef2246e62ec1477f -size 14772 diff --git a/product_docs/docs/edb_plus/40/images/edb_plus_welcome.png b/product_docs/docs/edb_plus/40/images/edb_plus_welcome.png deleted file mode 100755 index c526c78eabf..00000000000 --- a/product_docs/docs/edb_plus/40/images/edb_plus_welcome.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:4f557131b686992e3d8a9f7d0f40ddd14dcdde8a6ee7fb90af3ef57860194024 -size 56911 diff --git a/product_docs/docs/edb_plus/40/images/installation_complete.png b/product_docs/docs/edb_plus/40/images/installation_complete.png deleted file mode 100755 index f0803ad2adc..00000000000 --- a/product_docs/docs/edb_plus/40/images/installation_complete.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:685f7fe611646fde1106178bd3d82e48d2dc121a40df73fadb35dbae097448e9 -size 58951 diff --git a/product_docs/docs/edb_plus/40/images/ready_to_install.png b/product_docs/docs/edb_plus/40/images/ready_to_install.png deleted file mode 100755 index 4e7bba3e25f..00000000000 --- a/product_docs/docs/edb_plus/40/images/ready_to_install.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:7b1d62f081cde3660fc0f1a132e84d108ae7f16c96f535a18bd0cf26555f2310 -size 12733 diff --git a/product_docs/docs/edb_plus/41/02_release_notes/edbplus_41.0_rel_notes.mdx b/product_docs/docs/edb_plus/41/02_release_notes/edbplus_41.0_rel_notes.mdx new file mode 100644 index 00000000000..45858b30a37 --- /dev/null +++ b/product_docs/docs/edb_plus/41/02_release_notes/edbplus_41.0_rel_notes.mdx @@ -0,0 +1,10 @@ +--- +title: "Version 41.0.0" +--- + +New features, enhancements, bug fixes, and other changes in EDB*Plus 41.0.0 include: + +| Type | Description | +| ----------- | -------------------------------------------------------------- | +| Enhancement | EDB\*Plus now supports EDB Postgres Advanced Server 15. | +| Other | Starting with EDB\*Plus 41 (this release), EDB\*Plus is now being installed in a separate path outside of the EDB Postgres Advanced Server (EPAS) installation path. Any user processes or scripts with calls to EDB\*Plus that relied on EDB\*Plus being installed under EPAS specific directories, will need to be updated to use the new installation paths. On linux systems the new installation path is `/usr/edb/edbplus`. On Microsoft Windows systems, the default installation path is `C:\Program Files\edb\edbplus`. | diff --git a/product_docs/docs/edb_plus/41/02_release_notes/index.mdx b/product_docs/docs/edb_plus/41/02_release_notes/index.mdx new file mode 100644 index 00000000000..f8d6eb0ad87 --- /dev/null +++ b/product_docs/docs/edb_plus/41/02_release_notes/index.mdx @@ -0,0 +1,12 @@ +--- +title: "Release notes" + +--- + +EDB\*Plus is a utility program that provides a command line interface to EDB Postgres Advanced Server. + +The EDB\*Plus documentation describes the latest version of EDB\*Plus Version 41. The release notes provide information on what was new in each release. + +| Version | Release Date | +| ------------------------------------- | ------------ | +| [41.0.0](edbplus_41.0_rel_notes.mdx) | 2023 Feb 14 | diff --git a/product_docs/docs/edb_plus/41/02a_supported_platforms.mdx b/product_docs/docs/edb_plus/41/02a_supported_platforms.mdx new file mode 100644 index 00000000000..f13ca7d0e69 --- /dev/null +++ b/product_docs/docs/edb_plus/41/02a_supported_platforms.mdx @@ -0,0 +1,15 @@ +--- +title: "Supported platforms" +--- + +The following list of EDB Postgres Advanced Server (EPAS) versions are currently supported for use with EDB\*Plus: +- EPAS 15 +- EPAS 14 +- EPAS 13 +- EPAS 12 +- EPAS 11 + +EDB\*Plus is supported on the same platforms as EDB Postgres Advanced Server. See [Product Compatibility](https://www.enterprisedb.com/platform-compatibility#epas) for details about the support periods and supported platforms for each EDB Postgres Advanced Server version. + + + diff --git a/product_docs/docs/edb_plus/40/04_using_edb_plus.mdx b/product_docs/docs/edb_plus/41/04_using_edb_plus.mdx similarity index 95% rename from product_docs/docs/edb_plus/40/04_using_edb_plus.mdx rename to product_docs/docs/edb_plus/41/04_using_edb_plus.mdx index 80d404b964f..b166fce038c 100644 --- a/product_docs/docs/edb_plus/40/04_using_edb_plus.mdx +++ b/product_docs/docs/edb_plus/41/04_using_edb_plus.mdx @@ -74,7 +74,7 @@ For more information about the `pg_hba.conf` file, see the [PostgreSQL core docu The following example shows user `enterprisedb` with password `password` connecting to database `edb` running on a database server on the localhost at port 5444. ```text -C:\Program Files\edb\as14\edbplus>edbplus enterprisedb/password +C:\Program Files\edb\edbplus>edbplus enterprisedb/password Connected to EnterpriseDB 14.1.0 (localhost:5444/edb) AS enterprisedb EDB*Plus: Release 14 (Build 40.0.0) @@ -86,7 +86,7 @@ SQL> The following example shows user `enterprisedb` with password `password` connecting to database `edb` running on a database server on the localhost at port 5445. ```text -C:\Program Files\edb\as14\edbplus>edbplus enterprisedb/password@localhost:5445/edb +C:\Program Files\edb\edbplus>edbplus enterprisedb/password@localhost:5445/edb Connected to EnterpriseDB 14.1.0 (localhost:5445/edb) AS enterprisedb EDB*Plus: Release 14 (Build 40.0.0) @@ -98,7 +98,7 @@ SQL> Using variable `hr_5445` in the `login.sql` file, the following shows how it is used to connect to database `hr` on localhost at port 5445. ```text -C:\Program Files\edb\as14\edbplus>edbplus enterprisedb/password@hr_5445 +C:\Program Files\edb\edbplus>edbplus enterprisedb/password@hr_5445 Connected to EnterpriseDB 14.0.0 (localhost:5445/hr) AS enterprisedb EDB*Plus: Release 14 (Build 40.1.0) @@ -117,7 +117,7 @@ define hr_5445="localhost:5445/hr" The following example executes a script file, `dept_query.sql`, after connecting to database `edb` on server localhost at port 5444. ```sql -C:\Program Files\edb\as14\edbplus>edbplus enterprisedb/password @dept_query +C:\Program Files\edb\edbplus>edbplus enterprisedb/password @dept_query Connected to EnterpriseDB 14.1.0 (localhost:5444/edb) AS enterprisedb SQL> SELECT * FROM dept; diff --git a/product_docs/docs/edb_plus/40/05_using_edb_plus_with_ssl.mdx b/product_docs/docs/edb_plus/41/05_using_edb_plus_with_ssl.mdx similarity index 96% rename from product_docs/docs/edb_plus/40/05_using_edb_plus_with_ssl.mdx rename to product_docs/docs/edb_plus/41/05_using_edb_plus_with_ssl.mdx index fc908f00621..337d345fef2 100644 --- a/product_docs/docs/edb_plus/40/05_using_edb_plus_with_ssl.mdx +++ b/product_docs/docs/edb_plus/41/05_using_edb_plus_with_ssl.mdx @@ -39,7 +39,7 @@ writing new private key to 'server.key' ``` !!! Note - When creating the certificate, the value specified for the common name field (`CN=enterprisedb` in this example) must be the database user name that is specified when connecting to EDB\*Plus. + When creating the certificate, the value specified for the common name field (`CN=enterprisedb` in this example) must be the host name that is specified when connecting to EDB\*Plus. In addition, you can use user name maps as defined in the `pg_ident.conf` file to permit more flexibility for the common name and database user name, described in later steps. @@ -67,12 +67,12 @@ $ cp server.crt root.crt $ rm -f server.csr ``` -**Step 5:** Move or copy the certificate and private key files to the EDB Postgres Advanced Server data directory (for example, `/opt/edb/as14/data`). +**Step 5:** Move or copy the certificate and private key files to the EDB Postgres Advanced Server data directory (for example, `/var/lib/edb/as15/data`). ```shell -$ mv root.crt /opt/edb/as14/data -$ mv server.crt /opt/edb/as14/data -$ mv server.key /opt/edb/as14/data +$ mv root.crt /var/lib/edb/as15/data +$ mv server.crt /var/lib/edb/as15/data +$ mv server.key /var/lib/edb/as15/data ``` **Step 6:** Set the file ownership and permissions on the certificate files and private key file. @@ -106,7 +106,7 @@ ssl_ca_file = 'root.crt' In the `pg_hba.conf` file, the `hostssl` type indicates the entry is used to validate SSL connection attempts from the client (EDB\*Plus). -The authentication method is set to `cert` with the option `clientcert=1`. This setting requires an SSL certificate from the client against which authentication is performed using the common name of the certificate (`enterprisedb` in this example). +The authentication method is set to `cert` with the option `clientcert=verify-full`. This setting requires an SSL certificate from the client against which authentication is performed using the common name of the certificate (`enterprisedb` in this example). The `map=sslusers` option specifies to use a mapping named `sslusers` defined in the `pg_ident.conf` file for authentication. This mapping allows a connection to the database if the common name from the certificate and the database user name attempting the connection match the `SYSTEM-USERNAME/PG-USERNAME` pair listed in the `pg_ident.conf` file. @@ -118,7 +118,7 @@ The following is an example of the settings in the `pg_hba.conf` file if the dat # "local" is for Unix domain socket connections only local all all md5 # IPv4 local connections: -hostssl edb all 192.168.2.0/24 cert clientcert=1 map=sslusers +hostssl edb all 192.168.2.0/24 cert clientcert=verify-full map=sslusers ``` **Step 9:** The following shows the username maps in the `pg_ident.conf` file related to the `pg_hba.conf` file by the `map=sslusers` option. These username maps permit you to specify database user names `edbuser`, `postgres`, or `enterprisedb` when connecting with EDB\*Plus. @@ -176,7 +176,7 @@ The `keytool` program can be found under the `bin` subdirectory of the Java Runt You are prompted for a new password. Save this password as you must specify it with the `PGSSLCERTPASS` environment variable. -```text +```shell $ /usr/java/jdk1.8.0_131/jre/bin/keytool -keystore postgresql.keystore \ > -alias postgresqlstore -import -file edb_root.crt.der Enter keystore password: @@ -260,7 +260,7 @@ The `pg_hba.conf` file of the database server contains the following entry for c # "local" is for Unix domain socket connections only local all all md5 # IPv4 local connections: -hostssl edb all 192.168.2.24/32 cert clientcert=1 +hostssl edb all 192.168.2.24/32 cert clientcert=verify-full ``` On the remote host where EDB\*Plus is invoked, the Linux user account named `user` contains the certificate and keystore files in its `~/.postgresql` directory: @@ -282,7 +282,7 @@ Logged into Linux with the account named `user`, EDB\*Plus is successfully invok ```shell $ export PGSSLCERTPASS=keypass $ export PGSSLKEYPASS=exppass -$ cd /opt/edb/as14/edbplus +$ cd /usr/edb/edbplus $ ./edbplus.sh enterprisedb/password@192.168.2.22:5444/edb?ssl=true Connected to EnterpriseDB 14.0.0 (192.168.2.22:5444/edb) AS enterprisedb @@ -299,7 +299,7 @@ $ export PGSSLCERT=/home/user/ssl/postgresql.keystore $ export PGSSLKEY=/home/user/ssl/postgresql.p12 $ export PGSSLCERTPASS=keypass $ export PGSSLKEYPASS=exppass -$ cd /opt/edb/as14/edbplus +$ cd /usr/edb/edbplus $ ./edbplus.sh enterprisedb/password@192.168.2.22:5444/edb?ssl=true Connected to EnterpriseDB 14.0.0 (192.168.2.22:5444/edb) AS enterprisedb diff --git a/product_docs/docs/edb_plus/40/06_command_summary.mdx b/product_docs/docs/edb_plus/41/06_command_summary.mdx similarity index 99% rename from product_docs/docs/edb_plus/40/06_command_summary.mdx rename to product_docs/docs/edb_plus/41/06_command_summary.mdx index ea14d5608dd..410e329ecec 100644 --- a/product_docs/docs/edb_plus/40/06_command_summary.mdx +++ b/product_docs/docs/edb_plus/41/06_command_summary.mdx @@ -308,7 +308,7 @@ Connected to EnterpriseDB 14.0.0 (localhost:5444/edb) AS enterprisedb The `DEFINE` command creates or replaces the value of a *user variable* (also called a *substitution variable*). -```text +```sql DEF[INE ] [ variable [ = text ] ] ``` diff --git a/product_docs/docs/edb_plus/39/images/advanced_server_installation_details.png b/product_docs/docs/edb_plus/41/images/advanced_server_installation_details.png similarity index 100% rename from product_docs/docs/edb_plus/39/images/advanced_server_installation_details.png rename to product_docs/docs/edb_plus/41/images/advanced_server_installation_details.png diff --git a/product_docs/docs/edb_plus/36/images/edb_logo.png b/product_docs/docs/edb_plus/41/images/edb_logo.png similarity index 100% rename from product_docs/docs/edb_plus/36/images/edb_logo.png rename to product_docs/docs/edb_plus/41/images/edb_logo.png diff --git a/product_docs/docs/edb_plus/36/images/edb_logo.svg b/product_docs/docs/edb_plus/41/images/edb_logo.svg similarity index 100% rename from product_docs/docs/edb_plus/36/images/edb_logo.svg rename to product_docs/docs/edb_plus/41/images/edb_logo.svg diff --git a/product_docs/docs/edb_plus/36/images/edb_plus_welcome.png b/product_docs/docs/edb_plus/41/images/edb_plus_welcome.png similarity index 100% rename from product_docs/docs/edb_plus/36/images/edb_plus_welcome.png rename to product_docs/docs/edb_plus/41/images/edb_plus_welcome.png diff --git a/product_docs/docs/edb_plus/39/images/installation_complete.png b/product_docs/docs/edb_plus/41/images/installation_complete.png similarity index 100% rename from product_docs/docs/edb_plus/39/images/installation_complete.png rename to product_docs/docs/edb_plus/41/images/installation_complete.png diff --git a/product_docs/docs/edb_plus/41/images/installation_directory-new.png b/product_docs/docs/edb_plus/41/images/installation_directory-new.png new file mode 100644 index 00000000000..2edd58e5baf --- /dev/null +++ b/product_docs/docs/edb_plus/41/images/installation_directory-new.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:569da40e608f37f226071a85475abe7ae91ef26e1b493594532f8a567c01e9bb +size 20943 diff --git a/product_docs/docs/edb_plus/40/images/installation_directory.png b/product_docs/docs/edb_plus/41/images/installation_directory.png similarity index 100% rename from product_docs/docs/edb_plus/40/images/installation_directory.png rename to product_docs/docs/edb_plus/41/images/installation_directory.png diff --git a/product_docs/docs/edb_plus/41/images/installation_directory_new.png b/product_docs/docs/edb_plus/41/images/installation_directory_new.png new file mode 100644 index 00000000000..2edd58e5baf --- /dev/null +++ b/product_docs/docs/edb_plus/41/images/installation_directory_new.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:569da40e608f37f226071a85475abe7ae91ef26e1b493594532f8a567c01e9bb +size 20943 diff --git a/product_docs/docs/edb_plus/39/images/ready_to_install.png b/product_docs/docs/edb_plus/41/images/ready_to_install.png similarity index 100% rename from product_docs/docs/edb_plus/39/images/ready_to_install.png rename to product_docs/docs/edb_plus/41/images/ready_to_install.png diff --git a/product_docs/docs/edb_plus/40/index.mdx b/product_docs/docs/edb_plus/41/index.mdx similarity index 100% rename from product_docs/docs/edb_plus/40/index.mdx rename to product_docs/docs/edb_plus/41/index.mdx diff --git a/product_docs/docs/edb_plus/40/installing/configuring_linux_installation.mdx b/product_docs/docs/edb_plus/41/installing/configuring_linux_installation.mdx similarity index 100% rename from product_docs/docs/edb_plus/40/installing/configuring_linux_installation.mdx rename to product_docs/docs/edb_plus/41/installing/configuring_linux_installation.mdx diff --git a/product_docs/docs/edb_plus/40/installing/index.mdx b/product_docs/docs/edb_plus/41/installing/index.mdx similarity index 100% rename from product_docs/docs/edb_plus/40/installing/index.mdx rename to product_docs/docs/edb_plus/41/installing/index.mdx diff --git a/product_docs/docs/edb_plus/40/installing/linux_ppc64le/edbplus_rhel_8.mdx b/product_docs/docs/edb_plus/41/installing/linux_ppc64le/edbplus_rhel_8.mdx similarity index 81% rename from product_docs/docs/edb_plus/40/installing/linux_ppc64le/edbplus_rhel_8.mdx rename to product_docs/docs/edb_plus/41/installing/linux_ppc64le/edbplus_rhel_8.mdx index 6fa47affc81..c9c0134f1da 100644 --- a/product_docs/docs/edb_plus/40/installing/linux_ppc64le/edbplus_rhel_8.mdx +++ b/product_docs/docs/edb_plus/41/installing/linux_ppc64le/edbplus_rhel_8.mdx @@ -6,7 +6,7 @@ title: Installing EDB*Plus on RHEL 8 ppc64le # the documentation team will update the templates accordingly. redirects: - - /edb_plus/40/03_installing_edb_plus/install_on_linux/ibm_power_ppc64le/edbplus_rhel8_ppcle + - /edb_plus/41/03_installing_edb_plus/install_on_linux/ibm_power_ppc64le/edbplus_rhel8_ppcle --- ## Prerequisites @@ -38,11 +38,9 @@ Before you begin the installation process: ## Install the package ```shell -sudo dnf -y install edb-as-edbplus +sudo dnf -y install edb-edbplus ``` -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. - ## Initial configuration After performing a Linux installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation: diff --git a/product_docs/docs/edb_plus/40/installing/linux_ppc64le/edbplus_sles_12.mdx b/product_docs/docs/edb_plus/41/installing/linux_ppc64le/edbplus_sles_12.mdx similarity index 81% rename from product_docs/docs/edb_plus/40/installing/linux_ppc64le/edbplus_sles_12.mdx rename to product_docs/docs/edb_plus/41/installing/linux_ppc64le/edbplus_sles_12.mdx index 7a25ce520ff..00d5d0a0caf 100644 --- a/product_docs/docs/edb_plus/40/installing/linux_ppc64le/edbplus_sles_12.mdx +++ b/product_docs/docs/edb_plus/41/installing/linux_ppc64le/edbplus_sles_12.mdx @@ -6,7 +6,7 @@ title: Installing EDB*Plus on SLES 12 ppc64le # the documentation team will update the templates accordingly. redirects: - - /edb_plus/40/03_installing_edb_plus/install_on_linux/ibm_power_ppc64le/edbplus_sles12_ppcle + - /edb_plus/41/03_installing_edb_plus/install_on_linux/ibm_power_ppc64le/edbplus_sles12_ppcle --- ## Prerequisites @@ -39,11 +39,9 @@ Before you begin the installation process: ## Install the package ```shell -sudo zypper -n install edb-as-edbplus +sudo zypper -n install edb-edbplus ``` -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. - ## Initial configuration After performing a Linux installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation: diff --git a/product_docs/docs/edb_plus/40/installing/linux_ppc64le/edbplus_sles_15.mdx b/product_docs/docs/edb_plus/41/installing/linux_ppc64le/edbplus_sles_15.mdx similarity index 81% rename from product_docs/docs/edb_plus/40/installing/linux_ppc64le/edbplus_sles_15.mdx rename to product_docs/docs/edb_plus/41/installing/linux_ppc64le/edbplus_sles_15.mdx index fcc6b71166b..6ec43efcfde 100644 --- a/product_docs/docs/edb_plus/40/installing/linux_ppc64le/edbplus_sles_15.mdx +++ b/product_docs/docs/edb_plus/41/installing/linux_ppc64le/edbplus_sles_15.mdx @@ -6,7 +6,7 @@ title: Installing EDB*Plus on SLES 15 ppc64le # the documentation team will update the templates accordingly. redirects: - - /edb_plus/40/03_installing_edb_plus/install_on_linux/ibm_power_ppc64le/edbplus_sles15_ppcle + - /edb_plus/41/03_installing_edb_plus/install_on_linux/ibm_power_ppc64le/edbplus_sles15_ppcle --- ## Prerequisites @@ -38,11 +38,9 @@ Before you begin the installation process: ## Install the package ```shell -sudo zypper -n install edb-as-edbplus +sudo zypper -n install edb-edbplus ``` -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. - ## Initial configuration After performing a Linux installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation: diff --git a/product_docs/docs/edb_plus/40/installing/linux_ppc64le/index.mdx b/product_docs/docs/edb_plus/41/installing/linux_ppc64le/index.mdx similarity index 100% rename from product_docs/docs/edb_plus/40/installing/linux_ppc64le/index.mdx rename to product_docs/docs/edb_plus/41/installing/linux_ppc64le/index.mdx diff --git a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_centos_7.mdx b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_centos_7.mdx similarity index 81% rename from product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_centos_7.mdx rename to product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_centos_7.mdx index 5fca017765d..98e0abd548b 100644 --- a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_centos_7.mdx +++ b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_centos_7.mdx @@ -6,7 +6,7 @@ title: Installing EDB*Plus on CentOS 7 x86_64 # the documentation team will update the templates accordingly. redirects: - - /edb_plus/40/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_centos7_x86 + - /edb_plus/41/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_centos7_x86 --- ## Prerequisites @@ -36,11 +36,9 @@ Before you begin the installation process: ## Install the package ```shell -sudo yum -y install edb-as-edbplus +sudo yum -y install edb-edbplus ``` -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. - ## Initial configuration After performing a Linux installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation: diff --git a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_debian_10.mdx b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_debian_10.mdx similarity index 78% rename from product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_debian_10.mdx rename to product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_debian_10.mdx index ed9cf205663..9c635c52443 100644 --- a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_debian_10.mdx +++ b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_debian_10.mdx @@ -6,7 +6,7 @@ title: Installing EDB*Plus on Debian 10 x86_64 # the documentation team will update the templates accordingly. redirects: - - /edb_plus/40/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_deb10_x86 + - /edb_plus/41/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_deb10_x86 --- ## Prerequisites @@ -28,11 +28,9 @@ Before you begin the installation process: ## Install the package ```shell -sudo apt-get -y install edb-as-edbplus +sudo apt-get -y install edb-edbplus ``` -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. - ## Initial configuration After performing a Linux installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation: diff --git a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_debian_11.mdx b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_debian_11.mdx similarity index 78% rename from product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_debian_11.mdx rename to product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_debian_11.mdx index e059f64015d..d79ff288782 100644 --- a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_debian_11.mdx +++ b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_debian_11.mdx @@ -6,7 +6,7 @@ title: Installing EDB*Plus on Debian 11 x86_64 # the documentation team will update the templates accordingly. redirects: - - /edb_plus/40/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_deb11_x86 + - /edb_plus/41/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_deb11_x86 --- ## Prerequisites @@ -28,11 +28,9 @@ Before you begin the installation process: ## Install the package ```shell -sudo apt-get -y install edb-as-edbplus +sudo apt-get -y install edb-edbplus ``` -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. - ## Initial configuration After performing a Linux installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation: diff --git a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_other_linux_8.mdx b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_other_linux_8.mdx similarity index 79% rename from product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_other_linux_8.mdx rename to product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_other_linux_8.mdx index 54b223dca90..5970c96a476 100644 --- a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_other_linux_8.mdx +++ b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_other_linux_8.mdx @@ -6,7 +6,7 @@ title: Installing EDB*Plus on AlmaLinux 8 or Rocky Linux 8 x86_64 # the documentation team will update the templates accordingly. redirects: - - /edb_plus/40/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_other_linux8_x86 + - /edb_plus/41/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_other_linux8_x86 --- ## Prerequisites @@ -30,17 +30,15 @@ Before you begin the installation process: # Install the EPEL repository: sudo dnf -y install epel-release # Enable additional repositories to resolve dependencies: - sudo dnf config-manager --set-enabled PowerTools + sudo dnf config-manager --set-enabled powertools ``` ## Install the package ```shell -sudo dnf -y install edb-as-edbplus +sudo dnf -y install edb-edbplus ``` -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. - ## Initial configuration After performing a Linux installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation: diff --git a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_rhel_7.mdx b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_rhel_7.mdx similarity index 83% rename from product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_rhel_7.mdx rename to product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_rhel_7.mdx index 2b15ef8ef80..b09476f4393 100644 --- a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_rhel_7.mdx +++ b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_rhel_7.mdx @@ -6,7 +6,7 @@ title: Installing EDB*Plus on RHEL 7 or OL 7 x86_64 # the documentation team will update the templates accordingly. redirects: - - /edb_plus/40/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_rhel7_x86 + - /edb_plus/41/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_rhel7_x86 --- ## Prerequisites @@ -36,11 +36,9 @@ Before you begin the installation process: ## Install the package ```shell -sudo yum -y install edb-as-edbplus +sudo yum -y install edb-edbplus ``` -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. - ## Initial configuration After performing a Linux installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation: diff --git a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_rhel_8.mdx b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_rhel_8.mdx similarity index 81% rename from product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_rhel_8.mdx rename to product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_rhel_8.mdx index cac12133bb9..e9fd10ce00e 100644 --- a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_rhel_8.mdx +++ b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_rhel_8.mdx @@ -6,7 +6,7 @@ title: Installing EDB*Plus on RHEL 8 or OL 8 x86_64 # the documentation team will update the templates accordingly. redirects: - - /edb_plus/40/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_rhel8_x86 + - /edb_plus/41/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_rhel8_x86 --- ## Prerequisites @@ -36,11 +36,9 @@ Before you begin the installation process: ## Install the package ```shell -sudo dnf -y install edb-as-edbplus +sudo dnf -y install edb-edbplus ``` -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. - ## Initial configuration After performing a Linux installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation: diff --git a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_sles_12.mdx b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_sles_12.mdx similarity index 81% rename from product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_sles_12.mdx rename to product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_sles_12.mdx index 539db09fc5b..00bb9501623 100644 --- a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_sles_12.mdx +++ b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_sles_12.mdx @@ -6,7 +6,7 @@ title: Installing EDB*Plus on SLES 12 x86_64 # the documentation team will update the templates accordingly. redirects: - - /edb_plus/40/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_sles12_x86 + - /edb_plus/41/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_sles12_x86 --- ## Prerequisites @@ -39,11 +39,9 @@ Before you begin the installation process: ## Install the package ```shell -sudo zypper -n install edb-as-edbplus +sudo zypper -n install edb-edbplus ``` -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. - ## Initial configuration After performing a Linux installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation: diff --git a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_sles_15.mdx b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_sles_15.mdx similarity index 81% rename from product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_sles_15.mdx rename to product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_sles_15.mdx index c95e2b2392b..3ab7cf02ee1 100644 --- a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_sles_15.mdx +++ b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_sles_15.mdx @@ -6,7 +6,7 @@ title: Installing EDB*Plus on SLES 15 x86_64 # the documentation team will update the templates accordingly. redirects: - - /edb_plus/40/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_sles15_x86 + - /edb_plus/41/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_sles15_x86 --- ## Prerequisites @@ -38,11 +38,9 @@ Before you begin the installation process: ## Install the package ```shell -sudo zypper -n install edb-as-edbplus +sudo zypper -n install edb-edbplus ``` -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. - ## Initial configuration After performing a Linux installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation: diff --git a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_ubuntu_18.mdx b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_ubuntu_18.mdx similarity index 79% rename from product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_ubuntu_18.mdx rename to product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_ubuntu_18.mdx index 5195afe88ca..878c9e2a020 100644 --- a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_ubuntu_18.mdx +++ b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_ubuntu_18.mdx @@ -6,7 +6,7 @@ title: Installing EDB*Plus on Ubuntu 18.04 x86_64 # the documentation team will update the templates accordingly. redirects: - - /edb_plus/40/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_ubuntu18_x86 + - /edb_plus/41/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_ubuntu18_x86 --- ## Prerequisites @@ -28,11 +28,9 @@ Before you begin the installation process: ## Install the package ```shell -sudo apt-get -y install edb-as-edbplus +sudo apt-get -y install edb-edbplus ``` -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. - ## Initial configuration After performing a Linux installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation: diff --git a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_ubuntu_20.mdx b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_ubuntu_20.mdx similarity index 79% rename from product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_ubuntu_20.mdx rename to product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_ubuntu_20.mdx index 5b7c127f4e6..9b989c33da1 100644 --- a/product_docs/docs/edb_plus/40/installing/linux_x86_64/edbplus_ubuntu_20.mdx +++ b/product_docs/docs/edb_plus/41/installing/linux_x86_64/edbplus_ubuntu_20.mdx @@ -6,7 +6,7 @@ title: Installing EDB*Plus on Ubuntu 20.04 x86_64 # the documentation team will update the templates accordingly. redirects: - - /edb_plus/40/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_ubuntu20_x86 + - /edb_plus/41/03_installing_edb_plus/install_on_linux/x86_amd64/edbplus_ubuntu20_x86 --- ## Prerequisites @@ -28,11 +28,9 @@ Before you begin the installation process: ## Install the package ```shell -sudo apt-get -y install edb-as-edbplus +sudo apt-get -y install edb-edbplus ``` -Where `` is the version of EDB Postgres Advanced Server. For example, if you are installing with version 14 of EDB Postgres Advanced Server, the package name would be `edb-as14-edbplus`. - ## Initial configuration After performing a Linux installation of EDB\*Plus, you must set the values of environment variables that allow EDB\*Plus to locate your Java installation: diff --git a/product_docs/docs/edb_plus/40/installing/linux_x86_64/index.mdx b/product_docs/docs/edb_plus/41/installing/linux_x86_64/index.mdx similarity index 100% rename from product_docs/docs/edb_plus/40/installing/linux_x86_64/index.mdx rename to product_docs/docs/edb_plus/41/installing/linux_x86_64/index.mdx diff --git a/product_docs/docs/edb_plus/40/installing/windows.mdx b/product_docs/docs/edb_plus/41/installing/windows.mdx similarity index 69% rename from product_docs/docs/edb_plus/40/installing/windows.mdx rename to product_docs/docs/edb_plus/41/installing/windows.mdx index 72ee9e3abd8..bec5f2a0ff3 100644 --- a/product_docs/docs/edb_plus/40/installing/windows.mdx +++ b/product_docs/docs/edb_plus/41/installing/windows.mdx @@ -8,7 +8,7 @@ Before installing EDB\*Plus, you must first install Java (version 1.8 or later). -Windows installers for EDB\*Plus are available via StackBuilder Plus; you can access StackBuilder Plus through the Windows start menu. After opening StackBuilder Plus and selecting the installation for which you wamnt to install EDB\*Plus, expand the component selection screen tree control to select and download the EDB\*Plus installer. +Windows installers for EDB\*Plus are available via StackBuilder Plus; you can access StackBuilder Plus through the Windows start menu. After opening StackBuilder Plus and selecting the installation for which you want to install EDB\*Plus, expand the component selection screen tree control to select and download the EDB\*Plus installer. ![The EDBPlus Welcome window](../images/edb_plus_welcome.png) @@ -16,23 +16,12 @@ Windows installers for EDB\*Plus are available via StackBuilder Plus; you can ac The EDB\*Plus installer welcomes you to the setup wizard, as shown in the figure below. -![The Installation Directory window](../images/installation_directory.png) +![The Installation Directory window](../images/installation_directory_new.png)
Fig. 2: The Installation Directory window
Use the `Installation Directory` field to specify the directory in which you wish to install the EDB\*Plus software. Then, click `Next` to continue. -![The Advanced Server Installation Details window](../images/advanced_server_installation_details.png) - -
Fig. 3: The Advanced Server Installation Details window
- -Use fields on the `EDB Postgres Advanced Server Installation Details` window to identify the location of the Advanced Server host: - -- Use the `Host` field to identify the system on which Advanced Server resides. -- Use the `Port` field to identify the listener port that Advanced Server monitors for client connections. - -Then, click `Next` to continue. - ![The Ready to Install window](../images/ready_to_install.png)
Fig. 4: The Ready to Install window
diff --git a/product_docs/docs/efm/4/efm_deploy_arch/06_efm_pgpool.mdx b/product_docs/docs/efm/4/efm_deploy_arch/06_efm_pgpool.mdx index 99b206ea4ad..540ffb46a37 100644 --- a/product_docs/docs/efm/4/efm_deploy_arch/06_efm_pgpool.mdx +++ b/product_docs/docs/efm/4/efm_deploy_arch/06_efm_pgpool.mdx @@ -220,8 +220,6 @@ and takes charge as the leader EDB Pgpool-II instance. For Failover Manager / EDB Pgpool-II integration using the network load balancer in AWS or Azure, you need to perform some additional steps. - - Add the following rules to the security groups to be used by the EDB Pgpool-II instances: - Rules for the security group to be used by the EDB Pgpool-II instances (SG @@ -274,8 +272,6 @@ traffic to the remaining two EDB Pgpool-II processes. Make sure that the `listen_backlog_multiplier` parameter is tuned to compensate for the higher number of connections in case of failover. - - #### Configuring NLB in AWS The following assumptions have been taken for the sample configuration: diff --git a/product_docs/docs/efm/4/installing/linux_x86_64/efm_other_linux_8.mdx b/product_docs/docs/efm/4/installing/linux_x86_64/efm_other_linux_8.mdx index 96369c9a5b3..6cc6a758c8f 100644 --- a/product_docs/docs/efm/4/installing/linux_x86_64/efm_other_linux_8.mdx +++ b/product_docs/docs/efm/4/installing/linux_x86_64/efm_other_linux_8.mdx @@ -26,7 +26,7 @@ Before you begin the installation process: # Install the EPEL repository: sudo dnf -y install epel-release # Enable additional repositories to resolve dependencies: - sudo dnf config-manager --set-enabled PowerTools + sudo dnf config-manager --set-enabled powertools ``` ## Install the package diff --git a/product_docs/docs/epas/11/installing/linux_x86_64/epas_other_linux_8.mdx b/product_docs/docs/epas/11/installing/linux_x86_64/epas_other_linux_8.mdx index eb18956f784..d09aa7fc9b6 100644 --- a/product_docs/docs/epas/11/installing/linux_x86_64/epas_other_linux_8.mdx +++ b/product_docs/docs/epas/11/installing/linux_x86_64/epas_other_linux_8.mdx @@ -24,7 +24,7 @@ Before you begin the installation process: # Install the EPEL repository: sudo dnf -y install epel-release # Enable additional repositories to resolve dependencies: - sudo dnf config-manager --set-enabled PowerTools + sudo dnf config-manager --set-enabled powertools ``` ## Install the package diff --git a/product_docs/docs/epas/12/installing/linux_x86_64/epas_other_linux_8.mdx b/product_docs/docs/epas/12/installing/linux_x86_64/epas_other_linux_8.mdx index 55631687d3b..bc89f1f2824 100644 --- a/product_docs/docs/epas/12/installing/linux_x86_64/epas_other_linux_8.mdx +++ b/product_docs/docs/epas/12/installing/linux_x86_64/epas_other_linux_8.mdx @@ -24,7 +24,7 @@ Before you begin the installation process: # Install the EPEL repository: sudo dnf -y install epel-release # Enable additional repositories to resolve dependencies: - sudo dnf config-manager --set-enabled PowerTools + sudo dnf config-manager --set-enabled powertools ``` ## Install the package diff --git a/product_docs/docs/epas/13/installing/linux_x86_64/epas_other_linux_8.mdx b/product_docs/docs/epas/13/installing/linux_x86_64/epas_other_linux_8.mdx index 4b72d686039..695961959a4 100644 --- a/product_docs/docs/epas/13/installing/linux_x86_64/epas_other_linux_8.mdx +++ b/product_docs/docs/epas/13/installing/linux_x86_64/epas_other_linux_8.mdx @@ -24,7 +24,7 @@ Before you begin the installation process: # Install the EPEL repository: sudo dnf -y install epel-release # Enable additional repositories to resolve dependencies: - sudo dnf config-manager --set-enabled PowerTools + sudo dnf config-manager --set-enabled powertools ``` ## Install the package diff --git a/product_docs/docs/epas/14/installing/linux_x86_64/epas_other_linux_8.mdx b/product_docs/docs/epas/14/installing/linux_x86_64/epas_other_linux_8.mdx index 27b37daaf1a..b31dbab43d2 100644 --- a/product_docs/docs/epas/14/installing/linux_x86_64/epas_other_linux_8.mdx +++ b/product_docs/docs/epas/14/installing/linux_x86_64/epas_other_linux_8.mdx @@ -24,7 +24,7 @@ Before you begin the installation process: # Install the EPEL repository: sudo dnf -y install epel-release # Enable additional repositories to resolve dependencies: - sudo dnf config-manager --set-enabled PowerTools + sudo dnf config-manager --set-enabled powertools ``` ## Install the package diff --git a/product_docs/docs/epas/15/deployment_options/index.mdx b/product_docs/docs/epas/15/deployment_options/index.mdx new file mode 100644 index 00000000000..c12128a330d --- /dev/null +++ b/product_docs/docs/epas/15/deployment_options/index.mdx @@ -0,0 +1,13 @@ +--- +title: "Deployment options" +--- + +You can deploy and install EDB products using the following methods: + +- [BigAnimal](/biganimal/latest) is a fully managed database-as-a-service with built-in Oracle compatibility, running in your cloud account and operated by the Postgres experts. BigAnimal makes it easy to set up, manage, and scale your databases. Provision PostgreSQL or EDB Postgres Advanced Server with Oracle compatibility. + +- [EDB PostgreSQL for Kubernetes](/postgres_for_kubernetes/latest/) is an operator designed by EnterpriseDB to manage PostgreSQL workloads on any supported Kubernetes cluster running in private, public, hybrid, or multi-cloud environments. EDB PostgreSQL for Kubernetes adheres to DevOps principles and concepts such as declarative configuration and immutable infrastructure. + +- Installation using native packages or installers: + + - [Installing EDB Postgres Advanced Server](/epas/latest/installing) \ No newline at end of file diff --git a/product_docs/docs/epas/15/ecpgplus_guide/02_overview.mdx b/product_docs/docs/epas/15/ecpgplus_guide/02_overview.mdx new file mode 100644 index 00000000000..95e1b618dca --- /dev/null +++ b/product_docs/docs/epas/15/ecpgplus_guide/02_overview.mdx @@ -0,0 +1,260 @@ +--- +title: "ECPGPlus overview" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.07.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.04.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.06.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.05.html" +--- + + + +EDB enhanced ECPG (the PostgreSQL precompiler) to create ECPGPlus. ECPGPlus is a Pro\*C-compatible version of the PostgreSQL C precompiler. ECPGPlus translates a program that combines C code and embedded SQL statements into an equivalent C program. As it performs the translation, ECPGPlus verifies that the syntax of each SQL construct is correct. + +The following diagram charts the path of a program containing embedded SQL statements as it's compiled into an executable: + +![Compilation of a program containing embedded SQL statements](images/ecpg_path.png) + +Compilation of a program containing embedded SQL statements + +To produce an executable from a C program that contains embedded SQL statements: + +1. Pass the program (`my_program.pgc` in the diagram) to the ECPGPlus precompiler. ECPGPlus translates each SQL statement in `my_program.pgc` into C code that calls the `ecpglib` API and produces a C program (`my_program.c`). +1. Pass the C program to a C compiler. The C compiler generates an object file (`my_program.o`). +1. Pass the object file (`my_program.o`) as well as the `ecpglib` library file and any other required libraries to the linker, which in turn produces the executable (`my_program`). + +While the ECPGPlus preprocessor validates the syntax of each SQL statement, it can't validate the semantics. For example, the preprocessor confirms that an `INSERT` statement is syntactically correct, but it can't confirm that the table mentioned in the `INSERT` statement exists. + +## Behind the scenes + +A client application contains a mix of C code and SQL code made up of the following elements: + +- C preprocessor directives +- C declarations (variables, types, functions, ...) +- C definitions (variables, types, functions, ...) +- SQL preprocessor directives +- SQL statements + +For example: + +```c +1 #include +2 EXEC SQL INCLUDE sqlca; +3 +4 extern void printInt(char *label, int val); +5 extern void printStr(char *label, char *val); +6 extern void printFloat(char *label, float val); +7 +8 void displayCustomer(int custNumber) +9 { +10 EXEC SQL BEGIN DECLARE SECTION; +11 VARCHAR custName[50]; +12 float custBalance; +13 int custID = custNumber; +14 EXEC SQL END DECLARE SECTION; +15 +16 EXEC SQL SELECT name, balance +17 INTO :custName, :custBalance +18 FROM customer +19 WHERE id = :custID; +20 +21 printInt("ID", custID); +22 printStr("Name", custName); +23 printFloat("Balance", custBalance); +24 } +``` + +In this code fragment: + +- Line 1 specifies a directive to the C preprocessor. + + C preprocessor directives can be interpreted or ignored. The option is controlled by a command line option (`-C PROC`) entered when you invoke ECPGPlus. In either case, ECPGPlus copies each C preprocessor directive to the output file (4) without change. Any C preprocessor directive found in the source file appears in the output file. + +- Line 2 specifies a directive to the SQL preprocessor. + + SQL preprocessor directives are interpreted by the ECPGPlus preprocessor and aren't copied to the output file. + +- Lines 4 through 6 contain C declarations. + + C declarations are copied to the output file without change, except that each `VARCHAR` declaration is translated into an equivalent `struct` declaration. + +- Lines 10 through 14 contain an embedded-SQL declaration section. + + C variables that you refer to in SQL code are known as *host variables*. If you invoke the ECPGPlus preprocessor in Pro\*C mode (`-C PROC`), you can refer to any C variable in a SQL statement. Otherwise you must declare each host variable in a `BEGIN/END DECLARATION SECTION` pair. + +- Lines 16 through 19 contain a SQL statement. + + SQL statements are translated into calls to the ECPGPlus runtime library. + +- Lines 21 through 23 contain C code. + + C code is copied to the output file without change. + +Prefix any SQL statement with `EXEC SQL`. The SQL statement extends to the next (unquoted) semicolon. For example: + +```sql +printf(“Updating employee salaries\n”); + +EXEC SQL UPDATE emp SET sal = sal * 1.25; +EXEC SQL COMMIT; + +printf(“Employee salaries updated\n”); +``` + +When the preprocessor encounters this code fragment, it passes the C code (the first line and the last line) to the output file without translation and converts each `EXEC SQL` statement into a call to an `ecpglib` function. The result is similar to the following: + +```c +printf("Updating employee salaries\n"); + +{ + ECPGdo( __LINE__, 0, 1, NULL, 0, ECPGst_normal, + "update emp set sal = sal * 1.25", + ECPGt_EOIT, ECPGt_EORT); +} + +{ + ECPGtrans(__LINE__, NULL, "commit"); +} + +printf(“Employee salaries updated\n”); +``` + +## Installation and configuration + +On Windows, ECPGPlus is installed by the EDB Postgres Advanced Server installation wizard as part of the Database Server component. On Linux, install with the `edb-asxx-server-devel` RPM package, where `xx` is the EDB Postgres Advanced Server version number. By default, the executable is located on Windows in: + +```text +C:\Program Files\edb\as14\bin +``` + +On Linux, it's located in: + +```text +/usr/edb/as14/bin +``` + +When invoking the ECPGPlus compiler, the executable must be in your search path (`%PATH%` on Windows, `$PATH` on Linux). For example, the following commands set the search path to include the directory that holds the ECPGPlus executable file `ecpg`. + +On Windows: + +```shell +set EDB_PATH=C:\Program Files\edb\as14\bin +set PATH=%EDB_PATH%;%PATH% +``` + +On Linux: + +```shell +export EDB_PATH==/usr/edb/as14/bin +export PATH=$EDB_PATH:$PATH +``` + +## Constructing a makefile + +A makefile contains a set of instructions that tell the make utility how to transform a program written in C that contains embedded SQL into a C program. To try the examples, you need: + +- A C compiler (and linker) +- The make utility +- ECPGPlus preprocessor and library +- A makefile that contains instructions for ECPGPlus + +The following code is an example of a makefile for the samples included in this documentation. To use the sample code, save it in a file named `makefile` in the directory that contains the source code file. + +```c +INCLUDES = -I$(shell pg_config --includedir) +LIBPATH = -L $(shell pg_config --libdir) +CFLAGS += $(INCLUDES) -g +LDFLAGS += -g +LDLIBS += $(LIBPATH) -lecpg -lpq + +.SUFFIXES: .pgc,.pc + +.pgc.c: + ecpg -c $(INCLUDES) $? + +.pc.c: + ecpg -C PROC -c $(INCLUDES) $? +``` + +The first two lines use the `pg_config` program to locate the necessary header files and library directories: + +```sql +INCLUDES = -I$(shell pg_config --includedir) +LIBPATH = -L $(shell pg_config --libdir) +``` + +The `pg_config` program is shipped with EDB Postgres Advanced Server. + +make knows to use the `CFLAGS` variable when running the C compiler and `LDFLAGS` and `LDLIBS` when invoking the linker. ECPG programs must be linked against the ECPG runtime library (`-lecpg`) and the libpq library (`-lpq`). + +```sql +CFLAGS += $(INCLUDES) -g +LDFLAGS += -g +LDLIBS += $(LIBPATH) -lecpg -lpq +``` + +The sample makefile tells make how to translate a `.pgc` or a `.pc` file into a C program. Two lines in the makefile specify the mode in which the source file is compiled. The first compile option is: + +```c +.pgc.c: + ecpg -c $(INCLUDES) $? +``` + +The first option tells make how to transform a file that ends in `.pgc` (presumably, an ECPG source file) into a file that ends in `.c` (a C program), using community ECPG, without the ECPGPlus enhancements. It invokes the ECPG precompiler with the `-c` flag, which instructs the compiler to convert SQL code into C, using the value of the `INCLUDES` variable and the name of the `.pgc` file. + +```c +.pc.c: + ecpg -C PROC -c $(INCLUDES) $? +``` + +The second option tells make how to transform a file that ends in `.pg` (an ECPG source file) into a file that ends in `.c` (a C program) using the ECPGPlus extensions. It invokes the ECPG precompiler with the `-c` flag, which instructs the compiler to convert SQL code to C. It also uses the `-C PROC` flag, which instructs the compiler to use ECPGPlus in Pro\*C-compatibility mode, using the value of the `INCLUDES` variable and the name of the `.pgc` file. + +When you run make, pass the name of the ECPG source code file you want to compile. For example, to compile an ECPG source code file named `customer_list.pgc`, use the command: + +```shell +make customer_list +``` + +The make utility: + +1. Consults the makefile located in the current directory. +1. Discovers that the makefile contains a rule that compiles `customer_list.pgc` into a C program (`customer_list.c`). +1. Uses the rules built into `make` to compile `customer_list.c` into an executable program. + +## ECPGPlus command line options + +In the sample makefile, make includes the `-C` option when invoking ECPGPlus to invoke ECPGPlus in Pro\*C-compatible mode. + +If you include the `-C` `PROC` keywords on the command line, in addition to the ECPG syntax, you can use Pro\*C command line syntax. For example: + +```shell +$ ecpg -C PROC INCLUDE=/usr/edb/as14/include acct_update.c +``` + +To display a complete list of the other ECPGPlus options available, in the ECPGPlus installation directory, enter: + +```shell +./ecpg --help +``` + +The command line options are: + +| Option | Description | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| -c | Automatically generate C code from embedded SQL code. | +| -C *mode* | Use the `-C` option to specify a compatibility mode:

`INFORMIX`

`INFORMIX_SE`

`PROC` | +| -D *symbol* | Define a preprocessor *symbol*.

The *-D* keyword is not supported when compiling in *PROC mode.* Instead, use the Oracle-style *‘DEFINE=’* clause. | +| -h | Parse a header file, this option includes option `'-c'`. | +| -i | Parse system, include files as well. | +| -I directory | Search *directory* for `include` files. | +| -o *outfile* | Write the result to *outfile*. | +| -r *option* | Specify runtime behavior; *option* can be:

`no_indicator` - Don't use indicators, but instead use special values to represent NULL values.

`prepare` - Prepare all statements before using them.

`questionmarks` - Allow use of a question mark as a placeholder.

`usebulk` - Enable bulk processing for `INSERT`, `UPDATE`, and `DELETE` statements that operate on host variable arrays. | +| --regression | Run in regression testing mode. | +| -t | Turn on `autocommit` of transactions. | +| -l | Disable `#line` directives. | +| --help | Display the help options. | +| --version | Output version information. | + +!!! Note + If you don't specify an output file name when invoking ECPGPlus, the output file name is created by removing the `.pgc` extension from the file name and appending `.c`. diff --git a/product_docs/docs/epas/15/ecpgplus_guide/03_using_embedded_sql.mdx b/product_docs/docs/epas/15/ecpgplus_guide/03_using_embedded_sql.mdx new file mode 100644 index 00000000000..702842fab06 --- /dev/null +++ b/product_docs/docs/epas/15/ecpgplus_guide/03_using_embedded_sql.mdx @@ -0,0 +1,363 @@ +--- +title: "Using embedded SQL" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.11.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.09.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.08.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.12.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.10.html" +--- + + + +## Example: A simple query + +The first code sample shows how to execute a `SELECT` statement that returns a single row, storing the results in a group of host variables. After declaring host variables, it connects to the `edb` sample database using a hard-coded role name and the associated password and queries the `emp` table. The query returns the values into the declared host variables. After checking the value of the `NULL` indicator variable, it prints a simple result set onscreen and closes the connection. + +```c +/************************************************************ + * print_emp.pgc + * + */ +#include + +int main(void) +{ + EXEC SQL BEGIN DECLARE SECTION; + int v_empno; + char v_ename[40]; + double v_sal; + double v_comm; + short v_comm_ind; + EXEC SQL END DECLARE SECTION; + + EXEC SQL WHENEVER SQLERROR sqlprint; + + EXEC SQL CONNECT TO edb + USER 'alice' IDENTIFIED BY '1safepwd'; + + EXEC SQL + SELECT + empno, ename, sal, comm + INTO + :v_empno, :v_ename, :v_sal, :v_comm INDICATOR:v_comm_ind + FROM + emp + WHERE + empno = 7369; + + if (v_comm_ind) + printf("empno(%d), ename(%s), sal(%.2f) comm(NULL)\n", + v_empno, v_ename, v_sal); + else + printf("empno(%d), ename(%s), sal(%.2f) comm(%.2f)\n", + v_empno, v_ename, v_sal, v_comm); + EXEC SQL DISCONNECT; +} +/***********************************************************\* +``` + +The code sample begins by including the prototypes and type definitions for the C `stdio` library and then declares the `main` function: + +```c +#include + +int main(void) +{ +``` + +Next, the application declares a set of host variables used to interact with the database server: + +```c +EXEC SQL BEGIN DECLARE SECTION; + int v_empno; + char v_ename[40]; + double v_sal; + double v_comm; + short v_comm_ind; +EXEC SQL END DECLARE SECTION; +``` + +If you plan to precompile the code in `PROC` mode, you can omit the `BEGIN DECLARE…END DECLARE` section. For more information about declaring host variables, see [Declaring host variables](#declaring-host-variables). + +The data type associated with each variable in the declaration section is a C data type. Data passed between the server and the client application must share a compatible data type. For more information about data types, see the [Supported C data types](07_reference/#supported-c-data-types). + +The next statement tells the server how to handle an error: + +```sql +EXEC SQL WHENEVER SQLERROR sqlprint; +``` + +If the client application encounters an error in the SQL code, the server prints an error message to `stderr` (standard error), using the `sqlprint()` function supplied with `ecpglib`. The next `EXEC SQL` statement establishes a connection with EDB Postgres Advanced Server: + +```sql +EXEC SQL CONNECT TO edb + USER 'alice' IDENTIFIED BY '1safepwd'; +``` + +In this example, the client application connects to the `edb` database using a role named alice with a password of `1safepwd`. + +The code then performs a query against the `emp` table: + +```sql +EXEC SQL + SELECT + empno, ename, sal, comm + INTO + :v_empno, :v_ename, :v_sal, :v_comm INDICATOR :v_comm_ind + FROM + emp + WHERE + empno = 7369; +``` + +The query returns information about employee number 7369. + +The `SELECT` statement uses an `INTO` clause to assign the retrieved values (from the `empno`, `ename`, `sal`, and `comm` columns) into the `:v_empno`, `:v_ename`, `:v_sal`, and `:v_comm` host variables (and the `:v_comm_ind` null indicator). The first value retrieved is assigned to the first variable listed in the `INTO` clause, the second value is assigned to the second variable, and so on. + +The `comm` column contains the commission values earned by an employee and can potentially contain a `NULL` value. The statement includes the `INDICATOR` keyword and a host variable to hold a null indicator. + +The code checks the null indicator and displays the appropriate results: + +```C +if (v_comm_ind) + printf("empno(%d), ename(%s), sal(%.2f) comm(NULL)\n", + v_empno, v_ename, v_sal); +else + printf("empno(%d), ename(%s), sal(%.2f) comm(%.2f)\n", + v_empno, v_ename, v_sal, v_comm); +``` + +If the null indicator is `0` (that is, `false`), the `comm` column contains a meaningful value, and the `printf` function displays the commission. If the null indicator contains a non-zero value, `comm` is `NULL`, and `printf` displays a value of `NULL`. A host variable (other than a null indicator) contains no meaningful value if you fetch a `NULL` into that host variable. You must use null indicators to identify any value that might be `NULL`. + +The final statement in the code sample closes the connection to the server: + +```sql +EXEC SQL DISCONNECT; +} +``` + +### Using indicator variables + +The previous example included an *indicator variable* that identifies any row in which the value of the `comm` column (when returned by the server) was `NULL`. An indicator variable is an extra host variable that denotes if the content of the preceding variable is `NULL` or truncated. The indicator variable is populated when the contents of a row are stored. An indicator variable can contain the following values: + +| Indicator value | Denotes | +| --------------------------------------------- | -------------------------------------------------------------------------------- | +| If an indicator variable is less than `0`. | The value returned by the server was `NULL`. | +| If an indicator variable is equal to `0`. | The value returned by the server was not `NULL`, and was not truncated. | +| If an indicator variable is greater than `0`. | The value returned by the server was truncated when stored in the host variable. | + +When including an indicator variable in an `INTO` clause, you don't need to include the optional `INDICATOR` keyword. + +You can omit an indicator variable if you're certain that a query never returns a `NULL` value into the corresponding host variable. If you omit an indicator variable and a query returns a `NULL` value, `ecpglib` raises a runtime error. + + + +### Declaring host variables + +You can use a *host variable* in a SQL statement at any point that a value can appear in that statement. A host variable is a C variable that you can use to pass data values from the client application to the server and return data from the server to the client application. A host variable can be: + +- An array +- A `typedef` +- A pointer +- A `struct` +- Any scalar C data type + +The code fragments that follow show using host variables in code compiled in `PROC` mode and in non-`PROC` mode. The SQL statement adds a row to the `dept` table, inserting the values returned by the variables `v_deptno`, `v_dname`, and `v_loc` into the `deptno` column, the `dname` column, and the `loc` column, respectively. + +If you're compiling in `PROC` mode, you can omit the `EXEC SQL BEGIN DECLARE SECTION` and `EXEC SQL END DECLARE SECTION` directives. `PROC` mode permits you to use C function parameters as host variables: + +```c +void addDept(int v_deptno, char v_dname, char v_loc) +{ + EXEC SQL INSERT INTO dept VALUES( :v_deptno, :v_dname, :v_loc); +} +``` + +If you aren't compiling in `PROC` mode, you must wrap embedded variable declarations with the `EXEC SQL BEGIN DECLARE SECTION` and the `EXEC SQL END DECLARE SECTION` directives: + +```c +void addDept(int v_deptno, char v_dname, char v_loc) +{ + EXEC SQL BEGIN DECLARE SECTION; + int v_deptno_copy = v_deptno; + char v_dname_copy[14+1] = v_dname; + char v_loc_copy[13+1] = v_loc; + EXEC SQL END DECLARE SECTION; + + EXEC SQL INSERT INTO dept VALUES( :v_deptno, :v_dname, :v_loc); +} +``` + +You can also include the `INTO` clause in a `SELECT` statement to use the host variables to retrieve information: + +```sql +EXEC SQL SELECT deptno, dname, loc + INTO :v_deptno, :v_dname, v_loc FROM dept; +``` + +Each column returned by the `SELECT` statement must have a type-compatible target variable in the `INTO` clause. This is a simple example that retrieves a single row. To retrieve more than one row, you must define a cursor, as shown in the next example. + +## Example: Using a cursor to process a result set + +The code sample that follows shows using a cursor to process a result set. Four basic steps are involved in creating and using a cursor: + +1. Use the `DECLARE CURSOR` statement to define a cursor. +2. Use the `OPEN CURSOR` statement to open the cursor. +3. Use the `FETCH` statement to retrieve data from a cursor. +4. Use the `CLOSE CURSOR` statement to close the cursor. + +After declaring host variables, the example connects to the `edb` database using a user-supplied role name and password and queries the `emp` table. The query returns the values into a cursor named `employees`. The code sample then opens the cursor and loops through the result set a row at a time, printing the result set. When the sample detects the end of the result set, it closes the connection. + +```c +/************************************************************ + * print_emps.pgc + * + */ +#include + +int main(int argc, char *argv[]) +{ + EXEC SQL BEGIN DECLARE SECTION; + char *username = argv[1]; + char *password = argv[2]; + int v_empno; + char v_ename[40]; + double v_sal; + double v_comm; + short v_comm_ind; + EXEC SQL END DECLARE SECTION; + + EXEC SQL WHENEVER SQLERROR sqlprint; + + EXEC SQL CONNECT TO edb USER :username IDENTIFIED BY :password; + + EXEC SQL DECLARE employees CURSOR FOR + SELECT + empno, ename, sal, comm  + FROM  + emp; + + EXEC SQL OPEN employees; + + EXEC SQL WHENEVER NOT FOUND DO break; + + for (;;) + { + EXEC SQL FETCH NEXT FROM employees  + INTO + :v_empno, :v_ename, :v_sal, :v_comm INDICATOR :v_comm_ind; + + if (v_comm_ind) + printf("empno(%d), ename(%s), sal(%.2f) comm(NULL)\n", + v_empno, v_ename, v_sal); + else + printf("empno(%d), ename(%s), sal(%.2f) comm(%.2f)\n", + v_empno, v_ename, v_sal, v_comm); + } + EXEC SQL CLOSE employees; + EXEC SQL DISCONNECT; +} +/************************************************************ +``` + +The code sample begins by including the prototypes and type definitions for the C `stdio` library and then declares the `main` function: + +```c +#include + +int main(int argc, char *argv[]) +{ +``` + +Next, the application declares a set of host variables used to interact with the database server: + +```sql +EXEC SQL BEGIN DECLARE SECTION; + char *username = argv[1]; + char *password = argv[2]; + int v_empno; + char v_ename[40]; + double v_sal; + double v_comm; + short v_comm_ind; +EXEC SQL END DECLARE SECTION; +``` + +`argv[]` is an array that contains the command line arguments entered when the user runs the client application. `argv[1]` contains the first command line argument (in this case, a `username`), and `argv[2]` contains the second command line argument (a `password`). The example omits the error-checking code you would normally include a real-world application. The declaration initializes the values of `username` and `password`, setting them to the values entered when the user invoked the client application. + +You might think that you can refer to `argv[1]` and `argv[2]` in a SQL statement instead of creating a separate copy of each variable. However, that doesn't work. All host variables must be declared in a `BEGIN/END DECLARE SECTION`, unless you're compiling in `PROC` mode. Since `argv` is a function *parameter* (not an automatic variable), you can't declare it in a `BEGIN/END DECLARE SECTION`. If you're compiling in `PROC` mode, you can refer to any C variable in a SQL statement. + +The next statement tells the server to respond to an SQL error by printing the text of the error message returned by ECPGPlus or the database server: + +```sql +EXEC SQL WHENEVER SQLERROR sqlprint; +``` + +Then, the client application establishes a connection with EDB Postgres Advanced Server: + +```sql +EXEC SQL CONNECT TO edb USER :username IDENTIFIED BY :password; +``` + +The `CONNECT` statement creates a connection to the `edb` database, using the values found in the `:username` and `:password` host variables to authenticate the application to the server when connecting. + +The next statement declares a cursor named `employees`: + +```sql +EXEC SQL DECLARE employees CURSOR FOR + SELECT + empno, ename, sal, comm  + FROM  + emp; +``` + +`employees` contains the result set of a `SELECT` statement on the `emp` table. The query returns employee information from the following columns: `empno`, `ename`, `sal`, and `comm`. Notice that when you declare a cursor, you don't include an `INTO` clause. Instead, you specify the target variables (or descriptors) when you `FETCH` from the cursor. + +Before fetching rows from the cursor, the client application must `OPEN` the cursor: + +```sql +EXEC SQL OPEN employees; +``` + +In the subsequent `FETCH` section, the client application loops through the contents of the cursor. The client application includes a `WHENEVER` statement that instructs the server to `break` (that is, terminate the loop) when it reaches the end of the cursor: + +```sql +EXEC SQL WHENEVER NOT FOUND DO break; +``` + +The client application then uses a `FETCH` statement to retrieve each row from the cursor `INTO` the previously declared host variables: + +```c +for (;;) +{ + EXEC SQL FETCH NEXT FROM employees + INTO + :v_empno, :v_ename, :v_sal, :v_comm INDICATOR :v_comm_ind; +``` + +The `FETCH` statement uses an `INTO` clause to assign the retrieved values into the `:v_empno`, `:v_ename`, `:v_sal`, and `:v_comm` host variables (and the `:v_comm_ind` null indicator). The first value in the cursor is assigned to the first variable listed in the `INTO` clause, the second value is assigned to the second variable, and so on. + +The `FETCH` statement also includes the `INDICATOR` keyword and a host variable to hold a null indicator. If the `comm` column for the retrieved record contains a `NULL` value, `v_comm_ind` is set to a non-zero value, indicating that the column is `NULL`. + +The code then checks the null indicator and displays the appropriate results: + +```c +if (v_comm_ind) + printf("empno(%d), ename(%s), sal(%.2f) comm(NULL)\n", + v_empno, v_ename, v_sal); +else + printf("empno(%d), ename(%s), sal(%.2f) comm(%.2f)\n", + v_empno, v_ename, v_sal, v_comm); +} +``` + +If the null indicator is `0` (that is, `false`), `v_comm` contains a meaningful value, and the `printf` function displays the commission. If the null indicator contains a non-zero value, `comm` is `NULL`, and `printf` displays the string `'NULL'`. A host variable (other than a null indicator) contains no meaningful value if you fetch a `NULL` into that host variable. You must use null indicators for any value which may be `NULL`. + +The final statements in the code sample close the cursor `(employees)` and the connection to the server: + +```sql +EXEC SQL CLOSE employees; +EXEC SQL DISCONNECT; +``` diff --git a/product_docs/docs/epas/15/ecpgplus_guide/04_using_descriptors.mdx b/product_docs/docs/epas/15/ecpgplus_guide/04_using_descriptors.mdx new file mode 100644 index 00000000000..f0eecee0c10 --- /dev/null +++ b/product_docs/docs/epas/15/ecpgplus_guide/04_using_descriptors.mdx @@ -0,0 +1,557 @@ +--- +title: "Using descriptors" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.13.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.14.html" +--- + + + +Dynamic SQL allows a client application to execute SQL statements that are composed at runtime. This ability is useful when you don't know the content or form for a statement when you're writing a client application. ECPGPlus doesn't allow you to use a host variable in place of an identifier (such as a table name, column name, or index name). Instead, use dynamic SQL statements to build a string that includes the information, and then execute that string. The string is passed between the client and the server in the form of a *descriptor*. A descriptor is a data structure that contains both the data and the information about the shape of the data. + +A client application must use a `GET DESCRIPTOR` statement to retrieve information from a descriptor. The basic flow of a client application using dynamic SQL is: + +1. Use an `ALLOCATE DESCRIPTOR` statement to allocate a descriptor for the result set (select list). +2. Use an `ALLOCATE DESCRIPTOR` statement to allocate a descriptor for the input parameters (bind variables). +3. Obtain, assemble, or compute the text of an SQL statement. +4. Use a `PREPARE` statement to parse and check the syntax of the SQL statement. +5. Use a `DESCRIBE` statement to describe the select list into the select-list descriptor. +6. Use a `DESCRIBE` statement to describe the input parameters into the bind-variables descriptor. +7. Prompt the user (if required) for a value for each input parameter. Use a `SET DESCRIPTOR` statement to assign the values into a descriptor. +8. Use a `DECLARE CURSOR` statement to define a cursor for the statement. +9. Use an `OPEN CURSOR` statement to open a cursor for the statement. +10. Use a `FETCH` statement to fetch each row from the cursor, storing each row in select-list descriptor. +11. Use a `GET DESCRIPTOR` command to interrogate the select-list descriptor to find the value of each column in the current row. +12. Use a `CLOSE CURSOR` statement to close the cursor and free any cursor resources. + +A descriptor can contain these attributes. + +| Field | Type | Attribute description | +| ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `CARDINALITY` | `integer` | The number of rows in the result set. | +| `DATA` | N/A | The data value. | +| `DATETIME_INTERVAL_CODE` | `integer` | If `TYPE` is `9`:

`1 - DATE`

`2 - TIME`

`3 - TIMESTAMP`

`4 - TIME WITH TIMEZONE`

`5 - TIMESTAMP WITH TIMEZONE` | +| `DATETIME_INTERVAL_PRECISION` | `integer` | Unused. | +| `INDICATOR` | `integer` | Indicates a `NULL` or truncated value. | +| `KEY_MEMBER` | `integer` | Unused (returns `FALSE`). | +| `LENGTH` | `integer` | The data length (as stored on server). | +| `NAME` | `string` | The name of the column in which the data resides. | +| `NULLABLE` | `integer` | Unused (returns `TRUE`). | +| `OCTET_LENGTH` | `integer` | The data length (in bytes) as stored on server. | +| `PRECISION` | `integer` | The data precision (if the data is of `numeric` type). | +| `RETURNED_LENGTH` | `integer` | Actual length of data item. | +| `RETURNED_OCTET_LENGTH` | `integer` | Actual length of data item. | +| `SCALE` | `integer` | The data scale (if the data is of `numeric` type). | +| `TYPE` | `integer` | A numeric code that represents the data type of the column:

`1 - SQL3_CHARACTER`

`2 - SQL3_NUMERIC`

`3 - SQL3_DECIMAL`

`4 - SQL3_INTEGER`

`5 - SQL3_SMALLINT`

`6 - SQL3_FLOAT`

`7 - SQL3_REAL`

`8 - SQL3_DOUBLE_PRECISION`

`9 - SQL3_DATE_TIME_TIMESTAMP`

`10 - SQL3_INTERVAL`

`12 - SQL3_CHARACTER_VARYING`

`13 - SQL3_ENUMERATED`

`14 - SQL3_BIT`

`15 - SQL3_BIT_VARYING`

`16 - SQL3_BOOLEAN` | + +## Example: Using a descriptor to return data + +The following simple application executes an SQL statement entered by an end user. The code sample shows: + +- How to use a SQL descriptor to execute a `SELECT` statement. +- How to find the data and metadata returned by the statement. + +The application accepts an SQL statement from an end user, tests the statement to see if it includes the `SELECT` keyword, and executes the statement. + +When invoking the application, an end user must provide the name of the database on which to perform the SQL statement and a string that contains the text of the query. + +For example, a user might invoke the sample with the following command: + +```c +./exec_stmt edb "SELECT * FROM emp" + + +/************************************************************ +/* exec_stmt.pgc +* +*/ + +#include +#include +#include +#include + +EXEC SQL WHENEVER SQLERROR SQLPRINT; +static void print_meta_data( char * desc_name ); + +char *md1 = "col field data ret"; +char *md2 = "num name type len"; +char *md3 = "--- -------------------- ----------------- ---"; + +int main( int argc, char *argv[] ) +{ + + EXEC SQL BEGIN DECLARE SECTION; + char *db = argv[1]; + char *stmt = argv[2]; + int col_count; + EXEC SQL END DECLARE SECTION; + + EXEC SQL CONNECT TO :db; + + EXEC SQL ALLOCATE DESCRIPTOR parse_desc; + EXEC SQL PREPARE query FROM :stmt; + EXEC SQL DESCRIBE query INTO SQL DESCRIPTOR parse_desc; + EXEC SQL GET DESCRIPTOR 'parse_desc' :col_count = COUNT; + +if( col_count == 0 ) +{ + EXEC SQL EXECUTE IMMEDIATE :stmt; + + if( sqlca.sqlcode >= 0 ) + EXEC SQL COMMIT; +} +else +{ + int row; + + EXEC SQL ALLOCATE DESCRIPTOR row_desc; + EXEC SQL DECLARE my_cursor CURSOR FOR query; + EXEC SQL OPEN my_cursor; + + for( row = 0; ; row++ ) + { + EXEC SQL BEGIN DECLARE SECTION; + int col; + EXEC SQL END DECLARE SECTION; + EXEC SQL FETCH IN my_cursor + INTO SQL DESCRIPTOR row_desc; + + if( sqlca.sqlcode != 0 ) + break; + + if( row == 0 ) + print_meta_data( "row_desc" ); + + printf("[RECORD %d]\n", row+1); + + for( col = 1; col <= col_count; col++ ) + { + EXEC SQL BEGIN DECLARE SECTION; + short ind; + varchar val[40+1]; + varchar name[20+1]; + EXEC SQL END DECLARE SECTION; + + EXEC SQL GET DESCRIPTOR 'row_desc' + VALUE :col + :val = DATA, :ind = INDICATOR, :name = NAME; + + if( ind == -1 ) + printf( " %-20s : \n", name.arr ); + else if( ind > 0 ) + printf( " %-20s : \n", name.arr ); + else + printf( " %-20s : %s\n", name.arr, val.arr ); + } + + printf( "\n" ); + + } + printf( "%d rows\n", row ); +} + +exit( 0 ); +} + +static void print_meta_data( char *desc_name ) +{ + EXEC SQL BEGIN DECLARE SECTION; + char *desc = desc_name; + int col_count; + int col; + EXEC SQL END DECLARE SECTION; + +static char *types[] = +{ + "unused ", + "CHARACTER ", + "NUMERIC ", + "DECIMAL ", + "INTEGER ", + "SMALLINT ", + "FLOAT ", + "REAL ", + "DOUBLE ", + "DATE_TIME ", + "INTERVAL ", + "unused ", + "CHARACTER_VARYING", + "ENUMERATED ", + "BIT ", + "BIT_VARYING ", + "BOOLEAN ", + "abstract " +}; + +EXEC SQL GET DESCRIPTOR :desc :col_count = count; + + +printf( "%s\n", md1 ); +printf( "%s\n", md2 ); +printf( "%s\n", md3 ); + +for( col = 1; col <= col_count; col++ ) +{ + + EXEC SQL BEGIN DECLARE SECTION; + int type; + int ret_len; + varchar name[21]; + EXEC SQL END DECLARE SECTION; + char *type_name; + + EXEC SQL GET DESCRIPTOR :desc + VALUE :col + :name = NAME, + :type = TYPE, + :ret_len = RETURNED_OCTET_LENGTH; + + if( type > 0 && type < SQL3_abstract ) + type_name = types[type]; + else + type_name = "unknown"; + + printf( "%02d: %-20s %-17s %04d\n", + col, name.arr, type_name, ret_len ); +} +printf( "\n" ); +} + +/************************************************************ +``` + +The code sample begins by including the prototypes and type definitions for the C `stdio` and `stdlib` libraries, SQL data type symbols, and the `SQLCA` (SQL communications area) structure: + +```c +#include +#include +#include +#include +``` + +The sample provides minimal error handling. When the application encounters a SQL error, it prints the error message to screen: + +```sql +EXEC SQL WHENEVER SQLERROR SQLPRINT; +``` + +The application includes a forward-declaration for a function named `print_meta_data()` that prints the metadata found in a descriptor: + +```c +static void print_meta_data( char * desc_name ); +``` + +The following code specifies the column header information that the application uses when printing the metadata: + +```c +char *md1 = "col field data ret"; +char *md2 = "num name type len"; +char *md3 = "--- -------------------- ----------------- ---"; + +int main( int argc, char *argv[] ) +{ +``` + +The following declaration section identifies the host variables to contain the name of the database the application connects to, the content of the SQL statement, and a host variable for the number of columns in the result set (if any). + +```sql +EXEC SQL BEGIN DECLARE SECTION; + char *db = argv[1]; + char *stmt = argv[2]; + int col_count; +EXEC SQL END DECLARE SECTION; +``` + +The application connects to the database using the default credentials: + +```sql +EXEC SQL CONNECT TO :db; +``` + +Next, the application allocates a SQL descriptor to hold the metadata for a statement: + +```sql +EXEC SQL ALLOCATE DESCRIPTOR parse_desc; +``` + +The application uses a `PREPARE` statement to check the syntax of the string provided by the user: + +```sql +EXEC SQL PREPARE query FROM :stmt; +``` + +It also uses a `DESCRIBE` statement to move the metadata for the query into the SQL descriptor. + +```sql +EXEC SQL DESCRIBE query INTO SQL DESCRIPTOR parse_desc; +``` + +Then, the application interrogates the descriptor to discover the number of columns in the result set and stores that in the host variable `col_count`. + +```sql +EXEC SQL GET DESCRIPTOR parse_desc :col_count = COUNT; +``` + +If the column count is zero, the end user didn't enter a `SELECT` statement. The application uses an `EXECUTE IMMEDIATE` statement to process the contents of the statement: + +```c +if( col_count == 0 ) +{ + EXEC SQL EXECUTE IMMEDIATE :stmt; +``` + +If the statement executes successfully, the application performs a `COMMIT`: + +```c +if( sqlca.sqlcode >= 0 ) + EXEC SQL COMMIT; +} +else +{ +``` + +If the statement entered by the user is a `SELECT` statement (which we know because the column count is non-zero), the application declares a variable named `row`: + +```c +int row; +``` + +Then, the application allocates another descriptor that holds the description and the values of a specific row in the result set: + +```sql +EXEC SQL ALLOCATE DESCRIPTOR row_desc; +``` + +The application declares and opens a cursor for the prepared statement: + +```sql +EXEC SQL DECLARE my_cursor CURSOR FOR query; +EXEC SQL OPEN my_cursor; +``` + +It loops through the rows in the result set: + +```c +for( row = 0; ; row++ ) +{ + EXEC SQL BEGIN DECLARE SECTION; + int col; + EXEC SQL END DECLARE SECTION; +``` + +Then, it uses a `FETCH` to retrieve the next row from the cursor into the descriptor: + +```sql +EXEC SQL FETCH IN my_cursor INTO SQL DESCRIPTOR row_desc; +``` + +The application confirms that the `FETCH` didn't fail. If the `FETCH` fails, the application reached the end of the result set and breaks the loop: + +```c +if( sqlca.sqlcode != 0 ) + break; +``` + +The application checks to see if this is the first row of the cursor. If it is, the application prints the metadata for the row: + +```c +if( row == 0 ) + print_meta_data( "row_desc" ); +``` + +Next, it prints a record header containing the row number: + +```c +printf("[RECORD %d]\n", row+1); +``` + +Then, it loops through each column in the row: + +```c +for( col = 1; col <= col_count; col++ ) +{ + EXEC SQL BEGIN DECLARE SECTION; + short ind; + varchar val[40+1]; + varchar name[20+1]; + EXEC SQL END DECLARE SECTION; +``` + +The application interrogates the row descriptor `(row_desc)` to copy the column value `:val`, null indicator `:ind`, and column name `:name` into the host variables declared earlier. You can retrieve multiple items from a descriptor using a comma-separated list: + +```sql +EXEC SQL GET DESCRIPTOR row_desc + VALUE :col + :val = DATA, :ind = INDICATOR, :name = NAME; +``` + +If the null indicator (`ind`) is negative, the column value is `NULL`. If the null indicator is greater than `0`, the column value is too long to fit into the val host variable, so we print ``. Otherwise, the null indicator is `0`, meaning `NOT NULL`, so we print the value. In each case, we prefix the value (or `` or ``) with the name of the column. + +```c +if( ind == -1 ) + printf( " %-20s : \n", name.arr ); +else if( ind > 0 ) + printf( " %-20s : \n", name.arr ); +else + printf( " %-20s : %s\n", name.arr, val.arr ); +} + +printf( "\n" ); +} +``` + +When the loop terminates, the application prints the number of rows fetched and exits: + +```c + printf( "%d rows\n", row ); + } + +exit( 0 ); +} +``` + +The `print_meta_data()` function extracts the metadata from a descriptor and prints the name, data type, and length of each column: + +```c +static void print_meta_data( char *desc_name ) +{ +``` + +The application declares host variables: + +```sql +EXEC SQL BEGIN DECLARE SECTION; + char *desc = desc_name; + int col_count; + int col; +EXEC SQL END DECLARE SECTION; +``` + +The application then defines an array of character strings that map data type values (`numeric`) into data type names. We use the numeric value found in the descriptor to index into this array. For example, if we find that a given column is of type `2`, we can find the name of that type (`NUMERIC`) by writing `types[2]`. + +```c +static char *types[] = +{ + "unused ", + "CHARACTER ", + "NUMERIC ", + "DECIMAL ", + "INTEGER ", + "SMALLINT ", + "FLOAT ", + "REAL ", + "DOUBLE ", + "DATE_TIME ", + "INTERVAL ", + "unused ", + "CHARACTER_VARYING", + "ENUMERATED ", + "BIT ", + "BIT_VARYING ", + "BOOLEAN ", + "abstract " +}; +``` + +The application retrieves the column count from the descriptor. The program refers to the descriptor using a host variable (`desc`) that contains the name of the descriptor. In most scenarios, you use an identifier to refer to a descriptor. In this case, the caller provided the descriptor name, so we can use a host variable to refer to the descriptor. + +```sql +EXEC SQL GET DESCRIPTOR :desc :col_count = count; +``` + +The application prints the column headers defined at the beginning of this application: + +```c +printf( "%s\n", md1 ); +printf( "%s\n", md2 ); +printf( "%s\n", md3 ); +``` + +Then, it loops through each column found in the descriptor and prints the name, type, and length of each column. + +```c +for( col = 1; col <= col_count; col++ ) +{ + EXEC SQL BEGIN DECLARE SECTION; + int type; + int ret_len; + varchar name[21]; + EXEC SQL END DECLARE SECTION; + char *type_name; +``` + +It retrieves the name, type code, and length of the current column: + +```sql +EXEC SQL GET DESCRIPTOR :desc + VALUE :col + :name = NAME, + :type = TYPE, + :ret_len = RETURNED_OCTET_LENGTH; +``` + +If the numeric type code matches a 'known' type code (that is, a type code found in the `types[]` array), it sets `type_name` to the name of the corresponding type. Otherwise, it sets `type_name` to `"unknown"`: + +```c +if( type > 0 && type < SQL3_abstract ) + type_name = types[type]; +else + type_name = "unknown"; +``` + +It then prints the column number, name, type name, and length: + +```c + printf( "%02d: %-20s %-17s %04d\n", + col, name.arr, type_name, ret_len ); + } + printf( "\n" ); +} +``` + +Invoke the sample application with the following command: + +```c +./exec_stmt test "SELECT * FROM emp WHERE empno IN(7902, 7934)" +``` + +The application returns: + +```sql +__OUTPUT__ +col field                data              ret +num name                 type              len +--- -------------------- ----------------- --- +01: empno                NUMERIC           0004 +02: ename                CHARACTER_VARYING 0004 +03: job                  CHARACTER_VARYING 0007 +04: mgr                  NUMERIC           0004 +05: hiredate             DATE_TIME         0018 +06: sal                  NUMERIC           0007 +07: comm                 NUMERIC           0000 +08: deptno               NUMERIC           0002 + +[RECORD 1] +  empno                : 7902 +  ename                : FORD +  job                  : ANALYST +  mgr                  : 7566 +  hiredate             : 03-DEC-81 00:00:00 +  sal                  : 3000.00 +  comm                 : +  deptno               : 20 + +[RECORD 2] +  empno                : 7934 +  ename                : MILLER +  job                  : CLERK +  mgr                  : 7782 +  hiredate             : 23-JAN-82 00:00:00 +  sal                  : 1300.00 +  comm                 : +  deptno               : 10 + +2 rows +``` diff --git a/product_docs/docs/epas/15/ecpgplus_guide/05_building_executing_dynamic_sql_statements.mdx b/product_docs/docs/epas/15/ecpgplus_guide/05_building_executing_dynamic_sql_statements.mdx new file mode 100644 index 00000000000..b08e69552e5 --- /dev/null +++ b/product_docs/docs/epas/15/ecpgplus_guide/05_building_executing_dynamic_sql_statements.mdx @@ -0,0 +1,804 @@ +--- +title: "Building and executing dynamic SQL statements" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.18.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.15.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.17.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.16.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.19.html" +--- + + + +The following examples show four techniques for building and executing dynamic SQL statements. Each example shows processing a different combination of statement and input types: + +- The first example shows processing and executing a SQL statement that doesn't contain a `SELECT` statement and doesn't require input variables. This example corresponds to the techniques used by Oracle Dynamic SQL Method 1. +- The second example shows processing and executing a SQL statement that doesn't contain a `SELECT` statement and contains a known number of input variables. This example corresponds to the techniques used by Oracle Dynamic SQL Method 2. +- The third example shows processing and executing a SQL statement that might contain a `SELECT` statement and includes a known number of input variables. This example corresponds to the techniques used by Oracle Dynamic SQL Method 3. +- The fourth example shows processing and executing a SQL statement that might contain a `SELECT` statement and includes an unknown number of input variables. This example corresponds to the techniques used by Oracle Dynamic SQL Method 4. + +## Example: Executing a nonquery statement without parameters + +This example shows how to use the `EXECUTE IMMEDIATE` command to execute a SQL statement, where the text of the statement isn't known until you run the application. You can't use `EXECUTE IMMEDIATE` to execute a statement that returns a result set. You can't use `EXECUTE IMMEDIATE` to execute a statement that contains parameter placeholders. + +The `EXECUTE IMMEDIATE` statement parses and plans the SQL statement each time it executes, which can have a negative impact on the performance of your application. If you plan to execute the same statement repeatedly, consider using the `PREPARE/EXECUTE` technique described in [Example: Executing a nonquery statement with a specified number of placeholders](#example-executing-a-nonquery-statement-with-a-specified-number-of-placeholders). + +```c +/***********************************************************/ +#include +#include +#include + +static void handle_error(void); + +int main(int argc, char *argv[]) +{ + char *insertStmt; + + EXEC SQL WHENEVER SQLERROR DO handle_error(); + + EXEC SQL CONNECT :argv[1]; + + insertStmt = "INSERT INTO dept VALUES(50, 'ACCTG', 'SEATTLE')"; + + EXEC SQL EXECUTE IMMEDIATE :insertStmt; + + fprintf(stderr, "ok\n"); + + EXEC SQL COMMIT RELEASE; + + exit(EXIT_SUCCESS); +} + + +static void handle_error(void) +{ + fprintf(stderr, "%s\n", sqlca.sqlerrm.sqlerrmc); + + EXEC SQL WHENEVER SQLERROR CONTINUE; + EXEC SQL ROLLBACK RELEASE; + + exit(EXIT_FAILURE); +} + +/***********************************************************/ +``` + +The code sample begins by including the prototypes and type definitions for the C `stdio`, `string`, and `stdlib` libraries and providing basic infrastructure for the program: + +```c +#include +#include +#include + +static void handle_error(void); +int main(int argc, char *argv[]) +{ + char *insertStmt; +``` + +The example then sets up an error handler. ECPGPlus calls the `handle_error()` function whenever a SQL error occurs: + +```sql +EXEC SQL WHENEVER SQLERROR DO handle_error(); +``` + +Then, the example connects to the database using the credentials specified on the command line: + +```sql +EXEC SQL CONNECT :argv[1]; +``` + +Next, the program uses an `EXECUTE IMMEDIATE` statement to execute a SQL statement, adding a row to the `dept` table: + +```c +insertStmt = "INSERT INTO dept VALUES(50, 'ACCTG', 'SEATTLE')"; + +EXEC SQL EXECUTE IMMEDIATE :insertStmt; +``` + +If the `EXECUTE IMMEDIATE` command fails, ECPGPlus invokes the `handle_error()` function, which terminates the application after displaying an error message to the user. If the `EXECUTE IMMEDIATE` command succeeds, the application displays a message (`ok`) to the user, commits the changes, disconnects from the server, and terminates the application: + +```c + fprintf(stderr, "ok\n"); + + EXEC SQL COMMIT RELEASE; + + exit(EXIT_SUCCESS); +} +``` + +ECPGPlus calls the `handle_error()` function whenever it encounters a SQL error. The `handle_error()` function prints the content of the error message, resets the error handler, rolls back any changes, disconnects from the database, and terminates the application: + +```c +static void handle_error(void) +{ + fprintf(stderr, "%s\n", sqlca.sqlerrm.sqlerrmc); + + EXEC SQL WHENEVER SQLERROR CONTINUE; + EXEC SQL ROLLBACK RELEASE; + + exit(EXIT_FAILURE); +} +``` + +## Example: Executing a nonquery statement with a specified number of placeholders + +To execute a nonquery command that includes a known number of parameter placeholders, you must first `PREPARE` the statement (providing a *statement handle*) and then `EXECUTE` the statement using the statement handle. When the application executes the statement, it must provide a value for each placeholder found in the statement. + +When an application uses the `PREPARE/EXECUTE` mechanism, each SQL statement is parsed and planned once but might execute many times, providing different values each time. + +ECPGPlus converts each parameter value to the type required by the SQL statement, if possible. Otherwise, ECPGPlus reports an error. + +```c +/***********************************************************/ +#include +#include +#include +#include + +static void handle_error(void); + +int main(int argc, char *argv[]) +{ + char *stmtText; + + EXEC SQL WHENEVER SQLERROR DO handle_error(); + + EXEC SQL CONNECT :argv[1]; + + stmtText = "INSERT INTO dept VALUES(?, ?, ?)"; + + EXEC SQL PREPARE stmtHandle FROM :stmtText; + + EXEC SQL EXECUTE stmtHandle USING :argv[2], :argv[3], :argv[4]; + + fprintf(stderr, "ok\n"); + + EXEC SQL COMMIT RELEASE; + + exit(EXIT_SUCCESS); +} + +static void handle_error(void) +{ + printf("%s\n", sqlca.sqlerrm.sqlerrmc); + EXEC SQL WHENEVER SQLERROR CONTINUE; + EXEC SQL ROLLBACK RELEASE; + + exit(EXIT_FAILURE); +} +/***********************************************************/ +``` + +The code sample begins by including the prototypes and type definitions for the C `stdio`, `string`, `stdlib`, and `sqlca` libraries and providing basic infrastructure for the program: + +```c +#include +#include +#include +#include + +static void handle_error(void); + +int main(int argc, char *argv[]) +{ + char *stmtText; +``` + +The example then sets up an error handler. ECPGPlus calls the `handle_error()` function whenever a SQL error occurs. + +```sql +EXEC SQL WHENEVER SQLERROR DO handle_error(); +``` + +Then, the example connects to the database using the credentials specified on the command line: + +```sql +EXEC SQL CONNECT :argv[1]; +``` + +Next, the program uses a `PREPARE` statement to parse and plan a statement that includes three parameter markers. If the `PREPARE` statement succeeds, it creates a statement handle that you can use to execute the statement. (In this example, the statement handle is named `stmtHandle`.) You can execute a given statement multiple times using the same statement handle. + +```sql +stmtText = "INSERT INTO dept VALUES(?, ?, ?)"; + +EXEC SQL PREPARE stmtHandle FROM :stmtText; +``` + +After parsing and planning the statement, the application uses the `EXECUTE` statement to execute the statement associated with the statement handle, substituting user-provided values for the parameter markers: + +```sql +EXEC SQL EXECUTE stmtHandle USING :argv[2], :argv[3], :argv[4]; +``` + +If the `EXECUTE` command fails, ECPGPlus invokes the `handle_error()` function, which terminates the application after displaying an error message to the user. If the `EXECUTE` command succeeds, the application displays a message (`ok`) to the user, commits the changes, disconnects from the server, and terminates the application: + +```c + fprintf(stderr, "ok\n"); + + EXEC SQL COMMIT RELEASE; + + exit(EXIT_SUCCESS); +} +``` + +ECPGPlus calls the `handle_error()` function whenever it encounters a SQL error. The `handle_error()` function prints the content of the error message, resets the error handler, rolls back any changes, disconnects from the database, and terminates the application: + +```c +static void handle_error(void) +{ + printf("%s\n", sqlca.sqlerrm.sqlerrmc); + + EXEC SQL WHENEVER SQLERROR CONTINUE; + EXEC SQL ROLLBACK RELEASE; + exit(EXIT_FAILURE); +} +``` + +## Example: Executing a query with a known number of placeholders + +This example shows how to execute a query with a known number of input parameters and with a known number of columns in the result set. This method uses the `PREPARE` statement to parse and plan a query and then opens a cursor and iterates through the result set. + +```c +/***********************************************************/ +#include +#include +#include +#include +#include + +static void handle_error(void); + +int main(int argc, char *argv[]) +{ + VARCHAR empno[10]; + VARCHAR ename[20]; + + EXEC SQL WHENEVER SQLERROR DO handle_error(); + + EXEC SQL CONNECT :argv[1]; + + EXEC SQL PREPARE queryHandle + FROM "SELECT empno, ename FROM emp WHERE deptno = ?"; + + EXEC SQL DECLARE empCursor CURSOR FOR queryHandle; + + EXEC SQL OPEN empCursor USING :argv[2]; + + EXEC SQL WHENEVER NOT FOUND DO break; + + while(true) + { + + EXEC SQL FETCH empCursor INTO :empno, :ename; + + printf("%-10s %s\n", empno.arr, ename.arr); + } + + EXEC SQL CLOSE empCursor; + + EXEC SQL COMMIT RELEASE; + + exit(EXIT_SUCCESS); +} + +static void handle_error(void) +{ + printf("%s\n", sqlca.sqlerrm.sqlerrmc); + + EXEC SQL WHENEVER SQLERROR CONTINUE; + EXEC SQL ROLLBACK RELEASE; + + exit(EXIT_FAILURE); +} + +/***********************************************************/ +``` + +The code sample begins by including the prototypes and type definitions for the C `stdio`, `string`, `stdlib`, `stdbool`, and `sqlca` libraries and providing basic infrastructure for the program: + +```c +#include +#include +#include +#include +#include + +static void handle_error(void); + +int main(int argc, char *argv[]) +{ + VARCHAR empno[10]; + VARCHAR ename[20]; +``` + +The example then sets up an error handler. ECPGPlus calls the `handle_error()` function whenever a SQL error occurs: + +```sql +EXEC SQL WHENEVER SQLERROR DO handle_error(); +``` + +Then, the example connects to the database using the credentials specified on the command line: + +```sql +EXEC SQL CONNECT :argv[1]; +``` + +Next, the program uses a `PREPARE` statement to parse and plan a query that includes a single parameter marker. If the `PREPARE` statement succeeds, it creates a statement handle that you can use to execute the statement. (In this example, the statement handle is named `stmtHandle`.) You can execute a given statement multiple times using the same statement handle. + +```sql +EXEC SQL PREPARE stmtHandle + FROM "SELECT empno, ename FROM emp WHERE deptno = ?"; +``` + +The program then declares and opens the cursor `empCursor`, substituting a user-provided value for the parameter marker in the prepared `SELECT` statement. The `OPEN` statement includes a `USING` clause, which must provide a value for each placeholder found in the query: + +```sql +EXEC SQL DECLARE empCursor CURSOR FOR stmtHandle; + +EXEC SQL OPEN empCursor USING :argv[2]; + +EXEC SQL WHENEVER NOT FOUND DO break; + +while(true) +{ +``` + +The program iterates through the cursor and prints the employee number and name of each employee in the selected department: + +```sql + EXEC SQL FETCH empCursor INTO :empno, :ename; + + printf("%-10s %s\n", empno.arr, ename.arr); +} +``` + +The program then closes the cursor, commits any changes, disconnects from the server, and terminates the application: + +```sql + EXEC SQL CLOSE empCursor; + + EXEC SQL COMMIT RELEASE; + + exit(EXIT_SUCCESS); +} +``` + +The application calls the `handle_error()` function whenever it encounters a SQL error. The `handle_error()` function prints the content of the error message, resets the error handler, rolls back any changes, disconnects from the database, and terminates the application: + +```c +static void handle_error(void) +{ + printf("%s\n", sqlca.sqlerrm.sqlerrmc); + + EXEC SQL WHENEVER SQLERROR CONTINUE; + EXEC SQL ROLLBACK RELEASE; + + exit(EXIT_FAILURE); +} +``` + + + +## Example: Executing a query with an unknown number of variables + +This example shows executing a query with an unknown number of input parameters or columns in the result set. This type of query might occur when you prompt the user for the text of the query or when a query is assembled from a form on which the user chooses from a number of conditions (i.e., a filter). + +```c +/***********************************************************/ +#include +#include +#include +#include + +SQLDA *params; +SQLDA *results; + +static void allocateDescriptors(int count, + int varNameLength, + int indNameLenth); +static void bindParams(void); +static void displayResultSet(void); + +int main(int argc, char *argv[]) +{ + EXEC SQL BEGIN DECLARE SECTION; + char *username = argv[1]; + char *password = argv[2]; + char *stmtText = argv[3]; + EXEC SQL END DECLARE SECTION; + + EXEC SQL WHENEVER SQLERROR sqlprint; + + EXEC SQL CONNECT TO test + USER :username + IDENTIFIED BY :password; + + params = sqlald(20, 64, 64); + results = sqlald(20, 64, 64); + + EXEC SQL PREPARE stmt FROM :stmtText; + + EXEC SQL DECLARE dynCursor CURSOR FOR stmt; + + bindParams(); + + EXEC SQL OPEN dynCursor USING DESCRIPTOR params; + + displayResultSet(20); +} + +static void bindParams(void) +{ + EXEC SQL DESCRIBE BIND VARIABLES FOR stmt INTO params; + + if (params->F < 0) + fprintf(stderr, "Too many parameters required\n"); + else + { + int i; + + params->N = params->F; + + for (i = 0; i < params->F; i++) + { + char *paramName = params->S[i]; + int nameLen = params->C[i]; + char paramValue[255]; + + printf("Enter value for parameter %.*s: ", + nameLen, paramName); + + fgets(paramValue, sizeof(paramValue), stdin); + + params->T[i] = 1; /* Data type = Character (1) */ + params->L[i] = strlen(paramValue) - 1; + params->V[i] = strdup(paramValue); + } + } +} + +static void displayResultSet(void) +{ + EXEC SQL DESCRIBE SELECT LIST FOR stmt INTO results; + + if (results->F < 0) + fprintf(stderr, "Too many columns returned by query\n"); + else if (results->F == 0) + return; + else + { + int col; + + results->N = results->F; + + for (col = 0; col < results->F; col++) + { + int null_permitted, length; + + sqlnul(&results->T[col], + &results->T[col], + &null_permitted); + + switch (results->T[col]) + { + case 2: /* NUMERIC */ + { + int precision, scale; + + sqlprc(&results->L[col], &precision, &scale); + + if (precision == 0) + precision = 38; + + length = precision + 3; + break; + } + + case 12: /* DATE */ + { + length = 30; + break; + } + + default: /* Others */ + { + length = results->L[col] + 1; + break; + } + } + + results->V[col] = realloc(results->V[col], length); + results->L[col] = length; + results->T[col] = 1; + } + + EXEC SQL WHENEVER NOT FOUND DO break; + + while (1) + { + const char *delimiter = ""; + + EXEC SQL FETCH dynCursor USING DESCRIPTOR results; + + for (col = 0; col < results->F; col++) + { + if (*results->I[col] == -1) + printf("%s%s", delimiter, ""); + else + printf("%s%s", delimiter, results->V[col]); + delimiter = ", "; + } + + + printf("\n"); + } + } +} +/***********************************************************/ +``` + +The code sample begins by including the prototypes and type definitions for the C `stdio` and `stdlib` libraries. In addition, the program includes the `sqlda.h` and `sqlcpr.h` header files. `sqlda.h` defines the SQLDA structure used throughout this example. `sqlcpr.h` defines a small set of functions used to interrogate the metadata found in an SQLDA structure. + +```c +#include +#include +#include +#include +``` + +Next, the program declares pointers to two SQLDA structures. The first SQLDA structure (`params`) is used to describe the metadata for any parameter markers found in the dynamic query text. The second SQLDA structure (`results`) contains both the metadata and the result set obtained by executing the dynamic query. + +```sql +SQLDA *params; +SQLDA *results; +``` + +The program then declares two helper functions, which are defined near the end of the code sample: + +```c +static void bindParams(void); +static void displayResultSet(void); +``` + +Next, the program declares three host variables. The first two (`username` and `password`) are used to connect to the database server. The third host variable (`stmtTxt`) is a NULL-terminated C string containing the text of the query to execute. The values for these three host variables are derived from the command-line arguments. When the program begins to execute, it sets up an error handler and then connects to the database server: + +```c +int main(int argc, char *argv[]) +{ + EXEC SQL BEGIN DECLARE SECTION; + char *username = argv[1]; + char *password = argv[2]; + char *stmtText = argv[3]; + EXEC SQL END DECLARE SECTION; + + EXEC SQL WHENEVER SQLERROR sqlprint; + EXEC SQL CONNECT TO test + USER :username + IDENTIFIED BY :password; +``` + +Next, the program calls the `sqlald()` function to allocate the memory required for each descriptor. Each descriptor contains pointers to arrays of: + +- Column names +- Indicator names +- Data types +- Lengths +- Data values + +When you allocate an `SQLDA` descriptor, you specify the maximum number of columns you expect to find in the result set (for `SELECT`-list descriptors) or the maximum number of parameters you expect to find the dynamic query text (for bind-variable descriptors). In this case, we specify that we expect no more than 20 columns and 20 parameters. You must also specify a maximum length for each column or parameter name and each indicator variable name. In this case, we expect names to be no more than 64 bytes long. + +See [SQLDA structure](07_reference/#sqlda_structure) for a complete description of the `SQLDA` structure. + +```c +params = sqlald(20, 64, 64); +results = sqlald(20, 64, 64); +``` + +After allocating the `SELECT`-list and bind descriptors, the program prepares the dynamic statement and declares a cursor over the result set. + +```sql +EXEC SQL PREPARE stmt FROM :stmtText; + +EXEC SQL DECLARE dynCursor CURSOR FOR stmt; +``` + +Next, the program calls the `bindParams()` function. The `bindParams()` function examines the bind descriptor `(params)` and prompts the user for a value to substitute in place of each parameter marker found in the dynamic query. + +```c +bindParams(); +``` + +Finally, the program opens the cursor (using any parameter values supplied by the user) and calls the `displayResultSet()` function to print the result set produced by the query: + +```sql +EXEC SQL OPEN dynCursor USING DESCRIPTOR params; + +displayResultSet(); +} +``` + +The `bindParams()` function determines whether the dynamic query contains any parameter markers. If so, it prompts the user for a value for each parameter and then binds that value to the corresponding marker. The `DESCRIBE BIND VARIABLE` statement populates the `params` SQLDA structure with information describing each parameter marker: + +```c +static void bindParams(void) +{ + EXEC SQL DESCRIBE BIND VARIABLES FOR stmt INTO params; +``` + +If the statement contains no parameter markers, `params->F` contains 0. If the statement contains more parameters than fit into the descriptor, `params->F` contains a negative number. In this case, the absolute value of `params->F` indicates the number of parameter markers found in the statement. If `params->F` contains a positive number, that number indicates how many parameter markers were found in the statement. + +```c +if (params->F < 0) + fprintf(stderr, "Too many parameters required\n"); +else +{ + int i; + + params->N = params->F; +``` + +Next, the program executes a loop that prompts the user for a value, iterating once for each parameter marker found in the statement: + +```c +for (i = 0; i < params->F; i++) +{ + char *paramName = params->S[i]; + int nameLen = params->C[i]; + char paramValue[255]; + + printf("Enter value for parameter %.*s: ", + nameLen, paramName); + + fgets(paramValue, sizeof(paramValue), stdin); +``` + +After prompting the user for a value for a given parameter, the program binds that value to the parameter by setting: + +- `params->T[i]` to indicate the data type of the value +- `params->L[i]` to the length of the value (we subtract one to trim off the trailing new-line character added by `fgets()`) +- `params->V[i]` to point to a copy of the NULL-terminated string provided by the user + +```c + params->T[i] = 1; /* Data type = Character (1) */ + params->L[i] = strlen(paramValue) + 1; + params->V[i] = strdup(paramValue); + } + } +} +``` + +The `displayResultSet()` function loops through each row in the result set and prints the value found in each column. `displayResultSet()` starts by executing a `DESCRIBE SELECT LIST` statement. This statement populates an SQLDA descriptor (`results`) with a description of each column in the result set. + +```c +static void displayResultSet(void) +{ + EXEC SQL DESCRIBE SELECT LIST FOR stmt INTO results; +``` + +If the dynamic statement returns no columns (that is, the dynamic statement is not a `SELECT` statement), `results->F` contains 0. If the statement returns more columns than fit into the descriptor, `results->F` contains a negative number. In this case, the absolute value of `results->F` indicates the number of columns returned by the statement. If `results->F` contains a positive number, that number indicates how many columns were returned by the query. + +```c +if (results->F < 0) + fprintf(stderr, "Too many columns returned by query\n"); +else if (results->F == 0) + return; +else +{ + int col; + + results->N = results->F; +``` + +Next, the program enters a loop, iterating once for each column in the result set: + +```c +for (col = 0; col < results->F; col++) +{ + int null_permitted, length; +``` + +To decode the type code found in `results->T`, the program invokes the `sqlnul()` function (see the description of the `T` member of the SQLDA structure in the [The SQLDA structure](07_reference/#sqlda_structure)). This call to `sqlnul()` modifies `results->T[col]` to contain only the type code (the nullability flag is copied to `null_permitted`). This step is needed because the `DESCRIBE SELECT LIST` statement encodes the type of each column and the nullability of each column into the `T` array. + +```c +sqlnul(&results->T[col], + &results->T[col], + &null_permitted); +``` + +After decoding the actual data type of the column, the program modifies the results descriptor to tell ECPGPlus to return each value in the form of a NULL-terminated string. Before modifying the descriptor, the program must compute the amount of space required to hold each value. To make this computation, the program examines the maximum length of each column `(results->V[col])` and the data type of each column `(results->T[col])`. + +For numeric values (where `results->T[col] = 2`), the program calls the `sqlprc()` function to extract the precision and scale from the column length. To compute the number of bytes required to hold a numeric value in string form, `displayResultSet()` starts with the precision (that is, the maximum number of digits) and adds three bytes for a sign character, a decimal point, and a NULL terminator. + +```c +switch (results->T[col]) +{ + case 2: /* NUMERIC */ + { + int precision, scale; + + sqlprc(&results->L[col], &precision, &scale); + + if (precision == 0) + precision = 38; + length = precision + 3; + break; + } +``` + +For date values, the program uses a hard-coded length of 30. In a real-world application, you might want to more carefully compute the amount of space required. + +```c +case 12: /* DATE */ +{ + length = 30; + break; +} +``` + +For a value of any type other than date or numeric, `displayResultSet()` starts with the maximum column width reported by `DESCRIBE SELECT LIST` and adds one extra byte for the NULL terminator. Again, in a real-world application you might want to include more careful calculations for other data types: + +```c +default: /* Others */ +{ + length = results->L[col] + 1; + break; +} +} +``` + +After computing the amount of space required to hold a given column, the program: + +- Allocates enough memory to hold the value +- Sets `results->L[col]` to indicate the number of bytes found at `results->V[col]` +- Sets the type code for the column `(results->T[col])` to `1` to instruct the upcoming `FETCH` statement to return the value in the form of a NULL-terminated string + +```c + results->V[col] = malloc(length); + results->L[col] = length; + results->T[col] = 1; +} +``` + +At this point, the results descriptor is configured such that a `FETCH` statement can copy each value into an appropriately sized buffer in the form of a NULL-terminated string. + +Next, the program defines a new error handler to break out of the upcoming loop when the cursor is exhausted. + +```sql +EXEC SQL WHENEVER NOT FOUND DO break; + +while (1) +{ + const char *delimiter = ""; +``` + +The program executes a `FETCH` statement to fetch the next row in the cursor into the `results` descriptor. If the `FETCH` statement fails (because the cursor is exhausted), control transfers to the end of the loop because of the `EXEC SQL WHENEVER` directive found before the top of the loop. + + `EXEC SQL FETCH dynCursor USING DESCRIPTOR results;` + +The `FETCH` statement populates the following members of the results descriptor: + +- `*results->I[col]` indicates whether the column contains a NULL value `(-1)` or a non-NULL value `(0)`. If the value is non-NULL but too large to fit into the space provided, the value is truncated, and `*results->I[col]` contains a positive value. +- `results->V[col]` contains the value fetched for the given column (unless `*results->I[col]` indicates that the column value is NULL). +- `results->L[col]` contains the length of the value fetched for the given column. + +Finally, `displayResultSet()` iterates through each column in the result set, examines the corresponding NULL indicator, and prints the value. The result set isn't aligned. Instead, each value is separated from the previous value by a comma. + +```c +for (col = 0; col < results->F; col++) +{ + if (*results->I[col] == -1) + printf("%s%s", delimiter, ""); + else + printf("%s%s", delimiter, results->V[col]); + delimiter = ", "; +} + +printf("\n"); +} +} +} +/***********************************************************/ +``` diff --git a/product_docs/docs/epas/15/ecpgplus_guide/06_error_handling.mdx b/product_docs/docs/epas/15/ecpgplus_guide/06_error_handling.mdx new file mode 100644 index 00000000000..9ea2731bc6e --- /dev/null +++ b/product_docs/docs/epas/15/ecpgplus_guide/06_error_handling.mdx @@ -0,0 +1,193 @@ +--- +title: "Error handling" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.20.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.21.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.22.html" +--- + + + +ECPGPlus provides two methods to detect and handle errors in embedded SQL code. A client application can: + +- Examine the `sqlca` data structure for error messages and supply customized error handling for your client application. +- Include `EXEC SQL WHENEVER` directives to instruct the ECPGPlus compiler to add error-handling code. + +## Error handling with sqlca + +`sqlca` (SQL communications area) is a global variable used by `ecpglib` to communicate information from the server to the client application. After executing a SQL statement such as an `INSERT` or `SELECT` statement, you can inspect the contents of `sqlca` to determine if the statement completed successfully or if the statement failed. + +`sqlca` has the following structure: + +```c +struct +{ + char sqlcaid[8]; + long sqlabc; + long sqlcode; + struct + { + int sqlerrml; + char sqlerrmc[SQLERRMC_LEN]; + } sqlerrm; + char sqlerrp[8]; + long sqlerrd[6]; + char sqlwarn[8]; + char sqlstate[5]; + +} sqlca; +``` + +Use the following directive to implement `sqlca` functionality: + +```sql +EXEC SQL INCLUDE sqlca; +``` + +If you include the `ecpg` directive, you don't need to `#include` the `sqlca.h` file in the client application's header declaration. + +The EDB Postgres Advanced Server `sqlca` structure contains the following members: + +- `sqlcaid` — Contains the string: `"SQLCA"`. + +- `sqlabc` — `sqlabc` contains the size of the `sqlca` structure. + +- `sqlcode` — The `sqlcode` member was deprecated with SQL 92. EDB Postgres Advanced Server supports `sqlcode` for backward compatibility. Use the `sqlstate` member when writing new code. + + `sqlcode` is an integer value. A positive `sqlcode` value indicates that the client application encountered a harmless processing condition. A negative value indicates a warning or error. + + If a statement processes without error, `sqlcode` contains a value of `0`. If the client application encounters an error or warning during a statement's execution, `sqlcode` contains the last code returned. + + The SQL standard defines only a positive value of 100, which indicates that the most recent SQL statement processed returned or affected no rows. Since the SQL standard doesn't define other `sqlcode` values, be aware that the values assigned to each condition can vary from database to database. + +`sqlerrm` is a structure embedded in `sqlca`, composed of two members: + +- `sqlerrml` — Contains the length of the error message currently stored in `sqlerrmc`. + +- `sqlerrmc` — Contains the null-terminated message text associated with the code stored in `sqlstate`. If a message exceeds 149 characters, `ecpglib` truncates the error message. + +- `sqlerrp` — Contains the string `"NOT SET"`. + +`sqlerrd` is an array that contains six elements: + +- `sqlerrd[1]` — Contains the OID of the processed row (if applicable). + +- `sqlerrd[2]` — Contains the number of processed or returned rows. + +- `sqlerrd[0]`, `sqlerrd[3]`, `sqlerrd[4]` and `sqlerrd[5]` are unused. + +`sqlwarn` is an array that contains 8 characters: + +- `sqlwarn[0]` — Contains a value of `'W'` if any other element in `sqlwarn` is set to `'W'`. + +- `sqlwarn[1]` — Contains a value of `'W'` if a data value was truncated when it was stored in a host variable. + +- `sqlwarn[2]` — Contains a value of `'W'` if the client application encounters a nonfatal warning. + +- `sqlwarn[3]`, `sqlwarn[4]`, `sqlwarn[5]`, `sqlwarn[6]`, and `sqlwarn[7]` are unused. + +`sqlstate` is a five-character array that contains a SQL-compliant status code after the execution of a statement from the client application. If a statement processes without error, `sqlstate` contains a value of `00000`. `sqlstate` isn't a null-terminated string. + +`sqlstate` codes are assigned in a hierarchical scheme: + +- The first two characters of `sqlstate` indicate the general class of the condition. +- The last three characters of `sqlstate` indicate a specific status within the class. + +If the client application encounters multiple errors (or warnings) during an SQL statement's execution, `sqlstate` contains the last code returned. + +The following table lists the `sqlstate` and `sqlcode` values, as well as the symbolic name and error description for the related condition. + +| sqlstate | sqlcode (deprecated) | Symbolic name | Description | +| ------------------- | -------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `YE001` | `-12` | `ECPG_OUT_OF_MEMORY` | Virtual memory is exhausted. | +| `YE002` | `-200` | `ECPG_UNSUPPORTED` | The preprocessor generated an unrecognized item. Might indicate incompatibility between the preprocessor and the library. | +| `07001`, or `07002` | `-201` | `ECPG_TOO_MANY_ARGUMENTS` | The program specifies more variables than the command expects. | +| `07001`, or `07002` | `-202` | `ECPG_TOO_FEW_ARGUMENTS` | The program specified fewer variables than the command expects. | +| `21000` | `-203` | `ECPG_TOO_MANY_MATCHES` | The SQL command returned multiple rows, but the statement was prepared to receive a single row. | +| `42804` | `-204` | `ECPG_INT_FORMAT` | The host variable (defined in the C code) is of type INT, and the selected data is of a type that can't be converted into an INT. `ecpglib` uses the `strtol()` function to convert string values into numeric form. | +| `42804` | `-205` | `ECPG_UINT_FORMAT` | The host variable (defined in the C code) is an unsigned INT, and the selected data is of a type that can't be converted into an unsigned INT. `ecpglib` uses the `strtoul()` function to convert string values into numeric form. | +| `42804` | `-206` | `ECPG_FLOAT_FORMAT` | The host variable (defined in the C code) is of type FLOAT, and the selected data is of a type that can't be converted into a FLOAT. `ecpglib` uses the `strtod()` function to convert string values into numeric form. | +| `42804` | `-211` | `ECPG_CONVERT_BOOL` | The host variable (defined in the C code) is of type BOOL, and the selected data can't be stored in a BOOL. | +| `YE002` | `-2-1` | `ECPG_EMPTY` | The statement sent to the server was empty. | +| `22002` | `-213` | `ECPG_MISSING_INDICATOR` | A NULL indicator variable wasn't supplied for the NULL value returned by the server. (The client application received an unexpected NULL value.). | +| `42804` | `-214` | `ECPG_NO_ARRAY` | The server returned an array, and the corresponding host variable can't store an array. | +| `42804` | `-215` | `ECPG_DATA_NOT_ARRAY` | The server returned a value that isn't an array into a host variable that expects an array value. | +| `08003` | `-220` | `ECPG_NO_CONN` | The client application attempted to use a nonexistent connection. | +| `YE002` | `-221` | `ECPG_NOT_CONN` | The client application attempted to use an allocated but closed connection. | +| `26000` | `-230` | `ECPG_INVALID_STMT` | The statement wasn't prepared. | +| `33000` | `-240` | `ECPG_UNKNOWN_DESCRIPTOR` | The specified descriptor isn't found. | +| `07009` | `-241` | `ECPG_INVALID_DESCRIPTOR_INDEX` | The descriptor index is out of range. | +| `YE002` | `-242` | `ECPG_UNKNOWN_DESCRIPTOR_ITEM` | The client application requested an invalid descriptor item (internal error). | +| `07006` | `-243` | `ECPG_VAR_NOT_NUMERIC` | A dynamic statement returned a numeric value for a non-numeric host variable. | +| `07006` | `-244` | `ECPG_VAR_NOT_CHAR` | A dynamic SQL statement returned a CHAR value, and the host variable isn't a CHAR. | +| | `-400` | `ECPG_PGSQL` | The server returned an error message. The resulting message contains the error text. | +| `08007` | `-401` | `ECPG_TRANS` | The server can't start, commit, or roll back the specified transaction. | +| `08001` | `-402` | `ECPG_CONNECT` | The client application's attempt to connect to the database failed. | +| `02000` | `100` | `ECPG_NOT_FOUND` | The last command retrieved or processed no rows, or you reached the end of a cursor. | + +## EXEC SQL WHENEVER + +Use the `EXEC SQL WHENEVER` directive to implement simple error handling for client applications compiled with ECPGPlus. The syntax of the directive is: + +```sql +EXEC SQL WHENEVER ; +``` + +This directive instructs the ECPG compiler to insert error-handling code into your program. + +The code instructs the client application to perform a specified action if the client application detects a given condition. The *condition* can be one of the following: + +`SQLERROR` + + A `SQLERROR` condition exists when `sqlca.sqlcode` is less than zero. + +`SQLWARNING` + + A `SQLWARNING` condition exists when `sqlca.sqlwarn[0]` contains a `'W'`. + +`NOT FOUND` + + A `NOT FOUND` condition exists when `sqlca.sqlcode` is `ECPG_NOT_FOUND` (when a query returns no data). + +You can specify that the client application perform one of the following *actions* if it encounters one of the previous conditions: + +`CONTINUE` + + Specify `CONTINUE` to instruct the client application to continue processing, ignoring the current `condition`. `CONTINUE` is the default action. + +`DO CONTINUE` + + An action of `DO CONTINUE` generates a `CONTINUE` statement in the emitted C code. If it encounters the condition, it skips the rest of the code in the loop and continues with the next iteration. You can use it only in a loop. + +`GOTO label` or `GO TO label` + + Use a C `goto` statement to jump to the specified `label`. + +`SQLPRINT` + + Print an error message to `stderr` (standard error), using the `sqlprint()` function. The `sqlprint()` function prints `sql error` followed by the contents of `sqlca.sqlerrm.sqlerrmc`. + +`STOP` + + Call `exit(1)` to signal an error and terminate the program. + +`DO BREAK` + + Execute the C `break` statement. Use this action in loops or `switch` statements. + +`CALL name(args)` or `DO name(args)` + + Invoke the C function specified by the name `parameter`, using the parameters specified in the `args` parameter. + +## Example + +The following code fragment prints a message if the client application encounters a warning and aborts the application if it encounters an error: + +```sql +EXEC SQL WHENEVER SQLWARNING SQLPRINT; +EXEC SQL WHENEVER SQLERROR STOP; +``` + +!!! Note + The ECPGPlus compiler processes your program from top to bottom, even though the client application might not execute from top to bottom. The compiler directive is applied to each line in order and remains in effect until the compiler encounters another directive. If the control of the flow in your program isn't top to bottom, consider adding error-handling directives to any parts of the program that might be missed during compiling. diff --git a/product_docs/docs/epas/15/ecpgplus_guide/07_reference.mdx b/product_docs/docs/epas/15/ecpgplus_guide/07_reference.mdx new file mode 100644 index 00000000000..c878e3f0ceb --- /dev/null +++ b/product_docs/docs/epas/15/ecpgplus_guide/07_reference.mdx @@ -0,0 +1,1577 @@ +--- +title: "Reference" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.55.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.56.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.57.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.23.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.49.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.51.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.28.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.24.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.27.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.48.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.29.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.25.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.30.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.47.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.31.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.46.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.32.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.45.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.33.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.44.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.34.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.26.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.43.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.35.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.52.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.50.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.42.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.53.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.54.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.36.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.59.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.58.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.41.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.37.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.40.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.38.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/EDB_Postgres_Advanced_Server_ecpgPlus_Guide.1.39.html" + - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-reference-guide/9.6/Database_Compatibility_for_Oracle_Developers_Reference_Guide.1.093.html" + - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-reference-guide/9.6/Database_Compatibility_for_Oracle_Developers_Reference_Guide.1.058.html" + - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-reference-guide/9.6/Database_Compatibility_for_Oracle_Developers_Reference_Guide.1.031.html" + - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-reference-guide/9.6/Database_Compatibility_for_Oracle_Developers_Reference_Guide.1.033.html" + - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-reference-guide/9.6/Database_Compatibility_for_Oracle_Developers_Reference_Guide.1.085.html" + - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-reference-guide/9.6/Database_Compatibility_for_Oracle_Developers_Reference_Guide.1.087.html" + - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-reference-guide/9.6/Database_Compatibility_for_Oracle_Developers_Reference_Guide.1.082.html" + - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-reference-guide/9.6/Database_Compatibility_for_Oracle_Developers_Reference_Guide.1.088.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.349.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.351.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.352.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.350.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.348.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.114.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.119.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.113.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.111.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.108.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.086.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.063.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.061.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.103.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.104.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.100.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.102.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.101.html" +--- + + + +ECPGPlus has these language elements: + +- C-preprocessor directives +- Supported C data types +- Type codes +- The SQLDA structure +- ECPGPlus statements + +## C-preprocessor directives + +The ECPGPlus C-preprocessor enforces two behaviors that depend on the mode in which you invoke ECPGPlus: + +- `PROC` mode +- Non-`PROC` mode + +### Compiling in PROC mode + +In `PROC` mode, ECPGPlus allows you to: + +- Declare host variables outside of an `EXEC SQL BEGIN/END DECLARE SECTION`. +- Use any C variable as a host variable as long as its data type is compatible with ECPG. + +When you invoke ECPGPlus in `PROC` mode (by including the `-C PROC` keywords), the ECPG compiler honors the following C-preprocessor directives: + +```c +#include +#if expression +#ifdef symbolName +#ifndef symbolName +#else +#elif expression +#endif +#define symbolName expansion +#define symbolName([macro arguments]) expansion +#undef symbolName +#defined(symbolName) +``` + +Preprocessor directives are used to affect or direct the code that's received by the compiler. For example, consider the following code sample: + +```c +#if HAVE_LONG_LONG == 1 +#define BALANCE_TYPE long long +#else +#define BALANCE_TYPE double +#endif +... +BALANCE_TYPE customerBalance; +``` + +Suppose you invoke ECPGPlus with the following command-line arguments: + +```shell +ecpg –C PROC –DHAVE_LONG_LONG=1 +``` + +ECPGPlus copies the entire fragment, without change, to the output file. It sends only the following tokens to the ECPG parser: + +```shell +long long customerBalance; +``` + +On the other hand, suppose you invoke ECPGPlus with the following command-line arguments: + +```shell +ecpg –C PROC –DHAVE_LONG_LONG=0 +``` + +The ECPG parser receives the following tokens: + +```shell +double customerBalance; +``` + +If your code uses preprocessor directives to filter the code that's sent to the compiler, the complete code is retained in the original code, while the ECPG parser sees only the processed token stream. + +You can also use compatible syntax when executing the following preprocessor directives with an `EXEC` directive: + +```sql +EXEC ORACLE DEFINE +EXEC ORACLE UNDEF +EXEC ORACLE INCLUDE +EXEC ORACLE IFDEF +EXEC ORACLE IFNDEF +EXEC ORACLE ELIF +EXEC ORACLE ELSE +EXEC ORACLE ENDIF +EXEC ORACLE OPTION +``` + +For example, suppose your code includes the following: + +```sql +EXEC ORACLE IFDEF HAVE_LONG_LONG; +#define BALANCE_TYPE long long +EXEC ORACLE ENDIF; +BALANCE_TYPE customerBalance; +``` + +You invoke ECPGPlus with the following command-line arguments: + +```shell +ecpg –C PROC DEFINE=HAVE_LONG_LONG=1 +``` + +ECPGPlus sends the following tokens to the output file and the ECPG parser: + +```c +long long customerBalance; +``` + +!!! Note + The `EXEC ORACLE` preprocessor directives work only if you specify `-C PROC` on the ECPG command line. + +### Using the SELECT_ERROR precompiler option + +When using ECPGPlus in compatible mode, you can use the `SELECT_ERROR` precompiler option to tell your program how to handle result sets that contain more rows than the host variable can accommodate. The syntax is: + +```ini +SELECT_ERROR={YES|NO} +``` + +The default value is `YES`. A `SELECT` statement returns an error message if the result set exceeds the capacity of the host variable. Specify `NO` to suppress error messages when a `SELECT` statement returns more rows than a host variable can accommodate. + +Use `SELECT_ERROR` with the `EXEC ORACLE OPTION` directive. + +### Compiling in non-PROC mode + +If you don't include the `-C PROC` command-line option: + +- C preprocessor directives are copied to the output file without change. +- You must declare the type and name of each C variable that you intend to use as a host variable in an `EXEC SQL BEGIN/END DECLARE` section. + +When invoked in non-`PROC` mode, ECPG implements the behavior described in the PostgreSQL core documentation. + + + +## Supported C data types + +An ECPGPlus application must deal with two sets of data types: SQL data types (such as `SMALLINT`, `DOUBLE PRECISION`, and `CHARACTER VARYING`) and C data types (like `short`, `double`, and `varchar[n]`). When an application fetches data from the server, ECPGPlus maps each SQL data type to the type of the C variable into which the data is returned. + +In general, ECPGPlus can convert most SQL server types into similar C types, but not all combinations are valid. For example, ECPGPlus tries to convert a SQL character value into a C integer value, but the conversion might fail at execution time if the SQL character value contains non-numeric characters. + +The reverse is also true. When an application sends a value to the server, ECPGPlus tries to convert the C data type into the required SQL type. Again, the conversion might fail at execution time if the C value can't be converted into the required SQL type. + +ECPGPlus can convert any SQL type into C character values (`char[n]` or `varchar[n]`). Although it's safe to convert any SQL type to or from `char[n]` or `varchar[n]`, it's often convenient to use more natural C types such as `int`, `double`, or `float`. + +The supported C data types are: + +- `short` +- `int` +- `unsigned int` +- `long long int` +- `float` +- `double` +- `char[n+1]` +- `varchar[n+1]` +- `bool` +- Any equivalent created by a `typedef` + +In addition to the numeric and character types supported by C, the `pgtypeslib` runtime library offers custom data types, as well as functions to operate on those types, for dealing with date/time and exact numeric values: + +- `timestamp` +- `interval` +- `date` +- `decimal` +- `numeric` + +To use a data type supplied by `pgtypeslib`, you must `#include` the proper header file. + +## Type codes + +The following table contains the type codes for *external* data types. An external data type is used to indicate the type of a C host variable. When an application binds a value to a parameter or binds a buffer to a `SELECT`-list item, set the type code in the corresponding SQLDA descriptor `(descriptor->T[column])` to one of the following values: + +| Type code | Host variable type (C data type) | +| ------------------------------------------------- | ----------------------------------------- | +| `1, 2, 8, 11, 12, 15, 23, 24, 91, 94, 95, 96, 97` | `char[]` | +| `3` | `int` | +| `4, 7, 21` | `float` | +| `5, 6` | `null-terminated string (char[length+1])` | +| `9` | `varchar` | +| `22` | `double` | +| `68` | `unsigned int` | + +The following table contains the type codes for *internal* data types. An internal type code is used to indicate the type of a value as it resides in the database. The `DESCRIBE SELECT LIST` statement populates the data type array `(descriptor->T[column])` using the following values. + +| Internal type code | Server type | +| ---------------------- | ------------------------ | +| `1` | `VARCHAR2` | +| `2` | `NUMBER` | +| `8` | `LONG` | +| `11` | `ROWID` | +| `12` | `DATE` | +| `23` | `RAW` | +| `24` | `LONG RAW` | +| `96` | `CHAR` | +| `100` | `BINARY FLOAT` | +| `101` | `BINARY DOUBLE` | +| `104` | `UROWID` | +| `187` | `TIMESTAMP` | +| `188` | `TIMESTAMP W/TIMEZONE` | +| `189` | `INTERVAL YEAR TO MONTH` | +| `190` | `INTERVAL DAY TO SECOND` | +| `232` | `TIMESTAMP LOCAL_TZ` | + + + +## The SQLDA structure + +Oracle Dynamic SQL method 4 uses the SQLDA data structure to hold the data and metadata for a dynamic SQL statement. A SQLDA structure can describe a set of input parameters corresponding to the parameter markers found in the text of a dynamic statement or the result set of a dynamic statement. The layout of the SQLDA structure is: + +```c +struct SQLDA +{ + int N; /* Number of entries */ + char **V; /* Variables */ + int *L; /* Variable lengths */ + short *T; /* Variable types */ + short **I; /* Indicators */ + int F; /* Count of variables discovered by DESCRIBE */ + char **S; /* Variable names */ + short *M; /* Variable name maximum lengths */ + short *C; /* Variable name actual lengths */ + char **X; /* Indicator names */ + short *Y; /* Indicator name maximum lengths */ + short *Z; /* Indicator name actual lengths */ +}; +``` + +### Parameters + +`N - maximum number of entries` + + The `N` structure member contains the maximum number of entries that the SQLDA can describe. This member is populated by the `sqlald()` function when you allocate the SQLDA structure. Before using a descriptor in an `OPEN` or `FETCH` statement, you must set `N` to the actual number of values described. + +`V - data values` + + The `V` structure member is a pointer to an array of data values. + +- For a `SELECT`-list descriptor, `V` points to an array of values returned by a `FETCH` statement. Each member in the array corresponds to a column in the result set. +- For a bind descriptor, `V` points to an array of parameter values. You must populate the values in this array before opening a cursor that uses the descriptor. + +Your application must allocate the space required to hold each value. See [displayResultSet](05_building_executing_dynamic_sql_statements/#executing_query_with_unknown_number_of_variables) for an example of how to allocate space for `SELECT`-list values. + +`L - length of each data value` + + The `L` structure member is a pointer to an array of lengths. Each member of this array must indicate the amount of memory available in the corresponding member of the `V` array. For example, if `V[5]` points to a buffer large enough to hold a 20-byte NULL-terminated string, `L[5]` must contain the value 21 (20 bytes for the characters in the string plus 1 byte for the NULL-terminator). Your application must set each member of the `L` array. + +`T - data types` + + The `T` structure member points to an array of data types, one for each column (or parameter) described by the descriptor. + +- For a bind descriptor, you must set each member of the `T` array to tell ECPGPlus the data type of each parameter. +- For a `SELECT`-list descriptor, the `DESCRIBE SELECT LIST` statement sets each member of the `T` array to reflect the type of data found in the corresponding column. + +You can change any member of the `T` array before executing a `FETCH` statement to force ECPGPlus to convert the corresponding value to a specific data type. For example, if the `DESCRIBE SELECT LIST` statement indicates that a given column is of type `DATE`, you can change the corresponding `T` member to request that the next `FETCH` statement return that value in the form of a NULL-terminated string. Each member of the `T` array is a numeric type code (see [Type Codes](#type-codes) for a list of type codes). The type codes returned by a `DESCRIBE SELECT LIST` statement differ from those expected by a `FETCH` statement. After executing a `DESCRIBE SELECT LIST` statement, each member of `T` encodes a data type and a flag indicating whether the corresponding column is nullable. You can use the `sqlnul()` function to extract the type code and nullable flag from a member of the T array. The signature of the `sqlnul()` function is as follows: + +```c +void sqlnul(unsigned short *valType, + unsigned short *typeCode, + int *isNull) +``` + +For example, to find the type code and nullable flag for the third column of a descriptor named results, invoke `sqlnul()` as follows: + +```c +sqlnul(&results->T[2], &typeCode, &isNull); +``` + +`I - indicator variables` + + The `I` structure member points to an array of indicator variables. This array is allocated for you when your application calls the `sqlald()` function to allocate the descriptor. + +- For a `SELECT`-list descriptor, each member of the `I` array indicates whether the corresponding column contains a NULL (non-zero) or non-NULL (zero) value. +- For a bind parameter, your application must set each member of the `I` array to indicate whether the corresponding parameter value is NULL. + +`F - number of entries` + + The `F` structure member indicates how many values are described by the descriptor. The `N` structure member indicates the maximum number of values that the descriptor can describe. `F` indicates the actual number of values. The value of the `F` member is set by ECPGPlus when you execute a `DESCRIBE` statement. `F` can be positive, negative, or zero. + +- For a `SELECT`-list descriptor, `F` contains a positive value if the number of columns in the result set is equal to or less than the maximum number of values permitted by the descriptor (as determined by the `N` structure member). It contains 0 if the statement isn't a `SELECT` statement. It contains a negative value if the query returns more columns than allowed by the `N` structure member. +- For a bind descriptor, `F` contains a positive number if the number of parameters found in the statement is less than or equal to the maximum number of values permitted by the descriptor (as determined by the `N` structure member). It contains 0 if the statement contains no parameters markers. It contains a negative value if the statement contains more parameter markers than allowed by the `N` structure member. + +If `F` contains a positive number (after executing a `DESCRIBE` statement), that number reflects the count of columns in the result set (for a `SELECT`-list descriptor) or the number of parameter markers found in the statement (for a bind descriptor). If `F` contains a negative value, you can compute the absolute value of `F` to discover how many values or parameter markers are required. For example, if `F` contains `-24` after describing a `SELECT` list, you know that the query returns 24 columns. + +`S - column/parameter names` + + The `S` structure member points to an array of NULL-terminated strings. + +- For a `SELECT`-list descriptor, the `DESCRIBE SELECT LIST` statement sets each member of this array to the name of the corresponding column in the result set. +- For a bind descriptor, the `DESCRIBE BIND VARIABLES` statement sets each member of this array to the name of the corresponding bind variable. + +In this release, the name of each bind variable is determined by the left-to-right order of the parameter marker within the query. For example, the name of the first parameter is always `?0`, the name of the second parameter is always `?1`, and so on. + +`M - maximum column/parameter name length` + + The `M` structure member points to an array of lengths. Each member in this array specifies the maximum length of the corresponding member of the `S` array (that is, `M[0]` specifies the maximum length of the column/parameter name found at `S[0]`). This array is populated by the `sqlald()` function. + +`C - actual column/parameter name length` + + The `C` structure member points to an array of lengths. Each member in this array specifies the actual length of the corresponding member of the `S` array (that is, `C[0]` specifies the actual length of the column/parameter name found at `S[0]`). + + This array is populated by the `DESCRIBE` statement. + +`X - indicator variable names` + + The `X` structure member points to an array of NULL-terminated strings. Each string represents the name of a NULL indicator for the corresponding value. + + This array isn't used by ECPGPlus but is provided for compatibility with Pro\*C applications. + +`Y - maximum indicator name length` + + The `Y` structure member points to an array of lengths. Each member in this array specifies the maximum length of the corresponding member of the `X` array (that is, `Y[0]` specifies the maximum length of the indicator name found at `X[0]`). + + This array isn't used by ECPGPlus but is provided for compatibility with Pro\*C applications. + +`Z - actual indicator name length` + + The `Z` structure member points to an array of lengths. Each member in this array specifies the actual length of the corresponding member of the `X` array (that is, `Z[0]` specifies the actual length of the indicator name found at `X[0]`). + + This array isn't used by ECPGPlus but is provided for compatibility with Pro\*C applications. + +## ECPGPlus statements + +An embedded SQL statement allows your client application to interact with the server. An embedded directive is an instruction to the ECPGPlus compiler. + +You can embed any EDB Postgres Advanced Server SQL statement in a C program. Each statement must begin with the keywords `EXEC SQL` and must be terminated with a semi-colon (;). In the C program, a SQL statement takes the form: + +```sql +EXEC SQL ; +``` + +Where `sql_command_body` represents a standard SQL statement. You can use a host variable anywhere that the SQL statement expects a value expression. For more information about substituting host variables for value expressions, see [Declaring host variables](03_using_embedded_sql/#declaring-host-variables). + +ECPGPlus extends the PostgreSQL server-side syntax for some statements. Syntax differences are noted in the reference information that follows. For a complete reference to the supported syntax of other SQL commands, see the [PostgreSQL core documentation](https://www.postgresql.org/docs/current/static/sql-commands.html). + +### ALLOCATE DESCRIPTOR + +Use the `ALLOCATE DESCRIPTOR` statement to allocate an SQL descriptor area: + +```sql +EXEC SQL [FOR ] ALLOCATE DESCRIPTOR + [WITH MAX ]; +``` + +Where: + +- `array_size` is a variable that specifies the number of array elements to allocate for the descriptor. `array_size` can be an `INTEGER` value or a host variable. +- `descriptor_name` is the host variable that contains the name of the descriptor or the name of the descriptor. This value can take the form of an identifier, a quoted string literal, or of a host variable. +- `variable_count` specifies the maximum number of host variables in the descriptor. The default value of `variable_count` is `100`. + +The following code fragment allocates a descriptor named `emp_query` that can be processed as an array `(emp_array)`: + +```sql +EXEC SQL FOR :emp_array ALLOCATE DESCRIPTOR emp_query; +``` + +### CALL + +Use the `CALL` statement to invoke a procedure or function on the server. The `CALL` statement works only on EDB Postgres Advanced Server. The `CALL` statement comes in two forms. The first form is used to call a function: + +```sql +EXEC SQL CALL '('[]')' + INTO [[:][: ]]; +``` + +The second form is used to call a procedure: + +```sql +EXEC SQL CALL '('[]')'; +``` + +Where: + +- `program_name` is the name of the stored procedure or function that the `CALL` statement invokes. The program name can be schema qualified, package qualified, or both. If you don't specify the schema or package in which the program resides, ECPGPlus uses the value of `search_path` to locate the program. +- `actual_arguments` specifies a comma-separated list of arguments required by the program. Each `actual_argument` corresponds to a formal argument expected by the program. Each formal argument can be an `IN` parameter, an `OUT` parameter, or an `INOUT` parameter. +- `:ret_variable` specifies a host variable that receives the value returned if the program is a function. +- `:ret_indicator` specifies a host variable that receives the indicator value returned if the program is a function. + +For example, the following statement invokes the `get_job_desc` function with the value contained in the `:ename` host variable and captures the value returned by that function in the `:job` host variable: + +```sql +EXEC SQL CALL get_job_desc(:ename) + INTO :job; +``` + +### CLOSE + +Use the `CLOSE` statement to close a cursor and free any resources currently in use by the cursor. A client application can't fetch rows from a closed cursor. The syntax of the `CLOSE` statement is: + +```sql +EXEC SQL CLOSE []; +``` + +Where `cursor_name` is the name of the cursor closed by the statement. The cursor name can take the form of an identifier or of a host variable. + +The `OPEN` statement initializes a cursor. Once initialized, a cursor result set remains unchanged unless the cursor is reopened. You don't need to `CLOSE` a cursor before reopening it. + +To manually close a cursor named `emp_cursor`, use the command: + +```sql +EXEC SQL CLOSE emp_cursor; +``` + +A cursor is automatically closed when an application terminates. + +### COMMIT + +Use the `COMMIT` statement to complete the current transaction, making all changes permanent and visible to other users. The syntax is: + +```sql +EXEC SQL [AT ] COMMIT [WORK] + [COMMENT <'text'>] [COMMENT <'text'> RELEASE]; +``` + +Where `database_name` is the name of the database or host variable that contains the name of the database in which the work resides. This value can take the form of an unquoted string literal or of a host variable. + +For compatibility, ECPGPlus accepts the `COMMENT` clause without error but doesn't store any text included with the `COMMENT` clause. + +Include the `RELEASE` clause to close the current connection after performing the commit. + +For example, the following command commits all work performed on the `dept` database and closes the current connection: + +```sql +EXEC SQL AT dept COMMIT RELEASE; +``` + +By default, statements are committed only when a client application performs a `COMMIT` statement. Include the `-t` option when invoking ECPGPlus to specify for a client application to invoke `AUTOCOMMIT` functionality. You can also control `AUTOCOMMIT` functionality in a client application with the following statements: + +```sql +EXEC SQL SET AUTOCOMMIT TO ON +``` + +and + +```sql +EXEC SQL SET AUTOCOMMIT TO OFF +``` + +### CONNECT + +Use the `CONNECT` statement to establish a connection to a database. The `CONNECT` statement is available in two forms. One form is compatible with Oracle databases, and the other is not. + +The first form is compatible with Oracle databases: + +```sql +EXEC SQL CONNECT + {{: IDENTIFIED BY :} | :} + [AT ] + [USING :database_string] + [ALTER AUTHORIZATION :new_password]; +``` + +Where: + +- `user_name` is a host variable that contains the role that the client application uses to connect to the server. +- `password` is a host variable that contains the password associated with that role. +- `connection_id` is a host variable that contains a slash-delimited user name and password used to connect to the database. + +Include the `AT` clause to specify the database to which the connection is established. `database_name` is the name of the database to which the client is connecting. Specify the value in the form of a variable or as a string literal. + +Include the `USING` clause to specify a host variable that contains a null-terminated string identifying the database to which to establish the connection. + +The `ALTER AUTHORIZATION` clause is supported for syntax compatibility only. ECPGPlus parses the `ALTER AUTHORIZATION` clause and reports a warning. + +Using the first form of the `CONNECT` statement, a client application might establish a connection with a host variable named `user` that contains the identity of the connecting role and a host variable named `password` that contains the associated password using the following command: + +```text +EXEC SQL CONNECT :user IDENTIFIED BY :password; +``` + +A client application can also use the first form of the `CONNECT` statement to establish a connection using a single host variable named `:connection_id`. In the following example, `connection_id` contains the slash-delimited role name and associated password for the user: + +```sql +EXEC SQL CONNECT :connection_id; +``` + +The syntax of the second form of the `CONNECT` statement is: + +```sql +EXEC SQL CONNECT TO +[AS ] []; +``` + +Where `credentials` is one of the following: + +```sql +USER user_name password +USER user_name IDENTIFIED BY password +USER user_name USING password +``` + +In the second form: + +`database_name` is the name or identity of the database to which the client is connecting. Specify `database_name` as a variable or as a string literal in one of the following forms: + +```text +[@][:] + +tcp:postgresql://[:][/][options] + +unix:postgresql://[:][/][options] +``` + +Where: + +- `hostname` is the name or IP address of the server on which the database resides. +- `port` is the port on which the server listens. + + You can also specify a value of `DEFAULT` to establish a connection with the default database, using the default role name. If you specify `DEFAULT` as the target database, don't include a `connection_name` or `credentials`. + +- `connection_name` is the name of the connection to the database. `connection_name` takes the form of an identifier (that is, not a string literal or a variable). You can open multiple connections by providing a unique `connection_name` for each connection. + + If you don't specify a name for a connection, `ecpglib` assigns a name of `DEFAULT` to the connection. You can refer to the connection by name (`DEFAULT`) in any `EXEC SQL` statement. + +- `CURRENT` is the most recently opened or the connection mentioned in the most-recent `SET CONNECTION TO` statement. If you don't refer to a connection by name in an `EXEC SQL` statement, ECPG assumes the name of the connection to be `CURRENT`. + +- `user_name` is the role used to establish the connection with the EDB Postgres Advanced Server database. The privileges of the specified role are applied to all commands performed through the connection. + +- `password` is the password associated with the specified `user_name`. + +The following code fragment uses the second form of the `CONNECT` statement to establish a connection to a database named `edb` using the role `alice` and the password associated with that role, `1safepwd`: + +```sql +EXEC SQL CONNECT TO edb AS acctg_conn + USER 'alice' IDENTIFIED BY '1safepwd'; +``` + +The name of the connection is `acctg_conn`. You can use the connection name when changing the connection name using the `SET CONNECTION` statement. + +### DEALLOCATE DESCRIPTOR + +Use the `DEALLOCATE DESCRIPTOR` statement to free memory in use by an allocated descriptor. The syntax of the statement is: + +```sql +EXEC SQL DEALLOCATE DESCRIPTOR +``` + +Where `descriptor_name` is the name of the descriptor. This value can take the form of a quoted string literal or of a host variable. + +The following example deallocates a descriptor named `emp_query`: + +```sql +EXEC SQL DEALLOCATE DESCRIPTOR emp_query; +``` + +### DECLARE CURSOR + +Use the `DECLARE CURSOR` statement to define a cursor. The syntax of the statement is: + +```sql +EXEC SQL [AT ] DECLARE CURSOR FOR +( | ); +``` + +Where: + +- `database_name` is the name of the database on which the cursor operates. This value can take the form of an identifier or of a host variable. If you don't specify a database name, the default value of `database_name` is the default database. +- `cursor_name` is the name of the cursor. +- `select_statement` is the text of the `SELECT` statement that defines the cursor result set. The `SELECT` statement can't contain an `INTO` clause. +- `statement_name` is the name of a SQL statement or block that defines the cursor result set. + +The following example declares a cursor named `employees`: + +```sql +EXEC SQL DECLARE employees CURSOR FOR + SELECT + empno, ename, sal, comm + FROM + emp; +``` + +The cursor generates a result set that contains the employee number, employee name, salary, and commission for each employee record that's stored in the `emp` table. + +### DECLARE DATABASE + +Use the `DECLARE DATABASE` statement to declare a database identifier for use in subsequent SQL statements (for example, in a `CONNECT` statement). The syntax is: + +```sql +EXEC SQL DECLARE DATABASE; +``` + +Where `database_name` specifies the name of the database. + +The following example shows declaring an identifier for the `acctg` database: + +```sql +EXEC SQL DECLARE acctg DATABASE; +``` + +After invoking the command declaring `acctg` as a database identifier, you can reference the `acctg` database by name when establishing a connection or in `AT` clauses. + +This statement has no effect and is provided for Pro\*C compatibility only. + +### DECLARE STATEMENT + +Use the `DECLARE STATEMENT` directive to declare an identifier for an SQL statement. EDB Postgres Advanced Server supports two versions of the `DECLARE STATEMENT` directive: + +```sql +EXEC SQL [] DECLARE STATEMENT; +``` + +and + +```sql +EXEC SQL DECLARE STATEMENT ; +``` + +Where: + +- `statement_name` specifies the identifier associated with the statement. +- `database_name` specifies the name of the database. This value may take the form of an identifier or of a host variable that contains the identifier. + +A typical usage sequence that includes the `DECLARE STATEMENT` directive is: + +```sql +EXEC SQL DECLARE give_raise STATEMENT; // give_raise is now a statement +handle (not prepared) +EXEC SQL PREPARE give_raise FROM :stmtText; // give_raise is now associated +with a statement +EXEC SQL EXECUTE give_raise; +``` + +This statement has no effect and is provided for Pro\*C compatibility only. + +### DELETE + +Use the `DELETE` statement to delete one or more rows from a table. The syntax for the ECPGPlus `DELETE` statement is the same as the syntax for the SQL statement, but you can use parameter markers and host variables any place that an expression is allowed. The syntax is: + +```sql +[FOR ] DELETE FROM [ONLY] [[AS] ] + [USING ] + [WHERE | WHERE CURRENT OF ] + [{RETURNING|RETURN} * | [[AS] ] +[, ...] INTO ] +``` + +- Include the `FOR exec_count` clause to specify the number of times the statement executes. This clause is valid only if the `VALUES` clause references an array or a pointer to an array. +- `table` is the name (optionally schema qualified) of an existing table. Include the `ONLY` clause to limit processing to the specified table. If you don't include the `ONLY` clause, any tables inheriting from the named table are also processed. +- `alias` is a substitute name for the target table. +- `using_list` is a list of table expressions, allowing columns from other tables to appear in the `WHERE` condition. +- Include the `WHERE` clause to specify the rows to delete. If you don't include a `WHERE` clause in the statement, `DELETE` deletes all rows from the table, leaving the table definition intact. +- `condition` is an expression, host variable, or parameter marker that returns a value of type `BOOLEAN`. Those rows for which `condition` returns true are deleted. +- `cursor_name` is the name of the cursor to use in the `WHERE CURRENT OF` clause. The row to be deleted is the one most recently fetched from this cursor. The cursor must be a nongrouping query on the `DELETE` statements target table. You can't specify `WHERE CURRENT OF` in a `DELETE` statement that includes a Boolean condition. + +The `RETURN/RETURNING` clause specifies an `output_expression` or `host_variable_list` that's returned by the `DELETE` command after each row is deleted: + + - `output_expression` is an expression to be computed and returned by the `DELETE` command after each row is deleted. `output_name` is the name of the returned column. Include \* to return all columns. + - `host_variable_list` is a comma-separated list of host variables and optional indicator variables. Each host variable receives a corresponding value from the `RETURNING` clause. + +For example, the following statement deletes all rows from the `emp` table, where the `sal` column contains a value greater than the value specified in the host variable, `:max_sal:` + +```sql +DELETE FROM emp WHERE sal > :max_sal; +``` + +For more information about using the `DELETE` statement, see the [PostgreSQL core documentation](https://www.postgresql.org/docs/current/static/sql-delete.html). + +### DESCRIBE + +Use the `DESCRIBE` statement to find the number of input values required by a prepared statement or the number of output values returned by a prepared statement. The `DESCRIBE` statement is used to analyze a SQL statement whose shape is unknown at the time you write your application. + +The `DESCRIBE` statement populates an `SQLDA` descriptor. To populate a SQL descriptor, use the `ALLOCATE DESCRIPTOR` and `DESCRIBE...DESCRIPTOR` statements. + +```sql +EXEC SQL DESCRIBE BIND VARIABLES FOR INTO ; +``` + + +```sql +EXEC SQL DESCRIBE SELECT LIST FOR INTO ; +``` + +Where: + +- `statement_name` is the identifier associated with a prepared SQL statement or PL/SQL block. +- `descriptor` is the name of C variable of type `SQLDA*`. You must allocate the space for the descriptor by calling `sqlald()` and initialize the descriptor before executing the `DESCRIBE` statement. + +When you execute the first form of the `DESCRIBE` statement, ECPG populates the given descriptor with a description of each input variable *required* by the statement. For example, given two descriptors: + +```sql +SQLDA *query_values_in; +SQLDA *query_values_out; +``` + +You might prepare a query that returns information from the `emp` table: + +```sql +EXEC SQL PREPARE get_emp FROM + "SELECT ename, empno, sal FROM emp WHERE empno = ?"; +``` + +The command requires one input variable for the parameter marker (?). + +```sql +EXEC SQL DESCRIBE BIND VARIABLES + FOR get_emp INTO query_values_in; +``` + +After describing the bind variables for this statement, you can examine the descriptor to find the number of variables required and the type of each variable. + +When you execute the second form, ECPG populates the given descriptor with a description of each value returned by the statement. For example, the following statement returns three values: + +```sql +EXEC SQL DESCRIBE SELECT LIST + FOR get_emp INTO query_values_out; +``` + +After describing the select list for this statement, you can examine the descriptor to find the number of returned values and the name and type of each value. + +Before executing the statement, you must bind a variable for each input value and a variable for each output value. The variables that you bind for the input values specify the actual values used by the statement. The variables that you bind for the output values tell ECPGPlus where to put the values when you execute the statement. + +This is alternative Pro\*C-compatible syntax for the `DESCRIBE DESCRIPTOR` statement. + +### DESCRIBE DESCRIPTOR + +Use the `DESCRIBE DESCRIPTOR` statement to retrieve information about a SQL statement and store that information in a SQL descriptor. Before using `DESCRIBE DESCRIPTOR`, you must allocate the descriptor with the `ALLOCATE DESCRIPTOR` statement. The syntax is: + +```sql +EXEC SQL DESCRIBE [INPUT | OUTPUT] + USING [SQL] DESCRIPTOR ; +``` + +Where: + +- `statement_name` is the name of a prepared SQL statement. +- `descriptor_name` is the name of the descriptor. `descriptor_name` can be a quoted string value or a host variable that contains the name of the descriptor. + +If you include the `INPUT` clause, ECPGPlus populates the given descriptor with a description of each input variable required by the statement. + +For example, given two descriptors: + +```sql +EXEC SQL ALLOCATE DESCRIPTOR query_values_in; +EXEC SQL ALLOCATE DESCRIPTOR query_values_out; +``` + +You might prepare a query that returns information from the `emp` table: + +```sql +EXEC SQL PREPARE get_emp FROM + "SELECT ename, empno, sal FROM emp WHERE empno = ?"; +``` + +The command requires one input variable for the parameter marker (?). + +```sql +EXEC SQL DESCRIBE INPUT get_emp USING 'query_values_in'; +``` + +After describing the bind variables for this statement, you can examine the descriptor to find the number of variables required and the type of each variable. + +If you don't specify the `INPUT` clause, `DESCRIBE DESCRIPTOR` populates the specified descriptor with the values returned by the statement. + +If you include the `OUTPUT` clause, ECPGPlus populates the given descriptor with a description of each value returned by the statement. + +For example, the following statement returns three values: + +```sql +EXEC SQL DESCRIBE OUTPUT FOR get_emp USING 'query_values_out'; +``` + +After describing the select list for this statement, you can examine the descriptor to find the number of returned values and the name and type of each value. + +### DISCONNECT + +Use the `DISCONNECT` statement to close the connection to the server. The syntax is: + +```sql +EXEC SQL DISCONNECT [][CURRENT][DEFAULT][ALL]; +``` + +Where `connection_name` is the connection name specified in the `CONNECT` statement used to establish the connection. If you don't specify a connection name, the current connection is closed. + +Include the `CURRENT` keyword to specify for ECPGPlus to close the connection used most recently. + +Include the `DEFAULT` keyword to specify for ECPGPlus to close the connection named `DEFAULT`. If you don't specify a name when opening a connection, ECPGPlus assigns the name `DEFAULT` to the connection. + +Include the `ALL` keyword to close all active connections. + +The following example creates a connection named `hr_connection` that connects to the `hr` database and then disconnects from the connection: + +```c +/* client.pgc*/ +int main() +{ + EXEC SQL CONNECT TO hr AS connection_name; + EXEC SQL DISCONNECT connection_name; + return(0); +} +``` + +### EXECUTE + +Use the `EXECUTE` statement to execute a statement previously prepared using an `EXEC SQL PREPARE` statement. The syntax is: + +```sql +EXEC SQL [FOR ] EXECUTE + [USING {DESCRIPTOR + |: [[INDICATOR] :]}]; +``` + +Where: + +- `array_size` is an integer value or a host variable that contains an integer value that specifies the number of rows to process. If you omit the `FOR` clause, the statement is executed once for each member of the array. +- `statement_name` specifies the name assigned to the statement when the statement was created using the `EXEC SQL PREPARE` statement. + +Include the `USING` clause to supply values for parameters in the prepared statement: + +- Include the `DESCRIPTOR` `SQLDA_descriptor` clause to provide an SQLDA descriptor value for a parameter. +- Use a `host_variable` (and an optional `indicator_variable`) to provide a user-specified value for a parameter. + +The following example creates a prepared statement that inserts a record into the `emp` table: + +```sql +EXEC SQL PREPARE add_emp (numeric, text, text, numeric) AS + INSERT INTO emp VALUES($1, $2, $3, $4); +``` + +Each time you invoke the prepared statement, provide fresh parameter values for the statement: + +```sql +EXEC SQL EXECUTE add_emp USING 8000, 'DAWSON', 'CLERK', 7788; +EXEC SQL EXECUTE add_emp USING 8001, 'EDWARDS', 'ANALYST', 7698; +``` + +### EXECUTE DESCRIPTOR + +Use the `EXECUTE` statement to execute a statement previously prepared by an `EXEC SQL PREPARE` statement, using an SQL descriptor. The syntax is: + +```sql +EXEC SQL [FOR ] EXECUTE + [USING [SQL] DESCRIPTOR ] + [INTO [SQL] DESCRIPTOR ]; +``` + +Where: + +- `array_size` is an integer value or a host variable that contains an integer value that specifies the number of rows to process. If you omit the `FOR` clause, the statement is executed once for each member of the array. +- `statement_identifier` specifies the identifier assigned to the statement with the `EXEC SQL PREPARE` statement. +- `descriptor_name` specifies the name of a descriptor (as a single-quoted string literal), or a host variable that contains the name of a descriptor. + +Include the `USING` clause to specify values for any input parameters required by the prepared statement. + +Include the `INTO` clause to specify a descriptor into which the `EXECUTE` statement writes the results returned by the prepared statement. + +The following example executes the prepared statement, `give_raise`, using the values contained in the descriptor `stmtText:` + +```sql +EXEC SQL PREPARE give_raise FROM :stmtText; +EXEC SQL EXECUTE give_raise USING DESCRIPTOR :stmtText; +``` + +### EXECUTE...END EXEC + +Use the `EXECUTE…END-EXEC` statement to embed an anonymous block into a client application. The syntax is: + +```sql +EXEC SQL [AT ] EXECUTE END-EXEC; +``` + +Where: + +- `database_name` is the database identifier or a host variable that contains the database identifier. If you omit the `AT` clause, the statement executes on the current default database. +- `anonymous_block` is an inline sequence of PL/pgSQL or SPL statements and declarations. You can include host variables and optional indicator variables in the block. Each such variable is treated as an `IN/OUT` value. + +The following example executes an anonymous block: + +```sql +EXEC SQL EXECUTE + BEGIN + IF (current_user = :admin_user_name) THEN + DBMS_OUTPUT.PUT_LINE('You are an administrator'); + END IF; +END-EXEC; +``` + +!!! Note + The `EXECUTE…END EXEC` statement is supported only by EDB Postgres Advanced Server. + +### EXECUTE IMMEDIATE + +Use the `EXECUTE IMMEDIATE` statement to execute a string that contains a SQL command. The syntax is: + +```sql +EXEC SQL [AT ] EXECUTE IMMEDIATE ; +``` + +Where: + +- `database_name` is the database identifier or a host variable that contains the database identifier. If you omit the `AT` clause, the statement executes on the current default database. +- `command_text` is the command executed by the `EXECUTE IMMEDIATE` statement. + +This dynamic SQL statement is useful when you don't know the text of an SQL statement when writing a client application. For example, a client application might prompt a trusted user for a statement to execute. After the user provides the text of the statement as a string value, the statement is then executed with an `EXECUTE IMMEDIATE` command. + +The statement text can't contain references to host variables. If the statement might contain parameter markers or returns one or more values, use the `PREPARE` and `DESCRIBE` statements. + +The following example executes the command contained in the `:command_text` host variable: + +```sql +EXEC SQL EXECUTE IMMEDIATE :command_text; +``` + +### FETCH + +Use the `FETCH` statement to return rows from a cursor into an SQLDA descriptor or a target list of host variables. Before using a `FETCH` statement to retrieve information from a cursor, you must prepare the cursor using `DECLARE` and `OPEN` statements. The statement syntax is: + +```sql +EXEC SQL [FOR ] FETCH + { USING DESCRIPTOR }|{ INTO }; +``` + +Where: + +- `array_size` is an integer value or a host variable that contains an integer value specifying the number of rows to fetch. If you omit the `FOR` clause, the statement is executed once for each member of the array. +- `cursor` is the name of the cursor from which rows are being fetched or a host variable that contains the name of the cursor. + +If you include a `USING` clause, the `FETCH` statement populates the specified SQLDA descriptor with the values returned by the server. + +If you include an `INTO` clause, the `FETCH` statement populates the host variables (and optional indicator variables) specified in the `target_list`. + +The following code fragment declares a cursor named `employees` that retrieves the `employee number`, `name`, and `salary` from the `emp` table: + +```sql +EXEC SQL DECLARE employees CURSOR FOR + SELECT empno, ename, esal FROM emp; +EXEC SQL OPEN emp_cursor; +EXEC SQL FETCH emp_cursor INTO :emp_no, :emp_name, :emp_sal; +``` + +### FETCH DESCRIPTOR + +Use the `FETCH DESCRIPTOR` statement to retrieve rows from a cursor into an SQL descriptor. The syntax is: + +```sql +EXEC SQL [FOR ] FETCH + INTO [SQL] DESCRIPTOR ; +``` + +Where: + +- `array_size` is an integer value or a host variable that contains an integer value specifying the number of rows to fetch. If you omit the `FOR` clause, the statement is executed once for each member of the array. +- `cursor` is the name of the cursor from which rows are fetched or a host variable that contains the name of the cursor. The client must `DECLARE` and `OPEN` the cursor before calling the `FETCH DESCRIPTOR` statement. +- `descriptor_name` specifies the name of a descriptor (as a single-quoted string literal) or a host variable that contains the name of a descriptor. Prior to use, the descriptor must be allocated using an `ALLOCATE DESCRIPTOR` statement. + +Include the `INTO` clause to specify a SQL descriptor into which the `EXECUTE` statement writes the results returned by the prepared statement. + +The following example allocates a descriptor named `row_desc` that holds the description and the values of a specific row in the result set. It then declares and opens a cursor for a prepared statement (`my_cursor`), before looping through the rows in result set, using a `FETCH` to retrieve the next row from the cursor into the descriptor: + +```sql +EXEC SQL ALLOCATE DESCRIPTOR 'row_desc'; +EXEC SQL DECLARE my_cursor CURSOR FOR query; +EXEC SQL OPEN my_cursor; + +for( row = 0; ; row++ ) +{ + EXEC SQL BEGIN DECLARE SECTION; + int col; +EXEC SQL END DECLARE SECTION; +EXEC SQL FETCH my_cursor INTO SQL DESCRIPTOR 'row_desc'; +``` + +### GET DESCRIPTOR + +Use the `GET DESCRIPTOR` statement to retrieve information from a descriptor. The `GET DESCRIPTOR` statement comes in two forms. The first form returns the number of values (or columns) in the descriptor. + +```sql +EXEC SQL GET DESCRIPTOR + : = COUNT; +``` + +The second form returns information about a specific value (specified by the `VALUE column_number` clause): + +```sql +EXEC SQL [FOR ] GET DESCRIPTOR + VALUE {: = {,…}}; +``` + +Where: + +- `array_size` is an integer value or a host variable that contains an integer value that specifies the number of rows to process. If you specify an `array_size`, the `host_variable` must be an array of that size. For example, if `array_size` is `10`, `:host_variable` must be a 10-member array of `host_variables`. If you omit the `FOR` clause, the statement is executed once for each member of the array. +- `descriptor_name` specifies the name of a descriptor as a single-quoted string literal or a host variable that contains the name of a descriptor. + +Include the `VALUE` clause to specify the information retrieved from the descriptor. + +- `column_number` identifies the position of the variable in the descriptor. +- `host_variable` specifies the name of the host variable that receives the value of the item. +- `descriptor_item` specifies the type of the retrieved descriptor item. + +ECPGPlus implements the following `descriptor_item` types: + +- `TYPE` +- `LENGTH` +- `OCTET_LENGTH` +- `RETURNED_LENGTH` +- `RETURNED_OCTET_LENGTH` +- `PRECISION` +- `SCALE` +- `NULLABLE` +- `INDICATOR` +- `DATA` +- `NAME` + +The following code fragment shows using a `GET DESCRIPTOR` statement to obtain the number of columns entered in a user-provided string: + +```sql +EXEC SQL ALLOCATE DESCRIPTOR parse_desc; +EXEC SQL PREPARE query FROM :stmt; +EXEC SQL DESCRIBE query INTO SQL DESCRIPTOR parse_desc; +EXEC SQL GET DESCRIPTOR parse_desc :col_count = COUNT; +``` + +The example allocates an SQL descriptor named `parse_desc` before using a `PREPARE` statement to check the syntax of the string provided by the user `:stmt`. A `DESCRIBE` statement moves the user-provided string into the descriptor, `parse_desc`. The call to `EXEC SQL GET DESCRIPTOR` interrogates the descriptor to discover the number of columns `(:col_count)` in the result set. + +### INSERT + +Use the `INSERT` statement to add one or more rows to a table. The syntax for the ECPGPlus `INSERT` statement is the same as the syntax for the SQL statement, but you can use parameter markers and host variables any place that a value is allowed. The syntax is: + +```sql +[FOR ] INSERT INTO
[( [, ...])] + {DEFAULT VALUES | + VALUES ({ | DEFAULT} [, ...])[, ...] | } + [RETURNING * | [[ AS ] ] [, ...]] +``` + +Include the `FOR exec_count` clause to specify the number of times the statement executes. This clause is valid only if the `VALUES` clause references an array or a pointer to an array. + +- `table` specifies the (optionally schema-qualified) name of an existing table. +- `column` is the name of a column in the table. The column name can be qualified with a subfield name or array subscript. Specify the `DEFAULT VALUES` clause to use default values for all columns. +- `expression` is the expression, value, host variable, or parameter marker that's assigned to the corresponding column. Specify `DEFAULT` to fill the corresponding column with its default value. +- `query` specifies a `SELECT` statement that supplies the rows to insert. +- `output_expression` is an expression that's computed and returned by the `INSERT` command after each row is inserted. The expression can refer to any column in the table. Specify \* to return all columns of the inserted rows. +- `output_name` specifies a name to use for a returned column. + +The following example adds a row to the `employees` table: + +```sql +INSERT INTO emp (empno, ename, job, hiredate) + VALUES ('8400', :ename, 'CLERK', '2011-10-31'); +``` + +!!! Note + The `INSERT` statement uses a host variable `:ename` to specify the value of the `ename` column. + +For more information about using the `INSERT` statement, see the [PostgreSQL core documentation](https://www.postgresql.org/docs/current/static/sql-insert.html). + +### OPEN + +Use the `OPEN` statement to open a cursor. The syntax is: + +```sql +EXEC SQL [FOR ] OPEN [USING ]; +``` + +`parameters` is one of the following: + +```sql +DESCRIPTOR +``` + +or + +```sql + [ [ INDICATOR ] , … ] +``` + +Where: + +- `array_size` is an integer value or a host variable that contains an integer value specifying the number of rows to fetch. If you omit the `FOR` clause, the statement is executed once for each member of the array. +- `cursor` is the name of the cursor being opened. +- `parameters` is either `DESCRIPTOR SQLDA_descriptor` or a comma-separated list of `host variables` and optional `indicator variables` that initialize the cursor. If specifying an `SQLDA_descriptor`, the descriptor must be initialized with a `DESCRIBE` statement. + +The `OPEN` statement initializes a cursor using the values provided in `parameters`. Once initialized, the cursor result set remains unchanged unless the cursor is closed and reopened. A cursor is automatically closed when an application terminates. + +The following example declares a cursor named `employees` that queries the `emp` table. It returns the `employee number`, `name`, `salary`, and `commission` of an employee whose name matches a user-supplied value stored in the host variable `:emp_name`. + +```sql +EXEC SQL DECLARE employees CURSOR FOR + SELECT + empno, ename, sal, comm  + FROM  + emp + WHERE ename = :emp_name; +EXEC SQL OPEN employees; +... +``` + +After declaring the cursor, the example uses an `OPEN` statement to make the contents of the cursor available to a client application. + +### OPEN DESCRIPTOR + +Use the `OPEN DESCRIPTOR` statement to open a cursor with a SQL descriptor. The syntax is: + +```sql +EXEC SQL [FOR ] OPEN + [USING [SQL] DESCRIPTOR ] + [INTO [SQL] DESCRIPTOR ]; +``` + +Where: + +- `array_size` is an integer value or a host variable that contains an integer value specifying the number of rows to fetch. If you omit the `FOR` clause, the statement is executed once for each member of the array. +- `cursor` is the name of the cursor being opened. +- `descriptor_name` specifies the name of an SQL descriptor in the form of a single-quoted string literal or a host variable that contains the name of an SQL descriptor that contains the query that initializes the cursor. + +For example, the following statement opens a cursor named `emp_cursor` using the host variable `:employees`: + +```sql +EXEC SQL OPEN emp_cursor USING DESCRIPTOR :employees; +``` + +### PREPARE + +Prepared statements are useful when a client application must perform a task multiple times. The statement is parsed, written, and planned only once rather than each time the statement is executed. This approach saves repetitive processing time. + +Use the `PREPARE` statement to prepare a SQL statement or PL/pgSQL block for execution. The statement is available in two forms. The first form is: + +```sql +EXEC SQL [AT ] PREPARE + FROM ; +``` + +The second form is: + +```sql +EXEC SQL [AT ] PREPARE + AS ; +``` + +Where: + +- `database_name` is the database identifier or a host variable that contains the database identifier against which the statement executes. If you omit the `AT` clause, the statement executes against the current default database. +- `statement_name` is the identifier associated with a prepared SQL statement or PL/SQL block. +- `sql_statement` can take the form of a `SELECT` statement, a single-quoted string literal, or a host variable that contains the text of an SQL statement. + +To include variables in a prepared statement, substitute placeholders (`$1, $2, $3`, and so on) for statement values that might change when you `PREPARE` the statement. When you `EXECUTE` the statement, provide a value for each parameter. Provide the values in the order in which they replace placeholders. + +The following example creates a prepared statement named `add_emp` that inserts a record into the `emp` table: + +```sql +EXEC SQL PREPARE add_emp (int, text, text, numeric) AS + INSERT INTO emp VALUES($1, $2, $3, $4); +``` + +Each time you invoke the statement, provide fresh parameter values for the statement: + +```sql +EXEC SQL EXECUTE add_emp(8003, 'Davis', 'CLERK', 2000.00); +EXEC SQL EXECUTE add_emp(8004, 'Myer', 'CLERK', 2000.00); +``` + +!!! Note + A client application must issue a `PREPARE` statement in each session in which a statement executes. Prepared statements persist only for the duration of the current session. + +### ROLLBACK + +Use the `ROLLBACK` statement to abort the current transaction and discard any updates made by the transaction. The syntax is: + +```sql +EXEC SQL [AT ] ROLLBACK [WORK] + [ { TO [SAVEPOINT] } | RELEASE ] +``` + +Where `database_name` is the database identifier or a host variable that contains the database identifier against which the statement executes. If you omit the `AT` clause, the statement executes against the current default database. + +Include the `TO` clause to abort any commands that executed after the specified `savepoint`. Use the `SAVEPOINT` statement to define the `savepoint`. If you omit the `TO` clause, the `ROLLBACK` statement aborts the transaction, discarding all updates. + +Include the `RELEASE` clause to cause the application to execute an `EXEC SQL COMMIT RELEASE` and close the connection. + +Use the following statement to roll back a complete transaction: + +```sql +EXEC SQL ROLLBACK; +``` + +Invoking this statement aborts the transaction, undoing all changes, erasing any savepoints, and releasing all transaction locks. Suppose you include a savepoint (`my_savepoint` in the following example): + +```sql +EXEC SQL ROLLBACK TO SAVEPOINT my_savepoint; +``` + +Only the portion of the transaction that occurred after the `my_savepoint` is rolled back. `my_savepoint` is retained, but any savepoints created after `my_savepoint` are erased. + +Rolling back to a specified savepoint releases all locks acquired after the savepoint. + +### SAVEPOINT + +Use the `SAVEPOINT` statement to define a *savepoint*. A savepoint is a marker in a transaction. You can use a `ROLLBACK` statement to abort the current transaction, returning the state of the server to its condition prior to the specified savepoint. The syntax of a `SAVEPOINT` statement is: + +```sql +EXEC SQL [AT ] SAVEPOINT +``` + +Where: + +- `database_name` is the database identifier or a host variable that contains the database identifier against which the savepoint resides. If you omit the `AT` clause, the statement executes against the current default database. +- `savepoint_name` is the name of the savepoint. If you reuse a `savepoint_name`, the original savepoint is discarded. + +You can establish savepoints only in a transaction block. A transaction block can contain multiple savepoints. + +To create a savepoint named `my_savepoint`, include the statement: + +```sql +EXEC SQL SAVEPOINT my_savepoint; +``` + +### SELECT + +ECPGPlus extends support of the `SQL SELECT` statement by providing the `INTO host_variables` clause. The clause allows you to select specified information from an EDB Postgres Advanced Server database into a host variable. The syntax for the `SELECT` statement is: + +```sql +EXEC SQL [AT ] +SELECT + [ ] + [ ALL | DISTINCT [ ON( , ...) ]] + select_list INTO + + [ FROM from_item [, from_item ]...] + [ WHERE condition ] + [ hierarchical_query_clause ] + [ GROUP BY expression [, ...]] + [ HAVING condition ] + [ { UNION [ ALL ] | INTERSECT | MINUS } (subquery) ] + [ ORDER BY expression [order_by_options]] + [ LIMIT { count | ALL }] + [ OFFSET start [ ROW | ROWS ] ] + [ FETCH { FIRST | NEXT } [ count ] { ROW | ROWS } ONLY ] + [ FOR { UPDATE | SHARE } [OF table_name [, ...]][NOWAIT ][...]] +``` + +Where: + +- `database_name` is the name of the database or host variable that contains the name of the database in which the table resides. This value can take the form of an unquoted string literal or of a host variable. +- `host_variables` is a list of host variables populated by the `SELECT` statement. If the `SELECT` statement returns more than a single row, `host_variables` must be an array. + +ECPGPlus provides support for the additional clauses of the SQL `SELECT` statement as documented in the [PostgreSQL core documentation](https://www.postgresql.org/docs/current/static/sql-select.html). + +To use the `INTO host_variables` clause, include the names of defined host variables when specifying the `SELECT` statement. For example, the following `SELECT` statement populates the `:emp_name` and `:emp_sal` host variables with a list of employee names and salaries: + +```sql +EXEC SQL SELECT ename, sal + INTO :emp_name, :emp_sal + FROM emp + WHERE empno = 7988; +``` + +The enhanced `SELECT` statement also allows you to include parameter markers (question marks) in any clause where a value is allowed. For example, the following query contains a parameter marker in the `WHERE` clause: + +```sql +SELECT * FROM emp WHERE dept_no = ?; +``` + +This `SELECT` statement allows you to provide a value at runtime for the `dept_no` parameter marker. + +### SET CONNECTION + +There are at least three reasons you might need more than one connection in a given client application: + +- You might want different privileges for different statements. +- You might need to interact with multiple databases in the same client. +- Multiple threads of execution in a client application can't share a connection concurrently. + +The syntax for the `SET CONNECTION` statement is: + +```sql +EXEC SQL SET CONNECTION ; +``` + +Where `connection_name` is the name of the connection to the database. + +To use the `SET CONNECTION` statement, open the connection to the database using the second form of the `CONNECT` statement. Include the `AS` clause to specify a `connection_name`. + +By default, the current thread uses the current connection. Use the `SET CONNECTION` statement to specify a default connection for the current thread to use. The default connection is used only when you execute an `EXEC SQL` statement that doesn't explicitly specify a connection name. For example, the following statement uses the default connection because it doesn't include an `AT connection_name` clause: + +```sql +EXEC SQL DELETE FROM emp; +``` + +This statement doesn't use the default connection because it specifies a connection name using the `AT connection_name` clause: + +```sql +EXEC SQL AT acctg_conn DELETE FROM emp; +``` + +For example, suppose a client application creates and maintains multiple connections using either of the following approaches: + +```sql +EXEC SQL CONNECT TO edb AS acctg_conn + USER 'alice' IDENTIFIED BY 'acctpwd'; +``` + + +```sql +EXEC SQL CONNECT TO edb AS hr_conn + USER 'bob' IDENTIFIED BY 'hrpwd'; +``` + +It can change between the connections with the `SET CONNECTION` statement: + +```sql +SET CONNECTION acctg_conn; +``` + +or + +```sql +SET CONNECTION hr_conn; +``` + +The server uses the privileges associated with the connection when determining the privileges available to the connecting client. When using the `acctg_conn` connection, the client has the privileges associated with the role `alice`. When connected using `hr_conn`, the client has the privileges associated with `bob`. + +### SET DESCRIPTOR + +Use the `SET DESCRIPTOR` statement to assign a value to a descriptor area using information provided by the client application in the form of a host variable or an integer value. The statement comes in two forms. The first form is: + +```sql +EXEC SQL [FOR ] SET DESCRIPTOR + VALUE = ; +``` + +The second form is: + +```sql +EXEC SQL [FOR ] SET DESCRIPTOR + COUNT = integer; +``` + +Where: + +- `array_size` is an integer value or a host variable that contains an integer value specifying the number of rows to fetch. If you omit the `FOR` clause, the statement executes once for each member of the array. +- `descriptor_name` specifies the name of a descriptor as a single-quoted string literal or a host variable that contains the name of a descriptor. + +Include the `VALUE` clause to describe the information stored in the descriptor. + +- `column_number` identifies the position of the variable within the descriptor. +- `descriptor_item` specifies the type of the descriptor item. +- `host_variable` specifies the name of the host variable that contains the value of the item. + +ECPGPlus implements the following `descriptor_item` types: + +- `TYPE` +- `LENGTH` +- `[REF] INDICATOR` +- `[REF] DATA` +- `[REF] RETURNED LENGTH` + +For example, a client application might prompt a user for a dynamically created query: + +```c +query_text = promptUser("Enter a query"); +``` + +To execute a dynamically created query, you must first prepare the query (parsing and validating the syntax of the query) and then describe the input parameters found in the query using the `EXEC SQL DESCRIBE INPUT` statement. + +```sql +EXEC SQL ALLOCATE DESCRIPTOR query_params; +EXEC SQL PREPARE emp_query FROM :query_text; + +EXEC SQL DESCRIBE INPUT emp_query + USING SQL DESCRIPTOR 'query_params'; +``` + +After describing the query, the `query_params` descriptor contains information about each parameter required by the query. + +For this example, assume that the user entered: + +```sql +SELECT ename FROM emp WHERE sal > ? AND job = ?;, +``` + +In this case, the descriptor describes two parameters, one for `sal > ?` and one for `job = ?`. + +To discover the number of parameter markers (question marks) in the query and therefore the number of values you must provide before executing the query, use: + +```sql +EXEC SQL GET DESCRIPTOR … :host_variable = COUNT; +``` + +Then, you can use `EXEC SQL GET DESCRIPTOR` to retrieve the name of each parameter. You can also use `EXEC SQL GET DESCRIPTOR` to retrieve the type of each parameter from the descriptor, along with the number of parameters. Or you can supply each `value` in the form of a character string and ECPG converts that string into the required data type. + +The data type of the first parameter is `numeric`. The type of the second parameter is `varchar`. The name of the first parameter is `sal`. The name of the second parameter is `job`. + +Next, loop through each parameter, prompting the user for a value, and store those values in host variables. You can use `GET DESCRIPTOR … COUNT` to find the number of parameters in the query. + +```sql +EXEC SQL GET DESCRIPTOR 'query_params' + :param_count = COUNT; + +for(param_number = 1; + param_number <= param_count; + param_number++) +{ +``` + +Use `GET DESCRIPTOR` to copy the name of the parameter into the `param_name` host variable: + +```sql +EXEC SQL GET DESCRIPTOR 'query_params' + VALUE :param_number :param_name = NAME; + +reply = promptUser(param_name); +if (reply == NULL) + reply_ind = 1; /* NULL */ +else + reply_ind = 0; /* NOT NULL */ +``` + +To associate a `value` with each parameter, you use the `EXEC SQL SET DESCRIPTOR` statement. For example: + +```sql +EXEC SQL SET DESCRIPTOR 'query_params' + VALUE :param_number DATA = :reply; +EXEC SQL SET DESCRIPTOR 'query_params' + VALUE :param_number INDICATOR = :reply_ind; +} +``` + +Now, you can use the `EXEC SQL EXECUTE DESCRIPTOR` statement to execute the prepared statement on the server. + +### UPDATE + +Use an `UPDATE` statement to modify the data stored in a table. The syntax is: + +```sql +EXEC SQL [AT ][FOR ] + UPDATE [ ONLY ] table [ [ AS ] alias ] + SET {column = { expression | DEFAULT } | + (column [, ...]) = ({ expression|DEFAULT } [, ...])} [, ...] + [ FROM from_list ] + [ WHERE condition | WHERE CURRENT OF cursor_name ] + [ RETURNING * | output_expression [[ AS ] output_name] [, ...] ] +``` + +Where `database_name` is the name of the database or host variable that contains the name of the database in which the table resides. This value can take the form of an unquoted string literal or of a host variable. + +Include the `FOR exec_count` clause to specify the number of times the statement executes. This clause is valid only if the `SET` or `WHERE` clause contains an array. + +ECPGPlus provides support for the additional clauses of the SQL `UPDATE` statement as documented in the [PostgreSQL core documentation](https://www.postgresql.org/docs/current/static/sql-update.html). + +You can use a host variable in any clause that specifies a value. To use a host variable, substitute a defined variable for any value associated with any of the documented `UPDATE` clauses. + +The following `UPDATE` statement changes the job description of an employee (identified by the `:ename` host variable) to the value contained in the `:new_job` host variable. It increases the employees salary by multiplying the current salary by the value in the `:increase` host variable: + +```sql +EXEC SQL UPDATE emp + SET job = :new_job, sal = sal * :increase + WHERE ename = :ename; +``` + +The enhanced `UPDATE` statement also allows you to include parameter markers (question marks) in any clause where an input value is permitted. For example, we can write the same update statement with a parameter marker in the `WHERE` clause: + +```sql +EXEC SQL UPDATE emp + SET job = ?, sal = sal * ? + WHERE ename = :ename; +``` + +This `UPDATE` statement allows you to prompt the user for a new value for the `job` column and provide the amount by which the `sal` column is incremented for the employee specified by `:ename`. + +### WHENEVER + +Use the `WHENEVER` statement to specify the action taken by a client application when it encounters an SQL error or warning. The syntax is: + +```sql +EXEC SQL WHENEVER ; +``` + +The following table describes the different conditions that might trigger an `action`. + +| Condition | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `NOT FOUND` | The server returns a `NOT FOUND` condition when it encounters a `SELECT` that returns no rows or when a `FETCH` reaches the end of a result set. | +| `SQLERROR` | The server returns an `SQLERROR` condition when it encounters a serious error returned by an SQL statement. | +| `SQLWARNING` | The server returns an `SQLWARNING` condition when it encounters a nonfatal warning returned by an SQL statement. | + +The following table describes the actions that result from a client encountering a `condition`. + +| Action | Description | +| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `CALL function [([args])]` | Call the named `function`. | +| `CONTINUE` | Proceed to the next statement. | +| `DO BREAK` | Emit a C break statement. A break statement can appear in a `loop` or a `switch` statement. If executed, the break statement terminates the `loop` or the `switch` statement. | +| `DO CONTINUE` | Emit a C `continue` statement. A `continue` statement can exist only in a loop. If executed, it causes the flow of control to return to the top of the loop. | +| `DO function ([args])` | Call the named `function`. | +| `GOTO label` or `GO TO label` | Proceed to the statement that contains the label. | +| `SQLPRINT` | Print a message to standard error. | +| `STOP` | Stop executing. | + +The following code fragment prints a message if the client application encounters a warning and aborts the application if it encounters an error: + +```sql +EXEC SQL WHENEVER SQLWARNING SQLPRINT; +EXEC SQL WHENEVER SQLERROR STOP; +``` + +Include the following code to specify for a client to continue processing after warning a user of a problem: + +```sql +EXEC SQL WHENEVER SQLWARNING SQLPRINT; +``` + +Include the following code to call a function if a query returns no rows or when a cursor reaches the end of a result set: + +```sql +EXEC SQL WHENEVER NOT FOUND CALL error_handler(__LINE__); +``` diff --git a/product_docs/docs/epas/15/ecpgplus_guide/images/ecpg_path.png b/product_docs/docs/epas/15/ecpgplus_guide/images/ecpg_path.png new file mode 100755 index 00000000000..c08335bc0f8 --- /dev/null +++ b/product_docs/docs/epas/15/ecpgplus_guide/images/ecpg_path.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:848c6389145c5062fe2fac5b6235b381616c6b8a99311de5ee91e09b036ea205 +size 73046 diff --git a/product_docs/docs/edb_plus/37/images/edb_logo.png b/product_docs/docs/epas/15/ecpgplus_guide/images/edb_logo.png similarity index 100% rename from product_docs/docs/edb_plus/37/images/edb_logo.png rename to product_docs/docs/epas/15/ecpgplus_guide/images/edb_logo.png diff --git a/product_docs/docs/edb_plus/37/images/edb_logo.svg b/product_docs/docs/epas/15/ecpgplus_guide/images/edb_logo.svg similarity index 100% rename from product_docs/docs/edb_plus/37/images/edb_logo.svg rename to product_docs/docs/epas/15/ecpgplus_guide/images/edb_logo.svg diff --git a/product_docs/docs/epas/15/ecpgplus_guide/index.mdx b/product_docs/docs/epas/15/ecpgplus_guide/index.mdx new file mode 100644 index 00000000000..a383eec5fc8 --- /dev/null +++ b/product_docs/docs/epas/15/ecpgplus_guide/index.mdx @@ -0,0 +1,27 @@ +--- +navTitle: ECPGPlus +title: "ECPGPlus" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/toc.html" +--- + +EDB enhanced ECPG (the PostgreSQL precompiler) to create ECPGPlus. ECPGPlus allows you to include Pro\*C-compatible embedded SQL commands in C applications when connected to an EDB Postgres Advanced Server database. When you use ECPGPlus to compile an application, the SQL code syntax is checked and translated into C. + +ECPGPlus supports: + +- Oracle Dynamic SQL – Method 4 (ODS-M4) +- Pro\*C-compatible anonymous blocks +- A `CALL` statement compatible with Oracle databases + +As part of ECPGPlus's Pro\*C compatibility, you don't need to include the `BEGIN DECLARE SECTION` and `END DECLARE SECTION` directives. + +## PostgreSQL compatibility + +While most ECPGPlus statements work with community PostgreSQL, the `CALL` statement and the `EXECUTE…END EXEC` statement work only when the client application is connected to EDB Postgres Advanced Server. + +
+ +introduction overview using_embedded_sql using_descriptors building_executing_dynamic_sql_statements error_handling reference conclusion + +
diff --git a/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/E.ico b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/E.ico new file mode 100644 index 00000000000..7be2392833c --- /dev/null +++ b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/E.ico @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:890b83da8580893248e6ac1b36033fea0969ddeb650bb37d3dd4bd5e6b716a63 +size 6465 diff --git a/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/EDB_logo.png b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/EDB_logo.png new file mode 100644 index 00000000000..9fb5e3972a4 --- /dev/null +++ b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/EDB_logo.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:908368bfc5ecd7deb52f203fe0d43b410f1ea2dfabc18115a316663c37d361e9 +size 12379 diff --git a/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/connect_to_epas_server.png b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/connect_to_epas_server.png new file mode 100644 index 00000000000..b5e54a2e55e --- /dev/null +++ b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/connect_to_epas_server.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:648d21b50f4a3ec37a2edd95d6ab853dfa80b2345fd004c1f3480b2d2bf692f1 +size 88067 diff --git a/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/edb_logo.svg b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/edb_logo.svg new file mode 100644 index 00000000000..400b5547ef3 --- /dev/null +++ b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/edb_logo.svg @@ -0,0 +1,18 @@ + + edb-logo-disc-dark-2 + + + + diff --git a/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/edb_pgadmin4_first_look.png b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/edb_pgadmin4_first_look.png new file mode 100755 index 00000000000..8aad2a70e56 --- /dev/null +++ b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/edb_pgadmin4_first_look.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9201126dc356e396eb07869e4e30d441d81e3e81c9176117fbcef61eab057863 +size 235286 diff --git a/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/pgadmin4_from_applications_menu.png b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/pgadmin4_from_applications_menu.png new file mode 100644 index 00000000000..0aa5f50f062 --- /dev/null +++ b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/pgadmin4_from_applications_menu.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:69006ea7125cfe9f27ed9774e5aa7965394bfb4d657b97a97ac890a14e30e695 +size 63593 diff --git a/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/server_general.png b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/server_general.png new file mode 100755 index 00000000000..ffaf97e7c8f --- /dev/null +++ b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/images/server_general.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c44b464e549592db99d1faf3775af79da683ae6ade216d5f40da26ac21dfbadf +size 54040 diff --git a/product_docs/docs/epas/15/edb_pgadmin_linux_qs/index.mdx b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/index.mdx new file mode 100644 index 00000000000..01b024e8239 --- /dev/null +++ b/product_docs/docs/epas/15/edb_pgadmin_linux_qs/index.mdx @@ -0,0 +1,84 @@ +--- +title: "EDB pgAdmin4 Quick Start Linux" + +redirects: + - /epas/14/epas_inst_linux/06_installing_and_configuring_pgadmin4/ +--- + +pgAdmin 4 is the leading open source management tool for Postgres databases. EDB pgAdmin 4 is distributed by EDB along with EDB Postgres Advanced Server databases. It's designed to meet the needs of both novice and experienced Postgres users, providing a powerful graphical interface that simplifies creating, maintaining, and using database objects. + +You can install EDB pgAdmin 4 for your EDB Postgres Advanced Server databases using yum package manager for RHEL/CentOS 7.x or 8.x platforms. + +## Installing EDB pgAdmin 4 on a Linux host + +Use the yum package manager to install EDB pgAdmin4. + +### Create a repository configuration file + +Create the respository configuration file if it doesn't already exist. + +To create a repository configuration file, you need the credentials that allow access to the EDB repository. For information about requesting credentials, see [EDB Repository Access](https://info.enterprisedb.com/rs/069-ALB-339/images/Repository%20Access%2004-09-2019.pdf). + +To create the repository configuration file, assume superuser privileges and invoke the following command: + +```shell +yum -y install https://yum.enterprisedb.com/edb-repo-rpms/edb-repo-latest.noarch.rpm +``` + +The repository configuration file is named `edb.repo`. The file resides in `/etc/yum.repos.d.` After creating the `edb.repo` file, use the following command to replace the `USERNAME` and `PASSWORD` placeholders in the baseurl specification with the username and password of a registered EDB user: + +```shell +sed -i "s@:@USERNAME:PASSWORD@" /etc/yum.repos.d/edb.repo +``` + +### Install EPEL repository + +For CentOS 7.x, use the following command: + +```shell +yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm +``` + +!!! Note + To install EPEL repository on CentOS/RHEL 7.x and 8.x see the platform specific steps at [EDB Website](https://repos.enterprisedb.com/). + +### Install EDB pgAdmin 4 + +After creating the repository configuration file and adding a username and password to the `edb.repo` file, you can install `edb-pgadmin4`. To install `edb-pgadmin4`, assume superuser privileges and invoke the following command: + +```shell +yum install edb-pgadmin4* +``` + + +This command installs following packages: + +- `edb-pgadmin4` +- `edb-pgadmin4-desktop-common` +- `edb-pgadmin4-desktop-gnome` +- `edb-pgadmin4-docs` +- `edb-pgadmin4-web` + +### Starting pgAdmin 4 in desktop mode + +Use the following command to start pgAdmin 4 in desktop mode: + +```shell +/usr/edb/pgadmin4/bin/pgAdmin4 +``` + +You can also use the link on the **Applications** menu to start pgAdmin 4 in desktop mode: + +![Accessing pgAdmin 4 from Applications Menu.](images/pgadmin4_from_applications_menu.png) + + + +### Registering and connecting to EDB Postgres Advanced Server with pgAdmin 4 + +Before managing an EDB Postgres Advanced Server cluster, you must register the server. To register the server, use the fields on the Server dialog box to specify the connection properties. To open the Server dialog box, right-click the Servers node in the tree, and select **Create > Server**. + +For detailed information about registering your server, see the [pgAdmin documentation](https://www.pgadmin.org/docs/pgadmin4/latest/server_dialog.html). + +Then, to connect to your EDB Postgres Advanced Server instance, right-click the server name and select **Connect Server**. Provide your password in the Connect to Server dialog box. + +After you connect to the server, you can see the **Dashboard** tab. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/01_package_components.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/01_package_components.mdx new file mode 100644 index 00000000000..bf3ded91f27 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/01_package_components.mdx @@ -0,0 +1,382 @@ +--- +title: "Package components" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.06.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.184.html" +--- + +Packages consist of two main components: + +- The package specification, which is the public interface. You can reference these elements outside the package. Declare all database objects that are a part of a package in the specification. +- Th package body, which contains the actual implementation of all the database objects declared in the package specification. + + The package body implements the specifications in the package specification. It contains implementation details and private declarations that are invisible to the application. You can debug, enhance, or replace a package body without changing the specifications. Similarly, you can change the body without recompiling the calling programs because the implementation details are invisible to the application. + +## Package specification syntax + +The package specification defines the user interface for a package (the API). The specification lists the functions, procedures, types, exceptions, and cursors that are visible to a user of the package. + +The syntax used to define the interface for a package is: + +```sql +CREATE [ OR REPLACE ] PACKAGE + [ ] + { IS | AS } + [ ; ] ... + [ ] ... +END [ ] ; +``` + +Where `authorization_clause` := + +```sql +{ AUTHID DEFINER } | { AUTHID CURRENT_USER } +``` + +Where `procedure_or_function_declaration` := + +```text +procedure_declaration | function_declaration +``` + +Where `procedure_declaration` := + +```sql +PROCEDURE proc_name [ argument_list ]; +[ restriction_pragma; ] +``` + +Where `function_declaration` := + +```sql +FUNCTION func_name [ argument_list ] + RETURN rettype [ DETERMINISTIC ]; +[ restriction_pragma; ] +``` + +Where `argument_list` := + +```text +( argument_declaration [, ...] ) +``` + +Where `argument_declaration` := + +```text +argname [ IN | IN OUT | OUT ] argtype [ DEFAULT value ] +``` + +Where `restriction_pragma` := + +```sql +PRAGMA RESTRICT_REFERENCES(name, restrictions) +``` + +Where `restrictions` := + +```text +restriction [, ... ] +``` + +### Parameters + +`package_name` + + `package_name` is an identifier assigned to the package. Each package must have a unique name in the schema. + +`AUTHID DEFINER` + + If you omit the `AUTHID` clause or specify `AUTHID DEFINER`, the privileges of the package owner are used to determine access privileges to database objects. + +`AUTHID CURRENT_USER` + + If you specify `AUTHID CURRENT_USER`, the privileges of the current user executing a program in the package are used to determine access privileges. + +`declaration` + + `declaration` is an identifier of a public variable. You can access a public variable from outside the package using the syntax `package_name.variable`. There can be zero, one, or more public variables. Public variable definitions must come before procedure or function declarations. + + `declaration` can be any of the following: + +- Variable declaration +- Record declaration +- Collection declaration +- `REF CURSOR` and cursor variable declaration +- `TYPE` definitions for records, ollections, and `REF CURSOR` +- Exception +- Object variable declaration + +`proc_name` + + The name of a public procedure. + +`argname` + + The name of an argument. The argument is referenced by this name in the function or procedure body. + +`IN` | `IN OUT` | `OUT` + + The argument mode. `IN` (the default) declares the argument for input only. `IN OUT` allows the argument to receive a value as well as return a value. `OUT` specifies the argument is for output only. + +`argtype` + + The data types of an argument. An argument type can be a base data type, a copy of the type of an existing column using `%TYPE`, or a user-defined type such as a nested table or an object type. Don't specify a length for any base type. For example, specify `VARCHAR2`, not `VARCHAR2(10)`. + + Reference the type of a column by writing `tablename.columnname %TYPE`. Using this nomenclature can sometimes help make a procedure independent from changes to the definition of a table. + +`DEFAULT value` + + The `DEFAULT` clause supplies a default value for an input argument if you don't supply one in the invocation. You can't specify `DEFAULT` for arguments with modes `IN OUT` or `OUT`. + +`func_name` + + The name of a public function. + +`rettype` + + The return data type. + +`DETERMINISTIC` + + `DETERMINISTIC` is a synonym for `IMMUTABLE`. A `DETERMINISTIC` function can't modify the database and always reaches the same result when given the same argument values. It doesn't do database lookups or otherwise use information not directly present in its argument list. If you include this clause, any call of the function with all-constant arguments can be immediately replaced with the function value. + +`restriction` + + The following keywords are accepted for compatibility and ignored: + + `RNDS` + + `RNPS` + + `TRUST` + + `WNDS` + + `WNPS` + +## Package body syntax + +Package implementation details reside in the package body. The package body can contain objects that aren't visible to the package user. EDB Postgres Advanced Server supports the following syntax for the package body: + +```sql +CREATE [ OR REPLACE ] PACKAGE BODY + { IS | AS } + [ ; ] ... + [ ] ... + [ ] +END [ ] ; +``` + +Where `procedure_or_function_definition` := + +```text +procedure_definition | function_definition +``` + +Where `procedure_definition` := + +```sql +PROCEDURE proc_name[ argument_list ] + [ options_list ] + { IS | AS } + procedure_body + END [ proc_name ] ; +``` + +Where `procedure_body` := + +```sql +[ PRAGMA AUTONOMOUS_TRANSACTION; ] +[ declaration; ] [, ...] +BEGIN + statement; [...] +[ EXCEPTION + { WHEN exception [OR exception] [...]] THEN statement; } + [...] +] +``` + +Where `function_definition` := + +```sql +FUNCTION func_name [ argument_list ] + RETURN rettype [ DETERMINISTIC ] + [ options_list ] + { IS | AS } + function_body + END [ func_name ] ; +``` + +Where `function_body` := + +```sql +[ PRAGMA AUTONOMOUS_TRANSACTION; ] +[ declaration; ] [, ...] +BEGIN + statement; [...] +[ EXCEPTION + { WHEN exception [ OR exception ] [...] THEN statement; } + [...] +] +``` + +Where `argument_list` := + +```text +( argument_declaration [, ...] ) +``` + +Where `argument_declaration` := + +```text +argname [ IN | IN OUT | OUT ] argtype [ DEFAULT value ] +``` + +Where `options_list` := + +```text +option [ ... ] +``` + +Where `option` := + +```sql +STRICT +LEAKPROOF +PARALLEL { UNSAFE | RESTRICTED | SAFE } +COST execution_cost +ROWS result_rows +SET config_param { TO value | = value | FROM CURRENT } +``` + +Where `package_initializer` := + +```sql +BEGIN + statement; [...] +END; +``` + +### Parameters + +`package_name` + + `package_name` is the name of the package for which this is the package body. An package specification with this name must already exist. + +`private_declaration` + + `private_declaration` is an identifier of a private variable that any procedure or function can access in the package. There can be zero, one, or more private variables. `private_declaration` can be any of the following: + +- Variable declaration +- Record declaration +- Collection declaration +- `REF CURSOR` and cursor variable declaration +- `TYPE` definitions for records, collections, and `REF CURSORs` +- Exception +- Object variable declaration + +`proc_name` + + The name of the procedure being created. + +`PRAGMA AUTONOMOUS_TRANSACTION` + + `PRAGMA AUTONOMOUS_TRANSACTION` is the directive that sets the procedure as an autonomous transaction. + +`declaration` + + A variable, type, `REF CURSOR`, or subprogram declaration. If you include subprogram declarations, declare them after all other variable, type, and `REF CURSOR` declarations. + +`statement` + + An SPL program statement. A `DECLARE - BEGIN - END` block is considered an SPL statement unto itself. Thus, the function body can contain nested blocks. + +`exception` + + An exception condition name such as `NO_DATA_FOUND, OTHERS`. + +`func_name` + + The name of the function being created. + +`rettype` + + The return data type, which can be any of the types listed for `argtype`. As for `argtype`, don't specify a length for `rettype`. + +`DETERMINISTIC` + + Include `DETERMINISTIC` to specify for the function to always return the same result when given the same argument values. A `DETERMINISTIC` function must not modify the database. + + !!! Note + The `DETERMINISTIC` keyword is equivalent to the PostgreSQL `IMMUTABLE` option. + + !!!Note + If `DETERMINISTIC` is specified for a public function in the package body, you must also specify it for the function declaration in the package specification. For private functions, there's no function declaration in the package specification. + +`PRAGMA AUTONOMOUS_TRANSACTION` + + `PRAGMA AUTONOMOUS_TRANSACTION` is the directive that sets the function as an autonomous transaction. + +`argname` + + The name of a formal argument. The argument is referenced by this name in the procedure body. + +`IN` | `IN OUT` | `OUT` + + The argument mode. `IN` (the default) declares the argument for input only. `IN OUT` allows the argument to receive a value as well as return a value. `OUT` specifies the argument is for output only. + +`argtype` + + The data types of an argument. An argument type can be a base data type, a copy of the type of an existing column using `%TYPE`, or a user-defined type such as a nested table or an object type. Don't specify a length for any base type. For example, specify `VARCHAR2`, not `VARCHAR2(10)`. + + Reference the type of a column by writing `tablename.columnname%TYPE`. Using this nomenclature can sometimes help make a procedure independent from changes to the definition of a table. + +`DEFAULT value` + + The `DEFAULT` clause supplies a default value for an input argument if you don't supply one in the procedure call. Don't specify `DEFAULT` for arguments with modes `IN OUT` or `OUT`. + +The following options aren't compatible with Oracle databases. They're extensions to Oracle package syntax provided only by EDB Postgres Advanced Server. + +`STRICT` + + The `STRICT` keyword specifies for the function not to execute if called with a `NULL` argument. Instead the function returns `NULL`. + +`LEAKPROOF` + + The `LEAKPROOF` keyword specifies for the function not to reveal any information about arguments other than through a return value. + +`PARALLEL { UNSAFE | RESTRICTED | SAFE }` + + The `PARALLEL` clause enables the use of parallel sequential scans (parallel mode). A parallel sequential scan uses multiple workers to scan a relation in parallel during a query in contrast to a serial sequential scan. + + When set to `UNSAFE`, the procedure or function can't be executed in parallel mode. The presence of such a procedure or function forces a serial execution plan. This is the default setting if you omit the `PARALLEL` clause. + + When set to `RESTRICTED`, the procedure or function can be executed in parallel mode, but the execution is restricted to the parallel group leader. If the qualification for any particular relation has anything that is parallel restricted, that relation won't be chosen for parallelism. + + When set to `SAFE`, the procedure or function can be executed in parallel mode without restriction. + +`execution_cost` + + `execution_cost` specifies a positive number giving the estimated execution cost for the function, in units of `cpu_operator_cost`. If the function returns a set, this is the cost per returned row. The default is `0.0025`. + +`result_rows` + + `result_rows` is the estimated number of rows for the query planner to expect the function to return. The default is `1000`. + +`SET` + + Use the `SET` clause to specify a parameter value for the duration of the function: + + `config_param` specifies the parameter name. + + `value` specifies the parameter value. + + `FROM CURRENT` guarantees that the parameter value is restored when the function ends. + +`package_initializer` + + The statements in the `package_initializer` are executed once per user session when the package is first referenced. + +!!! Note + The `STRICT`, `LEAKPROOF`, `PARALLEL`, `COST`, `ROWS` and `SET` keywords provide extended functionality for EDB Postgres Advanced Server. Oracle doesn't support them. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/01a_display_packages.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/01a_display_packages.mdx new file mode 100644 index 00000000000..005b7b6a3cb --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/01a_display_packages.mdx @@ -0,0 +1,138 @@ +--- +title: "View package and package body definition" +--- + +You can view the package specification and package body definition using the psql meta-commands `\sps` and `\spb`, respectively. + +## Synopsis + +```sql +\sps[+] []. +\spb[+] []. +``` + +### Examples + +Create a package and a package body `test_pkg` in the `public` schema: + +```sql +edb=# CREATE OR REPLACE PACKAGE public.test_pkg IS +edb$# emp_name character varying(10); +edb$# PROCEDURE get_name(IN p_empno numeric); +edb$# FUNCTION display_counter() RETURN integer; +edb$# END; +CREATE PACKAGE +edb=# +edb=# CREATE OR REPLACE PACKAGE BODY public.test_pkg IS +edb$# v_counter integer; +edb$# +edb$# PROCEDURE get_name(IN p_empno numeric) IS +edb$# BEGIN +edb$# SELECT ename INTO emp_name FROM emp WHERE empno = p_empno; +edb$# v_counter := v_counter + 1; +edb$# END; +edb$# +edb$# FUNCTION display_counter() RETURN integer IS +edb$# BEGIN +edb$# RETURN v_counter; +edb$# END; +edb$# BEGIN +edb$# v_counter := 0; +edb$# DBMS_OUTPUT.PUT_LINE('Initialized counter'); +edb$# END; +CREATE PACKAGE BODY +edb=# +``` + +Use `\sps` and `\spb` commands to view the definition of package and package body: + +``` sql +edb=# \sps test_pkg +CREATE OR REPLACE PACKAGE public.test_pkg IS +emp_name character varying(10); +PROCEDURE get_name(IN p_empno numeric); +FUNCTION display_counter() RETURN integer; +END +edb=# +edb=# \sps+ test_pkg +1 CREATE OR REPLACE PACKAGE public.test_pkg IS +2 emp_name character varying(10); +3 PROCEDURE get_name(INOUT p_empno numeric); +4 FUNCTION display_counter(OUT p1 numeric, OUT p2 numeric) RETURN integer; +5 END + +edb=# \sps public.test_pkg +CREATE OR REPLACE PACKAGE public.test_pkg IS +emp_name character varying(10); +PROCEDURE get_name(INOUT p_empno numeric); +FUNCTION display_counter(OUT p1 numeric, OUT p2 numeric) RETURN integer; +END + +edb=# \sps+ public.test_pkg +1 CREATE OR REPLACE PACKAGE public.test_pkg IS +2 emp_name character varying(10); +3 PROCEDURE get_name(INOUT p_empno numeric); +4 FUNCTION display_counter(OUT p1 numeric, OUT p2 numeric) RETURN integer; +5 END + +edb=# \spb test_pkg +CREATE OR REPLACE PACKAGE BODY public.test_pkg IS +v_counter integer; + +PROCEDURE get_name(IN p_empno numeric) IS +BEGIN +SELECT ename INTO emp_name FROM emp WHERE empno = p_empno; +v_counter := v_counter + 1; +END; + +FUNCTION display_counter() RETURN integer IS +BEGIN +RETURN v_counter; +END; +BEGIN +v_counter := 0; +DBMS_OUTPUT.PUT_LINE('Initialized counter'); +END +edb=# +``` + +You can also view the definition of individual functions and procedures using the `\sf` command. + +### Examples + +Create the function and procedure: + +```sql +edb=# CREATE OR REPLACE FUNCTION public.func1() +edb-# RETURNS integer +edb-# LANGUAGE edbspl +edb-# SECURITY DEFINER +edb-# AS $function$ begin return 10; end$function$; +CREATE FUNCTION +edb=# +edb=# CREATE OR REPLACE PROCEDURE public.proc1() +edb-# SECURITY DEFINER +edb-# AS $procedure$ begin null; end$procedure$ +edb-# LANGUAGE edbspl; +CREATE PROCEDURE +edb=# +``` + +Use the `\sf ` command to view the definition: + +```sql +edb=# \sf func1 +CREATE OR REPLACE FUNCTION public.func1() + RETURNS integer + LANGUAGE edbspl + SECURITY DEFINER +AS $function$ begin return 10; end$function$ +edb=# +edb=# \sf proc1 +CREATE OR REPLACE PROCEDURE public.proc1() + SECURITY DEFINER +AS $procedure$ begin null; end$procedure$ + LANGUAGE edbspl +edb=# +``` + diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/02_creating_packages.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/02_creating_packages.mdx new file mode 100644 index 00000000000..66127d88219 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/02_creating_packages.mdx @@ -0,0 +1,136 @@ +--- +title: "Creating packages" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.07.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.185.html" +--- + +A package isn't an executable piece of code but a repository of code. When you use a package, you execute or make reference to an element within a package. + +## Creating the package specification + +The package specification contains the definition of all the elements in the package that you can reference from outside of the package. These are called the public elements of the package, and they act as the package interface. The following code sample is a package specification: + +```sql +-- +-- Package specification for the 'emp_admin' package. +-- +CREATE OR REPLACE PACKAGE emp_admin +IS + FUNCTION get_dept_name ( + p_deptno NUMBER DEFAULT 10 + ) + RETURN VARCHAR2; + FUNCTION update_emp_sal ( + p_empno NUMBER, + p_raise NUMBER + ) + RETURN NUMBER; + PROCEDURE hire_emp ( + p_empno NUMBER, + p_ename VARCHAR2, + p_job VARCHAR2, + p_sal NUMBER, + p_hiredate DATE DEFAULT sysdate, + p_comm NUMBER DEFAULT 0, + p_mgr NUMBER, + p_deptno NUMBER DEFAULT 10 + ); + PROCEDURE fire_emp ( + p_empno NUMBER + ); +END emp_admin; +``` + +This code sample creates the `emp_admin` package specification. This package specification consists of two functions and two stored procedures. You can also add the `OR REPLACE` clause to the `CREATE PACKAGE` statement for convenience. + +## Creating the package body + +The body of the package contains the actual implementation behind the package specification. For the `emp_admin` package specification in the example, this code now create a package body that implements the specifications. The body contains the implementation of the functions and stored procedures in the specification. + +```sql +-- +-- Package body for the 'emp_admin' package. +-- +CREATE OR REPLACE PACKAGE BODY emp_admin +IS + -- + -- Function that queries the 'dept' table based on the department + -- number and returns the corresponding department name. + -- + FUNCTION get_dept_name ( + p_deptno IN NUMBER DEFAULT 10 + ) + RETURN VARCHAR2 + IS + v_dname VARCHAR2(14); + BEGIN + SELECT dname INTO v_dname FROM dept WHERE deptno = p_deptno; + RETURN v_dname; + EXCEPTION + WHEN NO_DATA_FOUND THEN + DBMS_OUTPUT.PUT_LINE('Invalid department number ' || p_deptno); + RETURN ''; + END; + -- + -- Function that updates an employee's salary based on the + -- employee number and salary increment/decrement passed + -- as IN parameters. Upon successful completion the function + -- returns the new updated salary. + -- + FUNCTION update_emp_sal ( + p_empno IN NUMBER, + p_raise IN NUMBER + ) + RETURN NUMBER + IS + v_sal NUMBER := 0; + BEGIN + SELECT sal INTO v_sal FROM emp WHERE empno = p_empno; + v_sal := v_sal + p_raise; + UPDATE emp SET sal = v_sal WHERE empno = p_empno; + RETURN v_sal; + EXCEPTION + WHEN NO_DATA_FOUND THEN + DBMS_OUTPUT.PUT_LINE('Employee ' || p_empno || ' not found'); + RETURN -1; + WHEN OTHERS THEN + DBMS_OUTPUT.PUT_LINE('The following is SQLERRM:'); + DBMS_OUTPUT.PUT_LINE(SQLERRM); + DBMS_OUTPUT.PUT_LINE('The following is SQLCODE:'); + DBMS_OUTPUT.PUT_LINE(SQLCODE); + RETURN -1; + END; + -- + -- Procedure that inserts a new employee record into the 'emp' table. + -- + PROCEDURE hire_emp ( + p_empno NUMBER, + p_ename VARCHAR2, + p_job VARCHAR2, + p_sal NUMBER, + p_hiredate DATE DEFAULT sysdate, + p_comm NUMBER DEFAULT 0, + p_mgr NUMBER, + p_deptno NUMBER DEFAULT 10 + ) + AS + BEGIN + INSERT INTO emp(empno, ename, job, sal, hiredate, comm, mgr, deptno) + VALUES(p_empno, p_ename, p_job, p_sal, + p_hiredate, p_comm, p_mgr, p_deptno); + END; + -- + -- Procedure that deletes an employee record from the 'emp' table based + -- on the employee number. + -- + PROCEDURE fire_emp ( + p_empno NUMBER + ) + AS + BEGIN + DELETE FROM emp WHERE empno = p_empno; + END; +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/03_referencing_a_package.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/03_referencing_a_package.mdx new file mode 100644 index 00000000000..1dc8c143cc5 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/03_referencing_a_package.mdx @@ -0,0 +1,23 @@ +--- +title: "Referencing a package" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.08.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.186.html" +--- + +To reference the types, items, and subprograms that are declared in a package specification, use the dot notation. For example: + +`package_name.type_name` + +`package_name.item_name` + +`package_name.subprogram_name` + +To invoke a function from the `emp_admin` package specification, execute the following SQL command: + +```sql +SELECT emp_admin.get_dept_name(10) FROM DUAL; +``` + +This example invokes the `get_dept_name` function declared in the package `emp_admin`. It passes the department number as an argument to the function, which returns the name of the department. The value returned is `ACCOUNTING`, which corresponds to department number `10`. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/04_using_packages_with_user_defined_types.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/04_using_packages_with_user_defined_types.mdx new file mode 100644 index 00000000000..856a60822d3 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/04_using_packages_with_user_defined_types.mdx @@ -0,0 +1,184 @@ +--- +title: "Using packages with user-defined types" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.09.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.187.html" +--- + +This example incorporates various user-defined types in the context of a package. + +The package specification of `emp_rpt` shows the declaration of a record type `emprec_typ` and a weakly typed `REF CURSOR, emp_refcur` as publicly accessible. It also shows two functions and two procedures. The function, `open_emp_by_dept`, returns the `REF CURSOR` type `EMP_REFCUR`. Procedures `fetch_emp` and `close_refcur` both declare a weakly typed `REF CURSOR` as a formal parameter. + +```sql +CREATE OR REPLACE PACKAGE emp_rpt +IS + TYPE emprec_typ IS RECORD ( + empno NUMBER(4), + ename VARCHAR(10) + ); + TYPE emp_refcur IS REF CURSOR; + + FUNCTION get_dept_name ( + p_deptno IN NUMBER + ) RETURN VARCHAR2; + FUNCTION open_emp_by_dept ( + p_deptno IN emp.deptno%TYPE + ) RETURN EMP_REFCUR; + PROCEDURE fetch_emp ( + p_refcur IN OUT SYS_REFCURSOR + ); + PROCEDURE close_refcur ( + p_refcur IN OUT SYS_REFCURSOR + ); +END emp_rpt; +``` + +The package body shows the declaration of several private variables: a static cursor `dept_cur`, a table type `depttab_typ`, a table variable `t_dept`, an integer variable `t_dept_max`, and a record variable `r_emp`. + +```sql +CREATE OR REPLACE PACKAGE BODY emp_rpt +IS + CURSOR dept_cur IS SELECT * FROM dept; + TYPE depttab_typ IS TABLE of dept%ROWTYPE + INDEX BY BINARY_INTEGER; + t_dept DEPTTAB_TYP; + t_dept_max INTEGER := 1; + r_emp EMPREC_TYP; + + FUNCTION get_dept_name ( + p_deptno IN NUMBER + ) RETURN VARCHAR2 + IS + BEGIN + FOR i IN 1..t_dept_max LOOP + IF p_deptno = t_dept(i).deptno THEN + RETURN t_dept(i).dname; + END IF; + END LOOP; + RETURN 'Unknown'; + END; + + FUNCTION open_emp_by_dept( + p_deptno IN emp.deptno%TYPE + ) RETURN EMP_REFCUR + IS + emp_by_dept EMP_REFCUR; + BEGIN + OPEN emp_by_dept FOR SELECT empno, ename FROM emp + WHERE deptno = p_deptno; + RETURN emp_by_dept; + END; + + PROCEDURE fetch_emp ( + p_refcur IN OUT SYS_REFCURSOR + ) + IS + BEGIN + DBMS_OUTPUT.PUT_LINE('EMPNO ENAME'); + DBMS_OUTPUT.PUT_LINE('----- -------'); + LOOP + FETCH p_refcur INTO r_emp; + EXIT WHEN p_refcur%NOTFOUND; + DBMS_OUTPUT.PUT_LINE(r_emp.empno || ' ' || r_emp.ename); + END LOOP; + END; + + PROCEDURE close_refcur ( + p_refcur IN OUT SYS_REFCURSOR + ) + IS + BEGIN + CLOSE p_refcur; + END; +BEGIN + OPEN dept_cur; + LOOP + FETCH dept_cur INTO t_dept(t_dept_max); + EXIT WHEN dept_cur%NOTFOUND; + t_dept_max := t_dept_max + 1; + END LOOP; + CLOSE dept_cur; + t_dept_max := t_dept_max - 1; +END emp_rpt; +``` + +This package contains an initialization section that loads the private table variable `t_dept` using the private static cursor `dept_cur.t_dept`. `dept_cur.t_dept` serves as a department name lookup table in the function `get_dept_name`. + +The function `open_emp_by_dept` returns a `REF CURSOR` variable for a result set of employee numbers and names for a given department. This `REF CURSOR` variable can then be passed to the procedure `fetch_emp` to retrieve and list the individual rows of the result set. Finally, the procedure `close_refcur` can be used to close the `REF CURSOR` variable associated with this result set. + +The following anonymous block runs the package function and procedures. In the anonymous block's declaration section, note the declaration of cursor variable `v_emp_cur` using the package’s public `REF CURSOR` type, `EMP_REFCUR. v_emp_cur` contains the pointer to the result set that's passed between the package function and procedures. + +```sql +DECLARE + v_deptno dept.deptno%TYPE DEFAULT 30; + v_emp_cur emp_rpt.EMP_REFCUR; +BEGIN + v_emp_cur := emp_rpt.open_emp_by_dept(v_deptno); + DBMS_OUTPUT.PUT_LINE('EMPLOYEES IN DEPT #' || v_deptno || + ': ' || emp_rpt.get_dept_name(v_deptno)); + emp_rpt.fetch_emp(v_emp_cur); + DBMS_OUTPUT.PUT_LINE('**********************'); + DBMS_OUTPUT.PUT_LINE(v_emp_cur%ROWCOUNT || ' rows were retrieved'); + emp_rpt.close_refcur(v_emp_cur); +END; +``` + +The following is the result of this anonymous block: + +```sql +__OUTPUT__ +EMPLOYEES IN DEPT #30: SALES +EMPNO ENAME +----- ------- +7499 ALLEN +7521 WARD +7654 MARTIN +7698 BLAKE +7844 TURNER +7900 JAMES +********************** +6 rows were retrieved +``` + +The following anonymous block shows another way to achieve the same result. Instead of using the package procedures `fetch_emp` and `close_refcur`, the logic of these programs is coded directly into the anonymous block. In the anonymous block’s declaration section, note the addition of record variable `r_emp`, declared using the package’s public record type, `EMPREC_TYP`. + +```sql +DECLARE + v_deptno dept.deptno%TYPE DEFAULT 30; + v_emp_cur emp_rpt.EMP_REFCUR; + r_emp emp_rpt.EMPREC_TYP; +BEGIN + v_emp_cur := emp_rpt.open_emp_by_dept(v_deptno); + DBMS_OUTPUT.PUT_LINE('EMPLOYEES IN DEPT #' || v_deptno || + ': ' || emp_rpt.get_dept_name(v_deptno)); + DBMS_OUTPUT.PUT_LINE('EMPNO ENAME'); + DBMS_OUTPUT.PUT_LINE('----- -------'); + LOOP + FETCH v_emp_cur INTO r_emp; + EXIT WHEN v_emp_cur%NOTFOUND; + DBMS_OUTPUT.PUT_LINE(r_emp.empno || ' ' || + r_emp.ename); + END LOOP; + DBMS_OUTPUT.PUT_LINE('**********************'); + DBMS_OUTPUT.PUT_LINE(v_emp_cur%ROWCOUNT || ' rows were retrieved'); + CLOSE v_emp_cur; +END; +``` + +The following is the result of this anonymous block. + +```sql +__OUTPUT__ +EMPLOYEES IN DEPT #30: SALES +EMPNO ENAME +----- ------- +7499 ALLEN +7521 WARD +7654 MARTIN +7698 BLAKE +7844 TURNER +7900 JAMES +********************** +6 rows were retrieved +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/05_dropping_a_package.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/05_dropping_a_package.mdx new file mode 100644 index 00000000000..58e15476600 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/05_dropping_a_package.mdx @@ -0,0 +1,27 @@ +--- +title: "Dropping a package" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.10.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.188.html" +--- + +The syntax for deleting an entire package or the package body is: + +```sql +DROP PACKAGE [ BODY ] package_name; +``` + +If you omit the keyword `BODY`, both the package specification and the package body are deleted, that is, the entire package is dropped. If you specify the keyword `BODY`, then only the package body is dropped. The package specification remains intact. `package_name` is the identifier of the package to drop. + +The following statement destroys only the package body of `emp_admin`: + +```sql +DROP PACKAGE BODY emp_admin; +``` + +The following statement drops the entire `emp_admin` package: + +```sql +DROP PACKAGE emp_admin; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/index.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/index.mdx new file mode 100644 index 00000000000..2ba278e4f6e --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/02_packages/index.mdx @@ -0,0 +1,19 @@ +--- +title: "Packages" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.05.html" +--- + +A *package* is a named collection of functions, procedures, variables, cursors, user-defined record types, and records that are referenced using a common qualifier: the package identifier. Packages have the following characteristics: + +- They provide a convenient means of organizing the functions and procedures that perform a related purpose. Permission to use the package functions and procedures depends on one privilege granted to the entire package. You must reference all of the package programs with a common name. +- You can declare certain functions, procedures, variables, types, and so on in the package as *public*. Public entities are visible and other programs that are given `EXECUTE` privilege on the package can reference them. For public functions and procedures, only their signatures are visible: the program names, parameters, if any, and return types of functions. The SPL code of these functions and procedures isn't accessible to others. Therefore applications that use a package depend on only the information available in the signature and not in the procedural logic itself. +- You can declare other functions, procedures, variables, types, and so on in the package as *private*. Private entities can be referenced and used by function and procedures in the package but not by other external applications. Private entities are for use only by programs in the package. +- Function and procedure names can be overloaded in a package. You can define one or more functions/procedures with the same name but with different signatures. This capability enables you to create identically named programs that perform the same job but on different types of input. + +
+ +package_components creating_packages referencing_a_package using_packages_with_user_defined_types dropping_a_package + +
diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/01_dbms_alert.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/01_dbms_alert.mdx new file mode 100644 index 00000000000..770f5e8df15 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/01_dbms_alert.mdx @@ -0,0 +1,396 @@ +--- +title: "DBMS_ALERT" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.12.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.190.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.148.html" +--- + +The `DBMS_ALERT` package lets you register for, send, and receive alerts. The following table lists the supported procedures: + +| Function/procedure | Return type | Description | +| ----------------------------------------------------- | ----------- | --------------------------------------------------- | +| `REGISTER(name)` | n/a | Register to be able to receive alerts named `name`. | +| `REMOVE(name)` | n/a | Remove registration for the alert named `name`. | +| `REMOVEALL` | n/a | Remove registration for all alerts. | +| `SIGNAL(name, message)` | n/a | Signal the alert named `name` with `message`. | +| `WAITANY(name OUT, message OUT, status OUT, timeout)` | n/a | Wait for any registered alert to occur. | +| `WAITONE(name, message OUT, status OUT, timeout)` | n/a | Wait for the specified alert, `name`, to occur. | + +EDB Postgres Advanced Server's implementation of `DBMS_ALERT` is a partial implementation when compared to Oracle's version. Only those functions and procedures listed in the table are supported. + +EDB Postgres Advanced Server allows a maximum of 500 concurrent alerts. You can use the `dbms_alert.max_alerts` GUC variable, located in the `postgresql.conf` file, to specify the maximum number of concurrent alerts allowed on a system. + +To set a value for the `dbms_alert.max_alerts` variable, open the `postgresql.conf` file, which is located by default in `/opt/PostgresPlus/14AS/data`, with your choice of editor. Edit the `dbms_alert.max_alerts` parameter as shown: + +```ini +dbms_alert.max_alerts = alert_count +``` + +`alert_count` + +`alert_count` specifies the maximum number of concurrent alerts. By default, the value of `dbms_alert.max_alerts` is `100`. To disable this feature, set `dbms_alert.max_alerts` to `0`. + +For the `dbms_alert.max_alerts` GUC to function correctly, the `custom_variable_classes` parameter must contain `dbms_alerts`: + +```ini +custom_variable_classes = 'dbms_alert, …' +``` + +After editing the `postgresql.conf` file parameters, you must restart the server for the changes to take effect. + +## REGISTER + +The `REGISTER` procedure enables the current session to be notified of the specified alert. + +```sql +REGISTER( VARCHAR2) +``` + +### Parameters + +`name` + + Name of the alert to register. + +### Examples + +This anonymous block registers for an alert named `alert_test` and then waits for the signal. + +```sql +DECLARE + v_name VARCHAR2(30) := 'alert_test'; + v_msg VARCHAR2(80); + v_status INTEGER; + v_timeout NUMBER(3) := 120; +BEGIN + DBMS_ALERT.REGISTER(v_name); + DBMS_OUTPUT.PUT_LINE('Registered for alert ' || v_name); + DBMS_OUTPUT.PUT_LINE('Waiting for signal...'); + DBMS_ALERT.WAITONE(v_name,v_msg,v_status,v_timeout); + DBMS_OUTPUT.PUT_LINE('Alert name : ' || v_name); + DBMS_OUTPUT.PUT_LINE('Alert msg : ' || v_msg); + DBMS_OUTPUT.PUT_LINE('Alert status : ' || v_status); + DBMS_OUTPUT.PUT_LINE('Alert timeout: ' || v_timeout || ' seconds'); + DBMS_ALERT.REMOVE(v_name); +END; + +Registered for alert alert_test +Waiting for signal... +``` + +## REMOVE + +The `REMOVE` procedure unregisters the session for the named alert. + +```sql +REMOVE( VARCHAR2) +``` + +### Parameters + +`name` + + Name of the alert to unregister. + +## REMOVEALL + +The `REMOVEALL` procedure unregisters the session for all alerts. + +```sql +REMOVEALL +``` + +## SIGNAL + +The `SIGNAL` procedure signals the occurrence of the named alert. + +```sql +SIGNAL( VARCHAR2, VARCHAR2) +``` + +### Parameters + +`name` + + Name of the alert. + +`message` + + Information to pass with this alert. + +### Examples + +This anonymous block signals an alert for `alert_test`. + +```sql +DECLARE + v_name VARCHAR2(30) := 'alert_test'; +BEGIN + DBMS_ALERT.SIGNAL(v_name,'This is the message from ' || v_name); + DBMS_OUTPUT.PUT_LINE('Issued alert for ' || v_name); +END; +Issued alert for alert_test +``` + +## WAITANY + +The `WAITANY` procedure waits for any of the registered alerts to occur. + +```sql +WAITANY( OUT VARCHAR2, OUT VARCHAR2, + OUT INTEGER, NUMBER) +``` + +### Parameters + +`name` + + Variable receiving the name of the alert. + +`message` + + Variable receiving the message sent by the `SIGNAL` procedure. + +`status` + + Status code returned by the operation. Possible values are: `0` – alert occurred; `1` – timeout occurred. + +`timeout` + + Time to wait for an alert in seconds. + +### Examples + +This anonymous block uses the `WAITANY` procedure to receive an alert named `alert_test` or `any_alert`: + +```sql +DECLARE + v_name VARCHAR2(30); + v_msg VARCHAR2(80); + v_status INTEGER; + v_timeout NUMBER(3) := 120; +BEGIN + DBMS_ALERT.REGISTER('alert_test'); + DBMS_ALERT.REGISTER('any_alert'); + DBMS_OUTPUT.PUT_LINE('Registered for alert alert_test and any_alert'); + DBMS_OUTPUT.PUT_LINE('Waiting for signal...'); + DBMS_ALERT.WAITANY(v_name,v_msg,v_status,v_timeout); + DBMS_OUTPUT.PUT_LINE('Alert name : ' || v_name); + DBMS_OUTPUT.PUT_LINE('Alert msg : ' || v_msg); + DBMS_OUTPUT.PUT_LINE('Alert status : ' || v_status); + DBMS_OUTPUT.PUT_LINE('Alert timeout: ' || v_timeout || ' seconds'); + DBMS_ALERT.REMOVEALL; +END; + +Registered for alert alert_test and any_alert +Waiting for signal... +``` + +An anonymous block in a second session issues a signal for `any_alert`: + +```sql +DECLARE + v_name VARCHAR2(30) := 'any_alert'; +BEGIN + DBMS_ALERT.SIGNAL(v_name,'This is the message from ' || v_name); + DBMS_OUTPUT.PUT_LINE('Issued alert for ' || v_name); +END; + +Issued alert for any_alert +``` + +Control returns to the first anonymous block and the remainder of the code is executed: + +```text +Registered for alert alert_test and any_alert +Waiting for signal... +Alert name : any_alert +Alert msg : This is the message from any_alert +Alert status : 0 +Alert timeout: 120 seconds +``` + +## WAITONE + +The `WAITONE` procedure waits for the specified registered alert to occur. + +```sql +WAITONE( VARCHAR2, OUT VARCHAR2, + OUT INTEGER, NUMBER) +``` + +### Parameters + +`name` + + Name of the alert. + +`message` + + Variable receiving the message sent by the `SIGNAL` procedure. + +`status` + + Status code returned by the operation. Possible values are: `0` – alert occurred; `1` – timeout occurred. + +`timeout` + + Time to wait for an alert in seconds. + +### Examples + +This anonymous block is similar to the one used in the `WAITANY` example except the `WAITONE` procedure is used to receive the alert named `alert_test`. + +```sql +DECLARE + v_name VARCHAR2(30) := 'alert_test'; + v_msg VARCHAR2(80); + v_status INTEGER; + v_timeout NUMBER(3) := 120; +BEGIN + DBMS_ALERT.REGISTER(v_name); + DBMS_OUTPUT.PUT_LINE('Registered for alert ' || v_name); + DBMS_OUTPUT.PUT_LINE('Waiting for signal...'); + DBMS_ALERT.WAITONE(v_name,v_msg,v_status,v_timeout); + DBMS_OUTPUT.PUT_LINE('Alert name : ' || v_name); + DBMS_OUTPUT.PUT_LINE('Alert msg : ' || v_msg); + DBMS_OUTPUT.PUT_LINE('Alert status : ' || v_status); + DBMS_OUTPUT.PUT_LINE('Alert timeout: ' || v_timeout || ' seconds'); + DBMS_ALERT.REMOVE(v_name); +END; + +Registered for alert alert_test +Waiting for signal... +``` + +Signal sent for `alert_test` sent by an anonymous block in a second session: + +```sql +DECLARE + v_name VARCHAR2(30) := 'alert_test'; +BEGIN + DBMS_ALERT.SIGNAL(v_name,'This is the message from ' || v_name); + DBMS_OUTPUT.PUT_LINE('Issued alert for ' || v_name); +END; + +Issued alert for alert_test +``` + +First session is alerted, control returns to the anonymous block, and the remainder of the code is executed: + +```text +Registered for alert alert_test +Waiting for signal... +Alert name : alert_test +Alert msg : This is the message from alert_test +Alert status : 0 +Alert timeout: 120 seconds +``` + +## Comprehensive example + +The following example uses two triggers to send alerts when the `dept` table or the `emp` table is changed. An anonymous block listens for these alerts and displays messages when an alert is received. + +The following are the triggers on the `dept` and `emp` tables: + +```sql +CREATE OR REPLACE TRIGGER dept_alert_trig + AFTER INSERT OR UPDATE OR DELETE ON dept +DECLARE + v_action VARCHAR2(25); +BEGIN + IF INSERTING THEN + v_action := ' added department(s) '; + ELSIF UPDATING THEN + v_action := ' updated department(s) '; + ELSIF DELETING THEN + v_action := ' deleted department(s) '; + END IF; + DBMS_ALERT.SIGNAL('dept_alert',USER || v_action || 'on ' || + SYSDATE); +END; + +CREATE OR REPLACE TRIGGER emp_alert_trig + AFTER INSERT OR UPDATE OR DELETE ON emp +DECLARE + v_action VARCHAR2(25); +BEGIN + IF INSERTING THEN + v_action := ' added employee(s) '; + ELSIF UPDATING THEN + v_action := ' updated employee(s) '; + ELSIF DELETING THEN + v_action := ' deleted employee(s) '; + END IF; + DBMS_ALERT.SIGNAL('emp_alert',USER || v_action || 'on ' || + SYSDATE); +END; +``` + +This anonymous block is executed in a session while updates to the `dept` and `emp` tables occur in other sessions: + +```sql +DECLARE + v_dept_alert VARCHAR2(30) := 'dept_alert'; + v_emp_alert VARCHAR2(30) := 'emp_alert'; + v_name VARCHAR2(30); + v_msg VARCHAR2(80); + v_status INTEGER; + v_timeout NUMBER(3) := 60; +BEGIN + DBMS_ALERT.REGISTER(v_dept_alert); + DBMS_ALERT.REGISTER(v_emp_alert); + DBMS_OUTPUT.PUT_LINE('Registered for alerts dept_alert and emp_alert'); + DBMS_OUTPUT.PUT_LINE('Waiting for signal...'); + LOOP + DBMS_ALERT.WAITANY(v_name,v_msg,v_status,v_timeout); + EXIT WHEN v_status != 0; + DBMS_OUTPUT.PUT_LINE('Alert name : ' || v_name); + DBMS_OUTPUT.PUT_LINE('Alert msg : ' || v_msg); + DBMS_OUTPUT.PUT_LINE('Alert status : ' || v_status); + DBMS_OUTPUT.PUT_LINE('------------------------------------' || + '-------------------------'); + END LOOP; + DBMS_OUTPUT.PUT_LINE('Alert status : ' || v_status); + DBMS_ALERT.REMOVEALL; +END; + +Registered for alerts dept_alert and emp_alert +Waiting for signal... +``` + +The following changes are made by user, mary: + +```sql +INSERT INTO dept VALUES (50,'FINANCE','CHICAGO'); +INSERT INTO emp (empno,ename,deptno) VALUES (9001,'JONES',50); +INSERT INTO emp (empno,ename,deptno) VALUES (9002,'ALICE',50); +``` + +The following change is made by user, john: + +```sql +INSERT INTO dept VALUES (60,'HR','LOS ANGELES'); +``` + +The following is the output displayed by the anonymous block receiving the signals from the triggers: + +```text +Registered for alerts dept_alert and emp_alert +Waiting for signal... +Alert name : dept_alert +Alert msg : mary added department(s) on 25-OCT-07 16:41:01 +Alert status : 0 +------------------------------------------------------------- +Alert name : emp_alert +Alert msg : mary added employee(s) on 25-OCT-07 16:41:02 +Alert status : 0 +------------------------------------------------------------- +Alert name : dept_alert +Alert msg : john added department(s) on 25-OCT-07 16:41:22 +Alert status : 0 +------------------------------------------------------------- +Alert status : 1 +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/01_enqueue.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/01_enqueue.mdx new file mode 100644 index 00000000000..b0ea3adc866 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/01_enqueue.mdx @@ -0,0 +1,116 @@ +--- +title: "ENQUEUE" +--- + +The `ENQUEUE` procedure adds an entry to a queue. The signature is: + +```sql +ENQUEUE( + IN VARCHAR2, + IN DBMS_AQ.ENQUEUE_OPTIONS_T, + IN DBMS_AQ.MESSAGE_PROPERTIES_T, + IN , + OUT RAW) +``` + +## Parameters + +`queue_name` + + The name (optionally schema qualified) of an existing queue. If you omit the schema name, the server uses the schema specified in the `SEARCH_PATH`. Unlike Oracle, unquoted identifiers are converted to lower case before storing. To include special characters or use a case-sensitive name, enclose the name in double quotes. + + For detailed information about creating a queue, see [DBMS_AQADM.CREATE_QUEUE](../03_dbms_aqadm/03_create_queue). + +`enqueue_options` + + `enqueue_options` is a value of the type `enqueue_options_t`: + +```sql +DBMS_AQ.ENQUEUE_OPTIONS_T IS RECORD( + visibility BINARY_INTEGER DEFAULT ON_COMMIT, + relative_msgid RAW(16) DEFAULT NULL, + sequence_deviation BINARY INTEGER DEFAULT NULL, + transformation VARCHAR2(61) DEFAULT NULL, + delivery_mode PLS_INTEGER NOT NULL DEFAULT PERSISTENT); +``` + +Currently, the only supported parameter values for `enqueue_options_t` are: + +| `visibility` | `ON_COMMIT`. | +| -------------------- | ------------ | +| `delivery_mode` | `PERSISTENT` | +| `sequence_deviation` | `NULL` | +| `transformation` | `NULL` | +| `relative_msgid` | `NULL` | + +`message_properties` + + `message_properties` is a value of the type `message_properties_t`: + +```sql +message_properties_t IS RECORD( + priority INTEGER, + delay INTEGER, + expiration INTEGER, + correlation CHARACTER VARYING(128) COLLATE pg_catalog.”C”, + attempts INTEGER, + recipient_list “AQ$_RECIPIENT_LIST_T”, + exception_queue CHARACTER VARYING(61) COLLATE pg_catalog.”C”, + enqueue_time TIMESTAMP WITHOUT TIME ZONE, + state INTEGER, + original_msgid BYTEA, + transaction_group CHARACTER VARYING(30) COLLATE pg_catalog.”C”, + delivery_mode INTEGER +DBMS_AQ.PERSISTENT); +``` + +The supported values for `message_properties_t` are: + +| | | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `priority` | If the queue table definition includes a `sort_list` that references `priority`, this parameter affects the order that messages are dequeued. A lower value indicates a higher dequeue priority. | +| `delay` | Specify the number of seconds to pass before a message is available for dequeueing or `NO_DELAY`. | +| `expiration` | Use the expiration parameter to specify the number of seconds until a message expires. | +| `correlation` | Use correlation to specify a message to associate with the entry. The default is `NULL`. | +| `attempts` | This is a system-maintained value that specifies the number of attempts to dequeue the message. | +| `recipient_list` | This parameter is not supported. | +| `exception_queue` | Use the `exception_queue` parameter to specify the name of an exception queue to which to move a message if it expires or is dequeued by a transaction that rolls back too many times. | +| `enqueue_time` | `enqueue_time` is the time the record was added to the queue. This value is provided by the system. | +| `state` | This parameter is maintained by DBMS_AQ. The state can be:

`DBMS_AQ.WAITING` – The delay wasn't reached.

`DBMS_AQ.READY` – The queue entry is ready for processing.

`DBMS_AQ.PROCESSED` – The queue entry was processed.

`DBMS_AQ.EXPIRED` – The queue entry was moved to the exception queue. | +| `original_msgid` | This parameter is accepted for compatibility and ignored. | +| `transaction_group` | This parameter is accepted for compatibility and ignored. | +| `delivery_mode` | This parameter isn't supported. Specify a value of `DBMS_AQ.PERSISTENT`. | + +`payload` + + Use the `payload` parameter to provide the data to associate with the queue entry. The payload type must match the type specified when creating the corresponding queue table (see [DBMS_AQADM.CREATE_QUEUE_TABLE](../03_dbms_aqadm/04_create_queue_table)). + +`msgid` + + Use the `msgid` parameter to retrieve a unique (system-generated) message identifier. + +## Example + +The following anonymous block calls `DBMS_AQ.ENQUEUE`, adding a message to a queue named `work_order`: + +```sql +DECLARE + + enqueue_options DBMS_AQ.ENQUEUE_OPTIONS_T; + message_properties DBMS_AQ.MESSAGE_PROPERTIES_T; + message_handle raw(16); + payload work_order; + +BEGIN + + payload := work_order('Smith', 'system upgrade'); + +DBMS_AQ.ENQUEUE( + queue_name => 'work_order', + enqueue_options => enqueue_options, + message_properties => message_properties, + payload => payload, + msgid => message_handle + ); + END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/02_dequeue.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/02_dequeue.mdx new file mode 100644 index 00000000000..7698dc7d17d --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/02_dequeue.mdx @@ -0,0 +1,128 @@ +--- +title: "DEQUEUE" +--- + +The `DEQUEUE` procedure dequeues a message. The signature is: + +```sql +DEQUEUE( + IN VARCHAR2, + IN DBMS_AQ.DEQUEUE_OPTIONS_T, + OUT DBMS_AQ.MESSAGE_PROPERTIES_T, + OUT , + OUT RAW) +``` + +## Parameters + +`queue_name` + + The name (optionally schema-qualified) of an existing queue. If you omit the schema name, the server uses the schema specified in the `SEARCH_PATH`. Unlike Oracle, unquoted identifiers are converted to lower case before storing. To include special characters or use a case-sensitive name, enclose the name in double quotes. + + For detailed information about creating a queue, see [DBMS_AQADM.CREATE_QUEUE](../03_dbms_aqadm/03_create_queue). + +`dequeue_options` is a value of the type, `dequeue_options_t`: + +```sql +DEQUEUE_OPTIONS_T IS RECORD( + consumer_name CHARACTER VARYING(30), + dequeue_mode INTEGER, + navigation INTEGER, + visibility INTEGER, + wait INTEGER, + msgid BYTEA, + correlation CHARACTER VARYING(128), + deq_condition CHARACTER VARYING(4000), + transformation CHARACTER VARYING(61), + delivery_mode INTEGER); +``` + +Currently, the supported parameter values for `dequeue_options_t` are: + +| | | +| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `consumer_name` | Must be `NULL`. | +| `dequeue_mode` | The locking behavior of the dequeue operation. Must be either:

`DBMS_AQ.BROWSE` – Read the message without obtaining a lock.

`DBMS_AQ.LOCKED` – Read the message after acquiring a lock.

`DBMS_AQ.REMOVE` – Read the message before deleting the message.

`DBMS_AQ.REMOVE_NODATA` – Read the message, but don't delete the message. | +| `navigation` | Identifies the message to retrieve. Must be either:

`FIRST_MESSAGE` – The first message in the queue that matches the search term.

`NEXT_MESSAGE` – The next message that's available that matches the first term. | +| `visibility` | Must be `ON_COMMIT`. If you roll back the current transaction, the dequeued item remains in the queue. | +| `wait` | Must be a number larger than 0, or:

`DBMS_AQ.FOREVER` – Wait indefinitely.

`DBMS_AQ.NO_WAIT` – Don't wait. | +| `msgid` | The message ID of the message that to dequeue. | +| `correlation` | Accepted for compatibility and ignored. | +| `deq_condition` | A `VARCHAR2` expression that evaluates to a `BOOLEAN` value indicating whether to deqeueue the message. | +| `transformation` | Accepted for compatibility and ignored. | +| `delivery_mode` | Must be `PERSISTENT`. Buffered messages aren't supported. | + +`message_properties` is a value of the type `message_properties_t`: + +```sql +message_properties_t IS RECORD( + priority INTEGER, + delay INTEGER, + expiration INTEGER, + correlation CHARACTER VARYING(128) COLLATE pg_catalog.”C”, + attempts INTEGER, + recipient_list “AQ$_RECIPIENT_LIST_T”, + exception_queue CHARACTER VARYING(61) COLLATE pg_catalog.”C”, + enqueue_time TIMESTAMP WITHOUT TIME ZONE, + state INTEGER, + original_msgid BYTEA, + transaction_group CHARACTER VARYING(30) COLLATE pg_catalog.”C”, + delivery_mode INTEGER +DBMS_AQ.PERSISTENT); +``` + +The supported values for `message_properties_t` are: + +| | | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `priority` | If the queue table definition includes a `sort_list` that references `priority`, this parameter affects the order that messages are dequeued. A lower value indicates a higher dequeue priority. | +| `delay` | Specify the number of seconds that pass before a message is available for dequeueing or `NO_DELAY`. | +| `expiration` | Use the expiration parameter to specify the number of seconds until a message expires. | +| `correlation` | Use correlation to specify a message to associate with the entry. The default is `NULL`. | +| `attempts` | This is a system-maintained value that specifies the number of attempts to dequeue the message. | +| `recipient_list` | This parameter isn't supported. | +| `exception_queue` | Use the `exception_queue` parameter to specify the name of an exception queue to which to move a message if it expires or is dequeued by a transaction that rolls back too many times. | +| `enqueue_time` | `enqueue_time` is the time the record was added to the queue. This value is provided by the system. | +| `state` | This parameter is maintained by DBMS_AQ; state can be:

`DBMS_AQ.WAITING` – the delay has not been reached.

`DBMS_AQ.READY` – the queue entry is ready for processing.

`DBMS_AQ.PROCESSED` – the queue entry has been processed.

`DBMS_AQ.EXPIRED` – the queue entry has been moved to the exception queue. | +| `original_msgid` | This parameter is accepted for compatibility and ignored. | +| `transaction_group` | This parameter is accepted for compatibility and ignored. | +| `delivery_mode` | This parameter isn't supported. Specify a value of `DBMS_AQ.PERSISTENT`. | + +`payload` + + Use the `payload` parameter to retrieve the payload of a message with a dequeue operation. The payload type must match the type specified when creating the queue table. + +`msgid` + + Use the `msgid` parameter to retrieve a unique message identifier. + +## Example + +The following anonymous block calls `DBMS_AQ.DEQUEUE`, retrieving a message from the queue and a payload: + +```sql +DECLARE + + dequeue_options DBMS_AQ.DEQUEUE_OPTIONS_T; + message_properties DBMS_AQ.MESSAGE_PROPERTIES_T; + message_handle raw(16); + payload work_order; + +BEGIN + dequeue_options.dequeue_mode := DBMS_AQ.BROWSE; + + DBMS_AQ.DEQUEUE( + queue_name => 'work_queue', + dequeue_options => dequeue_options, + message_properties => message_properties, + payload => payload, + msgid => message_handle + ); + + DBMS_OUTPUT.PUT_LINE( + 'The next work order is [' || payload.subject || '].' + ); +END; +``` + +The payload is displayed by `DBMS_OUTPUT.PUT_LINE`. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/03_register.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/03_register.mdx new file mode 100644 index 00000000000..98167879942 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/03_register.mdx @@ -0,0 +1,59 @@ +--- +title: "REGISTER" +--- + +Use the `REGISTER` procedure to register an email address, procedure, or URL to notify when an item is enqueued or dequeued. The signature is: + +```sql +REGISTER( + IN SYS.AQ$_REG_INFO_LIST, + IN NUMBER) +``` + +## Parameters + +`reg_list` is a list of type `AQ$_REG_INFO_LIST` that provides information about each subscription that you want to register. Each entry in the list is of the type `AQ$_REG_INFO` and can contain: + +
+ +
+ +| Attribute | Type | Description | +| ----------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | VARCHAR2 (128) | The (optionally schema-qualified) name of the subscription. | +| `namespace` | NUMERIC | The only supported value is `DBMS_AQ.NAMESPACE_AQ (0)`. | +| `callback` | VARCHAR2 (4000) | Describes the action to perform on notification. Currently, only calls to PL/SQL procedures are supported. The call takes the form:

`plsql://schema.procedure`

Where:

schema specifies the schema in which the procedure resides.

procedure specifies the name of the procedure to notify. | +| `context` | RAW (16) | Any user-defined value required by the procedure. | + +`count` + + `count` is the number of entries in `reg_list`. + +## Example + +The following anonymous block calls `DBMS_AQ.REGISTER`, registering procedures to notify when an item is added to or removed from a queue. A set of attributes (of `sys.aq$_reg_info` type) is provided for each subscription identified in the `DECLARE` section: + +```sql +DECLARE + subscription1 sys.aq$_reg_info; + subscription2 sys.aq$_reg_info; + subscription3 sys.aq$_reg_info; + subscriptionlist sys.aq$_reg_info_list; +BEGIN + subscription1 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, +'plsql://assign_worker?PR=0',HEXTORAW('FFFF')); + subscription2 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, +'plsql://add_to_history?PR=1',HEXTORAW('FFFF')); + subscription3 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, +'plsql://reserve_parts?PR=2',HEXTORAW('FFFF')); + + subscriptionlist := sys.aq$_reg_info_list(subscription1, +subscription2, subscription3); + dbms_aq.register(subscriptionlist, 3); + commit; + + END; + / +``` + +The `subscriptionlist` is of type `sys.aq$_reg_info_list` and contains the previously described `sys.aq$_reg_info` objects. The list name and an object count are passed to `dbms_aq.register`. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/04_unregister.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/04_unregister.mdx new file mode 100644 index 00000000000..feafb943a01 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/04_unregister.mdx @@ -0,0 +1,60 @@ +--- +title: "UNREGISTER" +--- + +Use the `UNREGISTER` procedure to turn off notifications related to enqueueing and dequeueing. The signature is: + +```sql +UNREGISTER( + IN SYS.AQ$_REG_INFO_LIST, + IN NUMBER) +``` + +## Parameter + +`reg_list` + + `reg_list` is a list of type `AQ$_REG_INFO_LIST` that provides information about each subscription that you want to register. Each entry in the list is of the type `AQ$_REG_INFO` and can contain: + +
+ +
+ +| Attribute | Type | Description | +| ----------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | VARCHAR2 (128) | The (optionally schema-qualified) name of the subscription. | +| `namespace` | NUMERIC | The only supported value is `DBMS_AQ.NAMESPACE_AQ (0)`. | +| `callback` | VARCHAR2 (4000) | Describes the action to perform on notification. Currently, only calls to PL/SQL procedures are supported. The call taked the form:

`plsql://schema.procedure`

Where:

schema specifies the schema in which the procedure resides.

procedure specifies the name of the procedure to notify. | +| `context` | RAW (16) | Any user-defined value required by the procedure. | + +`count` + + `count` is the number of entries in `reg_list`. + +## Example + +The following anonymous block calls `DBMS_AQ.UNREGISTER`, disabling the notifications specified in the example for `DBMS_AQ.REGISTER`: + +```sql +DECLARE + subscription1 sys.aq$_reg_info; + subscription2 sys.aq$_reg_info; + subscription3 sys.aq$_reg_info; + subscriptionlist sys.aq$_reg_info_list; +BEGIN + subscription1 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, +'plsql://assign_worker?PR=0',HEXTORAW('FFFF')); + subscription2 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, +'plsql://add_to_history?PR=1',HEXTORAW('FFFF')); + subscription3 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, +'plsql://reserve_parts?PR=2',HEXTORAW('FFFF')); + + subscriptionlist := sys.aq$_reg_info_list(subscription1, +subscription2, subscription3); + dbms_aq.unregister(subscriptionlist, 3); + commit; + END; + / +``` + +The `subscriptionlist` is of type `sys.aq$_reg_info_list` and contains `sys.aq$_reg_info` objects. The list name and an object count are passed to `dbms_aq.unregister`. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/index.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/index.mdx new file mode 100644 index 00000000000..e3629e1ea24 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/index.mdx @@ -0,0 +1,72 @@ +--- +title: "DBMS_AQ" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.13.html" +--- + +EDB Postgres Advanced Server Advanced Queueing provides message queueing and message processing for the EDB Postgres Advanced Server database. User-defined messages are stored in a queue, and a collection of queues is stored in a queue table. Procedures in the `DBMS_AQADM` package create and manage message queues and queue tables. Use the `DBMS_AQ` package to add messages to or remove them from a queue or to register or unregister a PL/SQL callback procedure. + +EDB Postgres Advanced Server also provides extended (noncompatible) functionality for the `DBMS_AQ` package with SQL commands. See the [Database Compatibility for Oracle Developers SQL](../../../epas_compat_sql) for detailed information about the following SQL commands: + +- `ALTER QUEUE` +- `ALTER QUEUE TABLE` +- `CREATE QUEUE` +- `CREATE QUEUE TABLE` +- `DROP QUEUE` +- `DROP QUEUE TABLE` + +The `DBMS_AQ` package provides procedures that allow you to enqueue a message, dequeue a message, and manage callback procedures. The supported procedures are: + +| Function/procedure | Return type | Description | +| ------------------ | ----------- | ------------------------------------------------------------------ | +| `ENQUEUE` | n/a | Post a message to a queue. | +| `DEQUEUE` | n/a | Retrieve a message from a queue if or when a message is available. | +| `REGISTER` | n/a | Register a callback procedure. | +| `UNREGISTER` | n/a | Unregister a callback procedure. | + +EDB Postgres Advanced Server's implementation of `DBMS_AQ` is a partial implementation when compared to Oracle's version. Only those procedures listed in the table above are supported. + +EDB Postgres Advanced Server supports use of these constants: + +| Constant | Description | For parameters | +| --------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| `DBMS_AQ.BROWSE (0)` | Read the message without locking. | `dequeue_options_t.dequeue_mode` | +| `DBMS_AQ.LOCKED (1)` | This constant is defined but returns an error if used. | `dequeue_options_t.dequeue_mode` | +| `DBMS_AQ.REMOVE (2)` | Delete the message after reading (the default). | `dequeue_options_t.dequeue_mode` | +| `DBMS_AQ.REMOVE_NODATA (3)` | This constant is defined but returns an error if used. | `dequeue_options_t.dequeue_mode` | +| `DBMS_AQ.FIRST_MESSAGE (0)` | Return the first available message that matches the search terms. | `dequeue_options_t.navigation` | +| `DBMS_AQ.NEXT_MESSAGE (1)` | Return the next available message that matches the search terms. | `dequeue_options_t.navigation` | +| `DBMS_AQ.NEXT_TRANSACTION (2)` | This constant is defined but returns an error if used. | `dequeue_options_t.navigation` | +| `DBMS_AQ.FOREVER (-1)` | Wait forever if a message that matches the search term isn't found (the default). | `dequeue_options_t.wait` | +| `DBMS_AQ.NO_WAIT (0)` | Don't wait if a message that matches the search term isn't found. | `dequeue_options_t.wait` | +| `DBMS_AQ.ON_COMMIT (0)` | The dequeue is part of the current transaction. | `enqueue_options_t.visibility, dequeue_options_t.visibility` | +| `DBMS_AQ.IMMEDIATE (1)` | This constant is defined but returns an error if used. | `enqueue_options_t.visibility, dequeue_options_t.visibility` | +| `DBMS_AQ.PERSISTENT (0)` | Store the message in a table. | `enqueue_options_t.delivery_mode` | +| `DBMS_AQ.BUFFERED (1)` | This constant is defined but returns an error if used. | `enqueue_options_t.delivery_mode` | +| `DBMS_AQ.READY (0)` | Specifies that the message is ready to process. | `message_properties_t.state` | +| `DBMS_AQ.WAITING (1)` | Specifies that the message is waiting to be processed. | `message_properties_t.state` | +| `DBMS_AQ.PROCESSED (2)` | Specifies that the message was processed. | `message_properties_t.state` | +| `DBMS_AQ.EXPIRED (3)` | Specifies that the message is in the exception queue. | `message_properties_t.state` | +| `DBMS_AQ.NO_DELAY (0)` | This constant is defined but returns an error if used. | `message_properties_t.delay` | +| `DBMS_AQ.NEVER (NULL)` | This constant is defined but returns an error if used. | `message_properties_t.expiration` | +| `DBMS_AQ.NAMESPACE_AQ (0)` | Accept notifications from `DBMS_AQ` queues. | `sys.aq$_reg_info.namespace` | +| `DBMS_AQ.NAMESPACE_ANONYMOUS (1)` | This constant is defined but returns an error if used. | `sys.aq$_reg_info.namespace` | + +The `DBMS_AQ` configuration parameters listed in the following table can be defined in the `postgresql.conf` file. After the configuration parameters are defined, you can invoke the `DBMS_AQ` package to use and manage messages held in queues and queue tables. + +| Parameter | Description | +| ----------------------------- | ------------------------------------------------------------------------------------------------ | +| `dbms_aq.max_workers` | The maximum number of workers to run. | +| `dbms_aq.max_idle_time` | The idle time a worker must wait before exiting. | +| `dbms_aq.min_work_time` | The minimum time a worker can run before exiting. | +| `dbms_aq.launch_delay` | The minimum time between creating workers. | +| `dbms_aq.batch_size` | The maximum number of messages to process in a single transaction. The default batch size is 10. | +| `dbms_aq.max_databases` | The size of the `DBMS_AQ` hash table of databases. The default value is 1024. | +| `dbms_aq.max_pending_retries` | The size of the `DBMS_AQ` hash table of pending retries. The default value is 1024. | + +
+ +enqueue dequeue register unregister + +
diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/01_alter_queue.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/01_alter_queue.mdx new file mode 100644 index 00000000000..47a0b812815 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/01_alter_queue.mdx @@ -0,0 +1,48 @@ +--- +title: "ALTER_QUEUE" +--- + +Use the `ALTER_QUEUE` procedure to modify an existing queue. The signature is: + +```sql +ALTER_QUEUE( + IN NUMBER DEFAULT NULL, + IN NUMBER DEFAULT 0 + IN NUMBER DEFAULT 0, + IN BOOLEAN DEFAULT TRUE) + IN VARCHAR2 DEFAULT NULL, +``` + +## Parameters + +`queue_name` + + The name of the new queue. + +`max_retries` + + `max_retries` specifies the maximum number of attempts to remove a message with a dequeue statement. The value of `max_retries` is incremented with each `ROLLBACK` statement. When the number of failed attempts reaches the value specified by `max_retries`, the message is moved to the exception queue. Specify `0` to indicate that no retries are allowed. + +`retry_delay` + + `retry_delay` specifies the number of seconds until a message is scheduled for reprocessing after a `ROLLBACK`. Specify `0` to retry the message immediately (the default). + +`retention_time` + + `retention_time` specifies the length of time in seconds that a message is stored after being dequeued. You can also specify `0` (the default) to indicate not to retain the message after dequeueing or `INFINITE` to retain the message forever. + +`auto_commit` + + This parameter is accepted for compatibility and ignored. + +`comment` + + `comment` specifies a comment associated with the queue. + +## Example + +The following command alters a queue named `work_order`, setting the `retry_delay` parameter to 5 seconds: + +```sql +EXEC DBMS_AQADM.ALTER_QUEUE(queue_name => 'work_order', retry_delay => 5); +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/02_alter_queue_table.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/02_alter_queue_table.mdx new file mode 100644 index 00000000000..eed3c02f1df --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/02_alter_queue_table.mdx @@ -0,0 +1,43 @@ +--- +title: "ALTER_QUEUE_TABLE" +--- + +Use the `ALTER_QUEUE_TABLE` procedure to modify an existing queue table. The signature is: + +```sql +ALTER_QUEUE_TABLE ( + IN VARCHAR2, + IN VARCHAR2 DEFAULT NULL, + IN BINARY_INTEGER DEFAULT 0, + IN BINARY_INTEGER DEFAULT 0, +``` + +## Parameters + +`queue_table` + + The (optionally schema-qualified) name of the queue table. + +`comment` + + Use the `comment` parameter to provide a comment about the queue table. + +`primary_instance` + + `primary_instance` is accepted for compatibility and stored but is ignored. + +`secondary_instance` + + `secondary_instance` is accepted for compatibility but is ignored. + +## Example + +The following command modifies a queue table named `work_order_table`: + +```sql +EXEC DBMS_AQADM.ALTER_QUEUE_TABLE + (queue_table => 'work_order_table', comment => 'This queue table +contains work orders for the shipping department.'); +``` + +The queue table is named `work_order_table`. The command adds a comment to the definition of the queue table. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/03_create_queue.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/03_create_queue.mdx new file mode 100644 index 00000000000..2df5f4d2428 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/03_create_queue.mdx @@ -0,0 +1,71 @@ +--- +title: "CREATE_QUEUE" +--- + +Use the `CREATE_QUEUE` procedure to create a queue in an existing queue table. The signature is: + +```sql +CREATE_QUEUE( + IN VARCHAR2 + IN VARCHAR2, + IN BINARY_INTEGER DEFAULT NORMAL_QUEUE, + IN NUMBER DEFAULT 5, + IN NUMBER DEFAULT 0 + IN NUMBER DEFAULT 0, + IN BOOLEAN DEFAULT FALSE, + IN VARCHAR2 DEFAULT NULL, + IN BOOLEAN DEFAULT TRUE) +``` + +## Parameters + +`queue_name` + + The name of the new queue. + +`queue_table` + + The name of the table in which the new queue resides. + +`queue_type` + + The type of the new queue. The valid values for `queue_type` are: + + `DBMS_AQADM.NORMAL_QUEUE` — This value specifies a normal queue (the default). + + `DBMS_AQADM.EXCEPTION_QUEUE` — This value specifies that the new queue is an exception queue. An exception queue supports only dequeue operations. + +`max_retries` + + `max_retries` specifies the maximum number of attempts to remove a message with a dequeue statement. The value of `max_retries` is incremented with each `ROLLBACK` statement. When the number of failed attempts reaches the value specified by `max_retries`, the message is moved to the exception queue. The default value for a system table is `0`. The default value for a user-created table is `5`. + +`retry_delay` + + `retry_delay` specifies the number of seconds until a message is scheduled for reprocessing after a `ROLLBACK`. Specify `0` to retry the message immediately (the default). + +`retention_time` + + `retention_time` specifies the length of time (in seconds) that a message is stored after being dequeued. You can also specify `0` (the default) to indicate not to retain the message after dequeueing or `INFINITE` to retain the message forever. + +`dependency_tracking` + + This parameter is accepted for compatibility and ignored. + +`comment` + + `comment` specifies a comment associated with the queue. + +`auto_commit` + + This parameter is accepted for compatibility and ignored. + +## Example + +The following anonymous block creates a queue named `work_order` in the `work_order_table` table: + +```sql +BEGIN +DBMS_AQADM.CREATE_QUEUE ( queue_name => 'work_order', queue_table => +'work_order_table', comment => 'This queue contains pending work orders.'); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/04_create_queue_table.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/04_create_queue_table.mdx new file mode 100644 index 00000000000..6f203248066 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/04_create_queue_table.mdx @@ -0,0 +1,113 @@ +--- +title: "CREATE_QUEUE_TABLE" +--- + +Use the `CREATE_QUEUE_TABLE` procedure to create a queue table. The signature is: + +```sql +CREATE_QUEUE_TABLE ( + IN VARCHAR2, + IN VARCHAR2, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN BOOLEAN DEFAULT FALSE, + IN BINARY_INTEGER DEFAULT NONE, + IN VARCHAR2 DEFAULT NULL, + IN BOOLEAN DEFAULT TRUE, + IN BINARY_INTEGER DEFAULT 0, + IN BINARY_INTEGER DEFAULT 0, + IN VARCHAR2 DEFAULT NULL, + IN BOOLEAN DEFAULT FALSE) +``` + +## Parameters + +`queue_table` + + The (optionally schema-qualified) name of the queue table. + +`queue_payload_type` + + The user-defined type of the data that's stored in the queue table. To specify a `RAW` data type, you must create a user-defined type that identifies a `RAW` type. + +`storage_clause` + +Use the `storage_clause` parameter to specify attributes for the queue table. Only the `TABLESPACE` option is enforced. All others are accepted for compatibility and ignored. Use the `TABLESPACE` clause to specify the name of a tablespace in which to create the table. + + `storage_clause` can be one or more of the following: + +```sql +TABLESPACE tablespace_name, PCTFREE integer, PCTUSED integer, +INITRANS integer, MAXTRANS integer or STORAGE storage_option. +``` + +`storage_option` can be one or more of the following: + +```sql +MINEXTENTS integer, MAXEXTENTS integer, PCTINCREASE integer, INITIAL +size_clause, NEXT, FREELISTS integer, OPTIMAL size_clause, BUFFER_ +POOL {KEEP|RECYCLE|DEFAULT}. +``` + +`sort_list` + + `sort_list` controls the dequeueing order of the queue. Specify the names of the columns to use to sort the queue in ascending order. The currently accepted values are the following combinations of `enq_time` and `priority`: + +- `enq_time, priority` + +- `priority, enq_time` + +- `priority` + +- `enq_time` + +`multiple_consumers` + + `multiple_consumers` queue tables isn't supported. + +`message_grouping` + + If specified, `message_grouping` must be `NONE`. + +`comment` + + Use the `comment` parameter to provide a comment about the queue table. + +`auto_commit` + + `auto_commit` is accepted for compatibility but is ignored. + +`primary_instance` + + `primary_instance` is accepted for compatibility and stored but is ignored. + +`secondary_instance` + + `secondary_instance` is accepted for compatibility but is ignored. + +`compatible` + + `compatible` is accepted for compatibility but is ignored. + +`secure` + + `secure` is accepted for compatibility but is ignored. + +## Example + +The following anonymous block first creates a type (`work_order`) with attributes that hold a name (a `VARCHAR2`), and a project description (a `TEXT`). The block then uses that type to create a queue table: + +```sql +BEGIN + +CREATE TYPE work_order AS (name VARCHAR2, project TEXT, completed BOOLEAN); + +EXEC DBMS_AQADM.CREATE_QUEUE_TABLE + (queue_table => 'work_order_table', + queue_payload_type => 'work_order', + comment => 'Work order message queue table'); + +END; +``` + +The queue table is named `work_order_table` and contains a payload of a type `work_order`. A comment notes that this is the `Work order message queue table`. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/05_drop_queue.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/05_drop_queue.mdx new file mode 100644 index 00000000000..2308106ba27 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/05_drop_queue.mdx @@ -0,0 +1,31 @@ +--- +title: "DROP_QUEUE" +--- + +Use the `DROP_QUEUE` procedure to delete a queue. The signature is: + +```sql +DROP_QUEUE( + IN VARCHAR2, + IN BOOLEAN DEFAULT TRUE) +``` + +## Parameters + +`queue_name` + + The name of the queue that you want to drop. + +`auto_commit` + + `auto_commit` is accepted for compatibility but is ignored. + +## Example + +The following anonymous block drops the queue named `work_order`: + +```sql +BEGIN +DBMS_AQADM.DROP_QUEUE(queue_name => 'work_order'); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/06_drop_queue_table.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/06_drop_queue_table.mdx new file mode 100644 index 00000000000..bbc68b622ae --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/06_drop_queue_table.mdx @@ -0,0 +1,39 @@ +--- +title: "DROP_QUEUE_TABLE" +--- + +Use the `DROP_QUEUE_TABLE` procedure to delete a queue table. The signature is: + +```sql +DROP_QUEUE_TABLE( + IN VARCHAR2, + IN BOOLEAN default FALSE, + IN BOOLEAN default TRUE) +``` + +## Parameters + +`queue_table` + + The (optionally schema-qualified) name of the queue table. + +`force` + + The `force` keyword determines the behavior of the `DROP_QUEUE_TABLE` command when dropping a table that contain entries: + +- If the target table contains entries and `force` is `FALSE`, the command fails, and the server issues an error. +- If the target table contains entries and `force` is `TRUE`, the command drops the table and any dependent objects. + +`auto_commit` + + `auto_commit` is accepted for compatibility but is ignored. + +## Example + +The following anonymous block drops a table named `work_order_table`: + +```sql +BEGIN + DBMS_AQADM.DROP_QUEUE_TABLE ('work_order_table', force => TRUE); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/07_purge_queue_table.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/07_purge_queue_table.mdx new file mode 100644 index 00000000000..9ca32dc1745 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/07_purge_queue_table.mdx @@ -0,0 +1,44 @@ +--- +title: "PURGE_QUEUE_TABLE" +--- + +Use the `PURGE_QUEUE_TABLE` procedure to delete messages from a queue table. The signature is: + +```sql +PURGE_QUEUE_TABLE( + IN VARCHAR2, + IN VARCHAR2, + IN aq$_purge_options_t) +``` + +## Parameters + +`queue_table` + + `queue_table` specifies the name of the queue table from which you're deleting a message. + +`purge_condition` + + Use `purge_condition` to specify a condition (a SQL `WHERE` clause) that the server evaluates when deciding which messages to purge. + +`purge_options` + + `purge_options` is an object of the type `aq$_purge_options_t`. An `aq$_purge_options_t` object contains: + +| Attribute | Type | Description | +| --------------- | ------- | ------------------------------------------------------------------------------------------------------------------- | +| `block` | Boolean | Specify `TRUE` to hold an exclusive lock on all queues in the table. The default is `FALSE`. | +| `delivery_mode` | INTEGER | `delivery_mode` specifies the type of message to purge. The only accepted value is `DBMS_AQ.PERSISTENT`. | + +## Example + +The following anonymous block removes any messages from the `work_order_table` with a value in the `completed` column of `YES`: + +```sql +DECLARE + purge_options dbms_aqadm.aq$_purge_options_t; +BEGIN + dbms_aqadm.purge_queue_table('work_order_table', 'completed = YES', +purge_options); + END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/08_start_queue.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/08_start_queue.mdx new file mode 100644 index 00000000000..f9d4aafb65f --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/08_start_queue.mdx @@ -0,0 +1,37 @@ +--- +title: "START_QUEUE" +--- + +Use the `START_QUEUE` procedure to make a queue available for enqueuing and dequeueing. The signature is: + +```sql +START_QUEUE( + IN VARCHAR2, + IN BOOLEAN DEFAULT TRUE, + IN BOOLEAN DEFAULT TRUE) +``` + +## Parameters + +`queue_name` + + `queue_name` specifies the name of the queue that you're starting. + +`enqueue` + + Specify `TRUE` to enable enqueueing (the default) or `FALSE` to leave the current setting unchanged. + +`dequeue` + + Specify `TRUE` to enable dequeueing (the default) or `FALSE` to leave the current setting unchanged. + +## Example + +The following anonymous block makes a queue named `work_order` available for enqueueing: + +```sql +BEGIN +DBMS_AQADM.START_QUEUE +(queue_name => 'work_order); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/09_stop_queue.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/09_stop_queue.mdx new file mode 100644 index 00000000000..631eb9074d9 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/09_stop_queue.mdx @@ -0,0 +1,44 @@ +--- +title: "STOP_QUEUE" +--- + +Use the `STOP_QUEUE` procedure to disable enqueuing or dequeueing on a specified queue. The signature is: + +```sql +STOP_QUEUE( + IN VARCHAR2, + IN BOOLEAN DEFAULT TRUE, + IN BOOLEAN DEFAULT TRUE, + IN BOOLEAN DEFAULT TRUE) +``` + +## Parameters + +`queue_name` + + `queue_name` specifies the name of the queue that you're stopping. + +`enqueue` + + Specify `TRUE` to disable enqueueing (the default) or `FALSE` to leave the current setting unchanged. + +`dequeue` + + Specify `TRUE` to disable dequeueing (the default) or `FALSE` to leave the current setting unchanged. + +`wait` + + Specify `TRUE` to instruct the server to wait for any uncompleted transactions to complete before applying the specified changes. While waiting to stop the queue, no transactions are allowed to enqueue or dequeue from the specified queue. Specify `FALSE` to stop the queue immediately. + +## Example + +The following anonymous block disables enqueueing and dequeueing from the queue named `work_order`: + +```sql +BEGIN +DBMS_AQADM.STOP_QUEUE(queue_name =>'work_order', enqueue=>TRUE, +dequeue=>TRUE, wait=>TRUE); +END; +``` + +Enqueueing and dequeueing stops after any outstanding transactions complete. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/index.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/index.mdx new file mode 100644 index 00000000000..2b9b92da51a --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/index.mdx @@ -0,0 +1,50 @@ +--- +title: "DBMS_AQADM" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.14.html" +--- + +EDB Postgres Advanced Server advanced queueing provides message queueing and message processing for the EDB Postgres Advanced Server database. User-defined messages are stored in a queue, and a collection of queues is stored in a queue table. Procedures in the `DBMS_AQADM` package create and manage message queues and queue tables. Use the `DBMS_AQ` package to add messages to or remove messages from a queue or to register or unregister a PL/SQL callback procedure. + +EDB Postgres Advanced Server also provides extended (non-compatible) functionality for the `DBMS_AQ` package with SQL commands. See [Database Compatibility for Oracle Developers SQL](../../../epas_compat_sql/) for detailed information about the following SQL commands: + +- `ALTER QUEUE` +- `ALTER QUEUE TABLE` +- `CREATE QUEUE` +- `CREATE QUEUE TABLE` +- `DROP QUEUE` +- `DROP QUEUE TABLE` + +The `DBMS_AQADM` package provides procedures that allow you to create and manage queues and queue tables. EDB Postgres Advanced Server's implementation of `DBMS_AQADM` is a partial implementation when compared to Oracle's version. Only those functions and procedures listed in the table are supported. + +| Function/procedure | Return type | Description | +| -------------------- | ----------- | ----------------------------------------------------------------- | +| `ALTER_QUEUE` | n/a | Modify an existing queue. | +| `ALTER_QUEUE_TABLE` | n/a | Modify an existing queue table. | +| `CREATE_QUEUE` | n/a | Create a queue. | +| `CREATE_QUEUE_TABLE` | n/a | Create a queue table. | +| `DROP_QUEUE` | n/a | Drop an existing queue. | +| `DROP_QUEUE_TABLE` | n/a | Drop an existing queue table. | +| `PURGE_QUEUE_TABLE` | n/a | Remove one or more messages from a queue table. | +| `START_QUEUE` | n/a | Make a queue available for enqueueing and dequeueing procedures. | +| `STOP_QUEUE` | n/a | Make a queue unavailable for enqueueing and dequeueing procedures. | + +EDB Postgres Advanced Server supports use of the arguments listed in the table: + +| Constant | Description | For parameters | +| --------------------------------------- | ----------------------------------------------------------- | --------------------------------- | +| `DBMS_AQADM.TRANSACTIONAL(1)` | This constant is defined but returns an error if used. | `message_grouping` | +| `DBMS_AQADM.NONE(0)` | Use to specify message grouping for a queue table. | `message_grouping` | +| `DBMS_AQADM.NORMAL_QUEUE(0)` | Use with `create_queue` to specify `queue_type`. | `queue_type` | +| `DBMS_AQADM.EXCEPTION_QUEUE (1)` | Use with `create_queue` to specify `queue_type`. | `queue_type` | +| `DBMS_AQADM.INFINITE(-1)` | Use with `create_queue` to specify `retention_time`. | `retention_time` | +| `DBMS_AQADM.PERSISTENT (0)` | Store the message in a table. | `enqueue_options_t.delivery_mode` | +| `DBMS_AQADM.BUFFERED (1)` | This constant is defined but returns an error if used. | `enqueue_options_t.delivery_mode` | +| `DBMS_AQADM.PERSISTENT_OR_BUFFERED (2)` | This constant is defined but returns an error if used. | `enqueue_options_t.delivery_mode` | + +
+ +alter_queue alter_queue_table create_queue create_queue_table drop_queue drop_queue_table purge_queue_table start_queue stop_queue + +
diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/01_decrypt.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/01_decrypt.mdx new file mode 100644 index 00000000000..2c95a6e8c0e --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/01_decrypt.mdx @@ -0,0 +1,96 @@ +--- +title: "DECRYPT" +--- + +The `DECRYPT` function or procedure decrypts data using a user-specified cipher algorithm, key, and optional initialization vector. The signature of the `DECRYPT` function is: + +```sql +DECRYPT + ( IN RAW, IN INTEGER, IN RAW, IN RAW + DEFAULT NULL) RETURN RAW +``` + +The signature of the `DECRYPT` procedure is: + +```sql +DECRYPT + ( INOUT BLOB, IN BLOB, IN INTEGER, IN RAW, + IN RAW DEFAULT NULL) +``` + +or + +```sql +DECRYPT + ( INOUT CLOB, IN CLOB, IN INTEGER, IN RAW, + IN RAW DEFAULT NULL) +``` + +When invoked as a procedure, `DECRYPT` returns `BLOB` or `CLOB` data to a user-specified `BLOB`. + +## Parameters + +`dst` + + `dst` specifies the name of a `BLOB` to which the output of the `DECRYPT` procedure is written. The `DECRYPT` procedure overwrites any existing data currently in `dst`. + +`src` + + `src` specifies the source data to decrypt. If you're invoking `DECRYPT` as a function, specify `RAW` data. If invoking `DECRYPT` as a procedure, specify `BLOB` or `CLOB` data. + +`typ` + + `typ` specifies the block cipher type and any modifiers. Match the type specified when the `src` was encrypted. EDB Postgres Advanced Server supports the following block cipher algorithms, modifiers, and cipher suites: + +| Block cipher algorithms | | +| ---------------------------------- | ----------------------------------------------------------- | +| `ENCRYPT_DES` | `CONSTANT INTEGER := 1;` | +| `ENCRYPT_3DES` | `CONSTANT INTEGER := 3;` | +| `ENCRYPT_AES` | `CONSTANT INTEGER := 4;` | +| `ENCRYPT_AES128` | `CONSTANT INTEGER := 6;` | +| `ENCRYPT_AES192` | `CONSTANT INTEGER := 192;` | +| `ENCRYPT_AES256` | `CONSTANT INTEGER := 256;` | +| **Block cipher modifiers** | | +| `CHAIN_CBC` | `CONSTANT INTEGER := 256;` | +| `CHAIN_ECB` | `CONSTANT INTEGER := 768;` | +| **Block cipher padding modifiers** | | +| `PAD_PKCS5` | `CONSTANT INTEGER := 4096;` | +| `PAD_NONE` | `CONSTANT INTEGER := 8192;` | +| **Block cipher suites** | | +| `DES_CBC_PKCS5` | `CONSTANT INTEGER := ENCRYPT_DES + CHAIN_CBC + PAD_PKCS5;` | +| `DES3_CBC_PKCS5` | `CONSTANT INTEGER := ENCRYPT_3DES + CHAIN_CBC + PAD_PKCS5;` | +| `AES_CBC_PKCS5` | `CONSTANT INTEGER := ENCRYPT_AES + CHAIN_CBC + PAD_PKCS5;` | + +`key` + + `key` specifies the user-defined decryption key. Match the key specified when the `src` was encrypted. + +`iv` + + `iv` (optional) specifies an initialization vector. If an initialization vector was specified when the `src` was encrypted, you must specify an initialization vector when decrypting the `src`. The default is `NULL`. + +## Examples + +This example uses the `DBMS_CRYPTO.DECRYPT` function to decrypt an encrypted password retrieved from the `passwords` table: + +```sql +CREATE TABLE passwords +( + principal VARCHAR2(90) PRIMARY KEY, -- username + ciphertext RAW(9) -- encrypted password +); + +CREATE FUNCTION get_password(username VARCHAR2) RETURN RAW AS + typ INTEGER := DBMS_CRYPTO.DES_CBC_PKCS5; + key RAW(128) := 'my secret key'; + iv RAW(100) := 'my initialization vector'; + password RAW(2048); +BEGIN + + SELECT ciphertext INTO password FROM passwords WHERE principal = username; + + RETURN dbms_crypto.decrypt(password, typ, key, iv); +END; +``` + +When calling `DECRYPT`, you must pass the same cipher type, key value, and initialization vector that was used when encrypting the target. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/02_encrypt.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/02_encrypt.mdx new file mode 100644 index 00000000000..8a4ad48816a --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/02_encrypt.mdx @@ -0,0 +1,93 @@ +--- +title: "ENCRYPT" +--- + +The `ENCRYPT` function or procedure uses a user-specified algorithm, key, and optional initialization vector to encrypt `RAW`, `BLOB`, or `CLOB` data. The signature of the `ENCRYPT` function is: + +```sql +ENCRYPT + ( IN RAW, IN INTEGER, IN RAW, + IN RAW DEFAULT NULL) RETURN RAW +``` + +The signature of the `ENCRYPT` procedure is: + +```sql +ENCRYPT + ( INOUT BLOB, IN BLOB, IN INTEGER, IN RAW, + IN RAW DEFAULT NULL) +``` + +or + +```sql +ENCRYPT + ( INOUT BLOB, IN CLOB, IN INTEGER, IN RAW, + IN RAW DEFAULT NULL) +``` + +When invoked as a procedure, `ENCRYPT` returns `BLOB` or `CLOB` data to a user-specified `BLOB`. + +## Parameters + +`dst` + + `dst` specifies the name of a `BLOB` to which to write the output of the `ENCRYPT` procedure. The `ENCRYPT` procedure overwrites any existing data currently in `dst`. + +`src` + + `src` specifies the source data to encrypt. If you're invoking `ENCRYPT` as a function, specify `RAW` data. If invoking `ENCRYPT` as a procedure, specify `BLOB` or `CLOB` data. + +`typ` + + `typ` specifies the block cipher type used by `ENCRYPT` and any modifiers. EDB Postgres Advanced Server supports the block cipher algorithms, modifiers, and cipher suites shown in the table. + +| Block cipher algorithms | | +| ---------------------------------- | ----------------------------------------------------------- | +| `ENCRYPT_DES` | `CONSTANT INTEGER := 1;` | +| `ENCRYPT_3DES` | `CONSTANT INTEGER := 3;` | +| `ENCRYPT_AES` | `CONSTANT INTEGER := 4;` | +| `ENCRYPT_AES128` | `CONSTANT INTEGER := 6;` | +| `ENCRYPT_AES192` | `CONSTANT INTEGER := 192;` | +| `ENCRYPT_AES256` | `CONSTANT INTEGER := 256;` | +| **Block cipher modifiers** | | +| `CHAIN_CBC` | `CONSTANT INTEGER := 256;` | +| `CHAIN_ECB` | `CONSTANT INTEGER := 768;` | +| **Block cipher padding modifiers** | | +| `PAD_PKCS5` | `CONSTANT INTEGER := 4096;` | +| `PAD_NONE` | `CONSTANT INTEGER := 8192;` | +| **Block cipher suites** | | +| `DES_CBC_PKCS5` | `CONSTANT INTEGER := ENCRYPT_DES + CHAIN_CBC + PAD_PKCS5;` | +| `DES3_CBC_PKCS5` | `CONSTANT INTEGER := ENCRYPT_3DES + CHAIN_CBC + PAD_PKCS5;` | +| `AES_CBC_PKCS5` | `CONSTANT INTEGER := ENCRYPT_AES + CHAIN_CBC + PAD_PKCS5;` | + +`key` + + `key` specifies the encryption key. + +`iv` + + `iv` (optional) specifies an initialization vector. By default, `iv` is `NULL`. + +## Examples + +This example uses the `DBMS_CRYPTO.DES_CBC_PKCS5` Block Cipher Suite (a predefined set of algorithms and modifiers) to encrypt a value retrieved from the `passwords` table: + +```sql +CREATE TABLE passwords +( + principal VARCHAR2(90) PRIMARY KEY, -- username + ciphertext RAW(9) -- encrypted password +); +CREATE PROCEDURE set_password(username VARCHAR2, cleartext RAW) AS + typ INTEGER := DBMS_CRYPTO.DES_CBC_PKCS5; + key RAW(128) := 'my secret key'; + iv RAW(100) := 'my initialization vector'; + encrypted RAW(2048); +BEGIN + encrypted := dbms_crypto.encrypt(cleartext, typ, key, iv); + UPDATE passwords SET ciphertext = encrypted WHERE principal = username; +END; +``` + +`ENCRYPT` uses a key value of `my secret key` and an initialization vector of `my initialization vector` when encrypting the password. Specify the same key and initialization vector when decrypting the password. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/03_hash.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/03_hash.mdx new file mode 100644 index 00000000000..b7752199e5a --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/03_hash.mdx @@ -0,0 +1,44 @@ +--- +title: "HASH" +--- + +The `HASH` function uses a user-specified algorithm to return the hash value of a `RAW` or `CLOB` value. The `HASH` function is available in three forms: + +```sql +HASH + ( IN RAW, IN INTEGER) RETURN RAW + +HASH + ( IN CLOB, IN INTEGER) RETURN RAW +``` + +## Parameters + +`src` + + `src` specifies the value for which the hash value is generated. You can specify a `RAW`, `BLOB`, or `CLOB` value. + +`typ` + + `typ` specifies the `HASH` function type. EDB Postgres Advanced Server supports the `HASH` function types shown in the table. + +| HASH functions | | +| ------------------ | ------------------------ | +| `HASH_MD4` | `CONSTANT INTEGER := 1;` | +| `HASH_MD5` | `CONSTANT INTEGER := 2;` | +| `HASH_SH1` | `CONSTANT INTEGER := 3;` | + +## Examples + +This example uses `DBMS_CRYPTO.HASH` to find the `md5` hash value of the string, `cleartext source`: + +```sql +DECLARE + typ INTEGER := DBMS_CRYPTO.HASH_MD5; + hash_value RAW(100); +BEGIN + + hash_value := DBMS_CRYPTO.HASH('cleartext source', typ); + +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/04_mac.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/04_mac.mdx new file mode 100644 index 00000000000..c2e07aa97cd --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/04_mac.mdx @@ -0,0 +1,50 @@ +--- +title: "MAC" +--- + +The `MAC` function uses a user-specified `MAC` function to return the hashed `MAC` value of a `RAW` or `CLOB` value. The `MAC` function is available in three forms: + +```sql +MAC + ( IN RAW, IN INTEGER, IN RAW) RETURN RAW + +MAC + ( IN CLOB, IN INTEGER, IN RAW) RETURN RAW +``` + +## Parameters + +`src` + + `src` specifies the value for which the `MAC` value is generated. Specify a `RAW`, `BLOB`, or `CLOB` value. + +`typ` + + `typ` specifies the `MAC` function used. EDB Postgres Advanced Server supports the `MAC` functions shown in the table. + +| MAC functions | | +| ----------------- | ------------------------ | +| `HMAC_MD5` | `CONSTANT INTEGER := 1;` | +| `HMAC_SH1` | `CONSTANT INTEGER := 2;` | + +`key` + + `key` specifies the key used to calculate the hashed `MAC` value. + +## Examples + +This example finds the hashed `MAC` value of the string `cleartext source`: + +```sql +DECLARE + typ INTEGER := DBMS_CRYPTO.HMAC_MD5; + key RAW(100) := 'my secret key'; + mac_value RAW(100); +BEGIN + + mac_value := DBMS_CRYPTO.MAC('cleartext source', typ, key); + +END; +``` + +`DBMS_CRYPTO.MAC` uses a key value of `my secret` key when calculating the `MAC` value of `cleartext source`. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/05_randombytes.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/05_randombytes.mdx new file mode 100644 index 00000000000..6aadb1c8b37 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/05_randombytes.mdx @@ -0,0 +1,28 @@ +--- +title: "RANDOMBYTES" +--- + +The `RANDOMBYTES` function returns a `RAW` value of the specified length, containing cryptographically random bytes. The signature is: + +```sql +RANDOMBYTES + ( IN INTEGER) RETURNS RAW +``` + +## Parameter + +`number_bytes` + + `number_bytes` specifies the number of random bytes to return. + +## Examples + +This example uses `RANDOMBYTES` to return a value that is 1024 bytes long: + +```sql +DECLARE + result RAW(1024); +BEGIN + result := DBMS_CRYPTO.RANDOMBYTES(1024); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/06_randominteger.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/06_randominteger.mdx new file mode 100644 index 00000000000..b6129aca0fa --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/06_randominteger.mdx @@ -0,0 +1,22 @@ +--- +title: "RANDOMINTEGER" +--- + +The `RANDOMINTEGER()` function returns a random integer between `0` and `268,435,455`. The signature is: + +```sql +RANDOMINTEGER() RETURNS INTEGER +``` + +## Examples + +This example uses the `RANDOMINTEGER` function to return a cryptographically strong random `INTEGER` value: + +```sql +DECLARE + result INTEGER; +BEGIN + result := DBMS_CRYPTO.RANDOMINTEGER(); + DBMS_OUTPUT.PUT_LINE(result); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/07_randomnumber.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/07_randomnumber.mdx new file mode 100644 index 00000000000..2cbdf4e0776 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/07_randomnumber.mdx @@ -0,0 +1,22 @@ +--- +title: "RANDOMNUMBER" +--- + +The `RANDOMNUMBER()` function returns a random number between 0 and 268,435,455. The signature is: + +```sql +RANDOMNUMBER() RETURNS NUMBER +``` + +## Examples + +This example uses the `RANDOMNUMBER` function to return a cryptographically strong random number: + +```sql +DECLARE + result NUMBER; +BEGIN + result := DBMS_CRYPTO.RANDOMNUMBER(); + DBMS_OUTPUT.PUT_LINE(result); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/index.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/index.mdx new file mode 100644 index 00000000000..c8b01075d14 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/index.mdx @@ -0,0 +1,45 @@ +--- +title: "DBMS_CRYPTO" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.15.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.191.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.149.html" +--- + +The `DBMS_CRYPTO` package provides functions and procedures that allow you to encrypt or decrypt `RAW, BLOB`, or `CLOB` data. You can also use `DBMS_CRYPTO` functions to generate cryptographically strong random values. + +The table lists the `DBMS_CRYPTO` functions and procedures. + +| Function/procedure | Return type | Description | +| --------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------- | +| `DECRYPT(src, typ, key, iv)` | `RAW` | Decrypts `RAW` data. | +| `DECRYPT(dst INOUT, src, typ, key, iv)` | N/A | Decrypts `BLOB` data. | +| `DECRYPT(dst INOUT, src, typ, key, iv)` | N/A | Decrypts `CLOB` data. | +| `ENCRYPT(src, typ, key, iv)` | `RAW` | Encrypts `RAW` data. | +| `ENCRYPT(dst INOUT, src, typ, key, iv)` | N/A | Encrypts `BLOB` data. | +| `ENCRYPT(dst INOUT, src, typ, key, iv)` | N/A | Encrypts `CLOB` data. | +| `HASH(src, typ)` | `RAW` | Applies a hash algorithm to `RAW` data. | +| `MAC(src, typ, key)` | `RAW` | Returns the hashed `MAC` value of the given `RAW` data using the specified hash algorithm and key. | +| `MAC(src, typ, key)` | `RAW` | Returns the hashed `MAC` value of the given `CLOB` data using the specified hash algorithm and key. | +| `RANDOMBYTES(number_bytes)` | `RAW` | Returns a specified number of cryptographically strong random bytes. | +| `RANDOMINTEGER()` | `INTEGER` | Returns a random integer. | +| `RANDOMNUMBER()` | `NUMBER` | Returns a random number. | + +`DBMS_CRYPTO` functions and procedures support the following error messages: + +`ORA-28239 - DBMS_CRYPTO.KeyNull` + +`ORA-28829 - DBMS_CRYPTO.CipherSuiteNull` + +`ORA-28827 - DBMS_CRYPTO.CipherSuiteInvalid` + +Unlike Oracle, EDB Postgres Advanced Server doesn't return error `ORA-28233` if you reencrypt previously encrypted information. + +`RAW` and `BLOB` are synonyms for the PostgreSQL `BYTEA` data type. `CLOB` is a synonym for `TEXT`. + +
+ +decrypt encrypt hash mac randombytes randominteger randomnumber + +
diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/01_broken.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/01_broken.mdx new file mode 100644 index 00000000000..0c59524a1ac --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/01_broken.mdx @@ -0,0 +1,41 @@ +--- +title: "BROKEN" +--- + +The `BROKEN` procedure sets the state of a job to either broken or not broken. You can execute a broken job only by using the `RUN` procedure. + +```sql +BROKEN( BINARY_INTEGER, BOOLEAN [, DATE ]) +``` + +## Parameters + +`job` + + Identifier of the job to set as broken or not broken. + +`broken` + + If set to `TRUE`, the job’s state is set to broken. If set to `FALSE`, the job’s state is set to not broken. You can run broken jobs only by using the `RUN` procedure. + +`next_date` + + Date/time when the job is to be run. The default is `SYSDATE`. + +## Examples + +Set the state of a job with job identifier 104 to broken: + +```sql +BEGIN + DBMS_JOB.BROKEN(104,true); +END; +``` + +Change the state back to not broken: + +```sql +BEGIN + DBMS_JOB.BROKEN(104,false); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/02_change.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/02_change.mdx new file mode 100644 index 00000000000..e39bd021a95 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/02_change.mdx @@ -0,0 +1,47 @@ +--- +title: "CHANGE" +--- + +The `CHANGE` procedure modifies certain job attributes including the stored procedure to run, the next date/time the job runs, and how often it runs. + +```sql +CHANGE( BINARY_INTEGER VARCHAR2, DATE, + VARCHAR2, BINARY_INTEGER, BOOLEAN) +``` + +## Parameters + +`job` + + Identifier of the job to modify. + +`what` + + Stored procedure name. Set this parameter to null if you want the existing value to remain unchanged. + +`next_date` + + Date/time to run the job next. Set this parameter to null if you want the existing value to remain unchanged. + +`interval` + + Date function that, when evaluated, provides the next date/time to run the job. Set this parameter to null if you want the existing value to remain unchanged. + +`instance` + + This argument is ignored but is included for compatibility. + +`force` + + This argument is ignored but is included for compatibility. + +## Examples + +Change the job to run next on December 13, 2007. Leave other parameters unchanged. + +```sql +BEGIN + DBMS_JOB.CHANGE(104,NULL,TO_DATE('13-DEC-07','DD-MON-YY'),NULL, NULL, + NULL); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/03_interval.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/03_interval.mdx new file mode 100644 index 00000000000..204a898a1e3 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/03_interval.mdx @@ -0,0 +1,29 @@ +--- +title: "INTERVAL" +--- + +The `INTERVAL` procedure sets how often to run a job. + +```sql +INTERVAL( BINARY_INTEGER, VARCHAR2) +``` + +## Parameters + +`job` + + Identifier of the job to modify. + +`interval` + + Date function that, when evaluated, provides the next date/time to run the job. If `interval` is `NULL` and the job is complete, the job is removed from the queue. + +## Examples + +Change the job to run once a week: + +```sql +BEGIN + DBMS_JOB.INTERVAL(104,'SYSDATE + 7'); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/04_next_date.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/04_next_date.mdx new file mode 100644 index 00000000000..03832b89ec3 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/04_next_date.mdx @@ -0,0 +1,29 @@ +--- +title: "NEXT_DATE" +--- + +The `NEXT_DATE` procedure sets the date/time to run the job next. + +```sql +NEXT_DATE( BINARY_INTEGER, DATE) +``` + +## Parameters + +`job` + + Identifier of the job whose next run date you want to set. + +`next_date` + + Date/time when you want the job run next. + +## Examples + +Change the job to run next on December 14, 2007: + +```sql +BEGIN + DBMS_JOB.NEXT_DATE(104, TO_DATE('14-DEC-07','DD-MON-YY')); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/05_remove.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/05_remove.mdx new file mode 100644 index 00000000000..bfe97f2c78f --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/05_remove.mdx @@ -0,0 +1,25 @@ +--- +title: "REMOVE" +--- + +The `REMOVE` proceduzre deletes the specified job from the database. You must resubmit the job using the `SUBMIT` procedure to execute it again. The stored procedure that was associated with the job isn't deleted. + +```sql +REMOVE( BINARY_INTEGER) +``` + +## Parameter + +`job` + + Identifier of the job to remove from the database. + +## Examples + +Remove a job from the database: + +```sql +BEGIN + DBMS_JOB.REMOVE(104); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/06_run.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/06_run.mdx new file mode 100644 index 00000000000..e9d183c8db6 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/06_run.mdx @@ -0,0 +1,25 @@ +--- +title: "RUN" +--- + +The `RUN` procedure forces the job to run even if its state is broken. + +```sql +RUN( BINARY_INTEGER) +``` + +## Parameter + +`job` + + Identifier of the job to run. + +## Examples + +Force a job to run. + +```sql +BEGIN + DBMS_JOB.RUN(104); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/07_submit.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/07_submit.mdx new file mode 100644 index 00000000000..03e4a832cf9 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/07_submit.mdx @@ -0,0 +1,66 @@ +--- +title: "SUBMIT" +--- + +The `SUBMIT` procedure creates a job definition and stores it in the database. A job consists of: +- A job identifier +- The stored procedure to execute +- When to first run the job +- A date function that calculates the next date/time for the job to run + +```sql +SUBMIT( OUT BINARY_INTEGER, VARCHAR2 + [, DATE [, VARCHAR2 [, BOOLEAN ]]]) +``` + +## Parameters + +`job` + + Identifier assigned to the job. + +`what` + + Name of the stored procedure for the job to execute. + +`next_date` + + Date/time to run the job next. The default is `SYSDATE`. + +`interval` + + Date function that, when evaluated, provides the next date/time for the job to run. If `interval` is set to null, then the job runs only once. Null is the default. + +`no_parse` + + If set to `TRUE`, don't syntax-check the stored procedure upon job creation. Check only when the job first executes. If set to `FALSE`, check the procedure upon job creation. The default is `FALSE`. + +!!! Note + The `no_parse` option isn't supported in this implementation of `SUBMIT()`. It's included only for compatibility. + +## Examples + +This example creates a job using the stored procedure `job_proc`. The job executes immediately and runs once a day after that, as set by the `interval` parameter, `SYSDATE + 1`. + +```sql +DECLARE + jobid INTEGER; +BEGIN + DBMS_JOB.SUBMIT(jobid,'job_proc;',SYSDATE, + 'SYSDATE + 1'); + DBMS_OUTPUT.PUT_LINE('jobid: ' || jobid); +END; + +jobid: 104 +``` + +The job immediately executes the procedure `job_proc`, populating the table `jobrun` with a row: + +```sql +SELECT * FROM jobrun; +__OUTPUT__ + runtime +------------------------------------- + job_proc run at 2007-12-11 11:43:25 +(1 row) +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/08_what.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/08_what.mdx new file mode 100644 index 00000000000..c0f9abec666 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/08_what.mdx @@ -0,0 +1,29 @@ +--- +title: "WHAT" +--- + +The `WHAT` procedure changes the stored procedure that the job executes. + +```sql +WHAT( BINARY_INTEGER, VARCHAR2) +``` + +## Parameters + +`job` + + Identifier of the job whose stored procedure you want to change. + +`what` + + Name of the stored procedure to execute. + +## Examples + +Change the job to run the `list_emp` procedure: + +```sql +BEGIN + DBMS_JOB.WHAT(104,'list_emp;'); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/index.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/index.mdx new file mode 100644 index 00000000000..c1d9650de3c --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/index.mdx @@ -0,0 +1,60 @@ +--- +title: "DBMS_JOB" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.16.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.192.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.150.html" +--- + +The `DBMS_JOB` package lets you create, schedule, and manage jobs. A job runs a stored procedure that was previously stored in the database. The `SUBMIT` procedure creates and stores a job definition. A job identifier is assigned to a job with a stored procedure and the attributes describing when and how often to run the job. + +This package relies on the pgAgent scheduler. By default, the EDB Postgres Advanced Server installer installs pgAgent, but you must start the pgAgent service manually before using `DBMS_JOB`. If you attempt to use this package to schedule a job after uninstalling pgAgent, `DBMS_JOB` reports an error. `DBMS_JOB` verifies that pgAgent is installed but doesn't verify that the service is running. + +EDB Postgres Advanced Server's implementation of `DBMS_JOB` is a partial implementation when compared to Oracle's version. The following table lists the supported `DBMS_JOB` procedures. + +| Function/procedure | Return type | Description | +| ---------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `BROKEN(job, broken [, next_date ])` | n/a | Specify that a given job is either broken or not broken. | +| `CHANGE(job, what, next_date, interval, instance, force)` | n/a | Change the job’s parameters. | +| `INTERVAL(job, interval)` | n/a | Set the execution frequency by means of a date function that is recalculated each time the job is run. This value becomes the next date/time for execution. | +| `NEXT_DATE(job, next_date)` | n/a | Set the next date/time to run the job. | +| `REMOVE(job)` | n/a | Delete the job definition from the database. | +| `RUN(job)` | n/a | Force execution of a job even if it's marked broken. | +| `SUBMIT(job OUT, what [, next_date [, interval [, no_parse ]]])` | n/a | Create a job and store its definition in the database. | +| `WHAT(job, what)` | n/a | Change the stored procedure run by a job. | + +Before using `DBMS_JOB`, a database superuser must create the pgAgent and `DBMS_JOB` extension. Use the psql client to connect to a database and invoke the command: + +```sql +CREATE EXTENSION pgagent; +CREATE EXTENSION dbms_job; +``` + +When and how often a job runs depends on two interacting parameters: `next_date` and `interval`. The `next_date` parameter is a date/time value that specifies the next date/time to execute the job. The `interval` parameter is a string that contains a date function that evaluates to a date/time value. + +Before the job executes, the expression in the `interval` parameter is evaluated. The resulting value replaces the `next_date` value stored with the job. The job is then executed. In this manner, the expression in `interval` is repeatedly reevaluated before each job executes, supplying the `next_date` date/time for the next execution. + +!!! Note + To start the pgAgent server and execute the job, the database user must be the same user that created a job and schedule. + +The following examples use the stored procedure `job_proc`. The procedure inserts a timestamp into the table `jobrun`, which contains a single column, `VARCHAR2`. + +```sql +CREATE TABLE jobrun ( + runtime VARCHAR2(40) +); + +CREATE OR REPLACE PROCEDURE job_proc +IS +BEGIN + INSERT INTO jobrun VALUES ('job_proc run at ' || TO_CHAR(SYSDATE, + 'yyyy-mm-dd hh24:mi:ss')); +END; +``` + +
+ +broken change interval next_date remove run submit what + +
diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/01_append.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/01_append.mdx new file mode 100644 index 00000000000..4c881a3978a --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/01_append.mdx @@ -0,0 +1,19 @@ +--- +title: "APPEND" +--- + +The `APPEND` procedure appends one large object to another. Both large objects must be the same type. + +```sql +APPEND( IN OUT { BLOB | CLOB }, { BLOB | CLOB }) +``` + +## Parameters + +`dest_lob` + + Large object locator for the destination object. Must be the same data type as `src_lob`. + +`src_lob` + + Large object locator for the source object. Must be the same data type as `dest_lob`. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/02_compare.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/02_compare.mdx new file mode 100644 index 00000000000..5b9f47f9586 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/02_compare.mdx @@ -0,0 +1,37 @@ +--- +title: "COMPARE" +--- + +The `COMPARE` procedure performs an exact byte-by-byte comparison of two large objects for a given length at given offsets. The large objects being compared must be the same data type. + +```sql + INTEGER COMPARE( { BLOB | CLOB }, + { BLOB | CLOB } + [, INTEGER [, INTEGER [, INTEGER ]]]) +``` + +## Parameters + +`lob_1` + + Large object locator of the first large object to compare. Must be the same data type as `lob_2`. + +`lob_2` + + Large object locator of the second large object to compare. Must be the same data type as `lob_1`. + +`amount` + + If the data type of the large objects is `BLOB`, then the comparison is made for `amount` bytes. If the data type of the large objects is `CLOB`, then the comparison is made for `amount` characters. The default is the maximum size of a large object. + +`offset_1` + + Position in the first large object to begin the comparison. The first byte/character is offset 1. The default is 1. + +`offset_2` + + Position in the second large object to begin the comparison. The first byte/character is offset 1. The default is 1. + +`status` + + Zero if both large objects are exactly the same for the specified length for the specified offsets. Nonzero if the objects aren't the same. `NULL` if `amount`, `offset_1`, or `offset_2` are less than zero. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/03_converttoblob.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/03_converttoblob.mdx new file mode 100644 index 00000000000..556fc0c4774 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/03_converttoblob.mdx @@ -0,0 +1,58 @@ +--- +title: "CONVERTTOBLOB" +--- + +The `CONVERTTOBLOB` procedure converts character data to binary. + +```sql +CONVERTTOBLOB( IN OUT BLOB, CLOB, + INTEGER, IN OUT INTEGER, + IN OUT INTEGER, NUMBER, + IN OUT INTEGER, OUT INTEGER) +``` + +## Parameters + +`dest_lob` + + `BLOB` large object locator to which to convert the character data. + +`src_clob` + + `CLOB` large object locator of the character data to convert. + +`amount` + + Number of characters of `src_clob` to convert. + +`dest_offset IN` + + Position in bytes in the destination `BLOB` where you want to begin writing the source `CLOB`. The first byte is offset 1. + +`dest_offset OUT` + + Position in bytes in the destination `BLOB` after the write operation completes. The first byte is offset 1. + +`src_offset IN` + + Position in characters in the source `CLOB` where you want to begin conversion to the destination `BLOB`. The first character is offset 1. + +`src_offset OUT` + + Position in characters in the source `CLOB` after the conversion operation completes. The first character is offset 1. + +`blob_csid` + + Character set ID of the converted destination `BLOB`. + +`lang_context IN` + + Language context for the conversion. The default value of `0` is typically used for this setting. + +`lang_context OUT` + + Language context after the conversion completes. + +`warning` + + `0` if the conversion was successful, `1` if a character can't be converted. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/04_converttoclob.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/04_converttoclob.mdx new file mode 100644 index 00000000000..6d53a4626e5 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/04_converttoclob.mdx @@ -0,0 +1,58 @@ +--- +title: "CONVERTTOCLOB" +--- + +The `CONVERTTOCLOB` procedure converts binary data to character. + +```sql +CONVERTTOCLOB( IN OUT CLOB, BLOB, + INTEGER, IN OUT INTEGER, + IN OUT INTEGER, NUMBER, + IN OUT INTEGER, OUT INTEGER) +``` + +## Parameters + +`dest_lob` + + `CLOB` large object locator to which to convert the binary data. + +`src_blob` + + `BLOB` large object locator of the binary data to convert. + +`amount` + + Number of bytes of `src_blob` to convert. + +`dest_offset IN` + + Position in characters in the destination `CLOB` where you want to begin writing the source `BLOB`. The first character is offset 1. + +`dest_offset OUT` + + Position in characters in the destination `CLOB` after the write operation completes. The first character is offset 1. + +`src_offset IN` + + Position in bytes in the source `BLOB` where you want the conversion to the destination `CLOB` to begin. The first byte is offset 1. + +`src_offset OUT` + + Position in bytes in the source `BLOB` after the conversion operation completes. The first byte is offset 1. + +`blob_csid` + + Character set ID of the converted destination `CLOB`. + +`lang_context IN` + + Language context for the conversion. The default value of `0` is typically used for this setting. + +`lang_context OUT` + + Language context after the conversion completes. + +`warning` + + `0` if the conversion was successful, `1` if a character can't be converted. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/05_copy.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/05_copy.mdx new file mode 100644 index 00000000000..e35684fe06d --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/05_copy.mdx @@ -0,0 +1,34 @@ +--- +title: "COPY" +--- + +The `COPY` procedure copies one large object to another. The source and destination large objects must be the same data type. + +```sql +COPY( IN OUT { BLOB | CLOB }, +{ BLOB | CLOB }, + INTEGER + [, INTEGER [, INTEGER ]]) +``` + +## Parameters + +`dest_lob` + + Large object locator of the large object to which you want to copy `src_lob`. Must be the same data type as `src_lob`. + +`src_lob` + + Large object locator of the large object to copy to `dest_lob`. Must be the same data type as `dest_lob`. + +`amount` + + Number of bytes/characters of `src_lob` to copy. + +`dest_offset` + + Position in the destination large object where you want writing of the source large object to begin. The first position is offset 1. The default is 1. + +`src_offset` + + Position in the source large object where you want copying to the destination large object to begin. The first position is offset 1. The default is 1. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/06_erase.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/06_erase.mdx new file mode 100644 index 00000000000..62057d69f05 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/06_erase.mdx @@ -0,0 +1,28 @@ +--- +title: "ERASE" +--- + +The `ERASE` procedure erases a portion of a large object. To erase a large object means to replace the specified portion with zero-byte fillers for `BLOB` or with spaces for `CLOB`. The actual size of the large object isn't altered. + +```sql +ERASE( IN OUT { BLOB | CLOB }, IN OUT INTEGER + [, INTEGER ]) +``` + +## Parameters + +`lob_loc` + + Large object locator of the large object to erase. + +`amount IN` + + Number of bytes/characters to erase. + +`amount OUT` + + Number of bytes/characters erased. This value can be smaller than the input value if the end of the large object is reached before `amount` bytes/characters are erased. + +`offset` + + Position in the large object where erasing begins. The first byte/character is position 1. The default is 1. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/07_get_storage_limit.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/07_get_storage_limit.mdx new file mode 100644 index 00000000000..3b9560d75a6 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/07_get_storage_limit.mdx @@ -0,0 +1,21 @@ +--- +title: "GET_STORAGE_LIMIT" +--- + +The `GET_STORAGE_LIMIT` function returns the limit on the largest allowable large object. + +```sql + INTEGER GET_STORAGE_LIMIT( BLOB) + + INTEGER GET_STORAGE_LIMIT( CLOB) +``` + +## Parameters + +`size` + + Maximum allowable size of a large object in this database. + +`lob_loc` + + This parameter is ignored but is included for compatibility. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/08_getlength.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/08_getlength.mdx new file mode 100644 index 00000000000..3b0184411d2 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/08_getlength.mdx @@ -0,0 +1,21 @@ +--- +title: "GETLENGTH" +--- + +The `GETLENGTH` function returns the length of a large object. + +```sql + INTEGER GETLENGTH( BLOB) + + INTEGER GETLENGTH( CLOB) +``` + +## Parameters + +`lob_loc` + + Large object locator of the large object whose length to obtain. + +`amount` + + Length of the large object for `BLOB` or characters for `CLOB`, in bytes. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/09_instr.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/09_instr.mdx new file mode 100644 index 00000000000..3eb8ccc44a2 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/09_instr.mdx @@ -0,0 +1,32 @@ +--- +title: "INSTR" +--- + +The `INSTR` function returns the location of the nth occurrence of a given pattern in a large object. + +```sql + INTEGER INSTR( { BLOB | CLOB }, + { RAW | VARCHAR2 } [, INTEGER [, INTEGER ]]) +``` + +## Parameters + +`lob_loc` + + Large object locator of the large object in which to search for `pattern`. + +`pattern` + + Pattern of bytes or characters to match against the large object, `lob`. `pattern` must be `RAW` if `lob_loc` is a `BLOB`. `pattern` must be `VARCHAR2` if `lob_loc` is a `CLOB`. + +`offset` + + Position in `lob_loc` to start search for `pattern`. The first byte/character is position 1. The default is 1. + +`nth` + + Search for `pattern`, `nth` number of times starting at the position given by `offset`. The default is 1. + +`position` + + Position in the large object where `pattern` appears the `nth` time, starting from the position given by `offset`. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/10_read.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/10_read.mdx new file mode 100644 index 00000000000..7e3ebbaed47 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/10_read.mdx @@ -0,0 +1,32 @@ +--- +title: "READ" +--- + +The `READ` procedure reads a portion of a large object into a buffer. + +```sql +READ( { BLOB | CLOB }, IN OUT BINARY_INTEGER, + INTEGER, OUT { RAW | VARCHAR2 }) +``` + +## Parameters + +`lob_loc` + + Large object locator of the large object to read. + +`amount IN` + + Number of bytes/characters to read. + +`amount OUT` + + Number of bytes/characters read. If there's no more data to read, then `amount` returns `0` and a `DATA_NOT_FOUND` exception is thrown. + +`offset` + + Position to begin reading. The first byte/character is position 1. + +`buffer` + + Variable to receive the large object. If `lob_loc` is a `BLOB`, then `buffer` must be `RAW`. If `lob_loc` is a `CLOB`, then `buffer` must be `VARCHAR2`. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/11_substr.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/11_substr.mdx new file mode 100644 index 00000000000..cfb32b1f1e3 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/11_substr.mdx @@ -0,0 +1,28 @@ +--- +title: "SUBSTR" +--- + +The `SUBSTR` function returns a portion of a large object. + +```sql + { RAW | VARCHAR2 } SUBSTR( { BLOB | CLOB } + [, INTEGER [, INTEGER ]]) +``` + +## Parameters + +`lob_loc` + + Large object locator of the large object to read. + +`amount` + + Number of bytes/characters to return. Default is 32,767. + +`offset` + + Position in the large object to begin returning data. The first byte/character is position 1. The default is 1. + +`data` + + Returned portion of the large object to read. If `lob_loc` is a `BLOB`, the return data type is `RAW`. If `lob_loc` is a `CLOB`, the return data type is `VARCHAR2`. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/12_trim.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/12_trim.mdx new file mode 100644 index 00000000000..c3f3c34e5db --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/12_trim.mdx @@ -0,0 +1,19 @@ +--- +title: "TRIM" +--- + +The `TRIM` procedure truncates a large object to the specified length. + +```sql +TRIM( IN OUT { BLOB | CLOB }, INTEGER) +``` + +## Parameters + +`lob_loc` + + Large object locator of the large object to trim. + +`newlen` + + Number of bytes/characters to which you want to trim the large object. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/13_write.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/13_write.mdx new file mode 100644 index 00000000000..cb947147816 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/13_write.mdx @@ -0,0 +1,29 @@ +--- +title: "WRITE" +--- + +The `WRITE` procedure writes data into a large object. Any existing data in the large object at the specified offset for the given length is overwritten by data given in the buffer. + +```sql +WRITE( IN OUT { BLOB | CLOB }, + BINARY_INTEGER, + INTEGER, { RAW | VARCHAR2 }) +``` + +## Parameters + +`lob_loc` + + Large object locator of the large object to write. + +`amount` + + The number of bytes/characters in `buffer` to write to the large object. + +`offset` + + The offset in bytes/characters from the beginning of the large object (origin is 1) for the write operation to begin. + +`buffer` + + Contains data to write to the large object. If `lob_loc` is a `BLOB`, then `buffer` must be `RAW`. If `lob_loc` is a `CLOB`, then `buffer` must be `VARCHAR2`. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/14_writeappend.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/14_writeappend.mdx new file mode 100644 index 00000000000..13cfdc0c3b7 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/14_writeappend.mdx @@ -0,0 +1,24 @@ +--- +title: "WRITEAPPEND" +--- + +The `WRITEAPPEND` procedure adds data to the end of a large object. + +```sql +WRITEAPPEND( IN OUT { BLOB | CLOB }, + BINARY_INTEGER, { RAW | VARCHAR2 }) +``` + +## Parameters + +`lob_loc` + + Large object locator of the large object to which you want to append the data. + +`amount` + + Number of bytes/characters from `buffer` to append to the large object. + +`buffer` + + Data to append to the large object. If `lob_loc` is a `BLOB`, then `buffer` must be `RAW`. If `lob_loc` is a `CLOB`, then `buffer` must be `VARCHAR2`. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/index.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/index.mdx new file mode 100644 index 00000000000..c2a40066616 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/index.mdx @@ -0,0 +1,58 @@ +--- +title: "DBMS_LOB" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.17.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.193.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.151.html" +--- + +The `DBMS_LOB` package lets you operate on large objects. The following table lists the supported functions and procedures. EDB Postgres Advanced Server's implementation of `DBMS_LOB` is a partial implementation when compared to Oracle's version. Only the functions and procedures listed in this table are supported. + +| Function/procedure | Return type | Description | +| -------------------------------------------------------------------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------- | +| `APPEND(dest_lob IN OUT, src_lob)` | n/a | Appends one large object to another. | +| `COMPARE(lob_1, lob_2 [, amount [, offset_1 [, offset_2 ]]])` | `INTEGER` | Compares two large objects. | +| `CONVERTOBLOB(dest_lob IN OUT, src_clob, amount, dest_offset IN OUT, src_offset IN OUT, blob_csid, lang_context IN OUT, warning OUT)` | n/a | Converts character data to binary. | +| `CONVERTTOCLOB(dest_lob IN OUT, src_blob, amount, dest_offset IN OUT, src_offset IN OUT, blob_csid, lang_context IN OUT, warning OUT)` | n/a | Converts binary data to character. | +| `COPY(dest_lob IN OUT, src_lob, amount [, dest_offset [, src_offset ]])` | n/a | Copies one large object to another. | +| `ERASE(lob_loc IN OUT, amount IN OUT [, offset ])` | n/a | Erases a large object. | +| `GET_STORAGE_LIMIT(lob_loc)` | `INTEGER` | Gets the storage limit for large objects. | +| `GETLENGTH(lob_loc)` | `INTEGER` | Gets the length of the large object. | +| `INSTR(lob_loc, pattern [, offset [, nth ]])` | `INTEGER` | Gets the position of the nth occurrence of a pattern in the large object starting at `offset` | +| `READ(lob_loc, amount IN OUT, offset, buffer OUT)` | n/a | Reads a large object. | +| `SUBSTR(lob_loc [, amount [, offset ]])` | `RAW, VARCHAR2` | Gets part of a large object. | +| `TRIM(lob_loc IN OUT, newlen)` | n/a | Trims a large object to the specified length. | +| `WRITE(lob_loc IN OUT, amount, offset, buffer)` | n/a | Writes data to a large object. | +| `WRITEAPPEND(lob_loc IN OUT, amount, buffer)` | n/a | Writes data from the buffer to the end of a large object. | + + +The following table lists the public variables available in the package. + +| Public variables | Data type | Value | +| ------------------------- | ------------- | ------------ | +| `compress off` | `INTEGER` | `0` | +| `compress_on` | `INTEGER` | `1` | +| `deduplicate_off` | `INTEGER` | `0` | +| `deduplicate_on` | `INTEGER` | `4` | +| `default_csid` | `INTEGER` | `0` | +| `default_lang_ctx` | `INTEGER` | `0` | +| `encrypt_off` | `INTEGER` | `0` | +| `encrypt_on` | `INTEGER` | `1` | +| `file_readonly` | `INTEGER` | `0` | +| `lobmaxsize` | `INTEGER` | `1073741823` | +| `lob_readonly` | `INTEGER` | `0` | +| `lob_readwrite` | `INTEGER` | `1` | +| `no_warning` | `INTEGER` | `0` | +| `opt_compress` | `INTEGER` | `1` | +| `opt_deduplicate` | `INTEGER` | `4` | +| `opt_encrypt` | `INTEGER` | `2` | +| `warn_inconvertible_char` | `INTEGER` | `1` | + +Lengths and offsets are measured in bytes if the large objects are `BLOB`. Lengths and offsets are measured in characters if the large objects are `CLOB`. + +
+ +append compare converttoblob converttoclob copy erase get_storage_limit getlength instr read substr trim write writeappend + +
diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/07_dbms_lock.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/07_dbms_lock.mdx new file mode 100644 index 00000000000..2e975cce04e --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/07_dbms_lock.mdx @@ -0,0 +1,30 @@ +--- +title: "DBMS_LOCK" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.18.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.194.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.152.html" +--- + +EDB Postgres Advanced Server provides support for the `DBMS_LOCK.SLEEP` procedure. + +| Function/procedure | Return type | Description | +| ------------------ | ----------- | --------------------------------------------------------- | +| `SLEEP(seconds)` | n/a | Suspends a session for the specified number of `seconds`. | + +EDB Postgres Advanced Server's implementation of `DBMS_LOCK` is a partial implementation when compared to Oracle's version. Only `DBMS_LOCK.SLEEP` is supported. + +## SLEEP + +The `SLEEP` procedure suspends the current session for the specified number of seconds. + +```sql +SLEEP( NUMBER) +``` + +### Parameters + +`seconds` + + `seconds` specifies the number of seconds for which you want to suspend the session. `seconds` can be a fractional value. For example, enter `1.75` to specify one and three-fourths of a second. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/01_get_mv_dependencies.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/01_get_mv_dependencies.mdx new file mode 100644 index 00000000000..1ac0e5bdbdb --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/01_get_mv_dependencies.mdx @@ -0,0 +1,34 @@ +--- +title: "GET_MV_DEPENDENCIES" +--- + +When given the name of a materialized view, `GET_MV_DEPENDENCIES` returns a list of items that depend on the specified view. The signature is: + +```sql +GET_MV_DEPENDENCIES( + IN VARCHAR2, + OUT VARCHAR2); +``` + +## Parameters + +`list` + + `list` specifies the name of a materialized view or a comma-separated list of materialized view names. + +`deplist` + + `deplist` is a comma-separated list of schema-qualified dependencies. `deplist` is a `VARCHAR2` value. + +## Examples + +This example displays a list of the dependencies on a materialized view named `public.emp_view`. + +```sql +DECLARE + deplist VARCHAR2(1000); +BEGIN + DBMS_MVIEW.GET_MV_DEPENDENCIES('public.emp_view', deplist); + DBMS_OUTPUT.PUT_LINE('deplist: ' || deplist); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/02_refresh.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/02_refresh.mdx new file mode 100644 index 00000000000..fbd4a451607 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/02_refresh.mdx @@ -0,0 +1,89 @@ +--- +title: "REFRESH" +--- + +Use the `REFRESH` procedure to refresh all views specified in either a comma-separated list of view names or a table of `DBMS_UTILITY.UNCL_ARRAY` values. The procedure has two signatures. Use the first form when specifying a comma-separated list of view names: + +```sql +REFRESH( + IN VARCHAR2, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN BOOLEAN DEFAULT TRUE, + IN BOOLEAN DEFAULT FALSE, + IN NUMBER DEFAULT 1, + IN NUMBER DEFAULT 0, + IN NUMBER DEFAULT 0, + IN BOOLEAN DEFAULT TRUE, + IN BOOLEAN DEFAULT FALSE); +``` + +Use the second form to specify view names in a table of `DBMS_UTILITY.UNCL_ARRAY` values: + +```sql +REFRESH( + IN OUT DBMS_UTILITY.UNCL_ARRAY, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN BOOLEAN DEFAULT TRUE, + IN BOOLEAN DEFAULT FALSE, + IN NUMBER DEFAULT 1, + IN NUMBER DEFAULT 0, + IN NUMBER DEFAULT 0, + IN BOOLEAN DEFAULT TRUE, + IN BOOLEAN DEFAULT FALSE); +``` + +## Parameters + +`list` + + `list` is a `VARCHAR2` value that specifies the name of a materialized view or a comma-separated list of materialized view names. The names can be schema-qualified. + +`tab` + + `tab` is a table of `DBMS_UTILITY.UNCL_ARRAY` values that specify names of a materialized view. + +`method` + + `method` is a `VARCHAR2` value that specifies the refresh method to apply to the specified views. The only supported method is `C`, which performs a complete refresh of the view. + +`rollback_seg` + + `rollback_seg` is accepted for compatibility and ignored. The default is `NULL`. + +`push_deferred_rpc` + + `push_deferred_rpc` is accepted for compatibility and ignored. The default is `TRUE`. + +`refresh_after_errors` + + `refresh_after_errors` is accepted for compatibility and ignored. The default is `FALSE`. + +`purge_option` + + `purge_option` is accepted for compatibility and ignored. The default is `1`. + +`parallelism` + + `parallelism` is accepted for compatibility and ignored. The default is `0`. + +`heap_size IN NUMBER DEFAULT 0`, + + `heap_size` is accepted for compatibility and ignored. The default is `0`. + +`atomic_refresh` + + `atomic_refresh` is accepted for compatibility and ignored. The default is `TRUE`. + +`nested` + + `nested` is accepted for compatibility and ignored. The default is `FALSE`. + +## Examples + +This example uses `DBMS_MVIEW.REFRESH` to perform a complete refresh on the `public.emp_view` materialized view: + +```sql +EXEC DBMS_MVIEW.REFRESH(list => 'public.emp_view', method => 'C'); +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/03_refresh_all_mviews.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/03_refresh_all_mviews.mdx new file mode 100644 index 00000000000..dafb717b8af --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/03_refresh_all_mviews.mdx @@ -0,0 +1,50 @@ +--- +title: "REFRESH_ALL_MVIEWS" +--- + +Use the `REFRESH_ALL_MVIEWS` procedure to refresh any materialized views that weren't refreshed since the table or view on which the view depends was modified. The signature is: + +```sql +REFRESH_ALL_MVIEWS( + OUT BINARY_INTEGER, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN BOOLEAN DEFAULT FALSE, + IN BOOLEAN DEFAULT TRUE); +``` + +## Parameters + +`number_of_failures` + + `number_of_failures` is a `BINARY_INTEGER` that specifies the number of failures that occurred during the refresh. + +`method` + + `method` is a `VARCHAR2` value that specifies the refresh method to apply to the specified views. The only supported method is `C`, which performs a complete refresh of the view. + +`rollback_seg` + + `rollback_seg` is accepted for compatibility and ignored. The default is `NULL`. + +`refresh_after_errors` + + `refresh_after_errors` is accepted for compatibility and ignored. The default is `FALSE`. + +`atomic_refresh` + + `atomic_refresh` is accepted for compatibility and ignored. The default is `TRUE`. + +## Examples + +This example performs a complete refresh on all materialized views: + +```sql +DECLARE + errors INTEGER; +BEGIN + DBMS_MVIEW.REFRESH_ALL_MVIEWS(errors, method => 'C'); +END; +``` + +Upon completion, `errors` contains the number of failures. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/04_refresh_dependent.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/04_refresh_dependent.mdx new file mode 100644 index 00000000000..35242daf6fc --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/04_refresh_dependent.mdx @@ -0,0 +1,80 @@ +--- +title: "REFRESH_DEPENDENT" +--- + +Use the `REFRESH_DEPENDENT` procedure to refresh all material views that depend on the views specified in the call to the procedure. You can specify a comma-separated list or provide the view names in a table of `DBMS_UTILITY.UNCL_ARRAY` values. + +Use the first form of the procedure to refresh all material views that depend on the views specified in a comma-separated list: + +```sql +REFRESH_DEPENDENT( + OUT BINARY_INTEGER, + IN VARCHAR2, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL + IN BOOLEAN DEFAULT FALSE, + IN BOOLEAN DEFAULT TRUE, + IN BOOLEAN DEFAULT FALSE); +``` + +Use the second form of the procedure to refresh all material views that depend on the views specified in a table of `DBMS_UTILITY.UNCL_ARRAY` values: + +```sql +REFRESH_DEPENDENT( + OUT BINARY_INTEGER, + IN DBMS_UTILITY.UNCL_ARRAY, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN BOOLEAN DEFAULT FALSE, + IN BOOLEAN DEFAULT TRUE, + IN BOOLEAN DEFAULT FALSE); +``` + +## Parameters + +`number_of_failures` + + `number_of_failures` is a `BINARY_INTEGER` that contains the number of failures that occurred during the refresh operation. + +`list` + + `list` is a `VARCHAR2` value that specifies the name of a materialized view or a comma-separated list of materialized view names. The names can be schema-qualified. + +`tab` + + `tab` is a table of `DBMS_UTILITY.UNCL_ARRAY` values that specify the names of a materialized view. + +`method` + + `method` is a `VARCHAR2` value that specifies the refresh method to apply to the specified views. The only supported method is `C`, which performs a complete refresh of the view. + +`rollback_seg` + + `rollback_seg` is accepted for compatibility and ignored. The default is `NULL`. + +`refresh_after_errors` + + `refresh_after_errors` is accepted for compatibility and ignored. The default is `FALSE`. + +`atomic_refresh` + + `atomic_refresh` is accepted for compatibility and ignored. The default is `TRUE`. + +`nested` + + `nested` is accepted for compatibility and ignored. The default is `FALSE`. + +## Examples + +This example performs a complete refresh on all materialized views that depend on a materialized view named `emp_view` that resides in the `public` schema: + +```sql +DECLARE + errors INTEGER; +BEGIN + DBMS_MVIEW.REFRESH_DEPENDENT(errors, list => 'public.emp_view', method => +'C'); +END; +``` + +Upon completion, `errors` contains the number of failures. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/index.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/index.mdx new file mode 100644 index 00000000000..a82edec3cf5 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/index.mdx @@ -0,0 +1,27 @@ +--- +title: "DBMS_MVIEW" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.19.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.195.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.153.html" +--- + +Use procedures in the `DBMS_MVIEW` package to manage and refresh materialized views and their dependencies. EDB Postgres Advanced Server provides support for the following `DBMS_MVIEW` procedures: + +| Procedure | Return type | Description | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `GET_MV_DEPENDENCIES(list VARCHAR2, deplist VARCHAR2);` | n/a | The `GET_MV_DEPENDENCIES` procedure returns a list of dependencies for a specified view. | +| `REFRESH(list VARCHAR2, method VARCHAR2, rollback_seg VARCHAR2 , push_deferred_rpc BOOLEAN, refresh_after_errors BOOLEAN , purge_option NUMBER, parallelism NUMBER, heap_size NUMBER , atomic_refresh BOOLEAN , nested BOOLEAN);` | n/a | This variation of the `REFRESH` procedure refreshes all views named in a comma-separated list of view names. | +| `REFRESH(tab dbms_utility.uncl_array, method VARCHAR2, rollback_seg VARCHAR2, push_deferred_rpc BOOLEAN, refresh_after_errors BOOLEAN, purge_option NUMBER, parallelism NUMBER, heap_size NUMBER, atomic_refresh BOOLEAN, nested BOOLEAN);` | n/a | This variation of the `REFRESH` procedure refreshes all views named in a table of `dbms_utility.uncl_array` values. | +| `REFRESH_ALL_MVIEWS(number_of_failures BINARY_INTEGER, method VARCHAR2, rollback_seg VARCHAR2, refresh_after_errors BOOLEAN, atomic_refresh BOOLEAN);` | n/a | The `REFRESH_ALL_MVIEWS` procedure refreshes all materialized views. | +| `REFRESH_DEPENDENT(number_of_failures BINARY_INTEGER, list VARCHAR2, method VARCHAR2, rollback_seg VARCHAR2, refresh_after_errors BOOLEAN, atomic_refresh BOOLEAN, nested BOOLEAN);` | n/a | This variation of the `REFRESH_DEPENDENT` procedure refreshes all views that depend on the views listed in a comma-separated list. | +| `REFRESH_DEPENDENT(number_of_failures BINARY_INTEGER, tab dbms_utility.uncl_array, method VARCHAR2, rollback_seg VARCHAR2, refresh_after_errors BOOLEAN, atomic_refresh BOOLEAN, nested BOOLEAN);` | n/a | This variation of the `REFRESH_DEPENDENT` procedure refreshes all views that depend on the views listed in a table of `dbms_utility.uncl_array` values. | + +EDB Postgres Advanced Server's implementation of `DBMS_MVIEW` is a partial implementation when compared to Oracle's version. Only those functions and procedures listed in the table are supported. + +
+ +get_mv_dependencies refresh refresh_all_mviews refresh_dependent + +
diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/09_dbms_output.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/09_dbms_output.mdx new file mode 100644 index 00000000000..9e907ca85ef --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/09_dbms_output.mdx @@ -0,0 +1,429 @@ +--- +title: "DBMS_OUTPUT" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.20.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.196.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.154.html" +--- + +The `DBMS_OUTPUT` package sends messages (lines of text) to a message buffer or gets messages from the message buffer. A message buffer is local to a single session. Use the `DBMS_PIPE` package to send messages between sessions. + +The procedures and functions available in the `DBMS_OUTPUT` package are listed in the following table. + +| Function/procedure | Return type | Description | +| --------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------- | +| `DISABLE` | n/a | Disable the capability to send and receive messages. | +| `ENABLE(buffer_size)` | n/a | Enable the capability to send and receive messages. | +| `GET_LINE(line OUT, status OUT)` | n/a | Get a line from the message buffer. | +| `GET_LINES(lines OUT, numlines IN OUT)` | n/a | Get multiple lines from the message buffer. | +| `NEW_LINE` | n/a | Puts an end-of-line character sequence. | +| `PUT(item)` | n/a | Puts a partial line without an end-of-line character sequence. | +| `PUT_LINE(item)` | n/a | Puts a complete line with an end-of-line character sequence. | +| `SERVEROUTPUT(stdout)` | n/a | Direct messages from `PUT, PUT_LINE,` or `NEW_LINE` to either standard output or the message buffer. | + +The following table lists the public variables available in the `DBMS_OUTPUT` package. + +| Public variables | Data type | Value | Description | +| -------------------- | ------------- | --------- | ------------------ | +| `chararr` | `TABLE` | | For message lines. | + +## CHARARR + +The `CHARARR` is for storing multiple message lines. + +```sql +TYPE chararr IS TABLE OF VARCHAR2(32767) INDEX BY BINARY_INTEGER; +``` + +## DISABLE + +The `DISABLE` procedure clears out the message buffer. You can no longer access any messages in the buffer at the time the `DISABLE` procedure is executed. Any messages later sent with the `PUT`, `PUT_LINE,` or `NEW_LINE` procedures are discarded. No error is returned to the sender when the `PUT`, `PUT_LINE,` or `NEW_LINE` procedures are executed and messages were disabled. + +Use the `ENABLE or `SERVEROUTPUT(TRUE)` procedure to reenable sending and receiving messages. + +```sql +DISABLE +``` + +### Examples + +This anonymous block disables sending and receiving messages in the current session. + +```sql +BEGIN + DBMS_OUTPUT.DISABLE; +END; +``` + +## ENABLE + +The `ENABLE` procedure enables you to send messages to or retrieve messages from the message buffer. Running `SERVEROUTPUT(TRUE)` also implicitly performs the `ENABLE` procedure. + +The destination of a message sent with `PUT`, `PUT_LINE`, or `NEW_LINE` depends on the state of `SERVEROUTPUT`. + +- If the last state of `SERVEROUTPUT` is `TRUE`, the message goes to standard output of the command line. +- If the last state of `SERVEROUTPUT` is `FALSE`, the message goes to the message buffer. + +```sql +ENABLE [ ( INTEGER) ] +``` + +### Parameter + +`buffer_size` + + Maximum length of the message buffer in bytes. If you specify a `buffer_size` of less than 2000, the buffer size is set to 2000. + +### Examples + +This anonymous block enables messages. Setting `SERVEROUTPUT(TRUE)` forces them to standard output. + +```sql +BEGIN + DBMS_OUTPUT.ENABLE; + DBMS_OUTPUT.SERVEROUTPUT(TRUE); + DBMS_OUTPUT.PUT_LINE('Messages enabled'); +END; + +Messages enabled +``` + +You can achieve the same effect by using `SERVEROUTPUT(TRUE)`. + +```sql +BEGIN + DBMS_OUTPUT.SERVEROUTPUT(TRUE); + DBMS_OUTPUT.PUT_LINE('Messages enabled'); +END; + +Messages enabled +``` + +This anonymous block enables messages, but setting `SERVEROUTPUT(FALSE)` directs messages to the message buffer. + +```sql +BEGIN + DBMS_OUTPUT.ENABLE; + DBMS_OUTPUT.SERVEROUTPUT(FALSE); + DBMS_OUTPUT.PUT_LINE('Message sent to buffer'); +END; +``` + +## GET_LINE + +The `GET_LINE` procedure retrieves a line of text from the message buffer. Only text that was terminated by an end-of-line character sequence is retrieved. That includes complete lines generated using `PUT_LINE` or by a series of `PUT` calls followed by a `NEW_LINE` call. + +```sql +GET_LINE( OUT VARCHAR2, OUT INTEGER) +``` + +### Parameters + +`line` + + Variable receiving the line of text from the message buffer. + +`status` + + `0` if a line was returned from the message buffer, `1` if there was no line to return. + +### Examples + +This anonymous block writes the `emp` table out to the message buffer as a comma-delimited string for each row. + +```sql +EXEC DBMS_OUTPUT.SERVEROUTPUT(FALSE); + +DECLARE + v_emprec VARCHAR2(120); + CURSOR emp_cur IS SELECT * FROM emp ORDER BY empno; +BEGIN + DBMS_OUTPUT.ENABLE; + FOR i IN emp_cur LOOP + v_emprec := i.empno || ',' || i.ename || ',' || i.job || ',' || + NVL(LTRIM(TO_CHAR(i.mgr,'9999')),'') || ',' || i.hiredate || + ',' || i.sal || ',' || + NVL(LTRIM(TO_CHAR(i.comm,'9990.99')),'') || ',' || i.deptno; + DBMS_OUTPUT.PUT_LINE(v_emprec); + END LOOP; +END; +``` + +This anonymous block reads the message buffer and inserts the messages written by the prior example into a table named `messages`. The rows in `messages` are then displayed. + +```sql +CREATE TABLE messages ( + status INTEGER, + msg VARCHAR2(100) +); + +DECLARE + v_line VARCHAR2(100); + v_status INTEGER := 0; +BEGIN + DBMS_OUTPUT.GET_LINE(v_line,v_status); + WHILE v_status = 0 LOOP + INSERT INTO messages VALUES(v_status, v_line); + DBMS_OUTPUT.GET_LINE(v_line,v_status); + END LOOP; +END; + +SELECT msg FROM messages; +__OUTPUT__ + msg +----------------------------------------------------------------- + 7369,SMITH,CLERK,7902,17-DEC-80 00:00:00,800.00,,20 + 7499,ALLEN,SALESMAN,7698,20-FEB-81 00:00:00,1600.00,300.00,30 + 7521,WARD,SALESMAN,7698,22-FEB-81 00:00:00,1250.00,500.00,30 + 7566,JONES,MANAGER,7839,02-APR-81 00:00:00,2975.00,,20 + 7654,MARTIN,SALESMAN,7698,28-SEP-81 00:00:00,1250.00,1400.00,30 + 7698,BLAKE,MANAGER,7839,01-MAY-81 00:00:00,2850.00,,30 + 7782,CLARK,MANAGER,7839,09-JUN-81 00:00:00,2450.00,,10 + 7788,SCOTT,ANALYST,7566,19-APR-87 00:00:00,3000.00,,20 + 7839,KING,PRESIDENT,,17-NOV-81 00:00:00,5000.00,,10 + 7844,TURNER,SALESMAN,7698,08-SEP-81 00:00:00,1500.00,0.00,30 + 7876,ADAMS,CLERK,7788,23-MAY-87 00:00:00,1100.00,,20 + 7900,JAMES,CLERK,7698,03-DEC-81 00:00:00,950.00,,30 + 7902,FORD,ANALYST,7566,03-DEC-81 00:00:00,3000.00,,20 + 7934,MILLER,CLERK,7782,23-JAN-82 00:00:00,1300.00,,10 +(14 rows) +``` + +## GET_LINES + +The `GET_LINES` procedure retrieves one or more lines of text from the message buffer into a collection. Only text that was terminated by an end-of-line character sequence is retrieved. That includes complete lines generated using `PUT_LINE` or by a series of `PUT` calls followed by a `NEW_LINE` call. + +```sql +GET_LINES( OUT CHARARR, IN OUT INTEGER) +``` + +### Parameters + +`lines` + + Table receiving the lines of text from the message buffer. See `CHARARR` for a description of `lines.` + +`numlines IN` + + Number of lines to retrieve from the message buffer. + +`numlines OUT` + + Actual number of lines retrieved from the message buffer. If the output value of `numlines` is less than the input value, then no more lines are left in the message buffer. + +### Examples + +This example uses the `GET_LINES` procedure to store all rows from the `emp` table that were placed in the message buffer into an array. + +```sql +EXEC DBMS_OUTPUT.SERVEROUTPUT(FALSE); + +DECLARE + v_emprec VARCHAR2(120); + CURSOR emp_cur IS SELECT * FROM emp ORDER BY empno; +BEGIN + DBMS_OUTPUT.ENABLE; + FOR i IN emp_cur LOOP + v_emprec := i.empno || ',' || i.ename || ',' || i.job || ',' || + NVL(LTRIM(TO_CHAR(i.mgr,'9999')),'') || ',' || i.hiredate || + ',' || i.sal || ',' || + NVL(LTRIM(TO_CHAR(i.comm,'9990.99')),'') || ',' || i.deptno; + DBMS_OUTPUT.PUT_LINE(v_emprec); + END LOOP; +END; + +DECLARE + v_lines DBMS_OUTPUT.CHARARR; + v_numlines INTEGER := 14; + v_status INTEGER := 0; +BEGIN + DBMS_OUTPUT.GET_LINES(v_lines,v_numlines); + FOR i IN 1..v_numlines LOOP + INSERT INTO messages VALUES(v_numlines, v_lines(i)); + END LOOP; +END; + +SELECT msg FROM messages; +__OUTPUT__ + msg +----------------------------------------------------------------- + 7369,SMITH,CLERK,7902,17-DEC-80 00:00:00,800.00,,20 + 7499,ALLEN,SALESMAN,7698,20-FEB-81 00:00:00,1600.00,300.00,30 + 7521,WARD,SALESMAN,7698,22-FEB-81 00:00:00,1250.00,500.00,30 + 7566,JONES,MANAGER,7839,02-APR-81 00:00:00,2975.00,,20 + 7654,MARTIN,SALESMAN,7698,28-SEP-81 00:00:00,1250.00,1400.00,30 + 7698,BLAKE,MANAGER,7839,01-MAY-81 00:00:00,2850.00,,30 + 7782,CLARK,MANAGER,7839,09-JUN-81 00:00:00,2450.00,,10 + 7788,SCOTT,ANALYST,7566,19-APR-87 00:00:00,3000.00,,20 + 7839,KING,PRESIDENT,,17-NOV-81 00:00:00,5000.00,,10 + 7844,TURNER,SALESMAN,7698,08-SEP-81 00:00:00,1500.00,0.00,30 + 7876,ADAMS,CLERK,7788,23-MAY-87 00:00:00,1100.00,,20 + 7900,JAMES,CLERK,7698,03-DEC-81 00:00:00,950.00,,30 + 7902,FORD,ANALYST,7566,03-DEC-81 00:00:00,3000.00,,20 + 7934,MILLER,CLERK,7782,23-JAN-82 00:00:00,1300.00,,10 +(14 rows) +``` + +## NEW_LINE + +The `NEW_LINE` procedure writes an end-of-line character sequence in the message buffer. + +```sql +NEW_LINE +``` + +### Parameter + +The `NEW_LINE` procedure expects no parameters. + +## PUT + +The `PUT` procedure writes a string to the message buffer. No end-of-line character sequence is written at the end of the string. Use the `NEW_LINE` procedure to add an end-of-line character sequence. + +```sql +PUT( VARCHAR2) +``` + +### Parameter + +`item` + + Text written to the message buffer. + +### Examples + +The following example uses the `PUT` procedure to display a comma-delimited list of employees from the `emp` table. + +```sql +DECLARE + CURSOR emp_cur IS SELECT * FROM emp ORDER BY empno; +BEGIN + FOR i IN emp_cur LOOP + DBMS_OUTPUT.PUT(i.empno); + DBMS_OUTPUT.PUT(','); + DBMS_OUTPUT.PUT(i.ename); + DBMS_OUTPUT.PUT(','); + DBMS_OUTPUT.PUT(i.job); + DBMS_OUTPUT.PUT(','); + DBMS_OUTPUT.PUT(i.mgr); + DBMS_OUTPUT.PUT(','); + DBMS_OUTPUT.PUT(i.hiredate); + DBMS_OUTPUT.PUT(','); + DBMS_OUTPUT.PUT(i.sal); + DBMS_OUTPUT.PUT(','); + DBMS_OUTPUT.PUT(i.comm); + DBMS_OUTPUT.PUT(','); + DBMS_OUTPUT.PUT(i.deptno); + DBMS_OUTPUT.NEW_LINE; + END LOOP; +END; + +7369,SMITH,CLERK,7902,17-DEC-80 00:00:00,800.00,,20 +7499,ALLEN,SALESMAN,7698,20-FEB-81 00:00:00,1600.00,300.00,30 +7521,WARD,SALESMAN,7698,22-FEB-81 00:00:00,1250.00,500.00,30 +7566,JONES,MANAGER,7839,02-APR-81 00:00:00,2975.00,,20 +7654,MARTIN,SALESMAN,7698,28-SEP-81 00:00:00,1250.00,1400.00,30 +7698,BLAKE,MANAGER,7839,01-MAY-81 00:00:00,2850.00,,30 +7782,CLARK,MANAGER,7839,09-JUN-81 00:00:00,2450.00,,10 +7788,SCOTT,ANALYST,7566,19-APR-87 00:00:00,3000.00,,20 +7839,KING,PRESIDENT,,17-NOV-81 00:00:00,5000.00,,10 +7844,TURNER,SALESMAN,7698,08-SEP-81 00:00:00,1500.00,0.00,30 +7876,ADAMS,CLERK,7788,23-MAY-87 00:00:00,1100.00,,20 +7900,JAMES,CLERK,7698,03-DEC-81 00:00:00,950.00,,30 +7902,FORD,ANALYST,7566,03-DEC-81 00:00:00,3000.00,,20 +7934,MILLER,CLERK,7782,23-JAN-82 00:00:00,1300.00,,10 +``` + +## PUT_LINE + +The `PUT_LINE` procedure writes a single line to the message buffer including an end-of-line character sequence. + +```text +PUT_LINE( VARCHAR2) +``` + +### Parameter + +`item` + + Text to write to the message buffer. + +### Examples + +This example uses the `PUT_LINE` procedure to display a comma-delimited list of employees from the `emp` table. + +```sql +DECLARE + v_emprec VARCHAR2(120); + CURSOR emp_cur IS SELECT * FROM emp ORDER BY empno; +BEGIN + FOR i IN emp_cur LOOP + v_emprec := i.empno || ',' || i.ename || ',' || i.job || ',' || + NVL(LTRIM(TO_CHAR(i.mgr,'9999')),'') || ',' || i.hiredate || + ',' || i.sal || ',' || + NVL(LTRIM(TO_CHAR(i.comm,'9990.99')),'') || ',' || i.deptno; + DBMS_OUTPUT.PUT_LINE(v_emprec); + END LOOP; +END; + +7369,SMITH,CLERK,7902,17-DEC-80 00:00:00,800.00,,20 +7499,ALLEN,SALESMAN,7698,20-FEB-81 00:00:00,1600.00,300.00,30 +7521,WARD,SALESMAN,7698,22-FEB-81 00:00:00,1250.00,500.00,30 +7566,JONES,MANAGER,7839,02-APR-81 00:00:00,2975.00,,20 +7654,MARTIN,SALESMAN,7698,28-SEP-81 00:00:00,1250.00,1400.00,30 +7698,BLAKE,MANAGER,7839,01-MAY-81 00:00:00,2850.00,,30 +7782,CLARK,MANAGER,7839,09-JUN-81 00:00:00,2450.00,,10 +7788,SCOTT,ANALYST,7566,19-APR-87 00:00:00,3000.00,,20 +7839,KING,PRESIDENT,,17-NOV-81 00:00:00,5000.00,,10 +7844,TURNER,SALESMAN,7698,08-SEP-81 00:00:00,1500.00,0.00,30 +7876,ADAMS,CLERK,7788,23-MAY-87 00:00:00,1100.00,,20 +7900,JAMES,CLERK,7698,03-DEC-81 00:00:00,950.00,,30 +7902,FORD,ANALYST,7566,03-DEC-81 00:00:00,3000.00,,20 +7934,MILLER,CLERK,7782,23-JAN-82 00:00:00,1300.00,,10 +``` + +## SERVEROUTPUT + +The `SERVEROUTPUT` procedure directs messages to standard output of the command line or to the message buffer. Setting `SERVEROUTPUT(TRUE)` also performs an implicit execution of `ENABLE`. + +The default setting of `SERVEROUTPUT` depends on the implementation. For example, in Oracle SQL\*Plus, `SERVEROUTPUT(FALSE)` is the default. In PSQL, `SERVEROUTPUT(TRUE)` is the default. Also, in Oracle SQL\*Plus, you control this setting using the SQL\*Plus `SET` comman, not by a stored procedure as implemented in EDB Postgres Advanced Server. + +```sql +SERVEROUTPUT( BOOLEAN) +``` + +To get an Oracle-style display output, you can set the `dbms_output.serveroutput` to `FALSE` in the `postgresql.conf` file, which disables the message output. The default is `TRUE`, which enables the message output. + +### Parameter + +`stdout` + + Set to `TRUE` if you want subsequent `PUT`, `PUT_LINE`, or `NEW_LINE` to send text directly to standard output of the command line. Set to `FALSE` to send text to the message buffer. + +### Examples + +This anonymous block sends the first message to the command line and the second message to the message buffer. + +```sql +BEGIN + DBMS_OUTPUT.SERVEROUTPUT(TRUE); + DBMS_OUTPUT.PUT_LINE('This message goes to the command line'); + DBMS_OUTPUT.SERVEROUTPUT(FALSE); + DBMS_OUTPUT.PUT_LINE('This message goes to the message buffer'); +END; + +This message goes to the command line +``` + +If, in the same session, the following anonymous block is executed, the message stored in the message buffer from the prior example is flushed. It's displayed on the command line along with the new message. + +```sql +BEGIN + DBMS_OUTPUT.SERVEROUTPUT(TRUE); + DBMS_OUTPUT.PUT_LINE('Flush messages from the buffer'); +END; + +This message goes to the message buffer +Flush messages from the buffer +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/01_create_pipe.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/01_create_pipe.mdx new file mode 100644 index 00000000000..c6bbef203bb --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/01_create_pipe.mdx @@ -0,0 +1,54 @@ +--- +title: "CREATE_PIPE" +--- + +The `CREATE_PIPE` function creates an explicit public pipe or an explicit private pipe with a specified name. + +```sql + INTEGER CREATE_PIPE( VARCHAR2 + [, INTEGER ] [, BOOLEAN ]) +``` + +## Parameters + +`pipename` + + Name of the pipe. + +`maxpipesize` + + Maximum capacity of the pipe in bytes. Default is 8192 bytes. + +`private` + + Create a public pipe if set to `FALSE`. Create a private pipe if set to `TRUE.` This is the default. + +`status` + + Status code returned by the operation. `0` indicates successful creation. + +## Examples + +This example creates a private pipe named `messages`: + +```sql +DECLARE + v_status INTEGER; +BEGIN + v_status := DBMS_PIPE.CREATE_PIPE('messages'); + DBMS_OUTPUT.PUT_LINE('CREATE_PIPE status: ' || v_status); +END; +CREATE_PIPE status: 0 +``` + +This example creates a public pipe named `mailbox`: + +```sql +DECLARE + v_status INTEGER; +BEGIN + v_status := DBMS_PIPE.CREATE_PIPE('mailbox',8192,FALSE); + DBMS_OUTPUT.PUT_LINE('CREATE_PIPE status: ' || v_status); +END; +CREATE_PIPE status: 0 +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/02_next_item_pipe.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/02_next_item_pipe.mdx new file mode 100644 index 00000000000..6c094d3bae3 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/02_next_item_pipe.mdx @@ -0,0 +1,114 @@ +--- +title: "NEXT_ITEM_TYPE" +--- + +The `NEXT_ITEM_TYPE` function returns an integer code identifying the data type of the next data item in a message that was retrieved into the session’s local message buffer. As each item is moved off of the local message buffer with the `UNPACK_MESSAGE` procedure, the `NEXT_ITEM_TYPE` function returns the data type code for the next available item. A code of `0` is returned when no more items are left in the message. + +```sql + INTEGER NEXT_ITEM_TYPE +``` + +## Parameters + +`typecode` + + Code identifying the data type of the next data item is shown in the following table. + +| Type code | Data type | +| --------- | ------------------ | +| `0` | No more data items | +| `9` | `NUMBER` | +| `11` | `VARCHAR2` | +| `13` | `DATE` | +| `23` | `RAW` | + + !!! Note + The type codes listed in the table aren't compatible with Oracle databases. Oracle assigns a different numbering sequence to the data types. + +## Examples + +This example shows a pipe packed with a `NUMBER` item, a `VARCHAR2` item, a `DATE` item, and a `RAW` item. A second anonymous block then uses the `NEXT_ITEM_TYPE` function to display the type code of each item. + +```sql +DECLARE + v_number NUMBER := 123; + v_varchar VARCHAR2(20) := 'Character data'; + v_date DATE := SYSDATE; + v_raw RAW(4) := '21222324'; + v_status INTEGER; +BEGIN + DBMS_PIPE.PACK_MESSAGE(v_number); + DBMS_PIPE.PACK_MESSAGE(v_varchar); + DBMS_PIPE.PACK_MESSAGE(v_date); + DBMS_PIPE.PACK_MESSAGE(v_raw); + v_status := DBMS_PIPE.SEND_MESSAGE('datatypes'); + DBMS_OUTPUT.PUT_LINE('SEND_MESSAGE status: ' || v_status); +EXCEPTION + WHEN OTHERS THEN + DBMS_OUTPUT.PUT_LINE('SQLERRM: ' || SQLERRM); + DBMS_OUTPUT.PUT_LINE('SQLCODE: ' || SQLCODE); +END; + +SEND_MESSAGE status: 0 + +DECLARE + v_number NUMBER; + v_varchar VARCHAR2(20); + v_date DATE; + v_timestamp TIMESTAMP; + v_raw RAW(4); + v_status INTEGER; +BEGIN + v_status := DBMS_PIPE.RECEIVE_MESSAGE('datatypes'); + DBMS_OUTPUT.PUT_LINE('RECEIVE_MESSAGE status: ' || v_status); + DBMS_OUTPUT.PUT_LINE('----------------------------------'); + + v_status := DBMS_PIPE.NEXT_ITEM_TYPE; + DBMS_OUTPUT.PUT_LINE('NEXT_ITEM_TYPE: ' || v_status); + DBMS_PIPE.UNPACK_MESSAGE(v_number); + DBMS_OUTPUT.PUT_LINE('NUMBER Item : ' || v_number); + DBMS_OUTPUT.PUT_LINE('----------------------------------'); + + v_status := DBMS_PIPE.NEXT_ITEM_TYPE; + DBMS_OUTPUT.PUT_LINE('NEXT_ITEM_TYPE: ' || v_status); + DBMS_PIPE.UNPACK_MESSAGE(v_varchar); + DBMS_OUTPUT.PUT_LINE('VARCHAR2 Item : ' || v_varchar); + DBMS_OUTPUT.PUT_LINE('----------------------------------'); + + v_status := DBMS_PIPE.NEXT_ITEM_TYPE; + DBMS_OUTPUT.PUT_LINE('NEXT_ITEM_TYPE: ' || v_status); + DBMS_PIPE.UNPACK_MESSAGE(v_date); + DBMS_OUTPUT.PUT_LINE('DATE Item : ' || v_date); + DBMS_OUTPUT.PUT_LINE('----------------------------------'); + + v_status := DBMS_PIPE.NEXT_ITEM_TYPE; + DBMS_OUTPUT.PUT_LINE('NEXT_ITEM_TYPE: ' || v_status); + DBMS_PIPE.UNPACK_MESSAGE(v_raw); + DBMS_OUTPUT.PUT_LINE('RAW Item : ' || v_raw); + DBMS_OUTPUT.PUT_LINE('----------------------------------'); + + v_status := DBMS_PIPE.NEXT_ITEM_TYPE; + DBMS_OUTPUT.PUT_LINE('NEXT_ITEM_TYPE: ' || v_status); + DBMS_OUTPUT.PUT_LINE('---------------------------------'); +EXCEPTION + WHEN OTHERS THEN + DBMS_OUTPUT.PUT_LINE('SQLERRM: ' || SQLERRM); + DBMS_OUTPUT.PUT_LINE('SQLCODE: ' || SQLCODE); +END; + +RECEIVE_MESSAGE status: 0 +---------------------------------- +NEXT_ITEM_TYPE: 9 +NUMBER Item : 123 +---------------------------------- +NEXT_ITEM_TYPE: 11 +VARCHAR2 Item : Character data +---------------------------------- +NEXT_ITEM_TYPE: 13 +DATE Item : 02-OCT-07 11:11:43 +---------------------------------- +NEXT_ITEM_TYPE: 23 +RAW Item : 21222324 +---------------------------------- +NEXT_ITEM_TYPE: 0 +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/03_pack_message.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/03_pack_message.mdx new file mode 100644 index 00000000000..5196135d59a --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/03_pack_message.mdx @@ -0,0 +1,17 @@ +--- +title: "PACK_MESSAGE" +--- + +The `PACK_MESSAGE` procedure places an item of data in the session’s local message buffer. You must execute `PACK_MESSAGE` at least once before issuing a `SEND_MESSAGE` call. + +```sql +PACK_MESSAGE( { DATE | NUMBER | VARCHAR2 | RAW }) +``` + +Use the `UNPACK_MESSAGE` procedure to obtain data items once the message is retrieved using a `RECEIVE_MESSAGE` call. + +## Parameters + +`item` + + An expression evaluating to any of the acceptable parameter data types. The value is added to the session’s local message buffer. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/04_purge.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/04_purge.mdx new file mode 100644 index 00000000000..7566677e672 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/04_purge.mdx @@ -0,0 +1,75 @@ +--- +title: "PURGE" +--- + +The `PURGE` procedure removes the unreceived messages from a specified implicit pipe. + +```sql +PURGE( VARCHAR2) +``` + +Use the `REMOVE_PIPE` function to delete an explicit pipe. + +## Parameters + +`pipename` + + Name of the pipe. + +## Examples + +Two messages are sent on a pipe: + +```sql +DECLARE + v_status INTEGER; +BEGIN + DBMS_PIPE.PACK_MESSAGE('Message #1'); + v_status := DBMS_PIPE.SEND_MESSAGE('pipe'); + DBMS_OUTPUT.PUT_LINE('SEND_MESSAGE status: ' || v_status); + + DBMS_PIPE.PACK_MESSAGE('Message #2'); + v_status := DBMS_PIPE.SEND_MESSAGE('pipe'); + DBMS_OUTPUT.PUT_LINE('SEND_MESSAGE status: ' || v_status); +END; + +SEND_MESSAGE status: 0 +SEND_MESSAGE status: 0 +``` + +Receive the first message and unpack it: + +```sql +DECLARE + v_item VARCHAR2(80); + v_status INTEGER; +BEGIN + v_status := DBMS_PIPE.RECEIVE_MESSAGE('pipe',1); + DBMS_OUTPUT.PUT_LINE('RECEIVE_MESSAGE status: ' || v_status); + DBMS_PIPE.UNPACK_MESSAGE(v_item); + DBMS_OUTPUT.PUT_LINE('Item: ' || v_item); +END; + +RECEIVE_MESSAGE status: 0 +Item: Message #1 +``` + +Purge the pipe: + +```sql +EXEC DBMS_PIPE.PURGE('pipe'); +``` + +Try to retrieve the next message. The `RECEIVE_MESSAGE` call returns status code `1` indicating it timed out because no message was available. + +```sql +DECLARE + v_item VARCHAR2(80); + v_status INTEGER; +BEGIN + v_status := DBMS_PIPE.RECEIVE_MESSAGE('pipe',1); + DBMS_OUTPUT.PUT_LINE('RECEIVE_MESSAGE status: ' || v_status); +END; + +RECEIVE_MESSAGE status: 1 +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/05_receive_message.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/05_receive_message.mdx new file mode 100644 index 00000000000..639132daa1f --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/05_receive_message.mdx @@ -0,0 +1,32 @@ +--- +title: "RECEIVE_MESSAGE" +--- + +The `RECEIVE_MESSAGE` function obtains a message from a specified pipe. + +```sql + INTEGER RECEIVE_MESSAGE( VARCHAR2 + [, INTEGER ]) +``` + +## Parameters + +`pipename` + + Name of the pipe. + +`timeout` + + Wait time (seconds). Default is 86400000 (1000 days). + +`status` + + Status code returned by the operation. + + The possible status codes are: + +| Status code | Description | +| ----------- | -------------------------------- | +| `0` | Success | +| `1` | Time out | +| `2` | Message too large for the buffer | diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/06_remove_pipe.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/06_remove_pipe.mdx new file mode 100644 index 00000000000..a81df0fed36 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/06_remove_pipe.mdx @@ -0,0 +1,88 @@ +--- +title: "REMOVE_PIPE" +--- + +The `REMOVE_PIPE` function deletes an explicit private or explicit public pipe. + +```sql + INTEGER REMOVE_PIPE( VARCHAR2) +``` + +Use the `REMOVE_PIPE` function to delete explicitly created pipes, that is, pipes created with the `CREATE_PIPE` function. + +## Parameters + +`pipename` + + Name of the pipe. + +`status` + + Status code returned by the operation. A status code of `0` is returned even if the named pipe is nonexistent. + +## Examples + +Two messages are sent on a pipe: + +```sql +DECLARE + v_status INTEGER; +BEGIN + v_status := DBMS_PIPE.CREATE_PIPE('pipe'); + DBMS_OUTPUT.PUT_LINE('CREATE_PIPE status : ' || v_status); + + DBMS_PIPE.PACK_MESSAGE('Message #1'); + v_status := DBMS_PIPE.SEND_MESSAGE('pipe'); + DBMS_OUTPUT.PUT_LINE('SEND_MESSAGE status: ' || v_status); + + DBMS_PIPE.PACK_MESSAGE('Message #2'); + v_status := DBMS_PIPE.SEND_MESSAGE('pipe'); + DBMS_OUTPUT.PUT_LINE('SEND_MESSAGE status: ' || v_status); +END; + +CREATE_PIPE status : 0 +SEND_MESSAGE status: 0 +SEND_MESSAGE status: 0 +``` + +Receive the first message and unpack it: + +```sql +DECLARE + v_item VARCHAR2(80); + v_status INTEGER; +BEGIN + v_status := DBMS_PIPE.RECEIVE_MESSAGE('pipe',1); + DBMS_OUTPUT.PUT_LINE('RECEIVE_MESSAGE status: ' || v_status); + DBMS_PIPE.UNPACK_MESSAGE(v_item); + DBMS_OUTPUT.PUT_LINE('Item: ' || v_item); +END; + +RECEIVE_MESSAGE status: 0 +Item: Message #1 +``` + +Remove the pipe: + +```sql +SELECT DBMS_PIPE.REMOVE_PIPE('pipe') FROM DUAL; +__OUTPUT__ +remove_pipe +------------- + 0 +(1 row) +``` + +Try to retrieve the next message. The `RECEIVE_MESSAGE` call returns status code `1` indicating it timed out because the pipe was deleted. + +```sql +DECLARE + v_item VARCHAR2(80); + v_status INTEGER; +BEGIN + v_status := DBMS_PIPE.RECEIVE_MESSAGE('pipe',1); + DBMS_OUTPUT.PUT_LINE('RECEIVE_MESSAGE status: ' || v_status); +END; + +RECEIVE_MESSAGE status: 1 +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/07_reset_buffer.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/07_reset_buffer.mdx new file mode 100644 index 00000000000..8146c6cfb09 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/07_reset_buffer.mdx @@ -0,0 +1,50 @@ +--- +title: "RESET_BUFFER" +--- + +The `RESET_BUFFER` procedure resets a pointer to the session’s local message buffer back to the beginning of the buffer. This causes later `PACK_MESSAGE` calls to overwrite any data items that were in the message buffer before the `RESET_BUFFER` call. + +```sql +RESET_BUFFER +``` + +## Examples + +A message to John is written to the local message buffer. It is replaced by a message to Bob by calling `RESET_BUFFER`. The message is sent on the pipe. + +```sql +DECLARE + v_status INTEGER; +BEGIN + DBMS_PIPE.PACK_MESSAGE('Hi, John'); + DBMS_PIPE.PACK_MESSAGE('Can you attend a meeting at 3:00, today?'); + DBMS_PIPE.PACK_MESSAGE('If not, is tomorrow at 8:30 ok with you?'); + DBMS_PIPE.RESET_BUFFER; + DBMS_PIPE.PACK_MESSAGE('Hi, Bob'); + DBMS_PIPE.PACK_MESSAGE('Can you attend a meeting at 9:30, tomorrow?'); + v_status := DBMS_PIPE.SEND_MESSAGE('pipe'); + DBMS_OUTPUT.PUT_LINE('SEND_MESSAGE status: ' || v_status); +END; + +SEND_MESSAGE status: 0 +``` + +The message to Bob is in the received message: + +```sql +DECLARE + v_item VARCHAR2(80); + v_status INTEGER; +BEGIN + v_status := DBMS_PIPE.RECEIVE_MESSAGE('pipe',1); + DBMS_OUTPUT.PUT_LINE('RECEIVE_MESSAGE status: ' || v_status); + DBMS_PIPE.UNPACK_MESSAGE(v_item); + DBMS_OUTPUT.PUT_LINE('Item: ' || v_item); + DBMS_PIPE.UNPACK_MESSAGE(v_item); + DBMS_OUTPUT.PUT_LINE('Item: ' || v_item); +END; + +RECEIVE_MESSAGE status: 0 +Item: Hi, Bob +Item: Can you attend a meeting at 9:30, tomorrow? +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/08_send_message.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/08_send_message.mdx new file mode 100644 index 00000000000..bce900825e5 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/08_send_message.mdx @@ -0,0 +1,36 @@ +--- +title: "SEND_MESSAGE" +--- + +The `SEND_MESSAGE` function sends a message from the session’s local message buffer to the specified pipe. + +```sql + SEND_MESSAGE( VARCHAR2 [, INTEGER ] + [, INTEGER ]) +``` + +## Parameters + +`pipename` + + Name of the pipe. + +`timeout` + + Wait time (seconds). Default is 86400000 (1000 days). + +`maxpipesize` + + Maximum capacity of the pipe in bytes. Default is 8192 bytes. + +`status` + + Status code returned by the operation. + + The possible status codes are: + +| Status code | Description | +| ----------- | -------------------- | +| `0` | Success | +| `1` | Time out | +| `3` | Function interrupted | diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/09_unique_session_name.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/09_unique_session_name.mdx new file mode 100644 index 00000000000..3a54ca0db09 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/09_unique_session_name.mdx @@ -0,0 +1,30 @@ +--- +title: "UNIQUE_SESSION_NAME" +--- + +The `UNIQUE_SESSION_NAME` function returns a name that is unique to the current session. + +```sql + VARCHAR2 UNIQUE_SESSION_NAME +``` + +## Parameters + +`name` + + Unique session name. + +## Examples + +The following anonymous block retrieves and displays a unique session name: + +```sql +DECLARE + v_session VARCHAR2(30); +BEGIN + v_session := DBMS_PIPE.UNIQUE_SESSION_NAME; + DBMS_OUTPUT.PUT_LINE('Session Name: ' || v_session); +END; + +Session Name: PG$PIPE$5$2752 +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/10_unpack_message.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/10_unpack_message.mdx new file mode 100644 index 00000000000..264ca8f7cb5 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/10_unpack_message.mdx @@ -0,0 +1,15 @@ +--- +title: "UNPACK_MESSAGE" +--- + +The `UNPACK_MESSAGE` procedure copies the data items of a message from the local message buffer to a specified program variable. You must place the message in the local message buffer with the `RECEIVE_MESSAGE` function before using `UNPACK_MESSAGE`. + +```sql +UNPACK_MESSAGE( OUT { DATE | NUMBER | VARCHAR2 | RAW }) +``` + +## Parameters + +`item` + + Type-compatible variable that receives a data item from the local message buffer. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/11_comprehensive_example.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/11_comprehensive_example.mdx new file mode 100644 index 00000000000..c7b79d2bc9a --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/11_comprehensive_example.mdx @@ -0,0 +1,158 @@ +--- +title: "Comprehensive example" +--- + +This example uses a pipe as a “mailbox." Three procedures are enclosed in a package named `mailbox`. These procedures: + +1. Create the mailbox. +2. Add a multi-item message to the mailbox (up to three items). +3. Display the full contents of the mailbox. + +```sql +CREATE OR REPLACE PACKAGE mailbox +IS + PROCEDURE create_mailbox; + PROCEDURE add_message ( + p_mailbox VARCHAR2, + p_item_1 VARCHAR2, + p_item_2 VARCHAR2 DEFAULT 'END', + p_item_3 VARCHAR2 DEFAULT 'END' + ); + PROCEDURE empty_mailbox ( + p_mailbox VARCHAR2, + p_waittime INTEGER DEFAULT 10 + ); +END mailbox; + +CREATE OR REPLACE PACKAGE BODY mailbox +IS + PROCEDURE create_mailbox + IS + v_mailbox VARCHAR2(30); + v_status INTEGER; + BEGIN + v_mailbox := DBMS_PIPE.UNIQUE_SESSION_NAME; + v_status := DBMS_PIPE.CREATE_PIPE(v_mailbox,1000,FALSE); + IF v_status = 0 THEN + DBMS_OUTPUT.PUT_LINE('Created mailbox: ' || v_mailbox); + ELSE + DBMS_OUTPUT.PUT_LINE('CREATE_PIPE failed - status: ' || + v_status); + END IF; + END create_mailbox; + + PROCEDURE add_message ( + p_mailbox VARCHAR2, + p_item_1 VARCHAR2, + p_item_2 VARCHAR2 DEFAULT 'END', + p_item_3 VARCHAR2 DEFAULT 'END' + ) + IS + v_item_cnt INTEGER := 0; + v_status INTEGER; + BEGIN + DBMS_PIPE.PACK_MESSAGE(p_item_1); + v_item_cnt := 1; + IF p_item_2 != 'END' THEN + DBMS_PIPE.PACK_MESSAGE(p_item_2); + v_item_cnt := v_item_cnt + 1; + END IF; + IF p_item_3 != 'END' THEN + DBMS_PIPE.PACK_MESSAGE(p_item_3); + v_item_cnt := v_item_cnt + 1; + END IF; + v_status := DBMS_PIPE.SEND_MESSAGE(p_mailbox); + IF v_status = 0 THEN + DBMS_OUTPUT.PUT_LINE('Added message with ' || v_item_cnt || + ' item(s) to mailbox ' || p_mailbox); + ELSE + DBMS_OUTPUT.PUT_LINE('SEND_MESSAGE in add_message failed - ' || + 'status: ' || v_status); + END IF; + END add_message; + + PROCEDURE empty_mailbox ( + p_mailbox VARCHAR2, + p_waittime INTEGER DEFAULT 10 + ) + IS + v_msgno INTEGER DEFAULT 0; + v_itemno INTEGER DEFAULT 0; + v_item VARCHAR2(100); + v_status INTEGER; + BEGIN + v_status := DBMS_PIPE.RECEIVE_MESSAGE(p_mailbox,p_waittime); + WHILE v_status = 0 LOOP + v_msgno := v_msgno + 1; + DBMS_OUTPUT.PUT_LINE('****** Start message #' || v_msgno || + ' ******'); + BEGIN + LOOP + v_status := DBMS_PIPE.NEXT_ITEM_TYPE; + EXIT WHEN v_status = 0; + DBMS_PIPE.UNPACK_MESSAGE(v_item); + v_itemno := v_itemno + 1; + DBMS_OUTPUT.PUT_LINE('Item #' || v_itemno || ': ' || + v_item); + END LOOP; + DBMS_OUTPUT.PUT_LINE('******* End message #' || v_msgno || + ' *******'); + DBMS_OUTPUT.PUT_LINE('*'); + v_itemno := 0; + v_status := DBMS_PIPE.RECEIVE_MESSAGE(p_mailbox,1); + END; + END LOOP; + DBMS_OUTPUT.PUT_LINE('Number of messages received: ' || v_msgno); + v_status := DBMS_PIPE.REMOVE_PIPE(p_mailbox); + IF v_status = 0 THEN + DBMS_OUTPUT.PUT_LINE('Deleted mailbox ' || p_mailbox); + ELSE + DBMS_OUTPUT.PUT_LINE('Could not delete mailbox - status: ' + || v_status); + END IF; + END empty_mailbox; +END mailbox; +``` + +The following shows executing the procedures in `mailbox`. The first procedure creates a public pipe using a name generated by the `UNIQUE_SESSION_NAME` function. + +```sql +EXEC mailbox.create_mailbox; + +Created mailbox: PG$PIPE$13$3940 +``` + +Using the mailbox name, any user in the same database with access to the `mailbox` package and `DBMS_PIPE` package can add messages: + +```sql +EXEC mailbox.add_message('PG$PIPE$13$3940','Hi, John','Can you attend a +meeting at 3:00, today?','-- Mary'); + +Added message with 3 item(s) to mailbox PG$PIPE$13$3940 + +EXEC mailbox.add_message('PG$PIPE$13$3940','Don''t forget to submit your +report','Thanks,','-- Joe'); + +Added message with 3 item(s) to mailbox PG$PIPE$13$3940 +``` + +Finally, the contents of the mailbox can be emptied: + +```sql +EXEC mailbox.empty_mailbox('PG$PIPE$13$3940'); + +****** Start message #1 ****** +Item #1: Hi, John +Item #2: Can you attend a meeting at 3:00, today? +Item #3: -- Mary +******* End message #1 ******* +* +****** Start message #2 ****** +Item #1: Don't forget to submit your report +Item #2: Thanks, +Item #3: Joe +******* End message #2 ******* +* +Number of messages received: 2 +Deleted mailbox PG$PIPE$13$3940 +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/index.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/index.mdx new file mode 100644 index 00000000000..d9218d8b6ee --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/index.mdx @@ -0,0 +1,43 @@ +--- +title: "DBMS_PIPE" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.21.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.197.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.155.html" +--- + +The `DBMS_PIPE` package lets you send messages through a pipe in or between sessions connected to the same database cluster. + +The table shows the procedures and functions available in the `DBMS_PIPE` package: + +| Function/procedure | Return type | Description | +| ------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------- | +| `CREATE_PIPE(pipename [, maxpipesize ] [, private ])` | `INTEGER` | Explicitly create a private pipe if `private` is `true` (the default) or a public pipe if `private` is `false`. | +| `NEXT_ITEM_TYPE` | `INTEGER` | Determine the data type of the next item in a received message. | +| `PACK_MESSAGE(item)` | n/a | Place `item` in the session’s local message buffer. | +| `PURGE(pipename)` | n/a | Remove unreceived messages from the specified pipe. | +| `RECEIVE_MESSAGE(pipename [, timeout ])` | `INTEGER` | Get a message from a specified pipe. | +| `REMOVE_PIPE(pipename)` | `INTEGER` | Delete an explicitly created pipe. | +| `RESET_BUFFER` | n/a | Reset the local message buffer. | +| `SEND_MESSAGE(pipename [, timeout ] [, maxpipesize ])` | `INTEGER` | Send a message on a pipe. | +| `UNIQUE_SESSION_NAME` | `VARCHAR2` | Obtain a unique session name. | +| `UNPACK_MESSAGE(item OUT)` | n/a | Retrieve the next data item from a message into a type-compatible variable, `item`. | + +Pipes are categorized as *implicit* or *explicit*. An implicit pipe is created if a reference is made to a pipe name that wasn't previously created by the `CREATE_PIPE` function. For example, if the `SEND_MESSAGE` function is executed using a nonexistent pipe name, a new implicit pipe is created with that name. An explicit pipe is created using the `CREATE_PIPE` function in which the first parameter specifies the pipe name for the new pipe. + +Pipes are also categorized as *private* or *public*. Only the user who created the pipe can access a private pipe. Even a superuser can't access a private pipe that was created by another user. Any user who has access to the `DBMS_PIPE` package can access a public pipe. + +You can create a public pipe only by using the `CREATE_PIPE` function with the third parameter set to `FALSE`. You can use the `CREATE_PIPE` function to create a private pipe by setting the third parameter to `TRUE` or by omitting the third parameter. All implicit pipes are private. + +The individual data items, or lines, of a message are first built in a *local message buffer*, unique to the current session. The `PACK_MESSAGE` procedure builds the message in the session’s local message buffer. You then use the `SEND_MESSAGE` function to send the message through the pipe. + +Receipt of a message involves the reverse operation. You use the `RECEIVE_MESSAGE` function to get a message from the specified pipe. The message is written to the session’s local message buffer. You then use The `UNPACK_MESSAGE` procedure to transfer the message data items from the message buffer to program variables. If a pipe contains multiple messages, `RECEIVE_MESSAGE` gets the messages in FIFO (first-in-first-out) order. + +Each session maintains separate message buffers for messages created with the `PACK_MESSAGE` procedure and messages retrieved by the `RECEIVE_MESSAGE` function. Thus messages can be both built and received in the same session. However, if consecutive `RECEIVE_MESSAGE` calls are made, only the message from the last `RECEIVE_MESSAGE` call is preserved in the local message buffer. + +
+ +create_pipe next_item_pipe pack_message purge receive_message remove_pipe reset_buffer send_message unique_session_name unpack_message comprehensive_example + +
diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/11_dbms_profiler.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/11_dbms_profiler.mdx new file mode 100644 index 00000000000..acdb750eded --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/11_dbms_profiler.mdx @@ -0,0 +1,851 @@ +--- +title: "DBMS_PROFILER" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.24.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.23.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.22.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.25.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.198.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.138.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.156.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.140.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.137.html" +--- + +The `DBMS_PROFILER` package collects and stores performance information about the PL/pgSQL and SPL statements that are executed during a performance profiling session. Use these functions and procedures to control the profiling tool. + +| Function/procedure | Return type | Description | +| --------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | +| `FLUSH_DATA` | Status Code or Exception | Flushes performance data collected in the current session without terminating the session. Profiling continues. | +| `GET_VERSION(major OUT, minor OUT)` | n/a | Returns the version number of this package. | +| `INTERNAL_VERSION_CHECK` | Status Code | Confirms that the current version of the profiler works with the current database. | +| `PAUSE_PROFILER` | Status Code or Exception | Pauses data collection. | +| `RESUME_PROFILER` | Status Code or Exception | Resumes data collection. | +| `START_PROFILER(run_comment, run_comment1 [, run_number OUT ])` | Status Code or Exception | Starts data collection. | +| `STOP_PROFILER` | Status Code or Exception | Stops data collection and flushes performance data to the `PLSQL_PROFILER_RAWDATA` table. | + +The functions in the `DBMS_PROFILER` package return a status code to indicate success or failure. The `DBMS_PROFILER` procedures raise an exception only if they encounter a failure. The table shows the status codes and messages returned by the functions and the exceptions raised by the procedures. + +| Status code | Message | Exception | Description | +| ----------- | --------------- | ------------------ | ------------------------------------------------------- | +| `-1` | `error version` | `version_mismatch` | The profiler version and the database are incompatible. | +| `0` | `success` | n/a | The operation completed successfully. | +| `1` | `error_param` | `profiler_error` | The operation received an incorrect parameter. | +| `2` | `error_io` | `profiler_error` | The data flush operation failed. | + +## FLUSH_DATA + +The `FLUSH_DATA` function/procedure flushes the data collected in the current session without terminating the profiler session. The data is flushed to the tables described in the EDB Postgres Advanced Server Performance Features Guide. The function and procedure signatures are: + +```sql + INTEGER FLUSH_DATA + +FLUSH_DATA +``` + +### Parameters + +`status` + + Status code returned by the operation. + +## GET_VERSION + +The `GET_VERSION` procedure returns the version of `DBMS_PROFILER`. The procedure signature is: + +```sql +GET_VERSION( OUT INTEGER, OUT INTEGER) +``` + +### Parameters + +`major` + + The major version number of `DBMS_PROFILER`. + +`minor` + + The minor version number of `DBMS_PROFILER`. + +## INTERNAL_VERSION_CHECK + +The `INTERNAL_VERSION_CHECK` function confirms that the current version of `DBMS_PROFILER` works with the current database. The function signature is: + +```sql + INTEGER INTERNAL_VERSION_CHECK +``` + +### Parameters + +`status` + + Status code returned by the operation. + +## PAUSE_PROFILER + +The `PAUSE_PROFILER` function/procedure pauses a profiling session. The function and procedure signatures are: + +```sql + INTEGER PAUSE_PROFILER + +PAUSE_PROFILER +``` + +### Parameters + +`status` + + Status code returned by the operation. + +## RESUME_PROFILER + +The `RESUME_PROFILER` function/procedure pauses a profiling session. The function and procedure signatures are: + +```sql + INTEGER RESUME_PROFILER + +RESUME_PROFILER +``` + +### Parameters + +`status` + + Status code returned by the operation. + +## START_PROFILER + +The `START_PROFILER` function/procedure starts a data collection session. The function and procedure signatures are: + +```sql + INTEGER START_PROFILER( TEXT := SYSDATE, + TEXT := '' [, OUT INTEGER ]) + +START_PROFILER( TEXT := SYSDATE, + TEXT := '' [, OUT INTEGER ]) +``` + +### Parameters + +`run_comment` + + A user-defined comment for the profiler session. The default value is `SYSDATE`. + +`run_comment1` + + An additional user-defined comment for the profiler session. The default value is ''. + +`run_number` + + The session number of the profiler session. + +`status` + + Status code returned by the operation. + +## STOP_PROFILER + +The `STOP_PROFILER` function/procedure stops a profiling session and flushes the performance information to the `DBMS_PROFILER` tables and view. The function and procedure signatures are: + +```sql + INTEGER STOP_PROFILER + +STOP_PROFILER +``` + +### Parameters + +`status` + + Status code returned by the operation. + +## Using DBMS_PROFILER + +The `DBMS_PROFILER` package collects and stores performance information about the PL/pgSQL and SPL statements that are executed during a profiling session. You can review the performance information in the tables and views provided by the profiler. + +`DBMS_PROFILER` works by recording a set of performance-related counters and timers for each line of PL/pgSQL or SPL statement that executes in a profiling session. The counters and timers are stored in a table named `SYS.PLSQL_PROFILER_DATA`. When you complete a profiling session, `DBMS_PROFILER` writes a row to the performance statistics table for each line of PL/pgSQL or SPL code that executed in the session. For example, suppose you execute the following function: + +```sql +1 - CREATE OR REPLACE FUNCTION getBalance(acctNumber INTEGER) +2 - RETURNS NUMERIC AS $$ +3 - DECLARE +4 - result NUMERIC; +5 - BEGIN +6 - SELECT INTO result balance FROM acct WHERE id = acctNumber; +7 - +8 - IF (result IS NULL) THEN +9 - RAISE INFO 'Balance is null'; +10- END IF; +11- +12- RETURN result; +13- END; +14- $$ LANGUAGE 'plpgsql'; +``` + +`DBMS_PROFILER` adds one `PLSQL_PROFILER_DATA` entry for each line of code in the `getBalance()` function, including blank lines and comments. The entry corresponding to the `SELECT` statement executed exactly one time and required a very small amount of time to execute. On the other hand, the entry corresponding to the `RAISE INFO` statement executed once or not at all, depending on the value for the `balance` column. + +Some of the lines in this function contain no executable code so the performance statistics for those lines always contains zero values. + +To start a profiling session, invoke the `DBMS_PROFILER.START_PROFILER` function or procedure. Once you've invoked `START_PROFILER`, EDB Postgres Advanced Server profiles every PL/pgSQL or SPL function, procedure, trigger, or anonymous block that your session executes until you either stop or pause the profiler by calling `STOP_PROFILER` or `PAUSE_PROFILER`. + +!!! Note + When you start or resume the profiler, the profiler gathers performance statistics only for functions/procedures/triggers that start after the call to `START_PROFILER` (or `RESUME_PROFILER`). + +While the profiler is active, EDB Postgres Advanced Server records a large set of timers and counters in memory. When you invoke the `STOP_PROFILER` or `FLUSH_DATA` function/procedure, `DBMS_PROFILER` writes those timers and counters to a set of three tables: + +- `SYS.PLSQL_PROFILER_RAWDATA` + + Contains the performance counters and timers for each statement executed in the session. + +- `SYS.PLSQL_PROFILER_RUNS` + + Contains a summary of each run, aggregating the information found in `PLSQL_PROFILER_RAWDATA`. + +- `SYS.PLSQL_PROFILER_UNITS` + + Contains a summary of each code unit (function, procedure, trigger, or anonymous block) executed in a session. + +In addition, `DBMS_PROFILER` defines a view, `SYS.PLSQL_PROFILER_DATA`, which contains a subset of the `PLSQL_PROFILER_RAWDATA` table. + +A user who is not a superuser can gather profiling information but can't view that profiling information unless a superuser grants specific privileges on the profiling tables stored in the `SYS` schema. This permits a nonprivileged user to gather performance statistics without exposing information that the administrator might want to keep secret. + +### Querying the DBMS_PROFILER tables and view + +The following example uses `DBMS_PROFILER` to retrieve performance information for procedures, functions, and triggers included in the sample data distributed with EDB Postgres Advanced Server. + +1. Open the EDB-PSQL command line, and establish a connection to the EDB Postgres Advanced Server database. Use an `EXEC` statement to start the profiling session: + +```sql +acctg=# EXEC dbms_profiler.start_profiler('profile list_emp'); + +EDB-SPL Procedure successfully completed +``` + +!!! Note + The call to `start_profiler()` includes a comment that `DBMS_PROFILER` associates with the profiler session. + +2. Call the `list_emp` function: + +```sql +acctg=# SELECT list_emp(); +__OUTPUT__ +INFO: EMPNO ENAME +INFO: ----- ------- +INFO: 7369 SMITH +INFO: 7499 ALLEN +INFO: 7521 WARD +INFO: 7566 JONES +INFO: 7654 MARTIN +INFO: 7698 BLAKE +INFO: 7782 CLARK +INFO: 7788 SCOTT +INFO: 7839 KING +INFO: 7844 TURNER +INFO: 7876 ADAMS +INFO: 7900 JAMES +INFO: 7902 FORD +INFO: 7934 MILLER + list_emp +---------- + +(1 row) +``` + +3. Stop the profiling session with a call to `dbms_profiler.stop_profiler`: + +```sql +acctg=# EXEC dbms_profiler.stop_profiler; + +EDB-SPL Procedure successfully completed +``` + +4. Start a new session with the `dbms_profiler.start_profiler` function followed by a new comment: + +```sql +acctg=# EXEC dbms_profiler.start_profiler('profile get_dept_name and +emp_sal_trig'); + +EDB-SPL Procedure successfully completed +``` + +5. Invoke the `get_dept_name` function: + +```sql +acctg=# SELECT get_dept_name(10); +__OUTPUT__ + get_dept_name +--------------- + ACCOUNTING +(1 row) +``` + +6. Execute an `UPDATE` statement that causes a trigger to execute: + +```sql +acctg=# UPDATE memp SET sal = 500 WHERE empno = 7902; +INFO: Updating employee 7902 +INFO: ..Old salary: 3000.00 +INFO: ..New salary: 500.00 +INFO: ..Raise: -2500.00 +INFO: User enterprisedb updated employee(s) on 04-FEB-14 +UPDATE 1 +``` + +7. End the profiling session and flush the performance information to the profiling tables: + +```sql +acctg=# EXEC dbms_profiler.stop_profiler; + +EDB-SPL Procedure successfully completed +``` + +8. Query the `plsql_profiler_runs` table to view a list of the profiling sessions, arranged by `runid:` + +```sql +acctg=# SELECT * FROM plsql_profiler_runs; +__OUTPUT__ + runid | related_run | run_owner | run_date + | run_comment | run_total_time | run_system_info + | run_comment1 | spare1 +-------+-------------+--------------+---------------------------+------------- +---------------------------+----------------+-----------------+-------------- ++-------- + 1 | | enterprisedb | 04-FEB-14 09:32:48.874315 | profile + list_emp | 4154 | + | | + 2 | | enterprisedb | 04-FEB-14 09:41:30.546503 | profile + get_dept_name and emp_sal_trig | 2088 | + | | +(2 rows) +``` + +9. Query the `plsql_profiler_units` table to view the amount of time consumed by each unit (function, procedure, or trigger): + +```sql +acctg=# SELECT * FROM plsql_profiler_units; +__OUTPUT__ + runid | unit_number | unit_type | unit_owner | + unit_name | unit_timestamp | total_time | spare1 | spare2 +-------+-------------+-----------+--------------+---------------------------- +-----+----------------+------------+--------+-------- + 1 | 16999 | FUNCTION | enterprisedb | + list_emp() | | 4 | | + 2 | 17002 | FUNCTION | enterprisedb | + user_audit_trig() | | 1 | | + 2 | 17000 | FUNCTION | enterprisedb | get_dept_name(p_deptno + numeric) | | 1 | | + 2 | 17004 | FUNCTION | enterprisedb | + emp_sal_trig() | | 1 | | +(4 rows) +``` + +10. Query the `plsql_profiler_rawdata` table to view a list of the wait-event counters and wait-event times: + +```sql +acctg=# SELECT runid, sourcecode, func_oid, line_number, exec_count, +tuples_returned, time_total FROM plsql_profiler_rawdata; +__OUTPUT__ + runid | sourcecode | + func_oid | line_number | exec_count | tuples_returned | time_total +-------+-----------------------------------------------------------------+--- +-------+-------------+------------+-----------------+------------ + 1 | DECLARE + | 16999 | 1 | 0 | 0 | 0 + 1 | v_empno NUMERIC(4); + | 16999 | 2 | 0 | 0 | 0 + 1 | v_ename VARCHAR(10); + | 16999 | 3 | 0 | 0 | 0 + 1 | emp_cur CURSOR FOR + | 16999 | 4 | 0 | 0 | 0 + 1 | SELECT empno, ename FROM memp ORDER BY empno; + | 16999 | 5 | 0 | 0 | 0 + 1 | BEGIN + | 16999 | 6 | 0 | 0 | 0 + 1 | OPEN emp_cur; + | 16999 | 7 | 0 | 0 | 0 + 1 | RAISE INFO 'EMPNO ENAME'; + | 16999 | 8 | 1 | 0 | 0.001621 + 1 | RAISE INFO '----- -------'; + | 16999 | 9 | 1 | 0 | 0.000301 + 1 | LOOP + | 16999 | 10 | 1 | 0 | 4.6e-05 + 1 | FETCH emp_cur INTO v_empno, v_ename; + | 16999 | 11 | 1 | 0 | 0.001114 + 1 | EXIT WHEN NOT FOUND; + | 16999 | 12 | 15 | 0 | 0.000206 + 1 | RAISE INFO '% %', v_empno, v_ename; + | 16999 | 13 | 15 | 0 | 8.3e-05 + 1 | END LOOP; + | 16999 | 14 | 14 | 0 | 0.000773 + 1 | CLOSE emp_cur; + | 16999 | 15 | 0 | 0 | 0 + 1 | RETURN; + | 16999 | 16 | 1 | 0 | 1e-05 + 1 | END; + | 16999 | 17 | 1 | 0 | 0 + 1 | + | 16999 | 18 | 0 | 0 | 0 + 2 | DECLARE + | 17002 | 1 | 0 | 0 | 0 + 2 | v_action VARCHAR(24); + | 17002 | 2 | 0 | 0 | 0 + 2 | v_text TEXT; + | 17002 | 3 | 0 | 0 | 0 + 2 | BEGIN + | 17002 | 4 | 0 | 0 | 0 + 2 | IF TG_OP = 'INSERT' THEN + | 17002 | 5 | 0 | 0 | 0 + 2 | v_action := ' added employee(s) on '; + | 17002 | 6 | 1 | 0 | 0.000143 + 2 | ELSIF TG_OP = 'UPDATE' THEN + | 17002 | 7 | 0 | 0 | 0 + 2 | v_action := ' updated employee(s) on '; + | 17002 | 8 | 0 | 0 | 0 + 2 | ELSIF TG_OP = 'DELETE' THEN + | 17002 | 9 | 1 | 0 | 3.2e-05 + 2 | v_action := ' deleted employee(s) on '; + | 17002 | 10 | 0 | 0 | 0 + 2 | END IF; + | 17002 | 11 | 0 | 0 | 0 + 2 | v_text := 'User ' || USER || v_action || CURRENT_DATE; + | 17002 | 12 | 0 | 0 | 0 + 2 | RAISE INFO ' %', v_text; + | 17002 | 13 | 1 | 0 | 0.000383 + 2 | RETURN NULL; + | 17002 | 14 | 1 | 0 | 6.3e-05 + 2 | END; + | 17002 | 15 | 1 | 0 | 3.6e-05 + 2 | + | 17002 | 16 | 0 | 0 | 0 + 2 | DECLARE + | 17000 | 1 | 0 | 0 | 0 + 2 | v_dname VARCHAR(14); + | 17000 | 2 | 0 | 0 | 0 + 2 | BEGIN + | 17000 | 3 | 0 | 0 | 0 + 2 | SELECT INTO v_dname dname FROM dept WHERE deptno = p_deptno; + | 17000 | 4 | 0 | 0 | 0 + 2 | RETURN v_dname; + | 17000 | 5 | 1 | 0 | 0.000647 + 2 | IF NOT FOUND THEN + | 17000 | 6 | 1 | 0 | 2.6e-05 + 2 | RAISE INFO 'Invalid department number %', p_deptno; + | 17000 | 7 | 0 | 0 | 0 + 2 | RETURN ''; + | 17000 | 8 | 0 | 0 | 0 + 2 | END IF; + | 17000 | 9 | 0 | 0 | 0 + 2 | END; + | 17000 | 10 | 0 | 0 | 0 + 2 | + | 17000 | 11 | 0 | 0 | 0 + 2 | DECLARE + | 17004 | 1 | 0 | 0 | 0 + 2 | sal_diff NUMERIC(7,2); + | 17004 | 2 | 0 | 0 | 0 + 2 | BEGIN + | 17004 | 3 | 0 | 0 | 0 + 2 | IF TG_OP = 'INSERT' THEN + | 17004 | 4 | 0 | 0 | 0 + 2 | RAISE INFO 'Inserting employee %', NEW.empno; + | 17004 | 5 | 1 | 0 | 8.4e-05 + 2 | RAISE INFO '..New salary: %', NEW.sal; + | 17004 | 6 | 0 | 0 | 0 + 2 | RETURN NEW; + | 17004 | 7 | 0 | 0 | 0 + 2 | END IF; + | 17004 | 8 | 0 | 0 | 0 + 2 | IF TG_OP = 'UPDATE' THEN + | 17004 | 9 | 0 | 0 | 0 + 2 | sal_diff := NEW.sal - OLD.sal; + | 17004 | 10 | 1 | 0 | 0.000355 + 2 | RAISE INFO 'Updating employee %', OLD.empno; + | 17004 | 11 | 1 | 0 | 0.000177 + 2 | RAISE INFO '..Old salary: %', OLD.sal; + | 17004 | 12 | 1 | 0 | 5.5e-05 + 2 | RAISE INFO '..New salary: %', NEW.sal; + | 17004 | 13 | 1 | 0 | 3.1e-05 + 2 | RAISE INFO '..Raise : %', sal_diff; + | 17004 | 14 | 1 | 0 | 2.8e-05 + 2 | RETURN NEW; + | 17004 | 15 | 1 | 0 | 2.7e-05 + 2 | END IF; + | 17004 | 16 | 1 | 0 | 1e-06 + 2 | IF TG_OP = 'DELETE' THEN + | 17004 | 17 | 0 | 0 | 0 + 2 | RAISE INFO 'Deleting employee %', OLD.empno; + | 17004 | 18 | 0 | 0 | 0 + 2 | RAISE INFO '..Old salary: %', OLD.sal; + | 17004 | 19 | 0 | 0 | 0 + 2 | RETURN OLD; + | 17004 | 20 | 0 | 0 | 0 + 2 | END IF; + | 17004 | 21 | 0 | 0 | 0 + 2 | END; + | 17004 | 22 | 0 | 0 | 0 + 2 | + | 17004 | 23 | 0 | 0 | 0 + (68 rows) +                                                                                                                    +``` + +11. Query the `plsql_profiler_data` view to review a subset of the information found in `plsql_profiler_rawdata` table: + +```sql +acctg=# SELECT * FROM plsql_profiler_data; +__OUTPUT__ +runid | unit_number | line# | total_occur | total_time | min_time | max_time +| spare1 | spare2 | spare3 | spare4 +-------+-------------+-------+-------------+------------+----------+--------- +-+--------+--------+--------+-------- + 1 | 16999 | 1 | 0 | 0 | 0 | + 0 | | | | + 1 | 16999 | 2 | 0 | 0 | 0 | + 0 | | | | + 1 | 16999 | 3 | 0 | 0 | 0 | + 0 | | | | + 1 | 16999 | 4 | 0 | 0 | 0 | + 0 | | | | + 1 | 16999 | 5 | 0 | 0 | 0 | + 0 | | | | + 1 | 16999 | 6 | 0 | 0 | 0 | + 0 | | | | + 1 | 16999 | 7 | 0 | 0 | 0 | + 0 | | | | + 1 | 16999 | 8 | 1 | 0.001621 | 0.001621 | + 0.001621 | | | | + 1 | 16999 | 9 | 1 | 0.000301 | 0.000301 | + 0.000301 | | | | + 1 | 16999 | 10 | 1 | 4.6e-05 | 4.6e-05 | 4.6e- + 05 | | | | + 1 | 16999 | 11 | 1 | 0.001114 | 0.001114 | + 0.001114 | | | | + 1 | 16999 | 12 | 15 | 0.000206 | 5e-06 | 7.8e- + 05 | | | | + 1 | 16999 | 13 | 15 | 8.3e-05 | 2e-06 | 4.7e- + 05 | | | | + 1 | 16999 | 14 | 14 | 0.000773 | 4.7e-05 | + 0.000116 | | | | + 1 | 16999 | 15 | 0 | 0 | 0 | + 0 | | | | + 1 | 16999 | 16 | 1 | 1e-05 | 1e-05 | 1e- + 05 | | | | + 1 | 16999 | 17 | 1 | 0 | 0 | + 0 | | | | + 1 | 16999 | 18 | 0 | 0 | 0 | + 0 | | | | + 2 | 17002 | 1 | 0 | 0 | 0 | + 0 | | | | + 2 | 17002 | 2 | 0 | 0 | 0 | + 0 | | | | + 2 | 17002 | 3 | 0 | 0 | 0 | + 0 | | | | + 2 | 17002 | 4 | 0 | 0 | 0 | + 0 | | | | + 2 | 17002 | 5 | 0 | 0 | 0 | + 0 | | | | + 2 | 17002 | 6 | 1 | 0.000143 | 0.000143 | + 0.000143 | | | | + 2 | 17002 | 7 | 0 | 0 | 0 | + 0 | | | | + 2 | 17002 | 8 | 0 | 0 | 0 | + 0 | | | | + 2 | 17002 | 9 | 1 | 3.2e-05 | 3.2e-05 | 3.2e- + 05 | | | | + 2 | 17002 | 10 | 0 | 0 | 0 | + 0 | | | | + 2 | 17002 | 11 | 0 | 0 | 0 | + 0 | | | | + 2 | 17002 | 12 | 0 | 0 | 0 | + 0 | | | | + 2 | 17002 | 13 | 1 | 0.000383 | 0.000383 | + 0.000383 | | | | + 2 | 17002 | 14 | 1 | 6.3e-05 | 6.3e-05 | 6.3e- + 05 | | | | + 2 | 17002 | 15 | 1 | 3.6e-05 | 3.6e-05 | 3.6e- + 05 | | | | + 2 | 17002 | 16 | 0 | 0 | 0 | + 0 | | | | + 2 | 17000 | 1 | 0 | 0 | 0 | + 0 | | | | + 2 | 17000 | 2 | 0 | 0 | 0 | + 0 | | | | + 2 | 17000 | 3 | 0 | 0 | 0 | + 0 | | | | + 2 | 17000 | 4 | 0 | 0 | 0 | + 0 | | | | + 2 | 17000 | 5 | 1 | 0.000647 | 0.000647 | + 0.000647 | | | | + 2 | 17000 | 6 | 1 | 2.6e-05 | 2.6e-05 | 2.6e- + 05 | | | | + 2 | 17000 | 7 | 0 | 0 | 0 | + 0 | | | | + 2 | 17000 | 8 | 0 | 0 | 0 | + 0 | | | | + 2 | 17000 | 9 | 0 | 0 | 0 | + 0 | | | | + 2 | 17000 | 10 | 0 | 0 | 0 | + 0 | | | | + 2 | 17000 | 11 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 1 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 2 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 3 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 4 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 5 | 1 | 8.4e-05 | 8.4e-05 | 8.4e- + 05 | | | | + 2 | 17004 | 6 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 7 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 8 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 9 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 10 | 1 | 0.000355 | 0.000355 | + 0.000355 | | | | + 2 | 17004 | 11 | 1 | 0.000177 | 0.000177 | + 0.000177 | | | | + 2 | 17004 | 12 | 1 | 5.5e-05 | 5.5e-05 | 5.5e- + 05 | | | | + 2 | 17004 | 13 | 1 | 3.1e-05 | 3.1e-05 | 3.1e- + 05 | | | | + 2 | 17004 | 14 | 1 | 2.8e-05 | 2.8e-05 | 2.8e- + 05 | | | | + 2 | 17004 | 15 | 1 | 2.7e-05 | 2.7e-05 | 2.7e- + 05 | | | | + 2 | 17004 | 16 | 1 | 1e-06 | 1e-06 | 1e- + 06 | | | | + 2 | 17004 | 17 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 18 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 19 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 20 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 21 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 22 | 0 | 0 | 0 | + 0 | | | | + 2 | 17004 | 23 | 0 | 0 | 0 | + 0 | | | | +(68 rows) +``` + +### DBMS_PROFILER reference + +The EDB Postgres Advanced Server installer creates the following tables and views that you can query to review PL/SQL performance profile information: + +| Table name | Description | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------- | +| `PLSQL_PROFILER_RUNS` | Table containing information about all profiler runs, organized by `runid`. | +| `PLSQL_PROFILER_UNITS` | Table containing information about all profiler runs, organized by unit. | +| `PLSQL_PROFILER_DATA` | View containing performance statistics. | +| `PLSQL_PROFILER_RAWDATA` | Table containing the performance statistics and the extended performance statistics for DRITA counters and timers. | + +#### PLSQL_PROFILER_RUNS + +The `PLSQL_PROFILER_RUNS` table contains the following columns: + +| Column | Data type | Description | +| ----------------- | ----------------------------- | ---------------------------------------------- | +| `runid` | `INTEGER (NOT NULL)` | Unique identifier (`plsql_profiler_runnumber`) | +| `related_run` | `INTEGER` | The `runid` of a related run | +| `run_owner` | `TEXT` | The role that recorded the profiling session | +| `run_date` | `TIMESTAMP WITHOUT TIME ZONE` | The profiling session start time | +| `run_comment` | `TEXT` | User comments relevant to this run | +| `run_total_time` | `BIGINT` | Run time (in microseconds) | +| `run_system_info` | `TEXT` | Currently unused | +| `run_comment1` | `TEXT` | Additional user comments | +| `spare1` | `TEXT` | Currently unused | + +#### PLSQL_PROFILER_UNITS + +The `PLSQL_PROFILER_UNITS` table contains the following columns: + +| Column | Data type | Description | +| ---------------- | ----------------------------- | -------------------------------------------------------------------------------- | +| `runid` | `INTEGER` | Unique identifier (`plsql_profiler_runnumber`) | +| `unit_number` | `OID` | Corresponds to the OID of the row in the pg_proc table that identifies the unit | +| `unit_type` | `TEXT` | PL/SQL function, procedure, trigger or anonymous block | +| `unit_owner` | `TEXT` | The identity of the role that owns the unit | +| `unit_name` | `TEXT` | The complete signature of the unit | +| `unit_timestamp` | `TIMESTAMP WITHOUT TIME ZONE` | Creation date of the unit (currently NULL) | +| `total_time` | `BIGINT` | Time spent within the unit (in milliseconds) | +| `spare1` | `BIGINT` | Currently unused | +| `spare2` | `BIGINT` | Currently unused | + +#### PLSQL_PROFILER_DATA + +The `PLSQL_PROFILER_DATA` view contains the following columns: + +| Column | Data type | Description | +| ------------- | ------------------ | -------------------------------------------------------- | +| `runid` | `INTEGER` | Unique identifier (`plsql_profiler_runnumber`) | +| `unit_number` | `OID` | Object ID of the unit that contains the current line | +| `line#` | `INTEGER` | Current line number of the profiled workload | +| `total_occur` | `BIGINT` | The number of times that the line was executed | +| `total_time` | `DOUBLE PRECISION` | The amount of time spent executing the line (in seconds) | +| `min_time` | `DOUBLE PRECISION` | The minimum execution time for the line | +| `max_time` | `DOUBLE PRECISION` | The maximum execution time for the line | +| `spare1` | `NUMBER` | Currently unused | +| `spare2` | `NUMBER` | Currently unused | +| `spare3` | `NUMBER` | Currently unused | +| `spare4` | `NUMBER` | Currently unused | + +#### PLSQL_PROFILER_RAWDATA + +The `PLSQL_PROFILER_RAWDATA` table contains the statistical and wait-events information found in the `PLSQL_PROFILER_DATA` view, as well as the performance statistics returned by the DRITA counters and timers. + +| Column | Data type | Description | +| ---------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `runid` | `INTEGER` | The run identifier `(plsql_profiler_runnumber)`. | +| `sourcecode` | `TEXT` | The individual line of profiled code. | +| `func_oid` | `OID` | Object ID of the unit that contains the current line. | +| `line_number` | `INTEGER` | Current line number of the profiled workload. | +| `exec_count` | `BIGINT` | The number of times that the line was executed. | +| `tuples_returned` | `BIGINT` | Currently unused. | +| `time_total` | `DOUBLE PRECISION` | The amount of time spent executing the line, in seconds. | +| `time_shortest` | `DOUBLE PRECISION` | The minimum execution time for the line. | +| `time_longest` | `DOUBLE PRECISION` | The maximum execution time for the line. | +| `num_scans` | `BIGINT` | Currently unused. | +| `tuples_fetched` | `BIGINT` | Currently unused. | +| `tuples_inserted` | `BIGINT` | Currently unused. | +| `tuples_updated` | `BIGINT` | Currently unused. | +| `tuples_deleted` | `BIGINT` | Currently unused. | +| `blocks_fetched` | `BIGINT` | Currently unused. | +| `blocks_hit` | `BIGINT` | Currently unused. | +| `wal_write` | `BIGINT` | A server has waited for a write to the write-ahead log buffer. Expect this value to be high. | +| `wal_flush` | `BIGINT` | A server has waited for the write-ahead log to flush to disk. | +| `wal_file_sync` | `BIGINT` | A server has waited for the write-ahead log to sync to disk (related to the `wal_sync_method` parameter which, by default, is 'fsync' - better performance can be gained by changing this parameter to `open_sync`). | +| `db_file_read` | `BIGINT` | A server has waited for the completion of a read (from disk). | +| `db_file_write` | `BIGINT` | A server has waited for the completion of a write (to disk). | +| `db_file_sync` | `BIGINT` | A server has waited for the operating system to flush all changes to disk. | +| `db_file_extend` | `BIGINT` | A server has waited for the operating system while adding a new page to the end of a file. | +| `sql_parse` | `BIGINT` | Currently unused. | +| `query_plan` | `BIGINT` | A server has generated a query plan. | +| `other_lwlock_acquire` | `BIGINT` | A server has waited for other light-weight lock to protect data. | +| `shared_plan_cache_collision` | `BIGINT` | A server has waited for the completion of the `shared_plan_cache_collision` event. | +| `shared_plan_cache_insert` | `BIGINT` | A server has waited for the completion of the `shared_plan_cache_insert` event. | +| `shared_plan_cache_hit` | `BIGINT` | A server has waited for the completion of the `shared_plan_cache_hit` event. | +| `shared_plan_cache_miss` | `BIGINT` | A server has waited for the completion of the `shared_plan_cache_miss` event. | +| `shared_plan_cache_lock` | `BIGINT` | A server has waited for the completion of the `shared_plan_cache_lock` event. | +| `shared_plan_cache_busy` | `BIGINT` | A server has waited for the completion of the `shared_plan_cache_busy` event. | +| `shmemindexlock` | `BIGINT` | A server has waited to find or allocate space in the shared memory. | +| `oidgenlock` | `BIGINT` | A server has waited to allocate or assign an OID. | +| `xidgenlock` | `BIGINT` | A server has waited to allocate or assign a transaction ID. | +| `procarraylock` | `BIGINT` | A server has waited to get a snapshot or clearing a transaction ID at transaction end. | +| `sinvalreadlock` | `BIGINT` | A server has waited to retrieve or remove messages from shared invalidation queue. | +| `sinvalwritelock` | `BIGINT` | A server has waited to add a message to the shared invalidation queue. | +| `walbufmappinglock` | `BIGINT` | A server has waited to replace a page in WAL buffers. | +| `walwritelock` | `BIGINT` | A server has waited for WAL buffers to be written to disk. | +| `controlfilelock` | `BIGINT` | A server has waited to read or update the control file or creation of a new WAL file. | +| `checkpointlock` | `BIGINT` | A server has waited to perform a checkpoint. | +| `clogcontrollock` | `BIGINT` | A server has waited to read or update the transaction status. | +| `subtranscontrollock` | `BIGINT` | A server has waited to read or update the sub-transaction information. | +| `multixactgenlock` | `BIGINT` | A server has waited to read or update the shared multixact state. | +| `multixactoffsetcontrollock` | `BIGINT` | A server has waited to read or update multixact offset mappings. | +| `multixactmembercontrollock` | `BIGINT` | A server has waited to read or update multixact member mappings. | +| `relcacheinitlock` | `BIGINT` | A server has waited to read or write the relation cache initialization file. | +| `checkpointercommlock` | `BIGINT` | A server has waited to manage the fsync requests. | +| `twophasestatelock` | `BIGINT` | A server has waited to read or update the state of prepared transactions. | +| `tablespacecreatelock` | `BIGINT` | A server has waited to create or drop the tablespace. | +| `btreevacuumlock` | `BIGINT` | A server has waited to read or update the vacuum related information for a B-tree index. | +| `addinshmeminitlock` | `BIGINT` | A server has waited to manage space allocation in shared memory. | +| `autovacuumlock` | `BIGINT` | The autovacuum launcher waiting to read or update the current state of autovacuum workers. | +| `autovacuumschedulelock` | `BIGINT` | A server has waited to ensure that the table selected for a vacuum still needs vacuuming. | +| `syncscanlock` | `BIGINT` | A server has waited to get the start location of a scan on a table for synchronized scans. | +| `relationmappinglock` | `BIGINT` | A server has waited to update the relation map file used to store catalog to file node mapping. | +| `asyncctllock` | `BIGINT` | A server has waited to read or update shared notification state. | +| `asyncqueuelock` | `BIGINT` | A server has waited to read or update the notification messages. | +| `serializablexacthashlock` | `BIGINT` | A server has waited to retrieve or store information about serializable transactions. | +| `serializablefinishedlistlock` | `BIGINT` | A server has waited to access the list of finished serializable transactions. | +| `serializablepredicatelocklistlock` | `BIGINT` | A server has waited to perform an operation on a list of locks held by serializable transactions. | +| `oldserxidlock` | `BIGINT` | A server has waited to read or record the conflicting serializable transactions. | +| `syncreplock` | `BIGINT` | A server has waited to read or update information about synchronous replicas. | +| `backgroundworkerlock` | `BIGINT` | A server has waited to read or update the background worker state. | +| `dynamicsharedmemorycontrollock` | `BIGINT` | A server has waited to read or update the dynamic shared memory state. | +| `autofilelock` | `BIGINT` | A server has waited to update the `postgresql.auto.conf` file. | +| `replicationslotallocationlock` | `BIGINT` | A server has waited to allocate or free a replication slot. | +| `replicationslotcontrollock` | `BIGINT` | A server has waited to read or update replication slot state. | +| `committscontrollock` | `BIGINT` | A server has waited to read or update transaction commit timestamps. | +| `committslock` | `BIGINT` | A server has waited to read or update the last value set for the transaction timestamp. | +| `replicationoriginlock` | `BIGINT` | A server has waited to set up, drop, or use replication origin. | +| `multixacttruncationlock` | `BIGINT` | A server has waited to read or truncate multixact information. | +| `oldsnapshottimemaplock` | `BIGINT` | A server has waited to read or update old snapshot control information. | +| `backendrandomlock` | `BIGINT` | A server has waited to generate a random number. | +| `logicalrepworkerlock` | `BIGINT` | A server has waited for the action on logical replication worker to finish. | +| `clogtruncationlock` | `BIGINT` | A server has waited to truncate the write-ahead log or waiting for write-ahead log truncation to finish. | +| `bulkloadlock` | `BIGINT` | A server has waited for the `bulkloadlock` to bulk upload the data. | +| `edbresourcemanagerlock` | `BIGINT` | The `edbresourcemanagerlock` provides detail about edb resource manager lock module. | +| `wal_write_time` | `BIGINT` | The amount of time that the server has waited for a `wal_write` wait event to write to the write-ahead log buffer (expect this value to be high). | +| `wal_flush_time` | `BIGINT` | The amount of time that the server has waited for a `wal_flush` wait event to write-ahead log to flush to disk. | +| `wal_file_sync_time` | `BIGINT` | The amount of time that the server has waited for a `wal_file_sync` wait event to write-ahead log to sync to disk (related to the wal_sync_method parameter which, by default, is 'fsync' - better performance can be gained by changing this parameter to open_sync). | +| `db_file_read_time` | `BIGINT` | The amount of time that the server has waited for the `db_file_read` wait event for completion of a read (from disk). | +| `db_file_write_time` | `BIGINT` | The amount of time that the server has waited for the `db_file_write` wait event for completion of a write (to disk). | +| `db_file_sync_time` | `BIGINT` | The amount of time that the server has waited for the `db_file_sync` wait event to sync all changes to disk. | +| `db_file_extend_time` | `BIGINT` | The amount of time that the server has waited for the `db_file_extend` wait event while adding a new page to the end of a file. | +| `sql_parse_time` | `BIGINT` | The amount of time that the server has waited for the `sql_parse` wait event to parse a SQL statement. | +| `query_plan_time` | `BIGINT` | The amount of time that the server has waited for the `query_plan` wait event to compute the execution plan for a SQL statement. | +| `other_lwlock_acquire_time` | `BIGINT` | The amount of time that the server has waited for the `other_lwlock_acquire` wait event to protect data. | +| `shared_plan_cache_collision_time` | `BIGINT` | The amount of time that the server has waited for the `shared_plan_cache_collision` wait event. | +| `shared_plan_cache_insert_time` | `BIGINT` | The amount of time that the server has waited for the `shared_plan_cache_insert` wait event. | +| `shared_plan_cache_hit_time` | `BIGINT` | The amount of time that the server has waited for the `shared_plan_cache_hit` wait event. | +| `shared_plan_cache_miss_time` | `BIGINT` | The amount of time that the server has waited for the `shared_plan_cache_miss` wait event. | +| `shared_plan_cache_lock_time` | `BIGINT` | The amount of time that the server has waited for the `shared_plan_cache_lock` wait event. | +| `shared_plan_cache_busy_time` | `BIGINT` | The amount of time that the server has waited for the `shared_plan_cache_busy` wait event. | +| `shmemindexlock_time` | `BIGINT` | The amount of time that the server has waited for the `shmemindexlock` wait event to find or allocate space in the shared memory. | +| `oidgenlock_time` | `BIGINT` | The amount of time that the server has waited for the `oidgenlock` wait event to allocate or assign an OID. | +| `xidgenlock_time` | `BIGINT` | The amount of time that the server has waited for `xidgenlock` wait event to allocate or assign a transaction ID. | +| `procarraylock_time` | `BIGINT` | The amount of time that the server has waited for a `procarraylock` wait event to clear a transaction ID at transaction end. | +| `sinvalreadlock_time` | `BIGINT` | The amount of time that the server has waited for a `sinvalreadlock` wait event to retrieve or remove messages from shared invalidation queue. | +| `sinvalwritelock_time` | `BIGINT` | The amount of time that the server has waited for a `sinvalwritelock` wait event to add a message to the shared invalidation queue. | +| `walbufmappinglock_time` | `BIGINT` | The amount of time that the server has waited for a `walbufmappinglock` wait event to replace a page in WAL buffers. | +| `walwritelock_time` | `BIGINT` | The amount of time that the server has waited for a `walwritelock` wait event to write the WAL buffers to disk. | +| `controlfilelock_time` | `BIGINT` | The amount of time that the server has waited for a `controlfilelock` wait event to read or update the control file or to create a new WAL file. | +| `checkpointlock_time` | `BIGINT` | The amount of time that the server has waited for a `checkpointlock` wait event to perform a checkpoint. | +| `clogcontrollock_time` | `BIGINT` | The amount of time that the server has waited for a `clogcontrollock` wait event to read or update the transaction status. | +| `subtranscontrollock_time` | `BIGINT` | The amount of time that the server has waited for the `subtranscontrollock` wait event to read or update the sub-transaction information. | +| `multixactgenlock_time` | `BIGINT` | The amount of time that the server has waited for the `multixactgenlock` wait event to read or update the shared multixact state. | +| `multixactoffsetcontrollock_time` | `BIGINT` | The amount of time that the server has waited for the `multixactoffsetcontrollock` wait event to read or update multixact offset mappings. | +| `multixactmembercontrollock_time` | `BIGINT` | The amount of time that the server has waited for the `multixactmembercontrollock` wait event to read or update multixact member mappings. | +| `relcacheinitlock_time` | `BIGINT` | The amount of time that the server has waited for the `relcacheinitlock` wait event to read or write the relation cache initialization file. | +| `checkpointercommlock_time` | `BIGINT` | The amount of time that the server has waited for the `checkpointercommlock` wait event to manage the fsync requests. | +| `twophasestatelock_time` | `BIGINT` | The amount of time that the server has waited for the `twophasestatelock` wait event to read or update the state of prepared transactions. | +| `tablespacecreatelock_time` | `BIGINT` | The amount of time that the server has waited for the `tablespacecreatelock` wait event to create or drop the tablespace. | +| `btreevacuumlock_time` | `BIGINT` | The amount of time that the server has waited for the `btreevacuumlock` wait event to read or update the vacuum related information for a B-tree index. | +| `addinshmeminitlock_time` | `BIGINT` | The amount of time that the server has waited for the `addinshmeminitlock` wait event to manage space allocation in shared memory. | +| `autovacuumlock_time` | `BIGINT` | The amount of time that the server has waited for the `autovacuumlock` wait event to read or update the current state of autovacuum workers. | +| `autovacuumschedulelock_time` | `BIGINT` | The amount of time that the server has waited for the `autovacuumschedulelock` wait event to ensure that the table selected for a vacuum still needs vacuuming. | +| `syncscanlock_time` | `BIGINT` | The amount of time that the server has waited for the `syncscanlock` wait event to get the start location of a scan on a table for synchronized scans. | +| `relationmappinglock_time` | `BIGINT` | The amount of time that the server has waited for the `relationmappinglock` wait event to update the relation map file used to store catalog to file node mapping. | +| `asyncctllock_time` | `BIGINT` | The amount of time that the server has waited for the `asyncctllock` wait event to read or update shared notification state. | +| `asyncqueuelock_time` | `BIGINT` | The amount of time that the server has waited for the `asyncqueuelock` wait event to read or update the notification messages. | +| `serializablexacthashlock_time` | `BIGINT` | The amount of time that the server has waited for the `serializablexacthashlock` wait event to retrieve or store information about serializable transactions. | +| `serializablefinishedlistlock_time` | `BIGINT` | The amount of time that the server has waited for the `serializablefinishedlistlock` wait event to access the list of finished serializable transactions. | +| `serializablepredicatelocklistlock_time` | `BIGINT` | The amount of time that the server has waited for the `serializablepredicatelocklistlock` wait event to perform an operation on a list of locks held by serializable transactions. | +| `oldserxidlock_time` | `BIGINT` | The amount of time that the server has waited for the `oldserxidlock` wait event to read or record the conflicting serializable transactions. | +| `syncreplock_time` | `BIGINT` | The amount of time that the server has waited for the `syncreplock` wait event to read or update information about synchronous replicas. | +| `backgroundworkerlock_time` | `BIGINT` | The amount of time that the server has waited for the `backgroundworkerlock` wait event to read or update the background worker state. | +| `dynamicsharedmemorycontrollock_time` | `BIGINT` | The amount of time that the server has waited for the `dynamicsharedmemorycontrollock` wait event to read or update the dynamic shared memory state. | +| `autofilelock_time` | `BIGINT` | The amount of time that the server has waited for the `autofilelock` wait event to update the `postgresql.auto.conf` file. | +| `replicationslotallocationlock_time` | `BIGINT` | The amount of time that the server has waited for the `replicationslotallocationlock` wait event to allocate or free a replication slot. | +| `replicationslotcontrollock_time` | `BIGINT` | The amount of time that the server has waited for the `replicationslotcontrollock` wait event to read or update replication slot state. | +| `committscontrollock_time` | `BIGINT` | The amount of time that the server has waited for the `committscontrollock` wait event to read or update transaction commit timestamps. | +| `committslock_time` | `BIGINT` | The amount of time that the server has waited for the `committslock` wait event to read or update the last value set for the transaction timestamp. | +| `replicationoriginlock_time` | `BIGINT` | The amount of time that the server has waited for the `replicationoriginlock` wait event to set up, drop, or use replication origin. | +| `multixacttruncationlock_time` | `BIGINT` | The amount of time that the server has waited for the `multixacttruncationlock` wait event to read or truncate multixact information. | +| `oldsnapshottimemaplock_time` | `BIGINT` | The amount of time that the server has waited for the `oldsnapshottimemaplock` wait event to read or update old snapshot control information. | +| `backendrandomlock_time` | `BIGINT` | The amount of time that the server has waited for the `backendrandomlock` wait event to generate a random number. | +| `logicalrepworkerlock_time` | `BIGINT` | The amount of time that the server has waited for the `logicalrepworkerlock` wait event for an action on logical replication worker to finish. | +| `clogtruncationlock_time` | `BIGINT` | The amount of time that the server has waited for the `clogtruncationlock` wait event to truncate the write-ahead log or waiting for write-ahead log truncation to finish. | +| `bulkloadlock_time` | `BIGINT` | The amount of time that the server has waited for the `bulkloadlock` wait event to bulk upload the data. | +| `edbresourcemanagerlock_time` | `BIGINT` | The amount of time that the server has waited for the `edbresourcemanagerlock` wait event. | +| `totalwaits` | `BIGINT` | The total number of event waits. | +| `totalwaittime` | `BIGINT` | The total time spent waiting for an event. | diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/12_dbms_random.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/12_dbms_random.mdx new file mode 100644 index 00000000000..094439d2b4e --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/12_dbms_random.mdx @@ -0,0 +1,236 @@ +--- +title: "DBMS_RANDOM" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.26.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.199.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.157.html" +--- + +The `DBMS_RANDOM` package provides methods to generate random values. The procedures and functions available in the `DBMS_RANDOM` package are listed in the following table. + +| Function/procedure | Return type | Description | +| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `INITIALIZE(val)` | n/a | Initializes the `DBMS_RANDOM` package with the specified seed `value`. Deprecated, but supported for backward compatibility. | +| `NORMAL()` | `NUMBER` | Returns a random `NUMBER`. | +| `RANDOM` | `INTEGER` | Returns a random `INTEGER` with a value greater than or equal to -2^31 and less than 2^31. Deprecated, but supported for backward compatibility. | +| `SEED(val)` | n/a | Resets the seed with the specified `value`. | +| `SEED(val)` | n/a | Resets the seed with the specified `value`. | +| `STRING(opt, len)` | `VARCHAR2` | Returns a random string. | +| `TERMINATE` | n/a | `TERMINATE` has no effect. Deprecated, but supported for backward compatibility. | +| `VALUE` | `NUMBER` | Returns a random number with a value greater than or equal to `0` and less than `1`, with 38-digit precision. | +| `VALUE(low, high)` | `NUMBER` | Returns a random number with a value greater than or equal to `low` and less than `high`. | + +## INITIALIZE + +The `INITIALIZE` procedure initializes the `DBMS_RANDOM` package with a seed value. The signature is: + +```sql +INITIALIZE( IN INTEGER) +``` + +This procedure is deprecated. It is included for backward compatibility. + +### Parameters + +`val` + + `val` is the seed value used by the `DBMS_RANDOM` package algorithm. + +### Example + +The following code shows a call to the `INITIALIZE` procedure that initializes the `DBMS_RANDOM` package with the seed value 6475: + +```sql +DBMS_RANDOM.INITIALIZE(6475); +``` + +## NORMAL + +The `NORMAL` function returns a random number of type `NUMBER`. The signature is: + +```sql + NUMBER NORMAL() +``` + +### Parameters + +`result` + + `result` is a random value of type `NUMBER`. + +### Example + +The following code shows a call to the `NORMAL` function: + +```sql +x:= DBMS_RANDOM.NORMAL(); +``` + +## RANDOM + +The `RANDOM` function returns a random `INTEGER` value that is greater than or equal to -2 ^31 and less than 2 ^31. The signature is: + +```sql + INTEGER RANDOM() +``` + +This function is deprecated. It is included for backward compatibility. + +### Parameters + +`result` + + `result` is a random value of type `INTEGER`. + +### Example + +The following code shows a call to the `RANDOM` function. The call returns a random number: + +```sql +x := DBMS_RANDOM.RANDOM(); +``` + +## SEED + +The first form of the `SEED` procedure resets the seed value for the `DBMS_RANDOM` package with an `INTEGER` value. The `SEED` procedure is available in two forms. The signature of the first form is: + +```sql +SEED( IN INTEGER) +``` + +### Parameters + +`val` + + `val` is the seed value used by the `DBMS_RANDOM` package algorithm. + +### Example + +The following code shows a call to the `SEED` procedure. The call sets the seed value at 8495. + +```sql +DBMS_RANDOM.SEED(8495); +``` + +## SEED + +The second form of the `SEED` procedure resets the seed value for the `DBMS_RANDOM` package with a string value. The `SEED` procedure is available in two forms. The signature of the second form is: + +```sql +SEED( IN VARCHAR2) +``` + +### Parameters + +`val` + + `val` is the seed value used by the `DBMS_RANDOM` package algorithm. + +### Example + +The following code shows a call to the `SEED` procedure. The call sets the seed value to `abc123`. + +```sql +DBMS_RANDOM.SEED('abc123'); +``` + +## STRING + +The `STRING` function returns a random `VARCHAR2` string in a user-specified format. The signature of the `STRING` function is: + +```sql + VARCHAR2 STRING( IN CHAR, IN NUMBER) +``` + +### Parameters + +`opt` + + Formatting option for the returned string. `option` can be: + +| Option | Specifies formatting option | +| ---------- | ------------------------------- | +| `u` or `U` | Uppercase alpha string | +| `l` or `L` | Lowercase alpha string | +| `a` or `A` | Mixed-case string | +| `x` or `X` | Uppercase alphanumeric string | +| `p` or `P` | Any printable characters | + +`len` + + The length of the returned string. + +`result` + + `result` is a random value of type `VARCHAR2`. + +### Example + +The following code shows a call to the `STRING` function. The call returns a random alphanumeric character string that is 10 characters long. + +```sql +x := DBMS_RANDOM.STRING('X', 10); +``` + +## TERMINATE + +The `TERMINATE` procedure has no effect. The signature is: + +```sql +TERMINATE +``` + +The `TERMINATE` procedure is deprecated. The procedure is supported for compatibility. + +## VALUE + +The `VALUE` function returns a random `NUMBER` that is greater than or equal to 0 and less than 1, with 38-digit precision. The `VALUE` function has two forms. The signature of the first form is: + +```sql + NUMBER VALUE() +``` + +### Parameters + +`result` + + `result` is a random value of type `NUMBER`. + +### Example + +The following code shows a call to the `VALUE` function. The call returns a random `NUMBER`: + +```sql +x := DBMS_RANDOM.VALUE(); +``` + +## VALUE + +The `VALUE` function returns a random `NUMBER` with a value that is between boundaries that you specify. The `VALUE` function has two forms. The signature of the second form is: + +```sql + NUMBER VALUE( IN NUMBER, IN NUMBER) +``` + +### Parameters + +`low` + + `low` specifies the lower boundary for the random value. The random value can be equal to `low`. + +`high` + + `high` specifies the upper boundary for the random value. The random value is less than `high`. + +`result` + + `result` is a random value of type `NUMBER`. + +### Example + +The following code shows a call to the `VALUE` function. The call returns a random `NUMBER` with a value that is greater than or equal to 1 and less than 100: + +```sql +x := DBMS_RANDOM.VALUE(1, 100); +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/13_dbms_redact.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/13_dbms_redact.mdx new file mode 100644 index 00000000000..a58136a25e9 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/13_dbms_redact.mdx @@ -0,0 +1,709 @@ +--- +title: "DBMS_REDACT" +--- + +The `DBMS_REDACT` package enables you to redact or mask data returned by a query. The `DBMS_REDACT` package provides a procedure to create, alter, enable, disable, and drop policies. The procedures available in the `DBMS_REDACT` package are listed in the following table. + +| Function/procedure | Function or Procedure | Return Type | Description | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------- | --------------------------------------------------------------------- | +| `ADD_POLICY(object_schema, object_name, policy_name, policy_description, column_name, column_description, function_type, function_parameters, expression, enable, regexp_pattern, regexp_replace_string, regexp_position, regexp_occurence, regexp_match_parameter, custom_function_expression)` | Procedure | n/a | Adds a data redaction policy. | +| `ALTER_POLICY(object_schema, object_name, policy_name, action, column_name, function_type, function_parameters, expression, regexp_pattern, regexp_replace_string, regexp_position, regexp_occurence, regexp_match_parameter, policy_description, column_description, custom_function_expression)` | Procedure | n/a | Alters the existing data redaction policy. | +| `DISABLE_POLICY(object_schema, object_name, policy_name)` | Procedure | n/a | Disables the existing data redaction policy. | +| `ENABLE_POLICY(object_schema, object_name, policy_name)` | Procedure | n/a | Enables a previously disabled data redaction policy. | +| `DROP_POLICY(object_schema, object_name, policy_name)` | Procedure | n/a | Drops a data redaction policy. | +| `UPDATE_FULL_REDACTION_VALUES(number_val, binfloat_val, bindouble_val, char_val, varchar_val, nchar_val, nvarchar_val, datecol_val, ts_val, tswtz_val, blob_val, clob_val, nclob_val)` | Procedure | n/a | Updates the full redaction default values for the specified datatype. | + +The data redaction feature uses the `DBMS_REDACT` package to define policies or conditions to redact data in a column based on the table column type and redaction type. + +You must be the owner of the table to create or change the data redaction policies. The users are exempted from all the column redaction policies, which the table owner or superuser is by default. + +## Using DBMS_REDACT constants and function parameters + +The `DBMS_REDACT` package uses the constants and redacts the column data by using any one of the data redaction types. The redaction type can be decided based on the `function_type` parameter of `dbms_redact.add_policy` and `dbms_redact.alter_policy` procedure. The table highlights the values for `function_type` parameters of `dbms_redact.add_policy` and `dbms_redact.alter_policy`. + +| Constant | Type | Value | Description | +| --------- | --------- | ----- | --------------------------------------------------------------------------------------------------------- | +| `NONE` | `INTEGER` | `0` | No redaction, zero effect on the result of a query against table. | +| `FULL` | `INTEGER` | `1` | Full redaction, redacts full values of the column data. | +| `PARTIAL` | `INTEGER` | `2` | Partial redaction, redacts a portion of the column data. | +| `RANDOM` | `INTEGER` | `4` | Random redaction, each query results in a different random value depending on the datatype of the column. | +| `REGEXP` | `INTEGER` | `5` | Regular-expression-based redaction, searches for the pattern of data to redact. | +| `CUSTOM` | `INTEGER` | `99` | Custom redaction type. | + +The following table shows the values for the `action` parameter of `dbms_redact.alter_policy`. + +| Constant | Type | Value | Description | +| ------------------------ | --------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `ADD_COLUMN` | `INTEGER` | `1` | Adds a column to the redaction policy. | +| `DROP_COLUMN` | `INTEGER` | `2` | Drops a column from the redaction policy. | +| `MODIFY_EXPRESSION` | `INTEGER` | `3` | Modifies the expression of a redaction policy. The redaction is applied when the expression evaluates to the `BOOLEAN` value to `TRUE`. | +| `MODIFY_COLUMN` | `INTEGER` | `4` | Modifies a column in the redaction policy to change the redaction function type or function parameter. | +| `SET_POLICY_DESCRIPTION` | `INTEGER` | `5` | Sets the redaction policy description. | +| `SET_COLUMN_DESCRIPTION` | `INTEGER` | `6` | Sets a description for the redaction performed on the column. | + +The partial data redaction enables you to redact only a portion of the column data. To use partial redaction, you must set the `dbms_redact.add_policy` procedure `function_type` parameter to `dbms_redact.partial` and use the `function_parameters` parameter to specify the partial redaction behavior. + +The data redaction feature provides a predefined format to configure policies that use the following datatype: + +- `Character` +- `Number` +- `Datetime` + +The following table highlights the format descriptor for partial redaction with respect to datatype. The example shows how to perform a redaction for a string datatype (in this scenario, a Social Security Number (SSN)), a `Number` datatype, and a `DATE` datatype. + +| Datatype | Format descriptor | Description | Examples | +| --------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Character | `REDACT_PARTIAL_INPUT_FORMAT` | Specifies the input format. Enter `V` for each character from the input string to be possibly redacted. Enter `F` for each character from the input string that can be considered as a separator such as blank spaces or hyphens. | Consider `'VVVFVVFVVVV,VVV-VV-VVVV,X,1,5'` for masking first 5 digits of SSN strings such as `123-45-6789`, adding a hyphen to format it and thereby resulting in strings such as `XXX-XX-6789.` The field value `VVVFVVFVVVV` for matching SSN strings such as `123-45-6789`. | +| | `REDACT_PARTIAL_OUTPUT_FORMAT` | Specifies the output format. Enter `V` for each character from the input string to be possibly redacted. Replace each `F` character from the input format with a character such as a hyphen or any other separator. | The field value `VVV-VV-VVVV` can be used to redact SSN strings into `XXX-XX-6789` where `X` comes from `REDACT_PARTIAL_MASKCHAR` field. | +| | `REDACT_PARTIAL_MASKCHAR` | Specifies the character to use for redaction. | The value `X` for redacting SSN strings into `XXX-XX-6789`. | +| | `REDACT_PARTIAL_MASKFROM` | Specifies the `V` in the input format from which to start the redaction. | The value `1` for redacting SSN strings starting at the first `V` of the input format of `VVVFVVFVVVV` into strings such as `XXX-XX-6789`. | +| | `REDACT_PARTIAL_MASKTO` | Specifies the `V` in the input format at which to end the redaction. | The value `5` for redacting SSN strings up to and including the fifth `V` in the input format of `VVVFVVFVVVV` into strings such as `XXX-XX-6789`. | +| Number | `REDACT_PARTIAL_MASKCHAR` | Specifies the character to display in the range between 0 and 9. | `‘9, 1, 5’` for redacting the first five digits of the Social Security Number `123456789` into `999996789`. | +| | `REDACT_PARTIAL_MASKFROM` | Specifies the start-digit position for redaction. | | +| | `REDACT_PARTIAL_MASKTO` | Specifies the end-digit position for redaction. | | +| Datetime | `REDACT_PARTIAL_DATE_MONTH` | `‘m’` redacts the month. To mask a specific month, specify `‘m#’`, where # indicates the month specified by its number between `1` and `12`. | `m3` displays as March. | +| | `REDACT_PARTIAL_DATE_DAY` | `‘d’` redacts the day of the month. To mask with a day of the month, append `1-31` to a lowercase `d`. | `d3` displays as `03`. | +| | `REDACT_PARTIAL_DATE_YEAR` | `‘y’` redacts the year. To mask with a year, append `1-9999` to a lowercase `y`. | `y1960` displays as `60`. | +| | `REDACT_PARTIAL_DATE_HOUR` | `‘h’` redacts the hour. To mask with an hour, append `0-23` to a lowercase `h`. | `h18` displays as `18`. | +| | `REDACT_PARTIAL_DATE_MINUTE` | `‘m’` redacts the minute. To mask with a minute, append `0-59` to a lowercase `m`. | `m20` displays as `20`. | +| | `REDACT_PARTIAL_DATE_SECOND` | `‘s’` redacts the second. To mask with a second, append `0-59` to a lowercase `s`. | `s40` displays as `40`. | + +The following table represents `function_parameters` values that you can use in partial redaction. + +| Function parameter | Data type | Value | Description | +| ----------------------------- | ---------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `REDACT_US_SSN_F5` | `VARCHAR2` | `'VVVFVVFVVVV,VVV-VV-VVVV,X,1,5'` | Redacts the first 5 numbers of SSN. **Example:** The number `123-45-6789` becomes `XXX-XX-6789`. | +| `REDACT_US_SSN_L4` | `VARCHAR2` | `'VVVFVVFVVVV,VVV-VV-VVVV,X,6,9'` | Redacts the last 4 numbers of SSN. **Example:** The number `123-45-6789` becomes `123-45-XXXX`. | +| `REDACT_US_SSN_ENTIRE` | `VARCHAR2` | `'VVVFVVFVVVV,VVV-VV-VVVV,X,1,9'` | Redacts the entire SSN. **Example:** The number `123-45-6789` becomes `XXX-XX-XXXX`. | +| `REDACT_NUM_US_SSN_F5` | `VARCHAR2` | `'9,1,5'` | Redacts the first 5 numbers of SSN when the column is a number datatype. **Example:** The number `123456789` becomes `999996789`. | +| `REDACT_NUM_US_SSN_L4` | `VARCHAR2` | `'9,6,9'` | Redacts the last 4 numbers of SSN when the column is a number datatype. **Example:** The number `123456789` becomes `123459999`. | +| `REDACT_NUM_US_SSN_ENTIRE` | `VARCHAR2` | `'9,1,9'` | Redacts the entire SSN when the column is a number datatype. **Example:** The number `123456789` becomes `999999999`. | +| `REDACT_ZIP_CODE` | `VARCHAR2` | `'VVVVV,VVVVV,X,1,5'` | Redacts a 5 digit zip code. **Example:** `12345`becomes `XXXXX`. | +| `REDACT_NUM_ZIP_CODE` | `VARCHAR2` | `'9,1,5'` | Redacts a 5 digit zip code when the column is a number datatype. **Example:** `12345`becomes `99999`. | +| `REDACT_CCN16_F12` | `VARCHAR2` | `'VVVVFVVVVFVVVVFVVVV,VVVV-VVVV-VVVV-VVVV,*,1,12'` | Redacts a 16 digit credit card number and displays only 4 digits. **Example:** `1234 5678 9000 2358` becomes `****-****-****-2358`. | +| `REDACT_DATE_MILLENNIUM` | `VARCHAR2` | `'m1d1y2000'` | Redacts a date that is in the `DD-MM-YY` format. **Example:** Redacts all date to `01-JAN-2000`. | +| `REDACT_DATE_EPOCH` | `VARCHAR2` | `'m1d1y1970'` | Redacts all dates to `01-JAN-70`. | +| `REDACT_AMEX_CCN_FORMATTED` | `VARCHAR2` | `'VVVVFVVVVVVFVVVVV,VVVV-VVVVVV-VVVVV,*,1,10'` | Redacts the Amercian Express credit card number and replaces the digit with `*` except for the last 5 digits. **Example:** The credit card number `1234 567890 34500` becomes `**** ****** 34500`. | +| `REDACT_AMEX_CCN_NUMBER` | `VARCHAR2` | `'0,1,10'` | Redacts the Amercian Express credit card number and replaces the digit with `0` except for the last 5 digits. **Example:** The credit card number `1234 567890 34500` becomes `0000 000000 34500`. | +| `REDACT_SIN_FORMATTED` | `VARCHAR2` | `'VVVFVVVFVVV,VVV-VVV-VVV,*,1,6'` | Redacts the Social Insurance Number by replacing the first 6 digits by `*`. **Example:** `123-456-789` becomes `***-***-789`. | +| `REDACT_SIN_NUMBER` | `VARCHAR2` | `'9,1,6'` | Redacts the Social Insurance Number by replacing the first 6 digits by `9`. **Example:** `123456789` becomes `999999789`. | +| `REDACT_SIN_UNFORMATTED` | `VARCHAR2` | `'VVVVVVVVV,VVVVVVVVV,*,1,6'` | Redacts the Social Insurance Number by replacing the first 6 digits by `*`. **Example:** `123456789` becomes `******789`. | +| `REDACT_CCN_FORMATTED` | `VARCHAR2` | `'VVVVFVVVVFVVVVFVVVV,VVVV-VVVV-VVVV-VVVV,*,1,12'` | Redacts a credit card number by `*` and displays only 4 digits. **Example:** The credit card number `1234-5678-9000-4671` becomes `****-****-****-4671`. | +| `REDACT_CCN_NUMBER` | `VARCHAR2` | `'9,1,12'` | Redacts a credit card number by `0` except the last 4 digits. **Example:** The credit card number `1234567890004671` becomes `0000000000004671`. | +| `REDACT_NA_PHONE_FORMATTED` | `VARCHAR2` | `‘VVVFVVVFVVVV,VVV-VVV-VVVV,X,4,10'` | Redacts the North American phone number by `X` leaving the area code. **Example:** `123-456-7890` becomes `123-XXX-XXXX`. | +| `REDACT_NA_PHONE_NUMBER` | `VARCHAR2` | `'0,4,10'` | Redacts the North American phone number by `0` leaving the area code. **Example:** `1234567890` becomes `1230000000`. | +| `REDACT_NA_PHONE_UNFORMATTED` | `VARCHAR2` | `'VVVVVVVVVV,VVVVVVVVVV,X,4,10'` | Redacts the North American phone number by `X` leaving the area code. **Example:** `1234567890` becomes `123XXXXXXX`. | +| `REDACT_UK_NIN_FORMATTED` | `VARCHAR2` | `'VVFVVFVVFVVFV,VV VV VV VV V,X,3,8'` | Redacts the UK National Insurance Number by `X` but leaving the alphabetic characters. **Example:** `NY 22 01 34 D` becomes `NY XX XX XX D`. | +| `REDACT_UK_NIN_UNFORMATTED` | `VARCHAR2` | `'VVVVVVVVV,VVVVVVVVV,X,3,8'` | Redacts the UK National Insurance Number by `X` but leaving the alphabetic characters. **Example:** `NY220134D` becomes `NYXXXXXXD`. | + +A regular expression-based redaction searches for patterns of data to redact. The `regexp_pattern` search the values for the `regexp_replace_string` to change the value. The following table shows the `regexp_pattern` values that you can use during `REGEXP` based redaction. + +| Function parameter and description | Data type | Value | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------: | :-----------------------------------------------------: | +| `RE_PATTERN_CC_L6_T4`: Searches for the middle digits of a credit card number that includes 6 leading digits and 4 trailing digits.
The `regexp_replace_string` setting to use with the format is `RE_REDACT_CC_MIDDLE_DIGITS` that replaces the identified pattern with the characters specified by the `RE_REDACT_CC_MIDDLE_DIGITS` parameter. | `VARCHAR2` | `'(\d\d\d\d\d\d)(\d\d\d*)(\d\d\d\d)'` | +| `RE_PATTERN_ANY_DIGIT`: Searches for any digit and replaces the identified pattern with the characters specified by the following values of the `regexp_replace_string` parameter.
`regexp_replace_string=> RE_REDACT_WITH_SINGLE_X`
(replaces any matched digit with the `X` character).
`regexp_replace_string=> RE_REDACT_WITH_SINGLE_1`
(replaces any matched digit with the `1` character). | `VARCHAR2` | `'\d'` | +| `RE_PATTERN_US_PHONE`: Searches for the U.S. phone number and replaces the identified pattern with the characters specified by the `regexp_replace_string` parameter.
`regexp_replace_string=> RE_REDACT_US_PHONE_L7`
(searches the phone number and then replaces the last 7 digits). | `VARCHAR2` | `'(\(\d\d\d\)\|\d\d\d)-(\d\d\d)-(\d\d\d\d)'` | +| `RE_PATTERN_EMAIL_ADDRESS`: Searches for the email address and replaces the identified pattern with the characters specified by the following values of the `regexp_replace_string` parameter.
`regexp_replace_string=> RE_REDACT_EMAIL_NAME`
(finds the email address and redacts the email username).
`regexp_replace_string=> RE_REDACT_EMAIL_DOMAIN`
(finds the email address and redacts the email domain).
`regexp_replace_string=> RE_REDACT_EMAIL_ENTIRE`
(finds the email address and redacts the entire email address). | `VARCHAR2` | `'([A-Za-z0-9._%+-]+)@([A-Za-z0-9.-]+\.[A-Za-z]{2,4})'` | +| `RE_PATTERN_IP_ADDRESS`: Searches for an IP address and replaces the identified pattern with the characters specified by the `regexp_replace_string` parameter. The `regexp_replace_string` parameter to be used is `RE_REDACT_IP_L3` that replaces the last section of an IP address with `999` and indicates it is redacted. | `VARCHAR2` | `'(\d{1,3}\.\d{1,3}\.\d{1,3})\.\d{1,3}'` | +| `RE_PATTERN_AMEX_CCN`: Searches for the American Express credit card number. The `regexp_replace_string` parameter to be used is `RE_REDACT_AMEX_CCN` that redacts all of the digits except the last 5. | `VARCHAR2` | `'.*(\d\d\d\d\d)$'` | +| `RE_PATTERN_CCN`: Searches for the credit card number other than American Express credit cards. The `regexp_replace_string` parameter to be used is `RE_REDACT_CCN` that redacts all of the digits except the last 4. | `VARCHAR2` | `'.*(\d\d\d\d)$'` | +| `RE_PATTERN_US_SSN`: Searches the SSN number and replaces the identified pattern with the characters specified by the `regexp_replace_string` parameter.
`'\1-XXX-XXXX'` or `'XXX-XXX-\3'` return `123-XXX-XXXX` or `XXX-XXX-6789` for the value `'123-45-6789'` respectively. | `VARCHAR2` | `'(\d\d\d)-(\d\d)-(\d\d\d\d)'` | +| | | | + +This table shows the `regexp_replace_string` values that you can use during `REGEXP` based redaction. + +| Function parameter | Data type | Value | Description | +| ---------------------------- | ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `RE_REDACT_CC_MIDDLE_DIGITS` | `VARCHAR2` | `'\1XXXXXX\3'` | Redacts the middle digits of a credit card number according to the `regexp_pattern` parameter with the `RE_PATTERN_CC_L6_T4` format and replaces each redacted character with an `X`.

**Example:** The credit card number `1234 5678 9000 2490` becomes `1234 56XX XXXX 2490`. | +| `RE_REDACT_WITH_SINGLE_X` | `VARCHAR2` | `'X'` | Replaces the data with a single `X` character for each matching pattern as specified by setting the `regexp_pattern` parameter with the `RE_PATTERN_ANY_DIGIT` format.

**Example:** The credit card number `1234 5678 9000 2490` becomes `XXXX XXXX XXXX XXXX`. | +| `RE_REDACT_WITH_SINGLE_1` | `VARCHAR2` | `'1'` | Replaces the data with a single `1` digit for each of the data digits as specified by setting the `regexp_pattern` parameter with the `RE_PATTERN_ANY_DIGIT` format.

**Example:** The credit card number `1234 5678 9000 2490` becomes `1111 1111 1111 1111`. | +| `RE_REDACT_US_PHONE_L7` | `VARCHAR2` | `'\1-XXX-XXXX'` | Redacts the last 7 digits of U.S phone number according to the `regexp_pattern` parameter with the `RE_PATTERN_US_PHONE` format and replaces each redacted character with an `X`.

**Example:** The phone number `123-444-5900` becomes `123-XXX-XXXX`. | +| `RE_REDACT_EMAIL_NAME` | `VARCHAR2` | `'xxxx@\2'` | Redacts the email name according to the `regexp_pattern` parameter with the `RE_PATTERN_EMAIL_ADDRESS` format and replaces the email username with the four `x` characters.

**Example:** The email address `sjohn@example.com` becomes `xxxx@example.com`. | +| `RE_REDACT_EMAIL_DOMAIN` | `VARCHAR2` | `'\1@xxxxx.com'` | Redacts the email domain name according to the `regexp_pattern` parameter with the `RE_PATTERN_EMAIL_ADDRESS` format and replaces the domain with the five `x` characters.

**Example:** The email address `sjohn@example.com` becomes `sjohn@xxxxx.com`. | +| `RE_REDACT_EMAIL_ENTIRE` | `VARCHAR2` | `'xxxx@xxxxx.com'` | Redacts the entire email address according to the `regexp_pattern` parameter with the `RE_PATTERN_EMAIL_ADDRESS` format and replaces the email address with the `x` characters.

**Example:** The email address `sjohn@example.com` becomes `xxxx@xxxxx.com`. | +| `RE_REDACT_IP_L3` | `VARCHAR2` | `'\1.999'` | Redacts the last 3 digits of an IP address according to the `regexp_pattern` parameter with the `RE_PATTERN_IP_ADDRESS` format.

**Example:** The IP address `172.0.1.258` becomes `172.0.1.999`, which is an invalid IP address. | +| `RE_REDACT_AMEX_CCN` | `VARCHAR2` | `'**********\1'` | Redacts the first 10 digits of an American Express credit card number according to the `regexp_pattern` parameter with the `RE_PATTERN_AMEX_CCN` format.

**Example:** `123456789062816` becomes `**********62816`. | +| `RE_REDACT_CCN` | `VARCHAR2` | `'************\1'` | Redacts the first 12 digits of a credit card number as specified by the `regexp_pattern` parameter with the `RE_PATTERN_CCN` format.

**Example:** `8749012678345671` becomes `************5671`. | + +The following tables show the `regexp_position` value and `regexp_occurence` values that you can use during `REGEXP` based redaction. + +| Function parameter | Data type | Value | Description | +| ------------------ | --------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `RE_BEGINNING` | `INTEGER` | `1` | Specifies the position of a character where search must begin. By default, the value is `1` that indicates the search begins at the first character of `source_char`. | + +| Function parameter | Data type | Value | Description | +| ------------------ | --------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `RE_ALL` | `INTEGER` | `0` | Specifies the replacement occurrence of a substring. If the value is `0`, then the replacement of each matching substring occurs. | +| `RE_FIRST` | `INTEGER` | `1` | Specifies the replacement occurrence of a substring. If the value is `1`, then the replacement of the first matching substring occurs. | + +The following table shows the `regexp_match_parameter` values that you can use during `REGEXP` based redaction which lets you change the default matching behavior of a function. + +| Function parameter | Data type | Value | Description | +| ---------------------- | ---------- | ----- | --------------------------------------------------------------------------------------------------------------- | +| `RE_CASE_SENSITIVE` | `VARCHAR2` | `'c'` | Specifies the case-sensitive matching. | +| `RE_CASE_INSENSITIVE` | `VARCHAR2` | `'i'` | Specifies the case-insensitive matching. | +| `RE_MULTIPLE_LINES` | `VARCHAR2` | `'m'` | Treats the source string as multiple lines but if you omit this parameter, then it indicates as a single line. | +| `RE_NEWLINE_WILDCARD` | `VARCHAR2` | `'n'` | Specifies the period (.), but if you omit this parameter, then the period does not match the newline character. | +| `RE_IGNORE_WHITESPACE` | `VARCHAR2` | `'x'` | Ignores the whitespace characters. | + +!!! Note + If you create a redaction policy based on a numeric-type column, then make sure that the result after redaction is a number and set the replacement string accordingly to avoid runtime errors. + +!!! Note + If you create a redaction policy based on a character-type column, then make sure that a length of the result after redaction is compatible with the column type and set the replacement string accordingly to avoid runtime errors. + +## ADD_POLICY + +The `add_policy` procedure creates a new data redaction policy for a table. + +```sql +PROCEDURE add_policy ( + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2, + IN VARCHAR2, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN INTEGER DEFAULT DBMS_REDACT.FULL, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2, + IN BOOLEAN DEFAULT TRUE, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN INTEGER DEFAULT DBMS_REDACT.RE_BEGINNING, + IN INTEGER DEFAULT DBMS_REDACT.RE_ALL, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL + ) +``` + +### Parameters + +`object_schema` + + Specifies the name of the schema in which the object resides and on which the data redaction policy is applied. If you specify `NULL`, then the given object is searched by the order specified by `search_path` setting. + +`object_name` + + Name of the table on which the data redaction policy is created. + +`policy_name` + + Name of the policy to add. Ensure that the `policy_name` is unique for the table on which the policy is created. + +`policy_description` + + Specify the description of a redaction policy. + +`column_name` + + Name of the column to which the redaction policy applies. To redact more than one column, use the `alter_policy` procedure to add more columns. + +`column_description` + + Description of the column to redact. The `column_description` isn't supported, but if you specify the description for a column, a warning message appears. + +`function_type` + + The type of redaction function to use. The possible values are `NONE`, `FULL`, `PARTIAL`, `RANDOM`, `REGEXP`, and `CUSTOM`. + +`function_parameters` + + Specifies the function parameters for the partition redaction and is applicable only for partial redaction. + +`expression` + + Specifies the Boolean expression for the table and determines how to apply the policy. The redaction occurs if this policy expression evaluates to `TRUE`. + +`enable` + + When set to `TRUE`, the policy is enabled upon creation. The default is `TRUE`. When set to `FALSE`, the policy is disabled, but you can enable the policy cby calling the `enable_policy` procedure. + +`regexp_pattern` + + Specifies the regular expression pattern to redact data. If the `regexp_pattern` doesn't match, then the `NULL` value is returned. + +`regexp_replace_string` + + Specifies the replacement string value. + +`regexp_position` + + Specifies the position of a character where search must begin. By default, the function parameter is `RE_BEGINNING`. + +`regexp_occurrence` + + Specifies the replacement occurrence of a substring. If the constant is `RE_ALL`, then the replacement of each matching substring occurs. If the constant is `RE_FIRST`, then the replacement of the first matching substring occurs. + +`regexp_match_parameter` + + Changes the default matching behavior of a function. The possible `regexp_match_parameter` constants can be `‘RE_CASE_SENSITIVE’`, `‘RE_CASE_INSENSITIVE’`, `‘RE_MULTIPLE_LINES’`, `‘RE_NEWLINE_WILDCARD’`, and `‘RE_IGNORE_WHITESPACE’`. + + !!!Note + For more information on `constants`, `function_parameters`, or `regexp`, see [Using DBMS_REDACT Constants and Function Parameters](#using-dbms_redact-constants-and-function-parameters). + +`custom_function_expression` + + The `custom_function_expression` applies only for the `CUSTOM` redaction type. The `custom_function_expression` is a function expression, that is, a schema-qualified function with a parameter such as `schema_name.function_name (argument1, …)` that allows a user to use their redaction logic to redact the column data. + +### Example + +This example shows how to create a policy and use full redaction for values in the `payment_details_tab` table `customer id` column. + +```sql +edb=# CREATE TABLE payment_details_tab ( +customer_id NUMBER NOT NULL, +card_string VARCHAR2(19) NOT NULL); +CREATE TABLE + +edb=# BEGIN + INSERT INTO payment_details_tab VALUES (4000, '1234-1234-1234-1234'); + INSERT INTO payment_details_tab VALUES (4001, '2345-2345-2345-2345'); +END; + +EDB-SPL Procedure successfully completed + +edb=# CREATE USER redact_user; +CREATE ROLE +edb=# GRANT SELECT ON payment_details_tab TO redact_user; +GRANT + +\c edb base_user + +BEGIN + DBMS_REDACT.add_policy( + object_schema => 'public', + object_name => 'payment_details_tab', + policy_name => 'redactPolicy_001', + policy_description => 'redactPolicy_001 for payment_details_tab table', + column_name => 'customer_id', + function_type => DBMS_REDACT.full, + expression => '1=1', + enable => TRUE); +END; +``` + +Redacted Result: + +```sql +edb=# \c edb redact_user +You are now connected to database "edb" as user "redact_user". + +edb=> select customer_id from payment_details_tab order by 1; +__OUTPUT__ + customer_id +------------- + 0 + 0 +(2 rows) +``` + +## ALTER_POLICY + +The `alter_policy` procedure alters or modifies an existing data redaction policy for a table. + +```sql +PROCEDURE alter_policy ( + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2, + IN VARCHAR2, + IN INTEGER DEFAULT DBMS_REDACT.ADD_COLUMN, + IN VARCHAR2 DEFAULT NULL, + IN INTEGER DEFAULT DBMS_REDACT.FULL, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN INTEGER DEFAULT DBMS_REDACT.RE_BEGINNING, + IN INTEGER DEFAULT DBMS_REDACT.RE_ALL, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL + ) +``` + +### Parameters + +`object_schema` + + Specifies the name of the schema in which the object resides and on which to alter the data redaction policy. If you specify `NULL`, then the given object is searched by the order specified by `search_path` setting. + +`object_name` + + Name of the table to which to alter a data redaction policy. + +`policy_name` + + Name of the policy to alter. + +`action` + + The action to perform. For more information about action parameters see, [Using DBMS_REDACT Constants and Function Parameters](#using-dbms_redact-constants-and-function-parameters) + +`column_name` + + Name of the column to which the redaction policy applies. + +`function_type` + + The type of redaction function to use. The possible values are `NONE`, `FULL`, `PARTIAL`, `RANDOM`, `REGEXP`, and `CUSTOM`. + +`function_parameters` + + Specifies the function parameters for the redaction function. + +`expression` + + Specifies the Boolean expression for the table and determines how to apply the policy. The redaction occurs if this policy expression evaluates to `TRUE`. + +`regexp_pattern` + + Enables the use of regular expressions to redact data. If the `regexp_pattern` doesn't match the data, then the `NULL` value is returned. + +`regexp_replace_string` + + Specifies the replacement string value. + +`regexp_position` + + Specifies the position of a character where search must begin. By default, the function parameter is `RE_BEGINNING`. + +`regexp_occurence` + + Specifies the replacement occurrence of a substring. If the constant is `RE_ALL`, then the replacement of each matching substring occurs. If the constant is `RE_FIRST`, then the replacement of the first matching substring occurs. + +`regexp_match_parameter` + + Changes the default matching behavior of a function. The possible `regexp_match_parameter` constants can be `‘RE_CASE_SENSITIVE’`, `‘RE_CASE_INSENSITIVE’`, `‘RE_MULTIPLE_LINES’`, `‘RE_NEWLINE_WILDCARD’`, and `‘RE_IGNORE_WHITESPACE’`. + + !!!Note + For more information on `constants`, `function_parameters`, or `regexp`, see [Using DBMS_REDACT Constants and Function Parameters](#using-dbms_redact-constants-and-function-parameters). + +`policy_description` + + Specify the description of a redaction policy. + +`column_description` + + Description of the column to redact. The `column_description` isn't supported, but if you specify the description for a column, a warning message appears. + +`custom_function_expression` + + The `custom_function_expression` applies only for the `CUSTOM` redaction type. The `custom_function_expression` is a function expression, that is, a schema-qualified function with a parameter such as `schema_name.function_name (argument1, …)` that allows a user to use their redaction logic to redact the column data. + +### Example + +This example shows how to alter a policy using partial redaction for values in the `payment_details_tab` table `card_string` (usually a credit card number) column. + +```sql +\c edb base _user + +BEGIN + DBMS_REDACT.alter_policy ( + object_schema => 'public', + object_name => 'payment_details_tab', + policy_name => 'redactPolicy_001', + action => DBMS_REDACT.ADD_COLUMN, + column_name => 'card_string', + function_type => DBMS_REDACT.partial, + function_parameters => DBMS_REDACT.REDACT_CCN16_F12); +END; +``` + +Redacted Result: + +```sql +edb=# \c - redact_user +You are now connected to database "edb" as user "redact_user". +edb=> SELECT * FROM payment_details_tab; +__OUTPUT__ + customer_id | card_string +-------------+--------------------- + 0 | ****-****-****-1234 + 0 | ****-****-****-2345 +(2 rows) +``` + +## DISABLE_POLICY + +The `disable_policy` procedure disables an existing data redaction policy. + +```sql +PROCEDURE disable_policy ( + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2, + IN VARCHAR2 + ) +``` + +### Parameters + +`object_schema` + + Specifies the name of the schema in which the object resides and on which to apply the data redaction policy. If you specify `NULL`, then the given object is searched by the order specified by `search_path` setting. + +`object_name` + + Name of the table for which to disable a data redaction policy. + +`policy_name` + + Name of the policy to disable. + +### Example + +This example shows how to disable a policy. + +```sql +\c edb base_user + +BEGIN + DBMS_REDACT.disable_policy( + object_schema => 'public', + object_name => 'payment_details_tab', + policy_name => 'redactPolicy_001'); +END; +``` + +Redacted Result: Data is no longer redacted after disabling a policy. + +## ENABLE_POLICY + +The `enable_policy` procedure enables the previously disabled data redaction policy. + +```sql +PROCEDURE enable_policy ( + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2, + IN VARCHAR2 + ) +``` + +### Parameters + +`object_schema` + + Specifies the name of the schema in which the object resides and on which to apply the data redaction policy. If you specify `NULL`, then the given object is searched by the order specified by `search_path` setting. + +`object_name` + + Name of the table to which to enable a data redaction policy. + +`policy_name` + + Name of the policy to enable. + +### Example + +This example shows how to enable a policy. + +```sql +\c edb base_user + +BEGIN + DBMS_REDACT.enable_policy( + object_schema => 'public', + object_name => 'payment_details_tab', + policy_name => 'redactPolicy_001'); +END; +``` + +Redacted Result: Data is redacted after enabling a policy. + +## DROP_POLICY + +The `drop_policy` procedure drops a data redaction policy by removing the masking policy from a table. + +```sql +PROCEDURE drop_policy ( + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2, + IN VARCHAR2 + ) +``` + +### Parameters + +`object_schema` + + Specifies the name of the schema in which the object resides and on which to apply the data redaction policy. If you specify `NULL`, then the given object is searched by the order specified by `search_path` setting. + +`object_name` + + Name of the table from which to drop a data redaction policy. + +`policy_name` + + Name of the policy to drop. + +### Example + +This example shows how to drop a policy. + +```sql +\c edb base_user + +BEGIN + DBMS_REDACT.drop_policy( + object_schema => 'public', + object_name => 'payment_details_tab', + policy_name => 'redactPolicy_001'); +END; +``` + +Redacted Result: The server drops the specified policy. + +## UPDATE_FULL_REDACTION_VALUES + +The `update_full_redaction_values` procedure updates the default displayed values for a data redaction policy. You can view these default values using the `redaction_values_for_type_full` view that uses the full redaction type. + +```sql +PROCEDURE update_full_redaction_values ( + IN NUMBER DEFAULT NULL, + IN FLOAT4 DEFAULT NULL, + IN FLOAT8 DEFAULT NULL, + IN CHAR DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN NCHAR DEFAULT NULL, + IN NVARCHAR2 DEFAULT NULL, + IN DATE DEFAULT NULL, + IN TIMESTAMP DEFAULT NULL, + IN TIMESTAMPTZ DEFAULT NULL, + IN BLOB DEFAULT NULL, + IN CLOB DEFAULT NULL, + IN CLOB DEFAULT NULL + ) +``` + +### Parameters + +`number_val` + + Updates the default value for columns of the `NUMBER` datatype. + +`binfloat_val` + + The `FLOAT4` datatype is a random value. The binary float datatype isn't supported. + +`bindouble_val` + + The `FLOAT8` datatype is a random value. The binary double datatype isn;t supported. + +`char_val` + + Updates the default value for columns of the `CHAR` datatype. + +`varchar_val` + + Updates the default value for columns of the `VARCHAR2` datatype. + +`nchar_val` + + The `nchar_val` is mapped to `CHAR` datatype and returns the `CHAR` value. + +`nvarchar_val` + + The `nvarchar_val` is mapped to `VARCHAR2` datatype and returns the `VARCHAR` value. + +`datecol_val` + + Updates the default value for columns of the `DATE` datatype. + +`ts_val` + + Updates the default value for columns of the `TIMESTAMP` datatype. + +`tswtz_val` + + Updates the default value for columns of the `TIMESTAMPTZ` datatype. + +`blob_val` + + Updates the default value for columns of the `BLOB` datatype. + +`clob_val` + + Updates the default value for columns of the `CLOB` datatype. + +`nclob_val` + + The `nclob_val` is mapped to `CLOB` datatype and returns the `CLOB` value. + +### Example + +This example shows how to update the full redaction values. Before updating the values, you can view the default values using the `redaction_values_for_type_full` view. + +```sql +edb=# \x +Expanded display is on. +edb=# SELECT number_value, char_value, varchar_value, date_value, + timestamp_value, timestamp_with_time_zone_value, blob_value, +clob_value +FROM redaction_values_for_type_full; +__OUTPUT__ +-[ RECORD 1 ]------------------+-------------------------- +number_value | 0 +char_value | +varchar_value | +date_value | 01-JAN-01 00:00:00 +timestamp_value | 01-JAN-01 01:00:00 +timestamp_with_time_zone_value | 31-DEC-00 20:00:00 -05:00 +blob_value | \x5b72656461637465645d +clob_value | [redacted] +(1 row) +``` + +Update the default values for full redaction type. The `NULL` values are ignored. + +```sql +\c edb base_user + +edb=# BEGIN + DBMS_REDACT.update_full_redaction_values ( + number_val => 9999999, + char_val => 'Z', + varchar_val => 'V', + datecol_val => to_date('17/10/2018', 'DD/MM/YYYY'), + ts_val => to_timestamp('17/10/2018 11:12:13', 'DD/MM/YYYY HH24:MI:SS'), + tswtz_val => NULL, + blob_val => 'NEW REDACTED VALUE', + clob_val => 'NEW REDACTED VALUE'); +END; +``` + +You can now see the updated values using the `redaction_values_for_type_full` view. + +```sql +EDB-SPL Procedure successfully completed +edb=# SELECT number_value, char_value, varchar_value, date_value, + timestamp_value, timestamp_with_time_zone_value, blob_value, +clob_value +FROM redaction_values_for_type_full; +__OUTPUT__ +-[ RECORD 1 ]------------------+--------------------------------------- +number_value | 9999999 +char_value | Z +varchar_value | V +date_value | 17-OCT-18 00:00:00 +timestamp_value | 17-OCT-18 11:12:13 +timestamp_with_time_zone_value | 31-DEC-00 20:00:00 -05:00 +blob_value | \x4e45572052454441435445442056414c5545 +clob_value | NEW REDACTED VALUE +(1 row) +``` + +Redacted Result: + +```sql +edb=# \c edb redact_user +You are now connected to database "edb" as user "redact_user". + +edb=> select * from payment_details_tab order by 1; +__OUTPUT__ + customer_id | card_string +-------------+------------- + 9999999 | V + 9999999 | V +(2 rows) +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/14_dbms_rls.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/14_dbms_rls.mdx new file mode 100644 index 00000000000..d89c00bb896 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/14_dbms_rls.mdx @@ -0,0 +1,507 @@ +--- +title: "DBMS_RLS" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.27.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.200.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.158.html" +--- + +The `DBMS_RLS` package enables you to implement Virtual Private Database on certain EDB Postgres Advanced Server database objects. + +EDB Postgres Advanced Server's implementation of `DBMS_RLS` is a partial implementation when compared to Oracle's version. Only those functions and procedures listed in the table are supported. + +| Function/procedure | Function or procedure | Return type | Description | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------- | ------------------------------------------------ | +| `ADD_POLICY(object_schema, object_name, policy_name, function_schema, policy_function [, statement_types [, update_check [, enable [, static_policy [, policy_type [, long_predicate [, sec_relevant_cols [, sec_relevant_cols_opt ]]]]]]]])` | Procedure | n/a | Add a security policy to a database object. | +| `DROP_POLICY(object_schema, object_name, policy_name)` | Procedure | n/a | Remove a security policy from a database object. | +| `ENABLE_POLICY(object_schema, object_name, policy_name, enable)` | Procedure | n/a | Enable or disable a security policy. | + +*Virtual Private Database* is a type of fine-grained access control using security policies. *Fine-grained access control* in Virtual Private Database means that you can control access to data down to specific rows as defined by the security policy. + +The rules that encode a security policy are defined in a *policy function*, which is an SPL function with certain input parameters and return values. The *security policy* is the named association of the policy function to a particular database object, typically a table. + +!!! Note + In EDB Postgres Advanced Server, you can write the policy function in any language supported by EDB Postgres Advanced Server, such as SQL, PL/pgSQL, and SPL. + +!!! Note + The database objects currently supported by EDB Postgres Advanced Server Virtual Private Database are tables. You can't apply policies to views or synonyms. + +Virtual Private Database has these advantages: + +- It provides a fine-grained level of security. Database object-level privileges given by the `GRANT` command determine access privileges to the entire instance of a database object, while Virtual Private Database provides access control for the individual rows of a database object instance. +- You can apply a different security policy depending on the type of SQL command (`INSERT`, `UPDATE`, `DELETE`, or `SELECT`). +- The security policy can vary dynamically for each applicable SQL command affecting the database object, depending on factors such as the session user of the application accessing the database object. +- Invoking the security policy is transparent to all applications that access the database object. Thus, you don't have to modify individual applications to apply the security policy. +- Once a security policy is enabled, applications (including new applications) can't circumvent the security policy except by the system privilege described in the note that follows. +- Even superusers can't circumvent the security policy except by the system privilege described in the note that follows. + +!!! Note + The only way to circumvent security policies is if the `EXEMPT ACCESS POLICY` system privilege is granted to a user. Grant the `EXEMPT ACCESS POLICY` privilege with extreme care as a user with this privilege is exempted from all policies in the database. + +The `DBMS_RLS` package provides procedures to create policies, remove policies, enable policies, and disable policies. + +The process for implementing Virtual Private Database is as follows: + +1. Create a policy function. The function must have two input parameters of type `VARCHAR2`. The first input parameter is for the schema containing the database object to which the policy applies. The second input parameter is for the name of that database object. The function must have a `VARCHAR2` return type and return a string in the form of a `WHERE` clause predicate. This predicate is dynamically appended as an `AND` condition to the SQL command that acts on the database object. Thus, rows that don't satisfy the policy function predicate are filtered out from the SQL command result set. +1. Use the `ADD_POLICY` procedure to define a new policy, which is the association of a policy function with a database object. With the `ADD_POLICY` procedure, you can also specify: + - The types of SQL commands (`INSERT`, `UPDATE`, `DELETE`, or `SELECT`) to which the policy applies + - Whether to enable the policy at the time of its creation + - Whether the policy applies to newly inserted rows or the modified image of updated rows +1. Use the `ENABLE_POLICY` procedure to disable or enable an existing policy. +1. Use the `DROP_POLICY` procedure to remove an existing policy. The `DROP_POLICY` procedure doesn't drop the policy function or the associated database object. + +Once you create policies, you can view them in the catalog views compatible with Oracle databases: `ALL_POLICIES`, `DBA_POLICIES`, or `USER_POLICIES`. The supported compatible views are listed in [Database Compatibility for Oracle Developers Catalog Views](/epas/latest/epas_compat_cat_views/). + +The `SYS_CONTEXT` function is often used with `DBMS_RLS`. The signature is: + +```sql +SYS_CONTEXT(, ) +``` + +Where: + + `namespace` is a `VARCHAR2`. The only accepted value is `USERENV`. Any other value returns `NULL`. + + `attribute` is a `VARCHAR2`. Possible values are: + +| attribute Value | Equivalent value | +| ---------------- | ----------------------------- | +| `SESSION_USER` | `pg_catalog.session_user` | +| `CURRENT_USER` | `pg_catalog.current_user` | +| `CURRENT_SCHEMA` | `pg_catalog.current_schema` | +| `HOST` | `pg_catalog.inet_host` | +| `IP_ADDRESS` | `pg_catalog.inet_client_addr` | +| `SERVER_HOST` | `pg_catalog.inet_server_addr` | + + +The examples used to illustrate the `DBMS_RLS` package are based on a modified copy of the sample `emp` table provided with EDB Postgres Advanced Server along with a role named `salesmgr` that is granted all privileges on the table. You can create the modified copy of the `emp` table named `vpemp` and the `salesmgr` role as follows: + +```sql +CREATE TABLE public.vpemp AS SELECT empno, ename, job, sal, comm, deptno +FROM emp; +ALTER TABLE vpemp ADD authid VARCHAR2(12); +UPDATE vpemp SET authid = 'researchmgr' WHERE deptno = 20; +UPDATE vpemp SET authid = 'salesmgr' WHERE deptno = 30; +SELECT * FROM vpemp; +__OUTPUT__ +empno | ename | job | sal | comm | deptno | authid +-------+--------+-----------+---------+---------+--------+------------- + 7782 | CLARK | MANAGER | 2450.00 | | 10 | + 7839 | KING | PRESIDENT | 5000.00 | | 10 | + 7934 | MILLER | CLERK | 1300.00 | | 10 | + 7369 | SMITH | CLERK | 800.00 | | 20 | researchmgr + 7566 | JONES | MANAGER | 2975.00 | | 20 | researchmgr + 7788 | SCOTT | ANALYST | 3000.00 | | 20 | researchmgr + 7876 | ADAMS | CLERK | 1100.00 | | 20 | researchmgr + 7902 | FORD | ANALYST | 3000.00 | | 20 | researchmgr + 7499 | ALLEN | SALESMAN | 1600.00 | 300.00 | 30 | salesmgr + 7521 | WARD | SALESMAN | 1250.00 | 500.00 | 30 | salesmgr + 7654 | MARTIN | SALESMAN | 1250.00 | 1400.00 | 30 | salesmgr + 7698 | BLAKE | MANAGER | 2850.00 | | 30 | salesmgr + 7844 | TURNER | SALESMAN | 1500.00 | 0.00 | 30 | salesmgr + 7900 | JAMES | CLERK | 950.00 | | 30 | salesmgr +(14 rows) + +CREATE ROLE salesmgr WITH LOGIN PASSWORD 'password'; +GRANT ALL ON vpemp TO salesmgr; +``` + +## ADD_POLICY + +The `ADD_POLICY` procedure creates a new policy by associating a policy function with a database object. + +You must be a superuser to execute this procedure. + +```sql +ADD_POLICY( VARCHAR2, VARCHAR2, + VARCHAR2, VARCHAR2, + VARCHAR2 + [, VARCHAR2 + [, BOOLEAN + [, BOOLEAN + [, BOOLEAN + [, INTEGER + [, BOOLEAN + [, VARCHAR2 + [, INTEGER ]]]]]]]]) +``` + +### Parameters + +`object_schema` + + Name of the schema containing the database object to which to apply the policy. + +`object_name` + + Name of the database object to which to apply the policy. A given database object can have more than one policy applied to it. + +`policy_name` + + Name assigned to the policy. The combination of database object (identified by `object_schema` and `object_name`) and policy name must be unique in the database. + +`function_schema` + + Name of the schema containing the policy function. + + !!! Note + The policy function might belong to a package. In this case `function_schema` must contain the name of the schema in which the package is defined. + +`policy_function` + + Name of the SPL function that defines the rules of the security policy. You can specify the same function in more than one policy. + + !!! Note + The policy function might belong to a package. In this case `policy_function` must also contain the package name in dot notation (that is, `package_name.function_name`). + +`statement_types` + + Comma-separated list of SQL commands to which the policy applies. Valid SQL commands are `INSERT`, `UPDATE`, `DELETE`, and `SELECT`. The default is `INSERT,UPDATE,DELETE,SELECT`. + + !!! Note + EDB Postgres Advanced Server accepts `INDEX` as a statement type but it is ignored. Policies aren't applied to index operations in EDB Postgres Advanced Server. + +`update_check` + + Applies to `INSERT` and `UPDATE` SQL commands only. + +- When set to `TRUE`, the policy is applied to newly inserted rows and to the modified image of updated rows. If any of the new or modified rows don't qualify according to the policy function predicate, then the `INSERT` or `UPDATE` command throws an exception and no rows are inserted or modified by the `INSERT` or `UPDATE` command. +- When set to `FALSE`, the policy isn't applied to newly inserted rows or the modified image of updated rows. Thus, a newly inserted row might not appear in the result set of a subsequent SQL command that invokes the same policy. Similarly, rows that qualified according to the policy prior to an `UPDATE` command might not appear in the result set of a subsequent SQL command that invokes the same policy. +- The default is `FALSE`. + +`enable` + + When set to `TRUE`, the policy is enabled and applied to the SQL commands given by the `statement_types` parameter. When set to `FALSE` the policy is disabled and not applied to any SQL commands. You can enable the policy using the `ENABLE_POLICY` procedure. The default is `TRUE`. + +`static_policy` + + In Oracle, when set to `TRUE`, the policy is *static*, which means the policy function is evaluated once per database object the first time it's invoked by a policy on that database object. The resulting policy function predicate string is saved in memory and reused for all invocations of that policy on that database object while the database server instance is running. + +- When set to `FALSE`, the policy is *dynamic*, which means the policy function is reevaluated and the policy function predicate string regenerated for all invocations of the policy. +- The default is `FALSE`. + + !!! Note + In Oracle 10g, the `policy_type` parameter was introduced, which is intended to replace the `static_policy` parameter. In Oracle, if the `policy_type` parameter isn't set to its default value of `NULL`, the `policy_type` parameter setting overrides the `static_policy` setting. + + !!! Note + The setting of `static_policy` is ignored by EDB Postgres Advanced Server. EDB Postgres Advanced Server implements only the dynamic policy, regardless of the setting of the `static_policy` parameter. + +`policy_type` + + In Oracle, determines when the policy function is reevaluated and, hence, if and when the predicate string returned by the policy function changes. The default is `NULL`. + + !!! Note + This parameter setting is ignored by EDB Postgres Advanced Server. EDB Postgres Advanced Server always assumes a dynamic policy. + +`long_predicate` + + In Oracle, allows predicates up to 32K bytes if set to `TRUE`. Otherwise predicates are limited to 4000 bytes. The default is `FALSE`. + + !!! Note + This parameter setting is ignored by EDB Postgres Advanced Server. An EDB Postgres Advanced Server policy function can return a predicate of unlimited length for all practical purposes. + +`sec_relevant_cols` + + Comma-separated list of columns of `object_name`. Provides *column-level Virtual Private Database* for the listed columns. The policy is enforced if any of the listed columns are referenced in a SQL command of a type listed in `statement_types`. The policy isn't enforced if no such columns are referenced. + + The default is `NULL`, which has the same effect as if all of the database object’s columns were included in `sec_relevant_cols`. + +`sec_relevant_cols_opt` + + In Oracle, if `sec_relevant_cols_opt` is set to `DBMS_RLS.ALL_ROWS` (`INTEGER` constant of value 1), then the columns listed in `sec_relevant_cols` return `NULL` on all rows where the applied policy predicate is false. (If `sec_relevant_cols_opt` isn't set to `DBMS_RLS.ALL_ROWS`, these rows aren't returned at all in the result set.) The default is `NULL`. + + !!! Note + EDB Postgres Advanced Server doesn't support `DBMS_RLS.ALL_ROWS`. EDB Postgres Advanced Server throws an error if `sec_relevant_cols_opt` is set to `DBMS_RLS.ALL_ROWS` (`INTEGER` value of 1). + +### Examples + +This example uses the following policy function: + +```sql +CREATE OR REPLACE FUNCTION verify_session_user ( + p_schema VARCHAR2, + p_object VARCHAR2 +) +RETURN VARCHAR2 +IS +BEGIN + RETURN 'authid = SYS_CONTEXT(''USERENV'', ''SESSION_USER'')'; +END; +``` + +This function generates the predicate `authid = SYS_CONTEXT('USERENV', 'SESSION_USER')`, which is added to the `WHERE` clause of any SQL command of the type specified in the `ADD_POLICY` procedure. + +This limits the effect of the SQL command to those rows where the content of the `authid` column is the same as the session user. + +!!! Note + This example uses the `SYS_CONTEXT` function to return the login user name. In Oracle the `SYS_CONTEXT` function is used to return attributes of an *application context*. The first parameter of the `SYS_CONTEXT` function is the name of an application context. The second parameter is the name of an attribute set in the application context. `USERENV` is a special built-in namespace that describes the current session. EDB Postgres Advanced Server doesn't support application contexts. It supports only this specific usage of the `SYS_CONTEXT` function. + +The following anonymous block calls the `ADD_POLICY` procedure to create a policy named `secure_update`. The policy applies to the `vpemp` table using the function `verify_session_user` whenever an `INSERT`, `UPDATE`, or `DELETE` SQL command is given referencing the `vpemp` table. + +```sql +DECLARE + v_object_schema VARCHAR2(30) := 'public'; + v_object_name VARCHAR2(30) := 'vpemp'; + v_policy_name VARCHAR2(30) := 'secure_update'; + v_function_schema VARCHAR2(30) := 'enterprisedb'; + v_policy_function VARCHAR2(30) := 'verify_session_user'; + v_statement_types VARCHAR2(30) := 'INSERT,UPDATE,DELETE'; + v_update_check BOOLEAN := TRUE; + v_enable BOOLEAN := TRUE; +BEGIN + DBMS_RLS.ADD_POLICY( + v_object_schema, + v_object_name, + v_policy_name, + v_function_schema, + v_policy_function, + v_statement_types, + v_update_check, + v_enable + ); +END; +``` + +After successfully creating the policy, a terminal session is started by user `salesmgr`. The following query shows the content of the `vpemp` table: + +```sql +edb=# \c edb salesmgr +Password for user salesmgr: +You are now connected to database "edb" as user "salesmgr". +edb=> SELECT * FROM vpemp; +__OUTPUT__ + empno | ename | job | sal | comm | deptno | authid +-------+--------+-----------+---------+---------+--------+------------- + 7782 | CLARK | MANAGER | 2450.00 | | 10 | + 7839 | KING | PRESIDENT | 5000.00 | | 10 | + 7934 | MILLER | CLERK | 1300.00 | | 10 | + 7369 | SMITH | CLERK | 800.00 | | 20 | researchmgr + 7566 | JONES | MANAGER | 2975.00 | | 20 | researchmgr + 7788 | SCOTT | ANALYST | 3000.00 | | 20 | researchmgr + 7876 | ADAMS | CLERK | 1100.00 | | 20 | researchmgr + 7902 | FORD | ANALYST | 3000.00 | | 20 | researchmgr + 7499 | ALLEN | SALESMAN | 1600.00 | 300.00 | 30 | salesmgr + 7521 | WARD | SALESMAN | 1250.00 | 500.00 | 30 | salesmgr + 7654 | MARTIN | SALESMAN | 1250.00 | 1400.00 | 30 | salesmgr + 7698 | BLAKE | MANAGER | 2850.00 | | 30 | salesmgr + 7844 | TURNER | SALESMAN | 1500.00 | 0.00 | 30 | salesmgr + 7900 | JAMES | CLERK | 950.00 | | 30 | salesmgr +(14 rows) +``` + +An unqualified `UPDATE` command (no `WHERE` clause) is issued by the `salesmgr` user: + +```sql +edb=> UPDATE vpemp SET comm = sal * .75; +UPDATE 6 +``` + +Instead of updating all rows in the table, the policy restricts the effect of the update to only those rows where the `authid` column contains the value `salesmgr` as specified by the policy function predicate `authid = SYS_CONTEXT('USERENV', 'SESSION_USER')`. + +The following query shows that the `comm` column was changed only for those rows where `authid` contains `salesmgr`. All other rows are unchanged. + +```sql +edb=> SELECT * FROM vpemp; +__OUTPUT__ + empno | ename | job | sal | comm | deptno | authid +-------+--------+-----------+---------+---------+--------+------------- + 7782 | CLARK | MANAGER | 2450.00 | | 10 | + 7839 | KING | PRESIDENT | 5000.00 | | 10 | + 7934 | MILLER | CLERK | 1300.00 | | 10 | + 7369 | SMITH | CLERK | 800.00 | | 20 | researchmgr + 7566 | JONES | MANAGER | 2975.00 | | 20 | researchmgr + 7788 | SCOTT | ANALYST | 3000.00 | | 20 | researchmgr + 7876 | ADAMS | CLERK | 1100.00 | | 20 | researchmgr + 7902 | FORD | ANALYST | 3000.00 | | 20 | researchmgr + 7499 | ALLEN | SALESMAN | 1600.00 | 1200.00 | 30 | salesmgr + 7521 | WARD | SALESMAN | 1250.00 | 937.50 | 30 | salesmgr + 7654 | MARTIN | SALESMAN | 1250.00 | 937.50 | 30 | salesmgr + 7698 | BLAKE | MANAGER | 2850.00 | 2137.50 | 30 | salesmgr + 7844 | TURNER | SALESMAN | 1500.00 | 1125.00 | 30 | salesmgr + 7900 | JAMES | CLERK | 950.00 | 712.50 | 30 | salesmgr +(14 rows) +``` + +Furthermore, since the `update_check` parameter was set to `TRUE` in the `ADD_POLICY` procedure, the following `INSERT` command throws an exception. The value given for the `authid` column, `researchmgr`, doesn't match the session user (`salesmgr`) and hence fails the policy. + +```sql +edb=> INSERT INTO vpemp VALUES (9001,'SMITH','ANALYST',3200.00,NULL,20, +'researchmgr'); +ERROR: policy with check option violation +DETAIL: Policy predicate was evaluated to FALSE with the updated values +``` + +If `update_check` is set to `FALSE`, the preceding `INSERT` command succeeds. + +This example uses the `sec_relevant_cols` parameter to apply a policy only when certain columns are referenced in the SQL command. The following policy function is used for this example, which selects rows where the employee salary is less than `2000`. + +```sql +CREATE OR REPLACE FUNCTION sal_lt_2000 ( + p_schema VARCHAR2, + p_object VARCHAR2 +) +RETURN VARCHAR2 +IS +BEGIN + RETURN 'sal < 2000'; +END +``` + +The policy is created so that it's enforced only if a `SELECT` command includes columns `sal` or `comm`: + +```sql +DECLARE + v_object_schema VARCHAR2(30) := 'public'; + v_object_name VARCHAR2(30) := 'vpemp'; + v_policy_name VARCHAR2(30) := 'secure_salary'; + v_function_schema VARCHAR2(30) := 'enterprisedb'; + v_policy_function VARCHAR2(30) := 'sal_lt_2000'; + v_statement_types VARCHAR2(30) := 'SELECT'; + v_sec_relevant_cols VARCHAR2(30) := 'sal,comm'; +BEGIN + DBMS_RLS.ADD_POLICY( + v_object_schema, + v_object_name, + v_policy_name, + v_function_schema, + v_policy_function, + v_statement_types, + sec_relevant_cols => v_sec_relevant_cols + ); +END; +``` + +If a query doesn't reference columns `sal` or `comm`, then the policy isn't applied. The following query returns all 14 rows of table `vpemp`: + +```sql +edb=# SELECT empno, ename, job, deptno, authid FROM vpemp; +__OUTPUT__ + empno | ename | job | deptno | authid +-------+--------+-----------+--------+------------- + 7782 | CLARK | MANAGER | 10 | + 7839 | KING | PRESIDENT | 10 | + 7934 | MILLER | CLERK | 10 | + 7369 | SMITH | CLERK | 20 | researchmgr + 7566 | JONES | MANAGER | 20 | researchmgr + 7788 | SCOTT | ANALYST | 20 | researchmgr + 7876 | ADAMS | CLERK | 20 | researchmgr + 7902 | FORD | ANALYST | 20 | researchmgr + 7499 | ALLEN | SALESMAN | 30 | salesmgr + 7521 | WARD | SALESMAN | 30 | salesmgr + 7654 | MARTIN | SALESMAN | 30 | salesmgr + 7698 | BLAKE | MANAGER | 30 | salesmgr + 7844 | TURNER | SALESMAN | 30 | salesmgr + 7900 | JAMES | CLERK | 30 | salesmgr +(14 rows) +``` + +If the query references the `sal` or `comm` columns, then the policy is applied to the query, eliminating any rows where `sal` is greater than or equal to `2000`: + +```sql +edb=# SELECT empno, ename, job, sal, comm, deptno, authid FROM vpemp; +__OUTPUT__ + empno | ename | job | sal | comm | deptno | authid +-------+--------+----------+---------+---------+--------+------------- + 7934 | MILLER | CLERK | 1300.00 | | 10 | + 7369 | SMITH | CLERK | 800.00 | | 20 | researchmgr + 7876 | ADAMS | CLERK | 1100.00 | | 20 | researchmgr + 7499 | ALLEN | SALESMAN | 1600.00 | 1200.00 | 30 | salesmgr + 7521 | WARD | SALESMAN | 1250.00 | 937.50 | 30 | salesmgr + 7654 | MARTIN | SALESMAN | 1250.00 | 937.50 | 30 | salesmgr + 7844 | TURNER | SALESMAN | 1500.00 | 1125.00 | 30 | salesmgr + 7900 | JAMES | CLERK | 950.00 | 712.50 | 30 | salesmgr +(8 rows) +``` + +## DROP_POLICY + +The `DROP_POLICY` procedure deletes an existing policy. The `DROP_POLICY` procedure doesn't delete the policy function and database object associated with the policy. + +You must be a superuser to execute this procedure. + +```sql +DROP_POLICY( VARCHAR2, VARCHAR2, + VARCHAR2) +``` + +### Parameters + +`object_schema` + + Name of the schema containing the database object to which the policy applies. + +`object_name` + + Name of the database object to which the policy applies. + +`policy_name` + + Name of the policy to delete. + +### Examples + +This example deletes policy `secure_update` on table `public.vpemp`: + +```sql +DECLARE + v_object_schema VARCHAR2(30) := 'public'; + v_object_name VARCHAR2(30) := 'vpemp'; + v_policy_name VARCHAR2(30) := 'secure_update'; +BEGIN + DBMS_RLS.DROP_POLICY( + v_object_schema, + v_object_name, + v_policy_name + ); +END; +``` + +## ENABLE_POLICY + +The `ENABLE_POLICY` procedure enables or disables an existing policy on the specified database object. + +You must be a superuser to execute this procedure. + +```sql +ENABLE_POLICY( VARCHAR2, VARCHAR2, + VARCHAR2, BOOLEAN) +``` + +### Parameters + +`object_schema` + + Name of the schema containing the database object to which the policy applies. + +`object_name` + + Name of the database object to which the policy applies. + +`policy_name` + + Name of the policy to enable or disable. + +`enable` + + When set to `TRUE`, the policy is enabled. When set to `FALSE`, the policy is disabled. + +### Examples + +This example disables policy `secure_update` on table `public.vpemp`: + +```sql +DECLARE + v_object_schema VARCHAR2(30) := 'public'; + v_object_name VARCHAR2(30) := 'vpemp'; + v_policy_name VARCHAR2(30) := 'secure_update'; + v_enable BOOLEAN := FALSE; +BEGIN + DBMS_RLS.ENABLE_POLICY( + v_object_schema, + v_object_name, + v_policy_name, + v_enable + ); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/01_using_calendar_syntax_to_specify_a_repeating_interval.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/01_using_calendar_syntax_to_specify_a_repeating_interval.mdx new file mode 100644 index 00000000000..9340a6fc75b --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/01_using_calendar_syntax_to_specify_a_repeating_interval.mdx @@ -0,0 +1,32 @@ +--- +title: "Using calendar syntax to specify a repeating interval" +--- + +The `CREATE_JOB` and `CREATE_SCHEDULE` procedures use Oracle-style calendar syntax to define the interval with which a job or schedule is repeated. Provide the scheduling information in the `repeat_interval` parameter of each procedure. + +`repeat_interval` is a value or series of values that define the interval between the executions of the scheduled job. Each value is composed of a token, an equals sign, and the units on which the schedule executes. Separate multiple token values with a semi-colon (;). + +For example, the following value defines a schedule that's executed each weeknight at 5:45: + + `FREQ=DAILY;BYDAY=MON,TUE,WED,THU,FRI;BYHOUR=17;BYMINUTE=45` + +EDB Postgres Advanced Server supports the token types and syntax described in the table. + +| Token type | Syntax | Valid values | +| ------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `FREQ` | `FREQ=predefined_interval` | Where `predefined_interval` is one of the following: `YEARLY`, `MONTHLY`, `WEEKLY`, `DAILY`, `HOURLY`, `MINUTELY`. The `SECONDLY` keyword isn't supported. | +| `BYMONTH` | `BYMONTH=month(, month)...` | Where `month` is the three-letter abbreviation of the month name: `JAN`, `FEB`, `MAR`, `APR`, `MAY`, `JUN`, `JUL`, `AUG`, `SEP`, `OCT`, `NOV`, `DEC` | +| `BYMONTH` | `BYMONTH=month (, month)...` | Where `month` is the numeric value representing the month: `1` \| `2` \| `3` \| `4` \| `5` \| `6` \| `7` \| `8` \| `9` \| `10` \| `11` \| `12` | +| `BYMONTHDAY` | `BYMONTHDAY=day_of_month` | Where `day_of_month` is a value from `1` through `31` | +| `BYDAY` | `BYDAY=weekday` | Where `weekday` is a three-letter abbreviation or single-digit value representing the day of the week. | +| | | `Monday` \| `MON` \| `1` \| | +| | | `Tuesday` \| `TUE` \| `2` \| | +| | | `Wednesday` \| `WED` \| `3` \| | +| | | `Thursday` \| `THU` \| `4` \| | +| | | `Friday` \| `FRI` \| `5` \| | +| | | `Saturday` \| `SAT` \| `6` \| | +| | | `Sunday` \| `SUN` \| `7` \| | +| `BYDATE` | `BYDATE=date(, date)...` | Where date is `YYYYMMDD`.

`YYYY` is a four-digit year representation of the year,
`MM` is a two-digit representation of the month,
and `DD` is a two-digit day representation of the day. | +| `BYDATE` | `BYDATE=date(, date)...` | Where date is `MMDD`.

`MM` is a two-digit representation of the month,
and `DD` is a two-digit day representation of the day | +| `BYHOUR` | `BYHOUR=hour` | Where `hour` is a value from `0` through `23`. | +| `BYMINUTE` | `BYMINUTE=minute` | Where `minute` is a value from `0` through `59`. | diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/02_create_job.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/02_create_job.mdx new file mode 100644 index 00000000000..a0f804d815f --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/02_create_job.mdx @@ -0,0 +1,111 @@ +--- +title: "CREATE_JOB" +--- + +Use the `CREATE_JOB` procedure to create a job. The procedure comes in two forms. The first form of the procedure specifies a schedule in the job definition as well as a job action to invoke when the job executes: + +```sql +CREATE_JOB( + IN VARCHAR2, + IN VARCHAR2, + IN VARCHAR2, + IN PLS_INTEGER DEFAULT 0, + IN TIMESTAMP WITH TIME ZONE DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL, + IN TIMESTAMP WITH TIME ZONE DEFAULT NULL, + IN VARCHAR2 DEFAULT 'DEFAULT_JOB_CLASS', + IN BOOLEAN DEFAULT FALSE, + IN BOOLEAN DEFAULT TRUE, + IN VARCHAR2 DEFAULT NULL) +``` + +The second form uses a job schedule to specify the schedule on which the job executes and specifies the name of a program to execute when the job runs: + +```sql +CREATE_JOB( + IN VARCHAR2, + IN VARCHAR2, + IN VARCHAR2, + IN VARCHAR2 DEFAULT 'DEFAULT_JOB_CLASS', + IN BOOLEAN DEFAULT FALSE, + IN BOOLEAN DEFAULT TRUE, + IN VARCHAR2 DEFAULT NULL) +``` + +## Parameters + +`job_name` + + `job_name` specifies the optionally schema-qualified name of the job being created. + +`job_type` + + `job_type` specifies the type of job. The current implementation of `CREATE_JOB` supports a job type of `PLSQL_BLOCK` or `STORED_PROCEDURE`. + +`job_action` + +- If `job_type` is `PLSQL_BLOCK`, `job_action` specifies the content of the PL/SQL block to invoke when the job executes. The block must be terminated with a semi-colon (;). + +- If `job_type` is `STORED_PROCEDURE`, `job_action` specifies the optionally schema-qualified name of the procedure. + +`number_of_arguments` + + `number_of_arguments` is an integer value that specifies the number of arguments expected by the job. The default is `0`. + +`start_date` + + `start_date` is a `TIMESTAMP WITH TIME ZONE` value that specifies the first time that the job is scheduled to execute. The default value is `NULL`, indicating to schedule the job to execute when the job is enabled. + +`repeat_interval` + + `repeat_interval` is a `VARCHAR2` value that specifies how often the job repeats. If you don't specify a `repeat_interval`, the job executes only once. The default value is `NULL`. + +`end_date` + + `end_date` is a `TIMESTAMP WITH TIME ZONE` value that specifies a time after which the job no longer executes. If you specify a date, the `end_date` must be after `start_date`. The default value is `NULL`. + + If you don't specify an `end_date` and you do specify a `repeat_interval`, the job repeats indefinitely until you disable it. + +`program_name` + + `program_name` is the name of a program for the job to execute. + +`schedule_name` + + `schedule_name` is the name of the schedule associated with the job. + +`job_class` + + `job_class` is accepted for compatibility and ignored. + +`enabled` + + `enabled` is a Boolean value that specifies if the job is enabled when created. By default, a job is created in a disabled state, with `enabled` set to `FALSE`. To enable a job, specify a value of `TRUE` when creating the job, or enable the job with the `DBMS_SCHEDULER.ENABLE` procedure. + +`auto_drop` + + The `auto_drop` parameter is accepted for compatibility and is ignored. By default, a job's status is changed to `DISABLED` after the time specified in `end_date`. + +`comments` + + Use the `comments` parameter to specify a comment about the job. + +## Example + +This example shows a call to the `CREATE_JOB` procedure: + +```sql +EXEC + DBMS_SCHEDULER.CREATE_JOB ( + job_name => 'update_log', + job_type => 'PLSQL_BLOCK', + job_action => 'BEGIN INSERT INTO my_log VALUES(current_timestamp); + END;', + start_date => '01-JUN-15 09:00:00.000000', + repeat_interval => 'FREQ=DAILY;BYDAY=MON,TUE,WED,THU,FRI;BYHOUR=17;', + end_date => NULL, + enabled => TRUE, + comments => 'This job adds a row to the my_log table.'); +``` + +The code fragment creates a job named `update_log` that executes each weeknight at 5:00. The job executes a PL/SQL block that inserts the current timestamp into a logfile (`my_log`). Since no `end_date` is specified, the job executes until disabled by the `DBMS_SCHEDULER.DISABLE` procedure. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/03_create_program.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/03_create_program.mdx new file mode 100644 index 00000000000..b42cfd6ebc4 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/03_create_program.mdx @@ -0,0 +1,67 @@ +--- +title: "CREATE_PROGRAM" +--- + +Use the `CREATE_PROGRAM` procedure to create a `DBMS_SCHEDULER` program. The signature is: + +```sql +CREATE_PROGRAM( + IN VARCHAR2, + IN VARCHAR2, + IN VARCHAR2, + IN PLS_INTEGER DEFAULT 0, + IN BOOLEAN DEFAULT FALSE, + IN VARCHAR2 DEFAULT NULL) +``` + +## Parameters + +`program_name` + + `program_name` specifies the name of the program that's being created. + +`program_type` + + `program_type` specifies the type of program. The current implementation of `CREATE_PROGRAM` supports a `program_type` of `PLSQL_BLOCK` or `PROCEDURE`. + +`program_action` + +- If `program_type` is `PLSQL_BLOCK, program_action` contains the PL/SQL block that executes when the program is invoked. The PL/SQL block must be terminated with a semi-colon (;). + +- If `program_type` is `PROCEDURE`, `program_action` contains the name of the stored procedure. + +`number_of_arguments` + +- If `program_type` is `PLSQL_BLOCK`, this argument is ignored. + +- If `program_type` is `PROCEDURE`, `number_of_arguments` specifies the number of arguments required by the procedure. The default value is `0`. + +`enabled` + + `enabled` specifies if the program is created enabled or disabled: + +- If `enabled` is `TRUE`, the program is created enabled. +- If `enabled` is `FALSE`, the program is created disabled. Use the `DBMS_SCHEDULER.ENABLE` program to enable a disabled program. + + The default value is `FALSE`. + +`comments` + + Use the `comments` parameter to specify a comment about the program. By default, this parameter is `NULL`. + +## Example + +The following call to the `CREATE_PROGRAM` procedure creates a program named `update_log`: + +```sql +EXEC + DBMS_SCHEDULER.CREATE_PROGRAM ( + program_name => 'update_log', + program_type => 'PLSQL_BLOCK', + program_action => 'BEGIN INSERT INTO my_log VALUES(current_timestamp); + END;', + enabled => TRUE, + comment => 'This program adds a row to the my_log table.'); +``` + +`update_log` is a PL/SQL block that adds a row containing the current date and time to the `my_log` table. The program is enabled when the `CREATE_PROGRAM` procedure executes. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/04_create_schedule.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/04_create_schedule.mdx new file mode 100644 index 00000000000..0a58ee0be6d --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/04_create_schedule.mdx @@ -0,0 +1,57 @@ +--- +title: "CREATE_SCHEDULE" +--- + +Use the `CREATE_SCHEDULE` procedure to create a job schedule. The signature of the `CREATE_SCHEDULE` procedure is: + +```sql +CREATE_SCHEDULE( + IN VARCHAR2, + IN TIMESTAMP WITH TIME ZONE DEFAULT NULL, + IN VARCHAR2, + IN TIMESTAMP WITH TIME ZONE DEFAULT NULL, + IN VARCHAR2 DEFAULT NULL) +``` + +## Parameters + +`schedule_name` + + `schedule_name` specifies the name of the schedule. + +`start_date` + + `start_date` is a `TIMESTAMP WITH TIME ZONE` value that specifies the date and time that the schedule is eligible to execute. If you don't specify a `start_date`, the date that the job is enabled is used as the `start_date`. By default, `start_date` is `NULL`. + +`repeat_interval` + + `repeat_interval` is a `VARCHAR2` value that specifies how often the job repeats. If you don't specify a `repeat_interval`, the job executes only once, on the date specified by `start_date`. + + !!! Note + You must provide a value for either `start_date` or `repeat_interval`. If both `start_date` and `repeat_interval` are `NULL`, the server returns an error. + +`end_date` + + `end_date` is a `TIMESTAMP WITH TIME ZONE` value that specifies a time after which the schedule no longer executes. If you specify a date, the `end_date` must be after the `start_date`. The default value is `NULL`. + + !!! Note + If you specify a `repeat_interval` and don't specify an `end_date`, the schedule repeats indefinitely until you disable it. + +`comments` + + Use the `comments` parameter to specify a comment about the schedule. By default, this parameter is `NULL`. + +## Example + +This code fragment calls `CREATE_SCHEDULE` to create a schedule named `weeknights_at_5`: + +```sql +EXEC + DBMS_SCHEDULER.CREATE_SCHEDULE ( + schedule_name => 'weeknights_at_5', + start_date => '01-JUN-13 09:00:00.000000' + repeat_interval => 'FREQ=DAILY;BYDAY=MON,TUE,WED,THU,FRI;BYHOUR=17;', + comments => 'This schedule executes each weeknight at 5:00'); +``` + +The schedule executes each weeknight, at 5:00, effective after June 1, 2013. Since no `end_date` is specified, the schedule executes indefinitely until disabled with `DBMS_SCHEDULER.DISABLE`. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/05_define_program_argument.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/05_define_program_argument.mdx new file mode 100644 index 00000000000..937b6ece8e1 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/05_define_program_argument.mdx @@ -0,0 +1,74 @@ +--- +title: "DEFINE_PROGRAM_ARGUMENT" +--- + +Use the `DEFINE_PROGRAM_ARGUMENT` procedure to define a program argument. The `DEFINE_PROGRAM_ARGUMENT` procedure comes in two forms. The first form defines an argument with a default value: + +```sql +DEFINE_PROGRAM_ARGUMENT( + IN VARCHAR2, + IN PLS_INTEGER, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2, + IN VARCHAR2, + IN BOOLEAN DEFAULT FALSE) +``` + +The second form defines an argument without a default value: + +```sql +DEFINE_PROGRAM_ARGUMENT( + IN VARCHAR2, + IN PLS_INTEGER, + IN VARCHAR2 DEFAULT NULL, + IN VARCHAR2, + IN BOOLEAN DEFAULT FALSE) +``` + +## Parameters + +`program_name` + + `program_name` is the name of the program to which the arguments belong. + +`argument_position` + + `argument_position` specifies the position of the argument as it's passed to the program. + +`argument_name` + + `argument_name` specifies the optional name of the argument. By default, `argument_name` is `NULL`. + +`argument_type IN VARCHAR2` + + `argument_type` specifies the data type of the argument. + +`default_value` + + `default_value` specifies the default value assigned to the argument. `default_value` is overridden by a value specified by the job when the job executes. + +`out_argument IN BOOLEAN DEFAULT FALSE` + + `out_argument` isn't currently used. If specified, the value must be `FALSE`. + +## Example + +This code fragment uses the `DEFINE_PROGRAM_ARGUMENT` procedure to define the first and second arguments in a program named `add_emp`: + +```sql +EXEC + DBMS_SCHEDULER.DEFINE_PROGRAM_ARGUMENT( + program_name => 'add_emp', + argument_position => 1, + argument_name => 'dept_no', + argument_type => 'INTEGER, + default_value => '20'); +EXEC + DBMS_SCHEDULER.DEFINE_PROGRAM_ARGUMENT( + program_name => 'add_emp', + argument_position => 2, + argument_name => 'emp_name', + argument_type => 'VARCHAR2'); +``` + +The first argument is an `INTEGER` value named `dept_no` that has a default value of `20`. The second argument is a `VARCHAR2` value named `emp_name` and doesn't have a default value. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/06_dbms_scheduler_disable.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/06_dbms_scheduler_disable.mdx new file mode 100644 index 00000000000..dfc88872f4d --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/06_dbms_scheduler_disable.mdx @@ -0,0 +1,38 @@ +--- +title: "DISABLE" +--- + + + +Use the `DISABLE` procedure to disable a program or a job. The signature of the `DISABLE` procedure is: + +```sql +DISABLE( + IN VARCHAR2, + IN BOOLEAN DEFAULT FALSE, + IN VARCHAR2 DEFAULT 'STOP_ON_FIRST_ERROR') +``` + +## Parameters + +`name` + + `name` specifies the name of the program or job that's being disabled. + +`force` + + `force` is accepted for compatibility and ignored. + +`commit_semantics` + + `commit_semantics` tells the server how to handle an error encountered while disabling a program or job. By default, `commit_semantics` is set to `STOP_ON_FIRST_ERROR`, which means to stop when an error is encountered. Any programs or jobs that were successfully disabled before the error are committed to disk. + + The `TRANSACTIONAL` and `ABSORB_ERRORS` keywords are accepted for compatibility and ignored. + +## Example + +The following call to the `DISABLE` procedure disables a program named `update_emp`: + +```sql +DBMS_SCHEDULER.DISABLE('update_emp'); +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/07_drop_job.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/07_drop_job.mdx new file mode 100644 index 00000000000..f350600f1d6 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/07_drop_job.mdx @@ -0,0 +1,41 @@ +--- +title: "DROP_JOB" +--- + +Use the `DROP_JOB` procedure to drop a job, drop any arguments that belong to the job, and eliminate any future job executions. The signature of the procedure is: + +```sql +DROP_JOB( + IN VARCHAR2, + IN BOOLEAN DEFAULT FALSE, + IN BOOLEAN DEFAULT FALSE, + IN VARCHAR2 DEFAULT 'STOP_ON_FIRST_ERROR') +``` + +## Parameters + +`job_name` + + `job_name` specifies the name of the job that's being dropped. + +`force` + + `force` is accepted for compatibility and ignored. + +`defer` + + `defer` is accepted for compatibility and ignored. + +`commit_semantics` + + `commit_semantics` tells the server how to handle an error encountered while dropping a program or job. By default, `commit_semantics` is set to `STOP_ON_FIRST_ERROR`, which means to stop when an error is encountered. + + The `TRANSACTIONAL` and `ABSORB_ERRORS` keywords are accepted for compatibility and ignored. + +## Example + +The following call to `DROP_JOB` drops a job named `update_log`: + +```sql +DBMS_SCHEDULER.DROP_JOB('update_log'); +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/08_drop_program.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/08_drop_program.mdx new file mode 100644 index 00000000000..cf855edf68a --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/08_drop_program.mdx @@ -0,0 +1,35 @@ +--- +title: "DROP_PROGRAM" +--- + +The `DROP_PROGRAM` procedure drops a program. The signature of the `DROP_PROGRAM` procedure is: + +```sql +DROP_PROGRAM( + IN VARCHAR2, + IN BOOLEAN DEFAULT FALSE) +``` + +## Parameters + +`program_name` + + `program_name` specifies the name of the program that's being dropped. + +`force` + + `force` is a Boolean value that tells the server how to handle programs with dependent jobs. + +- Specify `FALSE` to return an error if the program is referenced by a job. + +- Specify `TRUE` to disable any jobs that reference the program before dropping the program. + + The default value is `FALSE`. + +## Example + +The following call to `DROP_PROGRAM` drops a job named `update_emp`: + +```sql +DBMS_SCHEDULER.DROP_PROGRAM('update_emp'); +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/09_drop_program_argument.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/09_drop_program_argument.mdx new file mode 100644 index 00000000000..5f078303f8d --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/09_drop_program_argument.mdx @@ -0,0 +1,47 @@ +--- +title: "DROP_PROGRAM_ARGUMENT" +--- + +Use the `DROP_PROGRAM_ARGUMENT` procedure to drop a program argument. The `DROP_PROGRAM_ARGUMENT` procedure comes in two forms. The first form uses an argument position to specify the argument to drop: + +```sql +DROP_PROGRAM_ARGUMENT( + IN VARCHAR2, + IN PLS_INTEGER) +``` + +The second form takes the argument name: + +```sql +DROP_PROGRAM_ARGUMENT( + IN VARCHAR2, + IN VARCHAR2) +``` + +## Parameters + +`program_name` + + `program_name` specifies the name of the program that's being modified. + +`argument_position` + + `argument_position` specifies the position of the argument that's being dropped. + +`argument_name` + + `argument_name` specifies the name of the argument that's being dropped. + +## Examples + +The following call to `DROP_PROGRAM_ARGUMENT` drops the first argument in the `update_emp` program: + +```sql +DBMS_SCHEDULER.DROP_PROGRAM_ARGUMENT('update_emp', 1); +``` + +The following call to `DROP_PROGRAM_ARGUMENT` drops an argument named `emp_name`: + +```sql +DBMS_SCHEDULER.DROP_PROGRAM_ARGUMENT(update_emp', 'emp_name'); +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/10_drop_schedule.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/10_drop_schedule.mdx new file mode 100644 index 00000000000..57f66bf30a4 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/10_drop_schedule.mdx @@ -0,0 +1,34 @@ +--- +title: "DROP_SCHEDULE" +--- + +Use the `DROP_SCHEDULE` procedure to drop a schedule. The signature is: + +```sql +DROP_SCHEDULE( + IN VARCHAR2, + IN BOOLEAN DEFAULT FALSE) +``` + +## Parameters + +`schedule_name` + + `schedule_name` specifies the name of the schedule that's being dropped. + +`force` + + `force` specifies the behavior of the server if the specified schedule is referenced by any job: + + - Specify `FALSE` to return an error if the specified schedule is referenced by a job. This is the default behavior. + - Specify `TRUE` to disable to any jobs that use the specified schedule before dropping the schedule. Any running jobs are allowed to complete before the schedule is dropped. + +## Example + +The following call to `DROP_SCHEDULE` drops a schedule named `weeknights_at_5`: + +```sql +DBMS_SCHEDULER.DROP_SCHEDULE('weeknights_at_5', TRUE); +``` + +The server disables any jobs that use the schedule before dropping the schedule. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/11_dbms_scheduler_enable.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/11_dbms_scheduler_enable.mdx new file mode 100644 index 00000000000..b775d4fd579 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/11_dbms_scheduler_enable.mdx @@ -0,0 +1,35 @@ +--- +title: "ENABLE" +--- + + + +Use the `ENABLE` procedure to enable a disabled program or job. + +The signature of the `ENABLE` procedure is: + +```sql +ENABLE( + IN VARCHAR2, + IN VARCHAR2 DEFAULT 'STOP_ON_FIRST_ERROR') +``` + +## Parameters + +`name` + + `name` specifies the name of the program or job that's being enabled. + +`commit_semantics` + + `commit_semantics` tells the server how to handle an error encountered while enabling a program or job. By default, `commit_semantics` is set to `STOP_ON_FIRST_ERROR`, tellin the server to stop when it encounters an error. + + The `TRANSACTIONAL` and `ABSORB_ERRORS` keywords are accepted for compatibility and ignored. + +## Example + +The following call to `DBMS_SCHEDULER.ENABLE` enables the `update_emp` program: + +```sql +DBMS_SCHEDULER.ENABLE('update_emp'); +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/12_evaluate_calendar_string.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/12_evaluate_calendar_string.mdx new file mode 100644 index 00000000000..0902ab97be2 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/12_evaluate_calendar_string.mdx @@ -0,0 +1,59 @@ +--- +title: "EVALUATE_CALENDAR_STRING" +--- + +Use the `EVALUATE_CALENDAR_STRING` procedure to evaluate the `repeat_interval` value specified when creating a schedule with the `CREATE_SCHEDULE` procedure. The `EVALUATE_CALENDAR_STRING` procedure returns the date and time that a specified schedule executes without actually scheduling the job. + +The signature of the `EVALUATE_CALENDAR_STRING` procedure is: + +```sql +EVALUATE_CALENDAR_STRING( + IN VARCHAR2, + IN TIMESTAMP WITH TIME ZONE, + IN TIMESTAMP WITH TIME ZONE, + OUT TIMESTAMP WITH TIME ZONE) +``` + +## Parameters + +`calendar_string` + + `calendar_string` is the calendar string that describes a `repeat_interval` that's being evaluated. + +`start_date IN TIMESTAMP WITH TIME ZONE` + + `start_date` is the date and time after which the `repeat_interval` becomes valid. + +`return_date_after` + + Use the `return_date_after` parameter to specify the date and time for `EVALUATE_CALENDAR_STRING` to use as a starting date when evaluating the `repeat_interval`. + + For example, if you specify a `return_date_after` value of `01-APR-13 09.00.00.000000`, `EVALUATE_CALENDAR_STRING` returns the date and time of the first iteration of the schedule after April 1st, 2013. + +`next_run_date OUT TIMESTAMP WITH TIME ZONE` + + `next_run_date` is an `OUT` parameter that contains the first occurrence of the schedule after the date specified by the `return_date_after` parameter. + +## Example + +This example evaluates a calendar string and returns the first date and time that the schedule will execute after June 15, 2013: + +```sql +DECLARE + result TIMESTAMP; +BEGIN + + DBMS_SCHEDULER.EVALUATE_CALENDAR_STRING + ( + 'FREQ=DAILY;BYDAY=MON,TUE,WED,THU,FRI;BYHOUR=17;', + '15-JUN-2013', NULL, result + ); + + DBMS_OUTPUT.PUT_LINE('next_run_date: ' || result); +END; +/ + +next_run_date: 17-JUN-13 05.00.00.000000 PM +``` + +Because June 15, 2013 is a Saturday, the schedule will execute on Monday, June 17, 2013 at 5:00 pm. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/13_run_job.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/13_run_job.mdx new file mode 100644 index 00000000000..6b3768424d5 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/13_run_job.mdx @@ -0,0 +1,31 @@ +--- +title: "RUN_JOB" +--- + +Use the `RUN_JOB` procedure to execute a job immediately. The signature of the `RUN_JOB` procedure is: + +```sql +RUN_JOB( + IN VARCHAR2, + IN BOOLEAN DEFAULT TRUE +``` + +## Parameters + +`job_name` + + `job_name` specifies the name of the job to execute. + +`use_current_session` + + By default, the job executes in the current session. If specified, `use_current_session` must be set to `TRUE`. If `use_current_session` is set to `FALSE`, EDB Postgres Advanced Server returns an error. + +## Example + +The following call to `RUN_JOB` executes a job named `update_log`: + +```sql +DBMS_SCHEDULER.RUN_JOB('update_log', TRUE); +``` + +Passing a value of `TRUE` as the second argument instructs the server to invoke the job in the current session. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/14_set_job_argument_value.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/14_set_job_argument_value.mdx new file mode 100644 index 00000000000..cd0c857cfc7 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/14_set_job_argument_value.mdx @@ -0,0 +1,55 @@ +--- +title: "SET_JOB_ARGUMENT_VALUE" +--- + +Use the `SET_JOB_ARGUMENT_VALUE` procedure to specify a value for an argument. The `SET_JOB_ARGUMENT_VALUE` procedure comes in two forms. The first form specifies the argument to modify by position: + +```sql +SET_JOB_ARGUMENT_VALUE( + IN VARCHAR2, + IN PLS_INTEGER, + IN VARCHAR2) +``` + +The second form uses an argument name to specify the argument to modify: + +```sql +SET_JOB_ARGUMENT_VALUE( + IN VARCHAR2, + IN VARCHAR2, + IN VARCHAR2) +``` + +Argument values set by the `SET_JOB_ARGUMENT_VALUE` procedure override any values set by default. + +## Parameters + +`job_name` + + `job_name` specifies the name of the job to which the modified argument belongs. + +`argument_position` + + Use `argument_position` to specify the argument position for which the value is set. + +`argument_name` + + Use `argument_name` to specify the argument by name for which the value is set. + +`argument_value` + + `argument_value` specifies the new value of the argument. + +## Examples + +This example assigns a value of `30` to the first argument in the `update_emp` job: + +```sql +DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE('update_emp', 1, '30'); +``` + +This example sets the `emp_name` argument to `SMITH`: + +```sql +DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE('update_emp', 'emp_name', 'SMITH'); +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/index.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/index.mdx new file mode 100644 index 00000000000..1ced38788ce --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/index.mdx @@ -0,0 +1,50 @@ +--- +title: "DBMS_SCHEDULER" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.28.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.201.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.159.html" +--- + +The `DBMS_SCHEDULER` package provides a way to create and manage Oracle-style jobs, programs, and job schedules. The `DBMS_SCHEDULER` package implements the following functions and procedures: + +| Function/procedure | Return type | Description | +| ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `CREATE_JOB(job_name, job_type, job_action, number_of_arguments, start_date, repeat_interval, end_date, job_class, enabled, auto_drop, comments)` | n/a | Use the first form of the `CREATE_JOB` procedure to create a job, specifying program and schedule details by means of parameters. | +| `CREATE_JOB(job_name, program_name, schedule_name, job_class, enabled, auto_drop, comments)` | n/a | Use the second form of `CREATE_JOB` to create a job that uses a named program and named schedule. | +| `CREATE_PROGRAM(program_name, program_type, program_action, number_of_arguments, enabled, comments)` | n/a | Use `CREATE_PROGRAM` to create a program. | +| `CREATE_SCHEDULE(schedule_name, start_date, repeat_interval, end_date, comments)` | n/a | Use the `CREATE_SCHEDULE` procedure to create a schedule. | +| `DEFINE_PROGRAM_ARGUMENT(program_name, argument_position, argument_name, argument_type, default_value, out_argument)` | n/a | Use the first form of the `DEFINE_PROGRAM_ARGUMENT` procedure to define a program argument that has a default value. | +| `DEFINE_PROGRAM_ARGUMENT(program_name, argument_position, argument_name, argument_type, out_argument)` | n/a | Use the first form of the `DEFINE_PROGRAM_ARGUMENT` procedure to define a program argument that doesn't have a default value. | +| `DISABLE(name, force, commit_semantics)` | n/a | Use the `DISABLE` procedure to disable a job or program. | +| `DROP_JOB(job_name, force, defer, commit_semantics)` | n/a | Use the `DROP_JOB` procedure to drop a job. | +| `DROP_PROGRAM(program_name, force)` | n/a | Use the `DROP_PROGRAM` procedure to drop a program. | +| `DROP_PROGRAM_ARGUMENT(program_name, argument_position)` | n/a | Use the first form of `DROP_PROGRAM_ARGUMENT` to drop a program argument by specifying the argument position. | +| `DROP_PROGRAM_ARGUMENT(program_name, argument_name)` | n/a | Use the second form of `DROP_PROGRAM_ARGUMENT` to drop a program argument by specifying the argument name. | +| `DROP_SCHEDULE(schedule_name, force)` | n/a | Use the `DROP SCHEDULE` procedure to drop a schedule. | +| `ENABLE(name, commit_semantics)` | n/a | Use the `ENABLE` command to enable a program or job. | +| `EVALUATE_CALENDAR_STRING(calendar_string, start_date, return_date_after, next_run_date)` | n/a | Use `EVALUATE_CALENDAR_STRING` to review the execution date described by a user-defined calendar schedule. | +| `RUN_JOB(job_name, use_current_session, manually)` | n/a | Use the `RUN_JOB` procedure to execute a job immediately. | +| `SET_JOB_ARGUMENT_VALUE(job_name, argument_position, argument_value)` | n/a | Use the first form of `SET_JOB_ARGUMENT_VALUE` to set the value of a job argument described by the argument's position. | +| `SET_JOB_ARGUMENT_VALUE(job_name, argument_name, argument_value)` | n/a | Use the second form of `SET_JOB_ARGUMENT_VALUE` to set the value of a job argument described by the argument's name. | + +EDB Postgres Advanced Server's implementation of `DBMS_SCHEDULER` is a partial implementation when compared to Oracle's version. Only those functions and procedures listed in the table are supported. + +The `DBMS_SCHEDULER` package depends on the pgAgent service. You must have a pgAgent service installed and running on your server before using `DBMS_SCHEDULER`. + +Before using `DBMS_SCHEDULER`, a database superuser must create the catalog tables in which the `DBMS_SCHEDULER` programs, schedules, and jobs are stored. Use the psql client to connect to the database, and invoke the command: + +```sql +CREATE EXTENSION dbms_scheduler; +``` + +By default, the `dbms_scheduler` extension resides in the `contrib/dbms_scheduler_ext` subdirectory under the EDB Postgres Advanced Server installation. + +After creating the `DBMS_SCHEDULER` tables, only a superuser can perform a dump or reload of the database. + +
+ +using_calendar_syntax_to_specify_a_repeating_interval create_job create_program create_schedule define_program_argument dbms_scheduler_disable drop_job drop_program drop_program_argument drop_schedule dbms_scheduler_enable evaluate_calendar_string run_job set_job_argument_value + +
diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/16_dbms_session.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/16_dbms_session.mdx new file mode 100644 index 00000000000..4cc6a0b1e93 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/16_dbms_session.mdx @@ -0,0 +1,42 @@ +--- +title: "DBMS_SESSION" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-reference-guide/9.6/Database_Compatibility_for_Oracle_Developers_Reference_Guide.1.090.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.29.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.202.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.116.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.160.html" +--- + +EDB Postgres Advanced Server provides support for the following `DBMS_SESSION.SET_ROLE` procedure: + +| Function/procedure | Return type | Description | +| -------------------- | ----------- | ------------------------------------------------------------------------------------- | +| `SET_ROLE(role_cmd)` | n/a | Executes a `SET ROLE` statement followed by the string value specified in `role_cmd`. | + +EDB Postgres Advanced Server's implementation of `DBMS_SESSION` is a partial implementation when compared to Oracle's version. Only `DBMS_SESSION.SET_ROLE` is supported. + +## SET_ROLE + +The `SET_ROLE` procedure sets the current session user to the role specified in `role_cmd`. After invoking the `SET_ROLE` procedure, the current session uses the permissions assigned to the specified role. The signature of the procedure is: + +```sql +SET_ROLE() +``` + +The `SET_ROLE` procedure appends the value specified for `role_cmd` to the `SET ROLE` statement and then invokes the statement. + +### Parameters + +`role_cmd` + + `role_cmd` specifies a role name in the form of a string value. + +### Example + +This call to the `SET_ROLE` procedure invokes the `SET ROLE` command to set the identity of the current session user to manager: + +```sql +edb=# exec DBMS_SESSION.SET_ROLE('manager'); +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/01_bind_variable.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/01_bind_variable.mdx new file mode 100644 index 00000000000..8c4527adf87 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/01_bind_variable.mdx @@ -0,0 +1,75 @@ +--- +title: "BIND_VARIABLE" +--- + +The `BIND_VARIABLE` procedure associates a value with an `IN` or `IN OUT` bind variable in a SQL command. + +```sql +BIND_VARIABLE( NUMBER, VARCHAR2, + { BLOB | CLOB | DATE | FLOAT | INTEGER | NUMBER | TIMESTAMP | VARCHAR2 } + [, NUMBER ]) +``` + +## Parameters + +`c` + + Cursor ID of the cursor for the SQL command with bind variables. + +`name` + + Name of the bind variable in the SQL command. + +`value` + + Value to be assigned. + +`out_value_size` + + If `name` is an `IN OUT` variable, defines the maximum length of the output value. If not specified, the length of `value` is assumed. + +## Examples + +The following anonymous block uses bind variables to insert a row into the `emp` table. + +```sql +DECLARE + curid NUMBER; + v_sql VARCHAR2(150) := 'INSERT INTO emp VALUES ' || + '(:p_empno, :p_ename, :p_job, :p_mgr, ' || + ':p_hiredate, :p_sal, :p_comm, :p_deptno)'; + v_empno emp.empno%TYPE; + v_ename emp.ename%TYPE; + v_job emp.job%TYPE; + v_mgr emp.mgr%TYPE; + v_hiredate emp.hiredate%TYPE; + v_sal emp.sal%TYPE; + v_comm emp.comm%TYPE; + v_deptno emp.deptno%TYPE; + v_status INTEGER; +BEGIN + curid := DBMS_SQL.OPEN_CURSOR; + DBMS_SQL.PARSE(curid,v_sql,DBMS_SQL.native); + v_empno := 9001; + v_ename := 'JONES'; + v_job := 'SALESMAN'; + v_mgr := 7369; + v_hiredate := TO_DATE('13-DEC-07','DD-MON-YY'); + v_sal := 8500.00; + v_comm := 1500.00; + v_deptno := 40; + DBMS_SQL.BIND_VARIABLE(curid,':p_empno',v_empno); + DBMS_SQL.BIND_VARIABLE(curid,':p_ename',v_ename); + DBMS_SQL.BIND_VARIABLE(curid,':p_job',v_job); + DBMS_SQL.BIND_VARIABLE(curid,':p_mgr',v_mgr); + DBMS_SQL.BIND_VARIABLE(curid,':p_hiredate',v_hiredate); + DBMS_SQL.BIND_VARIABLE(curid,':p_sal',v_sal); + DBMS_SQL.BIND_VARIABLE(curid,':p_comm',v_comm); + DBMS_SQL.BIND_VARIABLE(curid,':p_deptno',v_deptno); + v_status := DBMS_SQL.EXECUTE(curid); + DBMS_OUTPUT.PUT_LINE('Number of rows processed: ' || v_status); + DBMS_SQL.CLOSE_CURSOR(curid); +END; + +Number of rows processed: 1 +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/02_bind_variable_char.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/02_bind_variable_char.mdx new file mode 100644 index 00000000000..c2b1c0fdd10 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/02_bind_variable_char.mdx @@ -0,0 +1,28 @@ +--- +title: "BIND_VARIABLE_CHAR" +--- + +The `BIND_VARIABLE_CHAR` procedure associates a `CHAR` value with an `IN` or `IN OUT` bind variable in a SQL command. + +```sql +BIND_VARIABLE_CHAR( NUMBER, VARCHAR2, CHAR + [, NUMBER ]) +``` + +## Parameters + +`c` + + Cursor ID of the cursor for the SQL command with bind variables. + +`name` + + Name of the bind variable in the SQL command. + +`value` + + Value of type `CHAR` to be assigned. + +`out_value_size` + + If `name` is an `IN OUT` variable, defines the maximum length of the output value. If not specified, the length of `value` is assumed. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/03_bind_variable_raw.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/03_bind_variable_raw.mdx new file mode 100644 index 00000000000..f586bc17ac2 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/03_bind_variable_raw.mdx @@ -0,0 +1,28 @@ +--- +title: "BIND_VARIABLE_RAW" +--- + +The `BIND_VARIABLE_RAW` procedure associates a `RAW` value with an `IN` or `IN OUT` bind variable in a SQL command. + +```sql +BIND_VARIABLE_RAW( NUMBER, VARCHAR2, RAW + [, NUMBER ]) +``` + +## Parameters + +`c` + + Cursor ID of the cursor for the SQL command with bind variables. + +`name` + + Name of the bind variable in the SQL command. + +`value` + + Value of type `RAW` to be assigned. + +`out_value_size` + + If `name` is an `IN OUT` variable, defines the maximum length of the output value. If not specified, the length of `value` is assumed. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/04_close_cursor.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/04_close_cursor.mdx new file mode 100644 index 00000000000..a3ae7bdc9c0 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/04_close_cursor.mdx @@ -0,0 +1,35 @@ +--- +title: "CLOSE_CURSOR" +--- + +The `CLOSE_CURSOR` procedure closes an open cursor. The resources allocated to the cursor are released and you can no longer use it. + +```sql +CLOSE_CURSOR( IN OUT NUMBER) +``` + +## Parameters + +`c` + + Cursor ID of the cursor to be closed. + +## Examples + +This example closes an open cursor: + +```sql +DECLARE + curid NUMBER; + v_sql VARCHAR2(150); + v_status INTEGER; +BEGIN + v_sql:='INSERT INTO emp VALUES (9001,''JONES'',''SALESMAN'',7369,TO_DATE(''13-DEC-07'',''DD-MON-YY''),8500.00,1500.00,50)'; + curid := DBMS_SQL.OPEN_CURSOR; + DBMS_SQL.PARSE(curid,v_sql,DBMS_SQL.native); + v_status := DBMS_SQL.EXECUTE(curid); + DBMS_OUTPUT.PUT_LINE('Number of rows processed: ' || v_status); + DBMS_SQL.CLOSE_CURSOR(curid); +END; +``` + diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/05_column_value.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/05_column_value.mdx new file mode 100644 index 00000000000..ba441aa110b --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/05_column_value.mdx @@ -0,0 +1,75 @@ +--- +title: "COLUMN_VALUE" +--- + +The `COLUMN_VALUE` procedure defines a variable to receive a value from a cursor. + +```sql +COLUMN_VALUE( NUMBER, NUMBER, OUT { BLOB | CLOB | DATE | FLOAT | + INTEGER | NUMBER | TIMESTAMP | VARCHAR2 } + [, OUT NUMBER [, OUT INTEGER ]]) +``` + +## Parameters + +`c` + + Cursor id of the cursor returning data to the variable being defined. + +`position` + + Position of the returned data in the cursor. The first value in the cursor is position 1. + +`value` + + Variable receiving the data returned in the cursor by a prior fetch call. + +`column_error` + + Error number associated with the column, if any. + +`actual_length` + + Actual length of the data prior to any truncation. + +## Examples + +This example shows the portion of an anonymous block that receives the values from a cursor using the `COLUMN_VALUE` procedure. + +```sql +DECLARE + curid NUMBER; + v_empno NUMBER(4); + v_ename VARCHAR2(10); + v_hiredate DATE; + v_sal NUMBER(7,2); + v_comm NUMBER(7,2); + v_sql VARCHAR2(50) := 'SELECT empno, ename, hiredate, sal, ' || + 'comm FROM emp'; + v_status INTEGER; +BEGIN + curid := DBMS_SQL.OPEN_CURSOR; + DBMS_SQL.PARSE(curid,v_sql,DBMS_SQL.native); + DBMS_SQL.DEFINE_COLUMN(curid,1,v_empno); + DBMS_SQL.DEFINE_COLUMN(curid,2,v_ename); + DBMS_SQL.DEFINE_COLUMN(curid,3,v_hiredate); + DBMS_SQL.DEFINE_COLUMN(curid,4,v_sal); + DBMS_SQL.DEFINE_COLUMN(curid,5,v_comm); + v_status := DBMS_SQL.EXECUTE(curid); . + LOOP + v_status := DBMS_SQL.FETCH_ROWS(curid); + EXIT WHEN v_status = 0; + DBMS_SQL.COLUMN_VALUE(curid,1,v_empno); + DBMS_SQL.COLUMN_VALUE(curid,2,v_ename); + DBMS_SQL.COLUMN_VALUE(curid,3,v_hiredate); + DBMS_SQL.COLUMN_VALUE(curid,4,v_sal); + DBMS_SQL.COLUMN_VALUE(curid,4,v_sal); + DBMS_SQL.COLUMN_VALUE(curid,5,v_comm); + DBMS_OUTPUT.PUT_LINE(v_empno || ' ' || RPAD(v_ename,10) || ' ' || + TO_CHAR(v_hiredate,'yyyy-mm-dd') || ' ' || + TO_CHAR(v_sal,'9,999.99') || ' ' || + TO_CHAR(NVL(v_comm,0),'9,999.99')); + END LOOP; + DBMS_SQL.CLOSE_CURSOR(curid); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/06_column_value_char.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/06_column_value_char.mdx new file mode 100644 index 00000000000..72e6445ed61 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/06_column_value_char.mdx @@ -0,0 +1,32 @@ +--- +title: "COLUMN_VALUE_CHAR" +--- + +The `COLUMN_VALUE_CHAR` procedure defines a variable to receive a `CHAR` value from a cursor. + +```sql +COLUMN_VALUE_CHAR( NUMBER, NUMBER, OUT CHAR + [, OUT NUMBER [, OUT INTEGER ]]) +``` + +## Parameters + +`c` + + Cursor id of the cursor returning data to the variable being defined. + +`position` + + Position of the returned data in the cursor. The first value in the cursor is position 1. + +`value` + + Variable of data type `CHAR` receiving the data returned in the cursor by a prior fetch call. + +`column_error` + + Error number associated with the column, if any. + +`actual_length` + + Actual length of the data prior to any truncation. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/07_column_value_raw.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/07_column_value_raw.mdx new file mode 100644 index 00000000000..e9fa9eb7b3c --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/07_column_value_raw.mdx @@ -0,0 +1,69 @@ +--- +title: "COLUMN_VALUE_RAW" +--- + +The `COLUMN_VALUE_RAW` procedure defines a variable to receive a `RAW` value from a cursor. + +```sql +COLUMN_VALUE_RAW( NUMBER, NUMBER, OUT RAW + [, OUT NUMBER [, OUT INTEGER ]]) +``` + +## Parameters + +`c` + + Cursor id of the cursor returning data to the variable being defined. + +`position` + + Position of the returned data in the cursor. The first value in the cursor is position 1. + +`value` + + Variable of data type `RAW` receiving the data returned in the cursor by a prior fetch call. + +`column_error` + + Error number associated with the column, if any. + +`actual_length` + + Actual length of the data prior to any truncation. + +## COLUMN_VALUE_LONG + +The `COLUMN_VALUE_LONG` procedure returns a part of the value of a `LONG` column. + +```sql +COLUMN_VALUE_LONG( NUMBER, NUMBER, NUMBER, + NUMBER, OUT VARCHAR2, OUT INTEGER) +``` + +### Parameters + +`c` + + Cursor id of the cursor from which to get a value. + +`position` + + Position of the column of which to get a value. + +`length` + + Number of bytes of the long value to fetch. + +`offset` + + Offset into the long field for start of fetch. + +`value` + + Value of the column. + +`value_length` + + Number of bytes returned in value. + +For an example, see [DEFINE_COLUMN_LONG](10_define_column_raw/#define_column_long). diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/08_define_column.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/08_define_column.mdx new file mode 100644 index 00000000000..0947205936e --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/08_define_column.mdx @@ -0,0 +1,107 @@ +--- +title: "DEFINE_COLUMN" +--- + +The `DEFINE_COLUMN` procedure defines a column or expression in the `SELECT` list to be returned and retrieved in a cursor. + +```sql +DEFINE_COLUMN( NUMBER, NUMBER, { BLOB | CLOB | DATE | FLOAT | + INTEGER | NUMBER | TIMESTAMP | VARCHAR2 } + [, NUMBER ]) +``` + +## Parameters + +`c` + + Cursor id of the cursor associated with the `SELECT` command. + +`position` + + Position of the column or expression in the `SELECT` list that's being defined. + +`column` + + A variable of the same data type as the column or expression in position `position` of the `SELECT` list. + +`column_size` + + The maximum length of the returned data. Specify `column_size` only if `column` is `VARCHAR2`. Returned data exceeding `column_size` is truncated to `column_size` characters. + +## Examples + +This example shows how the `empno`, `ename`, `hiredate`, `sal`, and `comm` columns of the `emp` table are defined with the `DEFINE_COLUMN` procedure. + +```sql +DECLARE + curid NUMBER; + v_empno NUMBER(4); + v_ename VARCHAR2(10); + v_hiredate DATE; + v_sal NUMBER(7,2); + v_comm NUMBER(7,2); + v_sql VARCHAR2(50) := 'SELECT empno, ename, hiredate, sal, ' || + 'comm FROM emp'; + v_status INTEGER; +BEGIN + curid := DBMS_SQL.OPEN_CURSOR; + DBMS_SQL.PARSE(curid,v_sql,DBMS_SQL.native); + DBMS_SQL.DEFINE_COLUMN(curid,1,v_empno); + DBMS_SQL.DEFINE_COLUMN(curid,2,v_ename,10); + DBMS_SQL.DEFINE_COLUMN(curid,3,v_hiredate); + DBMS_SQL.DEFINE_COLUMN(curid,4,v_sal); + DBMS_SQL.DEFINE_COLUMN(curid,5,v_comm); + v_status := DBMS_SQL.EXECUTE(curid); + LOOP + v_status := DBMS_SQL.FETCH_ROWS(curid); + EXIT WHEN v_status = 0; + DBMS_SQL.COLUMN_VALUE(curid,1,v_empno); + DBMS_SQL.COLUMN_VALUE(curid,2,v_ename); + DBMS_SQL.COLUMN_VALUE(curid,3,v_hiredate); + DBMS_SQL.COLUMN_VALUE(curid,4,v_sal); + DBMS_SQL.COLUMN_VALUE(curid,5,v_comm); + DBMS_OUTPUT.PUT_LINE(v_empno || ' ' ||v_ename|| ' ' || + TO_CHAR(v_hiredate,'yyyy-mm-dd') || ' ' || + TO_CHAR(v_sal,'9,999.99') || ' ' || + TO_CHAR(NVL(v_comm,0),'9,999.99')); + END LOOP; + DBMS_SQL.CLOSE_CURSOR(curid); +END; +``` + +The following shows an alternative that produces the same results. The lengths of the data types are irrelevant. The `empno`, `sal`, and `comm` columns still return data equivalent to `NUMBER(4)` and `NUMBER(7,2)`, respectively, even though `v_num` is defined as `NUMBER(1)` (assuming the declarations in the `COLUMN_VALUE` procedure are of the appropriate maximum sizes). The `ename` column returns data up to 10 characters in length as defined by the `length` parameter in the `DEFINE_COLUMN` call, not by the data type declaration, `VARCHAR2(1)` declared for `v_varchar`. The actual size of the returned data is dictated by the `COLUMN_VALUE` procedure. + +```sql +DECLARE + curid NUMBER; + v_num NUMBER(1); + v_varchar VARCHAR2(1); + v_date DATE; + v_sql VARCHAR2(50) := 'SELECT empno, ename, hiredate, sal, ' || + 'comm FROM emp'; + v_status INTEGER; +BEGIN + curid := DBMS_SQL.OPEN_CURSOR; + DBMS_SQL.PARSE(curid,v_sql,DBMS_SQL.native); + DBMS_SQL.DEFINE_COLUMN(curid,1,v_num); + DBMS_SQL.DEFINE_COLUMN(curid,2,v_varchar,10); + DBMS_SQL.DEFINE_COLUMN(curid,3,v_date); + DBMS_SQL.DEFINE_COLUMN(curid,4,v_num); + DBMS_SQL.DEFINE_COLUMN(curid,5,v_num); + v_status := DBMS_SQL.EXECUTE(curid); + LOOP + v_status := DBMS_SQL.FETCH_ROWS(curid); + EXIT WHEN v_status = 0; + DBMS_SQL.COLUMN_VALUE(curid,1,v_empno); + DBMS_SQL.COLUMN_VALUE(curid,2,v_ename); + DBMS_SQL.COLUMN_VALUE(curid,3,v_hiredate); + DBMS_SQL.COLUMN_VALUE(curid,4,v_sal); + DBMS_SQL.COLUMN_VALUE(curid,5,v_comm); + DBMS_OUTPUT.PUT_LINE(v_empno || ' ' ||v_ename|| ' ' || + TO_CHAR(v_hiredate,'yyyy-mm-dd') || ' ' || + TO_CHAR(v_sal,'9,999.99') || ' ' || + TO_CHAR(NVL(v_comm,0),'9,999.99')); + END LOOP; + DBMS_SQL.CLOSE_CURSOR(curid); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/09_define_column_char.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/09_define_column_char.mdx new file mode 100644 index 00000000000..ad69e0ff1ff --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/09_define_column_char.mdx @@ -0,0 +1,28 @@ +--- +title: "DEFINE_COLUMN_CHAR" +--- + +The `DEFINE_COLUMN_CHAR` procedure defines a `CHAR` column or expression in the `SELECT` list to be returned and retrieved in a cursor. + +```sql +DEFINE_COLUMN_CHAR( NUMBER, NUMBER, +CHAR, NUMBER) +``` + +## Parameters + +`c` + + Cursor id of the cursor associated with the `SELECT` command. + +`position` + + Position of the column or expression in the `SELECT` list being defined. + +`column` + + A `CHAR` variable. + +`column_size` + + The maximum length of the returned data. Returned data exceeding `column_size` is truncated to `column_size` characters. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/10_define_column_raw.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/10_define_column_raw.mdx new file mode 100644 index 00000000000..5ff9ec9d4d8 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/10_define_column_raw.mdx @@ -0,0 +1,74 @@ +--- +title: "DEFINE_COLUMN_RAW" +--- + +The `DEFINE_COLUMN_RAW` procedure defines a `RAW` column or expression in the `SELECT` list to be returned and retrieved in a cursor. + +```sql +DEFINE_COLUMN_RAW( NUMBER, NUMBER, RAW, + NUMBER) +``` + +## Parameters + +`c` + + Cursor id of the cursor associated with the `SELECT` command. + +`position` + + Position of the column or expression in the `SELECT` list being defined. + +`column` + + A `RAW` variable. + +`column_size` + + The maximum length of the returned data. Returned data exceeding `column_size` is truncated to `column_size` characters. + +## DEFINE_COLUMN_LONG + + + +The `DEFINE_COLUMN_LONG` procedure defines a long column for a `SELECT` cursor. + +```sql +DEFINE_COLUMN_LONG( NUMBER, NUMBER) +``` + +### Parameters + +`c` + + Cursor id of the cursor for a row defined to be selected. + +`position` + + Position of the column in a row being defined. + +### Examples + +This example shows an anonymous block that defines a long column in the `SELECT` list using `DEFINE_COLUMN_LONG` procedure. It returns a part of the `LONG` column value into a variable using procedure `COLUMN_VALUE_LONG`. + +```sql +DECLARE + curid NUMBER; + v_ename VARCHAR(20); + sql_stmt VARCHAR2(50) := 'SELECT ename ' || ' FROM emp WHERE empno + = 7844'; + v_status INTEGER; + v_length INTEGER; +BEGIN + curid := DBMS_SQL.OPEN_CURSOR; + DBMS_SQL.PARSE(curid, sql_stmt, DBMS_SQL.native); + DBMS_SQL.DEFINE_COLUMN_LONG(curid, 1); + v_status := DBMS_SQL.EXECUTE(curid); + v_status := DBMS_SQL.FETCH_ROWS(curid); + DBMS_SQL.COLUMN_VALUE_LONG(curid, 1, 7, 0, v_ename, v_length); + DBMS_OUTPUT.PUT_LINE('ename: ' || v_ename || ' & length: ' || v_length); + DBMS_SQL.CLOSE_CURSOR(curid); +END; + +ename: TURNER & length: 6 +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/11_describe_columns.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/11_describe_columns.mdx new file mode 100644 index 00000000000..906d63508e2 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/11_describe_columns.mdx @@ -0,0 +1,38 @@ +--- +title: "DESCRIBE_COLUMNS" +--- + +The `DESCRIBE_COLUMNS` procedure describes the columns returned by a cursor. + +```sql +DESCRIBE_COLUMNS( NUMBER, OUT NUMBER, OUT + DESC_TAB); +``` + +## Parameters + +`c` + + The cursor ID of the cursor. + +`col_cnt` + + The number of columns in the cursor result set. + +`desc_tab` + + The table that contains a description of each column returned by the cursor. The descriptions are of type `DESC_REC` and contain the following values: + +| Column name | Type | +| --------------------- | --------------- | +| `col_type` | `INTEGER` | +| `col_max_len` | `INTEGER` | +| `col_name` | `VARCHAR2(128)` | +| `col_name_len` | `INTEGER` | +| `col_schema_name` | `VARCHAR2(128)` | +| `col_schema_name_len` | `INTEGER` | +| `col_precision` | `INTEGER` | +| `col_scale` | `INTEGER` | +| `col_charsetid` | `INTEGER` | +| `col_charsetform` | `INTEGER` | +| `col_null_ok` | `BOOLEAN` | diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/12_execute.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/12_execute.mdx new file mode 100644 index 00000000000..27c676d0123 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/12_execute.mdx @@ -0,0 +1,38 @@ +--- +title: "EXECUTE" +--- + +The `EXECUTE` function executes a parsed SQL command or SPL block. + +```sql + INTEGER EXECUTE( NUMBER) +``` + +## Parameters + +`c` + + Cursor ID of the parsed SQL command or SPL block to execute. + +`status` + + Number of rows processed if the SQL command was `DELETE`, `INSERT`, or `UPDATE`. `status` is meaningless for all other commands. + +## Examples + +The following anonymous block inserts a row into the `dept` table. + +```sql +DECLARE + curid NUMBER; + v_sql VARCHAR2(50); + v_status INTEGER; +BEGIN + curid := DBMS_SQL.OPEN_CURSOR; + v_sql := 'INSERT INTO dept VALUES (50, ''HR'', ''LOS ANGELES'')'; + DBMS_SQL.PARSE(curid, v_sql, DBMS_SQL.native); + v_status := DBMS_SQL.EXECUTE(curid); + DBMS_OUTPUT.PUT_LINE('Number of rows processed: ' || v_status); + DBMS_SQL.CLOSE_CURSOR(curid); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/13_execute_and_fetch.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/13_execute_and_fetch.mdx new file mode 100644 index 00000000000..b09b45f83e7 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/13_execute_and_fetch.mdx @@ -0,0 +1,94 @@ +--- +title: "EXECUTE_AND_FETCH" +--- + +Function `EXECUTE_AND_FETCH` executes a parsed `SELECT` command and fetches one row. + +```sql + INTEGER EXECUTE_AND_FETCH( NUMBER [, BOOLEAN ]) +``` + +## Parameters + +`c` + + Cursor id of the cursor for the `SELECT` command to execute. + +`exact` + + If set to `TRUE`, an exception is thrown if the number of rows in the result set isn't exactly equal to 1. If set to `FALSE`, no exception is thrown. The default is `FALSE`. A `NO_DATA_FOUND` exception is thrown if `exact` is `TRUE` and there are no rows in the result set. A `TOO_MANY_ROWS` exception is thrown if `exact` is `TRUE` and more than one row is in the result set. + +`status` + + Returns `1` if a row was successfully fetched, `0` if no rows to fetch. If an exception is thrown, no value is returned. + +## Examples + +This stored procedure uses the `EXECUTE_AND_FETCH` function to retrieve one employee using the employee’s name. An exception is thrown if the employee isn't found or more than one employee has the same name. + +```sql +CREATE OR REPLACE PROCEDURE select_by_name( + p_ename emp.ename%TYPE +) +IS + curid NUMBER; + v_empno emp.empno%TYPE; + v_hiredate emp.hiredate%TYPE; + v_sal emp.sal%TYPE; + v_comm emp.comm%TYPE; + v_dname dept.dname%TYPE; + v_disp_date VARCHAR2(10); + v_sql VARCHAR2(120) := 'SELECT empno, hiredate, sal, ' || + 'NVL(comm, 0), dname ' || + 'FROM emp e, dept d ' || + 'WHERE ename = :p_ename ' || + 'AND e.deptno = d.deptno'; + v_status INTEGER; +BEGIN + curid := DBMS_SQL.OPEN_CURSOR; + DBMS_SQL.PARSE(curid,v_sql,DBMS_SQL.native); + DBMS_SQL.BIND_VARIABLE(curid,':p_ename',UPPER(p_ename)); + DBMS_SQL.DEFINE_COLUMN(curid,1,v_empno); + DBMS_SQL.DEFINE_COLUMN(curid,2,v_hiredate); + DBMS_SQL.DEFINE_COLUMN(curid,3,v_sal); + DBMS_SQL.DEFINE_COLUMN(curid,4,v_comm); + DBMS_SQL.DEFINE_COLUMN(curid,5,v_dname,14); + v_status := DBMS_SQL.EXECUTE_AND_FETCH(curid,TRUE); + DBMS_SQL.COLUMN_VALUE(curid,1,v_empno); + DBMS_SQL.COLUMN_VALUE(curid,2,v_hiredate); + DBMS_SQL.COLUMN_VALUE(curid,3,v_sal); + DBMS_SQL.COLUMN_VALUE(curid,4,v_comm); + DBMS_SQL.COLUMN_VALUE(curid,5,v_dname); + v_disp_date := TO_CHAR(v_hiredate, 'MM/DD/YYYY'); + DBMS_OUTPUT.PUT_LINE('Number : ' || v_empno); + DBMS_OUTPUT.PUT_LINE('Name : ' || UPPER(p_ename)); + DBMS_OUTPUT.PUT_LINE('Hire Date : ' || v_disp_date); + DBMS_OUTPUT.PUT_LINE('Salary : ' || v_sal); + DBMS_OUTPUT.PUT_LINE('Commission: ' || v_comm); + DBMS_OUTPUT.PUT_LINE('Department: ' || v_dname); + DBMS_SQL.CLOSE_CURSOR(curid); +EXCEPTION + WHEN NO_DATA_FOUND THEN + DBMS_OUTPUT.PUT_LINE('Employee ' || p_ename || ' not found'); + DBMS_SQL.CLOSE_CURSOR(curid); + WHEN TOO_MANY_ROWS THEN + DBMS_OUTPUT.PUT_LINE('Too many employees named, ' || + p_ename || ', found'); + DBMS_SQL.CLOSE_CURSOR(curid); + WHEN OTHERS THEN + DBMS_OUTPUT.PUT_LINE('The following is SQLERRM:'); + DBMS_OUTPUT.PUT_LINE(SQLERRM); + DBMS_OUTPUT.PUT_LINE('The following is SQLCODE:'); + DBMS_OUTPUT.PUT_LINE(SQLCODE); + DBMS_SQL.CLOSE_CURSOR(curid); +END; + +EXEC select_by_name('MARTIN') + +Number : 7654 +Name : MARTIN +Hire Date : 09/28/1981 +Salary : 1250 +Commission: 1400 +Department: SALES +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/14_fetch_rows.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/14_fetch_rows.mdx new file mode 100644 index 00000000000..54709b90a78 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/14_fetch_rows.mdx @@ -0,0 +1,82 @@ +--- +title: "FETCH_ROWS" +--- + +The `FETCH_ROWS` function retrieves a row from a cursor. + +```sql + INTEGER FETCH_ROWS( NUMBER) +``` + +## Parameters + +`c` + + Cursor ID of the cursor from which to fetch a row. + +`status` + + Returns `1` if a row was successfully fetched, `0` if no more rows to fetch. + +## Examples + +These examples fetch the rows from the `emp` table and display the results. + +```sql +DECLARE + curid NUMBER; + v_empno NUMBER(4); + v_ename VARCHAR2(10); + v_hiredate DATE; + v_sal NUMBER(7,2); + v_comm NUMBER(7,2); + v_sql VARCHAR2(50) := 'SELECT empno, ename, hiredate, sal, ' || + 'comm FROM emp'; + v_status INTEGER; +BEGIN + curid := DBMS_SQL.OPEN_CURSOR; + DBMS_SQL.PARSE(curid,v_sql,DBMS_SQL.native); + DBMS_SQL.DEFINE_COLUMN(curid,1,v_empno); + DBMS_SQL.DEFINE_COLUMN(curid,2,v_ename,10); + DBMS_SQL.DEFINE_COLUMN(curid,3,v_hiredate); + DBMS_SQL.DEFINE_COLUMN(curid,4,v_sal); + DBMS_SQL.DEFINE_COLUMN(curid,5,v_comm); + + v_status := DBMS_SQL.EXECUTE(curid); + DBMS_OUTPUT.PUT_LINE('EMPNO ENAME HIREDATE SAL COMM'); + DBMS_OUTPUT.PUT_LINE('----- ---------- ---------- -------- ' || + '--------'); + LOOP + v_status := DBMS_SQL.FETCH_ROWS(curid); + EXIT WHEN v_status = 0; + DBMS_SQL.COLUMN_VALUE(curid,1,v_empno); + DBMS_SQL.COLUMN_VALUE(curid,2,v_ename); + DBMS_SQL.COLUMN_VALUE(curid,3,v_hiredate); + DBMS_SQL.COLUMN_VALUE(curid,4,v_sal); + DBMS_SQL.COLUMN_VALUE(curid,4,v_sal); + DBMS_SQL.COLUMN_VALUE(curid,5,v_comm); + DBMS_OUTPUT.PUT_LINE(v_empno || ' ' || RPAD(v_ename,10) || ' ' || + TO_CHAR(v_hiredate,'yyyy-mm-dd') || ' ' || + TO_CHAR(v_sal,'9,999.99') || ' ' || + TO_CHAR(NVL(v_comm,0),'9,999.99')); + END LOOP; + DBMS_SQL.CLOSE_CURSOR(curid); +END; + +EMPNO ENAME HIREDATE SAL COMM +----- ---------- ---------- -------- -------- +7369 SMITH 1980-12-17 800.00 .00 +7499 ALLEN 1981-02-20 1,600.00 300.00 +7521 WARD 1981-02-22 1,250.00 500.00 +7566 JONES 1981-04-02 2,975.00 .00 +7654 MARTIN 1981-09-28 1,250.00 1,400.00 +7698 BLAKE 1981-05-01 2,850.00 .00 +7782 CLARK 1981-06-09 2,450.00 .00 +7788 SCOTT 1987-04-19 3,000.00 .00 +7839 KING 1981-11-17 5,000.00 .00 +7844 TURNER 1981-09-08 1,500.00 .00 +7876 ADAMS 1987-05-23 1,100.00 .00 +7900 JAMES 1981-12-03 950.00 .00 +7902 FORD 1981-12-03 3,000.00 .00 +7934 MILLER 1982-01-23 1,300.00 .00 +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/15_is_open.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/15_is_open.mdx new file mode 100644 index 00000000000..fd15620abd8 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/15_is_open.mdx @@ -0,0 +1,19 @@ +--- +title: "IS_OPEN" +--- + +The `IS_OPEN` function tests whether the given cursor is open. + +```sql + BOOLEAN IS_OPEN( NUMBER) +``` + +## Parameters + +`c` + + Cursor ID of the cursor to test. + +`status` + + Set to `TRUE` if the cursor is open, set to `FALSE` if the cursor isn't open. diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/16_last_row_count.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/16_last_row_count.mdx new file mode 100644 index 00000000000..3be5b15a342 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/16_last_row_count.mdx @@ -0,0 +1,109 @@ +--- +title: "LAST_ROW_COUNT" +--- + +The `LAST_ROW_COUNT` function returns the number of rows that were currently fetched. + +```sql + INTEGER LAST_ROW_COUNT +``` + +## Parameters + +`rowcnt` + + Number of row fetched thus far. + +## Examples + +This example uses the `LAST_ROW_COUNT` function to display the total number of rows fetched in the query. + +```sql +DECLARE + curid NUMBER; + v_empno NUMBER(4); + v_ename VARCHAR2(10); + v_hiredate DATE; + v_sal NUMBER(7,2); + v_comm NUMBER(7,2); + v_sql VARCHAR2(50) := 'SELECT empno, ename, hiredate, sal, ' || + 'comm FROM emp'; + v_status INTEGER; +BEGIN + curid := DBMS_SQL.OPEN_CURSOR; + DBMS_SQL.PARSE(curid,v_sql,DBMS_SQL.native); + DBMS_SQL.DEFINE_COLUMN(curid,1,v_empno); + DBMS_SQL.DEFINE_COLUMN(curid,2,v_ename,10); + DBMS_SQL.DEFINE_COLUMN(curid,3,v_hiredate); + DBMS_SQL.DEFINE_COLUMN(curid,4,v_sal); + DBMS_SQL.DEFINE_COLUMN(curid,5,v_comm); + + v_status := DBMS_SQL.EXECUTE(curid); + DBMS_OUTPUT.PUT_LINE('EMPNO ENAME HIREDATE SAL COMM'); + DBMS_OUTPUT.PUT_LINE('----- ---------- ---------- -------- ' || + '--------'); + LOOP + v_status := DBMS_SQL.FETCH_ROWS(curid); + EXIT WHEN v_status = 0; + DBMS_SQL.COLUMN_VALUE(curid,1,v_empno); + DBMS_SQL.COLUMN_VALUE(curid,2,v_ename); + DBMS_SQL.COLUMN_VALUE(curid,3,v_hiredate); + DBMS_SQL.COLUMN_VALUE(curid,4,v_sal); + DBMS_SQL.COLUMN_VALUE(curid,4,v_sal); + DBMS_SQL.COLUMN_VALUE(curid,5,v_comm); + DBMS_OUTPUT.PUT_LINE(v_empno || ' ' || RPAD(v_ename,10) || ' ' || + TO_CHAR(v_hiredate,'yyyy-mm-dd') || ' ' || + TO_CHAR(v_sal,'9,999.99') || ' ' || + TO_CHAR(NVL(v_comm,0),'9,999.99')); + END LOOP; + DBMS_OUTPUT.PUT_LINE('Number of rows: ' || DBMS_SQL.LAST_ROW_COUNT); + DBMS_SQL.CLOSE_CURSOR(curid); +END; + +EMPNO ENAME HIREDATE SAL COMM +----- ---------- ---------- -------- -------- +7369 SMITH 1980-12-17 800.00 .00 +7499 ALLEN 1981-02-20 1,600.00 300.00 +7521 WARD 1981-02-22 1,250.00 500.00 +7566 JONES 1981-04-02 2,975.00 .00 +7654 MARTIN 1981-09-28 1,250.00 1,400.00 +7698 BLAKE 1981-05-01 2,850.00 .00 +7782 CLARK 1981-06-09 2,450.00 .00 +7788 SCOTT 1987-04-19 3,000.00 .00 +7839 KING 1981-11-17 5,000.00 .00 +7844 TURNER 1981-09-08 1,500.00 .00 +7876 ADAMS 1987-05-23 1,100.00 .00 +7900 JAMES 1981-12-03 950.00 .00 +7902 FORD 1981-12-03 3,000.00 .00 +7934 MILLER 1982-01-23 1,300.00 .00 +Number of rows: 14 +``` + +## LAST_ERROR_POSITION + +The `LAST_ERROR_POSITION` function returns an integer value indicating the byte offset in the SQL statement text where the error occurred. The error position of the first character in the SQL statement is at `1`. + +```sql +LAST_ERROR_POSITION RETURN INTEGER; +``` + +### Examples + +This example shows an anonymous block that returns an error position with the `LAST_ERROR_POSITION` function. + +```sql +DECLARE + curid NUMBER; + sql_stmt VARCHAR2(50) := 'SELECT empno FROM not_exist_table'; + v_position INTEGER; +BEGIN + curid := DBMS_SQL.OPEN_CURSOR; + DBMS_SQL.PARSE(curid, sql_stmt, DBMS_SQL.native); +EXCEPTION WHEN OTHERS THEN + v_position := DBMS_SQL.LAST_ERROR_POSITION; + DBMS_OUTPUT.PUT_LINE('error position = ' || v_position); + DBMS_SQL.CLOSE_CURSOR(curid); +END; + +error position = 19 +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/17_open_cursor.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/17_open_cursor.mdx new file mode 100644 index 00000000000..51eb3323043 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/17_open_cursor.mdx @@ -0,0 +1,34 @@ +--- +title: "OPEN_CURSOR" +--- + +The `OPEN_CURSOR` function creates a cursor. A cursor must be used to parse and execute any dynamic SQL statement. Once a cursor is open, you can reuse it with the same or different SQL statements. You don't have to close the cursor and reopen it to reuse it. + +```sql + INTEGER OPEN_CURSOR +``` + +## Parameters + +`c` + + Cursor ID number associated with the newly created cursor. + +## Examples + +This example creates a new cursor: + +```sql +DECLARE + curid NUMBER; + v_sql VARCHAR2(150); + v_status INTEGER; +BEGIN + v_sql:='INSERT INTO dept VALUES (50,''HR'',''LOS ANGELES'')'; + curid := DBMS_SQL.OPEN_CURSOR; + DBMS_SQL.PARSE(curid,v_sql,DBMS_SQL.native); + v_status := DBMS_SQL.EXECUTE(curid); + DBMS_OUTPUT.PUT_LINE('Number of rows processed: ' || v_status); + DBMS_SQL.CLOSE_CURSOR(curid); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/18_parse.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/18_parse.mdx new file mode 100644 index 00000000000..40430db45ad --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/18_parse.mdx @@ -0,0 +1,81 @@ +--- +title: "PARSE" +--- + +The `PARSE` procedure parses a SQL command or SPL block. If the SQL command is a DDL command, it executes immediately and doesn't require that you run the `EXECUTE` function. + +```sql +PARSE( NUMBER, VARCHAR2, NUMBER) +``` + +## Parameters + +`c` + + Cursor ID of an open cursor. + +`statement` + + SQL command or SPL block to parse. A SQL command must not end with the semi-colon terminator. However an SPL block does require the semi-colon terminator. + +`language_flag` + + Language flag provided for compatibility with Oracle syntax. Use `DBMS_SQL.V6`, `DBMS_SQL.V7` or `DBMS_SQL.native`. This flag is ignored, and all syntax is assumed to be in EDB EDB Postgres Advanced Server form. + +## Examples + +This anonymous block creates a table named, `job`. DDL statements are executed immediately by the `PARSE` procedure and don't require a separate `EXECUTE` step. + +```sql +DECLARE + curid NUMBER; +BEGIN + curid := DBMS_SQL.OPEN_CURSOR; + DBMS_SQL.PARSE(curid, 'CREATE TABLE job (jobno NUMBER(3), ' || + 'jname VARCHAR2(9))',DBMS_SQL.native); + DBMS_SQL.CLOSE_CURSOR(curid); +END; +``` + +The following inserts two rows into the `job` table. + +```sql +DECLARE + curid NUMBER; + v_sql VARCHAR2(50); + v_status INTEGER; +BEGIN + curid := DBMS_SQL.OPEN_CURSOR; + v_sql := 'INSERT INTO job VALUES (100, ''ANALYST'')'; + DBMS_SQL.PARSE(curid, v_sql, DBMS_SQL.native); + v_status := DBMS_SQL.EXECUTE(curid); + DBMS_OUTPUT.PUT_LINE('Number of rows processed: ' || v_status); + v_sql := 'INSERT INTO job VALUES (200, ''CLERK'')'; + DBMS_SQL.PARSE(curid, v_sql, DBMS_SQL.native); + v_status := DBMS_SQL.EXECUTE(curid); + DBMS_OUTPUT.PUT_LINE('Number of rows processed: ' || v_status); + DBMS_SQL.CLOSE_CURSOR(curid); +END; + +Number of rows processed: 1 +Number of rows processed: 1 +``` + +This anonymous block uses the `DBMS_SQL` package to execute a block containing two `INSERT` statements. The end of the block contains a terminating semi-colon. In the prior example, each `INSERT` statement doesn't have a terminating semi-colon. + +```sql +DECLARE + curid NUMBER; + v_sql VARCHAR2(100); + v_status INTEGER; +BEGIN + curid := DBMS_SQL.OPEN_CURSOR; + v_sql := 'BEGIN ' || + 'INSERT INTO job VALUES (300, ''MANAGER''); ' || + 'INSERT INTO job VALUES (400, ''SALESMAN''); ' || + 'END;'; + DBMS_SQL.PARSE(curid, v_sql, DBMS_SQL.native); + v_status := DBMS_SQL.EXECUTE(curid); + DBMS_SQL.CLOSE_CURSOR(curid); +END; +``` diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/index.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/index.mdx new file mode 100644 index 00000000000..ef1179d7b41 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/index.mdx @@ -0,0 +1,53 @@ +--- +title: "DBMS_SQL" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.30.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.203.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.161.html" +--- + +The `DBMS_SQL` package provides an application interface compatible with Oracle databases to the EDB dynamic SQL functionality. With `DBMS_SQL` you can construct queries and other commands at runtime rather than when you write the application. EDB Postgres Advanced Server offers native support for dynamic SQL. `DBMS_SQL` provides a way to use dynamic SQL in a way that's compatible with Oracle databases without modifying your application. + +`DBMS_SQL` assumes the privileges of the current user when executing dynamic SQL statements. + +EDB Postgres Advanced Server's implementation of `DBMS_SQL` is a partial implementation when compared to Oracle's version. Only those functions and procedures listed in the table are supported. + +| Function/procedure | Function or procedure | Return type | Description | +| --------------------------------------------------------------------------------------- | --------------------- | ----------- | ---------------------------------------------------------------------- | +| `BIND_VARIABLE(c, name, value [, out_value_size ])` | Procedure | n/a | Bind a value to a variable. | +| `BIND_VARIABLE_CHAR(c, name, value [, out_value_size ])` | Procedure | n/a | Bind a `CHAR` value to a variable. | +| `BIND_VARIABLE_RAW(c, name, value [, out_value_size ])` | Procedure | n/a | Bind a `RAW` value to a variable. | +| `CLOSE_CURSOR(c IN OUT)` | Procedure | n/a | Close a cursor. | +| `COLUMN_VALUE(c, position, value OUT [, column_error OUT [, actual_length OUT ]])` | Procedure | n/a | Return a column value into a variable. | +| `COLUMN_VALUE_CHAR(c, position, value OUT [, column_error OUT [, actual_length OUT ]])` | Procedure | n/a | Return a `CHAR` column value into a variable. | +| `COLUMN_VALUE_RAW(c, position, value OUT [, column_error OUT [, actual_length OUT ]])` | Procedure | n/a | Return a `RAW` column value into a variable. | +| `COLUMN_VALUE_LONG(c, position, length, offset, value OUT, value_length OUT` | Procedure | n/a | Return a part of the `LONG` column value into a variable. | +| `DEFINE_COLUMN(c, position, column [, column_size ])` | Procedure | n/a | Define a column in the `SELECT` list. | +| `DEFINE_COLUMN_CHAR(c, position, column, column_size)` | Procedure | n/a | Define a `CHAR` column in the `SELECT` list. | +| `DEFINE_COLUMN_RAW(c, position, column, column_size)` | Procedure | n/a | Define a `RAW` column in the `SELECT` list. | +| `DEFINE_COLUMN_LONG(c, position)` | Procedure | n/a | Define a `LONG` column in the `SELECT` list. | +| `DESCRIBE_COLUMNS` | Procedure | n/a | Define columns to hold a cursor result set. | +| `EXECUTE(c)` | Function | `INTEGER` | Execute a cursor. | +| `EXECUTE_AND_FETCH(c [, exact ])` | Function | `INTEGER` | Execute a cursor and fetch a single row. | +| `FETCH_ROWS(c)` | Function | `INTEGER` | Fetch rows from the cursor. | +| `IS_OPEN(c)` | Function | `BOOLEAN` | Check if a cursor is open. | +| `LAST_ROW_COUNT` | Function | `INTEGER` | Return cumulative number of rows fetched. | +| `LAST_ERROR_POSITION` | Function | `INTEGER` | Return byte offset in the SQL statement text where the error occurred. | +| `OPEN_CURSOR` | Function | `INTEGER` | Open a cursor. | +| `PARSE(c, statement, language_flag)` | Procedure | n/a | Parse a statement. | + + +The following table lists the public variables available in the `DBMS_SQL` package. + +| Public variables | Data type | Value | Description | +| ---------------- | --------- | ----- | ----------------------------------------------------------------------------------------- | +| `native` | `INTEGER` | `1` | Provided for compatibility with Oracle syntax. See `DBMS_SQL.PARSE` for more information. | +| `V6` | `INTEGER` | `2` | Provided for compatibility with Oracle syntax. See `DBMS_SQL.PARSE` for more information. | +| `V7` | `INTEGER` | `3` | Provided for compatibility with Oracle syntax. See `DBMS_SQL.PARSE` for more information | + +
+ +bind_variable bind_variable_char bind_variable_raw close_cursor column_value column_value_char column_value_raw define_column define_column_char define_column_raw describe_columns execute execute_and_fetch fetch_rows is_open last_row_count open_cursor parse + +
diff --git a/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/18_dbms_utility.mdx b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/18_dbms_utility.mdx new file mode 100644 index 00000000000..0b17b861698 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_bip_guide/03_built-in_packages/18_dbms_utility.mdx @@ -0,0 +1,815 @@ +--- +title: "DBMS_UTILITY" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-built-in-package-guide/9.6/Database_Compatibility_for_Oracle_Developers_Built-in_Package_Guide.1.31.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/database-compatibility-for-oracle-developers-guide/9.5/Database_Compatibility_for_Oracle_Developers_Guide.1.204.html" + - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.162.html" +--- + +The `DBMS_UTILITY` package provides support for the following utility programs. EDB Postgres Advanced Server's implementation of `DBMS_UTILITY` is a partial implementation when compared to Oracle's version. Only the functions and procedures listed in the table are supported. + +| Function/procedure | Function or procedure | Return type | Description | +| -------------------------------------------------------------------------------------------------------------- | --------------------- | ---------------- | ------------------------------------------------------------ | +| `ANALYZE_DATABASE(method [, estimate_rows [, estimate_percent [, method_opt ]]])` | Procedure | n/a | Analyze database tables. | +| `ANALYZE_PART_OBJECT(schema, object_name [, object_type [, command_type [, command_opt [, sample_clause ]]]])` | Procedure | n/a | Analyze a partitioned table. | +| `ANALYZE_SCHEMA(schema, method [, estimate_rows [, estimate_percent [, method_opt ]]])` | Procedure | n/a | Analyze schema tables. | +| `CANONICALIZE(name, canon_name OUT, canon_len)` | Procedure | n/a | Canonicalize a string, e.g., strip off white space. | +| `COMMA_TO_TABLE(list, tablen OUT, tab OUT)` | Procedure | n/a | Convert a comma-delimited list of names to a table of names. | +| `DB_VERSION(version OUT, compatibility OUT)` | Procedure | n/a | Get the database version. | +| `EXEC_DDL_STATEMENT (parse_string)` | Procedure | n/a | Execute a DDL statement. | +| `FORMAT_CALL_STACK` | Function | `TEXT` | Formats the current call stack. | +| `FORMAT_ERROR_BACKTRACE` | Function | `TEXT` | Formats the current error call backtrace. | +| `FORMAT_ERROR_STACK` | Function | `TEXT` | Get the exception name. | +| `GET_CPU_TIME` | Function | `NUMBER` | Get the current CPU time. | +| `GET_DEPENDENCY(type, schema, name)` | Procedure | n/a | Get objects that depend on the given object. | +| `GET_HASH_VALUE(name, base, hash_size)` | Function | `NUMBER` | Compute a hash value. | +| `GET_PARAMETER_VALUE(parnam, intval OUT, strval OUT)` | Procedure | `BINARY_INTEGER` | Get database initialization parameter settings. | +| `GET_TIME` | Function | `NUMBER` | Get the current time. | +| `NAME_TOKENIZE(name, a OUT, b OUT, c OUT, dblink OUT, nextpos OUT)` | Procedure | n/a | Parse the given name into its component parts. | +| `TABLE_TO_COMMA(tab, tablen OUT, list OUT)` | Procedure | n/a | Convert a table of names to a comma-delimited list. | + +The following table lists the public variables available in the `DBMS_UTILITY` package. + +| Public variables | Data type | Value | Description | +| --------------------------- | ------------- | ----- | ----------------------------------- | +| `inv_error_on_restrictions` | `PLS_INTEGER` | `1` | Used by the `INVALIDATE` procedure. | +| `lname_array` | `TABLE` | | For lists of long names. | +| `uncl_array` | `TABLE` | | For lists of users and names. | + + + +## LNAME_ARRAY + +The `LNAME_ARRAY` is for storing lists of long names including fully qualified names. + +```sql +TYPE lname_array IS TABLE OF VARCHAR2(4000) INDEX BY BINARY_INTEGER; +``` + + + +## UNCL_ARRAY + +The `UNCL_ARRAY` is for storing lists of users and names. + +```sql +TYPE uncl_array IS TABLE OF VARCHAR2(227) INDEX BY BINARY_INTEGER; +``` + +## ANALYZE_DATABASE, ANALYZE SCHEMA and ANALYZE PART_OBJECT + +The `ANALYZE_DATABASE(), ANALYZE_SCHEMA() and ANALYZE_PART_OBJECT()` procedures gather statistics on tables in the database. When you execute the `ANALYZE` statement, Postgres samples the data in a table and records distribution statistics in the `pg_statistics system` table. + +`ANALYZE_DATABASE`, `ANALYZE_SCHEMA`, and `ANALYZE_PART_OBJECT` differ primarily in the number of tables that are processed: + +- `ANALYZE_DATABASE` analyzes all tables in all schemas in the current database. +- `ANALYZE_SCHEMA` analyzes all tables in a given schema (in the current database). +- `ANALYZE_PART_OBJECT` analyzes a single table. + +The syntax for the `ANALYZE` commands are: + +```sql +ANALYZE_DATABASE( VARCHAR2 [, NUMBER + [, NUMBER [, VARCHAR2 ]]]) + +ANALYZE_SCHEMA( VARCHAR2, VARCHAR2 + [, NUMBER [, NUMBER + [, VARCHAR2 ]]]) + +ANALYZE_PART_OBJECT( VARCHAR2, VARCHAR2 + [, CHAR [, CHAR + [, VARCHAR2 [, ]]]]) +``` + +### Parameters for `ANALYZE_DATABASE` and `ANALYZE_SCHEMA` + +`method` + + Determines whether the `ANALYZE` procedure populates the `pg_statistics` table or removes entries from the `pg_statistics` table. If you specify a method of `DELETE`, the `ANALYZE` procedure removes the relevant rows from `pg_statistics`. If you specify a method of `COMPUTE` or `ESTIMATE`, the `ANALYZE` procedure analyzes a table (or multiple tables) and records the distribution information in `pg_statistics`. There's no difference between `COMPUTE` and `ESTIMATE`. Both methods execute the Postgres `ANALYZE` statement. All other parameters are validated and then ignored. + +`estimate_rows` + + Number of rows upon which to base estimated statistics. One of `estimate_rows` or `estimate_percent` must be specified if the method is `ESTIMATE`. + + This argument is ignored but is included for compatibility. + +`estimate_percent` + + Percentage of rows upon which to base estimated statistics. One of `estimate_rows` or `estimate_percent` must be specified if the method is `ESTIMATE`. + + This argument is ignored but is included for compatibility. + +`method_opt` + + Object types to analyze. Any combination of the following: + +```text +[ FOR TABLE ] + +[ FOR ALL [ INDEXED ] COLUMNS ] [ SIZE n ] + +[ FOR ALL INDEXES ] +``` + + This argument is ignored but is included for compatibility. + +### Parameters for `ANALYZE_PART_OBJECT` + +`schema` + + Name of the schema whose objects to analyze. + +`object_name` + + Name of the partitioned object to analyze. + +`object_type` + + Type of object to analyze. Valid values are: `T` – table, `I` – index. + + This argument is ignored but is included for compatibility. + +`command_type` + + Type of analyze functionality to perform. Valid values are: + - `E` — Gather estimated statistics based on a specified number of rows or a percentage of rows in the `sample_clause` clause. + - `C` — Compute exact statistics. + - `V` — Validate the structure and integrity of the partitions. + + This argument is ignored but is included for compatibility. + +`command_opt` + + For `command_type` `C` or `E`, can be any combination of: + +```text +[ FOR TABLE ] + +[ FOR ALL COLUMNS ] + +[ FOR ALL LOCAL INDEXES ] +``` + + For `command_type V`, can be `CASCADE` if `object_type` is `T`. + + This argument is ignored but is included for compatibility. + +`sample_clause` + + If `command_type` is `E`, contains the following clause to specify the number of rows or percentage of rows on which to base the estimate. + + `SAMPLE n { ROWS | PERCENT }` + + This argument is ignored but is included for compatibility. + +## CANONICALIZE + +The `CANONICALIZE` procedure performs the following operations on an input string: + +- If the string isn't double quoted, verifies that it uses the characters of a legal identifier. If not, an exception is thrown. If the string is double quoted, all characters are allowed. +- If the string isn't double quoted and doesn't contain periods, uppercases all alphabetic characters and eliminates leading and trailing spaces. +- If the string is double quoted and doesn't contain periods, strips off the double quotes. +- If the string contains periods and no portion of the string is double quoted, uppercases each portion of the string and encloses each portion in double quotes. +- If the string contains periods and portions of the string are double quoted, returns: + - The double-quoted portions unchanged, including the double quotes + - The non-double-quoted portions uppercased and enclosed in double quotes. + +```sql +CANONICALIZE( VARCHAR2, OUT VARCHAR2, + BINARY_INTEGER) +``` + +### Parameters + +`name` + + String to canonicalize. + +`canon_name` + + The canonicalized string. + +`canon_len` + + Number of bytes in `name` to canonicalize starting from the first character. + +### Examples + +This procedure applies the `CANONICALIZE` procedure on its input parameter and displays the results. + +```sql +CREATE OR REPLACE PROCEDURE canonicalize ( + p_name VARCHAR2, + p_length BINARY_INTEGER DEFAULT 30 +) +IS + v_canon VARCHAR2(100); +BEGIN + DBMS_UTILITY.CANONICALIZE(p_name,v_canon,p_length); + DBMS_OUTPUT.PUT_LINE('Canonicalized name ==>' || v_canon || '<=='); + DBMS_OUTPUT.PUT_LINE('Length: ' || LENGTH(v_canon)); +EXCEPTION + WHEN OTHERS THEN + DBMS_OUTPUT.PUT_LINE('SQLERRM: ' || SQLERRM); + DBMS_OUTPUT.PUT_LINE('SQLCODE: ' || SQLCODE); +END; + +EXEC canonicalize('Identifier') +Canonicalized name ==>IDENTIFIER<== +Length: 10 + +EXEC canonicalize('"Identifier"') +Canonicalized name ==>Identifier<== +Length: 10 + +EXEC canonicalize('"_+142%"') +Canonicalized name ==>_+142%<== +Length: 6 + +EXEC canonicalize('abc.def.ghi') +Canonicalized name ==>"ABC"."DEF"."GHI"<== +Length: 17 + +EXEC canonicalize('"abc.def.ghi"') +Canonicalized name ==>abc.def.ghi<== +Length: 11 + +EXEC canonicalize('"abc".def."ghi"') +Canonicalized name ==>"abc"."DEF"."ghi"<== +Length: 17 + +EXEC canonicalize('"abc.def".ghi') +Canonicalized name ==>"abc.def"."GHI"<== +Length: 15 +``` + +## COMMA_TO_TABLE + +The `COMMA_TO_TABLE` procedure converts a comma-delimited list of names into a table of names. Each entry in the list becomes a table entry. Format the names as valid identifiers. + +```sql +COMMA_TO_TABLE( VARCHAR2, OUT BINARY_INTEGER, + OUT { LNAME_ARRAY | UNCL_ARRAY }) +``` + +### Parameters + +`list` + + Comma-delimited list of names. + +`tablen` + + Number of entries in `tab`. + +`tab` + + Table containing the individual names in `list`. + +`LNAME_ARRAY` + + A `DBMS_UTILITY LNAME_ARRAY`, as described in [LNAME_ARRAY](#lname_array). + +`UNCL_ARRAY` + + A `DBMS_UTILITY UNCL_ARRAY`, as described in [UNCL_ARRAY](#uncl_array). + +### Examples + +This procedure uses the `COMMA_TO_TABLE` procedure to convert a list of names to a table. It then displays the table entries. + +```sql +CREATE OR REPLACE PROCEDURE comma_to_table ( + p_list VARCHAR2 +) +IS + r_lname DBMS_UTILITY.LNAME_ARRAY; + v_length BINARY_INTEGER; +BEGIN + DBMS_UTILITY.COMMA_TO_TABLE(p_list,v_length,r_lname); + FOR i IN 1..v_length LOOP + DBMS_OUTPUT.PUT_LINE(r_lname(i)); + END LOOP; +END; + +EXEC comma_to_table('edb.dept, edb.emp, edb.jobhist') + +edb.dept +edb.emp +edb.jobhist +``` + +## DB_VERSION + +The `DB_VERSION` procedure returns the version number of the database. + +```sql +DB_VERSION( OUT VARCHAR2, OUT VARCHAR2) +``` + +### Parameters + +`version` + + Database version number. + +`compatibility` + + Compatibility setting of the database (to be implementation-defined as to its meaning). + +### Examples + +The following anonymous block displays the database version information. + +```sql +DECLARE + v_version VARCHAR2(150); + v_compat VARCHAR2(150); +BEGIN + DBMS_UTILITY.DB_VERSION(v_version,v_compat); + DBMS_OUTPUT.PUT_LINE('Version: ' || v_version); + DBMS_OUTPUT.PUT_LINE('Compatibility: ' || v_compat); +END; + +Version: EnterpriseDB 14.0.0 on i686-pc-linux-gnu, compiled by GCC gcc +(GCC) 4.1.2 20080704 (Red Hat 4.1.2-48), 32-bit +Compatibility: EnterpriseDB 14.0.0 on i686-pc-linux-gnu, compiled by GCC +gcc (GCC) 4.1.220080704 (Red Hat 4.1.2-48), 32-bit +``` + +## EXEC_DDL_STATEMENT + +`EXEC_DDL_STATEMENT` executes a `DDL` command. + +```sql +EXEC_DDL_STATEMENT( VARCHAR2) +``` + +### Parameters + +`parse_string` + + The DDL command to execute. + +### Examples + +The following anonymous block creates the `job` table. + +```sql +BEGIN + DBMS_UTILITY.EXEC_DDL_STATEMENT( + 'CREATE TABLE job (' || + 'jobno NUMBER(3),' || + 'jname VARCHAR2(9))' + ); +END; +``` + +If the `parse_string` doesn't include a valid DDL statement, EDB Postgres Advanced Server returns an error: + +```sql +edb=#  exec dbms_utility.exec_ddl_statement('select rownum from dual'); +ERROR:  EDB-20001: 'parse_string' must be a valid DDL statement +``` + +In this case, EDB Postgres Advanced Server's behavior differs from Oracle's. Oracle accepts the invalid `parse_string` without complaint. + +## FORMAT_CALL_STACK + +The `FORMAT_CALL_STACK` function returns the formatted contents of the current call stack. + +```sql +DBMS_UTILITY.FORMAT_CALL_STACK +return VARCHAR2 +``` + +You can use this function in a stored procedure, function, or package to return the current call stack in a readable format. This function is useful for debugging. + +## FORMAT_ERROR_BACKTRACE + +The `FORMAT_ERROR_BACKTRACE` function returns the current error call stack, that is, function name and lines that lead up to the exception. + +```sql +DBMS_UTILITY.FORMAT_ERROR_BACKTRACE +return VARCHAR2 +``` + +You can use this function in a stored procedure, function, or package to return the current error call backtrace in a readable format. This function is useful for debugging. + +## FORMAT_ERROR_STACK + +The `FORMAT_ERROR_STACK` function returns the current exception name. + +```sql +DBMS_UTILITY.FORMAT_ERROR_STACK +return VARCHAR2 +``` + +You can use this function in a stored procedure, function, or package to return the current exception name. This function is useful for debugging. + +!!! Note + The output of the functions `FORMAT_ERROR_STACK` and `FORMAT_ERROR_BACKTRACE` is partially compatible with Oracle. However, it eases the migration from Oracle to EPAS. + +## GET_CPU_TIME + +The `GET_CPU_TIME` function returns the CPU time in hundredths of a second from some arbitrary point in time. + +```sql + NUMBER GET_CPU_TIME +``` + +### Parameters + +`cputime` + + Number of hundredths of a second of CPU time. + +### Examples + +This `SELECT` command retrieves the current CPU time, which is 603 hundredths of a second or .0603 seconds. + +```sql +SELECT DBMS_UTILITY.GET_CPU_TIME FROM DUAL; +__OUTPUT__ +get_cpu_time +-------------- + 603 +``` + +## GET_DEPENDENCY + +The `GET_DEPENDENCY` procedure lists the objects that depend on the specified object. `GET_DEPENDENCY` doesn't show dependencies for functions or procedures. + +```sql +GET_DEPENDENCY( VARCHAR2, VARCHAR2, + VARCHAR2) +``` + +### Parameters + +`type` + + The object type of `name`. Valid values are `INDEX`, `PACKAGE`, `PACKAGE BODY`, `SEQUENCE`, `TABLE`, `TRIGGER`, `TYPE`, and `VIEW`. + +`schema` + + Name of the schema in which `name` exists. + +`name` + + Name of the object for which to obtain dependencies. + +### Examples + +The following anonymous block finds dependencies on the `EMP` table: + +```sql +BEGIN + DBMS_UTILITY.GET_DEPENDENCY('TABLE','public','EMP'); +END; +__OUTPUT__ +DEPENDENCIES ON public.EMP +------------------------------------------------------------------ +*TABLE public.EMP() +* CONSTRAINT c public.emp() +* CONSTRAINT f public.emp() +* CONSTRAINT p public.emp() +* TYPE public.emp() +* CONSTRAINT c public.emp() +* CONSTRAINT f public.jobhist() +* VIEW .empname_view() +``` + +## GET_HASH_VALUE + +The `GET_HASH_VALUE` function computes a hash value for a given string. + +```sql + NUMBER GET_HASH_VALUE( VARCHAR2, NUMBER, + NUMBER) +``` + +### Parameters + +`name` + + The string for which to compute a hash value. + +`base` + + Starting value at which to generate hash values. + +`hash_size` + + The number of hash values for the desired hash table. + +`hash` + + The generated hash value. + +### Examples + +The following anonymous block creates a table of hash values using the `ename` column of the `emp` table and then displays the key along with the hash value. The hash values start at 100 with a maximum of 1024 distinct values. + +```sql +DECLARE + v_hash NUMBER; + TYPE hash_tab IS TABLE OF NUMBER INDEX BY VARCHAR2(10); + r_hash HASH_TAB; + CURSOR emp_cur IS SELECT ename FROM emp; +BEGIN + FOR r_emp IN emp_cur LOOP + r_hash(r_emp.ename) := + DBMS_UTILITY.GET_HASH_VALUE(r_emp.ename,100,1024); + END LOOP; + FOR r_emp IN emp_cur LOOP + DBMS_OUTPUT.PUT_LINE(RPAD(r_emp.ename,10) || ' ' || + r_hash(r_emp.ename)); + END LOOP; +END; + +SMITH 377 +ALLEN 740 +WARD 718 +JONES 131 +MARTIN 176 +BLAKE 568 +CLARK 621 +SCOTT 1097 +KING 235 +TURNER 850 +ADAMS 156 +JAMES 942 +FORD 775 +MILLER 148 +``` + +## GET_PARAMETER_VALUE + +The `GET_PARAMETER_VALUE` procedure retrieves database initialization parameter settings. + +```sql + BINARY_INTEGER GET_PARAMETER_VALUE( VARCHAR2, + OUT INTEGER, OUT VARCHAR2) +``` + +### Parameters + +`parnam` + + Name of the parameter whose value to return. The parameters are listed in the `pg_settings` system view. + +`intval` + + Value of an integer parameter or the length of `strval`. + +`strval` + + Value of a string parameter. + +`status` + + Returns `0` if the parameter value is `INTEGER` or `BOOLEAN`. Returns `1` if the parameter value is a string. + +### Examples + +The following anonymous block shows the values of two initialization parameters. + +```sql +DECLARE + v_intval INTEGER; + v_strval VARCHAR2(80); +BEGIN + DBMS_UTILITY.GET_PARAMETER_VALUE('max_fsm_pages', v_intval, v_strval); + DBMS_OUTPUT.PUT_LINE('max_fsm_pages' || ': ' || v_intval); + DBMS_UTILITY.GET_PARAMETER_VALUE('client_encoding', v_intval, v_strval); + DBMS_OUTPUT.PUT_LINE('client_encoding' || ': ' || v_strval); +END; + +max_fsm_pages: 72625 +client_encoding: SQL_ASCII +``` + +## GET_TIME + +The `GET_TIME` function returns the current time in hundredths of a second. + +```sql +