# RXS_Parse()

This subprocedure is used to set up XML parsing. Use of this subprocedure requires an XML handler subprocedure to also be written.

The events recognized by the XML parser are:

| Event | Format | Example |
| ----- |-| ------ |
| Element Begin | `>` | `Request>` |
| Element Content | `/` | `Request/Item/` |
| Element End | `/>` | `Request/>` |
| Attribute | `@` | `Request/Item@Attribute` |

The Element Content and Attribute events will return data, which can be retrieved with [RXS_STR()](https://isupport.katointegrations.com/rxs/3.5/rxs_str.md).

### New in RXS 3.5.0

#### Enhancements

* Corrected a possible memory leak condition present when parsing XML stored in an IFS file.

## Subprocedure Prototype

| Field | Description |
|---|---|
| `     D RXS_Parse...      D                 PR                  Extproc('RXS_Parse') Opdesc` |  |
| `     D  pInput                             Like(RXS_Var16Mv_t)      D                                     Options(*Omit:*Varsize)` | Holds the XML data to be passed to the parsing subprocedure(s). Will be ignored if the Stmf subfield of the DS parameter is set. |
| `     D  pDS                                LikeDS(RXS_ParseDS_t)      D                                     Options(*Varsize)` | Holds a RXS_ParseDS_t data structure which controls how RXS_Parse() functions. |


## Example Code

### Ex. 1: Simple Parse
```rpgle
      *--------------------------------------------------------------
      * This example parses a simple XML structure stored in the field
      * 'XML' and stores the data contained in nodes <Node1> and <Node2>
      * in the corresponding global fields.
      *
      * At a high level, the XML is passed into the XmlHandler() 
      * subprocedure in small chunks. Then, a SELECT block is used to
      * detect whether or not the current chunk of XML matches one
      * you'd like to handle. If it does, you can extract the data from
      * an element of attribute using RXS_STR().
      *
      * Once the XML has been entirely passed through XmlHander(), control
      * returns to the main part of the program.
      *--------------------------------------------------------------
     H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

      /copy QRPGLECPY,RXSCB

     D XmlHandler      PR
     D  pType                        10A   Value
     D  pXPath                     1024A   Value Varying
     D  pData                          *   Value
     D  pDataLen                     10I 0 Value

     D ParseDS         DS                  LikeDS(RXS_ParseDS_t)
     D                                     Inz(*LikeDS)
     D XML             S                   Like(RXS_Var64Kv_t)
     D Node1           S                   Like(RXS_Var1Kv_t)
     D Node2           S                   Like(RXS_Var1Kv_t)
      /free
        XML = '<?xml version="1.0" encoding="utf-8"?>' +
         '<Root><Node1>Hello</Node1><Node2>World</Node2></Root>';

        RXS_ResetDS( ParseDS : RXS_DS_TYPE_PARSE );
        ParseDS.GlobalHandler = %Paddr( XmlHandler );
        RXS_Parse( XML : ParseDS );

        RXS_JobLog( 'Node 1: %s' : Node1 );
        RXS_JobLog( 'Node 2: %s' : Node2 );

        *INLR = *ON;
      /end-free

     P XmlHandler      B
     D XmlHandler      PI
     D  pType                        10A   Value
     D  pXPath                     1024A   Value Varying
     D  pData                          *   Value
     D  pDataLen                     10I 0 Value
      /free
        select;
          when pXPath = '/Root/Node1/';
            Node1 = RXS_STR( pData : pDataLen );
          when pXPath = '/Root/Node2/';
            Node2 = RXS_STR( pData : pDataLen );
        endsl;
      /end-free
     P                 E
```

## Data Structures

### RXS_ParseDS_t

| Field | Description |
|---|---|
| `     D RXS_ParseDS_t   DS                  Qualified Template Inz` |  |
| `     D   ReturnedErrorInfo...      D                                     Like(RXS_ReturnedErrorInfoDS_t) Inz` |  |
| `     D   DataStructureType...      D                                5I 0 Inz(RXS_DS_TYPE_PARSE)` | **Internal use only** |
| `     D   OnErrorMessageType...      D                                5I 0` |  |
| `     D   GlobalHandler...      D                                 *   Procptr` | Holds a PROCPTR to an XmlHandler subprocedure used to handle all possible XML events. |
| `     D   ElementContentHandler...      D                                 *   Procptr` | Holds a PROCPTR to an XmlHandler subprocedure which will only respond to XML content events. |
| `     D   ElementBeginHandler...      D                                 *   Procptr` | Holds a PROCPTR to an XmlHandler subprocedure which will only respond to XML begin events. |
| `     D   ElementEndHandler...      D                                 *   Procptr` | Holds a PROCPTR to an XmlHandler subprocedure which will only respond to XML end events. |
| `     D   AttributeHandler...      D                                 *   Procptr` | Holds a PROCPTR to an XmlHandler subprocedure which will only respond to XML attribute events. |
| `     D   IncludeNamespaces...      D                                 N` | Controls whether namespaces are factored into XML parsing - if RXS_NO, they will be ignored. **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_NO` |
| `     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. |