MDRYAJLR4 copybook

This copybook contains RPG Prototypes for YAJL with mdr_ prefix. The procedures for these functions are found in the MDRYAJLR4 *SRVPGM, which is bound in by the MDRFRAME Binding directory.

All Copybooks

The source of these can be found in MDRST/QRPGLESRC

Copybook	Description
MDRFRAME	MDRFRAME framework prototypes and templates. Find this here: `MDRST/QRPGLESRC.MDRFRAME`
MDRYAJLR4	RPG Prototypes for YAJL with mdr_ prefix. Find this here: `MDRST/QRPGLESRC.MDRYAJLR4`
MDRTOOLS	Additional MDRest4i utilities used by the SDK, and also available for customer use. Find this here: `MDRST/QRPGLESRC.MDRTOOLS`
MDRPSDS	MDRest4i program status data structure (PSDS) definitions. Find this here: `MDRST/QRPGLESRC.MDRPSDS`
MDRTOKEN	MDRest4i Token handling functions. Find this here: `MDRST/QRPGLESRC.MDRTOKEN`

Warning

Before using mdr_ YAJL functions you need to create a temporary BUFFER to load the JSON created by the YAJL functions into.

mdr_startJson(OFF:OFF);

When you are finished creating the JSON you need to always clear the temporary buffer. This also moves the JSON into the MDRFRAME pointer used to create the response (provider) or request(consumer)

mdr_endJson();

Using YAJL Json generation in MDRFRAME

The full example below can be found in product source file MDRST/EXAMPLE.GETJSON

// Start writing the JSON using YAJL functions.
mdr_startJson(*OFF:*OFF);
mdr_beginObject();
mdr_addNum('id':%char(mdlresp.id));
mdr_addChar('name':mdlresp.name);
mdr_addChar('address': mdlresp.address );
mdr_addChar('phone': mdlresp.phone );
mdr_endObject();

// Retrieve JSON loaded in buffer memory
mdr_getJsonptr(jsonDataPtr:jsonPtrLen);

// Write the JSON data to standard output as response
mdr_len_write(handle:jsonDataPtr:jsonPtrLen);

// TODO: Set the IFS path where the JSON will be wrotten to. 
IFSPath = '/home/MDRest4i/GETJSON_YAJL.json';

// TODO: Retrieve JSON String loaded in buffer memory
// %size(JsonStr) tells MDRFRAME to return the defined length of
// the JsonStr variable to JsonStr
mdr_getJson(*zero:JsonPtr:%size(JsonStr):rtnlen);
// TODO: MDRFRAME function to cerated and write out an IFS file
if MDRF_writeAll(IFSPath:jsonStr:errorMsg) < *zero;
  errorMsg = 'Error occurred during writing JSON to the IFS';
  MDR_setError(handle:'GETJSON':errorMsg:84:20:200);
endif;

// Release the memory allocated by JSON generator
mdr_endJson();

mdr_beginArray

