diff --git a/product_docs/docs/bart/2.5.9/bart_inst/images/Ready_to_install.png b/product_docs/docs/bart/2.5.9/bart_inst/images/Ready_to_install.png deleted file mode 100755 index 42c035dde6b..00000000000 --- a/product_docs/docs/bart/2.5.9/bart_inst/images/Ready_to_install.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:dff53263277c8b332d0fd4fd46ed9f96657ddf4b432ec79e8d6e3f7c8c5dda3d -size 19141 diff --git a/product_docs/docs/bart/2.5.9/bart_inst/images/Welcome.png b/product_docs/docs/bart/2.5.9/bart_inst/images/Welcome.png deleted file mode 100755 index edcfd484547..00000000000 --- a/product_docs/docs/bart/2.5.9/bart_inst/images/Welcome.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:b882043ab5999fdbec5a59f9050e4c612ae858401119c7e478068feff4c8c9c7 -size 103820 diff --git a/product_docs/docs/bart/2.5.9/bart_inst/images/completed.png b/product_docs/docs/bart/2.5.9/bart_inst/images/completed.png deleted file mode 100755 index aac35e4cc1a..00000000000 --- a/product_docs/docs/bart/2.5.9/bart_inst/images/completed.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:cbcecc9cf18e08834b9d70b555da4db55d2d8a6c8943733b373852f46146d269 -size 134249 diff --git a/product_docs/docs/bart/2.5.9/bart_inst/images/ready_to_install_1.png b/product_docs/docs/bart/2.5.9/bart_inst/images/ready_to_install_1.png deleted file mode 100644 index 7b3128d7ac4..00000000000 --- a/product_docs/docs/bart/2.5.9/bart_inst/images/ready_to_install_1.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:6fd4bd01005c99a39a0ee6983c919d5aeda1ada277e11060b705b8ba49859444 -size 84697 diff --git a/product_docs/docs/bart/2.5.9/bart_inst/images/stackbuilder.png b/product_docs/docs/bart/2.5.9/bart_inst/images/stackbuilder.png deleted file mode 100755 index cf04a099503..00000000000 --- a/product_docs/docs/bart/2.5.9/bart_inst/images/stackbuilder.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:cfd27423af1b196c22bc25032e829115b37492aa89a36126103e76586f6b50f3 -size 238397 diff --git a/product_docs/docs/bart/2.5.9/bart_inst/images/the_installing_dialog1.png b/product_docs/docs/bart/2.5.9/bart_inst/images/the_installing_dialog1.png deleted file mode 100755 index 12bb5eddc2d..00000000000 --- a/product_docs/docs/bart/2.5.9/bart_inst/images/the_installing_dialog1.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:7bf5aa48fa7487b0374b4ab3d27cbdc3767386b61bb1191ffb1537789386c696 -size 103249 diff --git a/product_docs/docs/epas/12/ecpgplus_guide/02_overview.mdx b/product_docs/docs/epas/12/ecpgplus_guide/02_overview.mdx deleted file mode 100644 index 28d802902ce..00000000000 --- a/product_docs/docs/epas/12/ecpgplus_guide/02_overview.mdx +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: "ECPGPlus - Overview" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/13/overview.html" ---- - - - -EnterpriseDB 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. - -The following diagram charts the path of a program containing embedded SQL statements as it is 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`). - -While the ECPGPlus preprocessor validates the *syntax* of each SQL statement, it cannot validate the *semantics*. For example, the preprocessor will confirm that an `INSERT` statement is syntactically correct, but it cannot confirm that the table mentioned in the `INSERT` statement actually exists. - -**Behind the Scenes** - -A client application contains a mix of C code and SQL code comprised of the following elements: - -- C preprocessor directives -- C declarations (variables, types, functions, ...) -- C definitions (variables, types, functions, ...) -- SQL preprocessor directives -- SQL statements - -For example: - -```text -1 #include -2 EXEC SQL INCLUDE sqlca; -3 -4 extern void printInt(char *label, int val); -5 extern void printStr(char *label, char *val); -6 extern void printFloat(char *label, float val); -7 -8 void displayCustomer(int custNumber) -9 { -10 EXEC SQL BEGIN DECLARE SECTION; -11 VARCHAR custName[50]; -12 float custBalance; -13 int custID = custNumber; -14 EXEC SQL END DECLARE SECTION; -15 -16 EXEC SQL SELECT name, balance -17 INTO :custName, :custBalance -18 FROM customer -19 WHERE id = :custID; -20 -21 printInt("ID", custID); -22 printStr("Name", custName); -23 printFloat("Balance", custBalance); -24 } -``` - -In the above 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 will appear 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. - -- Lines 4 through 6 contain C declarations. - - C declarations are copied to the output file without change, except that each `VARCHAR` declaration is translated into an equivalent `struct` declaration. - -- Lines 10 through 14 contain an embedded-SQL declaration section. - - C variables that you refer to 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. - -- Lines 16 through 19 contain a SQL statement. - - SQL statements are translated into calls to the ECPGPlus run-time 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: - -```text -printf(“Updating employee salaries\n”); - -EXEC SQL UPDATE emp SET sal = sal * 1.25; -EXEC SQL COMMIT; - -printf(“Employee salaries updated\n”); -``` - -When the preprocessor encounters 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: - -```text -printf("Updating employee salaries\n"); - -{ - ECPGdo( __LINE__, 0, 1, NULL, 0, ECPGst_normal, - "update emp set sal = sal * 1.25", - ECPGt_EOIT, ECPGt_EORT); -} - -{ - ECPGtrans(__LINE__, NULL, "commit"); -} - -printf(“Employee salaries updated\n”); -``` - -## Installation and Configuration - -On Windows, ECPGPlus is installed by the 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 Advanced Server version number. By default, the executable is located in: - -On Windows: - -```text -C:\Program Files\edb\as12\bin -``` - -On Linux: - -```text -/usr/edb/as12/bin -``` - -When invoking the ECPGPlus compiler, the executable must be in your search path (`%PATH%` on Windows, `$PATH` on Linux). For example, the following commands set the search path to include the directory that holds the ECPGPlus executable file `ecpg`. - -On Windows: - -```text -set EDB_PATH=C:\Program Files\edb\as12\bin -set PATH=%EDB_PATH%;%PATH% -``` - -On Linux: - -```text -export EDB_PATH==/usr/edb/as12/bin -export PATH=$EDB_PATH:$PATH -``` - -## Constructing a Makefile - -A `makefile` contains a set of instructions that tell the `make` utility how to transform a program written in C (that contains embedded SQL) into a C program. To try the examples in this guide, you will need: - -- a C compiler (and linker) -- the `make` utility -- ECPGPlus preprocessor and library -- a `makefile` that contains instructions for ECPGPlus - -The following code is an example of a `makefile` for the samples included in this guide. 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) -LIBPATH = -L $(shell pg_config --libdir) -CFLAGS += $(INCLUDES) -g -LDFLAGS += -g -LDLIBS += $(LIBPATH) -lecpg -lpq - -.SUFFIXES: .pgc,.pc - -.pgc.c: - ecpg -c $(INCLUDES) $? - -.pc.c: - ecpg -C PROC -c $(INCLUDES) $? -``` - -The first two lines use the `pg_config` program to locate the necessary header files and library directories: - -```text -INCLUDES = -I$(shell pg_config --includedir) -LIBPATH = -L $(shell pg_config --libdir) -``` - -The `pg_config` program is shipped with 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`) - -```text -CFLAGS += $(INCLUDES) -g -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 will be 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. - -```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. - -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: - -```text -make customer_list -``` - -The `make` utility consults the `makefile` (located in the current directory), discovers that the `makefile` contains a rule that will compile `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. - -## 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. - -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: - -```text -$ ecpg -C PROC INCLUDE=/usr/edb/as12/include acct_update.c -``` - -To display a complete list of the other ECPGPlus options available, navigate to the ECPGPlus installation directory, and enter: - -```text -./ecpg --help -``` - -The command line options are: - -| **Option** | **Description** | -| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| -c | Automatically generate C code from embedded SQL code. | -| -C *mode* | Use the `-C` option to specify a compatibility mode:

`INFORMIX`

`INFORMIX_SE`

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

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

`no_indicator` - Do not use indicators, but instead use special values to represent NULL values.

`prepare` - Prepare all statements before using them.

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

`usebulk` - Enable bulk processing for `INSERT`, `UPDATE`, and `DELETE` statements that operate on host variable arrays. | -| --regression | Run in regression testing mode. | -| -t | Turn on `autocommit` of transactions. | -| -l | Disable `#line` directives. | -| --help | Display the help options. | -| --version | Output version information. | - -!!! Note - If you do not 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. diff --git a/product_docs/docs/epas/12/ecpgplus_guide/04_using_descriptors.mdx b/product_docs/docs/epas/12/ecpgplus_guide/04_using_descriptors.mdx deleted file mode 100644 index aface5c6517..00000000000 --- a/product_docs/docs/epas/12/ecpgplus_guide/04_using_descriptors.mdx +++ /dev/null @@ -1,556 +0,0 @@ ---- -title: "Using Descriptors" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/13/using_descriptors.html" ---- - - - -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 a statement will take 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. - -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: - -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. -5. Use a `DESCRIBE` statement to describe the select list into the select-list descriptor. -6. Use a `DESCRIBE` statement to describe the input parameters into the bind-variables descriptor. -7. Prompt the user (if required) for a value for each input parameter. Use a `SET DESCRIPTOR` statement to assign the values into a descriptor. -8. Use a `DECLARE CURSOR` statement to define a cursor for the statement. -9. Use an `OPEN CURSOR` statement to open a cursor for the statement. -10. Use a `FETCH` statement to fetch each row from the cursor, storing each row in select-list descriptor. -11. Use a `GET DESCRIPTOR` command to interrogate the select-list descriptor to find the value of each column in the current row. -12. Use a `CLOSE CURSOR` statement to close the cursor and free any cursor resources. - -A descriptor may contain the attributes listed in the table below: - -| **Field** | **Type** | **Attribute Description** | -| ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `CARDINALITY` | `integer` | The number of rows in the result set. | -| `DATA` | N/A | The data value. | -| `DATETIME_INTERVAL_CODE` | `integer` | If `TYPE` is `9`:

`1 - DATE`

`2 - TIME`

`3 - TIMESTAMP`

`4 - TIME WITH TIMEZONE`

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

`1 - SQL3_CHARACTER`

`2 - SQL3_NUMERIC`

`3 - SQL3_DECIMAL`

`4 - SQL3_INTEGER`

`5 - SQL3_SMALLINT`

`6 - SQL3_FLOAT`

`7 - SQL3_REAL`

`8 - SQL3_DOUBLE_PRECISION`

`9 - SQL3_DATE_TIME_TIMESTAMP`

`10 - SQL3_INTERVAL`

`12 - SQL3_CHARACTER_VARYING`

`13 - SQL3_ENUMERATED`

`14 - SQL3_BIT`

`15 - SQL3_BIT_VARYING`

