From a33f6adaa6f7f91129b2f6ed2230494e137c67b2 Mon Sep 17 00:00:00 2001 From: gvasquezvargas Date: Mon, 11 Nov 2024 17:45:12 +0100 Subject: [PATCH 1/5] dotNET: added page for nested table support --- .../docs/net_connector/8.0.5.1/index.mdx | 20 ++ .../8.0.5.1/using_nested_table_types.mdx | 176 ++++++++++++++++++ 2 files changed, 196 insertions(+) create mode 100644 product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx diff --git a/product_docs/docs/net_connector/8.0.5.1/index.mdx b/product_docs/docs/net_connector/8.0.5.1/index.mdx index 54903390cca..a0389a0e005 100644 --- a/product_docs/docs/net_connector/8.0.5.1/index.mdx +++ b/product_docs/docs/net_connector/8.0.5.1/index.mdx @@ -2,6 +2,26 @@ title: "EDB .NET Connector" directoryDefaults: description: "EDB .NET Connector version 8.0.2.1 documentation and release notes." +navigation: + - 01_release_notes + - 02_requirements_overview + - 03_the_advanced_server_net_connector_overview + - 04_installing_and_configuring_the_net_connector + - 05_using_the_net_connector + - 06_opening_a_database_connection + - 07_retrieving_database_records + - 08_parameterized_queries + - 09_inserting_records_in_a_database + - 10_deleting_records_in_a_database + - 11_using_spl_stored_procedures_in_your_net_application + - 12_using_advanced_queueing + - 13_using_a_ref_cursor_in_a_net_application + - 14_using_plugins + - 15_using_object_types + - using_nested_table_types + - 16_scram_compatibility + - 17_advanced_server_net_connector_logging + - 18_api_reference --- The EDB .NET Connector distributed with EDB Postgres Advanced Server provides connectivity between a .NET client application and an EDB Postgres Advanced Server database server. You can: diff --git a/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx b/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx new file mode 100644 index 00000000000..29baf450d29 --- /dev/null +++ b/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx @@ -0,0 +1,176 @@ +--- +title: "Using nested tables" + +--- + +EDB Postgres Advanced Server supports nested table collection types created with `CREATE TYPE ... AS TABLE OF` statements. The EDB .NET Connector supports output parameters declared as nested tables out of the box, whether they are free-standing types or declared inside packages. + +## Nested table types mapping + +Nested table types are mapped to `List`s in C#, as it is preferred over `ArrayList`. These lists contain as many elements as the nested table type’s rows. The nested table items are translated to be compatible with the C# application using the following rules: + +- The connector resolves all elements of a nested table into `List` elements of a single object type, making the element types are consistent in C#. + +- If the nested type `IS TABLE OF` a domain type (int, varchar, decimal, etc.): all the elements will be their C# counterpart according to the [Supported Types and their Mappings](https://www.npgsql.org/doc/types/basic.html#read-mappings). + +- If the nested type `IS TABLE OF` a record or composite type **not mapped** to a C# class: all elements will be a `List` containing as many elements as the record or composite fields, with proper type translation. + +- If the nested type `IS TABLE OF` a record or composite type **mapped** to a C# class (for example, `MyComposite`): all elements will be `MyComposite` instances. + +## Example: Retrieving nested table output parameter + +This program: + +- Creates a package with a nested `emp_tbl_typ` table type of `emp_rec_typ`. This packages has a stored procedure that fills the nested table output parameter. + +- Maps the nested table type to a C# class via `MapComposite<>`. + +- Executes and displays the results. + +Create an empty console program and paste the following code. + +!!!note + Always provide type names in lower case. +!!! + +```text +internal static class Program +{ + const string ConnectionString = "your_connection_string"; + + // Composite type, will be mapped to the nested table type + // This will work if field types are convertible from database types + public class Employee + { + [PgName("empno")] + public decimal Number; + [PgName("ename")] + public string? Name; + } + + public static void Sample_NestedTableTypes(string ConnectionString) + { + var dataSourceBuilder = new EDBDataSourceBuilder(ConnectionString); + dataSourceBuilder.MapComposite("pkgextendtest.emp_rec_typ"); + + using (var dataSource = dataSourceBuilder.Build()) + { + using (var connection = dataSource.OpenConnection()) + { + + try + { + CreatePackage(connection); + + var commandText = "pkgExtendTest.nestedTableExtendTest"; + var cstmt = new EDBCommand(commandText, connection); + cstmt.CommandType = CommandType.StoredProcedure; + + var tableOfParam = cstmt.Parameters.Add(new EDBParameter() + { + Direction = ParameterDirection.Output, + DataTypeName = "pkgextendtest.emp_tbl_typ" + }); + + cstmt.Prepare(); + cstmt.ExecuteNonQuery(); + + List? employees = tableOfParam.Value as List; + if (employees == null) + { + Console.WriteLine($"No employee found"); + return; + } + + foreach (var employeeRecord in employees) + { + var employee = employeeRecord as Employee; + if (employee != null) + { + Console.WriteLine($"Employee {employee.Number}: {employee.Name}"); + } + } + } + catch (Exception ex) + { + Console.WriteLine($"Error: {ex.Message}"); + } + finally + { + Cleanup(connection); + } + } + } + } + + // helper methods to create package and cleaning up + static void CreatePackage(EDBConnection connection) + { + var createPackage = +" CREATE OR REPLACE PACKAGE pkgExtendTest IS \n" + +" TYPE emp_rec_typ IS RECORD ( \n" + +" empno NUMBER(4), \n" + +" ename VARCHAR2(10) \n" + +" ); \n" + +" TYPE emp_tbl_typ IS TABLE OF emp_rec_typ; \n" + +" PROCEDURE nestedTableExtendTest(emp_tbl OUT emp_tbl_typ); \n" + +" END pkgExtendTest; \n"; + using (var com = new EDBCommand(createPackage, connection) { CommandType = CommandType.Text }) + { + com.ExecuteNonQuery(); + } + + var createPackageBody = +" CREATE OR REPLACE PACKAGE BODY pkgExtendTest IS \n" + +" PROCEDURE nestedTableExtendTest(emp_tbl OUT emp_tbl_typ) IS \n" + +" DECLARE \n" + +" CURSOR emp_cur IS SELECT empno, ename FROM emp WHERE ROWNUM <= 10 order by empno; \n" + +" i INTEGER := 0; \n" + +" BEGIN \n" + +" emp_tbl := emp_tbl_typ(); \n" + +" FOR r_emp IN emp_cur LOOP \n" + +" i := i + 1; \n" + +" emp_tbl.EXTEND; \n" + +" emp_tbl(i) := r_emp; \n" + +" END LOOP; \n" + +" END nestedTableExtendTest; \n" + +" END pkgExtendTest; \n"; + using (var com = new EDBCommand(createPackageBody, connection) { CommandType = CommandType.Text }) + { + com.ExecuteNonQuery(); + } + + connection.ReloadTypes(); + } + + static void Cleanup(EDBConnection connection) + { + var dropPackageBody = "DROP PACKAGE BODY pkgExtendTest"; + var dropPackage = "DROP PACKAGE pkgExtendTest"; + + using (var com = new EDBCommand(dropPackageBody, connection) { CommandType = CommandType.Text }) + { + com.ExecuteNonQuery(); + } + using (var com = new EDBCommand(dropPackage, connection) { CommandType = CommandType.Text }) + { + com.ExecuteNonQuery(); + } + } +} +``` + +The output should look like this: + +```text +Employee 7499: ALLEN +Employee 7521: WARD +Employee 7566: JONES +Employee 7654: MARTIN +Employee 7698: BLAKE +Employee 7782: CLARK +Employee 7788: SCOTT +Employee 7839: KING +Employee 7844: TURNER +Employee 7876: ADAMS +``` \ No newline at end of file From 12754f13668548347d0791351f9cb5f70d9a97aa Mon Sep 17 00:00:00 2001 From: gvasquezvargas Date: Tue, 12 Nov 2024 14:34:35 +0100 Subject: [PATCH 2/5] Corrected typos. --- .../8.0.5.1/using_nested_table_types.mdx | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx b/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx index 29baf450d29..4e4f10b46e5 100644 --- a/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx +++ b/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx @@ -9,30 +9,32 @@ EDB Postgres Advanced Server supports nested table collection types created with Nested table types are mapped to `List`s in C#, as it is preferred over `ArrayList`. These lists contain as many elements as the nested table type’s rows. The nested table items are translated to be compatible with the C# application using the following rules: -- The connector resolves all elements of a nested table into `List` elements of a single object type, making the element types are consistent in C#. +- The connector resolves all elements of a nested table into `List` elements of a single object type, making the element types consistent in C#. -- If the nested type `IS TABLE OF` a domain type (int, varchar, decimal, etc.): all the elements will be their C# counterpart according to the [Supported Types and their Mappings](https://www.npgsql.org/doc/types/basic.html#read-mappings). +- If the nested type `IS TABLE OF` a domain type (int, varchar, decimal, etc.), all the elements will be their C# counterpart according to the [Supported Types and their Mappings](https://www.npgsql.org/doc/types/basic.html#read-mappings). -- If the nested type `IS TABLE OF` a record or composite type **not mapped** to a C# class: all elements will be a `List` containing as many elements as the record or composite fields, with proper type translation. +- If the nested type `IS TABLE OF` a record or composite type **not mapped** to a C# class, all elements will be a `List` containing as many elements as the record or composite fields, with proper type translation. -- If the nested type `IS TABLE OF` a record or composite type **mapped** to a C# class (for example, `MyComposite`): all elements will be `MyComposite` instances. +- If the nested type `IS TABLE OF` a record or composite type **mapped** to a C# class (for example, `MyComposite`), all elements will be `MyComposite` instances. ## Example: Retrieving nested table output parameter This program: -- Creates a package with a nested `emp_tbl_typ` table type of `emp_rec_typ`. This packages has a stored procedure that fills the nested table output parameter. +- Creates a package with a nested `emp_tbl_typ` table type of `emp_rec_typ`. This package has a stored procedure that fills the nested table output parameter. - Maps the nested table type to a C# class via `MapComposite<>`. - Executes and displays the results. -Create an empty console program and paste the following code. - !!!note - Always provide type names in lower case. + Always provide type names in lowercase. !!! +### Program example + +Create an empty console program and paste the following code. + ```text internal static class Program { @@ -173,4 +175,4 @@ Employee 7788: SCOTT Employee 7839: KING Employee 7844: TURNER Employee 7876: ADAMS -``` \ No newline at end of file +``` From e179fdc53a46979f20aaa36b4baaaebf413662f5 Mon Sep 17 00:00:00 2001 From: gvasquezvargas Date: Tue, 12 Nov 2024 16:47:55 +0100 Subject: [PATCH 3/5] Implemented Feedback from Xavier --- product_docs/docs/net_connector/8.0.5.1/index.mdx | 2 +- .../docs/net_connector/8.0.5.1/using_nested_table_types.mdx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/product_docs/docs/net_connector/8.0.5.1/index.mdx b/product_docs/docs/net_connector/8.0.5.1/index.mdx index a0389a0e005..01dd6268d09 100644 --- a/product_docs/docs/net_connector/8.0.5.1/index.mdx +++ b/product_docs/docs/net_connector/8.0.5.1/index.mdx @@ -1,7 +1,7 @@ --- title: "EDB .NET Connector" directoryDefaults: - description: "EDB .NET Connector version 8.0.2.1 documentation and release notes." + description: "EDB .NET Connector version 8.0.5.1 documentation and release notes." navigation: - 01_release_notes - 02_requirements_overview diff --git a/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx b/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx index 4e4f10b46e5..ba65f65d7c4 100644 --- a/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx +++ b/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx @@ -13,7 +13,7 @@ Nested table types are mapped to `List`s in C#, as it is preferred over - If the nested type `IS TABLE OF` a domain type (int, varchar, decimal, etc.), all the elements will be their C# counterpart according to the [Supported Types and their Mappings](https://www.npgsql.org/doc/types/basic.html#read-mappings). -- If the nested type `IS TABLE OF` a record or composite type **not mapped** to a C# class, all elements will be a `List` containing as many elements as the record or composite fields, with proper type translation. +- If the nested type `IS TABLE OF` a record or composite type **not mapped** to a C# class, all elements become a nested `List` containing as many elements as the record or composite fields, with proper type translation. - If the nested type `IS TABLE OF` a record or composite type **mapped** to a C# class (for example, `MyComposite`), all elements will be `MyComposite` instances. @@ -35,7 +35,7 @@ This program: Create an empty console program and paste the following code. -```text +```csharp internal static class Program { const string ConnectionString = "your_connection_string"; From d5d004387b9797a6d6f4f35b4a614ed76308d65d Mon Sep 17 00:00:00 2001 From: gvasquezvargas Date: Mon, 18 Nov 2024 12:44:47 +0100 Subject: [PATCH 4/5] Improved bullet point on nested table resolution to C# and used temrinology when appropriate --- .../net_connector/8.0.5.1/using_nested_table_types.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx b/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx index ba65f65d7c4..b44dee0d6ba 100644 --- a/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx +++ b/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx @@ -9,13 +9,13 @@ EDB Postgres Advanced Server supports nested table collection types created with Nested table types are mapped to `List`s in C#, as it is preferred over `ArrayList`. These lists contain as many elements as the nested table type’s rows. The nested table items are translated to be compatible with the C# application using the following rules: -- The connector resolves all elements of a nested table into `List` elements of a single object type, making the element types consistent in C#. +- The connector resolves all rows of a nested table into a `List` in C# while maintaining and converting each column's underlying type. For example, a `[text1, text2, num1]` row will be resolved as a `[string, string, decimal]` item in the list. -- If the nested type `IS TABLE OF` a domain type (int, varchar, decimal, etc.), all the elements will be their C# counterpart according to the [Supported Types and their Mappings](https://www.npgsql.org/doc/types/basic.html#read-mappings). +- If the nested type `IS TABLE OF` a domain type (int, varchar, decimal, etc.), all the rows will be their C# counterpart according to the [Supported Types and their Mappings](https://www.npgsql.org/doc/types/basic.html#read-mappings). -- If the nested type `IS TABLE OF` a record or composite type **not mapped** to a C# class, all elements become a nested `List` containing as many elements as the record or composite fields, with proper type translation. +- If the nested type `IS TABLE OF` a record or composite type **not mapped** to a C# class, all rows become a nested List containing as many elements as the record or composite fields, with proper type translation. -- If the nested type `IS TABLE OF` a record or composite type **mapped** to a C# class (for example, `MyComposite`), all elements will be `MyComposite` instances. +- If the nested type `IS TABLE OF` a record or composite type **mapped** to a C# class (for example, `MyComposite`), all rows will be `MyComposite` instances. ## Example: Retrieving nested table output parameter From 230789a133f33a177d10dfa6229504ba81b2edc3 Mon Sep 17 00:00:00 2001 From: gvasquezvargas Date: Tue, 19 Nov 2024 09:22:34 +0100 Subject: [PATCH 5/5] Implementing feedback from Nidhi Co-authored-by: nidhibhammar <59045594+nidhibhammar@users.noreply.github.com> --- .../docs/net_connector/8.0.5.1/using_nested_table_types.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx b/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx index b44dee0d6ba..4bc1f1a348b 100644 --- a/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx +++ b/product_docs/docs/net_connector/8.0.5.1/using_nested_table_types.mdx @@ -3,13 +3,13 @@ title: "Using nested tables" --- -EDB Postgres Advanced Server supports nested table collection types created with `CREATE TYPE ... AS TABLE OF` statements. The EDB .NET Connector supports output parameters declared as nested tables out of the box, whether they are free-standing types or declared inside packages. +EDB Postgres Advanced Server supports nested table collection types created with `CREATE TYPE ... AS TABLE OF` statements. The EDB .NET Connector supports output parameters declared as nested tables out of the box, whether free-standing types or declared inside packages. ## Nested table types mapping -Nested table types are mapped to `List`s in C#, as it is preferred over `ArrayList`. These lists contain as many elements as the nested table type’s rows. The nested table items are translated to be compatible with the C# application using the following rules: +Nested table types are mapped to `List`s in C#, as it is preferred over `ArrayList`. These lists contain as many elements as the nested table type's rows. The nested table items are translated to be compatible with the C# application using the following rules: -- The connector resolves all rows of a nested table into a `List` in C# while maintaining and converting each column's underlying type. For example, a `[text1, text2, num1]` row will be resolved as a `[string, string, decimal]` item in the list. +- The connector resolves all nested table rows into a `List` in C# while maintaining and converting each column's underlying type. For example, a `[text1, text2, num1]` row will be resolved as a `[string, string, decimal]` item in the list. - If the nested type `IS TABLE OF` a domain type (int, varchar, decimal, etc.), all the rows will be their C# counterpart according to the [Supported Types and their Mappings](https://www.npgsql.org/doc/types/basic.html#read-mappings).