Skip to content

Commit

Permalink
Merge pull request #6335 from EnterpriseDB/docs/edits_to_epas_pr6290
Browse files Browse the repository at this point in the history 
Edits to PAS: DBMS_XMLDOMDOC corrections #6290
  • Loading branch information
@gvasquezvargas
gvasquezvargas authored Dec 20, 2024
2 parents e16a822 + 321b419 commit 11c96f4
Show file tree
Hide file tree
Showing 19 changed files with 70 additions and 75 deletions.
2 changes: 1 addition & 1 deletion product_docs/docs/epas/17/epas_rel_notes/epas17_2_rel_notes.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ With the release of EPAS 17, the DRITA is being deprecated and will not be inclu
!!!

!!! Note
The `pgAgent` and `adminpack` packages are end of life from EPAS 17 and later.
The `pgAgent` and `adminpack` packages are end of life in EPAS 17 and later.
!!!

| Type | Description | Addresses                |
Expand Down
12 changes: 6 additions & 6 deletions ...rence/epas_compat_bip_guide/03_built-in_packages/18_dbms_xmldom/appendchild.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@
title: "APPENDCHILD"
---

The `APPENDCHILD` function adds the node at the end of the list of children of a particular node. It returns the newly added node and if the node is already present, it removes the existing node before adding new node.
The `APPENDCHILD` function adds the node at the end of the list of children of a particular node. It returns the newly added node and, if a node is already present, removes the existing node before adding the new node.

You can append more than one child to a document node. However, a node cannot belong to several documents.
You can append more than one child to a document node. However, a node can't belong to several documents.

When appending elements, you cannot add an element to itself. Additionally, if the same element is added twice, only the latest is considered.
When appending elements, you can't add an element to itself. Also, if the same element is added twice, only the latest is considered.

```
APPENDCHILD(n DOMNode, newChild IN DOMNode) RETURN DOMNode
Expand All @@ -16,15 +16,15 @@ APPENDCHILD(n DOMNode, newChild IN DOMNode) RETURN DOMNode

`n`

The `DOMNode` where the new node is to be added.
The `DOMNode` to add the new node to.

`newchild`

The child node to be added to the existing list of children of node n.
The child node to add to the existing list of children of node `n`.

## Examples

This example creates a new XML `DOMDocument` named `l_domdoc` and a new `DOMElement` named `l_department_element` with tag name `Departments`. It then appends the `DOMElement` as a child of the `DOMDocument`.
This example creates an XML `DOMDocument` named `l_domdoc` and a `DOMElement` named `l_department_element` with the tag name `Departments`. It then appends the `DOMElement` as a child of the `DOMDocument`.

```sql
DECLARE
Expand Down
6 changes: 3 additions & 3 deletions ...nce/epas_compat_bip_guide/03_built-in_packages/18_dbms_xmldom/createelement.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "CREATEELEMENT"
---

The `CREATEELEMENT` function creates and returns a DOMElement.
The `CREATEELEMENT` function creates and returns a `DOMElement`.

```
CREATEELEMENT( doc DOMDocument, tagname IN VARCHAR2) RETURN DOMElement
Expand All @@ -16,11 +16,11 @@ Any `DOMDocument`.

`tagname`

Tag name to be given to the new `DOMElement`.
Tag name to give to the new `DOMElement`.

## Examples

This example creates a new XML `DOMDocument` named `l_domdoc` and a new `DOMElement` named `l_department_element` with tag name `Departments`. It then appends the `DOMElement` as a child of the `DOMDocument`.
This example creates an XML `DOMDocument` named `l_domdoc` and a `DOMElement` named `l_department_element` with the tag name `Departments`. It then appends the `DOMElement` as a child of the `DOMDocument`.

```sql
DECLARE
Expand Down
4 changes: 2 additions & 2 deletions ...ce/epas_compat_bip_guide/03_built-in_packages/18_dbms_xmldom/createtextnode.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "CREATETEXTNODE"
---

The `CREATETEXTNODE` function creates and returns a DOMText node.
The `CREATETEXTNODE` function creates and returns a `DOMText` node.

