diff --git a/product_docs/docs/epas/14/ecpgplus_guide/02_overview.mdx b/product_docs/docs/epas/14/ecpgplus_guide/02_overview.mdx index bbfe5731ec4..483088149ae 100644 --- a/product_docs/docs/epas/14/ecpgplus_guide/02_overview.mdx +++ b/product_docs/docs/epas/14/ecpgplus_guide/02_overview.mdx @@ -10,21 +10,25 @@ legacyRedirectsGenerated: -EDB has enhanced ECPG (the PostgreSQL pre-compiler) to create ECPGPlus. ECPGPlus is a Pro\*C-compatible version of the PostgreSQL C pre-compiler. 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. +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 is compiled into an executable: +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, pass the program (`my_program.pgc` in the diagram above) to the ECPGPlus pre-compiler. 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`). Then, pass the C program to a C compiler; the C compiler generates an object file (`my_program.o`). Finally, 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`). +To produce an executable from a C program that contains embedded SQL statements: -While the ECPGPlus preprocessor validates the *syntax* of each SQL statement, it cannot validate the *semantics*. For example, the preprocessor confirms that an `INSERT` statement is syntactically correct, but it cannot confirm that the table mentioned in the `INSERT` statement actually exists. +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 comprised of the following elements: +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, ...) @@ -61,15 +65,15 @@ For example: 24 } ``` -In the above code fragment: +In this code fragment: - Line 1 specifies a directive to the C preprocessor. - C preprocessor directives may 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. + 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 are not copied to the output file. + SQL preprocessor directives are interpreted by the ECPGPlus preprocessor and aren't copied to the output file. - Lines 4 through 6 contain C declarations. @@ -77,17 +81,17 @@ In the above code fragment: - Lines 10 through 14 contain an embedded-SQL declaration section. - C variables that you refer to within SQL code are known as `host variables`. If you invoke the ECPGPlus preprocessor in Pro\*C mode (`-C PROC`), you may refer to *any* C variable within a SQL statement; otherwise you must declare each host variable within a `BEGIN/END DECLARATION SECTION` pair. + 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 run-time library. + 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. -Any SQL statement must be prefixed with `EXEC SQL` and extends to the next (unquoted) semicolon. For example: +Prefix any SQL statement with `EXEC SQL`. The SQL statement extends to the next (unquoted) semicolon. For example: ```text printf(“Updating employee salaries\n”); @@ -98,7 +102,7 @@ EXEC SQL COMMIT; printf(“Employee salaries updated\n”); ``` -When the preprocessor encounters the code fragment shown above, 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 would appear similar to the following: +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: ```text printf("Updating employee salaries\n"); @@ -118,15 +122,13 @@ 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 in: - -On Windows: +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: +On Linux, it's located in: ```text /usr/edb/as14/bin @@ -150,14 +152,14 @@ 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 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 +- A C compiler (and linker) +- The make utility - ECPGPlus preprocessor and library -- a `makefile` that contains instructions for ECPGPlus +- A makefile that contains instructions for ECPGPlus -The following code is an example of a `makefile` for the samples included in this guide. To use the sample code, save it in a file named `makefile` in the directory that contains the source code file. +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. ```text INCLUDES = -I$(shell pg_config --includedir) @@ -184,7 +186,7 @@ LIBPATH = -L $(shell pg_config --libdir) The `pg_config` program is shipped with EDB Postgres Advanced Server. -`make` knows that it should 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 run-time library (`-lecpg`) and the libpq library (`-lpq`) +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`). ```text CFLAGS += $(INCLUDES) -g @@ -192,41 +194,45 @@ LDFLAGS += -g LDLIBS += $(LIBPATH) -lecpg -lpq ``` -The sample `makefile` instructs 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: +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: ```text .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 pre-compiler with the `-c` flag (instructing the compiler to convert SQL code into C), using the value of the `INCLUDES` variable and the name of the `.pgc` file. +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. ```text .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 pre-compiler with the `-c` flag (instructing the compiler to convert SQL code into C), as well as the `-C PROC` flag (instructing the compiler to use ECPGPlus in Pro\*C-compatibility mode), using the value of the `INCLUDES` variable and the name of the `.pgc` file. +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 wish to compile. For example, to compile an ECPG source code file named `customer_list.pgc`, use the command: +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: ```text make customer_list ``` -The `make` utility consults the `makefile` (located in the current directory), discovers that the `makefile` contains a rule that compiles `customer_list.pgc` into a C program (`customer_list.c`), and then uses the rules built into `make` to compile `customer_list.c` into an executable program. +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` shown above, `make` includes the `-C` option when invoking ECPGPlus to specify that ECPGPlus should be invoked in Pro\*C compatible mode. +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 may use Pro\*C command line syntax; for example: +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: ```text $ ecpg -C PROC INCLUDE=/usr/edb/as14/include acct_update.c ``` -To display a complete list of the other ECPGPlus options available, navigate to the ECPGPlus installation directory, and enter: +To display a complete list of the other ECPGPlus options available, in the ECPGPlus installation directory, enter: ```text ./ecpg --help @@ -243,7 +249,7 @@ The command line options are: | -i | Parse system, include files as well. | | -I directory | Search *directory* for `include` files. | | -o *outfile* | Write the result to *outfile*. | -| -r *option* | Specify run-time 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. | +| -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. | @@ -251,4 +257,4 @@ The command line options are: | --version | Output version information. | !!! Note - If you don't specify an output file name when invoking ECPGPlus, the output file name is created by stripping off the `.pgc` filename extension, and appending `.c` to the file name. + 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/14/ecpgplus_guide/03_using_embedded_sql.mdx b/product_docs/docs/epas/14/ecpgplus_guide/03_using_embedded_sql.mdx index 865a630e7c9..e78d63290e2 100644 --- a/product_docs/docs/epas/14/ecpgplus_guide/03_using_embedded_sql.mdx +++ b/product_docs/docs/epas/14/ecpgplus_guide/03_using_embedded_sql.mdx @@ -11,11 +11,9 @@ legacyRedirectsGenerated: -Each of the following sections leads with a code sample, followed by an explanation of each section within the code sample. - ## Example: A simple query -The first code sample demonstrates how to execute a `SELECT` statement (which 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. +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. ```text /************************************************************ @@ -60,7 +58,7 @@ int main(void) /***********************************************************\* ``` -The code sample begins by including the prototypes and type definitions for the C `stdio` library, and then declares the `main` function: +The code sample begins by including the prototypes and type definitions for the C `stdio` library and then declares the `main` function: ```text #include @@ -81,11 +79,11 @@ EXEC SQL BEGIN DECLARE SECTION; EXEC SQL END DECLARE SECTION; ``` -If you plan to pre-compile the code in `PROC` mode, you may omit the `BEGIN DECLARE…END DECLARE` section. For more information about declaring host variables, refer to the [Declaring Host Variables](#declaring-host-variables). +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 within 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 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 instructs the server how to handle an error: +The next statement tells the server how to handle an error: ```text EXEC SQL WHENEVER SQLERROR sqlprint; @@ -98,7 +96,7 @@ EXEC SQL CONNECT TO edb USER 'alice' IDENTIFIED BY '1safepwd'; ``` -In our example, the client application connects to the `edb` database, using a role named `alice` with a password of `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: @@ -114,13 +112,13 @@ EXEC SQL empno = 7369; ``` -The query returns information about employee number `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 `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 could potentially contain a `NULL` value. The statement includes the `INDICATOR` keyword, and a host variable to hold a null indicator. +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 on-screen results: +The code checks the null indicator and displays the appropriate results: ```text if (v_comm_ind) @@ -131,7 +129,7 @@ else 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 which may be `NULL`. +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: @@ -142,33 +140,33 @@ 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 may contain the following values: +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 | +| 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 are not required to include the optional `INDICATOR` keyword. +When including an indicator variable in an `INTO` clause, you don't need to include the optional `INDICATOR` keyword. -You may omit an indicator variable if you are 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 run-time error. +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 may appear within 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: +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 +- An array +- A `typedef` +- A pointer +- A `struct` +- Any scalar C data type -The code fragments that follow demonstrate 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. +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 are compiling in `PROC` mode, you may 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: +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: ```text void addDept(int v_deptno, char v_dname, char v_loc) @@ -177,7 +175,7 @@ void addDept(int v_deptno, char v_dname, char v_loc) } ``` -If you are not 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, as shown below: +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: ```text void addDept(int v_deptno, char v_dname, char v_loc) @@ -199,18 +197,18 @@ 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 demonstrated in the next example. +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 demonstrates using a cursor to process a result set. There are four basic steps involved in creating and using a cursor: +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, our 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. +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. ```text /************************************************************ @@ -264,7 +262,7 @@ int main(int argc, char *argv[]) /************************************************************ ``` -The code sample begins by including the prototypes and type definitions for the C `stdio` library, and then declares the `main` function: +The code sample begins by including the prototypes and type definitions for the C `stdio` library and then declares the `main` function: ```text #include @@ -287,11 +285,11 @@ EXEC SQL BEGIN DECLARE SECTION; 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`); we have omitted 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. +`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 may be thinking that you could refer to `argv[1]` and `argv[2]` in a SQL statement (instead of creating a separate copy of each variable); that doesn't work. All host variables must be declared within a `BEGIN/END DECLARE SECTION` (unless you are compiling in `PROC` mode). Since `argv` is a function *parameter* (not an automatic variable), it cannot be declared within a `BEGIN/END DECLARE SECTION`. If you are compiling in `PROC` mode, you can refer to *any* C variable within a SQL statement. +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 instructs the server to respond to an SQL error by printing the text of the error message returned by ECPGPlus or the database server: +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: ```text EXEC SQL WHENEVER SQLERROR sqlprint; @@ -315,7 +313,7 @@ EXEC SQL DECLARE employees CURSOR FOR 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. +`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: @@ -323,7 +321,7 @@ Before fetching rows from the cursor, the client application must `OPEN` the cur 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: +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: ```text EXEC SQL WHENEVER NOT FOUND DO break; @@ -339,11 +337,11 @@ for (;;) :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 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 on-screen results: +The code then checks the null indicator and displays the appropriate results: ```text if (v_comm_ind) @@ -355,9 +353,9 @@ else } ``` -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`. +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: +The final statements in the code sample close the cursor `(employees)` and the connection to the server: ```text EXEC SQL CLOSE employees; diff --git a/product_docs/docs/epas/14/ecpgplus_guide/04_using_descriptors.mdx b/product_docs/docs/epas/14/ecpgplus_guide/04_using_descriptors.mdx index c1839a5fe27..462e1a64c0e 100644 --- a/product_docs/docs/epas/14/ecpgplus_guide/04_using_descriptors.mdx +++ b/product_docs/docs/epas/14/ecpgplus_guide/04_using_descriptors.mdx @@ -8,14 +8,14 @@ legacyRedirectsGenerated: -Dynamic SQL allows a client application to execute SQL statements that are composed at runtime. This is useful when you don't know the content or form for a statement when you are writing a client application. ECPGPlus does *not* allow you to use a host variable in place of an identifier (such as a table name, column name or index name); instead, you should 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. +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 following steps describe the basic flow of a client application using dynamic SQL: +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 syntax-check the SQL statement. +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. @@ -25,9 +25,9 @@ A client application must use a `GET DESCRIPTOR` statement to retrieve informati 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 may contain the attributes listed in the table below: +A descriptor can contain these attributes. -| **Field** | **Type** | **Attribute Description** | +| Field | Type | Attribute description | | ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `CARDINALITY` | `integer` | The number of rows in the result set. | | `DATA` | N/A | The data value. | @@ -47,14 +47,14 @@ A descriptor may contain the attributes listed in the table below: ## Example: Using a descriptor to return data -The following simple application executes an SQL statement entered by an end user. The code sample demonstrates: +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. +- 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. +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: @@ -231,7 +231,7 @@ The code sample begins by including the prototypes and type definitions for the #include ``` -The sample provides minimal error handling; when the application encounters an SQL error, it prints the error message to screen: +The sample provides minimal error handling. When the application encounters a SQL error, it prints the error message to screen: ```text EXEC SQL WHENEVER SQLERROR SQLPRINT; @@ -254,7 +254,7 @@ int main( int argc, char *argv[] ) { ``` -The following declaration section identifies the host variables to contain the name of the database to which the application connects, the content of the SQL Statement, and a host variable for the number of columns in the result set (if any). +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). ```text EXEC SQL BEGIN DECLARE SECTION; @@ -264,37 +264,37 @@ EXEC SQL BEGIN DECLARE SECTION; EXEC SQL END DECLARE SECTION; ``` -The application connects to the database (using the default credentials): +The application connects to the database using the default credentials: ```text EXEC SQL CONNECT TO :db; ``` -Next, the application allocates an SQL descriptor to hold the metadata for a statement: +Next, the application allocates a SQL descriptor to hold the metadata for a statement: ```text EXEC SQL ALLOCATE DESCRIPTOR parse_desc; ``` -The application uses a `PREPARE` statement to syntax check the string provided by the user: +The application uses a `PREPARE` statement to check the syntax of the string provided by the user: ```text EXEC SQL PREPARE query FROM :stmt; ``` -and a `DESCRIBE` statement to move the metadata for the query into the SQL descriptor. +It also uses a `DESCRIBE` statement to move the metadata for the query into the SQL descriptor. ```text 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`. +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`. ```text EXEC SQL GET DESCRIPTOR parse_desc :col_count = COUNT; ``` -If the column count is zero, the end user did not enter a `SELECT` statement; the application uses an `EXECUTE IMMEDIATE` statement to process the contents of the statement: +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: ```text if( col_count == 0 ) @@ -312,7 +312,7 @@ 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`. +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`: ```text int row; @@ -331,7 +331,7 @@ EXEC SQL DECLARE my_cursor CURSOR FOR query; EXEC SQL OPEN my_cursor; ``` -Loops through the rows in result set: +It loops through the rows in the result set: ```text for( row = 0; ; row++ ) @@ -341,20 +341,20 @@ for( row = 0; ; row++ ) EXEC SQL END DECLARE SECTION; ``` -Then, uses a `FETCH` to retrieve the next row from the cursor into the descriptor: +Then, it uses a `FETCH` to retrieve the next row from the cursor into the descriptor: ```text EXEC SQL FETCH IN my_cursor INTO SQL DESCRIPTOR row_desc; ``` -The application confirms that the `FETCH` did not fail; if the `FETCH` fails, the application has reached the end of the result set, and breaks the loop: +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: ```text 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. +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: ```text if( row == 0 ) @@ -379,7 +379,7 @@ for( col = 1; col <= col_count; col++ ) 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 above. Notice that you can retrieve multiple items from a descriptor using a comma-separated list. +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: ```text EXEC SQL GET DESCRIPTOR row_desc @@ -387,7 +387,7 @@ EXEC SQL GET DESCRIPTOR row_desc :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. +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. ```text if( ind == -1 ) @@ -402,7 +402,7 @@ printf( "\n" ); } ``` -When the loop terminates, the application prints the number of rows fetched, and exits: +When the loop terminates, the application prints the number of rows fetched and exits: ```text printf( "%d rows\n", row ); @@ -429,7 +429,7 @@ EXEC SQL BEGIN DECLARE SECTION; 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]`. +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]`. ```text static char *types[] = @@ -455,13 +455,13 @@ static char *types[] = }; ``` -The application retrieves the column count from the descriptor. Notice that the program refers to the descriptor using a host variable `(desc)` that contains the name of the descriptor. In most scenarios, you would use an identifier to refer to a descriptor, but in this case, the caller provided the descriptor name, so we can use a host variable to refer to the descriptor. +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. ```text EXEC SQL GET DESCRIPTOR :desc :col_count = count; ``` -The application prints the column headers (defined at the beginning of this application): +The application prints the column headers defined at the beginning of this application: ```text printf( "%s\n", md1 ); @@ -469,7 +469,7 @@ printf( "%s\n", md2 ); printf( "%s\n", md3 ); ``` -Then, loops through each column found in the descriptor, and prints the name, type and length of each column. +Then, it loops through each column found in the descriptor and prints the name, type, and length of each column. ```text for( col = 1; col <= col_count; col++ ) @@ -492,7 +492,7 @@ EXEC SQL GET DESCRIPTOR :desc :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"`. +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"`: ```text if( type > 0 && type < SQL3_abstract ) @@ -501,7 +501,7 @@ else type_name = "unknown"; ``` -and prints the column number, name, type name, and length: +It then prints the column number, name, type name, and length: ```text printf( "%02d: %-20s %-17s %04d\n", @@ -511,7 +511,7 @@ and prints the column number, name, type name, and length: } ``` -If you invoke the sample application with the following command: +Invoke the sample application with the following command: ```text ./exec_stmt test "SELECT * FROM emp WHERE empno IN(7902, 7934)" diff --git a/product_docs/docs/epas/14/ecpgplus_guide/05_building_executing_dynamic_sql_statements.mdx b/product_docs/docs/epas/14/ecpgplus_guide/05_building_executing_dynamic_sql_statements.mdx index 5c6964f2170..6fc56e22adc 100644 --- a/product_docs/docs/epas/14/ecpgplus_guide/05_building_executing_dynamic_sql_statements.mdx +++ b/product_docs/docs/epas/14/ecpgplus_guide/05_building_executing_dynamic_sql_statements.mdx @@ -11,18 +11,18 @@ legacyRedirectsGenerated: -The following examples demonstrate four techniques for building and executing dynamic SQL statements. Each example demonstrates processing a different combination of statement and input types: +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 demonstrates processing and executing a SQL statement that does not contain a `SELECT` statement and does not require input variables. This example corresponds to the techniques used by Oracle Dynamic SQL Method 1. -- The second example demonstrates processing and executing a SQL statement that does not 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 demonstrates processing and executing a SQL statement that may 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 demonstrates processing and executing a SQL statement that may 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. +- 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 -The following example demonstrates how to use the `EXECUTE IMMEDIATE` command to execute a SQL statement where the text of the statement is not known until you run the application. You cannot use `EXECUTE IMMEDIATE` to execute a statement that returns a result set. You cannot use `EXECUTE IMMEDIATE` to execute a statement that contains parameter placeholders. +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 the next example. +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). ```text /***********************************************************/ @@ -65,7 +65,7 @@ static void handle_error(void) /***********************************************************/ ``` -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: +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: ```text #include @@ -78,7 +78,7 @@ 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: +The example then sets up an error handler. ECPGPlus calls the `handle_error()` function whenever a SQL error occurs: ```text EXEC SQL WHENEVER SQLERROR DO handle_error(); @@ -98,7 +98,7 @@ insertStmt = "INSERT INTO dept VALUES(50, 'ACCTG', 'SEATTLE')"; EXEC SQL EXECUTE IMMEDIATE :insertStmt; ``` -If the `EXECUTE IMMEDIATE` command fails for any reason, 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. +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: ```text fprintf(stderr, "ok\n"); @@ -109,7 +109,7 @@ If the `EXECUTE IMMEDIATE` command fails for any reason, ECPGPlus invokes the `h } ``` -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. +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: ```text static void handle_error(void) @@ -125,11 +125,11 @@ static void handle_error(void) ## Example: Executing a nonquery statement with a specified number of placeholders -To execute a non-query 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. +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 may execute many times (providing different *values* each time). +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; if not possible, ECPGPlus reports an error. +ECPGPlus converts each parameter value to the type required by the SQL statement, if possible. Otherwise, ECPGPlus reports an error. ```text /***********************************************************/ @@ -172,7 +172,7 @@ static void handle_error(void) /***********************************************************/ ``` -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: +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: ```text #include @@ -187,7 +187,7 @@ 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: +The example then sets up an error handler. ECPGPlus calls the `handle_error()` function whenever a SQL error occurs. ```text EXEC SQL WHENEVER SQLERROR DO handle_error(); @@ -199,7 +199,7 @@ Then, the example connects to the database using the credentials specified on th 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. +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. ```text stmtText = "INSERT INTO dept VALUES(?, ?, ?)"; @@ -213,7 +213,7 @@ After parsing and planning the statement, the application uses the `EXECUTE` sta EXEC SQL EXECUTE stmtHandle USING :argv[2], :argv[3], :argv[4]; ``` -If the `EXECUTE` command fails for any reason, 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. +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: ```text fprintf(stderr, "ok\n"); @@ -224,7 +224,7 @@ If the `EXECUTE` command fails for any reason, ECPGPlus invokes the `handle_erro } ``` -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. +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: ```text static void handle_error(void) @@ -239,7 +239,7 @@ static void handle_error(void) ## Example: Executing a query with a known number of placeholders -This example demonstrates 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, before opening a cursor and iterating through the result set. +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. ```text /***********************************************************/ @@ -297,7 +297,7 @@ static void handle_error(void) /***********************************************************/ ``` -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: +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: ```text #include @@ -314,7 +314,7 @@ int main(int argc, char *argv[]) VARCHAR ename[20]; ``` -The example then sets up an error handler; ECPGPlus calls the `handle_error()` function whenever a SQL error occurs: +The example then sets up an error handler. ECPGPlus calls the `handle_error()` function whenever a SQL error occurs: ```text EXEC SQL WHENEVER SQLERROR DO handle_error(); @@ -326,14 +326,14 @@ Then, the example connects to the database using the credentials specified on th 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. +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. ```text 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. Notice that the `OPEN` statement includes a `USING` clause: the `USING` clause must provide a *value* for each placeholder found in the query: +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: ```text EXEC SQL DECLARE empCursor CURSOR FOR stmtHandle; @@ -346,7 +346,7 @@ while(true) { ``` -The program iterates through the cursor, and prints the employee number and name of each employee in the selected department: +The program iterates through the cursor and prints the employee number and name of each employee in the selected department: ```text EXEC SQL FETCH empCursor INTO :empno, :ename; @@ -355,7 +355,7 @@ The program iterates through the cursor, and prints the employee number and name } ``` -The program then closes the cursor, commits any changes, disconnects from the server, and terminates the application. +The program then closes the cursor, commits any changes, disconnects from the server, and terminates the application: ```text EXEC SQL CLOSE empCursor; @@ -366,7 +366,7 @@ The program then closes the cursor, commits any changes, disconnects from the se } ``` -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. +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: ```text static void handle_error(void) @@ -384,7 +384,7 @@ static void handle_error(void) ## Example: Executing a query with an unknown number of variables -The next example demonstrates executing a query with an unknown number of input parameters and/or columns in the result set. This type of query may 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). +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). ```text /***********************************************************/ @@ -549,21 +549,21 @@ The code sample begins by including the prototypes and type definitions for the #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. +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. ```text SQLDA *params; SQLDA *results; ``` -The program then declares two helper functions (defined near the end of the code sample): +The program then declares two helper functions, which are defined near the end of the code sample: ```text 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. Notice that the values for these three host variables are derived from the command-line arguments. When the program begins execution, it sets up an error handler and then connects to the database server: +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: ```text int main(int argc, char *argv[]) @@ -580,17 +580,17 @@ int main(int argc, char *argv[]) IDENTIFIED BY :password; ``` -Next, the program calls the `sqlald()` function to allocate the memory required for each descriptor. Each descriptor contains (among other things): +Next, the program calls the `sqlald()` function to allocate the memory required for each descriptor. Each descriptor contains pointers to arrays of: -- a pointer to an array of column names -- a pointer to an array of indicator names -- a pointer to an array of data types -- a pointer to an array of lengths -- a pointer to an array of data values. +- 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. +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) section for a complete description of the `SQLDA` structure. +See [SQLDA structure](07_reference/#sqlda_structure) for a complete description of the `SQLDA` structure. ```text params = sqlald(20, 64, 64); @@ -605,13 +605,13 @@ 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 prompt the user for a value to substitute in place of each parameter marker found in the dynamic query. +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. ```text bindParams(); ``` -Finally, the program opens the cursor (using the parameter values supplied by the user, if any) and calls the `displayResultSet()` function to print the result set produced by the query. +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: ```text EXEC SQL OPEN dynCursor USING DESCRIPTOR params; @@ -620,7 +620,7 @@ displayResultSet(); } ``` -The `bindParams()` function determines whether the dynamic query contains any parameter markers, and, if so, 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. +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: ```text static void bindParams(void) @@ -628,7 +628,7 @@ 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. +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. ```text if (params->F < 0) @@ -640,7 +640,7 @@ else 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. +Next, the program executes a loop that prompts the user for a value, iterating once for each parameter marker found in the statement: ```text for (i = 0; i < params->F; i++) @@ -655,7 +655,11 @@ for (i = 0; i < params->F; i++) 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 (see `Type Codes` for a list of type codes), `params->L[i]` to the length of the value (we subtract one to trim off the trailing new-line character added by `fgets()`), and `params->V[i]` to point to a copy of the NULL-terminated string provided by the user. +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 ```text params->T[i] = 1; /* Data type = Character (1) */ @@ -666,7 +670,7 @@ After prompting the user for a value for a given parameter, the program *binds* } ``` -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. +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. ```text static void displayResultSet(void) @@ -674,7 +678,7 @@ 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 where returned by the query. +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. ```text if (results->F < 0) @@ -696,7 +700,7 @@ 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 necessary because the `DESCRIBE SELECT LIST` statement encodes the type of each column and the nullability of each column into the `T` array. +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. ```text sqlnul(&results->T[col], @@ -724,7 +728,7 @@ switch (results->T[col]) } ``` -For date values, the program uses a somewhat arbitrary, hard-coded length of 30. In a real-world application, you may want to more carefully compute the amount of space required. +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. ```text case 12: /* DATE */ @@ -734,7 +738,7 @@ case 12: /* DATE */ } ``` -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 may want to include more careful calculations for other data types. +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: ```text default: /* Others */ @@ -745,7 +749,11 @@ default: /* Others */ } ``` -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]`, and set 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. +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 ```text results->V[col] = malloc(length); @@ -772,11 +780,11 @@ The program executes a `FETCH` statement to fetch the next row in the cursor int 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 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 +- `*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 is not aligned - instead, each value is separated from the previous value by a comma. +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. ```text for (col = 0; col < results->F; col++) diff --git a/product_docs/docs/epas/14/ecpgplus_guide/06_error_handling.mdx b/product_docs/docs/epas/14/ecpgplus_guide/06_error_handling.mdx index 6127f42b40d..e174cd857a6 100644 --- a/product_docs/docs/epas/14/ecpgplus_guide/06_error_handling.mdx +++ b/product_docs/docs/epas/14/ecpgplus_guide/06_error_handling.mdx @@ -9,14 +9,14 @@ legacyRedirectsGenerated: -ECPGPlus provides two methods to detect and handle errors in embedded SQL code: +ECPGPlus provides two methods to detect and handle errors in embedded SQL code. A client application can: -- A client application can examine the `sqlca` data structure for error messages, and supply customized error handling for your client application. -- A client application can include `EXEC SQL WHENEVER` directives to instruct the ECPGPlus compiler to add error-handling code. +- 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 (for example, an `INSERT` or `SELECT` statement) you can inspect the contents of `sqlca` to determine if the statement has completed successfully or if the statement has failed. +`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: @@ -49,96 +49,82 @@ If you include the `ecpg` directive, you don't need to `#include` the `sqlca.h` The EDB Postgres Advanced Server `sqlca` structure contains the following members: -`sqlcaid` +- `sqlcaid` — Contains the string: `"SQLCA"`. - `sqlcaid` contains the string: `"SQLCA"`. +- `sqlabc` — `sqlabc` contains the size of the `sqlca` structure. -`sqlabc` +- `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. - `sqlabc` contains the size of the `sqlca` structure. + `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. -`sqlcode` + 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 `sqlcode` member has been deprecated with SQL 92; EDB Postgres Advanced Server supports `sqlcode` for backward compatibility, but you should use the `sqlstate` member when writing new code. + 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. - `sqlcode` is an integer value; a positive `sqlcode` value indicates that the client application has encountered a harmless processing condition, while a negative value indicates a warning or error. +`sqlerrm` is a structure embedded in `sqlca`, composed of two members: - 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. +- `sqlerrml` — Contains the length of the error message currently stored in `sqlerrmc`. - The SQL standard defines only a positive value of 100, which indicates that he most recent SQL statement processed returned/affected no rows. Since the SQL standard does not define other `sqlcode` values, be aware that the values assigned to each condition may vary from database to database. +- `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. -`sqlerrm` is a structure embedded within `sqlca`, composed of two members: - -`sqlerrml` - - `sqlerrml` contains the length of the error message currently stored in `sqlerrmc`. - -`sqlerrmc` - - `sqlerrmc` contains the null-terminated message text associated with the code stored in `sqlstate`. If a message exceeds 149 characters in length, `ecpglib` truncates the error message. - -`sqlerrp` - - `sqlerrp` contains the string `"NOT SET"`. +- `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[1]` — Contains the OID of the processed row (if applicable). -- `sqlerrd[2]` contains the number of processed or returned rows. +- `sqlerrd[2]` — Contains the number of processed or returned rows. -- `sqlerrd[0], sqlerrd[3], sqlerrd[4]` and `sqlerrd[5]` are unused. +- `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 within `sqlwarn` is set to `'W'`. +- `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[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 non-fatal warning. +- `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. +- `sqlwarn[3]`, `sqlwarn[4]`, `sqlwarn[5]`, `sqlwarn[6]`, and `sqlwarn[7]` are unused. -`sqlstate` +`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` is a 5 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` is *not* a null-terminated string. - - `sqlstate` codes are assigned in a hierarchical scheme: +`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. +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: +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 | +| sqlstate | sqlcode (deprecated) | Symbolic name | Description | | ------------------- | -------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `YE001` | `-12` | `ECPG_OUT_OF_MEMORY` | Virtual memory is exhausted. | -| `YE002` | `-200` | `ECPG_UNSUPPORTED` | The preprocessor has generated an unrecognized item. Could indicate incompatibility between the preprocessor and the library. | +| `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 has 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 cannot 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 cannot 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 cannot be converted into an 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 cannot be stored in a BOOL. | +| `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 has not been supplied for the NULL value returned by the server (the client application has received an unexpected NULL value). | -| `42804` | `-214` | `ECPG_NO_ARRAY` | The server has returned an array, and the corresponding host variable is not capable of storing an array. | -| `42804` | `-215` | `ECPG_DATA_NOT_ARRAY` | The server has returned a value that is not an array into a host variable that expects an array value. | -| `08003` | `-220` | `ECPG_NO_CONN` | The client application has attempted to use a non-existent connection. | -| `YE002` | `-221` | `ECPG_NOT_CONN` | The client application has attempted to use an allocated, but closed connection. | -| `26000` | `-230` | `ECPG_INVALID_STMT` | The statement has not been prepared. | -| `33000` | `-240` | `ECPG_UNKNOWN_DESCRIPTOR` | The specified descriptor is not found. | -| `07009` | `-241` | `ECPG_INVALID_DESCRIPTOR_INDEX` | The descriptor index is out-of-range. | -| `YE002` | `-242` | `ECPG_UNKNOWN_DESCRIPTOR_ITEM` | The client application has requested an invalid descriptor item (internal error). | -| `07006` | `-243` | `ECPG_VAR_NOT_NUMERIC` | A dynamic statement has returned a numeric value for a non-numeric host variable. | -| `07006` | `-244` | `ECPG_VAR_NOT_CHAR` | A dynamic SQL statement has returned a CHAR value, and the host variable is not a CHAR. | -| | `-400` | `ECPG_PGSQL` | The server has returned an error message; the resulting message contains the error text. | -| `08007` | `-401` | `ECPG_TRANS` | The server cannot start, commit or rollback the specified transaction. | -| `08001` | `-402` | `ECPG_CONNECT` | The client application's attempt to connect to the database has failed. | -| `02000` | `100` | `ECPG_NOT_FOUND` | The last command retrieved or processed no rows, or you have reached the end of a cursor. | +| `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 @@ -150,7 +136,7 @@ EXEC SQL WHENEVER ; This directive instructs the ECPG compiler to insert error-handling code into your program. -The code instructs the client application that it should perform a specified action if the client application detects a given condition. The *condition* may be one of the following: +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` @@ -172,39 +158,31 @@ You can specify that the client application perform one of the following *action `DO CONTINUE` - An action of `DO CONTINUE` generates a `CONTINUE` statement in the emitted C code that if it encounters the condition, skips the rest of the code in the loop and continues with the next iteration. You can only use it within a loop. - -`GOTO label` - - or + 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. -`GO TO label` +`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`. + 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. + 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 + Execute the C `break` statement. Use this action in loops or `switch` statements. -`DO name(args)` +`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:** +## Example -The following code fragment prints a message if the client application encounters a warning, and aborts the application if it encounters an error: +The following code fragment prints a message if the client application encounters a warning and aborts the application if it encounters an error: ```text EXEC SQL WHENEVER SQLWARNING SQLPRINT; @@ -212,4 +190,4 @@ EXEC SQL WHENEVER SQLERROR STOP; ``` !!! Note - The ECPGPlus compiler processes your program from top to bottom, even though the client application may 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 within your program is not top-to-bottom, you should consider adding error-handling directives to any parts of the program that may be inadvertently missed during compilation. + 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/14/ecpgplus_guide/07_reference.mdx b/product_docs/docs/epas/14/ecpgplus_guide/07_reference.mdx index cf1f197efe8..2c01789f42c 100644 --- a/product_docs/docs/epas/14/ecpgplus_guide/07_reference.mdx +++ b/product_docs/docs/epas/14/ecpgplus_guide/07_reference.mdx @@ -69,27 +69,27 @@ legacyRedirectsGenerated: -The sections that follow describe ecpgPlus language elements: +ECPGPlus has these language elements: -- C-Preprocessor Directives -- Supported C Data Types -- Type Codes -- The SQLDA Structure -- ECPGPlus Statements +- 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 are dependent on the mode in which you invoke ECPGPlus: +The ECPGPlus C-preprocessor enforces two behaviors that depend on the mode in which you invoke ECPGPlus: - `PROC` mode -- non-`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 it is of a data type compatible with ECPG. +- 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: @@ -107,7 +107,7 @@ When you invoke ECPGPlus in `PROC` mode (by including the `-C PROC` keywords), t #defined(symbolName) ``` -Pre-processor directives are used to effect or direct the code that is received by the compiler. For example, using the following code sample: +Preprocessor directives are used to affect or direct the code that's received by the compiler. For example, consider the following code sample: ```text #if HAVE_LONG_LONG == 1 @@ -119,19 +119,19 @@ Pre-processor directives are used to effect or direct the code that is received BALANCE_TYPE customerBalance; ``` -If you invoke ECPGPlus with the following command-line arguments: +Suppose you invoke ECPGPlus with the following command-line arguments: ```text ecpg –C PROC –DHAVE_LONG_LONG=1 ``` -ECPGPlus copies the entire fragment (without change) to the output file, but sends onlyi the following tokens to the ECPG parser: +ECPGPlus copies the entire fragment, without change, to the output file. It sends only the following tokens to the ECPG parser: ```text long long customerBalance; ``` -On the other hand, if you invoke ECPGPlus with the following command-line arguments: +On the other hand, suppose you invoke ECPGPlus with the following command-line arguments: ```text ecpg –C PROC –DHAVE_LONG_LONG=0 @@ -143,7 +143,7 @@ The ECPG parser receives the following tokens: double customerBalance; ``` -If your code uses preprocessor directives to filter the code that is sent to the compiler, the complete code is retained in the original code, while the ECPG parser sees only the processed token stream. +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: @@ -159,7 +159,7 @@ EXEC ORACLE ENDIF EXEC ORACLE OPTION ``` -For example, if your code includes the following: +For example, suppose your code includes the following: ```text EXEC ORACLE IFDEF HAVE_LONG_LONG; @@ -168,7 +168,7 @@ EXEC ORACLE ENDIF; BALANCE_TYPE customerBalance; ``` -If you invoke ECPGPlus with the following command-line arguments: +You invoke ECPGPlus with the following command-line arguments: ```text ecpg –C PROC DEFINE=HAVE_LONG_LONG=1 @@ -181,38 +181,40 @@ long long customerBalance; ``` !!! Note - The `EXEC ORACLE` pre-processor directives only work if you specify `-C PROC` on the ECPG command line. + 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 instruct your program how to handle result sets that contain more rows than the host variable can accommodate. The syntax is: +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: ```text 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 instruct the program to suppress error messages when a `SELECT` statement returns more rows than a host variable can accommodate. +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 +### 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 within an `EXEC SQL BEGIN/END DECLARE` section. +- 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. +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. +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 may 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 may fail (at execution time) if the C value cannot be converted into the required SQL type. +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. -ECPGPlus can convert any SQL type into C character values `(char[n]` or `varchar[n])`. Although it is safe to convert any SQL type to/from `char[n]` or `varchar[n]`, it is often convenient to use more natural C types such as `int`, `double`, or `float`. +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: @@ -225,9 +227,9 @@ The supported C data types are: - `char[n+1]` - `varchar[n+1]` - `bool` -- and any equivalent created by a `typedef` +- Any equivalent created by a `typedef` -In addition to the numeric and character types supported by C, the `pgtypeslib` run-time library offers custom data types (and functions to operate on those types) for dealing with date/time and exact numeric values: +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` @@ -239,7 +241,7 @@ To use a data type supplied by `pgtypeslib`, you must `#include` the proper head ## 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, the type code in the corresponding SQLDA descriptor `(descriptor->T[column])` should be set to one of the following values: +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) | | ------------------------------------------------- | ----------------------------------------- | @@ -300,20 +302,20 @@ struct SQLDA `N - maximum number of entries` - The `N` structure member contains the maximum number of entries that the SQLDA may 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. + 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). +- 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. Refer to [displayResultSet](05_building_executing_dynamic_sql_statements/#executing_query_with_unknown_number_of_variables) function for an example of how to allocate space for `SELECT`-list values. +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]` should 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. + 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` @@ -322,7 +324,7 @@ Your application must allocate the space required to hold each value. Refer to [ - 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 may 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 may 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: +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: ``` void sqlnul(unsigned short *valType, @@ -330,7 +332,7 @@ void sqlnul(unsigned short *valType, int *isNull) ``` -For example, to find the type code and nullable flag for the third column of a descriptor named results, you would invoke `sqlnul()` as follows: +For example, to find the type code and nullable flag for the third column of a descriptor named results, invoke `sqlnul()` as follows: ``` sqlnul(&results->T[2], &typeCode, &isNull); @@ -345,12 +347,12 @@ sqlnul(&results->T[2], &typeCode, &isNull); `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 which may be described by the descriptor; `F` indicates the actual number of values). The value of the `F` member is set by ECPGPlus when you execute a `DESCRIBE` statement. `F` may be positive, negative, or zero. + 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); 0 if the statement is *not* a `SELECT` statement, or 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); 0 if the statement contains no parameters markers, or a negative value if the statement contains more parameter markers than allowed by the `N` structure member. +- 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 may 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. +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` @@ -359,51 +361,49 @@ If `F` contains a positive number (after executing a `DESCRIBE` statement), that - 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. +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. + 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]`). + 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. + 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 is not used by ECPGPlus, but is provided for compatibility with Pro\*C applications. + 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]`). + 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 is not used by ECPGPlus, but is provided for compatibility with Pro\*C applications. + 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]`). + 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 is not used by ECPGPlus, but is provided for compatibility with Pro\*C applications. + 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, while an embedded directive is an instruction to the ECPGPlus compiler. +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 should begin with the keywords `EXEC SQL`, and must be terminated with a semi-colon (;). Within the C program, a SQL statement takes the form: +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: ```text 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, refer to [Declaring Host Variables](03_using_embedded_sql/#declaring-host-variables). - -ECPGPlus extends the PostgreSQL server-side syntax for some statements; for those statements, syntax differences are outlined in the following reference sections. For a complete reference to the supported syntax of other SQL commands, refer to the *PostgreSQL Core Documentation* available at: +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 @@ -416,13 +416,11 @@ EXEC SQL [FOR ] ALLOCATE DESCRIPTOR Where: -`array_size` is a variable that specifies the number of array elements to allocate for the descriptor. `array_size` may 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 may take the form of an identifier, a quoted string literal, or of a host variable. +- `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`. -`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 may be processed as an array `(emp_array)`: +The following code fragment allocates a descriptor named `emp_query` that can be processed as an array `(emp_array)`: ```text EXEC SQL FOR :emp_array ALLOCATE DESCRIPTOR emp_query; @@ -430,14 +428,14 @@ 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*: +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: ```text EXEC SQL CALL '('[]')' INTO [[:][: ]]; ``` -The second form is used to call a *procedure*: +The second form is used to call a procedure: ```text EXEC SQL CALL '('[]')'; @@ -445,15 +443,12 @@ EXEC SQL CALL '('[]')'; Where: -`program_name` is the name of the stored procedure or function that the `CALL` statement invokes. The program name may be schema-qualified or 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. Note that each `actual_argument` corresponds to a formal argument expected by the program. Each formal argument may be an `IN` parameter, an `OUT` parameter, or an `INOUT` parameter. +- `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. -`: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: +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: ```text EXEC SQL CALL get_job_desc(:ename) @@ -462,17 +457,15 @@ EXEC SQL CALL get_job_desc(:ename) ### CLOSE -Use the `CLOSE` statement to close a cursor, and free any resources currently in use by the cursor. A client application cannot fetch rows from a closed cursor. The syntax of the `CLOSE` statement is: +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: ```text EXEC SQL CLOSE []; ``` -Where: +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. -`cursor_name` is the name of the cursor closed by the statement. The cursor name may 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 re-opening it. +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: @@ -491,11 +484,9 @@ 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 may take the form of an unquoted string literal, or of a host variable. +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 does *not* store any text included with the `COMMENT` clause. +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. @@ -505,21 +496,19 @@ For example, the following command commits all work performed on the `dept` data 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 that a client application should invoke `AUTOCOMMIT` functionality. You can also control `AUTOCOMMIT` functionality in a client application with the following statements: +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: ```text EXEC SQL SET AUTOCOMMIT TO ON ``` -and - ```text 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, the other is not. +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: @@ -533,25 +522,23 @@ EXEC SQL CONNECT 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. +- `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. -`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 `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. +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: +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 could 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: +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: ```text EXEC SQL CONNECT :connection_id; @@ -574,7 +561,7 @@ 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: +`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 [@][:] @@ -586,30 +573,29 @@ 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. +- `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`. + 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` should take 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. +- `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. + 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`. +- `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. +- `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`. +- `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`: +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`: ```text 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. +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 @@ -619,9 +605,7 @@ Use the `DEALLOCATE DESCRIPTOR` statement to free memory in use by an allocated EXEC SQL DEALLOCATE DESCRIPTOR ``` -Where: - -`descriptor_name` is the name of the descriptor. This value may take the form of a quoted string literal, or of a host variable. +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`: @@ -640,13 +624,10 @@ EXEC SQL [AT ] DECLARE CURSOR FOR Where: -`database_name` is the name of the database on which the cursor operates. This value may 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 cannot contain an `INTO` clause. - -`statement_name` is the name of a SQL statement or block that defines the cursor result set. +- `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`: @@ -658,7 +639,7 @@ EXEC SQL DECLARE employees CURSOR FOR emp; ``` -The cursor generates a result set that contains the employee number, employee name, salary and commission for each employee record that is stored in the `emp` table. +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 @@ -668,17 +649,15 @@ Use the `DECLARE DATABASE` statement to declare a database identifier for use in EXEC SQL DECLARE DATABASE; ``` -Where: - -`database_name` specifies the name of the database. +Where `database_name` specifies the name of the database. -The following example demonstrates declaring an identifier for the `acctg` database: +The following example shows declaring an identifier for the `acctg` database: ```text EXEC SQL DECLARE acctg DATABASE; ``` -After invoking the command declaring `acctg` as a database identifier, the `acctg` database can be referenced by name when establishing a connection or in `AT` clauses. +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. @@ -690,19 +669,16 @@ Use the `DECLARE STATEMENT` directive to declare an identifier for an SQL statem EXEC SQL [] DECLARE STATEMENT; ``` -and - ```text EXEC SQL DECLARE STATEMENT ; ``` Where: -`statement_name` specifies the identifier associated with the statement. +- `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. -`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 might be: +A typical usage sequence that includes the `DECLARE STATEMENT` directive is: ```text EXEC SQL DECLARE give_raise STATEMENT; // give_raise is now a statement @@ -726,49 +702,37 @@ Use the `DELETE` statement to delete one or more rows from a table. The syntax f [, ...] INTO ] ``` -Where: - -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 which rows should be deleted. If you don't include a `WHERE` clause in the statement, `DELETE` deletes all rows from the table, leaving the table definition intact. +- 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. -`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. +The `RETURN/RETURNING` clause specifies an `output_expression` or `host_variable_list` that's returned by the `DELETE` command after each row is 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 non-grouping query on the `DELETE` statements target table. You cannot specify `WHERE CURRENT OF` in a `DELETE` statement that includes a Boolean condition. + - `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. -The `RETURN/RETURNING` clause specifies an `output_expression` or `host_variable_list` that is 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:` +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:` ```text DELETE FROM emp WHERE sal > :max_sal; ``` -For more information about using the `DELETE` statement, see the PostgreSQL Core documentation available at: - - +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. +The `DESCRIBE` statement populates an `SQLDA` descriptor. To populate a SQL descriptor, use the `ALLOCATE DESCRIPTOR` and `DESCRIBE...DESCRIPTOR` statements. ```text EXEC SQL DESCRIBE BIND VARIABLES FOR INTO ; ``` -or ```text EXEC SQL DESCRIBE SELECT LIST FOR INTO ; @@ -776,9 +740,8 @@ 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. +- `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: @@ -794,7 +757,7 @@ EXEC SQL PREPARE get_emp FROM "SELECT ename, empno, sal FROM emp WHERE empno = ?"; ``` -The command requires one input variable (for the parameter marker (?)). +The command requires one input variable for the parameter marker (?). ```text EXEC SQL DESCRIBE BIND VARIABLES @@ -803,7 +766,7 @@ EXEC SQL DESCRIBE BIND VARIABLES 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: +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: ```text EXEC SQL DESCRIBE SELECT LIST @@ -812,13 +775,13 @@ EXEC SQL DESCRIBE SELECT LIST 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. +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 alternate Pro\*C compatible syntax for the `DESCRIBE DESCRIPTOR` 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: +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: ```text EXEC SQL DESCRIBE [INPUT | OUTPUT] @@ -827,11 +790,10 @@ EXEC SQL DESCRIBE [INPUT | OUTPUT] 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. +- `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. +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: @@ -847,7 +809,7 @@ EXEC SQL PREPARE get_emp FROM "SELECT ename, empno, sal FROM emp WHERE empno = ?"; ``` -The command requires one input variable (for the parameter marker (?)). +The command requires one input variable for the parameter marker (?). ```text EXEC SQL DESCRIBE INPUT get_emp USING 'query_values_in'; @@ -857,7 +819,7 @@ After describing the bind variables for this statement, you can examine the desc 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. +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: @@ -875,17 +837,15 @@ Use the `DISCONNECT` statement to close the connection to the server. The syntax EXEC SQL DISCONNECT [][CURRENT][DEFAULT][ALL]; ``` -Where: +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. -`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 `CURRENT` keyword to specify that ECPGPlus should close the most-recently used connection. +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 `DEFAULT` keyword to specify that ECPGPlus should 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. -Include the `ALL` keyword to instruct ECPGPlus 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: +The following example creates a connection named `hr_connection` that connects to the `hr` database and then disconnects from the connection: ```text /* client.pgc*/ @@ -909,14 +869,12 @@ EXEC SQL [FOR ] EXECUTE Where: -`array_size` is an integer value or a host variable that contains an integer value that specifies the number of rows to be processed. 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). +- `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 within the prepared 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: @@ -945,16 +903,14 @@ EXEC SQL [FOR ] EXECUTE Where: -`array_size` is an integer value or a host variable that contains an integer value that specifies the number of rows to be processed. 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. +- `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. -`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. - The following example executes the prepared statement, `give_raise`, using the values contained in the descriptor `stmtText:` ```text @@ -972,9 +928,8 @@ 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 may include host variables and optional indicator variables within the block; each such variable is treated as an `IN/OUT` value. +- `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: @@ -1000,13 +955,12 @@ 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. +- `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 (ie., when writing a client application). For example, a client application may 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. +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 may not contain references to host variables. If the statement may contain parameter markers or returns one or more values, you must use the `PREPARE` and `DESCRIBE` statements. +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: @@ -1025,15 +979,14 @@ EXEC SQL [FOR ] FETCH 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. +- `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: +The following code fragment declares a cursor named `employees` that retrieves the `employee number`, `name`, and `salary` from the `emp` table: ```text EXEC SQL DECLARE employees CURSOR FOR @@ -1053,11 +1006,11 @@ EXEC SQL [FOR ] FETCH 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. +- `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 an SQL descriptor into which the `EXECUTE` statement writes the results returned by the prepared 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: @@ -1083,7 +1036,7 @@ EXEC SQL GET DESCRIPTOR : = COUNT; ``` -The second form returns information about a specific value (specified by the `VALUE column_number` clause). +The second form returns information about a specific value (specified by the `VALUE column_number` clause): ```text EXEC SQL [FOR ] GET DESCRIPTOR @@ -1092,16 +1045,13 @@ EXEC SQL [FOR ] GET DESCRIPTOR Where: -`array_size` is an integer value or a host variable that contains an integer value that specifies the number of rows to be processed. 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. +- `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 within 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: @@ -1118,7 +1068,7 @@ ECPGPlus implements the following `descriptor_item` types: - `DATA` - `NAME` -The following code fragment demonstrates using a `GET DESCRIPTOR` statement to obtain the number of columns entered in a user-provided string: +The following code fragment shows using a `GET DESCRIPTOR` statement to obtain the number of columns entered in a user-provided string: ```text EXEC SQL ALLOCATE DESCRIPTOR parse_desc; @@ -1127,7 +1077,7 @@ 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 syntax check 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. +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 @@ -1140,21 +1090,14 @@ Use the `INSERT` statement to add one or more rows to a table. The syntax for th [RETURNING * | [[ AS ] ] [, ...]] ``` -Where: - -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 may be qualified with a subfield name or array subscript. Specify the `DEFAULT VALUES` clause to use default values for all columns. +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. -`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 row(s) to be inserted. - -`output_expression` is an expression that computed and returned by the `INSERT` command after each row is inserted. The expression can refer to any column within the table. Specify \* to return all columns of the inserted row(s). - -`output_name` specifies a name to use for a returned column. +- `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: @@ -1164,11 +1107,9 @@ INSERT INTO emp (empno, ename, job, hiredate) ``` !!! Note - The `INSERT` statement uses a host variable `(:ename)` to specify the value of the `ename` column. + 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 available at: - - +For more information about using the `INSERT` statement, see the [PostgreSQL core documentation](https://www.postgresql.org/docs/current/static/sql-insert.html). ### OPEN @@ -1178,29 +1119,25 @@ Use the `OPEN` statement to open a cursor. The syntax is: EXEC SQL [FOR ] OPEN [USING ]; ``` -Where `parameters` is one of the following: +`parameters` is one of the following: ```text DESCRIPTOR ``` -or - ```text [ [ 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. +- `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 re-opened. A cursor is automatically closed when an application terminates. +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, returning the `employee number`, `name`, `salary` and `commission` of an employee whose name matches a user-supplied value (stored in the host variable, `:emp_name`). +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`. ```text EXEC SQL DECLARE employees CURSOR FOR @@ -1227,13 +1164,11 @@ EXEC SQL [FOR ] OPEN 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. +- `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`: +For example, the following statement opens a cursor named `emp_cursor` using the host variable `:employees`: ```text EXEC SQL OPEN emp_cursor USING DESCRIPTOR :employees; @@ -1241,9 +1176,9 @@ 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, saving repetitive processing time. +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 an SQL statement or PL/pgSQL block for execution. The statement is available in two forms; the first form is: +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: ```text EXEC SQL [AT ] PREPARE @@ -1259,15 +1194,13 @@ EXEC SQL [AT ] PREPARE 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. +- `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. -`statement_name` is the identifier associated with a prepared SQL statement or PL/SQL block. +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. -`sql_statement` may take the form of a `SELECT` statement, a single-quoted string literal or host variable that contains the text of an SQL statement. - -To include variables within a prepared statement, substitute placeholders (`$1, $2, $3`, etc.) 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: +The following example creates a prepared statement named `add_emp` that inserts a record into the `emp` table: ```text EXEC SQL PREPARE add_emp (int, text, text, numeric) AS @@ -1282,44 +1215,42 @@ 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. + 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: +Use the `ROLLBACK` statement to abort the current transaction and discard any updates made by the transaction. The syntax is: ```text EXEC SQL [AT ] ROLLBACK [WORK] [ { TO [SAVEPOINT] } | RELEASE ] ``` -Where: +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. -`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 were 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 `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 rollback a complete transaction: +Use the following statement to roll back a complete transaction: ```text EXEC SQL ROLLBACK; ``` -Invoking this statement aborts the transaction, undoing all changes, erasing any savepoints, and releasing all transaction locks. If you include a savepoint (`my_savepoint` in the following example): +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): ```text 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. +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 within 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: +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: ```text EXEC SQL [AT ] SAVEPOINT @@ -1327,11 +1258,10 @@ 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 re-use a `savepoint_name`, the original savepoint is discarded. +- `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. -Savepoints can only be established within a transaction block. A transaction block may contain multiple savepoints. +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: @@ -1365,15 +1295,12 @@ SELECT 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 may take the form of an unquoted string literal, or of a host variable. +- `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. -`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). -ECPGPlus provides support for the additional clauses of the SQL `SELECT` statement as documented in the PostgreSQL Core documentation available at: - - - -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`: +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: ```text EXEC SQL SELECT ename, sal @@ -1382,21 +1309,21 @@ EXEC SQL SELECT ename, sal WHERE empno = 7988; ``` -The enhanced `SELECT` statement also allows you to include parameter markers (question marks) in any clause where a value would be permitted. For example, the following query contains a parameter marker in the `WHERE` clause: +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: ```text SELECT * FROM emp WHERE dept_no = ?; ``` -This `SELECT` statement allows you to provide a value at run-time for the `dept_no` parameter marker. +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 may need more than one connection in a given client application: +There are at least three reasons you might need more than one connection in a given client application: -- You may want different privileges for different statements; -- You may need to interact with multiple databases within the same client. -- Multiple threads of execution (within a client application) cannot share a connection concurrently. +- 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: @@ -1404,39 +1331,36 @@ The syntax for the `SET CONNECTION` statement is: EXEC SQL SET CONNECTION ; ``` -Where: +Where `connection_name` is the name of the connection to the database. -`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`. -To use the `SET CONNECTION` statement, you should 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 only used when you execute an `EXEC SQL` statement that does not explicitly specify a connection name. For example, the following statement uses the default connection because it does not include an `AT` `connection_name` clause. : +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: ```text 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: +This statement doesn't use the default connection because it specifies a connection name using the `AT connection_name` clause: ```text EXEC SQL AT acctg_conn DELETE FROM emp; ``` -For example, a client application that creates and maintains multiple connections (such as): +For example, suppose a client application creates and maintains multiple connections using either of the following approaches: ```text EXEC SQL CONNECT TO edb AS acctg_conn USER 'alice' IDENTIFIED BY 'acctpwd'; ``` -and ```text EXEC SQL CONNECT TO edb AS hr_conn USER 'bob' IDENTIFIED BY 'hrpwd'; ``` -Can change between the connections with the `SET CONNECTION` statement: +It can change between the connections with the `SET CONNECTION` statement: ```text SET CONNECTION acctg_conn; @@ -1448,11 +1372,11 @@ or 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`. +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: +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: ```text EXEC SQL [FOR ] SET DESCRIPTOR @@ -1468,16 +1392,13 @@ EXEC SQL [FOR ] SET 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. - -`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. +- `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: @@ -1494,7 +1415,7 @@ For example, a client application might prompt a user for a dynamically created 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. +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. ```text EXEC SQL ALLOCATE DESCRIPTOR query_params; @@ -1506,7 +1427,7 @@ EXEC SQL DESCRIBE INPUT emp_query After describing the query, the `query_params` descriptor contains information about each parameter required by the query. -For this example, we'll assume that the user has entered: +For this example, assume that the user entered: ```text SELECT ename FROM emp WHERE sal > ? AND job = ?;, @@ -1514,15 +1435,15 @@ 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: +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: ```text 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 (along with the number of parameters) from the descriptor, or you can supply each `value` in the form of a character string and ECPG converts that string into the required data type. +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`. +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. @@ -1575,19 +1496,15 @@ EXEC SQL [AT ][FOR ] [ 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 may 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. +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. -ECPGPlus provides support for the additional clauses of the SQL `UPDATE` statement as documented in the PostgreSQL Core documentation available at: +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). -A host variable can be used in any clause that specifies a value. To use a host variable, simply substitute a defined variable for any value associated with any of the documented `UPDATE` clauses. +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, and increases the employees salary, by multiplying the current salary by the value in the `:increase` host variable: +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: ```text EXEC SQL UPDATE emp @@ -1595,7 +1512,7 @@ EXEC SQL UPDATE emp WHERE ename = :ename; ``` -The enhanced `UPDATE` statement also allows you to include parameter markers (question marks) in any clause where an input value would be permitted. For example, we can write the same update statement with a parameter marker in the `WHERE` clause: +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: ```text EXEC SQL UPDATE emp @@ -1603,7 +1520,7 @@ EXEC SQL UPDATE emp WHERE ename = :ename; ``` -This `UPDATE` statement could allow 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`. +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 @@ -1613,41 +1530,41 @@ Use the `WHENEVER` statement to specify the action taken by a client application EXEC SQL WHENEVER ; ``` -The following table describes the different conditions that might trigger an `action`: +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. | +| `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 non-fatal warning 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`: +The following table describes the actions that result from a client encountering a `condition`. | Action | Description | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `CALL function [([args])]` | Instructs the client application to call the named `function`. | -| `CONTINUE` | Instructs the client application to proceed to the next statement. | -| `DO BREAK` | Instructs the client application to a C break statement. A break statement may appear in a `loop` or a `switch` statement. If executed, the break statement terminate the `loop` or the `switch` statement. | -| `DO CONTINUE` | Instructs the client application to emit a C `continue` statement. A `continue` statement may only exist within a loop, and if executed, causes the flow of control to return to the top of the loop. | -| `DO function ([args])` | Instructs the client application to call the named `function`. | -| `GOTO label` or `GO TO label` | Instructs the client application to proceed to the statement that contains the `label`. | -| `SQLPRINT` | Instructs the client application to print a message to standard error. | -| `STOP` | Instructs the client application to stop execution. | +| `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: +The following code fragment prints a message if the client application encounters a warning and aborts the application if it encounters an error: ```text EXEC SQL WHENEVER SQLWARNING SQLPRINT; EXEC SQL WHENEVER SQLERROR STOP; ``` -Include the following code to specify that a client should continue processing after warning a user of a problem: +Include the following code to specify for a client to continue processing after warning a user of a problem: ```text 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: +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: ```text EXEC SQL WHENEVER NOT FOUND CALL error_handler(__LINE__); diff --git a/product_docs/docs/epas/14/ecpgplus_guide/index.mdx b/product_docs/docs/epas/14/ecpgplus_guide/index.mdx index c54ec467287..a383eec5fc8 100644 --- a/product_docs/docs/epas/14/ecpgplus_guide/index.mdx +++ b/product_docs/docs/epas/14/ecpgplus_guide/index.mdx @@ -6,19 +6,19 @@ legacyRedirectsGenerated: - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/9.6/toc.html" --- -EDB has enhanced ECPG (the PostgreSQL pre-compiler) 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 (EDB Postgres Advanced Server) database. When you use ECPGPlus to compile an application, the SQL code is syntax-checked and translated into C. +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. +- 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. +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.
diff --git a/product_docs/docs/epas/14/edb_pgadmin_linux_qs/index.mdx b/product_docs/docs/epas/14/edb_pgadmin_linux_qs/index.mdx index 132cc46b116..9e357512011 100644 --- a/product_docs/docs/epas/14/edb_pgadmin_linux_qs/index.mdx +++ b/product_docs/docs/epas/14/edb_pgadmin_linux_qs/index.mdx @@ -2,19 +2,19 @@ title: "EDB pgAdmin4 Quick Start Linux" --- -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 is designed to meet the needs of both novice and experienced Postgres users alike, providing a powerful graphical interface that simplifies the creation, maintenance and use of database objects. +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. +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 -You can use the following steps to use the yum package manager to install EDB pgAdmin4: +Use the yum package manager to install EDB pgAdmin4. ### Create a repository configuration file -To create a repository configuration file, you must have the credentials that allow access to the EDB repository. For information about requesting credentials, visit: +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: @@ -28,13 +28,9 @@ The repository configuration file is named `edb.repo`. The file resides in `/etc sed -i "s@:@USERNAME:PASSWORD@" /etc/yum.repos.d/edb.repo ``` -!!! Note - If you have `edb.repo` already configured then you can skip this step and go to the next step. - - ### Install EPEL repository -For CentOS 7.x use the following command: +For CentOS 7.x, use the following command: ```text yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm @@ -51,28 +47,24 @@ After creating the repository configuration file and adding a username and passw yum install edb-pgadmin4* ``` -!!! Note - This command installs following packages: - - `edb-pgadmin4` - - `edb-pgadmin4-desktop-common` - `edb-pgadmin4-desktop-gnome` +This command installs following packages: - `edb-pgadmin4-docs` - - `edb-pgadmin4-web` +- `edb-pgadmin4` +- `edb-pgadmin4-desktop-common` +- `edb-pgadmin4-desktop-gnome` +- `edb-pgadmin4-docs` +- `edb-pgadmin4-web` ### Starting pgAdmin 4 in desktop mode -You can use the following command to start pgAdmin 4 in desktop mode: +Use the following command to start pgAdmin 4 in desktop mode: ```text /usr/edb/pgadmin4/bin/pgAdmin4 ``` -You can also use the link on the `Applications` menu to start pgAdmin 4 in desktop mode: +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) @@ -80,18 +72,10 @@ You can also use the link on the `Applications` menu to start pgAdmin 4 in deskt ### 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 to specify the connection properties. To open the `Server` dialog, right-click on the `Servers` node of the tree control, and select `Server` from the `Create` menu. - -![Create Server dialog](images/server_general.png) - -For detailed information about registering your server, visit: - -. - -Then, to connect to your EDB Postgres Advanced Server instance, right click on the server name and select `Connect Server`; provide your password when the `Connect to Server` dialog opens: +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**. -![Connecting to EPAS Server through EDB pgAdmin 4.](images/connect_to_epas_server.png) +For detailed information about registering your server, see the [pgAdmin documentation](https://www.pgadmin.org/docs/pgadmin4/latest/server_dialog.html). -Once you are connected to the server, you can see the `Dashboard` tab as shown below: +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. -![EPAS Server - Dashboard](images/edb_pgadmin4_first_look.png) +After you connect to the server, you can see the **Dashboard** tab. diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/01_package_components.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/01_package_components.mdx index c7a22a72b75..0c95a365307 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/01_package_components.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/01_package_components.mdx @@ -8,14 +8,14 @@ legacyRedirectsGenerated: Packages consist of two main components: -- The *package specification*: This is the public interface, (these are the elements which can be referenced outside the package). We declare all database objects that are to be a part of our package within the specification. -- The *package body*: This contains the actual implementation of all the database objects declared within the package specification. +- 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 which 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. + 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 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: @@ -83,7 +83,7 @@ restriction [, ... ] `package_name` - `package_name` is an identifier assigned to the package - each package must have a name unique within the schema. + `package_name` is an identifier assigned to the package. Each package must have a unique name in the schema. `AUTHID DEFINER` @@ -95,17 +95,17 @@ restriction [, ... ] `declaration` - `declaration` is an identifier of a public variable. A public variable can be accessed from outside of 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` 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, Collections, and `REF CURSORs` +- Variable declaration +- Record declaration +- Collection declaration +- `REF CURSOR` and cursor variable declaration +- `TYPE` definitions for records, ollections, and `REF CURSOR` - Exception -- Object Variable Declaration +- Object variable declaration `proc_name` @@ -113,21 +113,21 @@ restriction [, ... ] `argname` - The name of an argument. The argument is referenced by this name within the function or procedure body. + The name of an argument. The argument is referenced by this name in the function or procedure body. -`IN | IN OUT | OUT` +`IN` | `IN OUT` | `OUT` - The argument mode. `IN` declares the argument for input only. This is the default. `IN OUT` allows the argument to receive a value as well as return a value. `OUT` specifies the argument is for output only. + 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 type(s) of an argument. An argument type may 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. A length must not be specified for any base type - for example, specify `VARCHAR2`, not `VARCHAR2(10`). + 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)`. - The type of a column is referenced by writing `tablename.columnname` `%TYPE`; using this can sometimes help make a procedure independent from changes to the definition of a table. + 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 one is not supplied in the invocation. `DEFAULT` may not be specified for arguments with modes `IN OUT` or `OUT`. + 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` @@ -139,7 +139,7 @@ restriction [, ... ] `DETERMINISTIC` - `DETERMINISTIC` is a synonym for `IMMUTABLE`. A `DETERMINISTIC` function cannot modify the database and always reaches the same result when given the same argument values; it does not 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. + `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` @@ -157,7 +157,7 @@ restriction [, ... ] ## Package body syntax -Package implementation details reside in the package body; the package body may contain objects that are not visible to the package user. EDB Postgres Advanced Server supports the following syntax for the package body: +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: ```text CREATE [ OR REPLACE ] PACKAGE BODY @@ -262,19 +262,19 @@ END; `package_name` - `package_name` is the name of the package for which this is the package body. There must be an existing package specification with this 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 can be accessed by any procedure or function within the package. There can be zero, one, or more private variables. `private_declaration` can be any of the following: + `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` +- Variable declaration +- Record declaration +- Collection declaration +- `REF CURSOR` and cursor variable declaration +- `TYPE` definitions for records, collections, and `REF CURSORs` - Exception -- Object Variable Declaration +- Object variable declaration `proc_name` @@ -286,15 +286,15 @@ END; `declaration` - A variable, type, `REF CURSOR`, or subprogram declaration. If subprogram declarations are included, they must be declared after all other variable, type, and `REF CURSOR` declarations. + 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. Note that a `DECLARE - BEGIN - END` block is considered an SPL statement unto itself. Thus, the function body may contain nested blocks. + 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`, etc. + An exception condition name such as `NO_DATA_FOUND, OTHERS`. `func_name` @@ -302,15 +302,17 @@ END; `rettype` - The return data type, which may be any of the types listed for `argtype`. As for `argtype`, a length must not be specified for `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 + The `DETERMINISTIC` keyword is equivalent to the PostgreSQL `IMMUTABLE` option. - **Note**: If `DETERMINISTIC` is specified for a public function in the package body, it must also be specified for the function declaration in the package specification. (For private functions, there is no function declaration in the package specification.) + !!!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` @@ -318,41 +320,41 @@ END; `argname` - The name of a formal argument. The argument is referenced by this name within the procedure body. + The name of a formal argument. The argument is referenced by this name in the procedure body. -`IN | IN OUT | OUT` +`IN` | `IN OUT` | `OUT` - The argument mode. `IN` declares the argument for input only. This is the default. `IN OUT` allows the argument to receive a value as well as return a value. `OUT` specifies the argument is for output only. + 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 type(s) of an argument. An argument type may 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. A length must not be specified for any base type - for example, specify `VARCHAR2`, not `VARCHAR2(10)`. + 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)`. - The type of a column is referenced by writing `tablename.columnname%TYPE`; using this can sometimes help make a procedure independent from changes to the definition of a table. + 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 one is not supplied in the procedure call. `DEFAULT` may not be specified for arguments with modes `IN OUT` or `OUT`. + 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 are not compatible with Oracle databases; they are extensions to Oracle package syntax provided by EDB Postgres Advanced Server only. +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`. + 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. + 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 cannot be executed in parallel mode. The presence of such a procedure or function forces a serial execution plan. This is the default setting if the `PARALLEL` clause is omitted. + 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 with no restriction. + When set to `SAFE`, the procedure or function can be executed in parallel mode without restriction. `execution_cost` @@ -360,7 +362,7 @@ The following options are not compatible with Oracle databases; they are extensi `result_rows` - `result_rows` is the estimated number of rows that the query planner should expect the function to return. The default is `1000`. + `result_rows` is the estimated number of rows for the query planner to expect the function to return. The default is `1000`. `SET` @@ -374,7 +376,7 @@ The following options are not compatible with Oracle databases; they are extensi `package_initializer` - The statements in the `package_initializer` are executed once per user’s session when the package is first referenced. + 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 and are not supported by Oracle. + 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/14/epas_compat_bip_guide/02_packages/02_creating_packages.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/02_creating_packages.mdx index d992ed87482..80f914567fa 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/02_creating_packages.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/02_creating_packages.mdx @@ -6,11 +6,11 @@ legacyRedirectsGenerated: - "/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 is not an executable piece of code; rather it is a repository of code. When you use a package, you actually execute or make reference to an element within a package. +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 can be referenced 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: +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: ```text -- @@ -43,11 +43,11 @@ IS END emp_admin; ``` -This code sample creates the `emp_admin` package specification. This package specification consists of two functions and two stored procedures. We can also add the `OR REPLACE` clause to the `CREATE PACKAGE` statement for convenience. +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 above `emp_admin` package specification, 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. +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. ```text -- diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/03_referencing_a_package.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/03_referencing_a_package.mdx index 97e521ef5c4..956b9fcb49e 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/03_referencing_a_package.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/03_referencing_a_package.mdx @@ -6,7 +6,7 @@ legacyRedirectsGenerated: - "/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 within a package specification, we use the dot notation. For example: +To reference the types, items, and subprograms that are declared in a package specification, use the dot notation. For example: `package_name.type_name` @@ -14,10 +14,10 @@ To reference the types, items and subprograms that are declared within a package `package_name.subprogram_name` -To invoke a function from the `emp_admin` package specification, execute the following SQL command. +To invoke a function from the `emp_admin` package specification, execute the following SQL command: ```text SELECT emp_admin.get_dept_name(10) FROM DUAL; ``` -Here we are invoking the `get_dept_name` function declared within the package `emp_admin`. We are passing the department number as an argument to the function, which returns the name of the department. Here the value returned should be `ACCOUNTING`, which corresponds to department number `10`. +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/14/epas_compat_bip_guide/02_packages/04_using_packages_with_user_defined_types.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/04_using_packages_with_user_defined_types.mdx index 141849afb40..3cac9e14641 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/04_using_packages_with_user_defined_types.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/04_using_packages_with_user_defined_types.mdx @@ -6,9 +6,9 @@ legacyRedirectsGenerated: - "/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" --- -The following example incorporates the various user-defined types discussed in earlier chapters within the context of a package. +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 along with two functions and two procedures. 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. +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. ```text CREATE OR REPLACE PACKAGE emp_rpt @@ -34,7 +34,7 @@ IS 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`. +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`. ```text CREATE OR REPLACE PACKAGE BODY emp_rpt @@ -103,11 +103,11 @@ BEGIN 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` serves as a department name lookup table in function, `get_dept_name`. +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`. -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 procedure, `fetch_emp`, to retrieve and list the individual rows of the result set. Finally, procedure, `close_refcur`, can be used to close the `REF CURSOR` variable associated with this result set. +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 is passed between the package function and procedures. +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. ```text DECLARE @@ -124,7 +124,7 @@ BEGIN END; ``` -The following is the result of this anonymous block. +The following is the result of this anonymous block: ```text EMPLOYEES IN DEPT #30: SALES @@ -140,7 +140,7 @@ EMPNO ENAME 6 rows were retrieved ``` -The following anonymous block illustrates another means of achieving 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`. +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`. ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/05_dropping_a_package.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/05_dropping_a_package.mdx index d01bef2fc20..3db484a6b7e 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/05_dropping_a_package.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/05_dropping_a_package.mdx @@ -6,13 +6,13 @@ legacyRedirectsGenerated: - "/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 just the package body is as follows: +The syntax for deleting an entire package or the package body is: ```text DROP PACKAGE [ BODY ] package_name; ``` -If the keyword, `BODY`, is omitted, both the package specification and the package body are deleted - i.e., the entire package is dropped. If the keyword, `BODY`, is specified, then only the package body is dropped. The package specification remains intact. `package_name` is the identifier of the package to be dropped. +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`: diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/index.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/index.mdx index 7ae99c5e1e4..2ba278e4f6e 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/index.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/02_packages/index.mdx @@ -5,12 +5,12 @@ legacyRedirectsGenerated: - "/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" --- -This chapter discusses the concept of packages in EDB Postgres Advanced Server. 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: +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: -- Packages provide a convenient means of organizing the functions and procedures that perform a related purpose. Permission to use the package functions and procedures is dependent upon one privilege granted to the entire package. All of the package programs must be referenced with a common name. -- Certain functions, procedures, variables, types, etc. in the package can be declared as *public*. Public entities are visible and can be referenced by other programs that are given `EXECUTE` privilege on the package. 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 is not accessible to others, therefore applications that utilize a package are dependent only upon the information available in the signature – not in the procedural logic itself. -- Other functions, procedures, variables, types, etc. in the package can be declared as *private*. Private entities can be referenced and used by function and procedures within the package, but not by other external applications. Private entities are for use only by programs within the package. -- Function and procedure names can be overloaded within a package. One or more functions/procedures can be defined with the same name, but with different signatures. This provides the capability to create identically named programs that perform the same job, but on different types of input. +- 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.
diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/01_dbms_alert.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/01_dbms_alert.mdx index 614e8bf2501..c0724f5d35c 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/01_dbms_alert.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/01_dbms_alert.mdx @@ -7,22 +7,22 @@ legacyRedirectsGenerated: - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.148.html" --- -The `DBMS_ALERT` package provides the capability to register for, send, and receive alerts. The following table lists the supported procedures: +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` | +| `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 | Signals the alert named, `name`, with `message` | +| `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 above are supported. +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. +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 (located by default in `/opt/PostgresPlus/14AS/data`) with your choice of editor, and edit the `dbms_alert.max_alerts` parameter as shown: +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: ```text dbms_alert.max_alerts = alert_count @@ -52,11 +52,11 @@ REGISTER( VARCHAR2) `name` - Name of the alert to be registered. + Name of the alert to register. ### Examples -The following anonymous block registers for an alert named, `alert_test`, then waits for the signal. +This anonymous block registers for an alert named `alert_test` and then waits for the signal. ```text DECLARE @@ -92,7 +92,7 @@ REMOVE( VARCHAR2) `name` - Name of the alert to be unregistered. + Name of the alert to unregister. ## REMOVEALL @@ -122,7 +122,7 @@ SIGNAL( VARCHAR2, VARCHAR2) ### Examples -The following anonymous block signals an alert for `alert_test`. +This anonymous block signals an alert for `alert_test`. ```text DECLARE @@ -155,7 +155,7 @@ WAITANY( OUT VARCHAR2, OUT VARCHAR2, `status` - Status code returned by the operation. Possible values are: 0 – alert occurred; 1 – timeout occurred. + Status code returned by the operation. Possible values are: `0` – alert occurred; `1` – timeout occurred. `timeout` @@ -163,7 +163,7 @@ WAITANY( OUT VARCHAR2, OUT VARCHAR2, ### Examples -The following anonymous block uses the `WAITANY` procedure to receive an alert named, `alert_test` or `any_alert`: +This anonymous block uses the `WAITANY` procedure to receive an alert named `alert_test` or `any_alert`: ```text DECLARE @@ -233,7 +233,7 @@ WAITONE( VARCHAR2, OUT VARCHAR2, `status` - Status code returned by the operation. Possible values are: 0 – alert occurred; 1 – timeout occurred. + Status code returned by the operation. Possible values are: `0` – alert occurred; `1` – timeout occurred. `timeout` @@ -241,7 +241,7 @@ WAITONE( VARCHAR2, OUT VARCHAR2, ### Examples -The following 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`. +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`. ```text DECLARE @@ -329,7 +329,7 @@ BEGIN END; ``` -The following anonymous block is executed in a session while updates to the `dept` and `emp` tables occur in other sessions: +This anonymous block is executed in a session while updates to the `dept` and `emp` tables occur in other sessions: ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/01_enqueue.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/01_enqueue.mdx index 3f1dba24af1..809f4fdb204 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/01_enqueue.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/01_enqueue.mdx @@ -17,13 +17,13 @@ ENQUEUE( `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. + 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`. + 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`: + `enqueue_options` is a value of the type `enqueue_options_t`: ```text DBMS_AQ.ENQUEUE_OPTIONS_T IS RECORD( @@ -45,7 +45,7 @@ Currently, the only supported parameter values for `enqueue_options_t` are: `message_properties` - `message_properties` is a value of the type, `message_properties_t`: + `message_properties` is a value of the type `message_properties_t`: ```text message_properties_t IS RECORD( @@ -69,21 +69,21 @@ 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 to pass before a message is available for dequeueing or `NO_DELAY`. | +| `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 that to associate with the entry; the default is `NULL`. | +| `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; 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. | +| `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 is not supported; specify a value of `DBMS_AQ.PERSISTENT`. | +| `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`). + 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` diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/02_dequeue.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/02_dequeue.mdx index f6f83438dba..34f7b3802ae 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/02_dequeue.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/02_dequeue.mdx @@ -19,7 +19,7 @@ DEQUEUE( 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`. + 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`: @@ -43,16 +43,16 @@ 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 within the queue that matches the search term.