`16 - SQL3_BOOLEAN` | - -## Example - Using a Descriptor to Return Data - -The following simple application executes an SQL statement entered by an end user. The code sample demonstrates: - -- 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 the SQL statement will be performed, and a string that contains the text of the query. - -For example, a user might invoke the sample with the following command: - -```text -./exec_stmt edb "SELECT * FROM emp" - - -/************************************************************ -/* exec_stmt.pgc -* -*/ - -#include -#include -#include -#include - -EXEC SQL WHENEVER SQLERROR SQLPRINT; -static void print_meta_data( char * desc_name ); - -char *md1 = "col field data ret"; -char *md2 = "num name type len"; -char *md3 = "--- -------------------- ----------------- ---"; - -int main( int argc, char *argv[] ) -{ - - EXEC SQL BEGIN DECLARE SECTION; - char *db = argv[1]; - char *stmt = argv[2]; - int col_count; - EXEC SQL END DECLARE SECTION; - - EXEC SQL CONNECT TO :db; - - EXEC SQL ALLOCATE DESCRIPTOR parse_desc; - EXEC SQL PREPARE query FROM :stmt; - EXEC SQL DESCRIBE query INTO SQL DESCRIPTOR parse_desc; - EXEC SQL GET DESCRIPTOR 'parse_desc' :col_count = COUNT; - -if( col_count == 0 ) -{ - EXEC SQL EXECUTE IMMEDIATE :stmt; - - if( sqlca.sqlcode >= 0 ) - EXEC SQL COMMIT; -} -else -{ - int row; - - EXEC SQL ALLOCATE DESCRIPTOR row_desc; - EXEC SQL DECLARE my_cursor CURSOR FOR query; - EXEC SQL OPEN my_cursor; - - for( row = 0; ; row++ ) - { - EXEC SQL BEGIN DECLARE SECTION; - int col; - EXEC SQL END DECLARE SECTION; - EXEC SQL FETCH IN my_cursor - INTO SQL DESCRIPTOR row_desc; - - if( sqlca.sqlcode != 0 ) - break; - - if( row == 0 ) - print_meta_data( "row_desc" ); - - printf("[RECORD %d]\n", row+1); - - for( col = 1; col <= col_count; col++ ) - { - EXEC SQL BEGIN DECLARE SECTION; - short ind; - varchar val[40+1]; - varchar name[20+1]; - EXEC SQL END DECLARE SECTION; - - EXEC SQL GET DESCRIPTOR 'row_desc' - VALUE :col - :val = DATA, :ind = INDICATOR, :name = NAME; - - if( ind == -1 ) - printf( " %-20s : \n", name.arr ); - else if( ind > 0 ) - printf( " %-20s : \n", name.arr ); - else - printf( " %-20s : %s\n", name.arr, val.arr ); - } - - printf( "\n" ); - - } - printf( "%d rows\n", row ); -} - -exit( 0 ); -} - -static void print_meta_data( char *desc_name ) -{ - EXEC SQL BEGIN DECLARE SECTION; - char *desc = desc_name; - int col_count; - int col; - EXEC SQL END DECLARE SECTION; - -static char *types[] = -{ - "unused ", - "CHARACTER ", - "NUMERIC ", - "DECIMAL ", - "INTEGER ", - "SMALLINT ", - "FLOAT ", - "REAL ", - "DOUBLE ", - "DATE_TIME ", - "INTERVAL ", - "unused ", - "CHARACTER_VARYING", - "ENUMERATED ", - "BIT ", - "BIT_VARYING ", - "BOOLEAN ", - "abstract " -}; - -EXEC SQL GET DESCRIPTOR :desc :col_count = count; - - -printf( "%s\n", md1 ); -printf( "%s\n", md2 ); -printf( "%s\n", md3 ); - -for( col = 1; col <= col_count; col++ ) -{ - - EXEC SQL BEGIN DECLARE SECTION; - int type; - int ret_len; - varchar name[21]; - EXEC SQL END DECLARE SECTION; - char *type_name; - - EXEC SQL GET DESCRIPTOR :desc - VALUE :col - :name = NAME, - :type = TYPE, - :ret_len = RETURNED_OCTET_LENGTH; - - if( type > 0 && type < SQL3_abstract ) - type_name = types[type]; - else - type_name = "unknown"; - - printf( "%02d: %-20s %-17s %04d\n", - col, name.arr, type_name, ret_len ); -} -printf( "\n" ); -} - -/************************************************************ -``` - -The code sample begins by including the prototypes and type definitions for the C `stdio` and `stdlib` libraries, SQL data type symbols, and the `SQLCA` (SQL communications area) structure: - -```text -#include -#include -#include -#include -``` - -The sample provides minimal error handling; when the application encounters an SQL error, it prints the error message to screen: - -```text -EXEC SQL WHENEVER SQLERROR SQLPRINT; -``` - -The application includes a forward-declaration for a function named `print_meta_data()` that will print the metadata found in a descriptor: - -```text -static void print_meta_data( char * desc_name ); -``` - -The following code specifies the column header information that the application will use when printing the metadata: - -```text -char *md1 = "col field data ret"; -char *md2 = "num name type len"; -char *md3 = "--- -------------------- ----------------- ---"; - -int main( int argc, char *argv[] ) -{ -``` - -The following declaration section identifies the host variables that will contain the name of the database to which the application will connect, the content of the SQL Statement, and a host variable that will hold the number of columns in the result set (if any). - -```text -EXEC SQL BEGIN DECLARE SECTION; - char *db = argv[1]; - char *stmt = argv[2]; - int col_count; -EXEC SQL END DECLARE SECTION; -``` - -The application connects to the database (using the default credentials): - -```text -EXEC SQL CONNECT TO :db; -``` - -Next, the application allocates an 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: - -```text -EXEC SQL PREPARE query FROM :stmt; -``` - -and 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`. - -```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: - -```text -if( col_count == 0 ) -{ - EXEC SQL EXECUTE IMMEDIATE :stmt; -``` - -If the statement executes successfully, the application performs a `COMMIT`: - -```text -if( sqlca.sqlcode >= 0 ) - EXEC SQL COMMIT; -} -else -{ -``` - -If the statement entered by the user is a `SELECT` statement (which we know because the column count is non-zero), the application declares a variable named `row`. - -```text -int row; -``` - -Then, the application allocates another descriptor that holds the description and the values of a specific row in the result set: - -```text -EXEC SQL ALLOCATE DESCRIPTOR row_desc; -``` - -The application declares and opens a cursor for the prepared statement: - -```text -EXEC SQL DECLARE my_cursor CURSOR FOR query; -EXEC SQL OPEN my_cursor; -``` - -Loops through the rows in result set: - -```text -for( row = 0; ; row++ ) -{ - EXEC SQL BEGIN DECLARE SECTION; - int col; - EXEC SQL END DECLARE SECTION; -``` - -Then, 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: - -```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. - -```text -if( row == 0 ) - print_meta_data( "row_desc" ); -``` - -Next, it prints a record header containing the row number: - -```text -printf("[RECORD %d]\n", row+1); -``` - -Then, it loops through each column in the row: - -```text -for( col = 1; col <= col_count; col++ ) -{ - EXEC SQL BEGIN DECLARE SECTION; - short ind; - varchar val[40+1]; - varchar name[20+1]; - EXEC SQL END DECLARE SECTION; -``` - -The application interrogates the row descriptor `(row_desc)` to copy the column value `(:val)`, null indicator `(:ind)` and column name `(:name)` into the host variables declared above. Notice that you can retrieve multiple items from a descriptor using a comma-separated list. - -```text -EXEC SQL GET DESCRIPTOR row_desc - VALUE :col - :val = DATA, :ind = INDICATOR, :name = NAME; -``` - -If the null indicator `(ind)` is negative, the column value is `NULL`; if the null indicator is greater than `0`, the column value is too long to fit into the val host variable (so we print `)`; otherwise, the null indicator is `0` (meaning `NOT NULL`) so we print the value. In each case, we prefix the value (or `` or ``) with the name of the column. - -```text -if( ind == -1 ) - printf( " %-20s : \n", name.arr ); -else if( ind > 0 ) - printf( " %-20s : \n", name.arr ); -else - printf( " %-20s : %s\n", name.arr, val.arr ); -} - -printf( "\n" ); -} -``` - -When the loop terminates, the application prints the number of rows fetched, and exits: - -```text - printf( "%d rows\n", row ); - } - -exit( 0 ); -} -``` - -The `print_meta_data()` function extracts the metadata from a descriptor and prints the name, data type, and length of each column: - -```text -static void print_meta_data( char *desc_name ) -{ -``` - -The application declares host variables: - -```text -EXEC SQL BEGIN DECLARE SECTION; - char *desc = desc_name; - int col_count; - int col; -EXEC SQL END DECLARE SECTION; -``` - -The application then defines an array of character strings that map data type values `(numeric)` into data type names. We use the numeric value found in the descriptor to index into this array. For example, if we find that a given column is of type `2`, we can find the name of that type `(NUMERIC)` by writing `types[2]`. - -```text -static char *types[] = -{ - "unused ", - "CHARACTER ", - "NUMERIC ", - "DECIMAL ", - "INTEGER ", - "SMALLINT ", - "FLOAT ", - "REAL ", - "DOUBLE ", - "DATE_TIME ", - "INTERVAL ", - "unused ", - "CHARACTER_VARYING", - "ENUMERATED ", - "BIT ", - "BIT_VARYING ", - "BOOLEAN ", - "abstract " -}; -``` - -The application retrieves the column count from the descriptor. 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. - -```text -EXEC SQL GET DESCRIPTOR :desc :col_count = count; -``` - -The application prints the column headers (defined at the beginning of this application): - -```text -printf( "%s\n", md1 ); -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. - -```text -for( col = 1; col <= col_count; col++ ) -{ - EXEC SQL BEGIN DECLARE SECTION; - int type; - int ret_len; - varchar name[21]; - EXEC SQL END DECLARE SECTION; - char *type_name; -``` - -It retrieves the name, type code, and length of the current column: - -```text -EXEC SQL GET DESCRIPTOR :desc - VALUE :col - :name = NAME, - :type = TYPE, - :ret_len = RETURNED_OCTET_LENGTH; -``` - -If the numeric type code matches a 'known' type code (that is, a type code found in the `types[]` array), it sets `type_name` to the name of the corresponding type; otherwise, it sets `type_name` to `"unknown"`. - -```text -if( type > 0 && type < SQL3_abstract ) - type_name = types[type]; -else - type_name = "unknown"; -``` - -and prints the column number, name, type name, and length: - -```text - printf( "%02d: %-20s %-17s %04d\n", - col, name.arr, type_name, ret_len ); - } - printf( "\n" ); -} -``` - -If you invoke the sample application with the following command: - -```text -./exec_stmt test "SELECT * FROM emp WHERE empno IN(7902, 7934)" -``` - -The application returns: - -```text -col field                data              ret -num name                 type              len ---- -------------------- ----------------- --- -01: empno                NUMERIC           0004 -02: ename                CHARACTER_VARYING 0004 -03: job                  CHARACTER_VARYING 0007 -04: mgr                  NUMERIC           0004 -05: hiredate             DATE_TIME         0018 -06: sal                  NUMERIC           0007 -07: comm                 NUMERIC           0000 -08: deptno               NUMERIC           0002 - -[RECORD 1] -  empno                : 7902 -  ename                : FORD -  job                  : ANALYST -  mgr                  : 7566 -  hiredate             : 03-DEC-81 00:00:00 -  sal                  : 3000.00 -  comm                 : -  deptno               : 20 - -[RECORD 2] -  empno                : 7934 -  ename                : MILLER -  job                  : CLERK -  mgr                  : 7782 -  hiredate             : 23-JAN-82 00:00:00 -  sal                  : 1300.00 -  comm                 : -  deptno               : 10 - -2 rows -``` diff --git a/product_docs/docs/epas/12/ecpgplus_guide/05_building_executing_dynamic_sql_statements.mdx b/product_docs/docs/epas/12/ecpgplus_guide/05_building_executing_dynamic_sql_statements.mdx deleted file mode 100644 index caf7707262c..00000000000 --- a/product_docs/docs/epas/12/ecpgplus_guide/05_building_executing_dynamic_sql_statements.mdx +++ /dev/null @@ -1,793 +0,0 @@ ---- -title: "Building and Executing Dynamic SQL Statements" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/13/building_executing_dynamic_sql_statements.html" ---- - - - -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 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. - -## Example - Executing a Non-query 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. - -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. - -```text -/***********************************************************/ -#include -#include -#include - -static void handle_error(void); - -int main(int argc, char *argv[]) -{ - char *insertStmt; - - EXEC SQL WHENEVER SQLERROR DO handle_error(); - - EXEC SQL CONNECT :argv[1]; - - insertStmt = "INSERT INTO dept VALUES(50, 'ACCTG', 'SEATTLE')"; - - EXEC SQL EXECUTE IMMEDIATE :insertStmt; - - fprintf(stderr, "ok\n"); - - EXEC SQL COMMIT RELEASE; - - exit(EXIT_SUCCESS); -} - - -static void handle_error(void) -{ - fprintf(stderr, "%s\n", sqlca.sqlerrm.sqlerrmc); - - EXEC SQL WHENEVER SQLERROR CONTINUE; - EXEC SQL ROLLBACK RELEASE; - - exit(EXIT_FAILURE); -} - -/***********************************************************/ -``` - -The code sample begins by including the prototypes and type definitions for the C `stdio, string`, and `stdlib` libraries, and providing basic infrastructure for the program: - -```text -#include -#include -#include - -static void handle_error(void); -int main(int argc, char *argv[]) -{ - char *insertStmt; -``` - -The example then sets up an error handler; ECPGPlus calls the `handle_error()` function whenever a SQL error occurs: - -```text -EXEC SQL WHENEVER SQLERROR DO handle_error(); -``` - -Then, the example connects to the database using the credentials specified on the command line: - -```text -EXEC SQL CONNECT :argv[1]; -``` - -Next, the program uses an `EXECUTE IMMEDIATE` statement to execute a SQL statement, adding a row to the `dept` table: - -```text -insertStmt = "INSERT INTO dept VALUES(50, 'ACCTG', 'SEATTLE')"; - -EXEC SQL EXECUTE IMMEDIATE :insertStmt; -``` - -If the `EXECUTE IMMEDIATE` command fails for any reason, ECPGPlus will invoke 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"); - - EXEC SQL COMMIT RELEASE; - - exit(EXIT_SUCCESS); -} -``` - -ECPGPlus calls the `handle_error()` function whenever it encounters a SQL error. The `handle_error()` function prints the content of the error message, resets the error handler, rolls back any changes, disconnects from the database, and terminates the application. - -```text -static void handle_error(void) -{ - fprintf(stderr, "%s\n", sqlca.sqlerrm.sqlerrmc); - - EXEC SQL WHENEVER SQLERROR CONTINUE; - EXEC SQL ROLLBACK RELEASE; - - exit(EXIT_FAILURE); -} -``` - -## Example - Executing a Non-query 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. - -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). - -ECPGPlus will convert each parameter value to the type required by the SQL statement, if possible; if not possible, ECPGPlus will report an error. - -```text -/***********************************************************/ -#include -#include -#include -#include - -static void handle_error(void); - -int main(int argc, char *argv[]) -{ - char *stmtText; - - EXEC SQL WHENEVER SQLERROR DO handle_error(); - - EXEC SQL CONNECT :argv[1]; - - stmtText = "INSERT INTO dept VALUES(?, ?, ?)"; - - EXEC SQL PREPARE stmtHandle FROM :stmtText; - - EXEC SQL EXECUTE stmtHandle USING :argv[2], :argv[3], :argv[4]; - - fprintf(stderr, "ok\n"); - - EXEC SQL COMMIT RELEASE; - - exit(EXIT_SUCCESS); -} - -static void handle_error(void) -{ - printf("%s\n", sqlca.sqlerrm.sqlerrmc); - EXEC SQL WHENEVER SQLERROR CONTINUE; - EXEC SQL ROLLBACK RELEASE; - - exit(EXIT_FAILURE); -} -/***********************************************************/ -``` - -The code sample begins by including the prototypes and type definitions for the C `stdio, string, stdlib`, and `sqlca` libraries, and providing basic infrastructure for the program: - -```text -#include -#include -#include -#include - -static void handle_error(void); - -int main(int argc, char *argv[]) -{ - char *stmtText; -``` - -The example then sets up an error handler; ECPGPlus calls the `handle_error()` function whenever a SQL error occurs: - -```text -EXEC SQL WHENEVER SQLERROR DO handle_error(); -``` - -Then, the example connects to the database using the credentials specified on the command line: - -```text -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 will create 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(?, ?, ?)"; - -EXEC SQL PREPARE stmtHandle FROM :stmtText; -``` - -After parsing and planning the statement, the application uses the `EXECUTE` statement to execute the statement associated with the statement handle, substituting user-provided values for the parameter markers: - -```text -EXEC SQL EXECUTE stmtHandle USING :argv[2], :argv[3], :argv[4]; -``` - -If the `EXECUTE` command fails for any reason, ECPGPlus will invoke 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"); - - EXEC SQL COMMIT RELEASE; - - exit(EXIT_SUCCESS); -} -``` - -ECPGPlus calls the `handle_error()` function whenever it encounters a SQL error. The `handle_error()` function prints the content of the error message, resets the error handler, rolls back any changes, disconnects from the database, and terminates the application. - -```text -static void handle_error(void) -{ - printf("%s\n", sqlca.sqlerrm.sqlerrmc); - - EXEC SQL WHENEVER SQLERROR CONTINUE; - EXEC SQL ROLLBACK RELEASE; - exit(EXIT_FAILURE); -} -``` - -## Example - Executing a Query With a Known Number of Placeholders - -This example 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. - -```text -/***********************************************************/ -#include -#include -#include -#include -#include - -static void handle_error(void); - -int main(int argc, char *argv[]) -{ - VARCHAR empno[10]; - VARCHAR ename[20]; - - EXEC SQL WHENEVER SQLERROR DO handle_error(); - - EXEC SQL CONNECT :argv[1]; - - EXEC SQL PREPARE queryHandle - FROM "SELECT empno, ename FROM emp WHERE deptno = ?"; - - EXEC SQL DECLARE empCursor CURSOR FOR queryHandle; - - EXEC SQL OPEN empCursor USING :argv[2]; - - EXEC SQL WHENEVER NOT FOUND DO break; - - while(true) - { - - EXEC SQL FETCH empCursor INTO :empno, :ename; - - printf("%-10s %s\n", empno.arr, ename.arr); - } - - EXEC SQL CLOSE empCursor; - - EXEC SQL COMMIT RELEASE; - - exit(EXIT_SUCCESS); -} - -static void handle_error(void) -{ - printf("%s\n", sqlca.sqlerrm.sqlerrmc); - - EXEC SQL WHENEVER SQLERROR CONTINUE; - EXEC SQL ROLLBACK RELEASE; - - exit(EXIT_FAILURE); -} - -/***********************************************************/ -``` - -The code sample begins by including the prototypes and type definitions for the C `stdio, string, stdlib, stdbool`, and `sqlca` libraries, and providing basic infrastructure for the program: - -```text -#include -#include -#include -#include -#include - -static void handle_error(void); - -int main(int argc, char *argv[]) -{ - VARCHAR empno[10]; - VARCHAR ename[20]; -``` - -The example then sets up an error handler; ECPGPlus calls the `handle_error()` function whenever a SQL error occurs: - -```text -EXEC SQL WHENEVER SQLERROR DO handle_error(); -``` - -Then, the example connects to the database using the credentials specified on the command line: - -```text -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 will create 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: - -```text -EXEC SQL DECLARE empCursor CURSOR FOR stmtHandle; - -EXEC SQL OPEN empCursor USING :argv[2]; - -EXEC SQL WHENEVER NOT FOUND DO break; - -while(true) -{ -``` - -The program iterates through the cursor, and prints the employee number and name of each employee in the selected department: - -```text - EXEC SQL FETCH empCursor INTO :empno, :ename; - - printf("%-10s %s\n", empno.arr, ename.arr); -} -``` - -The program then closes the cursor, commits any changes, disconnects from the server, and terminates the application. - -```text - EXEC SQL CLOSE empCursor; - - EXEC SQL COMMIT RELEASE; - - exit(EXIT_SUCCESS); -} -``` - -The application calls the `handle_error()` function whenever it encounters a SQL error. The `handle_error()` function prints the content of the error message, resets the error handler, rolls back any changes, disconnects from the database, and terminates the application. - -```text -static void handle_error(void) -{ - printf("%s\n", sqlca.sqlerrm.sqlerrmc); - - EXEC SQL WHENEVER SQLERROR CONTINUE; - EXEC SQL ROLLBACK RELEASE; - - exit(EXIT_FAILURE); -} -``` - - - -## Example - Executing a Query With an Unknown Number of Variables - -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). - -```text -/***********************************************************/ -#include -#include -#include -#include - -SQLDA *params; -SQLDA *results; - -static void allocateDescriptors(int count, - int varNameLength, - int indNameLenth); -static void bindParams(void); -static void displayResultSet(void); - -int main(int argc, char *argv[]) -{ - EXEC SQL BEGIN DECLARE SECTION; - char *username = argv[1]; - char *password = argv[2]; - char *stmtText = argv[3]; - EXEC SQL END DECLARE SECTION; - - EXEC SQL WHENEVER SQLERROR sqlprint; - - EXEC SQL CONNECT TO test - USER :username - IDENTIFIED BY :password; - - params = sqlald(20, 64, 64); - results = sqlald(20, 64, 64); - - EXEC SQL PREPARE stmt FROM :stmtText; - - EXEC SQL DECLARE dynCursor CURSOR FOR stmt; - - bindParams(); - - EXEC SQL OPEN dynCursor USING DESCRIPTOR params; - - displayResultSet(20); -} - -static void bindParams(void) -{ - EXEC SQL DESCRIBE BIND VARIABLES FOR stmt INTO params; - - if (params->F < 0) - fprintf(stderr, "Too many parameters required\n"); - else - { - int i; - - params->N = params->F; - - for (i = 0; i < params->F; i++) - { - char *paramName = params->S[i]; - int nameLen = params->C[i]; - char paramValue[255]; - - printf("Enter value for parameter %.*s: ", - nameLen, paramName); - - fgets(paramValue, sizeof(paramValue), stdin); - - params->T[i] = 1; /* Data type = Character (1) */ - params->L[i] = strlen(paramValue) - 1; - params->V[i] = strdup(paramValue); - } - } -} - -static void displayResultSet(void) -{ - EXEC SQL DESCRIBE SELECT LIST FOR stmt INTO results; - - if (results->F < 0) - fprintf(stderr, "Too many columns returned by query\n"); - else if (results->F == 0) - return; - else - { - int col; - - results->N = results->F; - - for (col = 0; col < results->F; col++) - { - int null_permitted, length; - - sqlnul(&results->T[col], - &results->T[col], - &null_permitted); - - switch (results->T[col]) - { - case 2: /* NUMERIC */ - { - int precision, scale; - - sqlprc(&results->L[col], &precision, &scale); - - if (precision == 0) - precision = 38; - - length = precision + 3; - break; - } - - case 12: /* DATE */ - { - length = 30; - break; - } - - default: /* Others */ - { - length = results->L[col] + 1; - break; - } - } - - results->V[col] = realloc(results->V[col], length); - results->L[col] = length; - results->T[col] = 1; - } - - EXEC SQL WHENEVER NOT FOUND DO break; - - while (1) - { - const char *delimiter = ""; - - EXEC SQL FETCH dynCursor USING DESCRIPTOR results; - - for (col = 0; col < results->F; col++) - { - if (*results->I[col] == -1) - printf("%s%s", delimiter, ""); - else - printf("%s%s", delimiter, results->V[col]); - delimiter = ", "; - } - - - printf("\n"); - } - } -} -/***********************************************************/ -``` - -The code sample begins by including the prototypes and type definitions for the C `stdio` and `stdlib` libraries. In addition, the program includes the `sqlda.h` and `sqlcpr.h` header files. `sqlda.h` defines the SQLDA structure used throughout this example. `sqlcpr.h` defines a small set of functions used to interrogate the metadata found in an SQLDA structure. - -```text -#include -#include -#include -#include -``` - -Next, the program declares pointers to two SQLDA structures. The first SQLDA structure `(params)` will be used to describe the metadata for any parameter markers found in the dynamic query text. The second SQLDA structure `(results)` will contain 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): - -```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: - -```text -int main(int argc, char *argv[]) -{ - EXEC SQL BEGIN DECLARE SECTION; - char *username = argv[1]; - char *password = argv[2]; - char *stmtText = argv[3]; - EXEC SQL END DECLARE SECTION; - - EXEC SQL WHENEVER SQLERROR sqlprint; - EXEC SQL CONNECT TO test - USER :username - IDENTIFIED BY :password; -``` - -Next, the program calls the `sqlald()` function to allocate the memory required for each descriptor. Each descriptor contains (among other things): - -- 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. - -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. - -```text -params = sqlald(20, 64, 64); -results = sqlald(20, 64, 64); -``` - -After allocating the `SELECT`-list and bind descriptors, the program prepares the dynamic statement and declares a cursor over the result set. - -```text -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. - -```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. - -```text - EXEC SQL OPEN dynCursor USING DESCRIPTOR params; - - 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. - -```text -static void bindParams(void) -{ - EXEC SQL DESCRIBE BIND VARIABLES FOR stmt INTO params; -``` - -If the statement contains no parameter markers, `params->F` will contain 0. If the statement contains more parameters than will fit into the descriptor, `params->F` will contain 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) - fprintf(stderr, "Too many parameters required\n"); -else -{ - int i; - - params->N = params->F; -``` - -Next, the program executes a loop that prompts the user for a value, iterating once for each parameter marker found in the statement. - -```text -for (i = 0; i < params->F; i++) -{ - char *paramName = params->S[i]; - int nameLen = params->C[i]; - char paramValue[255]; - - printf("Enter value for parameter %.*s: ", - nameLen, paramName); - - fgets(paramValue, sizeof(paramValue), stdin); -``` - -After prompting the user for a value for a given parameter, the program *binds* that value to the parameter by setting `params->T[i]` to indicate the data type of the value (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. - -```text - params->T[i] = 1; /* Data type = Character (1) */ - params->L[i] = strlen(paramValue) + 1; - params->V[i] = strdup(paramValue); - } - } -} -``` - -The `displayResultSet()` function loops through each row in the result set and prints the value found in each column. `displayResultSet()` starts by executing a `DESCRIBE SELECT LIST` statement - this statement populates an SQLDA descriptor `(results)` with a description of each column in the result set. - -```text -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` will contain 0. If the statement returns more columns than will fit into the descriptor, `results->F` will contain 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. - -```text -if (results->F < 0) - fprintf(stderr, "Too many columns returned by query\n"); -else if (results->F == 0) - return; -else -{ - int col; - - results->N = results->F; -``` - -Next, the program enters a loop, iterating once for each column in the result set: - -```text -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. - -```text -sqlnul(&results->T[col], - &results->T[col], - &null_permitted); -``` - -After decoding the actual data type of the column, the program modifies the results descriptor to tell ECPGPlus to return each value in the form of a NULL-terminated string. Before modifying the descriptor, the program must compute the amount of space required to hold each value. To make this computation, the program examines the maximum length of each column `(results->V[col])` and the data type of each column `(results->T[col])`. - -For numeric values (where `results->T[col] = 2`), the program calls the `sqlprc()` function to extract the precision and scale from the column length. To compute the number of bytes required to hold a numeric value in string form, `displayResultSet()` starts with the precision (that is, the maximum number of digits) and adds three bytes for a sign character, a decimal point, and a NULL terminator. - -```text -switch (results->T[col]) -{ - case 2: /* NUMERIC */ - { - int precision, scale; - - sqlprc(&results->L[col], &precision, &scale); - - if (precision == 0) - precision = 38; - length = precision + 3; - break; - } -``` - -For date values, the program uses a somewhat arbitrary, hard-coded length of 30. In a real-world application, you may want to more carefully compute the amount of space required. - -```text -case 12: /* DATE */ -{ - length = 30; - break; -} -``` - -For a value of any type other than date or numeric, `displayResultSet()` starts with the maximum column width reported by `DESCRIBE SELECT LIST` and adds one extra byte for the NULL terminator. Again, in a real-world application you may want to include more careful calculations for other data types. - -```text - default: /* Others */ - { - length = results->L[col] + 1; - break; - } -} -``` - -After computing the amount of space required to hold a given column, the program allocates enough memory to hold the value, sets `results->L[col]` to indicate the number of bytes found at `results->V[col]`, 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. - -```text - results->V[col] = malloc(length); - results->L[col] = length; - results->T[col] = 1; -} -``` - -At this point, the results descriptor is configured such that a `FETCH` statement can copy each value into an appropriately sized buffer in the form of a NULL-terminated string. - -Next, the program defines a new error handler to break out of the upcoming loop when the cursor is exhausted. - -```text -EXEC SQL WHENEVER NOT FOUND DO break; - -while (1) -{ - const char *delimiter = ""; -``` - -The program executes a `FETCH` statement to fetch the next row in the cursor into the `results` descriptor. If the `FETCH` statement fails (because the cursor is exhausted), control transfers to the end of the loop because of the `EXEC SQL WHENEVER` directive found before the top of the loop. - - `EXEC SQL FETCH dynCursor USING DESCRIPTOR results;` - -The `FETCH` statement will populate the following members of the results descriptor: - -- `*results->I[col]` will indicate 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]` will contain a positive value. -- `results->V[col]` will contain the value fetched for the given column `(unless *results->I[col]` indicates that the column value is NULL). -- `results->L[col]` will contain 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. - -```text - for (col = 0; col < results->F; col++) - { - if (*results->I[col] == -1) - printf("%s%s", delimiter, ""); - else - printf("%s%s", delimiter, results->V[col]); - delimiter = ", "; - } - - printf("\n"); - } - } -} -/***********************************************************/ -``` diff --git a/product_docs/docs/epas/12/ecpgplus_guide/07_reference.mdx b/product_docs/docs/epas/12/ecpgplus_guide/07_reference.mdx deleted file mode 100644 index dcfa346f20b..00000000000 --- a/product_docs/docs/epas/12/ecpgplus_guide/07_reference.mdx +++ /dev/null @@ -1,1593 +0,0 @@ ---- -title: "Reference" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/13/reference.html" ---- - - - -The sections that follow describe ecpgPlus language elements: - -- C-Preprocessor Directives -- Supported C Data Types -- Type Codes -- The SQLDA Structure -- ECPGPlus Statements - -## C-preprocessor Directives - -The ECPGPlus C-preprocessor enforces two behaviors that are dependent on the mode in which you invoke ECPGPlus: - -- `PROC` mode -- non-`PROC` mode - -**Compiling in PROC Mode** - -In `PROC` mode, ECPGPlus allows you to: - -- Declare host variables outside of an `EXEC SQL BEGIN/END DECLARE SECTION`. -- Use any C variable as a host variable as long as it is of a data type 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: - -```text -#include -#if expression -#ifdef symbolName -#ifndef symbolName -#else -#elif expression -#endif -#define symbolName expansion -#define symbolName([macro arguments]) expansion -#undef symbolName -#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: - -```text -#if HAVE_LONG_LONG == 1 -#define BALANCE_TYPE long long -#else -#define BALANCE_TYPE double -#endif -... -BALANCE_TYPE customerBalance; -``` - -If you invoke ECPGPlus with the following command-line arguments: - -```text -ecpg –C PROC –DHAVE_LONG_LONG=1 -``` - -ECPGPlus will copy the entire fragment (without change) to the output file, but will only send 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: - -```text -ecpg –C PROC –DHAVE_LONG_LONG=0 -``` - -The ECPG parser will receive the following tokens: - -```text -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. - -You can also use compatible syntax when executing the following preprocessor directives with an `EXEC` directive: - -```text -EXEC ORACLE DEFINE -EXEC ORACLE UNDEF -EXEC ORACLE INCLUDE -EXEC ORACLE IFDEF -EXEC ORACLE IFNDEF -EXEC ORACLE ELIF -EXEC ORACLE ELSE -EXEC ORACLE ENDIF -EXEC ORACLE OPTION -``` - -For example, if your code includes the following: - -```text -EXEC ORACLE IFDEF HAVE_LONG_LONG; -#define BALANCE_TYPE long long -EXEC ORACLE ENDIF; -BALANCE_TYPE customerBalance; -``` - -If you invoke ECPGPlus with the following command-line arguments: - -```text -ecpg –C PROC DEFINE=HAVE_LONG_LONG=1 -``` - -ECPGPlus will send the following tokens to the output file, and the ECPG parser: - -```text -long long customerBalance; -``` - -!!! Note - The `EXEC ORACLE` pre-processor directives only work 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: - -```text -SELECT_ERROR={YES|NO} -``` - -The default value is `YES`; a `SELECT` statement will return 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. - -Use `SELECT_ERROR` with the `EXEC ORACLE OPTION` directive. - -**Compiling in non-PROC Mode** - -If you do not 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. - -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 will map 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 will try 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 will try 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. - -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 supported C data types are: - -- `short` -- `int` -- `unsigned int` -- `long long int` -- `float` -- `double` -- `char[n+1]` -- `varchar[n+1]` -- `bool` -- and 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: - -- `timestamp` -- `interval` -- `date` -- `decimal` -- `numeric` - -To use a data type supplied by `pgtypeslib`, you must `#include` the proper header file. - -## Type Codes - -The following table contains the type codes for *external* data types. An external data type is used to indicate the type of a C host variable. When an application binds a value to a parameter or binds a buffer to a `SELECT`-list item, the type code in the corresponding SQLDA descriptor `(descriptor->T[column])` should be set to one of the following values: - -| **Type Code** | **Host Variable Type (C Data Type)** | -| ------------------------------------------------- | ----------------------------------------- | -| `1, 2, 8, 11, 12, 15, 23, 24, 91, 94, 95, 96, 97` | `char[]` | -| `3` | `int` | -| `4, 7, 21` | `float` | -| `5, 6` | `null-terminated string (char[length+1])` | -| `9` | `varchar` | -| `22` | `double` | -| `68` | `unsigned int` | - -The following table contains the type codes for *internal* data types. An internal type code is used to indicate the type of a value as it resides in the database. The `DESCRIBE SELECT LIST` statement populates the data type array `(descriptor->T[column])` using the following values. - -| **Internal Type Code** | **Server Type** | -| ---------------------- | ------------------------ | -| `1` | `VARCHAR2` | -| `2` | `NUMBER` | -| `8` | `LONG` | -| `11` | `ROWID` | -| `12` | `DATE` | -| `23` | `RAW` | -| `24` | `LONG RAW` | -| `96` | `CHAR` | -| `100` | `BINARY FLOAT` | -| `101` | `BINARY DOUBLE` | -| `104` | `UROWID` | -| `187` | `TIMESTAMP` | -| `188` | `TIMESTAMP W/TIMEZONE` | -| `189` | `INTERVAL YEAR TO MONTH` | -| `190` | `INTERVAL DAY TO SECOND` | -| `232` | `TIMESTAMP LOCAL_TZ` | - - - -## The SQLDA Structure - -Oracle Dynamic SQL method 4 uses the SQLDA data structure to hold the data and metadata for a dynamic SQL statement. A SQLDA structure can describe a set of input parameters corresponding to the parameter markers found in the text of a dynamic statement or the result set of a dynamic statement. The layout of the SQLDA structure is: - -```text -struct SQLDA -{ - int N; /* Number of entries */ - char **V; /* Variables */ - int *L; /* Variable lengths */ - short *T; /* Variable types */ - short **I; /* Indicators */ - int F; /* Count of variables discovered by DESCRIBE */ - char **S; /* Variable names */ - short *M; /* Variable name maximum lengths */ - short *C; /* Variable name actual lengths */ - char **X; /* Indicator names */ - short *Y; /* Indicator name maximum lengths */ - short *Z; /* Indicator name actual lengths */ -}; -``` - -**Parameters** - -`N - maximum number of entries` - - The N structure member contains the maximum number of entries that the SQLDA 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. - -`V - data values` - - The `V` structure member is a pointer to an array of data values. - -- For a `SELECT`-list descriptor, `V` points to an array of values returned by a `FETCH` statement (each member in the array corresponds to a column in the result set). -- For a bind descriptor, `V` points to an array of parameter values (you must populate the values in this array before opening a cursor that uses the descriptor). - -Your application must allocate the space required to hold each value. 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. - -`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. - -`T - data types` - - The `T` structure member points to an array of data types, one for each column (or parameter) described by the descriptor. - -- For a bind descriptor, you must set each member of the `T` array to tell ECPGPlus the data type of each parameter. -- For a `SELECT`-list descriptor, the `DESCRIBE SELECT LIST` statement sets each member of the `T` array to reflect the type of data found in the corresponding column. - -You 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: - -``` -void sqlnul(unsigned short *valType, - unsigned short *typeCode, - int *isNull) -``` - -For example, to find the type code and nullable flag for the third column of a descriptor named results, you would invoke `sqlnul()` as follows: - -``` -sqlnul(&results->T[2], &typeCode, &isNull); -``` - -`I - indicator variables` - - The `I` structure member points to an array of indicator variables. This array is allocated for you when your application calls the `sqlald()` function to allocate the descriptor. - -- For a `SELECT`-list descriptor, each member of the `I` array indicates whether the corresponding column contains a NULL (non-zero) or non-NULL (zero) value. -- For a bind parameter, your application must set each member of the `I` array to indicate whether the corresponding parameter value is NULL. - -`F - number of entries` - - The `F` structure member indicates how many values are described by the descriptor (the `N` structure member indicates the *maximum* number of values 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. - -- For a `SELECT`-list descriptor, `F` will contain 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` will contain 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. - -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. - -`S - column/parameter names` - - The `S` structure member points to an array of NULL-terminated strings. - -- For a `SELECT`-list descriptor, the `DESCRIBE SELECT LIST` statement sets each member of this array to the name of the corresponding column in the result set. -- For a bind descriptor, the `DESCRIBE BIND VARIABLES` statement sets each member of this array to the name of the corresponding bind variable. - -In this release, the name of each bind variable is determined by the left-to-right order of the parameter marker within the query - for example, the name of the first parameter is always `?0`, the name of the second parameter is always `?1`, and so on. - -`M - maximum column/parameter name length` - - The `M` structure member points to an array of lengths. Each member in this array specifies the *maximum* length of the corresponding member of the `S` array (that is, `M[0]` specifies the maximum length of the column/parameter name found at `S[0]`). This array is populated by the `sqlald()` function. - -`C - actual column/parameter name length` - - The `C` structure member points to an array of lengths. Each member in this array specifies the *actual* length of the corresponding member of the `S` array (that is, `C[0]` specifies the actual length of the column/parameter name found at `S[0]`). - - This array is populated by the `DESCRIBE` statement. - -`X - indicator variable names` - - The `X` structure member points to an array of NULL-terminated strings -each string represents the name of a NULL indicator for the corresponding value. - - This array is not used by ECPGPlus, but is provided for compatibility with Pro\*C applications. - -`Y - maximum indicator name length` - - The `Y` structure member points to an array of lengths. Each member in this array specifies the *maximum* length of the corresponding member of the `X` array (that is, `Y[0]` specifies the maximum length of the indicator name found at `X[0]`). - - This array is not used by ECPGPlus, but is provided for compatibility with Pro\*C applications. - -`Z - actual indicator name length` - - The `Z` structure member points to an array of lengths. Each member in this array specifies the *actual* length of the corresponding member of the `X` array (that is, `Z[0]` specifies the actual length of the indicator name found at `X[0]`). - - This array is not 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. - -You can embed any 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: - -```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: - - - -### ALLOCATE DESCRIPTOR - -Use the `ALLOCATE DESCRIPTOR` statement to allocate an SQL descriptor area: - -```text -EXEC SQL [FOR ] ALLOCATE DESCRIPTOR - [WITH MAX ]; -``` - -Where: - -`array_size` is a variable that specifies the number of array elements to allocate for the descriptor. `array_size` 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. - -`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)`: - -```text -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 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*: - -```text -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 do not specify the schema or package in which the program resides, ECPGPlus will use 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. - -`:ret_variable` specifies a host variable that will receive the value returned if the program is a function. - -`:ret_indicator` specifies a host variable that will receive 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: - -```text -EXEC SQL CALL get_job_desc(:ename) - INTO :job; -``` - -### CLOSE - -Use the `CLOSE` statement to close a cursor, and free any resources scurrently in use by the cursor. A client application cannot fetch rows from a closed cursor. The syntax of the `CLOSE` statement is: - -```text -EXEC SQL CLOSE []; -``` - -Where: - -`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 will remain unchanged unless the cursor is re-opened. You do not need to `CLOSE` a cursor before re-opening it. - -To manually close a cursor named `emp_cursor`, use the command: - -```text -EXEC SQL CLOSE emp_cursor; -``` - -A cursor is automatically closed when an application terminates. - -### COMMIT - -Use the `COMMIT` statement to complete the current transaction, making all changes permanent and visible to other users. The syntax is: - -```text -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. - -For compatibility, ECPGPlus accepts the `COMMENT` clause without error but does *not* store any text included with the `COMMENT` clause. - -Include the `RELEASE` clause to close the current connection after performing the commit. - -For example, the following command commits all work performed on the `dept` database and closes the current connection: - -```text -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: - -```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. - -The first form is compatible with Oracle databases: - -```text -EXEC SQL CONNECT - {{: IDENTIFIED BY :} | :} - [AT ] - [USING :database_string] - [ALTER AUTHORIZATION :new_password]; -``` - -Where: - -`user_name` is a host variable that contains the role that the client application will use to connect to the server. - -`password` is a host variable that contains the password associated with that role. - -`connection_id` is a host variable that contains a slash-delimited user name and password used to connect to the database. - -Include the `AT` clause to specify the database to which the connection is established. `database_name` is the name of the database to which the client is connecting; specify the value in the form of a variable, or as a string literal. - -Include the `USING` clause to specify a host variable that contains a null-terminated string identifying the database to which the connection will be established. - -The `ALTER AUTHORIZATION` clause is supported for syntax compatibility only; ECPGPlus parses the `ALTER AUTHORIZATION` clause, and reports a warning. - -Using the first form of the `CONNECT` statement, a client application might establish a connection with a host variable named `user` that contains the identity of the connecting role, and a host variable named `password` that contains the associated password using the following command: - -```text -EXEC SQL CONNECT :user IDENTIFIED BY :password; -``` - -A client application 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: - -```text -EXEC SQL CONNECT :connection_id; -``` - -The syntax of the second form of the `CONNECT` statement is: - -```text -EXEC SQL CONNECT TO -[AS ] []; -``` - -Where `credentials` is one of the following: - -```text -USER user_name password -USER user_name IDENTIFIED BY password -USER user_name USING password -``` - -In the second form: - -`database_name` is the name or identity of the database to which the client is connecting. Specify `database_name` as a variable, or as a string literal, in one of the following forms: - -```text -[@][:] - -tcp:postgresql://[:][/][options] - -unix:postgresql://[:][/][options] -``` - -Where: - - `hostname` is the name or IP address of the server on which the database resides. - - `port` is the port on which the server listens. - - You can also specify a value of `DEFAULT` to establish a connection with the default database, using the default role name. If you specify `DEFAULT` as the target database, do not 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. - - If you do not 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 do not 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 Advanced Server database. The privileges of the specified role will be applied to all commands performed through the connection. - -`password` is the password associated with the specified `user_name`. - -The following code fragment uses the second form of the `CONNECT` statement to establish a connection to a database named `edb`, using the role `alice` and the password associated with that role, `1safepwd`: - -```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. - -### DEALLOCATE DESCRIPTOR - -Use the `DEALLOCATE DESCRIPTOR` statement to free memory in use by an allocated descriptor. The syntax of the statement is: - -```text -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. - -The following example deallocates a descriptor named `emp_query`: - -```text -EXEC SQL DEALLOCATE DESCRIPTOR emp_query; -``` - -### DECLARE CURSOR - -Use the `DECLARE CURSOR` statement to define a cursor. The syntax of the statement is: - -```text -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 do not 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. - -The following example declares a cursor named `employees`: - -```text -EXEC SQL DECLARE employees CURSOR FOR - SELECT - empno, ename, sal, comm - FROM - emp; -``` - -The cursor generates a result set that contains the employee number, employee name, salary and commission for each employee record that is stored in the `emp` table. - -### DECLARE DATABASE - -Use the `DECLARE DATABASE` statement to declare a database identifier for use in subsequent SQL statements (for example, in a `CONNECT` statement). The syntax is: - -```text -EXEC SQL DECLARE DATABASE; -``` - -Where: - -`database_name` specifies the name of the database. - -The following example demonstrates 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. - -This statement has no effect and is provided for Pro\*C compatibility only. - -### DECLARE STATEMENT - -Use the `DECLARE STATEMENT` directive to declare an identifier for an SQL statement. Advanced Server supports two versions of the `DECLARE STATEMENT` directive: - -```text -EXEC SQL [] DECLARE STATEMENT; -``` - -and - -```text -EXEC SQL DECLARE STATEMENT ; -``` - -Where: - -`statement_name` specifies the identifier associated with the statement. - -`database_name` specifies the name of the database. This value may take the form of an identifier or of a host variable that contains the identifier. - -A typical usage sequence that includes the `DECLARE STATEMENT` directive might be: - -```text -EXEC SQL DECLARE give_raise STATEMENT; // give_raise is now a statement -handle (not prepared) -EXEC SQL PREPARE give_raise FROM :stmtText; // give_raise is now associated -with a statement -EXEC SQL EXECUTE give_raise; -``` - -This statement has no effect and is provided for Pro\*C compatibility only. - -### DELETE - -Use the `DELETE` statement to delete one or more rows from a table. The syntax for the ECPGPlus `DELETE` statement is the same as the syntax for the SQL statement, but you can use parameter markers and host variables any place that an expression is allowed. The syntax is: - -```text -[FOR ] DELETE FROM [ONLY] [[AS] ] - [USING ] - [WHERE | WHERE CURRENT OF ] - [{RETURNING|RETURN} * | [[AS] ] -[, ...] INTO ] -``` - -Where: - -Include the `FOR exec_count` clause to specify the number of times the statement will execute; 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 do not 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 do not include a `WHERE` clause in the statement, `DELETE` will delete 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 will be deleted. - -`cursor_name` is the name of the cursor to use in the `WHERE CURRENT OF` clause; the row to be deleted will be 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. - -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:` - -```text -DELETE FROM emp WHERE sal > :max_sal; -``` - -For more information about using the `DELETE` statement, see the PostgreSQL Core documentation available at: - - - -### 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. - -```text -EXEC SQL DESCRIBE BIND VARIABLES FOR INTO ; -``` - -or - -```text -EXEC SQL DESCRIBE SELECT LIST FOR INTO ; -``` - -Where: - -`statement_name` is the identifier associated with a prepared SQL statement or PL/SQL block. - -`descriptor` is the name of C variable of type `SQLDA*`. You must allocate the space for the descriptor by calling `sqlald()` (and initialize the descriptor) before executing the `DESCRIBE` statement. - -When you execute the first form of the `DESCRIBE` statement, ECPG populates the given descriptor with a description of each input variable *required* by the statement. For example, given two descriptors: - -```text -SQLDA *query_values_in; -SQLDA *query_values_out; -``` - -You might prepare a query that returns information from the `emp` table: - -```text -EXEC SQL PREPARE get_emp FROM - "SELECT ename, empno, sal FROM emp WHERE empno = ?"; -``` - -The command requires one input variable (for the parameter marker (?)). - -```text -EXEC SQL DESCRIBE BIND VARIABLES - FOR get_emp INTO query_values_in; -``` - -After describing the bind variables for this statement, you can examine the descriptor to find the number of variables required and the type of each variable. - -When you execute the second form, ECPG populates the given descriptor with a description of each value *returned* by the statement. For example, the following statement returns three values: - -```text -EXEC SQL DESCRIBE SELECT LIST - FOR get_emp INTO query_values_out; -``` - -After describing the select list for this statement, you can examine the descriptor to find the number of returned values and the name and type of each value. - -Before *executing* the statement, you must bind a variable for each input value and a variable for each output value. The variables that you bind for the input values specify the actual values used by the statement. The variables that you bind for the output values tell ECPGPlus where to put the values when you execute the statement. - -This is alternate 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: - -```text -EXEC SQL DESCRIBE [INPUT | OUTPUT] - USING [SQL] DESCRIPTOR ; -``` - -Where: - -`statement_name` is the name of a prepared SQL statement. - -`descriptor_name` is the name of the descriptor. `descriptor_name` can be a quoted string value or a host variable that contains the name of the descriptor. - -If you include the `INPUT` clause, ECPGPlus populates the given descriptor with a description of each input variable *required* by the statement. - -For example, given two descriptors: - -```text -EXEC SQL ALLOCATE DESCRIPTOR query_values_in; -EXEC SQL ALLOCATE DESCRIPTOR query_values_out; -``` - -You might prepare a query that returns information from the `emp` table: - -```text -EXEC SQL PREPARE get_emp FROM - "SELECT ename, empno, sal FROM emp WHERE empno = ?"; -``` - -The command requires one input variable (for the parameter marker (?)). - -```text -EXEC SQL DESCRIBE INPUT get_emp USING 'query_values_in'; -``` - -After describing the bind variables for this statement, you can examine the descriptor to find the number of variables required and the type of each variable. - -If you do not specify the `INPUT` clause, `DESCRIBE DESCRIPTOR` populates the specified descriptor with the values returned by the statement. - -If you include the `OUTPUT` clause, ECPGPlus populates the given descriptor with a description of each value *returned* by the statement. - -For example, the following statement returns three values: - -```text -EXEC SQL DESCRIBE OUTPUT FOR get_emp USING 'query_values_out'; -``` - -After describing the select list for this statement, you can examine the descriptor to find the number of returned values and the name and type of each value. - -### DISCONNECT - -Use the `DISCONNECT` statement to close the connection to the server. The syntax is: - -```text -EXEC SQL DISCONNECT [][CURRENT][DEFAULT][ALL]; -``` - -Where: - -`connection_name` is the connection name specified in the `CONNECT` statement used to establish the connection. If you do not specify a connection name, the current connection is closed. - -Include the `CURRENT` keyword to specify that ECPGPlus should close the most-recently used connection. - -Include the `DEFAULT` keyword to specify that ECPGPlus should close the connection named `DEFAULT`. If you do not specify a name when opening a connection, ECPGPlus assigns the name, `DEFAULT`, to the connection. - -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: - -```text -/* client.pgc*/ -int main() -{ - EXEC SQL CONNECT TO hr AS connection_name; - EXEC SQL DISCONNECT connection_name; - return(0); -} -``` - -### EXECUTE - -Use the `EXECUTE` statement to execute a statement previously prepared using an `EXEC SQL PREPARE` statement. The syntax is: - -```text -EXEC SQL [FOR ] EXECUTE - [USING {DESCRIPTOR - |: [[INDICATOR] :]}]; -``` - -Where: - -`array_size` is an integer value or a host variable that contains an integer value that specifies the number of rows to 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). - -Include the `USING` clause to supply values for parameters within 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: - -```text -EXEC SQL PREPARE add_emp (numeric, text, text, numeric) AS - INSERT INTO emp VALUES($1, $2, $3, $4); -``` - -Each time you invoke the prepared statement, provide fresh parameter values for the statement: - -```text -EXEC SQL EXECUTE add_emp USING 8000, 'DAWSON', 'CLERK', 7788; -EXEC SQL EXECUTE add_emp USING 8001, 'EDWARDS', 'ANALYST', 7698; -``` - -### EXECUTE DESCRIPTOR - -Use the `EXECUTE` statement to execute a statement previously prepared by an `EXEC SQL PREPARE` statement, using an SQL descriptor. The syntax is: - -```text -EXEC SQL [FOR ] EXECUTE - [USING [SQL] DESCRIPTOR ] - [INTO [SQL] DESCRIPTOR ]; -``` - -Where: - -`array_size` is an integer value or a host variable that contains an integer value that specifies the number of rows to 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. - -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 will write 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 -EXEC SQL PREPARE give_raise FROM :stmtText; -EXEC SQL EXECUTE give_raise USING DESCRIPTOR :stmtText; -``` - -### EXECUTE...END EXEC - -Use the `EXECUTE…END-EXEC` statement to embed an anonymous block into a client application. The syntax is: - -```text -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 will be executed 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. - -The following example executes an anonymous block: - -```text -EXEC SQL EXECUTE - BEGIN - IF (current_user = :admin_user_name) THEN - DBMS_OUTPUT.PUT_LINE('You are an administrator'); - END IF; -END-EXEC; -``` - -!!! Note - The `EXECUTE…END EXEC` statement is supported only by Advanced Server. - -### EXECUTE IMMEDIATE - -Use the `EXECUTE IMMEDIATE` statement to execute a string that contains a SQL command. The syntax is: - -```text -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 will be executed 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. - -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 following example executes the command contained in the `:command_text` host variable: - -```text -EXEC SQL EXECUTE IMMEDIATE :command_text; -``` - -### FETCH - -Use the `FETCH` statement to return rows from a cursor into an SQLDA descriptor or a target list of host variables. Before using a `FETCH` statement to retrieve information from a cursor, you must prepare the cursor using `DECLARE` and `OPEN` statements. The statement syntax is: - -```text -EXEC SQL [FOR ] FETCH - { USING DESCRIPTOR }|{ INTO }; -``` - -Where: - -`array_size` is an integer value or a host variable that contains an integer value specifying the number of rows to fetch. If you omit the `FOR` clause, the statement is executed once for each member of the array. - -`cursor` is the name of the cursor from which rows are being fetched, or a host variable that contains the name of the cursor. - -If you include a `USING` clause, the `FETCH` statement will populate the specified SQLDA descriptor with the values returned by the server. - -If you include an `INTO` clause, the `FETCH` statement will populate 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: - -```text -EXEC SQL DECLARE employees CURSOR - SELECT empno, ename, esal FROM emp -EXEC SQL OPEN emp_cursor -EXEC SQL FETCH emp_cursor INTO :emp_no, :emp_name, :emp_sal; -``` - -### FETCH DESCRIPTOR - -Use the `FETCH DESCRIPTOR` statement to retrieve rows from a cursor into an SQL descriptor. The syntax is: - -```text -EXEC SQL [FOR ] FETCH - INTO [SQL] DESCRIPTOR ; -``` - -Where: - -`array_size` is an integer value or a host variable that contains an integer value specifying the number of rows to fetch. If you omit the `FOR` clause, the statement is executed once for each member of the array. - -`cursor` is the name of the cursor from which rows are fetched, or a host variable that contains the name of the cursor. The client must `DECLARE` and `OPEN` the cursor before calling the `FETCH DESCRIPTOR` statement. - -Include the `INTO` clause to specify an SQL descriptor into which the `EXECUTE` statement will write 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. - -The following example allocates a descriptor named `row_desc` that will hold 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: - -```text -EXEC SQL ALLOCATE DESCRIPTOR 'row_desc'; -EXEC SQL DECLARE my_cursor CURSOR FOR query; -EXEC SQL OPEN my_cursor; - -for( row = 0; ; row++ ) -{ - EXEC SQL BEGIN DECLARE SECTION; - int col; - EXEC SQL END DECLARE SECTION; - EXEC SQL FETCH my_cursor INTO SQL DESCRIPTOR 'row_desc'; -``` - -### GET DESCRIPTOR - -Use the `GET DESCRIPTOR` statement to retrieve information from a descriptor. The `GET DESCRIPTOR` statement comes in two forms. The first form returns the number of values (or columns) in the descriptor. - -```text -EXEC SQL GET DESCRIPTOR - : = COUNT; -``` - -The second form returns information about a specific value (specified by the `VALUE column_number` clause). - -```text -EXEC SQL [FOR ] GET DESCRIPTOR - VALUE {: = {,…}}; -``` - -Where: - -`array_size` is an integer value or a host variable that contains an integer value that specifies the number of rows to 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. - -Include the `VALUE` clause to specify the information retrieved from the descriptor. - -- `column_number` identifies the position of the variable within the descriptor. - -- `host_variable` specifies the name of the host variable that will receive the value of the item. - -- `descriptor_item` specifies the type of the retrieved descriptor item. - -ECPGPlus implements the following `descriptor_item` types: - -- `TYPE` -- `LENGTH` -- `OCTET_LENGTH` -- `RETURNED_LENGTH` -- `RETURNED_OCTET_LENGTH` -- `PRECISION` -- `SCALE` -- `NULLABLE` -- `INDICATOR` -- `DATA` -- `NAME` - -The following code fragment demonstrates using a `GET DESCRIPTOR` statement to obtain the number of columns entered in a user-provided string: - -```text -EXEC SQL ALLOCATE DESCRIPTOR parse_desc; -EXEC SQL PREPARE query FROM :stmt; -EXEC SQL DESCRIBE query INTO SQL DESCRIPTOR parse_desc; -EXEC SQL GET DESCRIPTOR parse_desc :col_count = COUNT; -``` - -The example allocates an SQL descriptor (named `parse_desc`), before using a `PREPARE` statement to 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. - -### INSERT - -Use the `INSERT` statement to add one or more rows to a table. The syntax for the ECPGPlus `INSERT` statement is the same as the syntax for the SQL statement, but you can use parameter markers and host variables any place that a value is allowed. The syntax is: - -```text -[FOR ] INSERT INTO
[( [, ...])] - {DEFAULT VALUES | - VALUES ({ | DEFAULT} [, ...])[, ...] | } - [RETURNING * | [[ AS ] ] [, ...]] -``` - -Where: - -Include the `FOR exec_count` clause to specify the number of times the statement will execute; 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. - -`expression` is the expression, value, host variable or parameter marker that will be 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 will be 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. - -The following example adds a row to the `employees` table: - -```text -INSERT INTO emp (empno, ename, job, hiredate) - VALUES ('8400', :ename, 'CLERK', '2011-10-31'); -``` - -!!! Note - The `INSERT` statement uses a host variable `(:ename)` to specify the value of the `ename` column. - -For more information about using the `INSERT` statement, see the PostgreSQL Core documentation available at: - - - -### OPEN - -Use the `OPEN` statement to open a cursor. The syntax is: - -```text -EXEC SQL [FOR ] OPEN [USING ]; -``` - -Where `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. - -The `OPEN` statement initializes a cursor using the values provided in `parameters`. Once initialized, the cursor result set will remain unchanged unless the cursor is closed and re-opened. 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`). - -```text - EXEC SQL DECLARE employees CURSOR FOR - SELECT - empno, ename, sal, comm  - FROM  - emp - WHERE ename = :emp_name; - EXEC SQL OPEN employees; -... -``` - -After declaring the cursor, the example uses an `OPEN` statement to make the contents of the cursor available to a client application. - -### OPEN DESCRIPTOR - -Use the `OPEN DESCRIPTOR` statement to open a cursor with a SQL descriptor. The syntax is: - -```text -EXEC SQL [FOR ] OPEN - [USING [SQL] DESCRIPTOR ] - [INTO [SQL] DESCRIPTOR ]; -``` - -Where: - -`array_size` is an integer value or a host variable that contains an integer value specifying the number of rows to fetch. If you omit the `FOR` clause, the statement is executed once for each member of the array. - -`cursor` is the name of the cursor being opened. - -`descriptor_name` specifies the name of an SQL descriptor (in the form of a single-quoted string literal) or a host variable that contains the name of an SQL descriptor that contains the query that initializes the cursor. - -For example, the following statement opens a cursor (named `emp_cursor`), using the host variable, `:employees`: - -```text -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. - -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: - -```text -EXEC SQL [AT ] PREPARE - FROM ; -``` - -The second form is: - -```text -EXEC SQL [AT ] PREPARE - AS ; -``` - -Where: - -`database_name` is the database identifier or a host variable that contains the database identifier against which the statement will execute. If you omit the `AT` clause, the statement will execute against the current default database. - -`statement_name` is the identifier associated with a prepared SQL statement or PL/SQL block. - -`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. The values must be provided in the order in which they will replace placeholders. - -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 - INSERT INTO emp VALUES($1, $2, $3, $4); -``` - -Each time you invoke the statement, provide fresh parameter values for the statement: - -```text -EXEC SQL EXECUTE add_emp(8003, 'Davis', 'CLERK', 2000.00); -EXEC SQL EXECUTE add_emp(8004, 'Myer', 'CLERK', 2000.00); -``` - -!!! Note - A client application must issue a `PREPARE` statement within each session in which a statement will be executed; 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: - -```text -EXEC SQL [AT ] ROLLBACK [WORK] - [ { TO [SAVEPOINT] } | RELEASE ] -``` - -Where: - -`database_name` is the database identifier or a host variable that contains the database identifier against which the statement will execute. If you omit the `AT` clause, the statement will execute 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 will abort 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: - -```text -EXEC SQL ROLLBACK; -``` - -Invoking this statement will abort the transaction, undoing all changes, erasing any savepoints, and releasing all transaction locks. If 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` will be 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: - -```text -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 will execute 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. - -Savepoints can only be established within a transaction block. A transaction block may contain multiple savepoints. - -To create a savepoint named `my_savepoint`, include the statement: - -```text -EXEC SQL SAVEPOINT my_savepoint; -``` - -### SELECT - -ECPGPlus extends support of the `SQL SELECT` statement by providing the `INTO host_variables` clause. The clause allows you to select specified information from an Advanced Server database into a host variable. The syntax for the `SELECT` statement is: - -```text -EXEC SQL [AT ] -SELECT - [ ] - [ ALL | DISTINCT [ ON( , ...) ]] - select_list INTO - - [ FROM from_item [, from_item ]...] - [ WHERE condition ] - [ hierarchical_query_clause ] - [ GROUP BY expression [, ...]] - [ HAVING condition ] - [ { UNION [ ALL ] | INTERSECT | MINUS } (subquery) ] - [ ORDER BY expression> [order_by_options]] - [ LIMIT { count | ALL }] - [ OFFSET start [ ROW | ROWS ] ] - [ FETCH { FIRST | NEXT } [ count ] { ROW | ROWS } ONLY ] - [ FOR { UPDATE | SHARE } [OF table_name [, ...]][NOWAIT ][...]] -``` - -Where: - -`database_name` is the name of the database (or host variable that contains the name of the database) in which the table resides. This value may take the form of an unquoted string literal, or of a host variable. - -`host_variables` is a list of host variables that will be 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 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`: - -```text -EXEC SQL SELECT ename, sal - INTO :emp_name, :emp_sal - FROM emp - WHERE empno = 7988; -``` - -The enhanced `SELECT` statement also allows you to include parameter markers (question marks) in any clause where a value would be permitted. 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. - -### SET CONNECTION - -There are (at least) three reasons you may 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. - -The syntax for the `SET CONNECTION` statement is: - -```text -EXEC SQL SET CONNECTION ; -``` - -Where: - -`connection_name` is the name of the connection to the database. - -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 will use the default connection because it does not include an `AT` `connection_name` clause. : - -```text -EXEC SQL DELETE FROM emp; -``` - -This statement will not 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): - -```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: - -```text -SET CONNECTION acctg_conn; -``` - -or - -```text -SET CONNECTION hr_conn; -``` - -The server will use the privileges associated with the connection when determining the privileges available to the connecting client. When using the `acctg_conn` connection, the client will have the privileges associated with the role, `alice`; when connected using `hr_conn`, the client will have 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: - -```text -EXEC SQL [FOR ] SET DESCRIPTOR - VALUE = ; -``` - -The second form is: - -```text -EXEC SQL [FOR ] SET DESCRIPTOR - COUNT = integer; -``` - -Where: - -`array_size` is an integer value or a host variable that contains an integer value specifying the number of rows to fetch. If you omit the `FOR` clause, the statement 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 describe the information stored in the descriptor. - -- `column_number` identifies the position of the variable within the descriptor. - -- `descriptor_item` specifies the type of the descriptor item. - -- `host_variable` specifies the name of the host variable that contains the value of the item. - -ECPGPlus implements the following `descriptor_item` types: - -- `TYPE` -- `LENGTH` -- `[REF] INDICATOR` -- `[REF] DATA` -- `[REF] RETURNED LENGTH` - -For example, a client application might prompt a user for a dynamically created query: - -```text -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. - -```text -EXEC SQL ALLOCATE DESCRIPTOR query_params; -EXEC SQL PREPARE emp_query FROM :query_text; - -EXEC SQL DESCRIBE INPUT emp_query - USING SQL DESCRIPTOR 'query_params'; -``` - -After describing the query, the `query_params` descriptor contains information about each parameter required by the query. - -For this example, we'll assume that the user has entered: - -```text -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: - -```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 will convert that string into the required data type. - -The data type of the first parameter is `numeric`; the type of the second parameter is `varchar`. The name of the first parameter is `sal`; the name of the second parameter is `job`. - -Next, loop through each parameter, prompting the user for a value, and store those values in host variables. You can use `GET DESCRIPTOR … COUNT` to find the number of parameters in the query. - -```text -EXEC SQL GET DESCRIPTOR 'query_params' - :param_count = COUNT; - -for(param_number = 1; - param_number <= param_count; - param_number++) -{ -``` - -Use `GET DESCRIPTOR` to copy the name of the parameter into the `param_name` host variable: - -```text -EXEC SQL GET DESCRIPTOR 'query_params' - VALUE :param_number :param_name = NAME; - -reply = promptUser(param_name); -if (reply == NULL) - reply_ind = 1; /* NULL */ -else - reply_ind = 0; /* NOT NULL */ -``` - -To associate a `value` with each parameter, you use the `EXEC SQL SET DESCRIPTOR` statement. For example: - -```text -EXEC SQL SET DESCRIPTOR 'query_params' - VALUE :param_number DATA = :reply; -EXEC SQL SET DESCRIPTOR 'query_params' - VALUE :param_number INDICATOR = :reply_ind; -} -``` - -Now, you can use the `EXEC SQL EXECUTE DESCRIPTOR` statement to execute the prepared statement on the server. - -### UPDATE - -Use an `UPDATE` statement to modify the data stored in a table. The syntax is: - -```text -EXEC SQL [AT ][FOR ] - UPDATE [ ONLY ] table [ [ AS ] alias ] - SET {column = { expression | DEFAULT } | - (column [, ...]) = ({ expression|DEFAULT } [, ...])} [, ...] - [ FROM from_list ] - [ WHERE condition | WHERE CURRENT OF cursor_name ] - [ RETURNING * | output_expression [[ AS ] output_name] [, ...] ] -``` - -Where: - -`database_name` is the name of the database (or host variable that contains the name of the database) in which the table resides. This value 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 will execute; 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 available at: - - - -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. - -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: - -```text -EXEC SQL UPDATE emp - SET job = :new_job, sal = sal * :increase - WHERE ename = :ename; -``` - -The enhanced `UPDATE` statement also allows you to include parameter markers (question marks) in any clause where an input value would be permitted. For example, we can write the same update statement with a parameter marker in the `WHERE` clause: - -```text -EXEC SQL UPDATE emp - SET job = ?, sal = sal * ? - 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`. - -### WHENEVER - -Use the `WHENEVER` statement to specify the action taken by a client application when it encounters an SQL error or warning. The syntax is: - -```text -EXEC SQL WHENEVER ; -``` - -The following table describes the different conditions that might trigger an `action`: - -| **Condition** | **Description** | -| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| `NOT FOUND` | The server returns a `NOT FOUND` condition when it encounters a `SELECT` that returns no rows, or when a `FETCH` reaches the end of a result set. | -| `SQLERROR` | The server returns an `SQLERROR` condition when it encounters a serious error returned by an SQL statement. | -| `SQLWARNING` | The server returns an `SQLWARNING` condition when it encounters a non-fatal warning returned by an SQL statement. | - -The following table describes the actions that result from a client encountering a `condition`: - -| **Action** | **Description** | -| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `CALL function [([args])]` | 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, will cause 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. | - -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: - -```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: - -```text -EXEC SQL WHENEVER NOT FOUND CALL error_handler(__LINE__); -``` diff --git a/product_docs/docs/epas/12/ecpgplus_guide/index.mdx b/product_docs/docs/epas/12/ecpgplus_guide/index.mdx deleted file mode 100644 index 89311ae0fa3..00000000000 --- a/product_docs/docs/epas/12/ecpgplus_guide/index.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -navTitle: ECPGPlus -title: "ECPGPlus Guide" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/13/index.html" - - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/13/conclusion.html" - - "/edb-docs/d/edb-postgres-advanced-server/user-guides/ecpgplus-guide/13/introduction.html" ---- - -EnterpriseDB 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 (Advanced Server) database. When you use ECPGPlus to compile an application, the SQL code is syntax-checked and translated into C. - -ECPGPlus supports: - -- Oracle Dynamic SQL – Method 4 (ODS-M4). -- Pro\*C compatible anonymous blocks. -- A `CALL` statement compatible with Oracle databases. - -As part of ECPGPlus's Pro\*C compatibility, you do not need to include the `BEGIN DECLARE SECTION` and `END DECLARE SECTION` directives. - -**PostgreSQL Compatibility** - -While most ECPGPlus statements will work with community PostgreSQL, the `CALL` statement, and the `EXECUTE…END EXEC` statement work only when the client application is connected to EDB Postgres Advanced Server. - -
- -introduction overview using_embedded_sql using_descriptors building_executing_dynamic_sql_statements error_handling reference conclusion - -
diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/01_dbms_alert.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/01_dbms_alert.mdx deleted file mode 100644 index 44bca71f7dc..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/01_dbms_alert.mdx +++ /dev/null @@ -1,395 +0,0 @@ ---- -title: "DBMS_ALERT" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/dbms_alert.html" ---- - -The `DBMS_ALERT` package provides the capability to register for, send, and receive alerts. The following table lists the supported procedures: - -| Function/Procedure | Return Type | Description | -| ----------------------------------------------------- | ----------- | --------------------------------------------------- | -| `REGISTER(name)` | n/a | Register to be able to receive alerts named, `name` | -| `REMOVE(name)` | n/a | Remove registration for the alert named, `name` | -| `REMOVEALL` | n/a | Remove registration for all alerts. | -| `SIGNAL(name, message)` | n/a | Signals 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. | - -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. - -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/12AS/data`) with your choice of editor, and edit the `dbms_alert.max_alerts` parameter as shown: - -```text -dbms_alert.max_alerts = alert_count -``` - -`alert_count` - -`alert_count` specifies the maximum number of concurrent alerts. By default, the value of `dbms_alert.max_alerts` is `100`. To disable this feature, set `dbms_alert.max_alerts` to `0`. - -For the `dbms_alert.max_alerts` GUC to function correctly, the `custom_variable_classes` parameter must contain `dbms_alerts`: - -```text -custom_variable_classes = 'dbms_alert, …' -``` - -After editing the `postgresql.conf` file parameters, you must restart the server for the changes to take effect. - -## REGISTER - -The `REGISTER` procedure enables the current session to be notified of the specified alert. - -```text -REGISTER( VARCHAR2) -``` - -**Parameters** - -`name` - - Name of the alert to be registered. - -**Examples** - -The following anonymous block registers for an alert named, `alert_test`, then waits for the signal. - -```text -DECLARE - v_name VARCHAR2(30) := 'alert_test'; - v_msg VARCHAR2(80); - v_status INTEGER; - v_timeout NUMBER(3) := 120; -BEGIN - DBMS_ALERT.REGISTER(v_name); - DBMS_OUTPUT.PUT_LINE('Registered for alert ' || v_name); - DBMS_OUTPUT.PUT_LINE('Waiting for signal...'); - DBMS_ALERT.WAITONE(v_name,v_msg,v_status,v_timeout); - DBMS_OUTPUT.PUT_LINE('Alert name : ' || v_name); - DBMS_OUTPUT.PUT_LINE('Alert msg : ' || v_msg); - DBMS_OUTPUT.PUT_LINE('Alert status : ' || v_status); - DBMS_OUTPUT.PUT_LINE('Alert timeout: ' || v_timeout || ' seconds'); - DBMS_ALERT.REMOVE(v_name); -END; - -Registered for alert alert_test -Waiting for signal... -``` - -## REMOVE - -The `REMOVE` procedure unregisters the session for the named alert. - -```text -REMOVE( VARCHAR2) -``` - -**Parameters** - -`name` - - Name of the alert to be unregistered. - -## REMOVEALL - -The `REMOVEALL` procedure unregisters the session for all alerts. - -```text -REMOVEALL -``` - -## SIGNAL - -The `SIGNAL` procedure signals the occurrence of the named alert. - -```text -SIGNAL( VARCHAR2, VARCHAR2) -``` - -**Parameters** - -`name` - - Name of the alert. - -`message` - - Information to pass with this alert. - -**Examples** - -The following anonymous block signals an alert for `alert_test`. - -```text -DECLARE - v_name VARCHAR2(30) := 'alert_test'; -BEGIN - DBMS_ALERT.SIGNAL(v_name,'This is the message from ' || v_name); - DBMS_OUTPUT.PUT_LINE('Issued alert for ' || v_name); -END; -Issued alert for alert_test -``` - -## WAITANY - -The `WAITANY` procedure waits for any of the registered alerts to occur. - -```text -WAITANY( OUT VARCHAR2, OUT VARCHAR2, - OUT INTEGER, NUMBER) -``` - -**Parameters** - -`name` - - Variable receiving the name of the alert. - -`message` - - Variable receiving the message sent by the `SIGNAL` procedure. - -`status` - - Status code returned by the operation. Possible values are: 0 – alert occurred; 1 – timeout occurred. - -`timeout` - - Time to wait for an alert in seconds. - -**Examples** - -The following anonymous block uses the `WAITANY` procedure to receive an alert named, `alert_test` or `any_alert`: - -```text -DECLARE - v_name VARCHAR2(30); - v_msg VARCHAR2(80); - v_status INTEGER; - v_timeout NUMBER(3) := 120; -BEGIN - DBMS_ALERT.REGISTER('alert_test'); - DBMS_ALERT.REGISTER('any_alert'); - DBMS_OUTPUT.PUT_LINE('Registered for alert alert_test and any_alert'); - DBMS_OUTPUT.PUT_LINE('Waiting for signal...'); - DBMS_ALERT.WAITANY(v_name,v_msg,v_status,v_timeout); - DBMS_OUTPUT.PUT_LINE('Alert name : ' || v_name); - DBMS_OUTPUT.PUT_LINE('Alert msg : ' || v_msg); - DBMS_OUTPUT.PUT_LINE('Alert status : ' || v_status); - DBMS_OUTPUT.PUT_LINE('Alert timeout: ' || v_timeout || ' seconds'); - DBMS_ALERT.REMOVEALL; -END; - -Registered for alert alert_test and any_alert -Waiting for signal... -``` - -An anonymous block in a second session issues a signal for `any_alert`: - -```text -DECLARE - v_name VARCHAR2(30) := 'any_alert'; -BEGIN - DBMS_ALERT.SIGNAL(v_name,'This is the message from ' || v_name); - DBMS_OUTPUT.PUT_LINE('Issued alert for ' || v_name); -END; - -Issued alert for any_alert -``` - -Control returns to the first anonymous block and the remainder of the code is executed: - -```text -Registered for alert alert_test and any_alert -Waiting for signal... -Alert name : any_alert -Alert msg : This is the message from any_alert -Alert status : 0 -Alert timeout: 120 seconds -``` - -## WAITONE - -The `WAITONE` procedure waits for the specified registered alert to occur. - -```text -WAITONE( VARCHAR2, OUT VARCHAR2, - OUT INTEGER, NUMBER) -``` - -**Parameters** - -`name` - - Name of the alert. - -`message` - - Variable receiving the message sent by the `SIGNAL` procedure. - -`status` - - Status code returned by the operation. Possible values are: 0 – alert occurred; 1 – timeout occurred. - -`timeout` - - Time to wait for an alert in seconds. - -**Examples** - -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`. - -```text -DECLARE - v_name VARCHAR2(30) := 'alert_test'; - v_msg VARCHAR2(80); - v_status INTEGER; - v_timeout NUMBER(3) := 120; -BEGIN - DBMS_ALERT.REGISTER(v_name); - DBMS_OUTPUT.PUT_LINE('Registered for alert ' || v_name); - DBMS_OUTPUT.PUT_LINE('Waiting for signal...'); - DBMS_ALERT.WAITONE(v_name,v_msg,v_status,v_timeout); - DBMS_OUTPUT.PUT_LINE('Alert name : ' || v_name); - DBMS_OUTPUT.PUT_LINE('Alert msg : ' || v_msg); - DBMS_OUTPUT.PUT_LINE('Alert status : ' || v_status); - DBMS_OUTPUT.PUT_LINE('Alert timeout: ' || v_timeout || ' seconds'); - DBMS_ALERT.REMOVE(v_name); -END; - -Registered for alert alert_test -Waiting for signal... -``` - -Signal sent for `alert_test` sent by an anonymous block in a second session: - -```text -DECLARE - v_name VARCHAR2(30) := 'alert_test'; -BEGIN - DBMS_ALERT.SIGNAL(v_name,'This is the message from ' || v_name); - DBMS_OUTPUT.PUT_LINE('Issued alert for ' || v_name); -END; - -Issued alert for alert_test -``` - -First session is alerted, control returns to the anonymous block, and the remainder of the code is executed: - -```text -Registered for alert alert_test -Waiting for signal... -Alert name : alert_test -Alert msg : This is the message from alert_test -Alert status : 0 -Alert timeout: 120 seconds -``` - -## Comprehensive Example - -The following example uses two triggers to send alerts when the `dept` table or the `emp` table is changed. An anonymous block listens for these alerts and displays messages when an alert is received. - -The following are the triggers on the `dept` and `emp` tables: - -```text -CREATE OR REPLACE TRIGGER dept_alert_trig - AFTER INSERT OR UPDATE OR DELETE ON dept -DECLARE - v_action VARCHAR2(25); -BEGIN - IF INSERTING THEN - v_action := ' added department(s) '; - ELSIF UPDATING THEN - v_action := ' updated department(s) '; - ELSIF DELETING THEN - v_action := ' deleted department(s) '; - END IF; - DBMS_ALERT.SIGNAL('dept_alert',USER || v_action || 'on ' || - SYSDATE); -END; - -CREATE OR REPLACE TRIGGER emp_alert_trig - AFTER INSERT OR UPDATE OR DELETE ON emp -DECLARE - v_action VARCHAR2(25); -BEGIN - IF INSERTING THEN - v_action := ' added employee(s) '; - ELSIF UPDATING THEN - v_action := ' updated employee(s) '; - ELSIF DELETING THEN - v_action := ' deleted employee(s) '; - END IF; - DBMS_ALERT.SIGNAL('emp_alert',USER || v_action || 'on ' || - SYSDATE); -END; -``` - -The following anonymous block is executed in a session while updates to the `dept` and `emp` tables occur in other sessions: - -```text -DECLARE - v_dept_alert VARCHAR2(30) := 'dept_alert'; - v_emp_alert VARCHAR2(30) := 'emp_alert'; - v_name VARCHAR2(30); - v_msg VARCHAR2(80); - v_status INTEGER; - v_timeout NUMBER(3) := 60; -BEGIN - DBMS_ALERT.REGISTER(v_dept_alert); - DBMS_ALERT.REGISTER(v_emp_alert); - DBMS_OUTPUT.PUT_LINE('Registered for alerts dept_alert and emp_alert'); - DBMS_OUTPUT.PUT_LINE('Waiting for signal...'); - LOOP - DBMS_ALERT.WAITANY(v_name,v_msg,v_status,v_timeout); - EXIT WHEN v_status != 0; - DBMS_OUTPUT.PUT_LINE('Alert name : ' || v_name); - DBMS_OUTPUT.PUT_LINE('Alert msg : ' || v_msg); - DBMS_OUTPUT.PUT_LINE('Alert status : ' || v_status); - DBMS_OUTPUT.PUT_LINE('------------------------------------' || - '-------------------------'); - END LOOP; - DBMS_OUTPUT.PUT_LINE('Alert status : ' || v_status); - DBMS_ALERT.REMOVEALL; -END; - -Registered for alerts dept_alert and emp_alert -Waiting for signal... -``` - -The following changes are made by user, mary: - -```text -INSERT INTO dept VALUES (50,'FINANCE','CHICAGO'); -INSERT INTO emp (empno,ename,deptno) VALUES (9001,'JONES',50); -INSERT INTO emp (empno,ename,deptno) VALUES (9002,'ALICE',50); -``` - -The following change is made by user, john: - -```text -INSERT INTO dept VALUES (60,'HR','LOS ANGELES'); -``` - -The following is the output displayed by the anonymous block receiving the signals from the triggers: - -```text -Registered for alerts dept_alert and emp_alert -Waiting for signal... -Alert name : dept_alert -Alert msg : mary added department(s) on 25-OCT-07 16:41:01 -Alert status : 0 -------------------------------------------------------------- -Alert name : emp_alert -Alert msg : mary added employee(s) on 25-OCT-07 16:41:02 -Alert status : 0 -------------------------------------------------------------- -Alert name : dept_alert -Alert msg : john added department(s) on 25-OCT-07 16:41:22 -Alert status : 0 -------------------------------------------------------------- -Alert status : 1 -``` diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/01_enqueue.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/01_enqueue.mdx deleted file mode 100644 index 7487f87c635..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/01_enqueue.mdx +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: "ENQUEUE" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/enqueue.html" ---- - -The `ENQUEUE` procedure adds an entry to a queue. The signature is: - -```text -ENQUEUE( - IN VARCHAR2, - IN DBMS_AQ.ENQUEUE_OPTIONS_T, - IN DBMS_AQ.MESSAGE_PROPERTIES_T, - IN , - OUT RAW) -``` - -**Parameters** - -`queue_name` - - The name (optionally schema-qualified) of an existing queue. If you omit the schema name, the server will use the schema specified in the `SEARCH_PATH`. Please note that 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`. - -`enqueue_options` - - `enqueue_options` is a value of the type, `enqueue_options_t`: - -```text -DBMS_AQ.ENQUEUE_OPTIONS_T IS RECORD( - visibility BINARY_INTEGER DEFAULT ON_COMMIT, - relative_msgid RAW(16) DEFAULT NULL, - sequence_deviation BINARY INTEGER DEFAULT NULL, - transformation VARCHAR2(61) DEFAULT NULL, - delivery_mode PLS_INTEGER NOT NULL DEFAULT PERSISTENT); -``` - -Currently, the only supported parameter values for `enqueue_options_t` are: - -| `visibility` | `ON_COMMIT`. | -| -------------------- | ------------ | -| `delivery_mode` | `PERSISTENT` | -| `sequence_deviation` | `NULL` | -| `transformation` | `NULL` | -| `relative_msgid` | `NULL` | - -`message_properties` - - `message_properties` is a value of the type, `message_properties_t`: - -```text -message_properties_t IS RECORD( - priority INTEGER, - delay INTEGER, - expiration INTEGER, - correlation CHARACTER VARYING(128) COLLATE pg_catalog.”C”, - attempts INTEGER, - recipient_list “AQ$_RECIPIENT_LIST_T”, - exception_queue CHARACTER VARYING(61) COLLATE pg_catalog.”C”, - enqueue_time TIMESTAMP WITHOUT TIME ZONE, - state INTEGER, - original_msgid BYTEA, - transaction_group CHARACTER VARYING(30) COLLATE pg_catalog.”C”, - delivery_mode INTEGER -DBMS_AQ.PERSISTENT); -``` - -The supported values for `message_properties_t` are: - -| | | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `priority` | If the queue table definition includes a `sort_list` that references `priority`, this parameter affects the order that messages are dequeued. A lower value indicates a higher dequeue priority. | -| `delay` | Specify the number of seconds that will 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 will be associated 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 a message will be moved if it expires or is dequeued by a transaction that rolls back too many times. | -| `enqueue_time` | `enqueue_time` is the time the record was added to the queue; this value is provided by the system. | -| `state` | This parameter is maintained by DBMS_AQ; state can be:

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

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

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

`DBMS_AQ.EXPIRED` – the queue entry has been moved to the exception queue. | -| `original_msgid` | This parameter is accepted for compatibility and ignored. | -| `transaction_group` | This parameter is accepted for compatibility and ignored. | -| `delivery_mode` | This parameter is not supported; specify a value of `DBMS_AQ.PERSISTENT`. | - -`payload` - - Use the `payload` parameter to provide the data that will be associated with the queue entry. The payload type must match the type specified when creating the corresponding queue table (see `DBMS_AQADM.CREATE_QUEUE_TABLE`). - -`msgid` - - Use the `msgid` parameter to retrieve a unique (system-generated) message identifier. - -**Example** - -The following anonymous block calls `DBMS_AQ.ENQUEUE`, adding a message to a queue named `work_order`: - -```text -DECLARE - - enqueue_options DBMS_AQ.ENQUEUE_OPTIONS_T; - message_properties DBMS_AQ.MESSAGE_PROPERTIES_T; - message_handle raw(16); - payload work_order; - -BEGIN - - payload := work_order('Smith', 'system upgrade'); - -DBMS_AQ.ENQUEUE( - queue_name => 'work_order', - enqueue_options => enqueue_options, - message_properties => message_properties, - payload => payload, - msgid => message_handle - ); - END; -``` diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/02_dequeue.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/02_dequeue.mdx deleted file mode 100644 index 4a45c6c09e5..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/02_dequeue.mdx +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: "DEQUEUE" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/dequeue.html" ---- - -The `DEQUEUE` procedure dequeues a message. The signature is: - -```text -DEQUEUE( - IN VARCHAR2, - IN DBMS_AQ.DEQUEUE_OPTIONS_T, - OUT DBMS_AQ.MESSAGE_PROPERTIES_T, - OUT , - OUT RAW) -``` - -**Parameters** - -`queue_name` - - The name (optionally schema-qualified) of an existing queue. If you omit the schema name, the server will use the schema specified in the `SEARCH_PATH`. Please note that 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`. - -`dequeue_options` is a value of the type, `dequeue_options_t`: - -```text -DEQUEUE_OPTIONS_T IS RECORD( - consumer_name CHARACTER VARYING(30), - dequeue_mode INTEGER, - navigation INTEGER, - visibility INTEGER, - wait INTEGER, - msgid BYTEA, - correlation CHARACTER VARYING(128), - deq_condition CHARACTER VARYING(4000), - transformation CHARACTER VARYING(61), - delivery_mode INTEGER); -``` - -Currently, the supported parameter values for `dequeue_options_t` are: - -| | | -| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `consumer_name` | Must be `NULL`. | -| `dequeue_mode` | The locking behavior of the dequeue operation. Must be either:

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

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

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