If called without parameter or with blank parameter, it starts non-labeled array. If parameter, writes an labeled array eg. "myarray": [

@param (input/opt) array label
@return Yajl generation status

dcl-pr mdr_beginArray int(10) extproc('YAJL_BEGINARRAY');
  label varchar(65535) const options(*varsize:*nopass);
end-pr;

mdr_endArray

Ends the array by adding closing square bracket - @return: Yajl generation status

dcl-pr mdr_endArray int(10) extproc('YAJL_ENDARRAY')
end-pr;

mdr_beginObject

if called without parameter or with blank parameter, it starts non-labeled object. Otherwise, it writes labeled object eg. "myobject": {

@param (input/opt) array label
@return Yajl generation status

dcl-pr mdr_beginObject int(10) extproc('YAJL_BEGINOBJ');
  label varchar(65535) const options(*varsize:*nopass);
end-pr;

mdr_endObject

ends the object by adding closing curly bracket

@return Yajl generation status

dcl-pr mdr_endObject int(10) extproc('YAJL_ENDOBJ')
end-pr;

mdr_addNull

Add a null value to a JSON data stream

@param label (input) = label of property to add to object value of 'label' will be set to null. e.g "name": null
@return Yajl generation status

dcl-pr mdr_addNull int(10) extproc('YAJL_ADDNULL');
  value varchar(65535) const options(*varsize:*nopass);
end-pr;

mdr_addChar

Add a character value to the JSON data stream if one parameter: add character string to add to JSON stream if two parameters: key of property to add to object, and value

@param label (input) = key of property to add to object
@param value (input) = character string to set as property value

if the third parameter is given:

@param isNull (input) = if *ON output is null, otherwise is value above

@return yajl_gen_status_ok upon success, or generator status code upon failure. Example: mdr_addChar('name':mdlReq.name:mdlReq.name=' ');

if mdlReq.name is blank, then the JSON will look like this:
"name": null

if mdlReq.name is 'stuart', then the JSON will look like this:
"name": "stuart"

dcl-pr mdr_addChar int(10) extproc('YAJL_ADDCHAR');
  label varchar(65535) const options(*varsize);
  value varchar(65535) const options(*varsize:*nopass:*omit);
  isnull ind const options(*nopass:*omit);
end-pr;

MDR_addCurr

This function adds a numeric value to JSON output. If one parameter is supplied or two parameters are supplied, and the first one is blank, it will just add the non-labeled/non-keyed value to the JSON output. If both the values are received, it will add label/value pair to output. If the numeric value has a dot as the first character or the numeric value was negative and therefore it begins with "-.", a zero will be appended before dot to make sure the output JSON is valid. e.g .25 will be 0.25 or -.25 will be -0.25 in the JSON output

@param (input) value1 = character key (when both parameters are supplied) or numeric value (when only one parameter is supplied)
@param (input) value2 = numeric value for the key/label in first parameter
@info MDRFRAME7

dcl-pr MDR_addCurr
        extproc(*cwiden:'MDR_addCurr') opdesc;
  value1        varchar(2048) const options(*varsize);
  value1        varchar(2048) const options(*varsize:*nopass);
end-pr;

mdr_addNum

Add a numeric value to the JSON data stream if one parameter: add number to JSON stream (in string form) if two parameters: key of property to add to object, and value

@param label (input) = key of property to add to object
@param value (input) = number to set as property value (in string form)

if the third parameter is given:

@param isNull (input) = if *ON output is null, otherwise is value above
@return yajl_gen_status_ok upon success, or generator status code upon failure.

dcl-pr mdr_addNum int(10) extproc('YAJL_ADDNUM');
  label varchar(65535) const options(*varsize);
  value varchar(65535) const options(*varsize:*nopass:*omit);
  isnull ind const options(*nopass:*omit);
end-pr;

mdr_addBool

Add a boolean value to the JSON data stream if one parameter: RPG indicator, where ON=true, OFF=false to add to JSON data stream if two parameters: key of property to add to object, and value(true or false)

@param label (input) = key of property to add to object
@param value (input) = RPG indicator to set as a boolean value.

if the third parameter is given:

@param isNull (input) = if *ON output is null, otherwise is value above
@return yajl_gen_status_ok upon success, or generator status code upon failure.

dcl-pr mdr_addBool int(10) extproc('YAJL_ADDBOOL');
  label varchar(65535) const options(*varsize);
  Value ind const options(*nopass);
  isnull ind const options(*nopass:*omit);
end-pr;

mdr_startJson

Open a YAJL JSON generator mdr_addchar etc functions to build JSON in memory

@param beautify (input) = ON would add line breaks and indentation for readability OFF would generate compact JSON
@param escSolidus (input) = On would escape the solidus (aka forward slash) characters. default is Off
@return: yajl_gen_status_ok (i.e. 0) if successful yajl_gen_open_fail (i.e. 1000001) upon failure

dcl-pr mdr_startJson int(10) Extproc('YAJL_GENOPEN');
  beautify ind const;
  escSolidus ind const options(*nopass);
end-pr;

mdr_endJson

Closes the JSON generation channel and deallocates memory. Subsequently mdr_addchar, mdr_getJson etc cannot be used

dcl-pr mdr_endJson Extproc('YAJL_GENCLOSE')
end-pr;

mdr_getJson

Copies JSON generator buffer to the caller's variable or buffer.

@param ccsid = (input) CCSID to convert data to. 0=job CCSID.
@param bufptr = (input) Pointer to variable or buffer to copy the data to.
@param bufSize = (input) Size of the jsonBuf buffer (in bytes)
@param rtnLen = (output) length of data placed in buffer
@return YAJL generator status.

dcl-pr mdr_getJson int(10) Extproc('YAJL_COPYBUF');
  ccsid  int(10) value;
  bufptr pointer value;
  bufsize int(10) value;
  rtnlen int(10);
end-pr;

mdr_getJsonPtr

@param returns a pointer to JSON internal buffer where JSON data is stored.
@param rtnptr = (output) pointer to YAJL's generator buffer
@param rtnlen = (output) length of returned buffer in bytes
@return YAJL generator status.

dcl-pr mdr_getJsonPtr int(10) Extproc('YAJL_GETBUF');
  bufptr pointer;
  bufsize uns(10);
end-pr;

mdr_getJsonStr

@return the current JSON buffer to an RPG variable of max 2000000 size. Receiving variable must be a varchar. It is not optimized and for larger payloads can impact performance. If so, se mdr_getJson for larger size or better performance.

dcl-pr mdr_getJsonStr varucs2(2000000) extproc('YAJL_COPYBUFSTR')
end-pr;

MDR_addTimestamp

Adds an ISO 8601 timestamp in: YYYY-MM-DDTHH:MM:SS.sss format to the JSON document.

@param (input) name = key name if within an object, or *omit
@param (input) val = standard RPG timestamp field
@param (input/opt) tz = time zone to use, examples are: 'Z' = UTC '+0500' = 5 hours east of UTC '-0600' = 6 hours west of UTC ' ' = local time '*UTC' (default) Convert to UTC and report as a UTC timestamp
@param (input) datesep = date separator (default: -)
@param (input) timesep = time separator (default: :)
@param (input) tzsep = timezone sep (default: none)
@return returns yajl_gen_status_ok upon success, or generator status code upon failure.

dcl-pr MDR_addTimestamp extproc('YAJL_ADDTIMESTAMP');
  name           Varchar(65535) CONST OPTIONS(*VARSIZE:*OMIT);
  val            Timestamp  CONST;
  tz             Varchar(6)  CONST OPTIONS(*OMIT:*NOPASS);
  datesep        Varchar(1)  CONST OPTIONS(*OMIT:*NOPASS);
  timesep        Varchar(1)  CONST OPTIONS(*OMIT:*NOPASS);
  tzsep          Varchar(1)  CONST OPTIONS(*OMIT:*NOPASS);
  isnull         ind         CONST OPTIONS(*OMIT:*NOPASS);
end-pr;

mdr_getEntry

@return the value at the specified key node. e.g. for the node "city":"Paris", it will return "Paris". The node value must be of string type, otherwise, it will return blank

dcl-pr mdr_getEntry varchar(1024) extproc('YAJL_GETSTRKEY');
  bgnNode pointer value;
  entry varchar(50) const;
end-pr;

mdr_GetNumKey

@return the numeric value in string form at the specified key node. for the node "orderno":57689, it will return '57689'. The node must be of numeric type. Otherwise, it returns blank

dcl-pr mdr_GetNumKey varchar(50) extproc('YAJL_GETNUMSTR');
  node pointer value;
end-pr;

MDR_object_insert

Inserts a new node into an object in a YAJL tree structure

@param node = (i/o) object node to insert into
@param type = (input) type of node to insert (one of the MDR_t_xxx constants below)
@param newKey = (input) new key name to insert
@param newVal = (input) string representation of new value to insert (only used for numbers/strings)
@param rel = (input/opt) relationship to refKey (MDR_xx below)
@param refKey = (input/opt) key to reference when inserting
@return the newly created node (yajl_val) or *NULL upon failure

dcl-pr MDR_object_insert Pointer extproc('YAJL_OBJECT_INSERT');
  node           Pointer        VALUE;
  type           Int(10)        VALUE;
  newKey         Varchar(1024)  CONST OPTIONS(*VARSIZE);
  newVal         Varchar(65535) CONST OPTIONS(*VARSIZE);
  xrel           Int(10)        VALUE OPTIONS(*NOPASS);
  refKey         Varchar(1024)  CONST OPTIONS(*VARSIZE: *NOPASS: *OMIT);
end-pr;

Constants

Dcl-C MDR_before  CONST(1);
Dcl-C MDR_after   CONST(2);
Dcl-C MDR_replace CONST(3);
Dcl-C MDR_append  CONST(X'1FFFFFFF');

Dcl-C MDR_t_string CONST(1);
Dcl-C MDR_t_number CONST(2);
Dcl-C MDR_t_object CONST(3);
Dcl-C MDR_t_array  CONST(4);
Dcl-C MDR_t_true   CONST(5);
Dcl-C MDR_t_false  CONST(6);
Dcl-C MDR_t_null   CONST(7);

MDR_array_add

Adds data to the end of an array in a tree node - @param node = (i/o) array node to add onto - @param type = (input) type of node to insert (one of the yajl_t_xxx constants - @param newVal = (input) string representation of new value to insert (only used for numbers/strings) - @return the newly created node (yajl_val) or *NULL upon failure

dcl-pr MDR_array_add Pointer extproc('YAJL_ARRAY_ADD');
  node           Pointer        VALUE;
  type           Int(10)        VALUE;
  newVal         Varchar(65535) CONST OPTIONS(*VARSIZE);
end-pr;