`NEXT_MESSAGE` – The next message that is 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` – do not wait. | +| `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 if the message should be dequeued | -| `transformation` | Accepted for compatibility, and ignored. | -| `delivery_mode` | Must be `PERSISTENT`; buffered messages are not supported at this time. | +| `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`: +`message_properties` is a value of the type `message_properties_t`: ```text message_properties_t IS RECORD( @@ -78,15 +78,15 @@ 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`. | +| `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. | +| `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. | +| `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 is not supported; specify a value of `DBMS_AQ.PERSISTENT`. | +| `delivery_mode` | This parameter isn't supported. Specify a value of `DBMS_AQ.PERSISTENT`. | `payload` diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/03_register.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/03_register.mdx index d6bb56d1438..499412ff820 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/03_register.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/03_register.mdx @@ -12,7 +12,7 @@ REGISTER( ## Parameters -`reg_list` is a list of type `AQ$_REG_INFO_LIST`; that provides information about each subscription that you would like to register. Each entry within the list is of the type `AQ$_REG_INFO`, and may contain: +`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:
@@ -21,8 +21,8 @@ REGISTER( | 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 should take the form:

`plsql://schema.procedure`

Where:

schema specifies the schema in which the procedure resides.

procedure specifies the name of the procedure to notify. | +| `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` @@ -56,4 +56,4 @@ subscription2, subscription3); / ``` -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`. +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/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/04_unregister.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/04_unregister.mdx index 34aca1d7dc2..993e77e0c96 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/04_unregister.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/04_unregister.mdx @@ -14,7 +14,7 @@ UNREGISTER( `reg_list` -`reg_list` is a list of type `AQ$_REG_INFO_LIST`; that provides information about each subscription that you would like to register. Each entry within the list is of the type `AQ$_REG_INFO`, and may contain: + `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:
@@ -23,8 +23,8 @@ UNREGISTER( | 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 should take the form:

`plsql://schema.procedure`

Where:

schema specifies the schema in which the procedure resides.

procedure specifies the name of the procedure to notify. | +| `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` @@ -57,4 +57,4 @@ subscription2, subscription3); / ``` -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.unregister`. +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/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/index.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/index.mdx index 5c704f4156a..e3629e1ea24 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/index.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/index.mdx @@ -5,9 +5,9 @@ legacyRedirectsGenerated: - "/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; 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 a queue or remove messages from a queue, or register or unregister a PL/SQL callback procedure. +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 (non-compatible) functionality for the `DBMS_AQ` package with SQL commands, see the *Database Compatibility for Oracle Developers SQL Guide* for detailed information about the following SQL commands: +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` @@ -27,26 +27,26 @@ The `DBMS_AQ` package provides procedures that allow you to enqueue a message, d 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 the constants listed below: +EDB Postgres Advanced Server supports use of these constants: -| Constant | Description | For Parameters | +| 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 (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 is not found, the default. | `dequeue_options_t.wait` | -| `DBMS_AQ.NO_WAIT (0)` | Don't wait if a message that matches the search term is not found. | `dequeue_options_t.wait` | +| `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)` | The message should be stored in a table. | `enqueue_options_t.delivery_mode` | +| `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 has been 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` | @@ -62,8 +62,8 @@ The `DBMS_AQ` configuration parameters listed in the following table can be defi | `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 `DBMS_AQ`’s hash table of databases. The default value is 1024. | -| `dbms_aq.max_pending_retries` | The size of `DBMS_AQ`’s hash table of pending retries. The default value is 1024. | +| `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. |
diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/01_alter_queue.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/01_alter_queue.mdx index 6383b413257..6c6c44f09cc 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/01_alter_queue.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/01_alter_queue.mdx @@ -25,11 +25,11 @@ ALTER_QUEUE( `retry_delay` - `retry_delay` specifies the number of seconds until a message is scheduled for re-processing after a `ROLLBACK`. Specify `0` to indicate that the message should be retried immediately (the default). + `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 the message should not be retained after dequeueing, or `INFINITE` to retain the message forever. + `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` diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/02_alter_queue_table.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/02_alter_queue_table.mdx index 02b47de4256..cd7384d1af1 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/02_alter_queue_table.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/02_alter_queue_table.mdx @@ -24,11 +24,11 @@ ALTER_QUEUE_TABLE ( `primary_instance` - `primary_instance` is accepted for compatibility and stored, but is ignored. + `primary_instance` is accepted for compatibility and stored but is ignored. `secondary_instance` - `secondary_instance` is accepted for compatibility, but is ignored. + `secondary_instance` is accepted for compatibility but is ignored. ## Example @@ -40,4 +40,4 @@ EXEC DBMS_AQADM.ALTER_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. +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/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/03_create_queue.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/03_create_queue.mdx index d8fcb22850e..90111b8f293 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/03_create_queue.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/03_create_queue.mdx @@ -31,21 +31,21 @@ CREATE_QUEUE( 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.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. + `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`. + `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 re-processing after a `ROLLBACK`. Specify `0` to indicate that the message should be retried immediately (the default). + `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 the message should not be retained after dequeueing, or `INFINITE` to retain the message forever. + `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` diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/04_create_queue_table.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/04_create_queue_table.mdx index 39dbee4f9ca..f389001a1da 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/04_create_queue_table.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/04_create_queue_table.mdx @@ -28,20 +28,20 @@ CREATE_QUEUE_TABLE ( `queue_payload_type` - The user-defined type of the data that is stored in the queue table. To specify a `RAW` data type, you must create a user-defined type that identifies a `RAW` 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. +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` may be one or more of the following: + `storage_clause` can be one or more of the following: ```text TABLESPACE tablespace_name, PCTFREE integer, PCTUSED integer, INITRANS integer, MAXTRANS integer or STORAGE storage_option. ``` -`storage_option` may be one or more of the following: +`storage_option` can be one or more of the following: ```text MINEXTENTS integer, MAXEXTENTS integer, PCTINCREASE integer, INITIAL @@ -51,7 +51,7 @@ 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`: + `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` @@ -63,7 +63,7 @@ POOL {KEEP|RECYCLE|DEFAULT}. `multiple_consumers` - `multiple_consumers` queue tables is not supported. + `multiple_consumers` queue tables isn't supported. `message_grouping` @@ -75,23 +75,23 @@ POOL {KEEP|RECYCLE|DEFAULT}. `auto_commit` - `auto_commit` is accepted for compatibility, but is ignored. + `auto_commit` is accepted for compatibility but is ignored. `primary_instance` - `primary_instance` is accepted for compatibility and stored, but is ignored. + `primary_instance` is accepted for compatibility and stored but is ignored. `secondary_instance` - `secondary_instance` is accepted for compatibility, but is ignored. + `secondary_instance` is accepted for compatibility but is ignored. `compatible` - `compatible` is accepted for compatibility, but is ignored. + `compatible` is accepted for compatibility but is ignored. `secure` - `secure` is accepted for compatibility, but is ignored. + `secure` is accepted for compatibility but is ignored. ## Example @@ -110,4 +110,4 @@ EXEC DBMS_AQADM.CREATE_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`. +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/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/05_drop_queue.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/05_drop_queue.mdx index 04346eaa1b4..ed577ff3e3f 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/05_drop_queue.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/05_drop_queue.mdx @@ -14,11 +14,11 @@ DROP_QUEUE( `queue_name` - The name of the queue that you wish to drop. + The name of the queue that you want to drop. `auto_commit` - `auto_commit` is accepted for compatibility, but is ignored. + `auto_commit` is accepted for compatibility but is ignored. ## Example diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/06_drop_queue_table.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/06_drop_queue_table.mdx index ce5068298da..84655880f34 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/06_drop_queue_table.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/06_drop_queue_table.mdx @@ -21,13 +21,12 @@ DROP_QUEUE_TABLE( 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. +- 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. + `auto_commit` is accepted for compatibility but is ignored. ## Example diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/07_purge_queue_table.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/07_purge_queue_table.mdx index b8e25db285e..fbcd15f6fa3 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/07_purge_queue_table.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/07_purge_queue_table.mdx @@ -15,7 +15,7 @@ PURGE_QUEUE_TABLE( `queue_table` - `queue_table` specifies the name of the queue table from which you are deleting a message. + `queue_table` specifies the name of the queue table from which you're deleting a message. `purge_condition` @@ -27,7 +27,7 @@ PURGE_QUEUE_TABLE( | Attribute | Type | Description | | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------- | -| `block` | Boolean | Specify `TRUE` if an exclusive lock should be held on all queues within the table; the default is `FALSE`. | +| `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 diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/08_start_queue.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/08_start_queue.mdx index 1af7ec4ae40..a4d7feeb247 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/08_start_queue.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/08_start_queue.mdx @@ -15,15 +15,15 @@ START_QUEUE( `queue_name` - `queue_name` specifies the name of the queue that you are starting. + `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. + 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. + Specify `TRUE` to enable dequeueing (the default) or `FALSE` to leave the current setting unchanged. ## Example diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/09_stop_queue.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/09_stop_queue.mdx index 8a864bd0a7d..842d1e034c0 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/09_stop_queue.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/09_stop_queue.mdx @@ -16,19 +16,19 @@ STOP_QUEUE( `queue_name` - `queue_name` specifies the name of the queue that you are stopping. + `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. + 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. + 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. + 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 diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/index.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/index.mdx index 22b7a7337bd..2b9b92da51a 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/index.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/03_dbms_aqadm/index.mdx @@ -5,9 +5,9 @@ legacyRedirectsGenerated: - "/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; 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 a queue or remove messages from a queue, or register or unregister a PL/SQL callback procedure. +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 the *Database Compatibility for Oracle Developers SQL Guide* for detailed information about the following SQL commands: +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` @@ -16,7 +16,7 @@ EDB Postgres Advanced Server also provides extended (non-compatible) functionali - `DROP QUEUE` - `DROP QUEUE TABLE` -The `DBMS_AQADM` package provides procedures that allow you to create and manage queues and queue tables. +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 | | -------------------- | ----------- | ----------------------------------------------------------------- | @@ -28,20 +28,18 @@ The `DBMS_AQADM` package provides procedures that allow you to create and manage | `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 | +| `STOP_QUEUE` | n/a | Make a queue unavailable for enqueueing and dequeueing procedures. | -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 above are supported. - -EDB Postgres Advanced Server supports use of the arguments listed below: +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.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)` | The message should be stored in a table. | `enqueue_options_t.delivery_mode` | +| `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` | diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/01_decrypt.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/01_decrypt.mdx index f9f33a99ba9..b1c31e51e1e 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/01_decrypt.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/01_decrypt.mdx @@ -2,7 +2,7 @@ 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: +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: ```text DECRYPT @@ -36,11 +36,11 @@ When invoked as a procedure, `DECRYPT` returns `BLOB` or `CLOB` data to a user-s `src` - `src` specifies the source data to decrypt. If you are invoking `DECRYPT` as a function, specify `RAW` data; if invoking `DECRYPT` as a procedure, specify `BLOB` or `CLOB` data. + `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. This should match the type specified when the `src` was encrypted. EDB Postgres Advanced Server supports the following block cipher algorithms, modifiers and cipher suites: + `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 | | | ---------------------------------- | ----------------------------------------------------------- | @@ -63,7 +63,7 @@ When invoked as a procedure, `DECRYPT` returns `BLOB` or `CLOB` data to a user-s `key` - `key` specifies the user-defined decryption key. This should match the key specified when the `src` was encrypted. + `key` specifies the user-defined decryption key. Match the key specified when the `src` was encrypted. `iv` @@ -71,7 +71,7 @@ When invoked as a procedure, `DECRYPT` returns `BLOB` or `CLOB` data to a user-s ## Examples -The following example uses the `DBMS_CRYPTO.DECRYPT` function to decrypt an encrypted password retrieved from the `passwords` table: +This example uses the `DBMS_CRYPTO.DECRYPT` function to decrypt an encrypted password retrieved from the `passwords` table: ```text CREATE TABLE passwords @@ -93,4 +93,4 @@ BEGIN END; ``` -Note that when calling `DECRYPT`, you must pass the same cipher type, key value and initialization vector that was used when `ENCRYPTING` the target. +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/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/02_encrypt.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/02_encrypt.mdx index 0bf3b836668..193fb644367 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/02_encrypt.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/02_encrypt.mdx @@ -2,7 +2,7 @@ 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: +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: ```text ENCRYPT @@ -36,11 +36,11 @@ When invoked as a procedure, `ENCRYPT` returns `BLOB` or `CLOB` data to a user-s `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. + `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 listed below: + `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 | | | ---------------------------------- | ----------------------------------------------------------- | @@ -71,7 +71,7 @@ When invoked as a procedure, `ENCRYPT` returns `BLOB` or `CLOB` data to a user-s ## Examples -The following example uses the `DBMS_CRYPTO.DES_CBC_PKCS5` Block Cipher Suite (a pre-defined set of algorithms and modifiers) to encrypt a value retrieved from the `passwords` table: +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: ```text CREATE TABLE passwords @@ -90,4 +90,4 @@ BEGIN 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`. +`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/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/03_hash.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/03_hash.mdx index 1d2ad830704..d2805285fad 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/03_hash.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/03_hash.mdx @@ -16,11 +16,11 @@ HASH `src` - `src` specifies the value for which the hash value is generated. You can specify a `RAW`, a `BLOB`, or a `CLOB` value. + `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 listed below: + `typ` specifies the `HASH` function type. EDB Postgres Advanced Server supports the `HASH` function types shown in the table. | HASH functions | | | ------------------ | ------------------------ | @@ -30,7 +30,7 @@ HASH ## Examples -The following example uses `DBMS_CRYPTO.HASH` to find the `md5` hash value of the string, `cleartext source`: +This example uses `DBMS_CRYPTO.HASH` to find the `md5` hash value of the string, `cleartext source`: ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/04_mac.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/04_mac.mdx index e8c2fd33ff0..2d08d27f840 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/04_mac.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/04_mac.mdx @@ -20,7 +20,7 @@ MAC `typ` - `typ` specifies the `MAC` function used. EDB Postgres Advanced Server supports the `MAC` functions listed below. + `typ` specifies the `MAC` function used. EDB Postgres Advanced Server supports the `MAC` functions shown in the table. | MAC functions | | | ----------------- | ------------------------ | @@ -33,7 +33,7 @@ MAC ## Examples -The following example finds the hashed `MAC` value of the string `cleartext source`: +This example finds the hashed `MAC` value of the string `cleartext source`: ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/05_randombytes.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/05_randombytes.mdx index 598f2c4d20f..d383d216327 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/05_randombytes.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/05_randombytes.mdx @@ -13,11 +13,11 @@ RANDOMBYTES `number_bytes` - `number_bytes` specifies the number of random bytes to be returned + `number_bytes` specifies the number of random bytes to return. ## Examples -The following example uses `RANDOMBYTES` to return a value that is `1024` bytes long: +This example uses `RANDOMBYTES` to return a value that is 1024 bytes long: ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/06_randominteger.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/06_randominteger.mdx index 06acd9902e0..ef81cd89f84 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/06_randominteger.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/06_randominteger.mdx @@ -2,7 +2,7 @@ title: "RANDOMINTEGER" --- -The `RANDOMINTEGER()` function returns a random `INTEGER` between `0` and `268,435,455`. The signature is: +The `RANDOMINTEGER()` function returns a random integer between `0` and `268,435,455`. The signature is: ```text RANDOMINTEGER() RETURNS INTEGER @@ -10,7 +10,7 @@ RANDOMINTEGER() RETURNS INTEGER ## Examples -The following example uses the `RANDOMINTEGER` function to return a cryptographically strong random `INTEGER` value: +This example uses the `RANDOMINTEGER` function to return a cryptographically strong random `INTEGER` value: ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/07_randomnumber.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/07_randomnumber.mdx index 6b78fa4bcf8..0d94c3d9405 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/07_randomnumber.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/07_randomnumber.mdx @@ -2,7 +2,7 @@ title: "RANDOMNUMBER" --- -The `RANDOMNUMBER()` function returns a random `NUMBER` between `0` and `268,435,455`. The signature is: +The `RANDOMNUMBER()` function returns a random number between 0 and 268,435,455. The signature is: ```text RANDOMNUMBER() RETURNS NUMBER @@ -10,7 +10,7 @@ RANDOMNUMBER() RETURNS NUMBER ## Examples -The following example uses the `RANDOMNUMBER` function to return a cryptographically strong random number: +This example uses the `RANDOMNUMBER` function to return a cryptographically strong random number: ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/index.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/index.mdx index 2a65305f072..5773a32c656 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/index.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/index.mdx @@ -7,9 +7,9 @@ legacyRedirectsGenerated: - "/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 `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 following table lists the `DBMS_CRYPTO` Functions and Procedures. +The table lists the `DBMS_CRYPTO` functions and procedures. | Function/procedure | Return type | Description | | --------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------- | @@ -24,8 +24,8 @@ The following table lists the `DBMS_CRYPTO` Functions and Procedures. | `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.` | +| `RANDOMINTEGER()` | `INTEGER` | Returns a random integer. | +| `RANDOMNUMBER()` | `NUMBER` | Returns a random number. | `DBMS_CRYPTO` functions and procedures support the following error messages: @@ -35,9 +35,9 @@ The following table lists the `DBMS_CRYPTO` Functions and Procedures. `ORA-28827 - DBMS_CRYPTO.CipherSuiteInvalid` -Unlike Oracle, EDB Postgres Advanced Server doesn't return error `ORA-28233` if you re-encrypt previously encrypted information. +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, and `CLOB` is a synonym for `TEXT`. +`RAW` and `BLOB` are synonyms for the PostgreSQL `BYTEA` data type. `CLOB` is a synonym for `TEXT`.
diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/01_broken.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/01_broken.mdx index 678429b5221..1a2d18eef07 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/01_broken.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/01_broken.mdx @@ -2,7 +2,7 @@ title: "BROKEN" --- -The `BROKEN` procedure sets the state of a job to either broken or not broken. A broken job cannot be executed except by using the `RUN` procedure. +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. ```text BROKEN( BINARY_INTEGER, BOOLEAN [, DATE ]) @@ -12,11 +12,11 @@ BROKEN( BINARY_INTEGER, BOOLEAN [, DATE ]) `job` - Identifier of the job to be set as broken or not broken. + 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. Broken jobs cannot be run except by using the `RUN` procedure. + 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` diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/02_change.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/02_change.mdx index 5099c4b241e..9f6fd1e1167 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/02_change.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/02_change.mdx @@ -2,7 +2,7 @@ title: "CHANGE" --- -The `CHANGE` procedure modifies certain job attributes including the stored procedure to be run, the next date/time the job is to be run, and how often it is to be run. +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. ```text CHANGE( BINARY_INTEGER VARCHAR2, DATE, @@ -17,23 +17,23 @@ CHANGE( BINARY_INTEGER VARCHAR2, DATE, `what` - Stored procedure name. Set this parameter to null if the existing value is to remain unchanged. + Stored procedure name. Set this parameter to null if you want the existing value to remain unchanged. `next_date` - Date/time when the job is to be run next. Set this parameter to null if the existing value is to remain unchanged. + 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 the job is to run. Set this parameter to null if the existing value is to remain unchanged. + 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. + This argument is ignored but is included for compatibility. `force` - This argument is ignored, but is included for compatibility. + This argument is ignored but is included for compatibility. ## Examples diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/03_interval.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/03_interval.mdx index f075313b3b5..c8bf97a6e17 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/03_interval.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/03_interval.mdx @@ -2,7 +2,7 @@ title: "INTERVAL" --- -The `INTERVAL` procedure sets the frequency of how often a job is to be run. +The `INTERVAL` procedure sets how often to run a job. ```text INTERVAL( BINARY_INTEGER, VARCHAR2) @@ -16,7 +16,7 @@ INTERVAL( BINARY_INTEGER, VARCHAR2) `interval` - Date function that when evaluated, provides the next date/time the job is to be run. If `interval` is `NULL` and the job is complete, the job is removed from the queue. + 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 diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/04_next_date.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/04_next_date.mdx index 12191ceaebd..42dc45c272d 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/04_next_date.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/04_next_date.mdx @@ -2,7 +2,7 @@ title: "NEXT_DATE" --- -The `NEXT_DATE` procedure sets the date/time of when the job is to be run next. +The `NEXT_DATE` procedure sets the date/time to run the job next. ```text NEXT_DATE( BINARY_INTEGER, DATE) @@ -12,11 +12,11 @@ NEXT_DATE( BINARY_INTEGER, DATE) `job` - Identifier of the job whose next run date is to be set. + Identifier of the job whose next run date you want to set. `next_date` - Date/time when the job is to be run next. + Date/time when you want the job run next. ## Examples diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/05_remove.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/05_remove.mdx index 231d5f60100..512d6e4bc77 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/05_remove.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/05_remove.mdx @@ -2,7 +2,7 @@ title: "REMOVE" --- -The `REMOVE` procedure deletes the specified job from the database. The job must be resubmitted using the `SUBMIT` procedure in order to have it executed again. Note that the stored procedure that was associated with the job is not deleted. +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. ```text REMOVE( BINARY_INTEGER) @@ -12,7 +12,7 @@ REMOVE( BINARY_INTEGER) `job` - Identifier of the job that is to be removed from the database. + Identifier of the job to remove from the database. ## Examples diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/06_run.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/06_run.mdx index 58aa286782f..6b5f00bf215 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/06_run.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/06_run.mdx @@ -2,7 +2,7 @@ title: "RUN" --- -The `RUN` procedure forces the job to be run, even if its state is broken. +The `RUN` procedure forces the job to run even if its state is broken. ```text RUN( BINARY_INTEGER) @@ -12,11 +12,11 @@ RUN( BINARY_INTEGER) `job` - Identifier of the job to be run. + Identifier of the job to run. ## Examples -Force a job to be run. +Force a job to run. ```text BEGIN diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/07_submit.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/07_submit.mdx index df07660292a..8ea1d7ffbba 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/07_submit.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/07_submit.mdx @@ -2,7 +2,11 @@ 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 be executed, when the job is to be first run, and a date function that calculates the next date/time the job is to be run. +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 ```text SUBMIT( OUT BINARY_INTEGER, VARCHAR2 @@ -17,26 +21,26 @@ SUBMIT( OUT BINARY_INTEGER, VARCHAR2 `what` - Name of the stored procedure to be executed by the job. + Name of the stored procedure for the job to execute. `next_date` - Date/time when the job is to be run next. The default is `SYSDATE`. + Date/time to run the job next. The default is `SYSDATE`. `interval` - Date function that when evaluated, provides the next date/time the job is to run. If `interval` is set to null, then the job is run only once. Null is the default. + 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`. + 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 is not supported in this implementation of `SUBMIT()`. It is included for compatibility only. + The `no_parse` option isn't supported in this implementation of `SUBMIT()`. It's included only for compatibility. ## Examples -The following example creates a job using the stored procedure `job_proc`. The job executes immediately and runs once a day thereafter as set by the `interval` parameter, `SYSDATE + 1`. +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`. ```text DECLARE @@ -50,7 +54,7 @@ END; jobid: 104 ``` -The job immediately executes procedure, `job_proc`, populating table, `jobrun`, with a row: +The job immediately executes the procedure `job_proc`, populating the table `jobrun` with a row: ```text SELECT * FROM jobrun; diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/08_what.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/08_what.mdx index 68a810c5342..37aedf64c73 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/08_what.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/08_what.mdx @@ -12,11 +12,11 @@ WHAT( BINARY_INTEGER, VARCHAR2) `job` - Identifier of the job for which the stored procedure is to be changed. + Identifier of the job whose stored procedure you want to change. `what` - Name of the stored procedure to be executed. + Name of the stored procedure to execute. ## Examples diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/index.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/index.mdx index 8686bc78f59..6eefd2d7669 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/index.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/05_dbms_job/index.mdx @@ -7,38 +7,38 @@ legacyRedirectsGenerated: - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.150.html" --- -The `DBMS_JOB` package provides for the creation, scheduling, and managing of jobs. A job runs a stored procedure which has been previously stored in the database. The `SUBMIT` procedure is used to create and store a job definition. A job identifier is assigned to a job along with its associated stored procedure and the attributes describing when and how often the job is to be run. +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 prior to using `DBMS_JOB`. If you attempt to use this package to schedule a job after uninstalling `pgAgent, DBMS_JOB` throws an error. `DBMS_JOB` verifies that `pgAgent` is installed, but does not verify that the service is running. +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: +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 the job is to be run. | +| `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 | Forces execution of a job even if it is marked broken. | -| `SUBMIT(job OUT, what [, next_date [, interval [, no_parse ]]])` | n/a | Creates a job and stores its definition in 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: +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: ```text CREATE EXTENSION pgagent; CREATE EXTENSION dbms_job; ``` -When and how often a job is run is dependent upon two interacting parameters – `next_date` and `interval`. The `next_date` parameter is a date/time value that specifies the next date/time when the job is to be executed. The `interval` parameter is a string that contains a date function that evaluates to a date/time value. +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. -Just prior to any execution of the job, 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 re-evaluated prior to each job execution, supplying the `next_date` date/time for the next execution. +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 - The database user must be the same that created a job and schedule to start the `pgAgent` server and execute the job. + 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 following stored procedure, `job_proc`, which simply inserts a timestamp into table, `jobrun`, containing a single `VARCHAR2` column. +The following examples use the stored procedure `job_proc`. The procedure inserts a timestamp into the table `jobrun`, which contains a single column, `VARCHAR2`. ```text CREATE TABLE jobrun ( diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/01_append.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/01_append.mdx index 2a957a24d8e..17fed2d485b 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/01_append.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/01_append.mdx @@ -2,7 +2,7 @@ title: "APPEND" --- -The `APPEND` procedure provides the capability to append one large object to another. Both large objects must be of the same type. +The `APPEND` procedure appends one large object to another. Both large objects must be the same type. ```text APPEND( IN OUT { BLOB | CLOB }, { BLOB | CLOB }) diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/02_compare.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/02_compare.mdx index 3911340544c..214286d10d1 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/02_compare.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/02_compare.mdx @@ -14,11 +14,11 @@ The `COMPARE` procedure performs an exact byte-by-byte comparison of two large o `lob_1` - Large object locator of the first large object to be compared. Must be the same data type as `lob_2`. + 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 be compared. Must be the same data type as `lob_1`. + Large object locator of the second large object to compare. Must be the same data type as `lob_1`. `amount` @@ -26,12 +26,12 @@ The `COMPARE` procedure performs an exact byte-by-byte comparison of two large o `offset_1` - Position within the first large object to begin the comparison. The first byte/character is offset 1. The default is 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 within the second large object to begin the comparison. The first byte/character is offset 1. The default is 1. + 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. Non-zero, if the objects are not the same. `NULL` if `amount`, `offset_1`, or `offset_2` are less than zero. + 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/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/03_converttoblob.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/03_converttoblob.mdx index 2c34fd2db67..2b95f048a87 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/03_converttoblob.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/03_converttoblob.mdx @@ -2,7 +2,7 @@ title: "CONVERTTOBLOB" --- -The `CONVERTTOBLOB` procedure provides the capability to convert character data to binary. +The `CONVERTTOBLOB` procedure converts character data to binary. ```text CONVERTTOBLOB( IN OUT BLOB, CLOB, @@ -15,19 +15,19 @@ CONVERTTOBLOB( IN OUT BLOB, CLOB, `dest_lob` - `BLOB` large object locator to which the character data is to be converted. + `BLOB` large object locator to which to convert the character data. `src_clob` - `CLOB` large object locator of the character data to be converted. + `CLOB` large object locator of the character data to convert. `amount` - Number of characters of `src_clob` to be converted. + Number of characters of `src_clob` to convert. `dest_offset IN` - Position in bytes in the destination `BLOB` where writing of the source `CLOB` should begin. The first byte is offset 1. + 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` @@ -35,7 +35,7 @@ CONVERTTOBLOB( IN OUT BLOB, CLOB, `src_offset IN` - Position in characters in the source `CLOB` where conversion to the destination `BLOB` should begin. The first character is offset 1. + 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` @@ -43,11 +43,11 @@ CONVERTTOBLOB( IN OUT BLOB, CLOB, `blob_csid` - Character set ID of the converted, destination `BLOB`. + 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. + Language context for the conversion. The default value of `0` is typically used for this setting. `lang_context OUT` @@ -55,4 +55,4 @@ CONVERTTOBLOB( IN OUT BLOB, CLOB, `warning` - 0 if the conversion was successful, 1 if an inconvertible character was encountered. + `0` if the conversion was successful, `1` if a character can't be converted. diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/04_converttoclob.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/04_converttoclob.mdx index 3fe04b5f72c..15e3944e4b2 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/04_converttoclob.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/04_converttoclob.mdx @@ -2,7 +2,7 @@ title: "CONVERTTOCLOB" --- -The `CONVERTTOCLOB` procedure provides the capability to convert binary data to character. +The `CONVERTTOCLOB` procedure converts binary data to character. ```text CONVERTTOCLOB( IN OUT CLOB, BLOB, @@ -15,19 +15,19 @@ CONVERTTOCLOB( IN OUT CLOB, BLOB, `dest_lob` - `CLOB` large object locator to which the binary data is to be converted. + `CLOB` large object locator to which to convert the binary data. `src_blob` - `BLOB` large object locator of the binary data to be converted. + `BLOB` large object locator of the binary data to convert. `amount` - Number of bytes of `src_blob` to be converted. + Number of bytes of `src_blob` to convert. `dest_offset IN` - Position in characters in the destination `CLOB` where writing of the source `BLOB` should begin. The first character is offset 1. + 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` @@ -35,7 +35,7 @@ CONVERTTOCLOB( IN OUT CLOB, BLOB, `src_offset IN` - Position in bytes in the source `BLOB` where conversion to the destination `CLOB` should begin. The first byte is offset 1. + 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` @@ -43,11 +43,11 @@ CONVERTTOCLOB( IN OUT CLOB, BLOB, `blob_csid` - Character set ID of the converted, destination `CLOB`. + 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. + Language context for the conversion. The default value of `0` is typically used for this setting. `lang_context OUT` @@ -55,4 +55,4 @@ CONVERTTOCLOB( IN OUT CLOB, BLOB, `warning` - 0 if the conversion was successful, 1 if an inconvertible character was encountered. + `0` if the conversion was successful, `1` if a character can't be converted. diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/05_copy.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/05_copy.mdx index 03030d6a9eb..d62d9cbea66 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/05_copy.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/05_copy.mdx @@ -2,7 +2,7 @@ title: "COPY" --- -The `COPY` procedure provides the capability to copy one large object to another. The source and destination large objects must be the same data type. +The `COPY` procedure copies one large object to another. The source and destination large objects must be the same data type. ```text COPY( IN OUT { BLOB | CLOB }, @@ -15,20 +15,20 @@ COPY( IN OUT { BLOB | CLOB }, `dest_lob` - Large object locator of the large object to which `src_lob` is to be copied. Must be the same data type as `src_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 be copied to `dest_lob`. Must be the same data type as `dest_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 be copied. + Number of bytes/characters of `src_lob` to copy. `dest_offset` - Position in the destination large object where writing of the source large object should begin. The first position is offset 1. The default is 1. + 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 copying to the destination large object should begin. The first position is offset 1. The default is 1. + 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/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/06_erase.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/06_erase.mdx index e716d717615..e2eb369f8af 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/06_erase.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/06_erase.mdx @@ -2,7 +2,7 @@ title: "ERASE" --- -The `ERASE` procedure provides the capability to erase a portion of a large object. To erase a large object means to replace the specified portion with zero-byte fillers for `BLOBs` or with spaces for `CLOBs`. The actual size of the large object is not altered. +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. ```text ERASE( IN OUT { BLOB | CLOB }, IN OUT INTEGER @@ -13,16 +13,16 @@ ERASE( IN OUT { BLOB | CLOB }, IN OUT INTEGER `lob_loc` - Large object locator of the large object to be erased. + Large object locator of the large object to erase. `amount IN` - Number of bytes/characters to be erased. + Number of bytes/characters to erase. `amount OUT` - Number of bytes/characters actually erased. This value can be smaller than the input value if the end of the large object is reached before `amount` bytes/characters have been erased. + 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 is to begin. The first byte/character is position 1. The default is 1. + 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/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/07_get_storage_limit.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/07_get_storage_limit.mdx index 69095defcaa..4b3b14ddcb8 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/07_get_storage_limit.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/07_get_storage_limit.mdx @@ -18,4 +18,4 @@ The `GET_STORAGE_LIMIT` function returns the limit on the largest allowable larg `lob_loc` - This parameter is ignored, but is included for compatibility. + This parameter is ignored but is included for compatibility. diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/08_getlength.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/08_getlength.mdx index 70461ee3636..578ec47ba75 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/08_getlength.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/08_getlength.mdx @@ -14,8 +14,8 @@ The `GETLENGTH` function returns the length of a large object. `lob_loc` - Large object locator of the large object whose length is to be obtained. + Large object locator of the large object whose length to obtain. `amount` - Length of the large object in bytes for `BLOBs` or characters for `CLOBs`. + Length of the large object for `BLOB` or characters for `CLOB`, in bytes. diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/09_instr.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/09_instr.mdx index 256ec6c366d..73d6d6285c7 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/09_instr.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/09_instr.mdx @@ -2,7 +2,7 @@ title: "INSTR" --- -The `INSTR` function returns the location of the nth occurrence of a given pattern within a large object. +The `INSTR` function returns the location of the nth occurrence of a given pattern in a large object. ```text INTEGER INSTR( { BLOB | CLOB }, @@ -13,15 +13,15 @@ The `INSTR` function returns the location of the nth occurrence of a given patte `lob_loc` - Large object locator of the large object in which to search for pattern. + 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`. + 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 within `lob_loc` to start search for `pattern`. The first byte/character is position 1. The default is 1. + Position in `lob_loc` to start search for `pattern`. The first byte/character is position 1. The default is 1. `nth` @@ -29,4 +29,4 @@ The `INSTR` function returns the location of the nth occurrence of a given patte `position` - Position within the large object where `pattern` appears the nth time specified by `nth` starting from the position given by `offset`. + 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/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/10_read.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/10_read.mdx index 718b5757f04..f80dedf28c3 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/10_read.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/10_read.mdx @@ -2,7 +2,7 @@ title: "READ" --- -The `READ` procedure provides the capability to read a portion of a large object into a buffer. +The `READ` procedure reads a portion of a large object into a buffer. ```text READ( { BLOB | CLOB }, IN OUT BINARY_INTEGER, @@ -13,7 +13,7 @@ READ( { BLOB | CLOB }, IN OUT BINARY_INTEGER, `lob_loc` - Large object locator of the large object to be read. + Large object locator of the large object to read. `amount IN` @@ -21,7 +21,7 @@ READ( { BLOB | CLOB }, IN OUT BINARY_INTEGER, `amount OUT` - Number of bytes/characters actually read. If there is no more data to be read, then `amount` returns 0 and a `DATA_NOT_FOUND` exception is thrown. + 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` diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/11_substr.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/11_substr.mdx index 3a659a5d640..4e832f9341e 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/11_substr.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/11_substr.mdx @@ -2,7 +2,7 @@ title: "SUBSTR" --- -The `SUBSTR` function provides the capability to return a portion of a large object. +The `SUBSTR` function returns a portion of a large object. ```text { RAW | VARCHAR2 } SUBSTR( { BLOB | CLOB } @@ -13,16 +13,16 @@ The `SUBSTR` function provides the capability to return a portion of a large obj `lob_loc` - Large object locator of the large object to be read. + Large object locator of the large object to read. `amount` - Number of bytes/characters to be returned. Default is 32,767. + Number of bytes/characters to return. Default is 32,767. `offset` - Position within the large object to begin returning data. The first byte/character is position 1. The default is 1. + 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 be 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`. + 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/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/12_trim.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/12_trim.mdx index b7ec3935e3f..244f22ae6ae 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/12_trim.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/12_trim.mdx @@ -2,7 +2,7 @@ title: "TRIM" --- -The `TRIM` procedure provides the capability to truncate a large object to the specified length. +The `TRIM` procedure truncates a large object to the specified length. ```text TRIM( IN OUT { BLOB | CLOB }, INTEGER) @@ -12,8 +12,8 @@ TRIM( IN OUT { BLOB | CLOB }, INTEGER) `lob_loc` - Large object locator of the large object to be trimmed. + Large object locator of the large object to trim. `newlen` - Number of bytes/characters to which the large object is to be trimmed. + Number of bytes/characters to which you want to trim the large object. diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/13_write.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/13_write.mdx index 05ec88b5e27..f59057797ae 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/13_write.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/13_write.mdx @@ -2,7 +2,7 @@ title: "WRITE" --- -The `WRITE` procedure provides the capability to write 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. +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. ```text WRITE( IN OUT { BLOB | CLOB }, @@ -14,11 +14,11 @@ WRITE( IN OUT { BLOB | CLOB }, `lob_loc` - Large object locator of the large object to be written. + Large object locator of the large object to write. `amount` - The number of bytes/characters in `buffer` to be written to the large object. + The number of bytes/characters in `buffer` to write to the large object. `offset` @@ -26,4 +26,4 @@ WRITE( IN OUT { BLOB | CLOB }, `buffer` - Contains data to be written 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`. + 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/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/14_writeappend.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/14_writeappend.mdx index 56164496f4f..8cebee13d15 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/14_writeappend.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/14_writeappend.mdx @@ -2,7 +2,7 @@ title: "WRITEAPPEND" --- -The `WRITEAPPEND` procedure provides the capability to add data to the end of a large object. +The `WRITEAPPEND` procedure adds data to the end of a large object. ```text WRITEAPPEND( IN OUT { BLOB | CLOB }, @@ -13,12 +13,12 @@ WRITEAPPEND( IN OUT { BLOB | CLOB }, `lob_loc` - Large object locator of the large object to which data is to be appended. + Large object locator of the large object to which you want to append the data. `amount` - Number of bytes/characters from `buffer` to be appended the large object. + Number of bytes/characters from `buffer` to append to the large object. `buffer` - Data to be appended 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`. + 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/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/index.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/index.mdx index 41f73a1b480..c2a40066616 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/index.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/06_dbms_lob/index.mdx @@ -7,7 +7,7 @@ legacyRedirectsGenerated: - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.151.html" --- -The `DBMS_LOB` package provides the capability to operate on large objects. The following table lists the supported functions and procedures: +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 | | -------------------------------------------------------------------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------- | @@ -16,17 +16,16 @@ The `DBMS_LOB` package provides the capability to operate on large objects. The | `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 | Erase a large object. | -| `GET_STORAGE_LIMIT(lob_loc)` | `INTEGER` | Get the storage limit for large objects. | -| `GETLENGTH(lob_loc)` | `INTEGER` | Get the length of the large object. | -| `INSTR(lob_loc, pattern [, offset [, nth ]])` | `INTEGER` | Get 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 | Read a large object. | -| `SUBSTR(lob_loc [, amount [, offset ]])` | `RAW, VARCHAR2` | Get part of a large object. | -| `TRIM(lob_loc IN OUT, newlen)` | n/a | Trim a large object to the specified length. | -| `WRITE(lob_loc IN OUT, amount, offset, buffer)` | n/a | Write data to a large object. | -| `WRITEAPPEND(lob_loc IN OUT, amount, buffer)` | n/a | Write data from the buffer to the end of a large object. | - -EDB Postgres Advanced Server's implementation of `DBMS_LOB` is a partial implementation when compared to Oracle's version. Only those functions and procedures listed in the table above are supported. +| `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. @@ -50,7 +49,7 @@ The following table lists the public variables available in the package. | `opt_encrypt` | `INTEGER` | `2` | | `warn_inconvertible_char` | `INTEGER` | `1` | -In the following sections, lengths and offsets are measured in bytes if the large objects are `BLOBs`. Lengths and offsets are measured in characters if the large objects are `CLOBs`. +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`.
diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/07_dbms_lock.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/07_dbms_lock.mdx index 68683718d47..a31ca5b775d 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/07_dbms_lock.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/07_dbms_lock.mdx @@ -27,4 +27,4 @@ SLEEP( NUMBER) `seconds` - `seconds` specifies the number of seconds for which you wish to suspend the session. `seconds` can be a fractional value; for example, enter `1.75` to specify one and three-fourths of a second. + `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/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/01_get_mv_dependencies.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/01_get_mv_dependencies.mdx index c23fb9ac25c..e83ef4a8350 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/01_get_mv_dependencies.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/01_get_mv_dependencies.mdx @@ -14,7 +14,7 @@ GET_MV_DEPENDENCIES( `list` - `list` specifies the name of a materialized view, or a comma-separated list of materialized view names. + `list` specifies the name of a materialized view or a comma-separated list of materialized view names. `deplist` @@ -22,7 +22,7 @@ GET_MV_DEPENDENCIES( ## Examples -The following example displays a list of the dependencies on a materialized view named `public.emp_view`. +This example displays a list of the dependencies on a materialized view named `public.emp_view`. ```text DECLARE @@ -32,4 +32,3 @@ BEGIN DBMS_OUTPUT.PUT_LINE('deplist: ' || deplist); END; ``` - diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/02_refresh.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/02_refresh.mdx index 238ea2279eb..774db7b8dff 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/02_refresh.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/02_refresh.mdx @@ -2,7 +2,7 @@ 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: +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: ```text REFRESH( @@ -38,15 +38,15 @@ REFRESH( `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 may be schema-qualified. + `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 name (or names) of a materialized view. + `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 view (or views). The only supported method is `C`; this performs a complete refresh of the view. + `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` @@ -82,7 +82,7 @@ REFRESH( ## Examples -The following example uses `DBMS_MVIEW.REFRESH` to perform a `COMPLETE` refresh on the `public.emp_view` materialized view: +This example uses `DBMS_MVIEW.REFRESH` to perform a complete refresh on the `public.emp_view` materialized view: ```text EXEC DBMS_MVIEW.REFRESH(list => 'public.emp_view', method => 'C'); diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/03_refresh_all_mviews.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/03_refresh_all_mviews.mdx index 658857b08d3..247817e8d4e 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/03_refresh_all_mviews.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/03_refresh_all_mviews.mdx @@ -2,7 +2,7 @@ title: "REFRESH_ALL_MVIEWS" --- -Use the `REFRESH_ALL_MVIEWS` procedure to refresh any materialized views that have not been refreshed since the table or view on which the view depends has been modified. The signature is: +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: ```text REFRESH_ALL_MVIEWS( @@ -17,11 +17,11 @@ REFRESH_ALL_MVIEWS( `number_of_failures` - `number_of_failures` is a `BINARY_INTEGER` that specifies the number of failures that occurred during the refresh operation. + `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;` this performs a complete refresh of the view. + `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` @@ -37,7 +37,7 @@ REFRESH_ALL_MVIEWS( ## Examples -The following example performs a `COMPLETE` refresh on all materialized views: +This example performs a complete refresh on all materialized views: ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/04_refresh_dependent.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/04_refresh_dependent.mdx index 4ca819a81f7..ecdcc99d2d1 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/04_refresh_dependent.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/04_refresh_dependent.mdx @@ -2,9 +2,9 @@ title: "REFRESH_DEPENDENT" --- -Use the `REFRESH_DEPENDENT` procedure to refresh all material views that are dependent 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 `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 are dependent on the views specified in a comma-separated list: +Use the first form of the procedure to refresh all material views that depend on the views specified in a comma-separated list: ```text REFRESH_DEPENDENT( @@ -17,7 +17,7 @@ REFRESH_DEPENDENT( IN BOOLEAN DEFAULT FALSE); ``` -Use the second form of the procedure to refresh all material views that are dependent on the views specified in a table of `DBMS_UTILITY.UNCL_ARRAY` values: +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: ```text REFRESH_DEPENDENT( @@ -38,7 +38,7 @@ REFRESH_DEPENDENT( `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 may be schema-qualified. + `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` @@ -46,7 +46,7 @@ REFRESH_DEPENDENT( `method` - `method` is a `VARCHAR2` value that specifies the refresh method that to apply to the specified views. The only supported method is `C`; this performs a complete refresh of the view. + `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` @@ -66,7 +66,7 @@ REFRESH_DEPENDENT( ## Examples -The following example performs a `COMPLETE` refresh on all materialized views dependent on a materialized view named `emp_view` that resides in the `public` schema: +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: ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/index.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/index.mdx index 58947faa36e..a82edec3cf5 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/index.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/08_dbms_mview/index.mdx @@ -15,10 +15,10 @@ Use procedures in the `DBMS_MVIEW` package to manage and refresh materialized vi | `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 are dependent 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 are dependent on the views listed in a table of `dbms_utility.uncl_array` values. | +| `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 above are supported. +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.
diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/09_dbms_output.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/09_dbms_output.mdx index 3aea9868e1b..02f6496f2aa 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/09_dbms_output.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/09_dbms_output.mdx @@ -7,7 +7,7 @@ legacyRedirectsGenerated: - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.154.html" --- -The `DBMS_OUTPUT` package provides the capability to send messages (lines of text) to a message buffer, or get 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 `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. @@ -38,9 +38,9 @@ TYPE chararr IS TABLE OF VARCHAR2(32767) INDEX BY BINARY_INTEGER; ## DISABLE -The `DISABLE` procedure clears out the message buffer. Any messages in the buffer at the time the `DISABLE` procedure is executed are no longer be accessible. Any messages subsequently 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 have been disabled. +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` procedure or `SERVEROUTPUT(TRUE)` procedure to re-enable the sending and receiving of messages. +Use the `ENABLE or `SERVEROUTPUT(TRUE)` procedure to reenable sending and receiving messages. ```text DISABLE @@ -48,7 +48,7 @@ DISABLE ### Examples -This anonymous block disables the sending and receiving messages in the current session. +This anonymous block disables sending and receiving messages in the current session. ```text BEGIN @@ -58,9 +58,9 @@ END; ## ENABLE -The `ENABLE` procedure enables the capability to send messages to the message buffer or retrieve messages from the message buffer. Running `SERVEROUTPUT(TRUE)` also implicitly performs the `ENABLE` procedure. +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 upon the state of `SERVEROUTPUT`. +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. @@ -73,11 +73,11 @@ ENABLE [ ( INTEGER) ] `buffer_size` - Maximum length of the message buffer in bytes. If a `buffer_size` of less than 2000 is specified, the buffer size is set to 2000. + 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 -The following anonymous block enables messages. Setting `SERVEROUTPUT(TRUE)` forces them to standard output. +This anonymous block enables messages. Setting `SERVEROUTPUT(TRUE)` forces them to standard output. ```text BEGIN @@ -89,7 +89,7 @@ END; Messages enabled ``` -The same effect could have been achieved by simply using `SERVEROUTPUT(TRUE)`. +You can achieve the same effect by using `SERVEROUTPUT(TRUE)`. ```text BEGIN @@ -100,7 +100,7 @@ END; Messages enabled ``` -The following anonymous block enables messages, but setting `SERVEROUTPUT(FALSE)` directs messages to the message buffer. +This anonymous block enables messages, but setting `SERVEROUTPUT(FALSE)` directs messages to the message buffer. ```text BEGIN @@ -112,7 +112,7 @@ END; ## GET_LINE -The `GET_LINE` procedure provides the capability to retrieve a line of text from the message buffer. Only text that has been terminated by an end-of-line character sequence is retrieved – that is complete lines generated using `PUT_LINE`, or by a series of `PUT` calls followed by a `NEW_LINE` call. +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. ```text GET_LINE( OUT VARCHAR2, OUT INTEGER) @@ -126,11 +126,11 @@ GET_LINE( OUT VARCHAR2, OUT INTEGER) `status` - 0 if a line was returned from the message buffer, 1 if there was no line to return. + `0` if a line was returned from the message buffer, `1` if there was no line to return. ### Examples -The following anonymous block writes the `emp` table out to the message buffer as a comma-delimited string for each row. +This anonymous block writes the `emp` table out to the message buffer as a comma-delimited string for each row. ```text EXEC DBMS_OUTPUT.SERVEROUTPUT(FALSE); @@ -150,7 +150,7 @@ BEGIN END; ``` -The following 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. +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. ```text CREATE TABLE messages ( @@ -192,7 +192,7 @@ SELECT msg FROM messages; ## GET_LINES -The `GET_LINES` procedure provides the capability to retrieve one or more lines of text from the message buffer into a collection. Only text that has been terminated by an end-of-line character sequence is retrieved – that is complete lines generated using `PUT_LINE`, or by a series of `PUT` calls followed by a `NEW_LINE` call. +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. ```text GET_LINES( OUT CHARARR, IN OUT INTEGER) @@ -206,15 +206,15 @@ GET_LINES( OUT CHARARR, IN OUT INTEGER) `numlines IN` - Number of lines to be retrieved from the message buffer. + 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 there are no more lines left in the message buffer. + 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 -The following example uses the `GET_LINES` procedure to store all rows from the `emp` table that were placed on the message buffer, into an array. +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. ```text EXEC DBMS_OUTPUT.SERVEROUTPUT(FALSE); @@ -347,11 +347,11 @@ PUT_LINE( VARCHAR2) `item` - Text to be written to the message buffer. + Text to write to the message buffer. ### Examples -The following example uses the `PUT_LINE` procedure to display a comma-delimited list of employees from the `emp` table. +This example uses the `PUT_LINE` procedure to display a comma-delimited list of employees from the `emp` table. ```text DECLARE @@ -385,25 +385,25 @@ END; ## SERVEROUTPUT -The `SERVEROUTPUT` procedure provides the capability to direct messages to standard output of the command line or to the message buffer. Setting `SERVEROUTPUT(TRUE)` also performs an implicit execution of `ENABLE`. +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` is implementation dependent. For example, in Oracle SQL\*Plus, `SERVEROUTPUT(FALSE)` is the default. In PSQL, `SERVEROUTPUT(TRUE)` is the default. Also note that in Oracle SQL\*Plus, this setting is controlled using the SQL\*Plus `SET` command, not by a stored procedure as implemented in EDB Postgres Advanced Server. +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. ```text SERVEROUTPUT( BOOLEAN) ``` -To get an Oracle-style display output, you can set the `dbms_output.serveroutput` to `FALSE` in the `postgresql.conf` file; this disables the message output. The default is `TRUE`, which enables the message output. +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 subsequent `PUT, PUT_LINE`, or `NEW_LINE` commands are to send text directly to standard output of the command line. Set to `FALSE` if text is to be sent to the message buffer. + 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 -The following anonymous block sends the first message to the command line and the second message to the message buffer. +This anonymous block sends the first message to the command line and the second message to the message buffer. ```text BEGIN @@ -416,7 +416,7 @@ END; This message goes to the command line ``` -If within the same session, the following anonymous block is executed, the message stored in the message buffer from the prior example is flushed and displayed on the command line as well as the new message. +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. ```text BEGIN diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/01_create_pipe.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/01_create_pipe.mdx index 9908462d8e1..e202cb49330 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/01_create_pipe.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/01_create_pipe.mdx @@ -25,11 +25,11 @@ The `CREATE_PIPE` function creates an explicit public pipe or an explicit privat `status` - Status code returned by the operation. 0 indicates successful creation. + Status code returned by the operation. `0` indicates successful creation. ## Examples -The following example creates a private pipe named `messages:` +This example creates a private pipe named `messages`: ```text DECLARE @@ -41,7 +41,7 @@ END; CREATE_PIPE status: 0 ``` -The following example creates a public pipe named `mailbox:` +This example creates a public pipe named `mailbox`: ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/02_next_item_pipe.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/02_next_item_pipe.mdx index f65ed7200cb..d593cf01c67 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/02_next_item_pipe.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/02_next_item_pipe.mdx @@ -2,7 +2,7 @@ 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 has been 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 there are no more items left in the message. +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. ```text INTEGER NEXT_ITEM_TYPE @@ -12,7 +12,7 @@ The `NEXT_ITEM_TYPE` function returns an integer code identifying the data type `typecode` - Code identifying the data type of the next data item as shown in the following table. + Code identifying the data type of the next data item is shown in the following table. | Type code | Data type | | --------- | ------------------ | @@ -23,11 +23,11 @@ The `NEXT_ITEM_TYPE` function returns an integer code identifying the data type | `23` | `RAW` | !!! Note - The type codes list in the table are not compatible with Oracle databases. Oracle assigns a different numbering sequence to the data types. + The type codes listed in the table aren't compatible with Oracle databases. Oracle assigns a different numbering sequence to the data types. ## Examples -The following 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. +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. ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/03_pack_message.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/03_pack_message.mdx index f1bf6edd60a..dabe426120f 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/03_pack_message.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/03_pack_message.mdx @@ -2,7 +2,7 @@ title: "PACK_MESSAGE" --- -The `PACK_MESSAGE` procedure places an item of data in the session’s local message buffer. `PACK_MESSAGE` must be executed at least once before issuing a `SEND_MESSAGE` call. +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. ```text PACK_MESSAGE( { DATE | NUMBER | VARCHAR2 | RAW }) diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/04_purge.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/04_purge.mdx index a74224e6b41..5121727a367 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/04_purge.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/04_purge.mdx @@ -60,7 +60,7 @@ Purge the pipe: 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. +Try to retrieve the next message. The `RECEIVE_MESSAGE` call returns status code `1` indicating it timed out because no message was available. ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/06_remove_pipe.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/06_remove_pipe.mdx index d03a9bc4318..8abf4ed83ab 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/06_remove_pipe.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/06_remove_pipe.mdx @@ -8,7 +8,7 @@ The `REMOVE_PIPE` function deletes an explicit private or explicit public pipe. INTEGER REMOVE_PIPE( VARCHAR2) ``` -Use the `REMOVE_PIPE` function to delete explicitly created pipes – i.e., pipes created with the `CREATE_PIPE` function. +Use the `REMOVE_PIPE` function to delete explicitly created pipes, that is, pipes created with the `CREATE_PIPE` function. ## Parameters @@ -18,7 +18,7 @@ Use the `REMOVE_PIPE` function to delete explicitly created pipes – i.e., pipe `status` - Status code returned by the operation. A status code of 0 is returned even if the named pipe is non-existent. + Status code returned by the operation. A status code of `0` is returned even if the named pipe is nonexistent. ## Examples @@ -73,7 +73,7 @@ remove_pipe (1 row) ``` -Try to retrieve the next message. The `RECEIVE_MESSAGE` call returns status code 1 indicating it timed out because the pipe had been deleted. +Try to retrieve the next message. The `RECEIVE_MESSAGE` call returns status code `1` indicating it timed out because the pipe was deleted. ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/07_reset_buffer.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/07_reset_buffer.mdx index 21d75b9d9e6..19161900e3c 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/07_reset_buffer.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/07_reset_buffer.mdx @@ -2,7 +2,7 @@ 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 has the effect of causing subsequent `PACK_MESSAGE` calls to overwrite any data items that existed in the message buffer prior to the `RESET_BUFFER` call. +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. ```text RESET_BUFFER @@ -29,7 +29,7 @@ END; SEND_MESSAGE status: 0 ``` -The message to Bob is in the received message. +The message to Bob is in the received message: ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/08_send_message.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/08_send_message.mdx index b369ae03cd8..123eea97e13 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/08_send_message.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/08_send_message.mdx @@ -29,7 +29,7 @@ The `SEND_MESSAGE` function sends a message from the session’s local message b The possible status codes are: -| Status Code | Description | +| Status code | Description | | ----------- | -------------------- | | `0` | Success | | `1` | Time out | diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/09_unique_session_name.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/09_unique_session_name.mdx index 589c08b0c02..ba288605f2d 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/09_unique_session_name.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/09_unique_session_name.mdx @@ -2,7 +2,7 @@ title: "UNIQUE_SESSION_NAME" --- -The `UNIQUE_SESSION_NAME` function returns a name, unique to the current session. +The `UNIQUE_SESSION_NAME` function returns a name that is unique to the current session. ```text VARCHAR2 UNIQUE_SESSION_NAME @@ -16,7 +16,7 @@ The `UNIQUE_SESSION_NAME` function returns a name, unique to the current session ## Examples -The following anonymous block retrieves and displays a unique session name. +The following anonymous block retrieves and displays a unique session name: ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/10_unpack_message.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/10_unpack_message.mdx index 3fc7c2f850b..f95008e4e17 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/10_unpack_message.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/10_unpack_message.mdx @@ -2,7 +2,7 @@ title: "UNPACK_MESSAGE" --- -The `UNPACK_MESSAGE` procedure copies the data items of a message from the local message buffer to a specified program variable. The message must be placed in the local message buffer with the `RECEIVE_MESSAGE` function before using `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`. ```text UNPACK_MESSAGE( OUT { DATE | NUMBER | VARCHAR2 | RAW }) diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/11_comprehensive_example.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/11_comprehensive_example.mdx index ffdcba9a7fd..48be5132f13 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/11_comprehensive_example.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/11_comprehensive_example.mdx @@ -2,7 +2,11 @@ title: "Comprehensive example" --- -The following example uses a pipe as a “mailbox." The procedures to create the mailbox, add a multi-item message to the mailbox (up to three items), and display the full contents of the mailbox are enclosed in a package named, `mailbox`. +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. ```text CREATE OR REPLACE PACKAGE mailbox @@ -110,7 +114,7 @@ IS END mailbox; ``` -The following demonstrates the execution of the procedures in `mailbox`. The first procedure creates a public pipe using a name generated by the `UNIQUE_SESSION_NAME` function. +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. ```text EXEC mailbox.create_mailbox; diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/index.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/index.mdx index 1a024f76cdd..d9218d8b6ee 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/index.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/10_dbms_pipe/index.mdx @@ -7,13 +7,13 @@ legacyRedirectsGenerated: - "/edb-docs/d/edb-postgres-advanced-server/user-guides/user-guide/9.5/EDB_Postgres_Enterprise_Guide.1.155.html" --- -The `DBMS_PIPE` package provides the capability to send messages through a pipe within or between sessions connected to the same database cluster. +The `DBMS_PIPE` package lets you send messages through a pipe in or between sessions connected to the same database cluster. -The procedures and functions available in the `DBMS_PIPE` package are listed in the following table: +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”. | +| `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. | @@ -24,15 +24,15 @@ The procedures and functions available in the `DBMS_PIPE` package are listed in | `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 was not previously created by the `CREATE_PIPE` function. For example, if the `SEND_MESSAGE` function is executed using a non-existent pipe name, a new implicit pipe is created with that name. An *explicit pipe* is created using the `CREATE_PIPE` function whereby the first parameter specifies the pipe name for the new pipe. +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. A *private pipe* can only be accessed by the user who created the pipe. Even a superuser cannot access a private pipe that was created by another user. A *public pipe* can be accessed by any user who has access to the `DBMS_PIPE` package. +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. -A public pipe can only be created by using the `CREATE_PIPE` function with the third parameter set to `FALSE`. The `CREATE_PIPE` function can be used to create a private pipe by setting the third parameter to `TRUE` or by omitting the third parameter. All implicit pipes are private. +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. The `SEND_MESSAGE` function is then used to send the message through the pipe. +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. The `RECEIVE_MESSAGE` function is used to get a message from the specified pipe. The message is written to the session’s local message buffer. The `UNPACK_MESSAGE` procedure is then used 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. +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. diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/11_dbms_profiler.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/11_dbms_profiler.mdx index 1c10cd76247..f9901fedd74 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/11_dbms_profiler.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/11_dbms_profiler.mdx @@ -13,26 +13,26 @@ legacyRedirectsGenerated: - "/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 the functions and procedures listed below to control the profiling tool. +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). | +| `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 | Pause data collection. | -| `RESUME_PROFILER` | Status Code or Exception | Resume data collection. | -| `START_PROFILER(run_comment, run_comment1 [, run_number OUT ])` | Status Code or Exception | Start data collection. | -| `STOP_PROFILER` | Status Code or Exception | Stop data collection and flush performance data to the `PLSQL_PROFILER_RAWDATA` table. | +| `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 within 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 status codes and messages returned by the functions, and the exceptions raised by the procedures are listed in the table below. +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 has failed. | +| `2` | `error_io` | `profiler_error` | The data flush operation failed. | ## FLUSH_DATA @@ -162,9 +162,9 @@ STOP_PROFILER ## 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. +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 within 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 within the session. For example, if you execute the following function: +`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: ```text 1 - CREATE OR REPLACE FUNCTION getBalance(acctNumber INTEGER) @@ -183,35 +183,36 @@ The `DBMS_PROFILER` package collects and stores performance information about th 14- $$ LANGUAGE 'plpgsql'; ``` -`DBMS_PROFILER` adds one `PLSQL_PROFILER_DATA` entry for each line of code within 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). +`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`). +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`. -It is important to note that 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`). +!!! 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: +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 within the session. + 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`). + 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 within a session. + 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 non-superuser may gather profiling information, but may not view that profiling information unless a superuser grants specific privileges on the profiling tables (stored in the `SYS` schema). This permits a non-privileged user to gather performance statistics without exposing information that the administrator may want to keep secret. +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 step-by-step example uses `DBMS_PROFILER` to retrieve performance information for procedures, functions, and triggers included in the sample data distributed with EDB Postgres Advanced Server. +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: @@ -222,9 +223,9 @@ EDB-SPL Procedure successfully completed ``` !!! Note - (The call to `start_profiler()` includes a comment that `DBMS_PROFILER` associates with the profiler session). + The call to `start_profiler()` includes a comment that `DBMS_PROFILER` associates with the profiler session. -2. Then call the `list_emp` function: +2. Call the `list_emp` function: ```text acctg=# SELECT list_emp(); @@ -250,7 +251,7 @@ INFO: 7934 MILLER (1 row) ``` -3. Stop the profiling session with a call to `dbms_profiler.stop_profiler:` +3. Stop the profiling session with a call to `dbms_profiler.stop_profiler`: ```text acctg=# EXEC dbms_profiler.stop_profiler; @@ -258,7 +259,7 @@ 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): +4. Start a new session with the `dbms_profiler.start_profiler` function followed by a new comment: ```text acctg=# EXEC dbms_profiler.start_profiler('profile get_dept_name and @@ -289,7 +290,7 @@ INFO: User enterprisedb updated employee(s) on 04-FEB-14 UPDATE 1 ``` -7. Terminate the profiling session and flush the performance information to the profiling tables: +7. End the profiling session and flush the performance information to the profiling tables: ```text acctg=# EXEC dbms_profiler.stop_profiler; @@ -297,7 +298,7 @@ acctg=# EXEC dbms_profiler.stop_profiler; EDB-SPL Procedure successfully completed ``` -8. Now, query the `plsql_profiler_runs` table to view a list of the profiling sessions, arranged by `runid:` +8. Query the `plsql_profiler_runs` table to view a list of the profiling sessions, arranged by `runid:` ```text acctg=# SELECT * FROM plsql_profiler_runs; @@ -316,7 +317,7 @@ acctg=# SELECT * FROM plsql_profiler_runs; (2 rows) ``` -9. Query the `plsql_profiler_units` table to view the amount of time consumed by each unit (each function, procedure, or trigger): +9. Query the `plsql_profiler_units` table to view the amount of time consumed by each unit (function, procedure, or trigger): ```text acctg=# SELECT * FROM plsql_profiler_units; @@ -335,7 +336,7 @@ acctg=# SELECT * FROM plsql_profiler_units; (4 rows) ``` -10. Query the `plsql_profiler_rawdata` table to view a list of the wait event counters and wait event times: +10. Query the `plsql_profiler_rawdata` table to view a list of the wait-event counters and wait-event times: ```text acctg=# SELECT runid, sourcecode, func_oid, line_number, exec_count, @@ -641,7 +642,7 @@ The EDB Postgres Advanced Server installer creates the following tables and view | `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_RAWDATA` | Table containing the performance statistics and the extended performance statistics for DRITA counters and timers. | #### PLSQL_PROFILER_RUNS @@ -650,14 +651,14 @@ 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. | +| `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_system_info` | `TEXT` | Currently unused | | `run_comment1` | `TEXT` | Additional user comments | -| `spare1` | `TEXT` | Currently Unused | +| `spare1` | `TEXT` | Currently unused | #### PLSQL_PROFILER_UNITS @@ -666,14 +667,14 @@ 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_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). | +| `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 | +| `spare1` | `BIGINT` | Currently unused | +| `spare2` | `BIGINT` | Currently unused | #### PLSQL_PROFILER_DATA @@ -682,47 +683,47 @@ 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. | +| `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 | +| `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 that is found in the `PLSQL_PROFILER_DATA` view, as well as the performance statistics returned by the DRITA counters and timers. +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. | +| `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) | +| `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). | +| `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. | +| `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. | diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/12_dbms_random.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/12_dbms_random.mdx index 0807fa3fe7b..69dadd17dfc 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/12_dbms_random.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/12_dbms_random.mdx @@ -7,7 +7,7 @@ legacyRedirectsGenerated: - "/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 a number of methods to generate random values. The procedures and functions available in the `DBMS_RANDOM` package are listed in the following table. +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 | | ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -18,7 +18,7 @@ The `DBMS_RANDOM` package provides a number of methods to generate random values | `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` | `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 @@ -29,7 +29,7 @@ The `INITIALIZE` procedure initializes the `DBMS_RANDOM` package with a seed val INITIALIZE( IN INTEGER) ``` -This procedure should be considered deprecated; it is included for backward compatibility only. +This procedure is deprecated. It is included for backward compatibility. ### Parameters @@ -39,7 +39,7 @@ This procedure should be considered deprecated; it is included for backward comp ### Example -The following code snippet demonstrates a call to the `INITIALIZE` procedure that initializes the `DBMS_RANDOM` package with the seed value, `6475`. +The following code shows a call to the `INITIALIZE` procedure that initializes the `DBMS_RANDOM` package with the seed value 6475: ```text DBMS_RANDOM.INITIALIZE(6475); @@ -61,7 +61,7 @@ The `NORMAL` function returns a random number of type `NUMBER`. The signature is ### Example -The following code snippet demonstrates a call to the `NORMAL` function: +The following code shows a call to the `NORMAL` function: ```text x:= DBMS_RANDOM.NORMAL(); @@ -75,7 +75,7 @@ The `RANDOM` function returns a random `INTEGER` value that is greater than or e INTEGER RANDOM() ``` -This function should be considered deprecated; it is included for backward compatibility only. +This function is deprecated. It is included for backward compatibility. ### Parameters @@ -85,7 +85,7 @@ This function should be considered deprecated; it is included for backward compa ### Example -The following code snippet demonstrates a call to the `RANDOM` function. The call returns a random number: +The following code shows a call to the `RANDOM` function. The call returns a random number: ```text x := DBMS_RANDOM.RANDOM(); @@ -93,7 +93,7 @@ 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: +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: ```text SEED( IN INTEGER) @@ -107,7 +107,7 @@ SEED( IN INTEGER) ### Example -The following code snippet demonstrates a call to the `SEED` procedure; the call sets the seed value at `8495`. +The following code shows a call to the `SEED` procedure. The call sets the seed value at 8495. ```text DBMS_RANDOM.SEED(8495); @@ -115,7 +115,7 @@ 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: +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: ```text SEED( IN VARCHAR2) @@ -129,7 +129,7 @@ SEED( IN VARCHAR2) ### Example -The following code snippet demonstrates a call to the `SEED` procedure; the call sets the seed value to `abc123`. +The following code shows a call to the `SEED` procedure. The call sets the seed value to `abc123`. ```text DBMS_RANDOM.SEED('abc123'); @@ -147,14 +147,14 @@ The `STRING` function returns a random `VARCHAR2` string in a user-specified for `opt` - Formatting option for the returned string. `option` may be: + 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 alpha-numeric string | +| `a` or `A` | Mixed-case string | +| `x` or `X` | Uppercase alphanumeric string | | `p` or `P` | Any printable characters | `len` @@ -167,7 +167,7 @@ The `STRING` function returns a random `VARCHAR2` string in a user-specified for ### Example -The following code snippet demonstrates a call to the `STRING` function; the call returns a random alpha-numeric character string that is 10 characters long. +The following code shows a call to the `STRING` function. The call returns a random alphanumeric character string that is 10 characters long. ```text x := DBMS_RANDOM.STRING('X', 10); @@ -181,11 +181,11 @@ The `TERMINATE` procedure has no effect. The signature is: TERMINATE ``` -The `TERMINATE` procedure should be considered deprecated; the procedure is supported for compatibility only. +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: +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: ```text NUMBER VALUE() @@ -199,7 +199,7 @@ The `VALUE` function returns a random `NUMBER` that is greater than or equal to ### Example -The following code snippet demonstrates a call to the `VALUE` function. The call returns a random `NUMBER`: +The following code shows a call to the `VALUE` function. The call returns a random `NUMBER`: ```text x := DBMS_RANDOM.VALUE(); @@ -207,7 +207,7 @@ x := DBMS_RANDOM.VALUE(); ## VALUE -The `VALUE` function returns a random `NUMBER` with a value that is between user-specified boundaries. The `VALUE` function has two forms; the signature of the second form is: +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: ```text NUMBER VALUE( IN NUMBER, IN NUMBER) @@ -217,11 +217,11 @@ The `VALUE` function returns a random `NUMBER` with a value that is between user `low` - `low` specifies the lower boundary for the random value. The random value may be equal to `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`. + `high` specifies the upper boundary for the random value. The random value is less than `high`. `result` @@ -229,7 +229,7 @@ The `VALUE` function returns a random `NUMBER` with a value that is between user ### Example -The following code snippet demonstrates 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: +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: ```text x := DBMS_RANDOM.VALUE(1, 100); diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/13_dbms_redact.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/13_dbms_redact.mdx index 7eb30086cf7..6e789a0f73c 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/13_dbms_redact.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/13_dbms_redact.mdx @@ -2,7 +2,7 @@ title: "DBMS_REDACT" --- -The `DBMS_REDACT` package enables the redacting or masking of data returned by a query. The `DBMS_REDACT` package provides a procedure to create policies, alter policies, enable policies, disable policies, and drop policies. The procedures available in the `DBMS_REDACT` package are listed in the following table. +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 | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------- | --------------------------------------------------------------------- | @@ -15,11 +15,11 @@ The `DBMS_REDACT` package enables the redacting or masking of data returned by a 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. -Note that 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 super-user is by default. +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 below table highlights the values for `function_type` parameters of `dbms_redact.add_policy` and `dbms_redact.alter_policy`. +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 | | --------- | --------- | ----- | --------------------------------------------------------------------------------------------------------- | @@ -27,7 +27,7 @@ The `DBMS_REDACT` package uses the constants and redacts the column data by usin | `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. | +| `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`. @@ -49,26 +49,26 @@ The data redaction feature provides a predefined format to configure policies th - `Number` - `Datetime` -The following table highlights the format descriptor for partial redaction with respect to datatype. The example described below 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. +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 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`. | +| 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 be used for redaction. | The value `X` for redacting SSN strings into `XXX-XX-6789`. | -| | `REDACT_PARTIAL_MASKFROM` | Specifies which `V` within 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 which `V` within the input format at which to end the redaction. | The value `5` for redacting SSN strings up to and including the fifth `V` within the input format of `VVVFVVFVVVV` into strings such as `XXX-XX-6789`. | -| Number | `REDACT_PARTIAL_MASKCHAR` | Specifies the character to be displayed 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_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 can be used in partial redaction. +The following table represents `function_parameters` values that you can use in partial redaction. | Function parameter | Data type | Value | Description | | ----------------------------- | ---------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -96,13 +96,13 @@ The following table represents `function_parameters` values that can be used in | `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 in order for the `regexp_replace_string` to change the value. The following table illustrates the `regexp_pattern` values that you can use during `REGEXP` based redaction. +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_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)$'` | @@ -110,7 +110,7 @@ A regular expression-based redaction searches for patterns of data to redact. Th | `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)'` | | | | | -The below table illustrates the `regexp_replace_string` values that you can use during `REGEXP` based redaction. +This table shows the `regexp_replace_string` values that you can use during `REGEXP` based redaction. | Function parameter | Data type | Value | Description | | ---------------------------- | ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -147,10 +147,10 @@ The following table shows the `regexp_match_parameter` values that you can use d | `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 accordingly set the replacement string to avoid runtime errors. + 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 accordingly set the replacement string to avoid runtime errors. + 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 @@ -181,7 +181,7 @@ PROCEDURE add_policy ( `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. + 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` @@ -189,7 +189,7 @@ PROCEDURE add_policy ( `policy_name` - Name of the policy to be added. Ensure that the `policy_name` is unique for the table on which the policy is created. + Name of the policy to add. Ensure that the `policy_name` is unique for the table on which the policy is created. `policy_description` @@ -197,15 +197,15 @@ PROCEDURE add_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 additional columns. + 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 be redacted. The `column_description` is not supported, but if you specify the description for a column then, a warning message appears. + 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 be used. The possible values are `NONE, FULL, PARTIAL, RANDOM, REGEXP`, and `CUSTOM`. + The type of redaction function to use. The possible values are `NONE`, `FULL`, `PARTIAL`, `RANDOM`, `REGEXP`, and `CUSTOM`. `function_parameters` @@ -213,15 +213,15 @@ PROCEDURE add_policy ( `expression` - Specifies the Boolean expression for the table and determines how the policy is to be applied. The redaction occurs if this policy expression is evaluated to `TRUE`. + 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 set as `TRUE`. When set to `FALSE`, the policy is disabled but the policy can be enabled by calling the `enable_policy` procedure. + 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` does not match, then the `NULL` value is returned. + Specifies the regular expression pattern to redact data. If the `regexp_pattern` doesn't match, then the `NULL` value is returned. `regexp_replace_string` @@ -237,18 +237,18 @@ PROCEDURE add_policy ( `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’, ‘RE_IGNORE_WHITESPACE’`. + 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` (regular expressions) see, Using `DBMS_REDACT Constants and Function Parameters`. + 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` is applicable only for the `CUSTOM` redaction type. The `custom_function_expression` is a function expression that is, 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. + 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 -The following example illustrates how to create a policy and use full redaction for values in the `payment_details_tab` table `customer id` column. +This example shows how to create a policy and use full redaction for values in the `payment_details_tab` table `customer id` column. ```text edb=# CREATE TABLE payment_details_tab ( @@ -326,7 +326,7 @@ PROCEDURE alter_policy ( `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. + 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` @@ -334,11 +334,11 @@ PROCEDURE alter_policy ( `policy_name` - Name of the policy to be altered. + Name of the policy to alter. `action` - The action to perform. For more information about action parameters see, `DBMS_REDACT Constants and Function Parameters`. + 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` @@ -346,7 +346,7 @@ PROCEDURE alter_policy ( `function_type` - The type of redaction function to be used. The possible values are `NONE, FULL, PARTIAL, RANDOM, REGEXP`, and `CUSTOM`. + The type of redaction function to use. The possible values are `NONE`, `FULL`, `PARTIAL`, `RANDOM`, `REGEXP`, and `CUSTOM`. `function_parameters` @@ -354,11 +354,11 @@ PROCEDURE alter_policy ( `expression` - Specifies the Boolean expression for the table and determines how the policy is to be applied. The redaction occurs if this policy expression is evaluated to `TRUE`. + 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` does not match the data, then the `NULL` value is returned. + 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` @@ -374,10 +374,10 @@ PROCEDURE alter_policy ( `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’, ‘RE_IGNORE_WHITESPACE’`. + 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` (regular expressions) see, `Using DBMS_REDACT Constants and Function Parameters`. + 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` @@ -385,15 +385,15 @@ PROCEDURE alter_policy ( `column_description` - Description of the column to be redacted. The `column_description` is not supported, but if you specify the description for a column then, a warning message appears. + 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` is applicable only for the `CUSTOM` redaction type. The `custom_function_expression` is a function expression that is, 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. + 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 -The following example illustrates to alter a policy using partial redaction for values in the `payment_details_tab` table `card_string` (usually a credit card number) column. +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. ```text \c edb base _user @@ -439,7 +439,7 @@ PROCEDURE disable_policy ( `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. + 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` @@ -447,11 +447,11 @@ PROCEDURE disable_policy ( `policy_name` - Name of the policy to be disabled. + Name of the policy to disable. ### Example -The following example illustrates how to disable a policy. +This example shows how to disable a policy. ```text \c edb base_user @@ -482,7 +482,7 @@ PROCEDURE enable_policy ( `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. + 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` @@ -490,11 +490,11 @@ PROCEDURE enable_policy ( `policy_name` - Name of the policy to be enabled. + Name of the policy to enable. ### Example -The following example illustrates how to enable a policy. +This example shows how to enable a policy. ```text \c edb base_user @@ -525,7 +525,7 @@ PROCEDURE drop_policy ( `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. + 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` @@ -533,11 +533,11 @@ PROCEDURE drop_policy ( `policy_name` - Name of the policy to be dropped. + Name of the policy to drop. ### Example -The following example illustrates how to drop a policy. +This example shows how to drop a policy. ```text \c edb base_user @@ -554,7 +554,7 @@ 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 and these default values can be viewed using the `redaction_values_for_type_full` view that use the full redaction type. +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. ```TEXT PROCEDURE update_full_redaction_values ( @@ -582,11 +582,11 @@ PROCEDURE update_full_redaction_values ( `binfloat_val` - The `FLOAT4` datatype is a random value. The binary float datatype is not supported. + 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 is not supported. + The `FLOAT8` datatype is a random value. The binary double datatype isn;t supported. `char_val` @@ -630,9 +630,7 @@ PROCEDURE update_full_redaction_values ( ### Example -The following example illustrates how to update the full redaction values but before updating the values, you can: - -View the default values using `redaction_values_for_type_full` view as shown below: +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. ```text edb=# \x @@ -653,7 +651,7 @@ clob_value | [redacted] (1 row) ``` -Now, update the default values for full redaction type. The `NULL` values are ignored. +Update the default values for full redaction type. The `NULL` values are ignored. ```text \c edb base_user @@ -671,7 +669,7 @@ edb=# BEGIN END; ``` -You can now see the updated values using `redaction_values_for_type_full` view. +You can now see the updated values using the `redaction_values_for_type_full` view. ```text EDB-SPL Procedure successfully completed diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/14_dbms_rls.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/14_dbms_rls.mdx index b560d7c27e1..9be05914a1d 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/14_dbms_rls.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/14_dbms_rls.mdx @@ -7,50 +7,51 @@ legacyRedirectsGenerated: - "/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 the implementation of Virtual Private Database on certain EDB Postgres Advanced Server database objects. +The `DBMS_RLS` package enables you to implement Virtual Private Database on certain EDB Postgres Advanced Server database objects. -| Function/procedure | Function or Procedure | Return Type | Description | +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. | -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 above are supported. - -*Virtual Private Database* is a type of fine-grained access control using security policies. *Fine-grained access control* in Virtual Private Database means that access to data can be controlled down to specific rows as defined by the 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 value. The *security policy* is the named association of the policy function to a particular database object, typically a table. +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, the policy function can be written in any language supported by EDB Postgres Advanced Server such as SQL, PL/pgSQL and SPL. + 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. Policies cannot be applied to views or synonyms. + The database objects currently supported by EDB Postgres Advanced Server Virtual Private Database are tables. You can't apply policies to views or synonyms. -The advantages of using Virtual Private Database are the following: +Virtual Private Database has these advantages: -- 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. -- A different security policy can be applied depending upon 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 upon factors such as the session user of the application accessing the database object. -- Invocation of the security policy is transparent to all applications that access the database object and thus, individual applications don't have to be modified to apply the security policy. -- Once a security policy is enabled, it is not possible for any application (including new applications) to circumvent the security policy except by the system privilege noted by the following. -- Even superusers cannot circumvent the security policy except by the system privilege noted by the following. +- 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 security policies can be circumvented is if the `EXEMPT ACCESS POLICY` system privilege has been granted to a user. The `EXEMPT ACCESS POLICY` privilege should be granted with extreme care as a user with this privilege is exempted from all policies in the database. + 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: -- 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 is to apply and the second input parameter is for the name of that database object. The function must have a `VARCHAR2` return type. The function must 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 upon the database object. Thus, rows that don't satisfy the policy function predicate are filtered out from the SQL command result set. -- 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 is to apply, whether or not to enable the policy at the time of its creation, and if the policy should apply to newly inserted rows or the modified image of updated rows. -- Use the `ENABLE_POLICY` procedure to disable or enable an existing policy. -- Use the `DROP_POLICY` procedure to remove an existing policy. The `DROP_POLICY` procedure does not drop the policy function or the associated database object. +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 policies are created, they can be viewed in the catalog views, compatible with Oracle databases: `ALL_POLICIES, DBA_POLICIES`, or `USER_POLICIES`. The supported compatible views are listed in the *Database Compatibility for Oracle Developers Catalog Views Guide*, available at the EDB website at: - -[https://www.enterprisedb.com/docs/](/epas/latest/epas_compat_cat_views/) +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: @@ -60,11 +61,11 @@ SYS_CONTEXT(, ) Where: - `namespace` is a `VARCHAR2`; the only accepted value is `USERENV`. Any other value returns `NULL`. + `namespace` is a `VARCHAR2`. The only accepted value is `USERENV`. Any other value returns `NULL`. - `attribute` is a `VARCHAR2`. `attribute` may be: + `attribute` is a `VARCHAR2`. Possible values are: -| attribute Value | Equivalent Value | +| attribute Value | Equivalent value | | ---------------- | ----------------------------- | | `SESSION_USER` | `pg_catalog.session_user` | | `CURRENT_USER` | `pg_catalog.current_user` | @@ -73,8 +74,8 @@ Where: | `IP_ADDRESS` | `pg_catalog.inet_client_addr` | | `SERVER_HOST` | `pg_catalog.inet_server_addr` | -!!! Note - 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 shown by the following: + +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: ```text CREATE TABLE public.vpemp AS SELECT empno, ename, job, sal, comm, deptno @@ -130,91 +131,88 @@ ADD_POLICY( VARCHAR2, VARCHAR2, `object_schema` - Name of the schema containing the database object to which the policy is to be applied. + Name of the schema containing the database object to which to apply the policy. `object_name` - Name of the database object to which the policy is to be applied. A given database object may have more than one policy applied to it. + 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 within the database. + 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 may belong to a package in which case `function_schema` must contain the name of the schema in which the package is defined. + 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. The same function may be specified in more than one policy. + 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 may belong to a package in which case `policy_function` must also contain the package name in dot notation (that is, `package_name.function_name`). + 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`. + 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 are not applied to index operations in EDB Postgres Advanced Server. + 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 is not applied to newly inserted rows or the modified image of updated rows. Thus, a newly inserted row may not appear in the result set of a subsequent SQL command that invokes the same policy. Similarly, rows which qualified according to the policy prior to an `UPDATE` command may not appear in the result set of a subsequent SQL command that invokes the same policy. - +- 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. The policy can be enabled using the `ENABLE_POLICY` procedure. The default is `TRUE`. + 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 is 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 re-evaluated and the policy function predicate string regenerated for all invocations of the 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 is not set to its default value of `NULL`, the `policy_type` parameter setting overrides the `static_policy` setting. + 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 re-evaluated, and hence, if and when the predicate string returned by the policy function changes. The default is `NULL`. + 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 - The setting of this parameter is ignored by EDB Postgres Advanced Server. EDB Postgres Advanced Server always assumes a dynamic policy. + 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`. + In Oracle, allows predicates up to 32K bytes if set to `TRUE`. Otherwise predicates are limited to 4000 bytes. The default is `FALSE`. !!! Note - The setting of this parameter 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. + 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 is not enforced if no such columns are referenced. + 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` is not set to `DBMS_RLS.ALL_ROWS`, these rows would not be returned at all in the result set.) The default is `NULL`. + 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 does not support the `DBMS_RLS.ALL_ROWS` functionality. EDB Postgres Advanced Server throws an error if `sec_relevant_cols_opt` is set to `DBMS_RLS.ALL_ROWS (INTEGER` value of 1). + 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 @@ -237,9 +235,9 @@ This function generates the predicate `authid = SYS_CONTEXT('USERENV', 'SESSION_ 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 while the second parameter is the name of an attribute set within the application context. `USERENV` is a special built-in namespace that describes the current session. EDB Postgres Advanced Server does not support application contexts, but only this specific usage of the `SYS_CONTEXT` function. + 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` to be applied to the `vpemp` table using function `verify_session_user` whenever an `INSERT, UPDATE`, or `DELETE` SQL command is given referencing the `vpemp` table. +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. ```text DECLARE @@ -265,7 +263,7 @@ BEGIN END; ``` -After successful creation of the policy, a terminal session is started by user `salesmgr`. The following query shows the content of the `vpemp` table: +After successfully creating the policy, a terminal session is started by user `salesmgr`. The following query shows the content of the `vpemp` table: ```text edb=# \c edb salesmgr @@ -300,7 +298,7 @@ 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 has been changed only for those rows where `authid` contains `salesmgr`. All other rows are unchanged. +The following query shows that the `comm` column was changed only for those rows where `authid` contains `salesmgr`. All other rows are unchanged. ```text edb=> SELECT * FROM vpemp; @@ -323,7 +321,7 @@ edb=> SELECT * FROM vpemp; (14 rows) ``` -Furthermore, since the `update_check` parameter was set to `TRUE` in the `ADD_POLICY` procedure, the following `INSERT` command throws an exception since the value given for the `authid` column, `researchmgr`, does not match the session user, which is `salesmgr`, and hence, fails the policy. +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. ```text edb=> INSERT INTO vpemp VALUES (9001,'SMITH','ANALYST',3200.00,NULL,20, @@ -332,9 +330,9 @@ ERROR: policy with check option violation DETAIL: Policy predicate was evaluated to FALSE with the updated values ``` -If `update_check` was set to `FALSE`, the preceding `INSERT` command would have succeeded. +If `update_check` is set to `FALSE`, the preceding `INSERT` command succeeds. -The following example illustrates the use of 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`. +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`. ```text CREATE OR REPLACE FUNCTION sal_lt_2000 ( @@ -348,7 +346,7 @@ BEGIN END ``` -The policy is created so that it is enforced only if a `SELECT` command includes columns `sal` or `comm`: +The policy is created so that it's enforced only if a `SELECT` command includes columns `sal` or `comm`: ```text DECLARE @@ -372,7 +370,7 @@ BEGIN END; ``` -If a query does not reference columns `sal` or `comm`, then the policy is not applied. The following query returns all 14 rows of table `vpemp`: +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`: ```text edb=# SELECT empno, ename, job, deptno, authid FROM vpemp; @@ -395,7 +393,7 @@ edb=# SELECT empno, ename, job, deptno, authid FROM vpemp; (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` as shown by the following: +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`: ```text edb=# SELECT empno, ename, job, sal, comm, deptno, authid FROM vpemp; @@ -414,7 +412,7 @@ edb=# SELECT empno, ename, job, sal, comm, deptno, authid FROM vpemp; ## DROP_POLICY -The `DROP_POLICY` procedure deletes an existing policy. The policy function and database object associated with the policy are not deleted by the `DROP_POLICY` procedure. +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. @@ -435,11 +433,11 @@ DROP_POLICY( VARCHAR2, VARCHAR2, `policy_name` - Name of the policy to be deleted. + Name of the policy to delete. ### Examples -The following example deletes policy `secure_update` on table `public.vpemp`: +This example deletes policy `secure_update` on table `public.vpemp`: ```text DECLARE @@ -478,7 +476,7 @@ ENABLE_POLICY( VARCHAR2, VARCHAR2, `policy_name` - Name of the policy to be enabled or disabled. + Name of the policy to enable or disable. `enable` @@ -486,7 +484,7 @@ ENABLE_POLICY( VARCHAR2, VARCHAR2, ### Examples -The following example disables policy `secure_update` on table `public.vpemp`: +This example disables policy `secure_update` on table `public.vpemp`: ```text DECLARE diff --git a/product_docs/docs/epas/14/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/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/01_using_calendar_syntax_to_specify_a_repeating_interval.mdx index 35e54507a61..9340a6fc75b 100644 --- a/product_docs/docs/epas/14/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/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/01_using_calendar_syntax_to_specify_a_repeating_interval.mdx @@ -2,23 +2,21 @@ title: "Using calendar syntax to specify a repeating interval" --- -The `CREATE_JOB` and `CREATE_SCHEDULE` procedures use Oracle-styled calendar syntax to define the interval with which a job or schedule is repeated. You should provide the scheduling information in the `repeat_interval` parameter of each procedure. +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, followed by an equal sign, followed by the unit (or units) on which the schedule executes. Multiple token values must be separated by a semi-colon (;). +`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: +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` -Defines a schedule that is executed each weeknight at 5:45. - -The token types and syntax described in the table below are supported by EDB Postgres Advanced Server: +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 is not 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` | +| `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` \| | diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/02_create_job.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/02_create_job.mdx index 8f9393db731..44b0008817d 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/02_create_job.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/02_create_job.mdx @@ -2,7 +2,7 @@ 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 within the job definition, as well as a job action to invoke when the job executes: +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: ```text CREATE_JOB( @@ -19,7 +19,7 @@ CREATE_JOB( 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: +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: ```text CREATE_JOB( @@ -50,21 +50,21 @@ CREATE_JOB( `number_of_arguments` - `number_of_arguments` is an `INTEGER` value that specifies the number of arguments expected by the job. The default is `0`. + `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 that the job should be scheduled to execute when the job is enabled. + `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 a `repeat_interval` isn't specified, the job executes only once. The default value is `NULL`. + `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 a date is specified, the `end_date` must be after `start_date`. The default value is `NULL`. + `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 an `end_date` is not specified and a `repeat_interval` is specified, the job repeats indefinitely until it is disabled. + 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` @@ -80,7 +80,7 @@ CREATE_JOB( `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. + `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` @@ -92,7 +92,7 @@ CREATE_JOB( ## Example -The following example demonstrates a call to the `CREATE_JOB` procedure: +This example shows a call to the `CREATE_JOB` procedure: ```text EXEC diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/03_create_program.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/03_create_program.mdx index 576467d04e2..44fefde00d5 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/03_create_program.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/03_create_program.mdx @@ -18,7 +18,7 @@ CREATE_PROGRAM( `program_name` - `program_name` specifies the name of the program that is being created. + `program_name` specifies the name of the program that's being created. `program_type` @@ -41,13 +41,13 @@ CREATE_PROGRAM( `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. +- 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`. + Use the `comments` parameter to specify a comment about the program. By default, this parameter is `NULL`. ## Example diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/04_create_schedule.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/04_create_schedule.mdx index 6f718a21414..55369b65d12 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/04_create_schedule.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/04_create_schedule.mdx @@ -21,29 +21,29 @@ CREATE_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 a `start_date` is not specified, the date that the job is enabled is used as the `start_date`. By default, `start_date` is `NULL`. + `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 a `repeat_interval` is not specified, the job executes only once, on the date specified by `start_date`. + `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. + 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 a date is specified, the `end_date` must be after the `start_date`. The default value is `NULL`. + `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 a `repeat_interval` is specified and an `end_date` is not specified, the schedule repeats indefinitely until disabled. + 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`. + Use the `comments` parameter to specify a comment about the schedule. By default, this parameter is `NULL`. ## Example -The following code fragment calls `CREATE_SCHEDULE` to create a schedule named `weeknights_at_5`: +This code fragment calls `CREATE_SCHEDULE` to create a schedule named `weeknights_at_5`: ```text EXEC @@ -54,4 +54,4 @@ EXEC comments => 'This schedule executes each weeknight at 5:00'); ``` -The schedule executes each weeknight, at 5:00 pm, effective after June 1, 2013. Since no `end_date` is specified, the schedule executes indefinitely until disabled with `DBMS_SCHEDULER.DISABLE`. +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/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/05_define_program_argument.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/05_define_program_argument.mdx index a2e315f2263..97f147f4a50 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/05_define_program_argument.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/05_define_program_argument.mdx @@ -2,7 +2,7 @@ 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: +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: ```text DEFINE_PROGRAM_ARGUMENT( @@ -33,7 +33,7 @@ DEFINE_PROGRAM_ARGUMENT( `argument_position` - `argument_position` specifies the position of the argument as it is passed to the program. + `argument_position` specifies the position of the argument as it's passed to the program. `argument_name` @@ -49,11 +49,11 @@ DEFINE_PROGRAM_ARGUMENT( `out_argument IN BOOLEAN DEFAULT FALSE` - `out_argument` is not currently used; if specified, the value must be `FALSE`. + `out_argument` isn't currently used. If specified, the value must be `FALSE`. ## Example -The following code fragment uses the `DEFINE_PROGRAM_ARGUMENT` procedure to define the first and second arguments in a program named `add_emp`: +This code fragment uses the `DEFINE_PROGRAM_ARGUMENT` procedure to define the first and second arguments in a program named `add_emp`: ```text EXEC @@ -71,4 +71,4 @@ EXEC 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`; the second argument does not have a default value. +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/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/06_dbms_scheduler_disable.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/06_dbms_scheduler_disable.mdx index 228d3f5bb97..850d68ee9a7 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/06_dbms_scheduler_disable.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/06_dbms_scheduler_disable.mdx @@ -17,17 +17,17 @@ DISABLE( `name` - `name` specifies the name of the program or job that is being disabled. + `name` specifies the name of the program or job that's being disabled. `force` - `force` is accepted for compatibility, and ignored. + `force` is accepted for compatibility and ignored. `commit_semantics` - `commit_semantics` instructs 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`, instructing the server to stop when it encounters an error. Any programs or jobs that were successfully disabled prior to the error are committed to disk. + `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. + The `TRANSACTIONAL` and `ABSORB_ERRORS` keywords are accepted for compatibility and ignored. ## Example diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/07_drop_job.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/07_drop_job.mdx index 5e507fc7e5a..887171481b0 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/07_drop_job.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/07_drop_job.mdx @@ -2,7 +2,7 @@ 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: +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: ```text DROP_JOB( @@ -16,21 +16,21 @@ DROP_JOB( `job_name` - `job_name` specifies the name of the job that is being dropped. + `job_name` specifies the name of the job that's being dropped. `force` - `force` is accepted for compatibility, and ignored. + `force` is accepted for compatibility and ignored. `defer` - `defer` is accepted for compatibility, and ignored. + `defer` is accepted for compatibility and ignored. `commit_semantics` - `commit_semantics` instructs 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`, instructing the server to stop when it encounters an error. + `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. + The `TRANSACTIONAL` and `ABSORB_ERRORS` keywords are accepted for compatibility and ignored. ## Example diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/08_drop_program.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/08_drop_program.mdx index 6591e3db975..1e0641e25dd 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/08_drop_program.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/08_drop_program.mdx @@ -2,7 +2,7 @@ title: "DROP_PROGRAM" --- -The `DROP_PROGRAM` procedure to drop a program. The signature of the `DROP_PROGRAM` procedure is: +The `DROP_PROGRAM` procedure drops a program. The signature of the `DROP_PROGRAM` procedure is: ```text DROP_PROGRAM( @@ -14,17 +14,17 @@ DROP_PROGRAM( `program_name` - `program_name` specifies the name of the program that is being dropped. + `program_name` specifies the name of the program that's being dropped. `force` - `force` is a `BOOLEAN` value that instructs the server how to handle programs with dependent jobs. + `force` is a Boolean value that tells the server how to handle programs with dependent jobs. -- Specify `FALSE` to instruct the server to return an error if the program is referenced by a job. +- Specify `FALSE` to return an error if the program is referenced by a job. -- Specify `TRUE` to instruct the server to disable any jobs that reference the program before dropping the program. +- Specify `TRUE` to disable any jobs that reference the program before dropping the program. - The default value is `FALSE`. + The default value is `FALSE`. ## Example diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/09_drop_program_argument.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/09_drop_program_argument.mdx index 43d05e95f89..70a622bd4e1 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/09_drop_program_argument.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/09_drop_program_argument.mdx @@ -2,7 +2,7 @@ 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 which argument to drop: +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: ```text DROP_PROGRAM_ARGUMENT( @@ -22,15 +22,15 @@ DROP_PROGRAM_ARGUMENT( `program_name` - `program_name` specifies the name of the program that is being modified. + `program_name` specifies the name of the program that's being modified. `argument_position` - `argument_position` specifies the position of the argument that is being dropped. + `argument_position` specifies the position of the argument that's being dropped. `argument_name` - `argument_name` specifies the name of the argument that is being dropped. + `argument_name` specifies the name of the argument that's being dropped. ## Examples diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/10_drop_schedule.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/10_drop_schedule.mdx index 1ed05148e06..6d44baf91eb 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/10_drop_schedule.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/10_drop_schedule.mdx @@ -14,14 +14,14 @@ DROP_SCHEDULE( `schedule_name` - `schedule_name` specifies the name of the schedule that is being dropped. + `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 instruct the server to return an error if the specified schedule is referenced by a job. This is the default behavior. -- Specify `TRUE` to instruct the server 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. + - 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 diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/11_dbms_scheduler_enable.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/11_dbms_scheduler_enable.mdx index 8d52ca662cf..234996c5353 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/11_dbms_scheduler_enable.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/11_dbms_scheduler_enable.mdx @@ -18,13 +18,13 @@ ENABLE( `name` - `name` specifies the name of the program or job that is being enabled. + `name` specifies the name of the program or job that's being enabled. `commit_semantics` - `commit_semantics` instructs 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`, instructing the server to stop when it encounters an error. + `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. + The `TRANSACTIONAL` and `ABSORB_ERRORS` keywords are accepted for compatibility and ignored. ## Example diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/12_evaluate_calendar_string.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/12_evaluate_calendar_string.mdx index 9f2be1b6715..a81aa91f8f6 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/12_evaluate_calendar_string.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/12_evaluate_calendar_string.mdx @@ -18,7 +18,7 @@ EVALUATE_CALENDAR_STRING( `calendar_string` - `calendar_string` is the calendar string that describes a `repeat_interval` that is being evaluated. + `calendar_string` is the calendar string that describes a `repeat_interval` that's being evaluated. `start_date IN TIMESTAMP WITH TIME ZONE` @@ -26,9 +26,9 @@ EVALUATE_CALENDAR_STRING( `return_date_after` - Use the `return_date_after` parameter to specify the date and time that `EVALUATE_CALENDAR_STRING` should use as a starting date when evaluating the `repeat_interval`. + 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. + 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` @@ -36,7 +36,7 @@ EVALUATE_CALENDAR_STRING( ## Example -The following example evaluates a calendar string and returns the first date and time that the schedule will execute after June 15, 2013: +This example evaluates a calendar string and returns the first date and time that the schedule will execute after June 15, 2013: ```text DECLARE @@ -56,4 +56,4 @@ END; next_run_date: 17-JUN-13 05.00.00.000000 PM ``` -June 15, 2013 is a Saturday; the schedule will not execute until Monday, June 17, 2013 at 5:00 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/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/13_run_job.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/13_run_job.mdx index 0308eb7d510..fed4e087d65 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/13_run_job.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/13_run_job.mdx @@ -18,7 +18,7 @@ RUN_JOB( `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. + 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 diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/14_set_job_argument_value.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/14_set_job_argument_value.mdx index 8413767fd3e..0ba1fdc84e5 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/14_set_job_argument_value.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/14_set_job_argument_value.mdx @@ -2,7 +2,7 @@ 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 which argument should be modified by position: +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: ```text SET_JOB_ARGUMENT_VALUE( @@ -11,7 +11,7 @@ SET_JOB_ARGUMENT_VALUE( IN VARCHAR2) ``` -The second form uses an argument name to specify which argument to modify: +The second form uses an argument name to specify the argument to modify: ```text SET_JOB_ARGUMENT_VALUE( @@ -42,13 +42,13 @@ Argument values set by the `SET_JOB_ARGUMENT_VALUE` procedure override any value ## Examples -The following example assigns a value of `30` to the first argument in the `update_emp` job: +This example assigns a value of `30` to the first argument in the `update_emp` job: ```text DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE('update_emp', 1, '30'); ``` -The following example sets the `emp_name` argument to `SMITH`: +This example sets the `emp_name` argument to `SMITH`: ```text DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE('update_emp', 'emp_name', 'SMITH'); diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/index.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/index.mdx index 0274dcac0ee..9d0372a90e5 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/index.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/index.mdx @@ -7,16 +7,16 @@ legacyRedirectsGenerated: - "/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-styled jobs, programs and job schedules. The `DBMS_SCHEDULER` package implements the following functions and procedures: +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 | +| 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 does not have 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. | @@ -26,20 +26,20 @@ The `DBMS_SCHEDULER` package provides a way to create and manage Oracle-styled j | `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. | +| `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 above are supported. +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 is dependent on the pgAgent service; you must have a pgAgent service installed and running on your server before using `DBMS_SCHEDULER`. +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: +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: ```text 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). +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. diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/16_dbms_session.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/16_dbms_session.mdx index 7eddc2909c5..b0f60e0b6db 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/16_dbms_session.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/16_dbms_session.mdx @@ -25,7 +25,7 @@ The `SET_ROLE` procedure sets the current session user to the role specified in SET_ROLE() ``` -The `SET_ROLE` procedure appends the value specified for `role_cmd` to the `SET ROLE` statement, and then invokes the statement. +The `SET_ROLE` procedure appends the value specified for `role_cmd` to the `SET ROLE` statement and then invokes the statement. ### Parameters @@ -35,7 +35,7 @@ The `SET_ROLE` procedure appends the value specified for `role_cmd` to the `SET ### Example -The following call to the `SET_ROLE` procedure invokes the `SET ROLE` command to set the identity of the current session user to manager: +This call to the `SET_ROLE` procedure invokes the `SET ROLE` command to set the identity of the current session user to manager: ```text edb=# exec DBMS_SESSION.SET_ROLE('manager'); diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/01_bind_variable.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/01_bind_variable.mdx index c0d83b9e96e..e6f898d2b67 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/01_bind_variable.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/01_bind_variable.mdx @@ -2,7 +2,7 @@ title: "BIND_VARIABLE" --- -The `BIND_VARIABLE` procedure provides the capability to associate a value with an `IN` or `IN OUT` bind variable in a SQL command. +The `BIND_VARIABLE` procedure associates a value with an `IN` or `IN OUT` bind variable in a SQL command. ```text BIND_VARIABLE( NUMBER, VARCHAR2, diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/02_bind_variable_char.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/02_bind_variable_char.mdx index 45d9e3e13bb..73ac16d0365 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/02_bind_variable_char.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/02_bind_variable_char.mdx @@ -2,7 +2,7 @@ title: "BIND_VARIABLE_CHAR" --- -The `BIND_VARIABLE_CHAR` procedure provides the capability to associate a `CHAR` value with an `IN` or `IN OUT` bind variable in a SQL command. +The `BIND_VARIABLE_CHAR` procedure associates a `CHAR` value with an `IN` or `IN OUT` bind variable in a SQL command. ```text BIND_VARIABLE_CHAR( NUMBER, VARCHAR2, CHAR diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/03_bind_variable_raw.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/03_bind_variable_raw.mdx index fcbcbaaad94..dfd8eb974b4 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/03_bind_variable_raw.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/03_bind_variable_raw.mdx @@ -2,7 +2,7 @@ title: "BIND_VARIABLE_RAW" --- -The `BIND_VARIABLE_RAW` procedure provides the capability to associate a `RAW` value with an `IN` or `IN OUT` bind variable in a SQL command. +The `BIND_VARIABLE_RAW` procedure associates a `RAW` value with an `IN` or `IN OUT` bind variable in a SQL command. ```text BIND_VARIABLE_RAW( NUMBER, VARCHAR2, RAW diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/04_close_cursor.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/04_close_cursor.mdx index 3fc6c546934..3cf4e4b3bd4 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/04_close_cursor.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/04_close_cursor.mdx @@ -2,7 +2,7 @@ title: "CLOSE_CURSOR" --- -The `CLOSE_CURSOR` procedure closes an open cursor. The resources allocated to the cursor are released and it can no longer be used. +The `CLOSE_CURSOR` procedure closes an open cursor. The resources allocated to the cursor are released and you can no longer use it. ```text CLOSE_CURSOR( IN OUT NUMBER) @@ -16,7 +16,7 @@ CLOSE_CURSOR( IN OUT NUMBER) ## Examples -The following example closes an opened cursor: +This example closes an open cursor: ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/05_column_value.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/05_column_value.mdx index e2b058bf851..212a763b6c5 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/05_column_value.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/05_column_value.mdx @@ -18,7 +18,7 @@ COLUMN_VALUE( NUMBER, NUMBER, OUT { BLOB | CLOB | DATE | F `position` - Position within the cursor of the returned data. The first value in the cursor is position 1. + Position of the returned data in the cursor. The first value in the cursor is position 1. `value` @@ -34,7 +34,7 @@ COLUMN_VALUE( NUMBER, NUMBER, OUT { BLOB | CLOB | DATE | F ## Examples -The following example shows the portion of an anonymous block that receives the values from a cursor using the `COLUMN_VALUE` procedure. +This example shows the portion of an anonymous block that receives the values from a cursor using the `COLUMN_VALUE` procedure. ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/06_column_value_char.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/06_column_value_char.mdx index 6ab5559a8dd..857a769af32 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/06_column_value_char.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/06_column_value_char.mdx @@ -17,7 +17,7 @@ COLUMN_VALUE_CHAR( NUMBER, NUMBER, OUT CHAR `position` - Position within the cursor of the returned data. The first value in the cursor is position 1. + Position of the returned data in the cursor. The first value in the cursor is position 1. `value` diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/07_column_value_raw.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/07_column_value_raw.mdx index c267e18b142..3fb3868e104 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/07_column_value_raw.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/07_column_value_raw.mdx @@ -17,7 +17,7 @@ COLUMN_VALUE_RAW( NUMBER, NUMBER, OUT RAW `position` - Position within the cursor of the returned data. The first value in the cursor is position 1. + Position of the returned data in the cursor. The first value in the cursor is position 1. `value` @@ -66,4 +66,4 @@ COLUMN_VALUE_LONG( NUMBER, NUMBER, NUMBER, Number of bytes returned in value. -To refer example, see [DEFINE_COLUMN_LONG](10_define_column_raw/#define_column_long). +For an example, see [DEFINE_COLUMN_LONG](10_define_column_raw/#define_column_long). diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/08_define_column.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/08_define_column.mdx index f7301f131f4..f24904414cc 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/08_define_column.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/08_define_column.mdx @@ -2,7 +2,7 @@ title: "DEFINE_COLUMN" --- -The `DEFINE_COLUMN` procedure defines a column or expression in the `SELECT` list that is to be returned and retrieved in a cursor. +The `DEFINE_COLUMN` procedure defines a column or expression in the `SELECT` list to be returned and retrieved in a cursor. ```text DEFINE_COLUMN( NUMBER, NUMBER, { BLOB | CLOB | DATE | FLOAT | @@ -18,19 +18,19 @@ DEFINE_COLUMN( NUMBER, NUMBER, { BLOB | CLOB | DATE | FLO `position` - Position of the column or expression in the `SELECT` list that is being defined. + Position of the column or expression in the `SELECT` list that's being defined. `column` - A variable that is of the same data type as the column or expression in position `position` of the `SELECT` list. + 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. `column_size` must be specified only if `column` is `VARCHAR2`. Returned data exceeding `column_size` is truncated to `column_size` characters. + 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 -The following shows how the `empno, ename, hiredate, sal`, and `comm` columns of the `emp` table are defined with the `DEFINE_COLUMN` procedure. +This example shows how the `empno`, `ename`, `hiredate`, `sal`, and `comm` columns of the `emp` table are defined with the `DEFINE_COLUMN` procedure. ```text DECLARE @@ -69,7 +69,7 @@ BEGIN END; ``` -The following shows an alternative to the prior example that produces the exact 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 ten 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. +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. ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/09_define_column_char.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/09_define_column_char.mdx index 7c3362b15c9..b9c7846b231 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/09_define_column_char.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/09_define_column_char.mdx @@ -2,7 +2,7 @@ title: "DEFINE_COLUMN_CHAR" --- -The `DEFINE_COLUMN_CHAR` procedure defines a `CHAR` column or expression in the `SELECT` list that is to be returned and retrieved in a cursor. +The `DEFINE_COLUMN_CHAR` procedure defines a `CHAR` column or expression in the `SELECT` list to be returned and retrieved in a cursor. ```text DEFINE_COLUMN_CHAR( NUMBER, NUMBER, @@ -17,7 +17,7 @@ CHAR, NUMBER) `position` - Position of the column or expression in the `SELECT` list that is being defined. + Position of the column or expression in the `SELECT` list being defined. `column` diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/10_define_column_raw.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/10_define_column_raw.mdx index 738598d1bc1..8273ea8205c 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/10_define_column_raw.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/10_define_column_raw.mdx @@ -2,7 +2,7 @@ title: "DEFINE_COLUMN_RAW" --- -The `DEFINE_COLUMN_RAW` procedure defines a `RAW` column or expression in the `SELECT` list that is to be returned and retrieved in a cursor. +The `DEFINE_COLUMN_RAW` procedure defines a `RAW` column or expression in the `SELECT` list to be returned and retrieved in a cursor. ```text DEFINE_COLUMN_RAW( NUMBER, NUMBER, RAW, @@ -17,7 +17,7 @@ DEFINE_COLUMN_RAW( NUMBER, NUMBER, RAW, `position` - Position of the column or expression in the `SELECT` list that is being defined. + Position of the column or expression in the `SELECT` list being defined. `column` @@ -45,11 +45,11 @@ DEFINE_COLUMN_LONG( NUMBER, NUMBER) `position` - Position of the column in a row that is being defined. + Position of the column in a row being defined. ### Examples -The following example shows an anonymous block that defines a long column in the `SELECT` list using `DEFINE_COLUMN_LONG` procedure and returns a part of the `LONG` column value into a variable using procedure `COLUMN_VALUE_LONG`. +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`. ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/11_describe_columns.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/11_describe_columns.mdx index ef2d5b95642..c4cda36859e 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/11_describe_columns.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/11_describe_columns.mdx @@ -17,11 +17,11 @@ DESCRIBE_COLUMNS( NUMBER, OUT NUMBER, OUT `col_cnt` - The number of columns in cursor result set. + 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: + 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 | | --------------------- | --------------- | diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/12_execute.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/12_execute.mdx index a14a249ff18..607a78530c8 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/12_execute.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/12_execute.mdx @@ -12,11 +12,11 @@ The `EXECUTE` function executes a parsed SQL command or SPL block. `c` - Cursor ID of the parsed SQL command or SPL block to be executed. + 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. + Number of rows processed if the SQL command was `DELETE`, `INSERT`, or `UPDATE`. `status` is meaningless for all other commands. ## Examples diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/13_execute_and_fetch.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/13_execute_and_fetch.mdx index d81257f5e0d..f3f9d8c37e8 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/13_execute_and_fetch.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/13_execute_and_fetch.mdx @@ -12,19 +12,19 @@ Function `EXECUTE_AND_FETCH` executes a parsed `SELECT` command and fetches one `c` - Cursor id of the cursor for the `SELECT` command to be executed. + 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 is not 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 there is more than one row in the result set. + 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. + Returns `1` if a row was successfully fetched, `0` if no rows to fetch. If an exception is thrown, no value is returned. ## Examples -The following stored procedure uses the `EXECUTE_AND_FETCH` function to retrieve one employee using the employee’s name. An exception is thrown if the employee is not found, or there is more than one employee with the same name. +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. ```text CREATE OR REPLACE PROCEDURE select_by_name( diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/14_fetch_rows.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/14_fetch_rows.mdx index 5ea2c3d9888..5affbcaa056 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/14_fetch_rows.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/14_fetch_rows.mdx @@ -20,7 +20,7 @@ The `FETCH_ROWS` function retrieves a row from a cursor. ## Examples -The following examples fetches the rows from the `emp` table and displays the results. +These examples fetch the rows from the `emp` table and display the results. ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/15_is_open.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/15_is_open.mdx index 9f1876061a9..422bfb5423f 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/15_is_open.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/15_is_open.mdx @@ -2,7 +2,7 @@ title: "IS_OPEN" --- -The `IS_OPEN` function provides the capability to test if the given cursor is open. +The `IS_OPEN` function tests whether the given cursor is open. ```text BOOLEAN IS_OPEN( NUMBER) @@ -12,8 +12,8 @@ The `IS_OPEN` function provides the capability to test if the given cursor is op `c` - Cursor ID of the cursor to be tested. + Cursor ID of the cursor to test. `status` - Set to `TRUE` if the cursor is open, set to `FALSE` if the cursor is not open. + Set to `TRUE` if the cursor is open, set to `FALSE` if the cursor isn't open. diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/16_last_row_count.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/16_last_row_count.mdx index c081833909f..4c9fbec7396 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/16_last_row_count.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/16_last_row_count.mdx @@ -2,7 +2,7 @@ title: "LAST_ROW_COUNT" --- -The `LAST_ROW_COUNT` function returns the number of rows that have been currently fetched. +The `LAST_ROW_COUNT` function returns the number of rows that were currently fetched. ```text INTEGER LAST_ROW_COUNT @@ -16,7 +16,7 @@ The `LAST_ROW_COUNT` function returns the number of rows that have been currentl ## Examples -The following example uses the `LAST_ROW_COUNT` function to display the total number of rows fetched in the query. +This example uses the `LAST_ROW_COUNT` function to display the total number of rows fetched in the query. ```text DECLARE @@ -81,7 +81,7 @@ 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`. +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`. ```text LAST_ERROR_POSITION RETURN INTEGER; @@ -89,7 +89,7 @@ LAST_ERROR_POSITION RETURN INTEGER; ### Examples -The following example demonstrates an anonymous block that returns an error position with the `LAST_ERROR_POSITION` function. +This example shows an anonymous block that returns an error position with the `LAST_ERROR_POSITION` function. ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/17_open_cursor.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/17_open_cursor.mdx index 2a4a3b0d626..7cb8cde7511 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/17_open_cursor.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/17_open_cursor.mdx @@ -2,7 +2,7 @@ title: "OPEN_CURSOR" --- -The `OPEN_CURSOR` function creates a new cursor. A cursor must be used to parse and execute any dynamic SQL statement. Once a cursor has been opened, it can be re-used with the same or different SQL statements. The cursor does not have to be closed and re-opened in order to be re-used. +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. ```text INTEGER OPEN_CURSOR @@ -16,7 +16,7 @@ The `OPEN_CURSOR` function creates a new cursor. A cursor must be used to parse ## Examples -The following example creates a new cursor: +This example creates a new cursor: ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/18_parse.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/18_parse.mdx index 52d6ab7f09f..28ec4fe62bc 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/18_parse.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/18_parse.mdx @@ -2,7 +2,7 @@ title: "PARSE" --- -The `PARSE` procedure parses a SQL command or SPL block. If the SQL command is a DDL command, it is immediately executed and does not require running the `EXECUTE` function. +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. ```text PARSE( NUMBER, VARCHAR2, NUMBER) @@ -16,15 +16,15 @@ PARSE( NUMBER, VARCHAR2, NUMBER) `statement` - SQL command or SPL block to be parsed. A SQL command must not end with the semi-colon terminator, however an SPL block does require the semi-colon terminator. + 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. + 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 -The following anonymous block creates a table named, `job`. Note that DDL statements are executed immediately by the `PARSE` procedure and don't require a separate `EXECUTE` step. +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. ```text DECLARE @@ -61,7 +61,7 @@ Number of rows processed: 1 Number of rows processed: 1 ``` -The following anonymous block uses the `DBMS_SQL` package to execute a block containing two `INSERT` statements. Note that the end of the block contains a terminating semi-colon, while in the prior example, each individual `INSERT` statement does not have a terminating semi-colon. +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. ```text DECLARE diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/index.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/index.mdx index b943c1c1655..ef1179d7b41 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/index.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/index.mdx @@ -7,10 +7,12 @@ legacyRedirectsGenerated: - "/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 run time (rather than when you write the application). EDB EDB Postgres Advanced Server offers native support for dynamic SQL; `DBMS_SQL` provides a way to use dynamic SQL in a fashion compatible with Oracle databases without modifying your application. +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. | @@ -25,7 +27,7 @@ The `DBMS_SQL` package provides an application interface compatible with Oracle | `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 | Defines columns to hold a cursor result set. | +| `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. | @@ -35,9 +37,8 @@ The `DBMS_SQL` package provides an application interface compatible with Oracle | `OPEN_CURSOR` | Function | `INTEGER` | Open a cursor. | | `PARSE(c, statement, language_flag)` | Procedure | n/a | Parse a statement. | -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 above are supported. -The following table lists the public variable available in the `DBMS_SQL` package. +The following table lists the public variables available in the `DBMS_SQL` package. | Public variables | Data type | Value | Description | | ---------------- | --------- | ----- | ----------------------------------------------------------------------------------------- | diff --git a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/18_dbms_utility.mdx b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/18_dbms_utility.mdx index c672ff361dc..92d2c915812 100644 --- a/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/18_dbms_utility.mdx +++ b/product_docs/docs/epas/14/epas_compat_bip_guide/03_built-in_packages/18_dbms_utility.mdx @@ -7,28 +7,26 @@ legacyRedirectsGenerated: - "/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 various utility programs: +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 | Canonicalizes a string – e.g., strips off white space. | +| `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_CALL_STACK` | Function | `TEXT` | Format the current call stack. | | `GET_CPU_TIME` | Function | `NUMBER` | Get the current CPU time. | -| `GET_DEPENDENCY(type, schema, name)` | Procedure | n/a | Get objects that are dependent upon the given object.. | +| `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. | -EDB Postgres Advanced Server's implementation of `DBMS_UTILITY` is a partial implementation when compared to Oracle's version. Only those functions and procedures listed in the table above are supported. - The following table lists the public variables available in the `DBMS_UTILITY` package. | Public variables | Data type | Value | Description | @@ -41,7 +39,7 @@ The following table lists the public variables available in the `DBMS_UTILITY` p ## LNAME_ARRAY -The `LNAME_ARRAY` is for storing lists of long names including fully-qualified names. +The `LNAME_ARRAY` is for storing lists of long names including fully qualified names. ```text TYPE lname_array IS TABLE OF VARCHAR2(4000) INDEX BY BINARY_INTEGER; @@ -59,12 +57,12 @@ 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 provide the capability to 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. +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`, `ANALYZE_SCHEMA`, and `ANALYZE_PART_OBJECT` differ primarily in the number of tables that are processed: -- `ANALYZE_DATABASE` analyzes all tables in all schemas within the current database. -- `ANALYZE_SCHEMA` analyzes all tables in a given schema (within the current database). +- `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: @@ -86,23 +84,23 @@ ANALYZE_PART_OBJECT( VARCHAR2, VARCHAR2 `method` - 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 is no difference between `COMPUTE` and `ESTIMATE`; both methods execute the Postgres `ANALYZE` statement. All other parameters are validated and then ignored. + 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 method is `ESTIMATE`. + 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. + 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 method is `ESTIMATE`. + 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. + This argument is ignored but is included for compatibility. `method_opt` - Object types to be analyzed. Any combination of the following: + Object types to analyze. Any combination of the following: ``` [ FOR TABLE ] @@ -112,29 +110,32 @@ ANALYZE_PART_OBJECT( VARCHAR2, VARCHAR2 [ FOR ALL INDEXES ] ``` - This argument is ignored, but is included for compatibility. + This argument is ignored but is included for compatibility. ### Parameters for `ANALYZE_PART_OBJECT` `schema` - Name of the schema whose objects are to be analyzed. + Name of the schema whose objects to analyze. `object_name` - Name of the partitioned object to be analyzed. + Name of the partitioned object to analyze. `object_type` - Type of object to be analyzed. Valid values are: `T` – table, `I` – index. + Type of object to analyze. Valid values are: `T` – table, `I` – index. - This argument is ignored, but is included for compatibility. + 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 upon on a specified number of rows or a percentage of rows in the `sample_clause` clause; `C` - compute exact statistics; or `V` – validate the structure and integrity of the partitions. + 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. + This argument is ignored but is included for compatibility. `command_opt` @@ -150,25 +151,27 @@ ANALYZE_PART_OBJECT( VARCHAR2, VARCHAR2 For `command_type V`, can be `CASCADE` if `object_type` is `T`. - This argument is ignored, but is included for compatibility. + 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 or rows on which to base the estimate. + 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. + This argument is ignored but is included for compatibility. ## CANONICALIZE The `CANONICALIZE` procedure performs the following operations on an input string: -- If the string is not 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 is not double-quoted and does not contain periods, uppercases all alphabetic characters and eliminates leading and trailing spaces. -- If the string is double-quoted and does not 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 and returns the non-double-quoted portions uppercased and enclosed in double quotes. +- 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. ```text CANONICALIZE( VARCHAR2, OUT VARCHAR2, @@ -179,7 +182,7 @@ CANONICALIZE( VARCHAR2, OUT VARCHAR2, `name` - String to be canonicalized. + String to canonicalize. `canon_name` @@ -191,7 +194,7 @@ CANONICALIZE( VARCHAR2, OUT VARCHAR2, ### Examples -The following procedure applies the `CANONICALIZE` procedure on its input parameter and displays the results. +This procedure applies the `CANONICALIZE` procedure on its input parameter and displays the results. ```text CREATE OR REPLACE PROCEDURE canonicalize ( @@ -241,7 +244,7 @@ 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. The names must be formatted as valid identifiers. +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. ```text COMMA_TO_TABLE( VARCHAR2, OUT BINARY_INTEGER, @@ -264,15 +267,15 @@ COMMA_TO_TABLE( VARCHAR2, OUT BINARY_INTEGER, `LNAME_ARRAY` - A `DBMS_UTILITY LNAME_ARRAY` (as described in the [LNAME_ARRAY](#lname_array) section). + A `DBMS_UTILITY LNAME_ARRAY`, as described in [LNAME_ARRAY](#lname_array). `UNCL_ARRAY` - A `DBMS_UTILITY UNCL_ARRAY` (as described in the [UNCL_ARRAY](#uncl_array) section). + A `DBMS_UTILITY UNCL_ARRAY`, as described in [UNCL_ARRAY](#uncl_array). ### Examples -The following procedure uses the `COMMA_TO_TABLE` procedure to convert a list of names to a table. The table entries are then displayed. +This procedure uses the `COMMA_TO_TABLE` procedure to convert a list of names to a table. It then displays the table entries. ```text CREATE OR REPLACE PROCEDURE comma_to_table ( @@ -311,7 +314,7 @@ DB_VERSION( OUT VARCHAR2, OUT VARCHAR2) `compatibility` - Compatibility setting of the database. (To be implementation-defined as to its meaning.) + Compatibility setting of the database (to be implementation-defined as to its meaning). ### Examples @@ -335,7 +338,7 @@ gcc (GCC) 4.1.220080704 (Red Hat 4.1.2-48), 32-bit ## EXEC_DDL_STATEMENT -The `EXEC_DDL_STATEMENT` provides the capability to execute a `DDL` command. +`EXEC_DDL_STATEMENT` executes a `DDL` command. ```text EXEC_DDL_STATEMENT( VARCHAR2) @@ -345,7 +348,7 @@ EXEC_DDL_STATEMENT( VARCHAR2) `parse_string` - The DDL command to be executed. + The DDL command to execute. ### Examples @@ -361,14 +364,14 @@ BEGIN END; ``` -If the `parse_string` does not include a valid DDL statement, EDB Postgres Advanced Server returns the following error: +If the `parse_string` doesn't include a valid DDL statement, EDB Postgres Advanced Server returns an error: ```text 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. +In this case, EDB Postgres Advanced Server's behavior differs from Oracle's. Oracle accepts the invalid `parse_string` without complaint. ## FORMAT_CALL_STACK @@ -379,7 +382,7 @@ DBMS_UTILITY.FORMAT_CALL_STACK return VARCHAR2 ``` -This function can be used in a stored procedure, function or package to return the current call stack in a readable format. This function is useful for debugging purposes. +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. ## GET_CPU_TIME @@ -397,7 +400,7 @@ The `GET_CPU_TIME` function returns the CPU time in hundredths of a second from ### Examples -The following `SELECT` command retrieves the current CPU time, which is 603 hundredths of a second or .0603 seconds. +This `SELECT` command retrieves the current CPU time, which is 603 hundredths of a second or .0603 seconds. ```text SELECT DBMS_UTILITY.GET_CPU_TIME FROM DUAL; @@ -409,7 +412,7 @@ get_cpu_time ## GET_DEPENDENCY -The `GET_DEPENDENCY` procedure provides the capability to list the objects that are dependent upon the specified object. `GET_DEPENDENCY` does not show dependencies for functions or procedures. +The `GET_DEPENDENCY` procedure lists the objects that depend on the specified object. `GET_DEPENDENCY` doesn't show dependencies for functions or procedures. ```text GET_DEPENDENCY( VARCHAR2, VARCHAR2, @@ -420,7 +423,7 @@ GET_DEPENDENCY( VARCHAR2, VARCHAR2, `type` - The object type of `name`. Valid values are `INDEX, PACKAGE, PACKAGE BODY, SEQUENCE, TABLE, TRIGGER, TYPE` and `VIEW`. + The object type of `name`. Valid values are `INDEX`, `PACKAGE`, `PACKAGE BODY`, `SEQUENCE`, `TABLE`, `TRIGGER`, `TYPE`, and `VIEW`. `schema` @@ -428,11 +431,11 @@ GET_DEPENDENCY( VARCHAR2, VARCHAR2, `name` - Name of the object for which dependencies are to be obtained. + Name of the object for which to obtain dependencies. ### Examples -The following anonymous block finds dependencies on the `EMP` table. +The following anonymous block finds dependencies on the `EMP` table: ```text BEGIN @@ -453,7 +456,7 @@ DEPENDENCIES ON public.EMP ## GET_HASH_VALUE -The `GET_HASH_VALUE` function provides the capability to compute a hash value for a given string. +The `GET_HASH_VALUE` function computes a hash value for a given string. ```text NUMBER GET_HASH_VALUE( VARCHAR2, NUMBER, @@ -464,11 +467,11 @@ The `GET_HASH_VALUE` function provides the capability to compute a hash value fo `name` - The string for which a hash value is to be computed. + The string for which to compute a hash value. `base` - Starting value at which hash values are to be generated. + Starting value at which to generate hash values. `hash_size` @@ -517,7 +520,7 @@ MILLER 148 ## GET_PARAMETER_VALUE -The `GET_PARAMETER_VALUE` procedure provides the capability to retrieve database initialization parameter settings. +The `GET_PARAMETER_VALUE` procedure retrieves database initialization parameter settings. ```text BINARY_INTEGER GET_PARAMETER_VALUE( VARCHAR2, @@ -528,7 +531,7 @@ The `GET_PARAMETER_VALUE` procedure provides the capability to retrieve database `parnam` - Name of the parameter whose value is to be returned. The parameters are listed in the `pg_settings` system view. + Name of the parameter whose value to return. The parameters are listed in the `pg_settings` system view. `intval` @@ -540,7 +543,7 @@ The `GET_PARAMETER_VALUE` procedure provides the capability to retrieve database `status` - Returns 0 if the parameter value is `INTEGER` or `BOOLEAN`. Returns 1 if the parameter value is a string. + Returns `0` if the parameter value is `INTEGER` or `BOOLEAN`. Returns `1` if the parameter value is a string. ### Examples @@ -563,7 +566,7 @@ client_encoding: SQL_ASCII ## GET_TIME -The `GET_TIME` function provides the capability to return the current time in hundredths of a second. +The `GET_TIME` function returns the current time in hundredths of a second. ```text