`DBMS_AQ.REMOVE_NODATA` – Read the message, but do not delete the message. | -| `navigation` | Identifies the message that will be retrieved. 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 will remain in the queue. | -| `wait` | Must be a number larger than 0, or:

`DBMS_AQ.FOREVER` – Wait indefinitely.

`DBMS_AQ.NO_WAIT` – Do not wait. | -| `msgid` | The message ID of the message that will be dequeued. | -| `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. | - -`message_properties` is a value of the type, `message_properties_t`: - -```text -message_properties_t IS RECORD( - priority INTEGER, - delay INTEGER, - expiration INTEGER, - correlation CHARACTER VARYING(128) COLLATE pg_catalog.”C”, - attempts INTEGER, - recipient_list “AQ$_RECIPIENT_LIST_T”, - exception_queue CHARACTER VARYING(61) COLLATE pg_catalog.”C”, - enqueue_time TIMESTAMP WITHOUT TIME ZONE, - state INTEGER, - original_msgid BYTEA, - transaction_group CHARACTER VARYING(30) COLLATE pg_catalog.”C”, - delivery_mode INTEGER -DBMS_AQ.PERSISTENT); -``` - -The supported values for `message_properties_t` are: - -| | | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `priority` | If the queue table definition includes a `sort_list` that references `priority`, this parameter affects the order that messages are dequeued. A lower value indicates a higher dequeue priority. | -| `delay` | Specify the number of seconds that will 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 will be associated 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 a message will be moved if it expires or is dequeued by a transaction that rolls back too many times. | -| `enqueue_time` | `enqueue_time` is the time the record was added to the queue; this value is provided by the system. | -| `state` | This parameter is maintained by DBMS_AQ; state can be:

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

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

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

`DBMS_AQ.EXPIRED` – the queue entry has been moved to the exception queue. | -| `original_msgid` | This parameter is accepted for compatibility and ignored. | -| `transaction_group` | This parameter is accepted for compatibility and ignored. | -| `delivery_mode` | This parameter is not supported; specify a value of `DBMS_AQ.PERSISTENT`. | - -`payload` - - Use the `payload` parameter to retrieve the payload of a message with a dequeue operation. The payload type must match the type specified when creating the queue table. - -`msgid` - - Use the `msgid` parameter to retrieve a unique message identifier. - -**Example** - -The following anonymous block calls `DBMS_AQ.DEQUEUE`, retrieving a message from the queue and a payload: - -```text -DECLARE - - dequeue_options DBMS_AQ.DEQUEUE_OPTIONS_T; - message_properties DBMS_AQ.MESSAGE_PROPERTIES_T; - message_handle raw(16); - payload work_order; - -BEGIN - dequeue_options.dequeue_mode := DBMS_AQ.BROWSE; - - DBMS_AQ.DEQUEUE( - queue_name => 'work_queue', - dequeue_options => dequeue_options, - message_properties => message_properties, - payload => payload, - msgid => message_handle - ); - - DBMS_OUTPUT.PUT_LINE( - 'The next work order is [' || payload.subject || '].' - ); -END; -``` - -The payload is displayed by `DBMS_OUTPUT.PUT_LINE`. diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/03_register.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/03_register.mdx deleted file mode 100644 index ac2bcd2df1d..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/03_register.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: "REGISTER" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/register.html" ---- - -Use the `REGISTER` procedure to register an email address, procedure or URL that will be notified when an item is enqueued or dequeued. The signature is: - -```text -REGISTER( - IN SYS.AQ$_REG_INFO_LIST, - IN NUMBER) -``` - -**Parameters** - -`reg_list` is a list of type `AQ$_REG_INFO_LIST`; that provides information about each subscription that you would like to register. Each entry within the list is of the type `AQ$_REG_INFO`, and may contain: - -
- -
- -| Attribute | Type | Description | -| ----------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | VARCHAR2 (128) | The (optionally schema-qualified) name of the subscription. | -| `namespace` | NUMERIC | The only supported value is `DBMS_AQ.NAMESPACE_AQ (0)` | -| `callback` | VARCHAR2 (4000) | Describes the action that will be performed upon 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 that will be notified. | -| `context` | RAW (16) | Any user-defined value required by the procedure. | - -`count` - - `count` is the number of entries in `reg_list`. - -**Example** - -The following anonymous block calls `DBMS_AQ.REGISTER`, registering procedures that will be notified when an item is added to or removed from a queue. A set of attributes (of `sys.aq$_reg_info` type) is provided for each subscription identified in the `DECLARE` section: - -```text -DECLARE - subscription1 sys.aq$_reg_info; - subscription2 sys.aq$_reg_info; - subscription3 sys.aq$_reg_info; - subscriptionlist sys.aq$_reg_info_list; -BEGIN - subscription1 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, -'plsql://assign_worker?PR=0',HEXTORAW('FFFF')); - subscription2 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, -'plsql://add_to_history?PR=1',HEXTORAW('FFFF')); - subscription3 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, -'plsql://reserve_parts?PR=2',HEXTORAW('FFFF')); - - subscriptionlist := sys.aq$_reg_info_list(subscription1, -subscription2, subscription3); - dbms_aq.register(subscriptionlist, 3); - commit; - END; - / -``` - -The `subscriptionlist` is of type `sys.aq$_reg_info_list`, and contains the previously described `sys.aq$_reg_info` objects. The list name and an object count are passed to `dbms_aq.register`. diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/04_unregister.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/04_unregister.mdx deleted file mode 100644 index 762b412c003..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/04_unregister.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: "UNREGISTER" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/unregister.html" ---- - -Use the `UNREGISTER` procedure to turn off notifications related to enqueueing and dequeueing. The signature is: - -```text -UNREGISTER( - IN SYS.AQ$_REG_INFO_LIST, - IN NUMBER) -``` - -**Parameter** - -`reg_list` - -`reg_list` is a list of type `AQ$_REG_INFO_LIST`; that provides information about each subscription that you would like to register. Each entry within the list is of the type `AQ$_REG_INFO`, and may contain: - -
- -
- -| Attribute | Type | Description | -| ----------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | VARCHAR2 (128) | The (optionally schema-qualified) name of the subscription. | -| `namespace` | NUMERIC | The only supported value is `DBMS_AQ.NAMESPACE_AQ (0)` | -| `callback` | VARCHAR2 (4000) | Describes the action that will be performed upon 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 that will be notified. | -| `context` | RAW (16) | Any user-defined value required by the procedure. | - -`count` - - `count` is the number of entries in `reg_list`. - -**Example** - -The following anonymous block calls `DBMS_AQ.UNREGISTER`, disabling the notifications specified in the example for `DBMS_AQ.REGISTER`: - -```text -DECLARE - subscription1 sys.aq$_reg_info; - subscription2 sys.aq$_reg_info; - subscription3 sys.aq$_reg_info; - subscriptionlist sys.aq$_reg_info_list; -BEGIN - subscription1 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, -'plsql://assign_worker?PR=0',HEXTORAW('FFFF')); - subscription2 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, -'plsql://add_to_history?PR=1',HEXTORAW('FFFF')); - subscription3 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, -'plsql://reserve_parts?PR=2',HEXTORAW('FFFF')); - - subscriptionlist := sys.aq$_reg_info_list(subscription1, -subscription2, subscription3); - dbms_aq.unregister(subscriptionlist, 3); - commit; - END; - / -``` - -The `subscriptionlist` is of type `sys.aq$_reg_info_list`, and contains the previously described `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/12/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/01_decrypt.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/01_decrypt.mdx deleted file mode 100644 index 2a822fc109b..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/01_decrypt.mdx +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: "DECRYPT" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/decrypt.html" ---- - -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 - ( IN RAW, IN INTEGER, IN RAW, IN RAW - DEFAULT NULL) RETURN RAW -``` - -The signature of the `DECRYPT` procedure is: - -```text -DECRYPT - ( INOUT BLOB, IN BLOB, IN INTEGER, IN RAW, - IN RAW DEFAULT NULL) -``` - -or - -```text -DECRYPT - ( INOUT CLOB, IN CLOB, IN INTEGER, IN RAW, - IN RAW DEFAULT NULL) -``` - -When invoked as a procedure, `DECRYPT` returns `BLOB` or `CLOB` data to a user-specified `BLOB`. - -**Parameters** - -`dst` - - `dst` specifies the name of a `BLOB` to which the output of the `DECRYPT` procedure will be written. The `DECRYPT` procedure will overwrite any existing data currently in `dst`. - -`src` - - `src` specifies the source data that will be decrypted. If you are 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. Advanced Server supports the following block cipher algorithms, modifiers and cipher suites: - -| **Block Cipher Algorithms** | | -| ---------------------------------- | ----------------------------------------------------------- | -| `ENCRYPT_DES` | `CONSTANT INTEGER := 1;` | -| `ENCRYPT_3DES` | `CONSTANT INTEGER := 3;` | -| `ENCRYPT_AES` | `CONSTANT INTEGER := 4;` | -| `ENCRYPT_AES128` | `CONSTANT INTEGER := 6;` | -| **Block Cipher Modifiers** | | -| `CHAIN_CBC` | `CONSTANT INTEGER := 256;` | -| `CHAIN_ECB` | `CONSTANT INTEGER := 768;` | -| **Block Cipher Padding Modifiers** | | -| `PAD_PKCS5` | `CONSTANT INTEGER := 4096;` | -| `PAD_NONE` | `CONSTANT INTEGER := 8192;` | -| **Block Cipher Suites** | | -| `DES_CBC_PKCS5` | `CONSTANT INTEGER := ENCRYPT_DES + CHAIN_CBC + PAD_PKCS5;` | -| `DES3_CBC_PKCS5` | `CONSTANT INTEGER := ENCRYPT_3DES + CHAIN_CBC + PAD_PKCS5;` | -| `AES_CBC_PKCS5` | `CONSTANT INTEGER := ENCRYPT_AES + CHAIN_CBC + PAD_PKCS5;` | - -`key` - - `key` specifies the user-defined decryption key. This should match the key specified when the `src` was encrypted. - -`iv` - - `iv` (optional) specifies an initialization vector. If an initialization vector was specified when the `src` was encrypted, you must specify an initialization vector when decrypting the `src`. The default is `NULL`. - -**Examples** - -The following example uses the `DBMS_CRYPTO.DECRYPT` function to decrypt an encrypted password retrieved from the `passwords` table: - -```text -CREATE TABLE passwords -( - principal VARCHAR2(90) PRIMARY KEY, -- username - ciphertext RAW(9) -- encrypted password -); - -CREATE FUNCTION get_password(username VARCHAR2) RETURN RAW AS - typ INTEGER := DBMS_CRYPTO.DES_CBC_PKCS5; - key RAW(128) := 'my secret key'; - iv RAW(100) := 'my initialization vector'; - password RAW(2048); -BEGIN - - SELECT ciphertext INTO password FROM passwords WHERE principal = username; - - RETURN dbms_crypto.decrypt(password, typ, key, iv); -END; -``` - -Note that 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/12/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/02_encrypt.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/02_encrypt.mdx deleted file mode 100644 index 6152bf1f3f3..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/04_dbms_crypto/02_encrypt.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "ENCRYPT" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/encrypt.html" ---- - -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 - ( IN RAW, IN INTEGER, IN RAW, - IN RAW DEFAULT NULL) RETURN RAW -``` - -The signature of the `ENCRYPT` procedure is: - -```text -ENCRYPT - ( INOUT BLOB, IN BLOB, IN INTEGER, IN RAW, - IN RAW DEFAULT NULL) -``` - -or - -```text -ENCRYPT - ( INOUT BLOB, IN CLOB, IN INTEGER, IN RAW, - IN RAW DEFAULT NULL) -``` - -When invoked as a procedure, `ENCRYPT` returns `BLOB` or `CLOB` data to a user-specified `BLOB`. - -**Parameters** - -`dst` - - `dst` specifies the name of a `BLOB` to which the output of the `ENCRYPT` procedure will be written. The `ENCRYPT` procedure will overwrite any existing data currently in `dst`. - -`src` - - `src` specifies the source data that will be encrypted. If you are 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 that will be used by `ENCRYPT`, and any modifiers. Advanced Server supports the block cipher algorithms, modifiers and cipher suites listed below: - -| **Block Cipher Algorithms** | | -| ---------------------------------- | ----------------------------------------------------------- | -| `ENCRYPT_DES` | `CONSTANT INTEGER := 1;` | -| `ENCRYPT_3DES` | `CONSTANT INTEGER := 3;` | -| `ENCRYPT_AES` | `CONSTANT INTEGER := 4;` | -| `ENCRYPT_AES128` | `CONSTANT INTEGER := 6;` | -| **Block Cipher Modifiers** | | -| `CHAIN_CBC` | `CONSTANT INTEGER := 256;` | -| `CHAIN_ECB` | `CONSTANT INTEGER := 768;` | -| **Block Cipher Padding Modifiers** | | -| `PAD_PKCS5` | `CONSTANT INTEGER := 4096;` | -| `PAD_NONE` | `CONSTANT INTEGER := 8192;` | -| **Block Cipher Suites** | | -| `DES_CBC_PKCS5` | `CONSTANT INTEGER := ENCRYPT_DES + CHAIN_CBC + PAD_PKCS5;` | -| `DES3_CBC_PKCS5` | `CONSTANT INTEGER := ENCRYPT_3DES + CHAIN_CBC + PAD_PKCS5;` | -| `AES_CBC_PKCS5` | `CONSTANT INTEGER := ENCRYPT_AES + CHAIN_CBC + PAD_PKCS5;` | - -`key` - - `key` specifies the encryption key. - -`iv` - - `iv` (optional) specifies an initialization vector. By default, `iv` is `NULL`. - -**Examples** - -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: - -```text -CREATE TABLE passwords -( - principal VARCHAR2(90) PRIMARY KEY, -- username - ciphertext RAW(9) -- encrypted password -); -CREATE PROCEDURE set_password(username VARCHAR2, cleartext RAW) AS - typ INTEGER := DBMS_CRYPTO.DES_CBC_PKCS5; - key RAW(128) := 'my secret key'; - iv RAW(100) := 'my initialization vector'; - encrypted RAW(2048); -BEGIN - encrypted := dbms_crypto.encrypt(cleartext, typ, key, iv); - UPDATE passwords SET ciphertext = encrypted WHERE principal = username; -END; -``` - -`ENCRYPT` uses a key value of `my secret key` and an initialization vector of `my initialization vector` when encrypting the `password`; specify the same key and initialization vector when decrypting the `password`. diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/09_dbms_output.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/09_dbms_output.mdx deleted file mode 100644 index 6aae5df5c95..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/09_dbms_output.mdx +++ /dev/null @@ -1,426 +0,0 @@ ---- -title: "DBMS_OUTPUT" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/dbms_output.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 procedures and functions available in the `DBMS_OUTPUT` package are listed in the following table. - -| Function/Procedure | Return Type | Description | -| --------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------- | -| `DISABLE` | n/a | Disable the capability to send and receive messages. | -| `ENABLE(buffer_size)` | n/a | Enable the capability to send and receive messages. | -| `GET_LINE(line OUT, status OUT)` | n/a | Get a line from the message buffer. | -| `GET_LINES(lines OUT, numlines IN OUT)` | n/a | Get multiple lines from the message buffer. | -| `NEW_LINE` | n/a | Puts an end-of-line character sequence. | -| `PUT(item)` | n/a | Puts a partial line without an end-of-line character sequence. | -| `PUT_LINE(item)` | n/a | Puts a complete line with an end-of-line character sequence. | -| `SERVEROUTPUT(stdout)` | n/a | Direct messages from `PUT, PUT_LINE,` or `NEW_LINE` to either standard output or the message buffer. | - -The following table lists the public variables available in the `DBMS_OUTPUT` package. - -| **Public Variables** | **Data Type** | **Value** | **Description** | -| -------------------- | ------------- | --------- | ------------------ | -| `chararr` | `TABLE` | | For message lines. | - -## CHARARR - -The `CHARARR` is for storing multiple message lines. - -```text -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 will 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. - -Use the `ENABLE` procedure or `SERVEROUTPUT(TRUE)` procedure to re-enable the sending and receiving of messages. - -```text -DISABLE -``` - -**Examples** - -This anonymous block disables the sending and receiving messages in the current session. - -```text -BEGIN - DBMS_OUTPUT.DISABLE; -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 destination of a message sent with `PUT, PUT_LINE,` or `NEW_LINE` depends upon 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. - -```text -ENABLE [ ( INTEGER) ] -``` - -**Parameter** - -`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. - -**Examples** - -The following anonymous block enables messages. Setting `SERVEROUTPUT(TRUE)` forces them to standard output. - -```text -BEGIN - DBMS_OUTPUT.ENABLE; - DBMS_OUTPUT.SERVEROUTPUT(TRUE); - DBMS_OUTPUT.PUT_LINE('Messages enabled'); -END; - -Messages enabled -``` - -The same effect could have been achieved by simply using `SERVEROUTPUT(TRUE)`. - -```text -BEGIN - DBMS_OUTPUT.SERVEROUTPUT(TRUE); - DBMS_OUTPUT.PUT_LINE('Messages enabled'); -END; - -Messages enabled -``` - -The following anonymous block enables messages, but setting `SERVEROUTPUT(FALSE)` directs messages to the message buffer. - -```text -BEGIN - DBMS_OUTPUT.ENABLE; - DBMS_OUTPUT.SERVEROUTPUT(FALSE); - DBMS_OUTPUT.PUT_LINE('Message sent to buffer'); -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. - -```text -GET_LINE( OUT VARCHAR2, OUT INTEGER) -``` - -**Parameters** - -`line` - - Variable receiving the line of text from the message buffer. - -`status` - - 0 if a line was returned from the message buffer, 1 if there was no line to return. - -**Examples** - -The following 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); - -DECLARE - v_emprec VARCHAR2(120); - CURSOR emp_cur IS SELECT * FROM emp ORDER BY empno; -BEGIN - DBMS_OUTPUT.ENABLE; - FOR i IN emp_cur LOOP - v_emprec := i.empno || ',' || i.ename || ',' || i.job || ',' || - NVL(LTRIM(TO_CHAR(i.mgr,'9999')),'') || ',' || i.hiredate || - ',' || i.sal || ',' || - NVL(LTRIM(TO_CHAR(i.comm,'9990.99')),'') || ',' || i.deptno; - DBMS_OUTPUT.PUT_LINE(v_emprec); - END LOOP; -END; -``` - -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. - -```text -CREATE TABLE messages ( - status INTEGER, - msg VARCHAR2(100) -); - -DECLARE - v_line VARCHAR2(100); - v_status INTEGER := 0; -BEGIN - DBMS_OUTPUT.GET_LINE(v_line,v_status); - WHILE v_status = 0 LOOP - INSERT INTO messages VALUES(v_status, v_line); - DBMS_OUTPUT.GET_LINE(v_line,v_status); - END LOOP; -END; - -SELECT msg FROM messages; - - msg ------------------------------------------------------------------ - 7369,SMITH,CLERK,7902,17-DEC-80 00:00:00,800.00,,20 - 7499,ALLEN,SALESMAN,7698,20-FEB-81 00:00:00,1600.00,300.00,30 - 7521,WARD,SALESMAN,7698,22-FEB-81 00:00:00,1250.00,500.00,30 - 7566,JONES,MANAGER,7839,02-APR-81 00:00:00,2975.00,,20 - 7654,MARTIN,SALESMAN,7698,28-SEP-81 00:00:00,1250.00,1400.00,30 - 7698,BLAKE,MANAGER,7839,01-MAY-81 00:00:00,2850.00,,30 - 7782,CLARK,MANAGER,7839,09-JUN-81 00:00:00,2450.00,,10 - 7788,SCOTT,ANALYST,7566,19-APR-87 00:00:00,3000.00,,20 - 7839,KING,PRESIDENT,,17-NOV-81 00:00:00,5000.00,,10 - 7844,TURNER,SALESMAN,7698,08-SEP-81 00:00:00,1500.00,0.00,30 - 7876,ADAMS,CLERK,7788,23-MAY-87 00:00:00,1100.00,,20 - 7900,JAMES,CLERK,7698,03-DEC-81 00:00:00,950.00,,30 - 7902,FORD,ANALYST,7566,03-DEC-81 00:00:00,3000.00,,20 - 7934,MILLER,CLERK,7782,23-JAN-82 00:00:00,1300.00,,10 -(14 rows) -``` - -## GET_LINES - -The `GET_LINES` procedure 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. - -```text -GET_LINES( OUT CHARARR, IN OUT INTEGER) -``` - -**Parameters** - -`lines` - - Table receiving the lines of text from the message buffer. See `CHARARR` for a description of `lines.` - -`numlines IN` - - Number of lines to be retrieved 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. - -**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. - -```text -EXEC DBMS_OUTPUT.SERVEROUTPUT(FALSE); - -DECLARE - v_emprec VARCHAR2(120); - CURSOR emp_cur IS SELECT * FROM emp ORDER BY empno; -BEGIN - DBMS_OUTPUT.ENABLE; - FOR i IN emp_cur LOOP - v_emprec := i.empno || ',' || i.ename || ',' || i.job || ',' || - NVL(LTRIM(TO_CHAR(i.mgr,'9999')),'') || ',' || i.hiredate || - ',' || i.sal || ',' || - NVL(LTRIM(TO_CHAR(i.comm,'9990.99')),'') || ',' || i.deptno; - DBMS_OUTPUT.PUT_LINE(v_emprec); - END LOOP; -END; - -DECLARE - v_lines DBMS_OUTPUT.CHARARR; - v_numlines INTEGER := 14; - v_status INTEGER := 0; -BEGIN - DBMS_OUTPUT.GET_LINES(v_lines,v_numlines); - FOR i IN 1..v_numlines LOOP - INSERT INTO messages VALUES(v_numlines, v_lines(i)); - END LOOP; -END; - -SELECT msg FROM messages; - - msg ------------------------------------------------------------------ - 7369,SMITH,CLERK,7902,17-DEC-80 00:00:00,800.00,,20 - 7499,ALLEN,SALESMAN,7698,20-FEB-81 00:00:00,1600.00,300.00,30 - 7521,WARD,SALESMAN,7698,22-FEB-81 00:00:00,1250.00,500.00,30 - 7566,JONES,MANAGER,7839,02-APR-81 00:00:00,2975.00,,20 - 7654,MARTIN,SALESMAN,7698,28-SEP-81 00:00:00,1250.00,1400.00,30 - 7698,BLAKE,MANAGER,7839,01-MAY-81 00:00:00,2850.00,,30 - 7782,CLARK,MANAGER,7839,09-JUN-81 00:00:00,2450.00,,10 - 7788,SCOTT,ANALYST,7566,19-APR-87 00:00:00,3000.00,,20 - 7839,KING,PRESIDENT,,17-NOV-81 00:00:00,5000.00,,10 - 7844,TURNER,SALESMAN,7698,08-SEP-81 00:00:00,1500.00,0.00,30 - 7876,ADAMS,CLERK,7788,23-MAY-87 00:00:00,1100.00,,20 - 7900,JAMES,CLERK,7698,03-DEC-81 00:00:00,950.00,,30 - 7902,FORD,ANALYST,7566,03-DEC-81 00:00:00,3000.00,,20 - 7934,MILLER,CLERK,7782,23-JAN-82 00:00:00,1300.00,,10 -(14 rows) -``` - -## NEW_LINE - -The `NEW_LINE` procedure writes an end-of-line character sequence in the message buffer. - -```text -NEW_LINE -``` - -**Parameter** - -The `NEW_LINE` procedure expects no parameters. - -## PUT - -The `PUT` procedure writes a string to the message buffer. No end-of-line character sequence is written at the end of the string. Use the `NEW_LINE` procedure to add an end-of-line character sequence. - -```text -PUT( VARCHAR2) -``` - -**Parameter** - -`item` - - Text written to the message buffer. - -**Examples** - -The following example uses the `PUT` procedure to display a comma-delimited list of employees from the `emp` table. - -```text -DECLARE - CURSOR emp_cur IS SELECT * FROM emp ORDER BY empno; -BEGIN - FOR i IN emp_cur LOOP - DBMS_OUTPUT.PUT(i.empno); - DBMS_OUTPUT.PUT(','); - DBMS_OUTPUT.PUT(i.ename); - DBMS_OUTPUT.PUT(','); - DBMS_OUTPUT.PUT(i.job); - DBMS_OUTPUT.PUT(','); - DBMS_OUTPUT.PUT(i.mgr); - DBMS_OUTPUT.PUT(','); - DBMS_OUTPUT.PUT(i.hiredate); - DBMS_OUTPUT.PUT(','); - DBMS_OUTPUT.PUT(i.sal); - DBMS_OUTPUT.PUT(','); - DBMS_OUTPUT.PUT(i.comm); - DBMS_OUTPUT.PUT(','); - DBMS_OUTPUT.PUT(i.deptno); - DBMS_OUTPUT.NEW_LINE; - END LOOP; -END; - -7369,SMITH,CLERK,7902,17-DEC-80 00:00:00,800.00,,20 -7499,ALLEN,SALESMAN,7698,20-FEB-81 00:00:00,1600.00,300.00,30 -7521,WARD,SALESMAN,7698,22-FEB-81 00:00:00,1250.00,500.00,30 -7566,JONES,MANAGER,7839,02-APR-81 00:00:00,2975.00,,20 -7654,MARTIN,SALESMAN,7698,28-SEP-81 00:00:00,1250.00,1400.00,30 -7698,BLAKE,MANAGER,7839,01-MAY-81 00:00:00,2850.00,,30 -7782,CLARK,MANAGER,7839,09-JUN-81 00:00:00,2450.00,,10 -7788,SCOTT,ANALYST,7566,19-APR-87 00:00:00,3000.00,,20 -7839,KING,PRESIDENT,,17-NOV-81 00:00:00,5000.00,,10 -7844,TURNER,SALESMAN,7698,08-SEP-81 00:00:00,1500.00,0.00,30 -7876,ADAMS,CLERK,7788,23-MAY-87 00:00:00,1100.00,,20 -7900,JAMES,CLERK,7698,03-DEC-81 00:00:00,950.00,,30 -7902,FORD,ANALYST,7566,03-DEC-81 00:00:00,3000.00,,20 -7934,MILLER,CLERK,7782,23-JAN-82 00:00:00,1300.00,,10 -``` - -## PUT_LINE - -The `PUT_LINE` procedure writes a single line to the message buffer including an end-of-line character sequence. - -```text -PUT_LINE( VARCHAR2) -``` - -**Parameter** - -`item` - - Text to be written 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. - -```text -DECLARE - v_emprec VARCHAR2(120); - CURSOR emp_cur IS SELECT * FROM emp ORDER BY empno; -BEGIN - FOR i IN emp_cur LOOP - v_emprec := i.empno || ',' || i.ename || ',' || i.job || ',' || - NVL(LTRIM(TO_CHAR(i.mgr,'9999')),'') || ',' || i.hiredate || - ',' || i.sal || ',' || - NVL(LTRIM(TO_CHAR(i.comm,'9990.99')),'') || ',' || i.deptno; - DBMS_OUTPUT.PUT_LINE(v_emprec); - END LOOP; -END; - -7369,SMITH,CLERK,7902,17-DEC-80 00:00:00,800.00,,20 -7499,ALLEN,SALESMAN,7698,20-FEB-81 00:00:00,1600.00,300.00,30 -7521,WARD,SALESMAN,7698,22-FEB-81 00:00:00,1250.00,500.00,30 -7566,JONES,MANAGER,7839,02-APR-81 00:00:00,2975.00,,20 -7654,MARTIN,SALESMAN,7698,28-SEP-81 00:00:00,1250.00,1400.00,30 -7698,BLAKE,MANAGER,7839,01-MAY-81 00:00:00,2850.00,,30 -7782,CLARK,MANAGER,7839,09-JUN-81 00:00:00,2450.00,,10 -7788,SCOTT,ANALYST,7566,19-APR-87 00:00:00,3000.00,,20 -7839,KING,PRESIDENT,,17-NOV-81 00:00:00,5000.00,,10 -7844,TURNER,SALESMAN,7698,08-SEP-81 00:00:00,1500.00,0.00,30 -7876,ADAMS,CLERK,7788,23-MAY-87 00:00:00,1100.00,,20 -7900,JAMES,CLERK,7698,03-DEC-81 00:00:00,950.00,,30 -7902,FORD,ANALYST,7566,03-DEC-81 00:00:00,3000.00,,20 -7934,MILLER,CLERK,7782,23-JAN-82 00:00:00,1300.00,,10 -``` - -## SERVEROUTPUT - -The `SERVEROUTPUT` procedure 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 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 Advanced Server. - -```text -SERVEROUTPUT( BOOLEAN) -``` - -**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. - -**Examples** - -The following anonymous block sends the first message to the command line and the second message to the message buffer. - -```text -BEGIN - DBMS_OUTPUT.SERVEROUTPUT(TRUE); - DBMS_OUTPUT.PUT_LINE('This message goes to the command line'); - DBMS_OUTPUT.SERVEROUTPUT(FALSE); - DBMS_OUTPUT.PUT_LINE('This message goes to the message buffer'); -END; - -This message goes to the command line -``` - -If 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. - -```text -BEGIN - DBMS_OUTPUT.SERVEROUTPUT(TRUE); - DBMS_OUTPUT.PUT_LINE('Flush messages from the buffer'); -END; - -This message goes to the message buffer -Flush messages from the buffer -``` diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/12_dbms_random.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/12_dbms_random.mdx deleted file mode 100644 index 2a237c8fc29..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/12_dbms_random.mdx +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: "DBMS_RANDOM" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/dbms_random.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. - -| Function/Procedure | Return Type | Description | -| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| `INITIALIZE(val)` | n/a | Initializes the `DBMS_RANDOM` package with the specified seed `value`. Deprecated, but supported for backward compatibility. | -| `NORMAL()` | `NUMBER` | Returns a random `NUMBER`. | -| `RANDOM` | `INTEGER` | Returns a random `INTEGER` with a value greater than or equal to -2^31 and less than 2^31. Deprecated, but supported for backward compatibility. | -| `SEED(val)` | n/a | Resets the seed with the specified `value`. | -| `SEED(val)` | n/a | Resets the seed with the specified `value`. | -| `STRING(opt, len)` | `VARCHAR2` | Returns a random string. | -| `TERMINATE` | n/a | `TERMINATE` has no effect. Deprecated, but supported for backward compatibility. | -| `VALUE` | `NUMBER` | Returns a random number with a value greater than or equal to `0` and less than `1`, with 38 digit precision. | -| `VALUE(low, high)` | `NUMBER` | Returns a random number with a value greater than or equal to `low` and less than `high`. | - -## INITIALIZE - -The `INITIALIZE` procedure initializes the `DBMS_RANDOM` package with a seed value. The signature is: - -```text -INITIALIZE( IN INTEGER) -``` - -This procedure should be considered deprecated; it is included for backward compatibility only. - -**Parameters** - -`val` - - `val` is the seed value used by the `DBMS_RANDOM` package algorithm. - -**Example** - -The following code snippet demonstrates a call to the `INITIALIZE` procedure that initializes the `DBMS_RANDOM` package with the seed value, `6475`. - -```text -DBMS_RANDOM.INITIALIZE(6475); -``` - -## NORMAL - -The `NORMAL` function returns a random number of type `NUMBER`. The signature is: - -```text - NUMBER NORMAL() -``` - -**Parameters** - -`result` - - `result` is a random value of type `NUMBER`. - -**Example** - -The following code snippet demonstrates a call to the `NORMAL` function: - -```text -x:= DBMS_RANDOM.NORMAL(); -``` - -## RANDOM - -The `RANDOM` function returns a random `INTEGER` value that is greater than or equal to -2 ^31 and less than 2 ^31. The signature is: - -```text - INTEGER RANDOM() -``` - -This function should be considered deprecated; it is included for backward compatibility only. - -**Parameters** - -`result` - - `result` is a random value of type `INTEGER`. - -**Example** - -The following code snippet demonstrates a call to the `RANDOM` function. The call returns a random number: - -```text -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: - -```text -SEED( IN INTEGER) -``` - -**Parameters** - -`val` - - `val` is the seed value used by the `DBMS_RANDOM` package algorithm. - -**Example** - -The following code snippet demonstrates a call to the `SEED` procedure; the call sets the seed value at `8495`. - -```text -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: - -```text -SEED( IN VARCHAR2) -``` - -**Parameters** - -`val` - - `val` is the seed value used by the `DBMS_RANDOM` package algorithm. - -**Example** - -The following code snippet demonstrates a call to the `SEED` procedure; the call sets the seed value to `abc123`. - -```text -DBMS_RANDOM.SEED('abc123'); -``` - -## STRING - -The `STRING` function returns a random `VARCHAR2` string in a user-specified format. The signature of the `STRING` function is: - -```text - VARCHAR2 STRING( IN CHAR, IN NUMBER) -``` - -**Parameters** - -`opt` - - Formatting option for the returned string. `option` may 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 | -| `p` or `P` | Any printable characters | - -`len` - - The length of the returned string. - -`result` - - `result` is a random value of type `VARCHAR2`. - -**Example** - -The following code snippet demonstrates a call to the `STRING` function; the call returns a random alpha-numeric character string that is 10 characters long. - -```text -x := DBMS_RANDOM.STRING('X', 10); -``` - -## TERMINATE - -The `TERMINATE` procedure has no effect. The signature is: - -```text -TERMINATE -``` - -The `TERMINATE` procedure should be considered deprecated; the procedure is supported for compatibility only. - -## 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: - -```text - NUMBER VALUE() -``` - -**Parameters** - -`result` - - `result` is a random value of type `NUMBER`. - -**Example** - -The following code snippet demonstrates a call to the `VALUE` function. The call returns a random `NUMBER`: - -```text -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: - -```text - NUMBER VALUE( IN NUMBER, IN NUMBER) -``` - -**Parameters** - -`low` - - `low` specifies the lower boundary for the random value. The random value may be equal to `low`. - -`high` - - `high` specifies the upper boundary for the random value; the random value will be less than `high`. - -`result` - - `result` is a random value of type `NUMBER`. - -**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: - -```text -x := DBMS_RANDOM.VALUE(1, 100); -``` diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/13_dbms_redact.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/13_dbms_redact.mdx deleted file mode 100644 index 90c94f8c993..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/13_dbms_redact.mdx +++ /dev/null @@ -1,709 +0,0 @@ ---- -title: "DBMS_REDACT" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/dbms_redact.html" ---- - -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. - -| Function/Procedure | Function or Procedure | Return Type | Description | -| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------- | --------------------------------------------------------------------- | -| `ADD_POLICY(object_schema, object_name, policy_name, policy_description, column_name, column_description, function_type, function_parameters, expression, enable, regexp_pattern, regexp_replace_string, regexp_position, regexp_occurence, regexp_match_parameter, custom_function_expression)` | Procedure | n/a | Adds a data redaction policy. | -| `ALTER_POLICY(object_schema, object_name, policy_name, action, column_name, function_type, function_parameters, expression, regexp_pattern, regexp_replace_string, regexp_position, regexp_occurence, regexp_match_parameter, policy_description, column_description, custom_function_expression)` | Procedure | n/a | Alters the existing data redaction policy. | -| `DISABLE_POLICY(object_schema, object_name, policy_name)` | Procedure | n/a | Disables the existing data redaction policy. | -| `ENABLE_POLICY(object_schema, object_name, policy_name)` | Procedure | n/a | Enables a previously disabled data redaction policy. | -| `DROP_POLICY(object_schema, object_name, policy_name)` | Procedure | n/a | Drops a data redaction policy. | -| `UPDATE_FULL_REDACTION_VALUES(number_val, binfloat_val, bindouble_val, char_val, varchar_val, nchar_val, nvarchar_val, datecol_val, ts_val, tswtz_val, blob_val, clob_val, nclob_val)` | Procedure | n/a | Updates the full redaction default values for the specified datatype. | - -The data redaction feature uses the `DBMS_REDACT` package to define policies or conditions to redact data in a column based on the table column type and redaction type. - -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. - -## 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`. - -| Constant | Type | Value | Description | -| --------- | --------- | ----- | --------------------------------------------------------------------------------------------------------- | -| `NONE` | `INTEGER` | `0` | No redaction, zero effect on the result of a query against table. | -| `FULL` | `INTEGER` | `1` | Full redaction, redacts full values of the column data. | -| `PARTIAL` | `INTEGER` | `2` | Partial redaction, redacts a portion of the column data. | -| `RANDOM` | `INTEGER` | `4` | Random redaction, each query results in a different random value depending on the datatype of the column. | -| `REGEXP` | `INTEGER` | `5` | Regular Expression based redaction, searches for the pattern of data to redact. | -| `CUSTOM` | `INTEGER` | `99` | Custom redaction type. | - -The following table shows the values for the `action` parameter of `dbms_redact.alter_policy`. - -| Constant | Type | Value | Description | -| ------------------------ | --------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------- | -| `ADD_COLUMN` | `INTEGER` | `1` | Adds a column to the redaction policy. | -| `DROP_COLUMN` | `INTEGER` | `2` | Drops a column from the redaction policy. | -| `MODIFY_EXPRESSION` | `INTEGER` | `3` | Modifies the expression of a redaction policy. The redaction is applied when the expression evaluates to the `BOOLEAN` value to `TRUE`. | -| `MODIFY_COLUMN` | `INTEGER` | `4` | Modifies a column in the redaction policy to change the redaction function type or function parameter. | -| `SET_POLICY_DESCRIPTION` | `INTEGER` | `5` | Sets the redaction policy description. | -| `SET_COLUMN_DESCRIPTION` | `INTEGER` | `6` | Sets a description for the redaction performed on the column. | - -The partial data redaction enables you to redact only a portion of the column data. To use partial redaction, you must set the `dbms_redact.add_policy` procedure `function_type` parameter to `dbms_redact.partial` and use the `function_parameters` parameter to specify the partial redaction behavior. - -The data redaction feature provides a predefined format to configure policies that use the following datatype: - -- `Character` -- `Number` -- `Datetime` - -The following table highlights the format descriptor for partial redaction with respect to datatype. The example 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. - -| 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`. | -| | `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_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. - -| Function Parameter | Data Type | Value | Description | -| ----------------------------- | ---------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `REDACT_US_SSN_F5` | `VARCHAR2` | `'VVVFVVFVVVV,VVV-VV-VVVV,X,1,5'` | Redacts the first 5 numbers of SSN. **Example:** The number `123-45-6789` becomes `XXX-XX-6789`. | -| `REDACT_US_SSN_L4` | `VARCHAR2` | `'VVVFVVFVVVV,VVV-VV-VVVV,X,6,9'` | Redacts the last 4 numbers of SSN. **Example:** The number `123-45-6789` becomes `123-45-XXXX`. | -| `REDACT_US_SSN_ENTIRE` | `VARCHAR2` | `'VVVFVVFVVVV,VVV-VV-VVVV,X,1,9'` | Redacts the entire SSN. **Example:** The number `123-45-6789` becomes `XXX-XX-XXXX`. | -| `REDACT_NUM_US_SSN_F5` | `VARCHAR2` | `'9,1,5'` | Redacts the first 5 numbers of SSN when the column is a number datatype. **Example:** The number `123456789` becomes `999996789`. | -| `REDACT_NUM_US_SSN_L4` | `VARCHAR2` | `'9,6,9'` | Redacts the last 4 numbers of SSN when the column is a number datatype. **Example:** The number `123456789` becomes `123459999`. | -| `REDACT_NUM_US_SSN_ENTIRE` | `VARCHAR2` | `'9,1,9'` | Redacts the entire SSN when the column is a number datatype. **Example:** The number `123456789` becomes `999999999`. | -| `REDACT_ZIP_CODE` | `VARCHAR2` | `'VVVVV,VVVVV,X,1,5'` | Redacts a 5 digit zip code. **Example:** `12345`becomes `XXXXX`. | -| `REDACT_NUM_ZIP_CODE` | `VARCHAR2` | `'9,1,5'` | Redacts a 5 digit zip code when the column is a number datatype. **Example:** `12345`becomes `99999`. | -| `REDACT_CCN16_F12` | `VARCHAR2` | `'VVVVFVVVVFVVVVFVVVV,VVVV-VVVV-VVVV-VVVV,*,1,12'` | Redacts a 16 digit credit card number and displays only 4 digits. **Example:** `1234 5678 9000 2358` becomes `****-****-****-2358`. | -| `REDACT_DATE_MILLENNIUM` | `VARCHAR2` | `'m1d1y2000'` | Redacts a date that is in the `DD-MM-YY` format. **Example:** Redacts all date to `01-JAN-2000`. | -| `REDACT_DATE_EPOCH` | `VARCHAR2` | `'m1d1y1970'` | Redacts all dates to `01-JAN-70`. | -| `REDACT_AMEX_CCN_FORMATTED` | `VARCHAR2` | `'VVVVFVVVVVVFVVVVV,VVVV-VVVVVV-VVVVV,*,1,10'` | Redacts the Amercian Express credit card number and replaces the digit with `*` except for the last 5 digits. **Example:** The credit card number `1234 567890 34500` becomes `**** ****** 34500`. | -| `REDACT_AMEX_CCN_NUMBER` | `VARCHAR2` | `'0,1,10'` | Redacts the Amercian Express credit card number and replaces the digit with `0` except for the last 5 digits. **Example:** The credit card number `1234 567890 34500` becomes `0000 000000 34500`. | -| `REDACT_SIN_FORMATTED` | `VARCHAR2` | `'VVVFVVVFVVV,VVV-VVV-VVV,*,1,6'` | Redacts the Social Insurance Number by replacing the first 6 digits by `*`. **Example:** `123-456-789` becomes `***-***-789`. | -| `REDACT_SIN_NUMBER` | `VARCHAR2` | `'9,1,6'` | Redacts the Social Insurance Number by replacing the first 6 digits by `9`. **Example:** `123456789` becomes `999999789`. | -| `REDACT_SIN_UNFORMATTED` | `VARCHAR2` | `'VVVVVVVVV,VVVVVVVVV,*,1,6'` | Redacts the Social Insurance Number by replacing the first 6 digits by `*`. **Example:** `123456789` becomes `******789`. | -| `REDACT_CCN_FORMATTED` | `VARCHAR2` | `'VVVVFVVVVFVVVVFVVVV,VVVV-VVVV-VVVV-VVVV,*,1,12'` | Redacts a credit card number by `*` and displays only 4 digits. **Example:** The credit card number `1234-5678-9000-4671` becomes `****-****-****-4671`. | -| `REDACT_CCN_NUMBER` | `VARCHAR2` | `'9,1,12'` | Redacts a credit card number by `0` except the last 4 digits. **Example:** The credit card number `1234567890004671` becomes `0000000000004671`. | -| `REDACT_NA_PHONE_FORMATTED` | `VARCHAR2` | `‘VVVFVVVFVVVV,VVV-VVV-VVVV,X,4,10'` | Redacts the North American phone number by `X` leaving the area code. **Example:** `123-456-7890` becomes `123-XXX-XXXX`. | -| `REDACT_NA_PHONE_NUMBER` | `VARCHAR2` | `'0,4,10'` | Redacts the North American phone number by `0` leaving the area code. **Example:** `1234567890` becomes `1230000000`. | -| `REDACT_NA_PHONE_UNFORMATTED` | `VARCHAR2` | `'VVVVVVVVVV,VVVVVVVVVV,X,4,10'` | Redacts the North American phone number by `X` leaving the area code. **Example:** `1234567890` becomes `123XXXXXXX`. | -| `REDACT_UK_NIN_FORMATTED` | `VARCHAR2` | `'VVFVVFVVFVVFV,VV VV VV VV V,X,3,8'` | Redacts the UK National Insurance Number by `X` but leaving the alphabetic characters. **Example:** `NY 22 01 34 D` becomes `NY XX XX XX D`. | -| `REDACT_UK_NIN_UNFORMATTED` | `VARCHAR2` | `'VVVVVVVVV,VVVVVVVVV,X,3,8'` | Redacts the UK National Insurance Number by `X` but leaving the alphabetic characters. **Example:** `NY220134D` becomes `NYXXXXXXD`. | - -A regular expression-based redaction searches for patterns of data to redact. The `regexp_pattern` search the values 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. - -| Function Parameter and Description | Data Type | Value | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------: | :----------------------------------------------------: | -| `RE_PATTERN_CC_L6_T4`: Searches for the middle digits of a credit card number that includes 6 leading digits and 4 trailing digits.
The `regexp_replace_string` setting to use with the format is `RE_REDACT_CC_MIDDLE_DIGITS` that replaces the identified pattern with the characters specified by the `RE_REDACT_CC_MIDDLE_DIGITS` parameter. | `VARCHAR2` | `'(\d\d\d\d\d\d)(\d\d\d*)(\d\d\d\d)'` | -| `RE_PATTERN_ANY_DIGIT`: Searches for any digit and replaces the identified pattern with the characters specified by the following values of the `regexp_replace_string` parameter.
`regexp_replace_string=> RE_REDACT_WITH_SINGLE_X`
(replaces any matched digit with the `X` character).
`regexp_replace_string=> RE_REDACT_WITH_SINGLE_1`
(replaces any matched digit with the `1` character). | `VARCHAR2` | `'\d'` | -| `RE_PATTERN_US_PHONE`: Searches for the U.S phone number and replaces the identified pattern with the characters specified by the `regexp_replace_string` parameter.
`regexp_replace_string=> RE_REDACT_US_PHONE_L7`
(searches the phone number and then replaces the last 7 digits). | `VARCHAR2` | `'(\(\d\d\d\)\|\d\d\d)-(\d\d\d)-(\d\d\d\d)'` | -| `RE_PATTERN_EMAIL_ADDRESS`: Searches for the email address and replaces the identified pattern with the characters specified by the following values of the `regexp_replace_string` parameter.
`regexp_replace_string=> RE_REDACT_EMAIL_NAME`
(finds the email address and redacts the email username).
`regexp_replace_string=> RE_REDACT_EMAIL_DOMAIN`
(finds the email address and redacts the email domain).
`regexp_replace_string=> RE_REDACT_EMAIL_ENTIRE`
(finds the email address and redacts the entire email address). | `VARCHAR2` | `'([A-Za-z0-9._%+-]+)@([A-Za-z0-9.-]+\.[A-Za-z]{2,4})'` | -| `RE_PATTERN_IP_ADDRESS`: Searches for an IP address and replaces the identified pattern with the characters specified by the `regexp_replace_string` parameter. The `regexp_replace_string` parameter to be used is `RE_REDACT_IP_L3` that replaces the last section of an IP address with `999` and indicates it is redacted. | `VARCHAR2` | `'(\d{1,3}\.\d{1,3}\.\d{1,3})\.\d{1,3}'` | -| `RE_PATTERN_AMEX_CCN`: Searches for the American Express credit card number. The `regexp_replace_string` parameter to be used is `RE_REDACT_AMEX_CCN` that redacts all of the digits except the last 5. | `VARCHAR2` | `'.*(\d\d\d\d\d)$'` | -| `RE_PATTERN_CCN`: Searches for the credit card number other than American Express credit cards. The `regexp_replace_string` parameter to be used is `RE_REDACT_CCN` that redacts all of the digits except the last 4. | `VARCHAR2` | `'.*(\d\d\d\d)$'` | -| `RE_PATTERN_US_SSN`: Searches the SSN number and replaces the identified pattern with the characters specified by the `regexp_replace_string` parameter.
`'\1-XXX-XXXX'` or `'XXX-XXX-\3'` will 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. - -| Function Parameter | Data Type | Value | Description | -| ---------------------------- | ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `RE_REDACT_CC_MIDDLE_DIGITS` | `VARCHAR2` | `'\1XXXXXX\3'` | Redacts the middle digits of a credit card number according to the `regexp_pattern` parameter with the `RE_PATTERN_CC_L6_T4` format and replaces each redacted character with an `X`.

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

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

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

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

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

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

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

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

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