```
CREATETEXTNODE( doc DOMDocument, data IN VARCHAR2) RETURN DOMText
Expand All @@ -20,7 +20,7 @@ Content provided for the `DOMText` node.

## Examples

This example creates a new XML `DOMDocument`, a `DOMElement` with tag name “Departments” and a text node with “Depts list” as its value. The `DOMElement` is appended as a child to the `DOMDocument`, and the text node as a child to the `DOMElement`.
This example creates an XML `DOMDocument`, a `DOMElement` with the tag name `Departments`, and a text node with `Depts list` as its value. The `DOMElement` is appended as a child to the `DOMDocument` and the text node as a child to the `DOMElement`.

```sql
DECLARE
Expand Down
6 changes: 3 additions & 3 deletions ...ence/epas_compat_bip_guide/03_built-in_packages/18_dbms_xmldom/freedocument.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "FREEDOCUMENT"
---

The `FREEDOCUMENT` procedure is used to free the `DOMDocument` object.
The `FREEDOCUMENT` procedure frees the `DOMDocument` object.

```
FREEDOCUMENT(doc IN DOMDocument)
Expand All @@ -12,12 +12,12 @@ FREEDOCUMENT(doc IN DOMDocument)

`doc`

The `DOMDocument` to be made free.
The `DOMDocument` to free.


## Examples

This example creates a new `DOMDocument`, which is not accessible after it has been freed.
This example creates a `DOMDocument` that's not accessible after it's free.

```sql
DECLARE
Expand Down
12 changes: 6 additions & 6 deletions ...ence/epas_compat_bip_guide/03_built-in_packages/18_dbms_xmldom/getattribute.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "GETATTRIBUTE"
---

The `GETATTRIBUTE` function returns the value of an attribute of an `DOMElement` by name.
The `GETATTRIBUTE` function returns the value of an attribute of a `DOMElement` by name.

```
GETATTRIBUTE(elem DOMElement, name IN VARCHAR2) RETURN VARCHAR2
Expand All @@ -14,21 +14,21 @@ GETATTRIBUTE(elem DOMElement, name IN VARCHAR2, ns IN VARCHAR2) RETURN VARCHAR2

`elem`

The `DOMElement` whose attribute value needs to be obtained.
The `DOMElement` whose attribute you want to obtain.

`name`

The attribute name whose attribute value needs to be obtained.
The attribute name whose attribute value you want to obtain.

`ns`

The namespace URI.

## Examples

This example creates a new `DOMDocument` named `l_domdoc`, and a `DOMElement` named `elem` with tag name “Departments”. It adds an attribute (`attr`) to the `DOMElement` with the value "value" and appends the `DOMElement` as a child of the `DOMDocument`.
This example creates a `DOMDocument` named `l_domdoc` and a `DOMElement` named `elem` with the tag name `Departments`. It adds an attribute `attr` to the `DOMElement` with the value `value` and appends the `DOMElement` as a child of the `DOMDocument`.

The `get` subprogram returns the value of the attribute `attr` of the "Departments" element.
The `get` subprogram returns the value of the attribute `attr` of the `Departments` element.


```sql
Expand All @@ -48,7 +48,7 @@ BEGIN
END;
```

This example defines a namespace named “example” and uses an XMLtype string to create an XML structure. `GETFIRSTCHILD` then returns a `DOMNode` that represents a `DOMElement`. Since `GETATTRIBUTE` expects a `DOMElement`, the `MAKEELEMENT` function converts a specified `DOMNode` into a `DOMElement` and returns it.
This example defines a namespace `example` and uses an XMLType string to create an XML structure. `GETFIRSTCHILD` then returns a `DOMNode` that represents a `DOMElement`. Since `GETATTRIBUTE` expects a `DOMElement`, the `MAKEELEMENT` function converts a specified `DOMNode` to a `DOMElement` and returns it.

```sql
DECLARE
Expand Down
4 changes: 2 additions & 2 deletions ...nce/epas_compat_bip_guide/03_built-in_packages/18_dbms_xmldom/getchildnodes.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@ GETCHILDNODES(n DOMNode) RETURN DOMNodeList

`n`

The `DOMNode` whose childnode list is to be retrieved.
The `DOMNode` whose child node list you want to retrieve.

## Examples

This example executes a function named `func1` that creates the XML structure `<Deptartments>Dept1</Deptartments>` and returns the root node which is a `DOMDocument`.
This example executes a function `func1` that creates the XML structure `<Departments>Dept1</Departments>` and returns the root node, which is a `DOMDocument`.

