# RXS_OpenDom()

This subprocedure initializes DOM parsing for a specified chunk of XML.

## Subprocedure Prototype

| Field | Description |
|---|---|
| `     D RXS_OpenDom     PR                  Extproc('RXS_OpenDom') Opdesc      D                                     Like(RXS_ParseDOMDS_t)` | Returns an RXS_ParseDOMDS_t which contains information and pointers used by subsequent DOM parsing APIs. |
| `     D  pXML                               Like(RXS_Var16Mv_t) Const      D                                     Options(*Omit:*Varsize)` | Chunk of XML to be used for subsequent DOM operations. |
| `     D  pDS                                LikeDS(RXS_OpenDomDS_t)      D                                     Options(*Nopass:*Varsize)` | Holds RXS_OpenDomDS_t used to set up initial DOM parsing options. |


## Example Code

### Ex. 1: Begin DOM Parse on Character Field
```rpgle
**FREE
// This example demonstrates starting a DOM parsing session by using
//  RXS_OpenDom and then performing additional queries on the RXS_ParseDomDS_t
//  datastructure it returned. It's important to call RXS_CloseDom once DOM
//  parsing has been completed to free memory used by the DOM parser.

Ctl-Opt ActGrp(*New) BndDir('RXSBND');

/COPY QRPGLECPY,RXSCB

Dcl-Ds RootDomDS LikeDS(RXS_ParseDomDS_t);
Dcl-Ds BookDomDS LikeDS(RXS_ParseDomDS_t);
Dcl-S XPath Like(RXS_Var8Kv_t);
Dcl-S Data Like(RXS_Var1Kv_t);

Dcl-S x Uns(10);

Dcl-S gXML Like(RXS_Var64Kv_t);

gXML = '<?xml version="1.0" encoding="UTF-8"?>'
     + '<bookstore xmlns:test="testnamespace">'
     + '<book category="children">'
     + '<title lang="en"><![CDATA[Charlotte''s Web]]></title>'
     + '<author>E. B. White</author>'
     + '<year>1952</year>'
     + '<price>5.99</price>'
     + '<review><text>What a great book!</text></review>'
     + '<review><text>Highly recommended.</text></review>'
     + '</book>'
     + '<book category="cooking">'
     + '<title lang="en">Everyday Italian</title>'
     + '<author>Giada De Laurentiis</author>'
     + '<year>2005</year>'
     + '<price>30.00</price>'
     + '</book>'
     + '</bookstore>';

RXS_ResetDS( RootDomDS : RXS_DS_TYPE_PARSEDOM );
RootDomDS = RXS_OpenDom( gXML );

XPath = RXS_XPath( '/*:bookstore/*:book' );
RXS_ResetDS( BookDomDS : RXS_DS_TYPE_PARSEDOM );
BookDomDS = RXS_ParseDomToDom( XPath : RootDomDS );

for x = 1 to BookDomDS.NodeCount;
  XPath = RXS_XPath( '*:book[%u]/*:title' : x );
  Data = RXS_ParseDomToText( XPath : BookDomDS );
  RXS_JobLog( 'Title: %s' : Data );
endfor;

RXS_CloseDom( RootDomDS );

return;
```