**Example:** `8749012678345671` becomes `************5671`. | - -The following tables show the `regexp_position` value and `regexp_occurence` values that you can use during `REGEXP` based redaction. - -| Function Parameter | Data Type | Value | Description | -| ------------------ | --------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `RE_BEGINNING` | `INTEGER` | `1` | Specifies the position of a character where search must begin. By default, the value is `1` that indicates the search begins at the first character of `source_char`. | - -| Function Parameter | Data Type | Value | Description | -| ------------------ | --------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `RE_ALL` | `INTEGER` | `0` | Specifies the replacement occurrence of a substring. If the value is `0`, then the replacement of each matching substring occurs. | -| `RE_FIRST` | `INTEGER` | `1` | Specifies the replacement occurrence of a substring. If the value is `1`, then the replacement of the first matching substring occurs. | - -The following table shows the `regexp_match_parameter` values that you can use during `REGEXP` based redaction which lets you change the default matching behavior of a function. - -| Function Parameter | Data Type | Value | Description | -| ---------------------- | ---------- | ----- | --------------------------------------------------------------------------------------------------------------- | -| `RE_CASE_SENSITIVE` | `VARCHAR2` | `'c'` | Specifies the case-sensitive matching. | -| `RE_CASE_INSENSITIVE` | `VARCHAR2` | `'i'` | Specifies the case-insensitive matching. | -| `RE_MULTIPLE_LINES` | `VARCHAR2` | `'m'` | Treats the source string as multiple lines but if you omit this parameter, then it indicates as a single line. | -| `RE_NEWLINE_WILDCARD` | `VARCHAR2` | `'n'` | Specifies the period (.), but if you omit this parameter, then the period does not match the newline character. | -| `RE_IGNORE_WHITESPACE` | `VARCHAR2` | `'x'` | Ignores the whitespace characters. | - -!!! Note - If you create a redaction policy based on a numeric type column, then make sure that the result after redaction is a number and accordingly set the replacement string 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. - -## ADD_POLICY - -The `add_policy` procedure creates a new data redaction policy for a table. - -```text -PROCEDURE add_policy ( - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2, - IN VARCHAR2, - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2 DEFAULT NULL, - IN INTEGER DEFAULT DBMS_REDACT.FULL, - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2, - IN BOOLEAN DEFAULT TRUE, - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2 DEFAULT NULL, - IN INTEGER DEFAULT DBMS_REDACT.RE_BEGINNING, - IN INTEGER DEFAULT DBMS_REDACT.RE_ALL, - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2 DEFAULT NULL - ) -``` - -**Parameters** - -`object_schema` - - Specifies the name of the schema in which the object resides and on which the data redaction policy will be applied. If you specify `NULL` then the given object is searched by the order specified by `search_path` setting. - -`object_name` - - Name of the table on which the data redaction policy is created. - -`policy_name` - - Name of the policy to be added. Ensure that the `policy_name` is unique for the table on which the policy is created. - -`policy_description` - - Specify the description of a redaction policy. - -`column_name` - - Name of the column to which the redaction policy applies. To redact more than one column, use the `alter_policy` procedure to add additional 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, you will get a warning message. - -`function_type` - - The type of redaction function to be used. The possible values are `NONE, FULL, PARTIAL, RANDOM, REGEXP`, and `CUSTOM`. - -`function_parameters` - - Specifies the function parameters for the partition redaction and is applicable only for partial redaction. - -`expression` - - Specifies the Boolean expression for the table and determines how the policy is to be applied. The redaction occurs if this policy expression is evaluated 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. - -`regexp_pattern` - - Specifies the regular expression pattern to redact data. If the `regexp_pattern` does not match, then the `NULL` value is returned. - -`regexp_replace_string` - - Specifies the replacement string value. - -`regexp_position` - - Specifies the position of a character where search must begin. By default, the function parameter is `RE_BEGINNING`. - -`regexp_occurrence` - - Specifies the replacement occurrence of a substring. If the constant is `RE_ALL`, then the replacement of each matching substring occurs. If the constant is `RE_FIRST`, then the replacement of the first matching substring occurs. - -`regexp_match_parameter` - - Changes the default matching behavior of a function. The possible regexp_match_parameter constants can be `‘RE_CASE_SENSITIVE’, ‘RE_CASE_INSENSITIVE’, ‘RE_MULTIPLE_LINES’, ‘RE_NEWLINE_WILDCARD’, ‘RE_IGNORE_WHITESPACE’`. - - **Note**: For more information on `constants`, `function_parameters`, or `regexp` (regular expressions) see, 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. - -**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. - -```text -edb=# CREATE TABLE payment_details_tab ( -customer_id NUMBER NOT NULL, -card_string VARCHAR2(19) NOT NULL); -CREATE TABLE - -edb=# BEGIN - INSERT INTO payment_details_tab VALUES (4000, '1234-1234-1234-1234'); - INSERT INTO payment_details_tab VALUES (4001, '2345-2345-2345-2345'); -END; - -EDB-SPL Procedure successfully completed - -edb=# CREATE USER redact_user; -CREATE ROLE -edb=# GRANT SELECT ON payment_details_tab TO redact_user; -GRANT - -\c edb base_user - -BEGIN - DBMS_REDACT.add_policy( - object_schema => 'public', - object_name => 'payment_details_tab', - policy_name => 'redactPolicy_001', - policy_description => 'redactPolicy_001 for payment_details_tab -table', - column_name => 'customer_id', - function_type => DBMS_REDACT.full, - expression => '1=1', - enable => TRUE); -END; -``` - -Redacted Result: - -```text -edb=# \c edb redact_user -You are now connected to database "edb" as user "redact_user". - -edb=> select customer_id from payment_details_tab order by 1; - customer_id -------------- - 0 - 0 -(2 rows) -``` - -## ALTER_POLICY - -The `alter_policy` procedure alters or modifies an existing data redaction policy for a table. - -```text -PROCEDURE alter_policy ( - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2, - IN VARCHAR2, - IN INTEGER DEFAULT DBMS_REDACT.ADD_COLUMN, - IN VARCHAR2 DEFAULT NULL, - IN INTEGER DEFAULT DBMS_REDACT.FULL, - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2 DEFAULT NULL, - IN INTEGER DEFAULT DBMS_REDACT.RE_BEGINNING, - IN INTEGER DEFAULT DBMS_REDACT.RE_ALL, - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2 DEFAULT NULL - ) -``` - -**Parameters** - -`object_schema` - - Specifies the name of the schema in which the object resides and on which the data redaction policy will be altered. If you specify `NULL` then the given object is searched by the order specified by `search_path` setting. - -`object_name` - - Name of the table to which to alter a data redaction policy. - -`policy_name` - - Name of the policy to be altered. - -`action` - - The action to perform. For more information about action parameters see, `DBMS_REDACT Constants and Function Parameters`. - -`column_name` - - Name of the column to which the redaction policy applies. - -`function_type` - - The type of redaction function to be used. The possible values are `NONE, FULL, PARTIAL, RANDOM, REGEXP`, and `CUSTOM`. - -`function_parameters` - - Specifies the function parameters for the redaction function. - -`expression` - - Specifies the Boolean expression for the table and determines how the policy is to be applied. The redaction occurs if this policy expression is evaluated 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. - -`regexp_replace_string` - - Specifies the replacement string value. - -`regexp_position` - - Specifies the position of a character where search must begin. By default, the function parameter is `RE_BEGINNING`. - -`regexp_occurence` - - Specifies the replacement occurrence of a substring. If the constant is `RE_ALL`, then the replacement of each matching substring occurs. If the constant is `RE_FIRST`, then the replacement of the first matching substring occurs. - -`regexp_match_parameter` - - Changes the default matching behavior of a function. The possible regexp_match_parameter constants can be `‘RE_CASE_SENSITIVE’, ‘RE_CASE_INSENSITIVE’, ‘RE_MULTIPLE_LINES’, ‘RE_NEWLINE_WILDCARD’, ‘RE_IGNORE_WHITESPACE’`. - - **Note**: For more information on `constants, function_parameters`, or `regexp` (regular expressions) see, `Using DBMS_REDACT Constants and Function Parameters`. - -`policy_description` - - Specify the description of a redaction 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, you will get a warning message. - -`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. - -**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. - -```text -\c edb base _user - -BEGIN - DBMS_REDACT.alter_policy ( - object_schema => 'public', - object_name => 'payment_details_tab', - policy_name => 'redactPolicy_001', - action => DBMS_REDACT.ADD_COLUMN, - column_name => 'card_string', - function_type => DBMS_REDACT.partial, - function_parameters => DBMS_REDACT.REDACT_CCN16_F12); -END; -``` - -Redacted Result: - -```text -edb=# \c - redact_user -You are now connected to database "edb" as user "redact_user". -edb=> SELECT * FROM payment_details_tab; - customer_id | card_string --------------+--------------------- - 0 | ****-****-****-1234 - 0 | ****-****-****-2345 -(2 rows) -``` - -## DISABLE_POLICY - -The `disable_policy` procedure disables an existing data redaction policy. - -```text -PROCEDURE disable_policy ( - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2, - IN VARCHAR2 - ) -``` - -**Parameters** - -`object_schema` - - Specifies the name of the schema in which the object resides and on which the data redaction policy will be applied. If you specify `NULL` then the given object is searched by the order specified by `search_path` setting. - -`object_name` - - Name of the table for which to disable a data redaction policy. - -`policy_name` - - Name of the policy to be disabled. - -**Example** - -The following example illustrates how to disable a policy. - -```text -\c edb base_user - -BEGIN - DBMS_REDACT.disable_policy( - object_schema => 'public', - object_name => 'payment_details_tab', - policy_name => 'redactPolicy_001'); -END; -``` - -Redacted Result: Data is no longer redacted after disabling a policy. - -## ENABLE_POLICY - -The `enable_policy` procedure enables the previously disabled data redaction policy. - -```text -PROCEDURE enable_policy ( - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2, - IN VARCHAR2 - ) -``` - -**Parameters** - -`object_schema` - - Specifies the name of the schema in which the object resides and on which the data redaction policy will be applied. If you specify `NULL` then the given object is searched by the order specified by `search_path` setting. - -`object_name` - - Name of the table to which to enable a data redaction policy. - -`policy_name` - - Name of the policy to be enabled. - -**Example** - -The following example illustrates how to enable a policy. - -```text -\c edb base_user - -BEGIN - DBMS_REDACT.enable_policy( - object_schema => 'public', - object_name => 'payment_details_tab', - policy_name => 'redactPolicy_001'); -END; -``` - -Redacted Result: Data is redacted after enabling a policy. - -## DROP_POLICY - -The `drop_policy` procedure drops a data redaction policy by removing the masking policy from a table. - -```text -PROCEDURE drop_policy ( - IN VARCHAR2 DEFAULT NULL, - IN VARCHAR2, - IN VARCHAR2 - ) -``` - -**Parameters** - -`object_schema` - - Specifies the name of the schema in which the object resides and on which the data redaction policy will be applied. If you specify `NULL` then the given object is searched by the order specified by `search_path` setting. - -`object_name` - - Name of the table from which to drop a data redaction policy. - -`policy_name` - - Name of the policy to be dropped. - -**Example** - -The following example illustrates how to drop a policy. - -```text -\c edb base_user - -BEGIN - DBMS_REDACT.drop_policy( - object_schema => 'public', - object_name => 'payment_details_tab', - policy_name => 'redactPolicy_001'); -END; -``` - -Redacted Result: The server drops the specified policy. - -## UPDATE_FULL_REDACTION_VALUES - -The `update_full_redaction_values` procedure updates the default displayed values for a data redaction policy and these default values can be viewed using the `redaction_values_for_type_full` view that use the full redaction type. - -```TEXT -PROCEDURE update_full_redaction_values ( - IN NUMBER DEFAULT NULL, - IN FLOAT4 DEFAULT NULL, - IN FLOAT8 DEFAULT NULL, - IN CHAR DEFAULT NULL, - IN VARCHAR2 DEFAULT NULL, - IN NCHAR DEFAULT NULL, - IN NVARCHAR2 DEFAULT NULL, - IN DATE DEFAULT NULL, - IN TIMESTAMP DEFAULT NULL, - IN TIMESTAMPTZ DEFAULT NULL, - IN BLOB DEFAULT NULL, - IN CLOB DEFAULT NULL, - IN CLOB DEFAULT NULL - ) -``` - -**Parameters** - -`number_val` - - Updates the default value for columns of the `NUMBER` datatype. - -`binfloat_val` - - The `FLOAT4` datatype is a random value. The binary float datatype is not supported. - -`bindouble_val` - - The `FLOAT8` datatype is a random value. The binary double datatype is not supported. - -`char_val` - - Updates the default value for columns of the `CHAR` datatype. - -`varchar_val` - - Updates the default value for columns of the `VARCHAR2` datatype. - -`nchar_val` - - The `nchar_val` is mapped to `CHAR` datatype and returns the `CHAR` value. - -`nvarchar_val` - - The `nvarchar_val` is mapped to `VARCHAR2` datatype and returns the `VARCHAR` value. - -`datecol_val` - - Updates the default value for columns of the `DATE` datatype. - -`ts_val` - - Updates the default value for columns of the `TIMESTAMP` datatype. - -`tswtz_val` - - Updates the default value for columns of the `TIMESTAMPTZ` datatype. - -`blob_val` - - Updates the default value for columns of the `BLOB` datatype. - -`clob_val` - - Updates the default value for columns of the `CLOB` datatype. - -`nclob_val` - - The `nclob_val` is mapped to `CLOB` datatype and returns the `CLOB` value. - -**Example** - -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: - -```text -edb=# \x -Expanded display is on. -edb=# SELECT number_value, char_value, varchar_value, date_value, - timestamp_value, timestamp_with_time_zone_value, blob_value, -clob_value -FROM redaction_values_for_type_full; --[ RECORD 1 ]------------------+-------------------------- -number_value | 0 -char_value | -varchar_value | -date_value | 01-JAN-01 00:00:00 -timestamp_value | 01-JAN-01 01:00:00 -timestamp_with_time_zone_value | 31-DEC-00 20:00:00 -05:00 -blob_value | \x5b72656461637465645d -clob_value | [redacted] -(1 row) -``` - -Now, update the default values for full redaction type. The `NULL` values will be ignored. - -```text -\c edb base_user - -edb=# BEGIN - DBMS_REDACT.update_full_redaction_values ( - number_val => 9999999, - char_val => 'Z', - varchar_val => 'V', - datecol_val => to_date('17/10/2018', 'DD/MM/YYYY'), - ts_val => to_timestamp('17/10/2018 11:12:13', 'DD/MM/YYYY HH24:MI:SS'), - tswtz_val => NULL, - blob_val => 'NEW REDACTED VALUE', - clob_val => 'NEW REDACTED VALUE'); -END; -``` - -You can now see the updated values using `redaction_values_for_type_full` view. - -```text -EDB-SPL Procedure successfully completed -edb=# SELECT number_value, char_value, varchar_value, date_value, - timestamp_value, timestamp_with_time_zone_value, blob_value, -clob_value -FROM redaction_values_for_type_full; --[ RECORD 1 ]------------------+--------------------------------------- -number_value | 9999999 -char_value | Z -varchar_value | V -date_value | 17-OCT-18 00:00:00 -timestamp_value | 17-OCT-18 11:12:13 -timestamp_with_time_zone_value | 31-DEC-00 20:00:00 -05:00 -blob_value | \x4e45572052454441435445442056414c5545 -clob_value | NEW REDACTED VALUE -(1 row) -``` - -Redacted Result: - -```text -edb=# \c edb redact_user -You are now connected to database "edb" as user "redact_user". - -edb=> select * from payment_details_tab order by 1; - customer_id | card_string --------------+------------- - 9999999 | V - 9999999 | V -(2 rows) -``` diff --git a/product_docs/docs/epas/12/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/12/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/01_using_calendar_syntax_to_specify_a_repeating_interval.mdx deleted file mode 100644 index ab386d98016..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/01_using_calendar_syntax_to_specify_a_repeating_interval.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: "Using Calendar Syntax to Specify a Repeating Interval" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/using_calendar_syntax_to_specify_a_repeating_interval.html" ---- - -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. - -`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 will execute. Multiple token values must be separated by a semi-colon (;). - -For example, the following value: - - `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 Advanced Server: - -| 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` | -| `BYMONTHDAY` | `BYMONTHDAY=day_of_month` | Where `day_of_month` is a value from `1` through `31` | -| `BYDAY` | `BYDAY=weekday` | Where `weekday` is a three-letter abbreviation or single-digit value representing the day of the week. | -| | | `Monday` \| `MON` \| `1` \| | -| | | `Tuesday` \| `TUE` \| `2` \| | -| | | `Wednesday` \| `WED` \| `3` \| | -| | | `Thursday` \| `THU` \| `4` \| | -| | | `Friday` \| `FRI` \| `5` \| | -| | | `Saturday` \| `SAT` \| `6` \| | -| | | `Sunday` \| `SUN` \| `7` \| | -| `BYDATE` | `BYDATE=date(, date)...` | Where date is `YYYYMMDD`.

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