```sql
CREATE OR REPLACE FUNCTION func1 RETURN DBMS_XMLDOM.DOMNode IS
Expand Down
8 changes: 4 additions & 4 deletions ...nce/epas_compat_bip_guide/03_built-in_packages/18_dbms_xmldom/getfirstchild.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "GETFIRSTCHILD"
---

The `GETFIRSTCHILD` function retrieves the first child of the particular node. If there is no such node, then this function returns NULL.
The `GETFIRSTCHILD` function retrieves the first child of the particular node. If there's no such node, then this function returns NULL.

```
GETFIRSTCHILD(n DOMNode) RETURN DOMNode
Expand All @@ -12,11 +12,11 @@ GETFIRSTCHILD(n DOMNode) RETURN DOMNode

`n`

The `DOMNode` whose first child needs to be retrieved.
The `DOMNode` whose first child you want to retrieve.

## Examples

This example creates a new `DOMDocument` named `l_domdoc`, and turns it into a `DOMNode`. Then, it creates a `DOMElement` named `l_department_element` with the tag name “Departments” and appends this element as a child to the `DOMNode`. Finally, it outputs the tag name of the first (and in this example, the only) appended child.
This example creates a `DOMDocument` named `l_domdoc` and turns it into a `DOMNode`. Then, it creates a `DOMElement` named `l_department_element` with the tag name `Departments` and appends this element as a child to the `DOMNode`. It then outputs the tag name of the first (and in this example, the only) appended child.

```sql
DECLARE
Expand All @@ -28,7 +28,7 @@ DECLARE
BEGIN
l_domdoc := DBMS_XMLDOM.NEWDOMDOCUMENT();
l_root_node := DBMS_XMLDOM.MAKENODE(l_domdoc);
l_department_element := DBMS_XMLDOM.CREATEELEMENT(l_domdoc, 'Deptartments' );
l_department_element := DBMS_XMLDOM.CREATEELEMENT(l_domdoc, 'Departments' );
PERFORM DBMS_XMLDOM.APPENDCHILD(l_root_node,DBMS_XMLDOM.MAKENODE(l_department_element));
DBMS_OUTPUT.PUT_LINE(DBMS_XMLDOM.GETNODENAME(DBMS_XMLDOM.GETFIRSTCHILD(l_root_node)));
END;
Expand Down
6 changes: 3 additions & 3 deletions ...ference/epas_compat_bip_guide/03_built-in_packages/18_dbms_xmldom/getlength.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@ GETLENGTH(nl DOMNodeList) RETURN PLS_INTEGER

`nl`

The `DOMNodeList`
The `DOMNodeList`,

## Examples

This example executes a function named `func1` that creates the XML structure `<Deptartments>Dept1</Deptartments>` and returns the root node which is a `DOMDocument`.
This example executes a function `func1` that creates the XML structure `<Departments>Dept1</Departments>` and returns the root node, which is a `DOMDocument`.

```sql
CREATE OR REPLACE FUNCTION func1 RETURN DBMS_XMLDOM.DOMNode IS
Expand All @@ -29,7 +29,7 @@ CREATE OR REPLACE FUNCTION func1 RETURN DBMS_XMLDOM.DOMNode IS
BEGIN
l_domdoc := DBMS_XMLDOM.NEWDOMDOCUMENT;
l_root_node := DBMS_XMLDOM.MAKENODE(l_domdoc);
l_department_element := DBMS_XMLDOM.CREATEELEMENT(l_domdoc, 'Deptartments' );
l_department_element := DBMS_XMLDOM.CREATEELEMENT(l_domdoc, 'Departments' );
l_departments_node := DBMS_XMLDOM.APPENDCHILD(l_root_node,DBMS_XMLDOM.MAKENODE(l_department_element));
l_name_text := DBMS_XMLDOM.CREATETEXTNODE(l_domdoc, 'Dept1' );
PERFORM DBMS_XMLDOM.APPENDCHILD(l_departments_node,DBMS_XMLDOM.MAKENODE(l_name_text));
Expand Down
6 changes: 3 additions & 3 deletions ...rence/epas_compat_bip_guide/03_built-in_packages/18_dbms_xmldom/getnodename.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "GETNODENAME"
---

The `GETNODENAME` function provides the name of the node depending on its type.
The `GETNODENAME` function provides the name of the node or a placeholder value that reflects the node type.