### Ex. 2: Begin DOM Parse on IFS STMF
```rpgle
**FREE
// This example demonstrates starting a DOM parsing session by using
//  RXS_OpenDom to parse an XML file stored in an IFS STMF, and then performing
//  additional queries on the RXS_ParseDomDS_t datastructure it returned. It's
//  important to call RXS_CloseDom once DOM parsing has been completed to free
//  memory used by the DOM parser.

Ctl-Opt ActGrp(*New) BndDir('RXSBND');

/COPY QRPGLECPY,RXSCB

Dcl-Ds RootDomDS LikeDS(RXS_ParseDomDS_t);
Dcl-Ds BookDomDS LikeDS(RXS_ParseDomDS_t);
Dcl-S XPath Like(RXS_Var8Kv_t);
Dcl-S Data Like(RXS_Var1Kv_t);

Dcl-S x Uns(10);

RXS_ResetDS( RootDomDS : RXS_DS_TYPE_PARSEDOM );
RXS_ResetDS( OpenDomDS : RXS_DS_TYPE_OPENDOM );

OpenDomDS.Stmf = '/tmp/bookstore.xml';
// For this example, the IFS file /tmp/bookstore.xml contains
//  XML that looks like this:

// <?xml version="1.0" encoding="UTF-8"?>
// <bookstore xmlns:test="testnamespace">
// <book category="children">
// <title lang="en"><![CDATA[Charlotte's Web]]></title>
// <author>E. B. White</author>
// <year>1952</year>
// <price>5.99</price>
// <review><text>What a great book!</text></review>
// <review><text>Highly recommended.</text></review>
// </book>
// <book category="cooking">
// <title lang="en">Everyday Italian</title>
// <author>Giada De Laurentiis</author>
// <year>2005</year>
// <price>30.00</price>
// </book>
// </bookstore>

RootDomDS = RXS_OpenDom( *Omit : OpenDomDS );

XPath = RXS_XPath( '/*:bookstore/*:book' );
RXS_ResetDS( BookDomDS : RXS_DS_TYPE_PARSEDOM );
BookDomDS = RXS_ParseDomToDom( XPath : RootDomDS );

for x = 1 to BookDomDS.NodeCount;
  XPath = RXS_XPath( '*:book[%u]/*:title' : x );
  Data = RXS_ParseDomToText( XPath : BookDomDS );
  RXS_JobLog( 'Title: %s' : Data );
endfor;

RXS_CloseDom( RootDomDS );

return;
```

## Data Structures

### RXS_OpenDomDS_t

| Field | Description |
|---|---|
| `     D RXS_OpenDomDS_t...      D                 DS                  Qualified Template Inz` |  |
| `     D   ReturnedErrorInfo...      D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz` |  |
| `     D   DataStructureType...      D                                5I 0 Inz(RXS_DS_TYPE_OPENDOM)` | **Internal use only** |
| `     D   OnErrorMessageType...      D                                5I 0` |  |
| `     D   InputCcsid...      D                               10I 0` | Specifies the CCSID of the XML being parsed. |
| `     D   OutputCcsid...      D                               10I 0` | Specifies the CCSID the parsed data will be converted to. |
| `     D   Stmf...      D                                     Like(RXS_Var1Kv_t)` | Specifies an IFS path to an XML file to parse instead of the Input parm. |


### RXS_ParseDomDS_t

| Field | Description |
|---|---|
| `     D RXS_ParseDomDS_t...      D                 DS                  Qualified Template Inz` |  |
| `     D   ReturnedErrorInfo...      D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz` |  |
| `     D   OnErrorMessageType...      D                               10I 0` |  |
| `     D   InputCcsid...      D                               10I 0` | Specifies the CCSID of the XML being parsed. |
| `     D   OutputCcsid...      D                               10I 0` | Specifies the CCSID the parsed data will be converted to. |
| `     D   Stmf...      D                                     Like(RXS_Var1Kv_t)` | Specifies an IFS path to an XML file to parse instead of the Input parm. |
| `     D   NodeCount                   10U 0` | Contains the current count of XML nodes tracked by this data structure. |
| `     D   NodeType                    10I 0` |  |
| `     D   xmlPtr                        *` | **Internal use only** |
| `     D   docPtr                        *` | **Internal use only** |
| `     D   contextPtr                    *` | **Internal use only** |
| `     D   dictPtr                       *` | **Internal use only** |
| `     D   currentPtr                    *` | **Internal use only** |
| `     D   parentPtr                     *` | **Internal use only** |
| `     D   Reserved                  4096A` | **Internal use only** |