# RXS_CreateJson()

This subprocedure is used to begin JSON composition. It creates a "root" JSON structure that other JSON objects, arrays, and data elements can be attached to.

## Subprocedure Prototype

### IBM i 7.1+

| Field | Description |
|---|---|
| `     D RXS_CreateJson...      D                 PR                  Extproc('RXS_CreateJson') Opdesc      D                                     LikeDS(RXS_JsonStructureDS_t)` | Returns an RXS_JsonStructureDS_t which can be used by the RXS JSON composition subprocedures. |
| `     D  pCreateJsonDS...      D                                     LikeDS(RXS_CreateJsonDS_t)      D                                     Options(*Varsize)` | RXS_CreateJsonDS_t data structure which controls how RXS_CreateJson() functions. |


## Example Code

### IBM i 7.1+

#### Example 1: Create root JSON object
```rpgle
      *--------------------------------------------------------------
      * This example creates a root JSON structure that is a JSON 
      * object. It allows subsequent JSON objects, arrays, or data
      * elements to be attached in order to build a JSON document.
      *--------------------------------------------------------------
     H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

      /copy QRPGLECPY,RXSCB

     D JSON            S                   Like(RXS_Var64Kv_t)

     D CreateJsonDS    DS                  LikeDS(RXS_CreateJsonDS_t)
     D RootDS          DS                  LikeDS(RXS_JsonStructureDS_t)
     D ItemDS          DS                  LikeDS(RXS_JsonStructureDS_t)
      /free
        RXS_ResetDS( CreateJsonDS : RXS_DS_TYPE_CREATEJSON );
        RXS_ResetDS( RootDS : RXS_DS_TYPE_JSONSTRUCTURE );
        RXS_ResetDS( ItemDS : RXS_DS_TYPE_JSONSTRUCTURE );
        
        CreateJsonDS.JsonStructureType = RXS_JSON_STRUCTURE_OBJECT;
        RootDS = RXS_CreateJson( CreateJsonDS );
        // RootDS now contains a JSON structure that looks like this
        //  if printed:
        //
        //  { }

        // Create JSON object named "item" and attach it to RootDS
        ItemDS = RXS_ComposeJsonObject( 'item' : RootDS );
        // JSON now looks like this if printed:
        //
        // { "item": {} }

        // Create JSON number named "id" and attach it to ItemDS
        // Note that RXS_ComposeJsonNumber() uses character data,
        //  not numeric data, to allow it to handle the large
        //  numbers that JSON supports
        RXS_ComposeJsonNumber( 'id' : '7' : ItemDS );
        // JSON now looks like this if printed:
        //
        // { "item": { "id": 7 } }

        // Create JSON string named "name" and attach it to ItemDS
        RXS_ComposeJsonString( 'name' : 'headlight fluid' : ItemDS );
        // JSON now looks like this if printed:
        //
        // { "item": { "id": 7, "name": "headlight fluid" } }


        // Create JSON number named "price" and attach it to ItemDS
        RXS_ComposeJsonNumber( 'price' : '12.50' : ItemDS );

        // Enable JSON "prettification" (format to make more readable)
        //  and retrieve JSON into an RPG character data field
        CreateJsonDS.Prettify = RXS_YES;
        JSON = RXS_GetJsonString( CreateJsonDS );
        // Character data retrieved:
        //
        // {
        //    "item": {
        //      "id": 7,
        //      "name": "headlight fluid",
        //      "price": 12.50
        //    }
        // }

        RXS_DestroyJson( CreateJsonDS );

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

#### Example 2: Create root JSON array
```rpgle
      *--------------------------------------------------------------
      * This example creates a root JSON structure that is a JSON
      * array. It allows subsequent JSON objects, arrays, or data
      * elements to be attached in order to build a JSON document.
      *--------------------------------------------------------------
     H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

      /copy QRPGLECPY,RXSCB

     D JSON            S                   Like(RXS_Var64Kv_t)

     D CreateJsonDS    DS                  LikeDS(RXS_CreateJsonDS_t)
     D RootDS          DS                  LikeDS(RXS_JsonStructureDS_t)
     D i               S              3U 0
      /free
        RXS_ResetDS( CreateJsonDS : RXS_DS_TYPE_CREATEJSON );
        RXS_ResetDS( RootDS : RXS_DS_TYPE_JSONSTRUCTURE );
        
        CreateJsonDS.JsonStructureType = RXS_JSON_STRUCTURE_ARRAY;
        RootDS = RXS_CreateJson( CreateJsonDS );
        // RootDS now contains a JSON structure that looks like this
        //  if printed:
        //
        //  "[]"

        for i = 1 to 10;
          // Elements in a JSON array do not have a name associated
          //  with them, so the first parameter of the RXS_ComposeJson
          //  subprocedures should be set to *OMIT
          RXS_ComposeJsonNumber( *OMIT : %Char(i) : RootDS );
        endfor;
        // JSON now looks like:
        //
        // [1,2,3,4,5,6,7,8,9,10]

        // Enable JSON "prettification" (format to make more readable)
        //  and retrieve JSON into an RPG character data field
        CreateJsonDS.Prettify = RXS_YES;
        JSON = RXS_GetJsonString( CreateJsonDS );
        // Character data retrieved:
        //
        // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

        RXS_DestroyJson( CreateJsonDS );

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