```
GETNODENAME(n DOMNODE) RETURN VARCHAR2
Expand All @@ -12,11 +12,11 @@ GETNODENAME(n DOMNODE) RETURN VARCHAR2

`n`

`DOMNode` value to be provided.
`DOMNode` value you want to obtain.

## Examples

This example creates a new `DOMDocument` named `l_domdoc`, and a `DOMElement` named `elem` with tag name “Departments”. Finally, it outputs the tag name.
This example creates a `DOMDocument` named `l_domdoc` and a `DOMElement` named `elem` with the tag name `Departments`. It then outputs the tag name.

```sql
DECLARE
Expand Down
7 changes: 3 additions & 4 deletions ...ence/epas_compat_bip_guide/03_built-in_packages/18_dbms_xmldom/getnodevalue.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "GETNODEVALUE"
---

The `GETNODEVALUE` function provides the value of the node depending on its type.
The `GETNODEVALUE` function provides the value of the node.

```
GETNODEVALUE(n DOMNode) RETURN VARCHAR2
Expand All @@ -12,12 +12,11 @@ GETNODEVALUE(n DOMNode) RETURN VARCHAR2

`n`

`DOMNode` to be provided.

`DOMNode` to provide.

## Examples

This example creates a new `DOMDocument` named `l_domdoc`, and a text node with tag name “Depts list”. Finally, it outputs the text node value in XML it set before.
This example creates a `DOMDocument` named `l_domdoc` and a text node with the tag name `Depts list`. It then outputs the text node value it set before in XML.

```sql
DECLARE
Expand Down
4 changes: 2 additions & 2 deletions ...erence/epas_compat_bip_guide/03_built-in_packages/18_dbms_xmldom/getxmltype.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ The `DOMDocument`.

## Examples

This example creates a new XML `DOMDocument`, sets the version to 1.0, and converts it into an XMLType object.
This example creates an XML `DOMDocument`, sets the version to 1.0, and converts it to an XMLType object:

```sql
DECLARE
Expand All @@ -32,7 +32,7 @@ BEGIN
END;
```

This example takes an xml string as input, converts it into a `DOMDocument`, and adds a new element to the document. It then converts the `DOMDocument` back to `XMLType`.
This example takes an XML string as input, converts it to a `DOMDocument`, and adds a new element to the document. It then converts the `DOMDocument` back to XMLType.

