# RXS_StartComposeEngine()

This subprocedure initializes the compose engine with a specific template file. This is utilized primarily to build XML but could be used to build any type of character data.

## Subprocedure Prototype

| Field | Description |
|---|---|
| `     D RXS_StartComposeEngine...      D                 PR                  Extproc('RXS_StartComposeEngine')      D                                     Opdesc` |  |
| `     D  pDS                                LikeDS(RXS_ComposeDS_t)      D                                     Options(*Varsize)` | Pass in an RXS_ComposeDS_t to control how the composition engine functions. |


## Example Code

### Ex. 1
```rpgle
      *--------------------------------------------------------------
      * This example code initializes the composition engine for the EXAMPLE template and 
      *  configures it with the procedure address for the Template procedure.
      *--------------------------------------------------------------
     H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

      /copy QRPGLECPY,RXSCB
      /copy QRPGLETPL,EXAMPLE

     D ComposeDS       DS                  LikeDS(RXS_ComposeDS_t)
      /free
       RXS_ResetDS( ComposeDS : RXS_DS_TYPE_COMPOSE );
       ComposeDS.TemplateProcedure = %Paddr(Template);
       RXS_StartComposeEngine( ComposeDS );

       *INLR = *ON;
      /end-free

     P Template        B
     D                 PI
     D  p                         65535A   Varying
      /copy QRPGLETPL,EXAMPLE
     P                 E
```

### Ex. 2
```rpgle
      *--------------------------------------------------------------
      * This example code initializes the composition engine for the EXAMPLE template and 
      *  configures it with the procedure address for the Template procedure. It also
      *  sets configuration values to trim whitespace from template lines and to
      *  omit line control characters.
      *--------------------------------------------------------------
     H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

      /copy QRPGLECPY,RXSCB
      /copy QRPGLETPL,EXAMPLE

     D ComposeDS       DS                  LikeDS(RXS_ComposeDS_t) 
      /free
       RXS_ResetDS( ComposeDS : RXS_DS_TYPE_COMPOSE );
       ComposeDS.TemplateProcedure = %Paddr(Template);
       ComposeDS.TrimTemplateLines = RXS_YES;
       ComposeDS.OmitLineControls = RXS_YES;
       RXS_StartComposeEngine( ComposeDS );

       *INLR = *ON;
      /end-free

     P Template        B
     D                 PI
     D  p                         65535A   Varying
      /copy QRPGLETPL,EXAMPLE
     P                 E
```

### Ex. 3
```rpgle
      *--------------------------------------------------------------
      * This example code initializes the composition engine for the EXAMPLE template and 
      *  configures it with the procedure address for the Template procedure. It also
      *  sets a configuration value to skip composing lines on which there are
      *  uncomposed varaibles.
      *--------------------------------------------------------------
     H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

      /copy QRPGLECPY,RXSCB
      /copy QRPGLETPL,EXAMPLE

     D ComposeDS       DS                  LikeDS(RXS_ComposeDS_t) 
      /free
       RXS_ResetDS( ComposeDS : RXS_DS_TYPE_COMPOSE );
       ComposeDS.TemplateProcedure = %Paddr(Template);
       ComposeDS.OmitUncomposedLines = RXS_YES;
       RXS_StartComposeEngine( ComposeDS );

       *INLR = *ON;
      /end-free

     P Template        B
     D                 PI
     D  p                         65535A   Varying
      /copy QRPGLETPL,EXAMPLE
     P                 E
```

### Ex. 4
```rpgle
      *--------------------------------------------------------------
      * This example code initializes the composition engine for the EXAMPLE template and 
      *  configures it with an IFS file containing a template file.
      *--------------------------------------------------------------
     H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

      /copy QRPGLECPY,RXSCB

     D ComposeDS       DS                  LikeDS(RXS_ComposeDS_t) 
      /free
       RXS_ResetDS( ComposeDS : RXS_DS_TYPE_COMPOSE );
       ComposeDS.Stmf = '/www/RXS/templates/geturi2.tpl';
       RXS_StartComposeEngine( ComposeDS );

       *INLR = *ON;
      /end-free
```

## Data Structures

### RXS_ComposeDS_t

| Field | Description |
|---|---|
| `     D RXS_ComposeDS_t...      D                 DS                  Qualified Template Inz` |  |
| `     D   ReturnedErrorInfo...      D                                     Like(RXS_ReturnedErrorInfoDS_t) Inz` |  |
| `     D   DataStructureType...      D                                5I 0 Inz(RXS_DS_TYPE_COMPOSE)` | **Internal use only** |
| `     D   OnErrorMessageType...      D                                5I 0` |  |
| `     D   TemplateProcedure...      D                                 *   Procptr` | Pointer to the address of the subprocedure that will compose the XML or other character based content. |
| `     D   LogFile                           Like(RXS_Var1Kv_t)` | IFS location where a log file will be created during composition. |
| `     D   Stmf                              Like(RXS_Var1Kv_t)` | IFS location where a dynamically processed template file is located. If specified, the TemplateProcedure option is ignored. |
| `     D   LogFileAppend...      D                                 N   Inz(RXS_NO)` | Determines whether to append the data to the log file (RXS_YES), or to overwrite the log file (RXS_NO). Default: RXS_NO **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_NO` |
| `     D   UseStmfCCSID                  N` | Determines whether to compose all characters in the CCSID of the Stmf (RXS_YES), or to use the CCSID of the current job (RXS_NO). **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_NO` |
| `     D   Initialize                    N   Inz(RXS_YES)` | Determines whether to initialize the engine (RXS_YES), or to leave any previous configuration and composed content in place (RXS_NO). **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_YES` |
| `     D   LargeTemplate...      D                                 N   Inz(RXS_NO)` | Determines whether to allow templates up to 256K in length (RXS_YES), or to use 64K (RXS_NO). **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_NO` |
| `     D   OmitLineControls...      D                                 N   Inz(RXS_NO)` | Determines whether to strip the line controls from the end of each template line (RXS_YES), or to leave line controls in place (RXS_NO). **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_NO` |
| `     D   TrimTemplateLines...      D                                 N   Inz(RXS_NO)` | Determines whether to trim leading and trailing spaces from the start and end of each template line (RXS_YES), or to leave all spaces in place (RXS_NO). Note that spaces are only trimmed from template content and not from content passed via RXS_ComposeVariable(). **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_NO` |
| `     D   OmitUncomposedLines...      D                                 N   Inz(RXS_NO)` | Determines whether to omit template lines with variables that have not been composed by RXS_ComposeVariable() (RXS_YES), or to compose all template lines (RXS_NO). **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_NO` |
| `     D   TrimVariables...      D                                 N   Inz(RXS_NO)` | Determines whether to trim leading and trailing spaces from each variable passed to RXS_ComposeVariable() (RXS_YES), or to leave all spaces in place (RXS_NO). **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_NO` |
| `     D   EncodeVariables...      D                                 N   Inz(RXS_NO)` | Determines whether to perform XML entity encoding on each variable passed to RXS_ComposeVariable() (RXS_YES), or to leave all entities unencoded (RXS_NO). **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_NO` |