## Data Structures

### RXS_CreateJsonDS_t

| Field | Description |
|---|---|
| `     D RXS_CreateJsonDS_t...      D                 DS                  Qualified Template Inz` |  |
| `     D   ReturnedErrorInfo...      D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz` |  |
| `     D   DataStructureType...      D                                5I 0 Inz(RXS_DS_TYPE_CREATEJSON)` | **Internal use only** |
| `     D   OnErrorMessageType...      D                                5I 0` |  |
| `     D   Prettify                      N   Inz(RXS_NO)` | If set to RXS_YES, JSON retrieved with RXS_GetJsonString() will be formatted with whitespace to be "pretty" and more human readable. If set to RXS_NO, JSON will be returned in a compact form with as little whitespace as possible. **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_NO` |
| `     D   JsonStructureType...      D                                 N   Inz(RXS_JSON_STRUCTURE_OBJECT)` | If set to RXS_JSON_STRUCTURE_OBJECT, the JSON document being created will begin with a root JSON object. If set to RXS_JSON_STRUCTURE_ARRAY, it will begin with a root JSON array. **Valid Values:** `RXS_JSON_STRUCTURE_OBJECT`, `RXS_JSON_STRUCTURE_ARRAY` **Default Value:** `RXS_JSON_STRUCTURE_OBJECT` |
| `     D   JsonStructurePtr...      D                                 *   Inz(*Null)` | **Internal use only** |
| `     D   InputCcsid...      D                               10I 0 Inz(RXS_CCSID_JOB)` | Specifies the CCSID of the data being passed into the JSON composition subprocedures. Default is job CCSID. **Default Value:** `RXS_CCSID_JOB` |
| `     D   OutputCcsid...      D                               10I 0 Inz(RXS_CCSID_JOB)` | Specifies the CCSID that the JSON will be output as from RXS_GetJsonString(). Default is job CCSID. **Default Value:** `RXS_CCSID_JOB` |
| `     D   TrimVariables...      D                                 N   Inz(RXS_NO)` | Determines whether to trim leading and trailing spaces from each value passed to RXS_ComposeJsonString() (RXS_YES), or to leave all spaces in place (RXS_NO). **Valid Values:** `RXS_YES`, `RXS_NO` **Default Value:** `RXS_NO` |


### RXS_JsonStructureDS_t

| Field | Description |
|---|---|
| `     D RXS_JsonStructureDS_t...      D                 DS                  Qualified Template Inz` |  |
| `     D   ReturnedErrorInfo...      D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz` |  |
| `     D   DataStructureType...      D                                5I 0 Inz(RXS_DS_TYPE_JSONSTRUCTURE)` | **Internal use only** |
| `     D   OnErrorMessageType...      D                                5I 0` |  |
| `     D   JsonStructureType...      D                                 N   Inz(RXS_JSON_STRUCTURE_OBJECT)` | **Internal use only** |
| `     D   JsonStructurePtr...      D                                 *   Inz(*Null)` | **Internal use only** |
| `     D   InputCcsid...      D                               10I 0 Inz(RXS_CCSID_JOB)` | Specifies the CCSID of the data being passed into the JSON composition subprocedures. Default is job CCSID. **Default Value:** `RXS_CCSID_JOB` |
| `     D   OutputCcsid...      D                               10I 0 Inz(RXS_CCSID_JOB)` | Specifies the CCSID that the JSON will be output as from RXS_GetJsonString(). Default is job CCSID. **Default Value:** `RXS_CCSID_JOB` |