```sql
DECLARE
Expand Down
17 changes: 7 additions & 10 deletions ...y_reference/epas_compat_bip_guide/03_built-in_packages/18_dbms_xmldom/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,11 @@ navigation:

The `DBMS_XMLDOM` package implements Document Object Model (DOM) and is used to create DOM documents from scratch or from an XML document.

EDB Postgres Advanced Server's implementation of `DBMS_XMLDOM` is a partial implementation when compared to Oracle's version. Only the functions and procedures listed in this table are supported.
EDB Postgres Advanced Server's implementation of `DBMS_XMLDOM` is a partial implementation when compared to Oracle's version. Only the functions and procedures listed in the tables that follow are supported.

## Types

The `DBMS_XMLDOM` package implements the following types:
The `DBMS_XMLDOM` package implements the following types.

| Type name | Description |
|---------------|-------------------------------------------|
Expand All @@ -38,12 +38,12 @@ The `DBMS_XMLDOM` package implements the following types:

## Subprograms

This table lists the subprograms available with `DBMS_XMLDOM` package:
This table lists the subprograms available with the `DBMS_XMLDOM` package.

| Subprogram | Type | Return type | Description |
|------------------|-----------|-------------|--------------------------------------------------------------------------------|
| `APPENDCHILD` | Function | DOMNode | Appends a new child to the node. |
| `CREATEELEMENT` | Function | DOMElement | Creates a new element. |
| `CREATEELEMENT` | Function | DOMElement | Creates an element. |
| `CREATETEXTNODE` | Function | DOMText | Creates a text node. |
| `FREEDOCUMENT` | Procedure | N/A | Frees the resources associated with the DOMDocument. |
| `GETATTRIBUTE` | Function | DOMElement | Retrieves the attribute value given to an attribute name and returns VARCHAR2. |
Expand All @@ -52,13 +52,10 @@ This table lists the subprograms available with `DBMS_XMLDOM` package:
| `GETLENGTH` | Function | PLS_INTEGER | Retrieves the number of items in the given DOMNodeList. |
| `GETNODENAME` | Function | VARCHAR2 | Retrieves the name of the node. |
| `GETNODEVALUE` | Function | VARCHAR2 | Retrieves the value of the node. |
| `GETXMLTYPE` | Function | XMLTYPE | Converts DOMDocument to xmltype and returns it. |
| `ITEM` | Function | DOMNode | Retrieves the item from the given the index in the NODELIST. |
| `GETXMLTYPE` | Function | XMLTYPE | Converts DOMDocument to XMLType and returns it. |
| `ITEM` | Function | DOMNode | Retrieves the item from the given index in the NODELIST. |
| `MAKEELEMENT` | Function | DOMElement | Casts the node to a DOMElement. |
| `MAKENODE` | Function | DOMNode | Casts the attribute to a node. |
| `NEWDOMDOCUMENT` | Function | DOMDocument | Creates a new document. |
| `NEWDOMDOCUMENT` | Function | DOMDocument | Creates a document. |
| `SETATTRIBUTE` | Procedure | N/A | Sets the attribute value of a DOMElement. |
| `SETVERSION` | Procedure | N/A | Sets the version of the document. |



12 changes: 6 additions & 6 deletions ...ty_reference/epas_compat_bip_guide/03_built-in_packages/18_dbms_xmldom/item.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "ITEM"
---

The `ITEM` function returns the item in the collection corresponding to the `idx` parameter. If the value of `idx` parameter is greater than or equal to the number of nodes in the list, then function returns a `NULL`.
The `ITEM` function returns the item in the collection corresponding to the `idx` parameter. If the value of the `idx` parameter is greater than or equal to the number of nodes in the list, then the function returns `NULL`.

```
ITEM(nl DOMNodeList, idx IN PLS_INTEGER) RETURN DOMNode
Expand All @@ -12,15 +12,15 @@ ITEM(nl DOMNodeList, idx IN PLS_INTEGER) RETURN DOMNode

`nl`

The DOMNodeList, the number of nodes in the list.
The `DOMNodeList`, that is, the number of nodes in the list.

`idx`

The index in the NODELIST that is used to retrieve the item.
The index in the NODELIST that's used to retrieve the item.

## Examples

This example uses a function named `func1` that creates an XML structure `<Deptartments>Dept1</Deptartments>` and returns the document node that is the root node.
This example uses a function `func1` that creates an XML structure `<Departments>Dept1</Departments>` and returns the document node that's the root node:

```sql
CREATE OR REPLACE FUNCTION func1 RETURN DBMS_XMLDOM.DOMNode IS
Expand All @@ -33,15 +33,15 @@ CREATE OR REPLACE FUNCTION func1 RETURN DBMS_XMLDOM.DOMNode IS
BEGIN
l_domdoc := DBMS_XMLDOM.NEWDOMDOCUMENT;
l_root_node := DBMS_XMLDOM.MAKENODE(l_domdoc);
l_department_element := DBMS_XMLDOM.CREATEELEMENT(l_domdoc, 'Deptartments' );
l_department_element := DBMS_XMLDOM.CREATEELEMENT(l_domdoc, 'Departments' );
l_departments_node := DBMS_XMLDOM.APPENDCHILD(l_root_node,DBMS_XMLDOM.MAKENODE(l_department_element));
l_name_text := DBMS_XMLDOM.CREATETEXTNODE(l_domdoc, 'Dept1' );
PERFORM DBMS_XMLDOM.APPENDCHILD(l_departments_node,DBMS_XMLDOM.MAKENODE(l_name_text));
return l_root_node;
END;
```

The document node is passed to `GETCHILDNODES` using the function `func1`, which returns the list of children of the document node. The list contains the `DOMElement` representing "Departments". The call to item returns this element as a `DOMNode`, which is then picked by `GETNODENAME` to fetch the tag name of this `DOMElement`.
The document node is passed to `GETCHILDNODES` using the function `func1`, which returns the list of children of the document node. The list contains the `DOMElement` representing `Departments`. The call to the item returns this element as a `DOMNode`, which is then picked by `GETNODENAME` to fetch the tag name of this `DOMElement`.

```sql
DECLARE
Expand Down
Loading

0 comments on commit 11c96f4

Please sign in to comment.