`MM` is a two-digit representation of the month,
and `DD` is a two-digit day representation of the day | -| `BYHOUR` | `BYHOUR=hour` | Where `hour` is a value from `0` through `23`. | -| `BYMINUTE` | `BYMINUTE=minute` | Where `minute` is a value from `0` through `59`. | diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/index.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/index.mdx deleted file mode 100644 index 7c9a17bf0e5..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/15_dbms_scheduler/index.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "DBMS_SCHEDULER" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/dbms_scheduler.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: - -| 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. | -| `DISABLE(name, force, commit_semantics)` | n/a | Use the `DISABLE` procedure to disable a job or program. | -| `DROP_JOB(job_name, force, defer, commit_semantics)` | n/a | Use the `DROP_JOB` procedure to drop a job. | -| `DROP_PROGRAM(program_name, force)` | n/a | Use the `DROP_PROGRAM` procedure to drop a program. | -| `DROP_PROGRAM_ARGUMENT(program_name, argument_position)` | n/a | Use the first form of `DROP_PROGRAM_ARGUMENT` to drop a program argument by specifying the argument position. | -| `DROP_PROGRAM_ARGUMENT(program_name, argument_name)` | n/a | Use the second form of `DROP_PROGRAM_ARGUMENT` to drop a program argument by specifying the argument name. | -| `DROP_SCHEDULE(schedule_name, force)` | n/a | Use the `DROP SCHEDULE` procedure to drop a schedule. | -| `ENABLE(name, commit_semantics)` | n/a | Use the `ENABLE` command to enable a program or job. | -| `EVALUATE_CALENDAR_STRING(calendar_string, start_date, return_date_after, next_run_date)` | n/a | Use `EVALUATE_CALENDAR_STRING` to review the execution date described by a user-defined calendar schedule. | -| `RUN_JOB(job_name, use_current_session, manually)` | n/a | Use the `RUN_JOB` procedure to execute a job immediately. | -| `SET_JOB_ARGUMENT_VALUE(job_name, argument_position, argument_value)` | n/a | Use the first form of `SET_JOB_ARGUMENT` value to set the value of a job argument described by the argument's position. | -| `SET_JOB_ARGUMENT_VALUE(job_name, argument_name, argument_value)` | n/a | Use the second form of `SET_JOB_ARGUMENT` value to set the value of a job argument described by the argument's name. | - -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. - -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`. - -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 Advanced Server installation). - -Note that after creating the `DBMS_SCHEDULER` tables, only a superuser will be able to perform a dump or reload of the database. - -
- -using_calendar_syntax_to_specify_a_repeating_interval create_job create_program create_schedule define_program_argument dbms_scheduler_disable drop_job drop_program drop_program_argument drop_schedule dbms_scheduler_enable evaluate_calendar_string run_job set_job_argument_value - -
diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/01_bind_variable.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/01_bind_variable.mdx deleted file mode 100644 index 624e43d670b..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/01_bind_variable.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: "BIND_VARIABLE" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/bind_variable.html" ---- - -The `BIND_VARIABLE` procedure provides the capability to associate a value with an `IN` or `IN OUT` bind variable in a SQL command. - -```text -BIND_VARIABLE( INTEGER, VARCHAR2, - { BLOB | CLOB | DATE | FLOAT | INTEGER | NUMBER | TIMESTAMP | VARCHAR2 } - [, INTEGER ]) -``` - -**Parameters** - -`c` - - Cursor ID of the cursor for the SQL command with bind variables. - -`name` - - Name of the bind variable in the SQL command. - -`value` - - Value to be assigned. - -`out_value_size` - - If `name` is an `IN OUT` variable, defines the maximum length of the output value. If not specified, the length of `value` is assumed. - -**Examples** - -The following anonymous block uses bind variables to insert a row into the `emp` table. - -```text -DECLARE - curid INTEGER; - v_sql VARCHAR2(150) := 'INSERT INTO emp VALUES ' || - '(:p_empno, :p_ename, :p_job, :p_mgr, ' || - ':p_hiredate, :p_sal, :p_comm, :p_deptno)'; - v_empno emp.empno%TYPE; - v_ename emp.ename%TYPE; - v_job emp.job%TYPE; - v_mgr emp.mgr%TYPE; - v_hiredate emp.hiredate%TYPE; - v_sal emp.sal%TYPE; - v_comm emp.comm%TYPE; - v_deptno emp.deptno%TYPE; - v_status INTEGER; -BEGIN - curid := DBMS_SQL.OPEN_CURSOR; - DBMS_SQL.PARSE(curid,v_sql,DBMS_SQL.native); - v_empno := 9001; - v_ename := 'JONES'; - v_job := 'SALESMAN'; - v_mgr := 7369; - v_hiredate := TO_DATE('13-DEC-07','DD-MON-YY'); - v_sal := 8500.00; - v_comm := 1500.00; - v_deptno := 40; - DBMS_SQL.BIND_VARIABLE(curid,':p_empno',v_empno); - DBMS_SQL.BIND_VARIABLE(curid,':p_ename',v_ename); - DBMS_SQL.BIND_VARIABLE(curid,':p_job',v_job); - DBMS_SQL.BIND_VARIABLE(curid,':p_mgr',v_mgr); - DBMS_SQL.BIND_VARIABLE(curid,':p_hiredate',v_hiredate); - DBMS_SQL.BIND_VARIABLE(curid,':p_sal',v_sal); - DBMS_SQL.BIND_VARIABLE(curid,':p_comm',v_comm); - DBMS_SQL.BIND_VARIABLE(curid,':p_deptno',v_deptno); - v_status := DBMS_SQL.EXECUTE(curid); - DBMS_OUTPUT.PUT_LINE('Number of rows processed: ' || v_status); - DBMS_SQL.CLOSE_CURSOR(curid); -END; - -Number of rows processed: 1 -``` diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/07_column_value_raw.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/07_column_value_raw.mdx deleted file mode 100644 index 90fcefa99b7..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/07_column_value_raw.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "COLUMN_VALUE_RAW" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/column_value_raw.html" ---- - -The `COLUMN_VALUE_RAW` procedure defines a variable to receive a `RAW` value from a cursor. - -```text -COLUMN_VALUE_RAW( INTEGER, INTEGER, OUT RAW - [, OUT NUMBER [, OUT INTEGER ]]) -``` - -**Parameters** - -`c` - - Cursor id of the cursor returning data to the variable being defined. - -`position` - - Position within the cursor of the returned data. The first value in the cursor is position 1. - -`value` - - Variable of data type `RAW` receiving the data returned in the cursor by a prior fetch call. - -`column_error` - - Error number associated with the column, if any. - -`actual_length` - - Actual length of the data prior to any truncation. - diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/10_define_column_raw.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/10_define_column_raw.mdx deleted file mode 100644 index 5882316926a..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/10_define_column_raw.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "DEFINE_COLUMN_RAW" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/define_column_raw.html" ---- - -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. - -```text -DEFINE_COLUMN_RAW( INTEGER, INTEGER, RAW, - INTEGER) -``` - -**Parameters** - -`c` - - Cursor id of the cursor associated with the `SELECT` command. - -`position` - - Position of the column or expression in the `SELECT` list that is being defined. - -`column` - - A `RAW` variable. - -`column_size` - - The maximum length of the returned data. Returned data exceeding `column_size` is truncated to `column_size` characters. - - diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/11_describe_columns.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/11_describe_columns.mdx deleted file mode 100644 index 2497f5296d6..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/11_describe_columns.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "DESCRIBE_COLUMNS" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/describe_columns.html" ---- - -The `DESCRIBE_COLUMNS` procedure describes the columns returned by a cursor. - -```text -DESCRIBE_COLUMNS( INTEGER, OUT INTEGER, OUT - DESC_TAB); -``` - -**Parameters** - -`c` - - The cursor ID of the cursor. - -`col_cnt` - - The number of columns in cursor result set. - -`desc_tab` - - The table that contains a description of each column returned by the cursor. The descriptions are of type `DESC_REC`, and contain the following values: - -| Column Name | Type | -| --------------------- | --------------- | -| `col_type` | `INTEGER` | -| `col_max_len` | `INTEGER` | -| `col_name` | `VARCHAR2(128)` | -| `col_name_len` | `INTEGER` | -| `col_schema_name` | `VARCHAR2(128)` | -| `col_schema_name_len` | `INTEGER` | -| `col_precision` | `INTEGER` | -| `col_scale` | `INTEGER` | -| `col_charsetid` | `INTEGER` | -| `col_charsetform` | `INTEGER` | -| `col_null_ok` | `BOOLEAN` | diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/13_execute_and_fetch.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/13_execute_and_fetch.mdx deleted file mode 100644 index a5ae0eb400a..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/13_execute_and_fetch.mdx +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: "EXECUTE_AND_FETCH" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/execute_and_fetch.html" ---- - -Function `EXECUTE_AND_FETCH` executes a parsed `SELECT` command and fetches one row. - -```text - INTEGER EXECUTE_AND_FETCH( INTEGER [, BOOLEAN ]) -``` - -**Parameters** - -`c` - - Cursor id of the cursor for the `SELECT` command to be executed. - -`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. - -`status` - - Returns 1 if a row was successfully fetched, 0 if no rows to fetch. If an exception is thrown, no value is returned. - -**Examples** - -The following stored procedure uses the `EXECUTE_AND_FETCH` function to retrieve one employee using the employee’s name. An exception will be thrown if the employee is not found, or there is more than one employee with the same name. - -```text -CREATE OR REPLACE PROCEDURE select_by_name( - p_ename emp.ename%TYPE -) -IS - curid INTEGER; - v_empno emp.empno%TYPE; - v_hiredate emp.hiredate%TYPE; - v_sal emp.sal%TYPE; - v_comm emp.comm%TYPE; - v_dname dept.dname%TYPE; - v_disp_date VARCHAR2(10); - v_sql VARCHAR2(120) := 'SELECT empno, hiredate, sal, ' || - 'NVL(comm, 0), dname ' || - 'FROM emp e, dept d ' || - 'WHERE ename = :p_ename ' || - 'AND e.deptno = d.deptno'; - v_status INTEGER; -BEGIN - curid := DBMS_SQL.OPEN_CURSOR; - DBMS_SQL.PARSE(curid,v_sql,DBMS_SQL.native); - DBMS_SQL.BIND_VARIABLE(curid,':p_ename',UPPER(p_ename)); - DBMS_SQL.DEFINE_COLUMN(curid,1,v_empno); - DBMS_SQL.DEFINE_COLUMN(curid,2,v_hiredate); - DBMS_SQL.DEFINE_COLUMN(curid,3,v_sal); - DBMS_SQL.DEFINE_COLUMN(curid,4,v_comm); - DBMS_SQL.DEFINE_COLUMN(curid,5,v_dname,14); - v_status := DBMS_SQL.EXECUTE_AND_FETCH(curid,TRUE); - DBMS_SQL.COLUMN_VALUE(curid,1,v_empno); - DBMS_SQL.COLUMN_VALUE(curid,2,v_hiredate); - DBMS_SQL.COLUMN_VALUE(curid,3,v_sal); - DBMS_SQL.COLUMN_VALUE(curid,4,v_comm); - DBMS_SQL.COLUMN_VALUE(curid,5,v_dname); - v_disp_date := TO_CHAR(v_hiredate, 'MM/DD/YYYY'); - DBMS_OUTPUT.PUT_LINE('Number : ' || v_empno); - DBMS_OUTPUT.PUT_LINE('Name : ' || UPPER(p_ename)); - DBMS_OUTPUT.PUT_LINE('Hire Date : ' || v_disp_date); - DBMS_OUTPUT.PUT_LINE('Salary : ' || v_sal); - DBMS_OUTPUT.PUT_LINE('Commission: ' || v_comm); - DBMS_OUTPUT.PUT_LINE('Department: ' || v_dname); - DBMS_SQL.CLOSE_CURSOR(curid); -EXCEPTION - WHEN NO_DATA_FOUND THEN - DBMS_OUTPUT.PUT_LINE('Employee ' || p_ename || ' not found'); - DBMS_SQL.CLOSE_CURSOR(curid); - WHEN TOO_MANY_ROWS THEN - DBMS_OUTPUT.PUT_LINE('Too many employees named, ' || - p_ename || ', found'); - DBMS_SQL.CLOSE_CURSOR(curid); - WHEN OTHERS THEN - DBMS_OUTPUT.PUT_LINE('The following is SQLERRM:'); - DBMS_OUTPUT.PUT_LINE(SQLERRM); - DBMS_OUTPUT.PUT_LINE('The following is SQLCODE:'); - DBMS_OUTPUT.PUT_LINE(SQLCODE); - DBMS_SQL.CLOSE_CURSOR(curid); -END; - -EXEC select_by_name('MARTIN') - -Number : 7654 -Name : MARTIN -Hire Date : 09/28/1981 -Salary : 1250 -Commission: 1400 -Department: SALES -``` diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/16_last_row_count.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/16_last_row_count.mdx deleted file mode 100644 index 50614bab0e2..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/16_last_row_count.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "LAST_ROW_COUNT" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/last_row_count.html" ---- - -The `LAST_ROW_COUNT` function returns the number of rows that have been currently fetched. - -```text - INTEGER LAST_ROW_COUNT -``` - -**Parameters** - -`rowcnt` - - Number of row fetched thus far. - -**Examples** - -The following example uses the `LAST_ROW_COUNT` function to display the total number of rows fetched in the query. - -```text -DECLARE - curid sINTEGER; - v_empno NUMBER(4); - v_ename VARCHAR2(10); - v_hiredate DATE; - v_sal NUMBER(7,2); - v_comm NUMBER(7,2); - v_sql VARCHAR2(50) := 'SELECT empno, ename, hiredate, sal, ' || - 'comm FROM emp'; - v_status INTEGER; -BEGIN - curid := DBMS_SQL.OPEN_CURSOR; - DBMS_SQL.PARSE(curid,v_sql,DBMS_SQL.native); - DBMS_SQL.DEFINE_COLUMN(curid,1,v_empno); - DBMS_SQL.DEFINE_COLUMN(curid,2,v_ename,10); - DBMS_SQL.DEFINE_COLUMN(curid,3,v_hiredate); - DBMS_SQL.DEFINE_COLUMN(curid,4,v_sal); - DBMS_SQL.DEFINE_COLUMN(curid,5,v_comm); - - v_status := DBMS_SQL.EXECUTE(curid); - DBMS_OUTPUT.PUT_LINE('EMPNO ENAME HIREDATE SAL COMM'); - DBMS_OUTPUT.PUT_LINE('----- ---------- ---------- -------- ' || - '--------'); - LOOP - v_status := DBMS_SQL.FETCH_ROWS(curid); - EXIT WHEN v_status = 0; - DBMS_SQL.COLUMN_VALUE(curid,1,v_empno); - DBMS_SQL.COLUMN_VALUE(curid,2,v_ename); - DBMS_SQL.COLUMN_VALUE(curid,3,v_hiredate); - DBMS_SQL.COLUMN_VALUE(curid,4,v_sal); - DBMS_SQL.COLUMN_VALUE(curid,4,v_sal); - DBMS_SQL.COLUMN_VALUE(curid,5,v_comm); - DBMS_OUTPUT.PUT_LINE(v_empno || ' ' || RPAD(v_ename,10) || ' ' || - TO_CHAR(v_hiredate,'yyyy-mm-dd') || ' ' || - TO_CHAR(v_sal,'9,999.99') || ' ' || - TO_CHAR(NVL(v_comm,0),'9,999.99')); - END LOOP; - DBMS_OUTPUT.PUT_LINE('Number of rows: ' || DBMS_SQL.LAST_ROW_COUNT); - DBMS_SQL.CLOSE_CURSOR(curid); -END; - -EMPNO ENAME HIREDATE SAL COMM ------ ---------- ---------- -------- -------- -7369 SMITH 1980-12-17 800.00 .00 -7499 ALLEN 1981-02-20 1,600.00 300.00 -7521 WARD 1981-02-22 1,250.00 500.00 -7566 JONES 1981-04-02 2,975.00 .00 -7654 MARTIN 1981-09-28 1,250.00 1,400.00 -7698 BLAKE 1981-05-01 2,850.00 .00 -7782 CLARK 1981-06-09 2,450.00 .00 -7788 SCOTT 1987-04-19 3,000.00 .00 -7839 KING 1981-11-17 5,000.00 .00 -7844 TURNER 1981-09-08 1,500.00 .00 -7876 ADAMS 1987-05-23 1,100.00 .00 -7900 JAMES 1981-12-03 950.00 .00 -7902 FORD 1981-12-03 3,000.00 .00 -7934 MILLER 1982-01-23 1,300.00 .00 -Number of rows: 14 -``` - - diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/18_parse.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/18_parse.mdx deleted file mode 100644 index 84b004c4d1f..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/18_parse.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "PARSE" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/parse.html" ---- - -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. - -```text -PARSE( INTEGER, VARCHAR2, INTEGER) -``` - -**Parameters** - -`c` - - Cursor ID of an open cursor. - -`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. - -`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 EnterpriseDB 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 do not require a separate `EXECUTE` step. - -```text -DECLARE - curid INTEGER; -BEGIN - curid := DBMS_SQL.OPEN_CURSOR; - DBMS_SQL.PARSE(curid, 'CREATE TABLE job (jobno NUMBER(3), ' || - 'jname VARCHAR2(9))',DBMS_SQL.native); - DBMS_SQL.CLOSE_CURSOR(curid); -END; -``` - -The following inserts two rows into the `job` table. - -```text -DECLARE - curid INTEGER; - v_sql VARCHAR2(50); - v_status INTEGER; -BEGIN - curid := DBMS_SQL.OPEN_CURSOR; - v_sql := 'INSERT INTO job VALUES (100, ''ANALYST'')'; - DBMS_SQL.PARSE(curid, v_sql, DBMS_SQL.native); - v_status := DBMS_SQL.EXECUTE(curid); - DBMS_OUTPUT.PUT_LINE('Number of rows processed: ' || v_status); - v_sql := 'INSERT INTO job VALUES (200, ''CLERK'')'; - DBMS_SQL.PARSE(curid, v_sql, DBMS_SQL.native); - v_status := DBMS_SQL.EXECUTE(curid); - DBMS_OUTPUT.PUT_LINE('Number of rows processed: ' || v_status); - DBMS_SQL.CLOSE_CURSOR(curid); -END; - -Number of rows processed: 1 -Number of rows processed: 1 -``` - -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. - -```text -DECLARE - curid INTEGER; - v_sql VARCHAR2(100); - v_status INTEGER; -BEGIN - curid := DBMS_SQL.OPEN_CURSOR; - v_sql := 'BEGIN ' || - 'INSERT INTO job VALUES (300, ''MANAGER''); ' || - 'INSERT INTO job VALUES (400, ''SALESMAN''); ' || - 'END;'; - DBMS_SQL.PARSE(curid, v_sql, DBMS_SQL.native); - v_status := DBMS_SQL.EXECUTE(curid); - DBMS_SQL.CLOSE_CURSOR(curid); -END; -``` diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/index.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/index.mdx deleted file mode 100644 index 67be14f4d83..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/17_dbms_sql/index.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "DBMS_SQL" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/dbms_sql.html" ---- - -The `DBMS_SQL` package provides an application interface compatible with Oracle databases to the EnterpriseDB dynamic SQL functionality. With `DBMS_SQL` you can construct queries and other commands at run time (rather than when you write the application). EnterpriseDB 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. - -`DBMS_SQL` assumes the privileges of the current user when executing dynamic SQL statements. - -| Function/Procedure | Function or Procedure | Return Type | Description | -| --------------------------------------------------------------------------------------- | --------------------- | ----------- | ---------------------------------------------------------------------- | -| `BIND_VARIABLE(c, name, value [, out_value_size ])` | Procedure | n/a | Bind a value to a variable. | -| `BIND_VARIABLE_CHAR(c, name, value [, out_value_size ])` | Procedure | n/a | Bind a `CHAR` value to a variable. | -| `BIND_VARIABLE_RAW(c, name, value [, out_value_size ])` | Procedure | n/a | Bind a `RAW` value to a variable. | -| `CLOSE_CURSOR(c IN OUT)` | Procedure | n/a | Close a cursor. | -| `COLUMN_VALUE(c, position, value OUT [, column_error OUT [, actual_length OUT ]])` | Procedure | n/a | Return a column value into a variable. | -| `COLUMN_VALUE_CHAR(c, position, value OUT [, column_error OUT [, actual_length OUT ]])` | Procedure | n/a | Return a `CHAR` column value into a variable. | -| `COLUMN_VALUE_RAW(c, position, value OUT [, column_error OUT [, actual_length OUT ]])` | Procedure | n/a | Return a `RAW` column value into a variable. | -| `DEFINE_COLUMN(c, position, column [, column_size ])` | Procedure | n/a | Define a column in the `SELECT` list. | -| `DEFINE_COLUMN_CHAR(c, position, column, column_size)` | Procedure | n/a | Define a `CHAR` column in the `SELECT` list. | -| `DEFINE_COLUMN_RAW(c, position, column, column_size)` | Procedure | n/a | Define a `RAW` column in the `SELECT` list. | -| `DESCRIBE_COLUMNS` | Procedure | n/a | Defines columns to hold a cursor result set. | -| `EXECUTE(c)` | Function | `INTEGER` | Execute a cursor. | -| `EXECUTE_AND_FETCH(c [, exact ])` | Function | `INTEGER` | Execute a cursor and fetch a single row. | -| `FETCH_ROWS(c)` | Function | `INTEGER` | Fetch rows from the cursor. | -| `IS_OPEN(c)` | Function | `BOOLEAN` | Check if a cursor is open. | -| `LAST_ROW_COUNT` | Function | `INTEGER` | Return cumulative number of rows fetched. | -| `OPEN_CURSOR` | Function | `INTEGER` | Open a cursor. | -| `PARSE(c, statement, language_flag)` | Procedure | n/a | Parse a statement. | - -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. - -| Public Variables | Data Type | Value | Description | -| ---------------- | --------- | ----- | ----------------------------------------------------------------------------------------- | -| `native` | `INTEGER` | `1` | Provided for compatibility with Oracle syntax. See `DBMS_SQL.PARSE` for more information. | -| `V6` | `INTEGER` | `2` | Provided for compatibility with Oracle syntax. See `DBMS_SQL.PARSE` for more information. | -| `V7` | `INTEGER` | `3` | Provided for compatibility with Oracle syntax. See `DBMS_SQL.PARSE` for more information | - -
- -bind_variable bind_variable_char bind_variable_raw close_cursor column_value column_value_char column_value_raw define_column define_column_char define_column_raw describe_columns execute execute_and_fetch fetch_rows is_open last_row_count open_cursor parse - -
diff --git a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/18_dbms_utility.mdx b/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/18_dbms_utility.mdx deleted file mode 100644 index 9bde984ee0a..00000000000 --- a/product_docs/docs/epas/12/epas_compat_bip_guide/03_built-in_packages/18_dbms_utility.mdx +++ /dev/null @@ -1,783 +0,0 @@ ---- -title: "DBMS_UTILITY" - -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-advanced-server/reference/database-compatibility-for-oracle-developers-built-in-package-guide/13/dbms_utility.html" ---- - -The `DBMS_UTILITY` package provides support for the following various utility programs: - -| 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. | -| `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. | -| `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_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. | - -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 | -| --------------------------- | ------------- | ----- | ----------------------------------- | -| `inv_error_on_restrictions` | `PLS_INTEGER` | `1` | Used by the `INVALIDATE` procedure. | -| `lname_array` | `TABLE` | | For lists of long names. | -| `uncl_array` | `TABLE` | | For lists of users and names. | - - - -## LNAME_ARRAY - -The `LNAME_ARRAY` is for storing lists of long names including fully-qualified names. - -```text -TYPE lname_array IS `TABLE OF VARCHAR2(4000) INDEX BY BINARY_INTEGER; -``` - - - -## UNCL_ARRAY - -The `UNCL_ARRAY` is for storing lists of users and names. - -```text -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. - -`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_PART_OBJECT` analyzes a single table. - -The syntax for the `ANALYZE` commands are: - -```text -ANALYZE_DATABASE( VARCHAR2 [, NUMBER - [, NUMBER [, VARCHAR2 ]]]) - -ANALYZE_SCHEMA( VARCHAR2, VARCHAR2 - [, NUMBER [, NUMBER - [, VARCHAR2 ]]]) - -ANALYZE_PART_OBJECT( VARCHAR2, VARCHAR2 - [, CHAR [, CHAR - [, VARCHAR2 [, ]]]]) -``` - -**Parameters** - `ANALYZE_DATABASE` and `ANALYZE_SCHEMA` - -`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. - -`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`. - - 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`. - - This argument is ignored, but is included for compatibility. - -`method_opt` - - Object types to be analyzed. Any combination of the following: - -``` -[ FOR TABLE ] - -[ FOR ALL [ INDEXED ] COLUMNS ] [ SIZE n ] - -[ FOR ALL INDEXES ] -``` - - This argument is ignored, but is included for compatibility. - -**Parameters** - `ANALYZE_PART_OBJECT` - -`schema` - - Name of the schema whose objects are to be analyzed. - -`object_name` - - Name of the partitioned object to be analyzed. - -`object_type` - - Type of object to be analyzed. Valid values are: `T` – table, `I` – index. - - This argument is ignored, but is included for compatibility. - -`command_type` - - Type of analyze functionality to perform. Valid values are: `E` - gather estimated statistics based 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. - - This argument is ignored, but is included for compatibility. - -`command_opt` - - For `command_type` `C` or `E`, can be any combination of: - -``` -[ FOR TABLE ] - -[ FOR ALL COLUMNS ] - -[ FOR ALL LOCAL INDEXES ] -``` - - For `command_type V`, can be `CASCADE` if `object_type` is `T`. - - This argument is ignored, but is included for compatibility. - -`sample_clause` - - If `command_type` is `E`, contains the following clause to specify the number of rows or percentage or rows on which to base the estimate. - - `SAMPLE n { ROWS | PERCENT }` - - This argument is ignored, but is included for compatibility. - -## CANONICALIZE - -The `CANONICALIZE` procedure performs the following operations on an input string: - -- If the string 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. - -```text -CANONICALIZE( VARCHAR2, OUT VARCHAR2, - BINARY_INTEGER) -``` - -**Parameters** - -`name` - - String to be canonicalized. - -`canon_name` - - The canonicalized string. - -`canon_len` - - Number of bytes in `name` to canonicalize starting from the first character. - -**Examples** - -The following procedure applies the `CANONICALIZE` procedure on its input parameter and displays the results. - -```text -CREATE OR REPLACE PROCEDURE canonicalize ( - p_name VARCHAR2, - p_length BINARY_INTEGER DEFAULT 30 -) -IS - v_canon VARCHAR2(100); -BEGIN - DBMS_UTILITY.CANONICALIZE(p_name,v_canon,p_length); - DBMS_OUTPUT.PUT_LINE('Canonicalized name ==>' || v_canon || '<=='); - DBMS_OUTPUT.PUT_LINE('Length: ' || LENGTH(v_canon)); -EXCEPTION - WHEN OTHERS THEN - DBMS_OUTPUT.PUT_LINE('SQLERRM: ' || SQLERRM); - DBMS_OUTPUT.PUT_LINE('SQLCODE: ' || SQLCODE); -END; - -EXEC canonicalize('Identifier') -Canonicalized name ==>IDENTIFIER<== -Length: 10 - -EXEC canonicalize('"Identifier"') -Canonicalized name ==>Identifier<== -Length: 10 - -EXEC canonicalize('"_+142%"') -Canonicalized name ==>_+142%<== -Length: 6 - -EXEC canonicalize('abc.def.ghi') -Canonicalized name ==>"ABC"."DEF"."GHI"<== -Length: 17 - -EXEC canonicalize('"abc.def.ghi"') -Canonicalized name ==>abc.def.ghi<== -Length: 11 - -EXEC canonicalize('"abc".def."ghi"') -Canonicalized name ==>"abc"."DEF"."ghi"<== -Length: 17 - -EXEC canonicalize('"abc.def".ghi') -Canonicalized name ==>"abc.def"."GHI"<== -Length: 15 -``` - -## COMMA_TO_TABLE - -The `COMMA_TO_TABLE` procedure converts a comma-delimited list of names into a table of names. Each entry in the list becomes a table entry. The names must be formatted as valid identifiers. - -```text -COMMA_TO_TABLE( VARCHAR2, OUT BINARY_INTEGER, - OUT { LNAME_ARRAY | UNCL_ARRAY }) -``` - -**Parameters** - -`list` - - Comma-delimited list of names. - -`tablen` - - Number of entries in `tab`. - -`tab` - - Table containing the individual names in `list`. - -`LNAME_ARRAY` - - A `DBMS_UTILITY LNAME_ARRAY` (as described in the [LNAME_ARRAY](#lname_array) section). - -`UNCL_ARRAY` - - A `DBMS_UTILITY UNCL_ARRAY` (as described in the [UNCL_ARRAY](#uncl_array) section). - -**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. - -```text -CREATE OR REPLACE PROCEDURE comma_to_table ( - p_list VARCHAR2 -) -IS - r_lname DBMS_UTILITY.LNAME_ARRAY; - v_length BINARY_INTEGER; -BEGIN - DBMS_UTILITY.COMMA_TO_TABLE(p_list,v_length,r_lname); - FOR i IN 1..v_length LOOP - DBMS_OUTPUT.PUT_LINE(r_lname(i)); - END LOOP; -END; - -EXEC comma_to_table('edb.dept, edb.emp, edb.jobhist') - -edb.dept -edb.emp -edb.jobhist -``` - -## DB_VERSION - -The `DB_VERSION` procedure returns the version number of the database. - -```text -DB_VERSION( OUT VARCHAR2, OUT VARCHAR2) -``` - -**Parameters** - -`version` - - Database version number. - -`compatibility` - - Compatibility setting of the database. (To be implementation-defined as to its meaning.) - -**Examples** - -The following anonymous block displays the database version information. - -```text -DECLARE - v_version VARCHAR2(150); - v_compat VARCHAR2(150); -BEGIN - DBMS_UTILITY.DB_VERSION(v_version,v_compat); - DBMS_OUTPUT.PUT_LINE('Version: ' || v_version); - DBMS_OUTPUT.PUT_LINE('Compatibility: ' || v_compat); -END; - -Version: EnterpriseDB 12.0.0 on i686-pc-linux-gnu, compiled by GCC gcc -(GCC) 4.1.2 20080704 (Red Hat 4.1.2-48), 32-bit -Compatibility: EnterpriseDB 12.0.0 on i686-pc-linux-gnu, compiled by GCC -gcc (GCC) 4.1.220080704 (Red Hat 4.1.2-48), 32-bit -``` - -## EXEC_DDL_STATEMENT - -The `EXEC_DDL_STATEMENT` provides the capability to execute a `DDL` command. - -```text -EXEC_DDL_STATEMENT( VARCHAR2) -``` - -**Parameters** - -`parse_string` - - The DDL command to be executed. - -**Examples** - -The following anonymous block creates the `job` table. - -```text -BEGIN - DBMS_UTILITY.EXEC_DDL_STATEMENT( - 'CREATE TABLE job (' || - 'jobno NUMBER(3),' || - 'jname VARCHAR2(9))' - ); -END; -``` - -If the `parse_string` does not include a valid DDL statement, Advanced Server returns the following 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, Advanced Server's behavior differs from Oracle's; Oracle accepts the invalid `parse_string` without complaint. - -## FORMAT_CALL_STACK - -The `FORMAT_CALL_STACK` function returns the formatted contents of the current call stack. - -```text -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. - -## GET_CPU_TIME - -The `GET_CPU_TIME` function returns the CPU time in hundredths of a second from some arbitrary point in time. - -```text - NUMBER GET_CPU_TIME -``` - -**Parameters** - -`cputime` - - Number of hundredths of a second of CPU time. - -**Examples** - -The following `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; - -get_cpu_time --------------- - 603 -``` - -## 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. - -```text -GET_DEPENDENCY( VARCHAR2, VARCHAR2, - VARCHAR2) -``` - -**Parameters** - -`type` - - The object type of `name`. Valid values are `INDEX, PACKAGE, PACKAGE BODY, SEQUENCE, TABLE, TRIGGER, TYPE` and `VIEW`. - -`schema` - - Name of the schema in which `name` exists. - -`name` - - Name of the object for which dependencies are to be obtained. - -**Examples** - -The following anonymous block finds dependencies on the `EMP` table. - -```text -BEGIN - DBMS_UTILITY.GET_DEPENDENCY('TABLE','public','EMP'); -END; - -DEPENDENCIES ON public.EMP ------------------------------------------------------------------- -*TABLE public.EMP() -* CONSTRAINT c public.emp() -* CONSTRAINT f public.emp() -* CONSTRAINT p public.emp() -* TYPE public.emp() -* CONSTRAINT c public.emp() -* CONSTRAINT f public.jobhist() -* VIEW .empname_view() -``` - -## GET_HASH_VALUE - -The `GET_HASH_VALUE` function provides the capability to compute a hash value for a given string. - -```text - NUMBER GET_HASH_VALUE( VARCHAR2, NUMBER, - NUMBER) -``` - -**Parameters** - -`name` - - The string for which a hash value is to be computed. - -`base` - - Starting value at which hash values are to be generated. - -`hash_size` - - The number of hash values for the desired hash table. - -`hash` - - The generated hash value. - -**Examples** - -The following anonymous block creates a table of hash values using the `ename` column of the `emp` table and then displays the key along with the hash value. The hash values start at 100 with a maximum of 1024 distinct values. - -```text -DECLARE - v_hash NUMBER; - TYPE hash_tab IS TABLE OF NUMBER INDEX BY VARCHAR2(10); - r_hash HASH_TAB; - CURSOR emp_cur IS SELECT ename FROM emp; -BEGIN - FOR r_emp IN emp_cur LOOP - r_hash(r_emp.ename) := - DBMS_UTILITY.GET_HASH_VALUE(r_emp.ename,100,1024); - END LOOP; - FOR r_emp IN emp_cur LOOP - DBMS_OUTPUT.PUT_LINE(RPAD(r_emp.ename,10) || ' ' || - r_hash(r_emp.ename)); - END LOOP; -END; - -SMITH 377 -ALLEN 740 -WARD 718 -JONES 131 -MARTIN 176 -BLAKE 568 -CLARK 621 -SCOTT 1097 -KING 235 -TURNER 850 -ADAMS 156 -JAMES 942 -FORD 775 -MILLER 148 -``` - -## GET_PARAMETER_VALUE - -The `GET_PARAMETER_VALUE` procedure provides the capability to retrieve database initialization parameter settings. - -```text - BINARY_INTEGER GET_PARAMETER_VALUE( VARCHAR2, - OUT INTEGER, OUT VARCHAR2) -``` - -**Parameters** - -`parnam` - - Name of the parameter whose value is to be returned. The parameters are listed in the `pg_settings` system view. - -`intval` - - Value of an integer parameter or the length of `strval`. - -`strval` - - Value of a string parameter. - -`status` - - Returns 0 if the parameter value is `INTEGER` or `BOOLEAN`. Returns 1 if the parameter value is a string. - -**Examples** - -The following anonymous block shows the values of two initialization parameters. - -```text -DECLARE - v_intval INTEGER; - v_strval VARCHAR2(80); -BEGIN - DBMS_UTILITY.GET_PARAMETER_VALUE('max_fsm_pages', v_intval, v_strval); - DBMS_OUTPUT.PUT_LINE('max_fsm_pages' || ': ' || v_intval); - DBMS_UTILITY.GET_PARAMETER_VALUE('client_encoding', v_intval, v_strval); - DBMS_OUTPUT.PUT_LINE('client_encoding' || ': ' || v_strval); -END; - -max_fsm_pages: 72625 -client_encoding: SQL_ASCII -``` - -## GET_TIME - -The `GET_TIME` function provides the capability to return the current time in hundredths of a second. - -```text -