JSON (RPGLE)

JSON Service program
Details ....

Copybooks  

'json_h.rpgle'
'json_int_h.rpgle'
'ceeapi_h.rpgle'
'llist_h.rpgle'
'libc_h.rpgle'
QSYSINC/QRPGLESRC,QUSEC
COMMON STRUCTURE FOR ERROR CODE PARAMETER
'json_c.rpgle'
'unicode_c.rpgle'

Procedures  

disposeEntryValueexported
Dealloc entry value
escapeLastTokenexported
Escape characters
getJSONEntryexported
Get entry by key
isJSONImplexported
Check for JSON object
json_abortIterationexported
Abort iteration
json_clearexported
Clear JSON object
json_containsexported
Contains key
json_createexported
Create JSON Object
json_disposeexported
Deallocate JSON object
json_getexported
Get entry
json_getArrayexported
Get array entry
json_getBooleanexported
Get boolean entry
json_getDoubleexported
Get double entry
json_getEntryTypeexported
Get entry type
json_getIntexported
Get integer entry
json_getLongexported
Get long entry
json_getNextexported
Get next entry
json_getObjectexported
Get object entry
json_getStringexported
Get string entry
json_isEmptyexported
Is JSON object empty
json_isNullexported
Checks if entry is of special type null
json_putArrayexported
Add array entry
json_putBooleanexported
Add boolean entry
json_putDoubleexported
Add double entry
json_putIntexported
Add integer entry
json_putLongexported
Add long entry
json_putNullexported
Add null value entry
json_putObjectexported
Add JSON object entry
json_putStringexported
Add character entry
json_removeexported
Remove entry
json_sizeexported
Count JSON object entries
json_srvpgm_initexported
Service program initialization
json_toStringexported
String representation of the JSON object in JSON syntax
prettyPrintexported
sendDiagnosticMessageexported
Send diagnostic message
sendEscapeMessageexported
Send escape message

Detailed Description  

From the main web site:

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.

JSON is built on two structures:

These are universal data structures. Virtually all modern programming languages support them in one form or another. It makes sense that a data format that is interchangable with programming languages also be based on these structures.

In JSON, they take on these forms:

An object is an unordered set of name/value pairs. An object begins with { (left brace) and ends with } (right brace). Each name is followed by : (colon) and the name/value pairs are separated by , (comma).

Concerning this implementation:

The pointer to the JSON object will be check on every procedure call. If the pointer does not point to a JSON object an escape message will be send to the next level of the call stack.

If the JSON obect is queried for an entry of a specific type and the type does not match with the expectation of the procedure an escape message will be send to the next level of the call stack.

All the allocated memory of the JSON object and its entries is managed by this service program and will be freed with the call of the procedure dispose. No manual deallocation must be done.
Author:
Mihael Schmidt
Date:
20.03.2008
Changes:
27.01.2010   —   Mihael Schmidt
Added support for getting numbers with procedures json_getInt, json_getLong, json_getDouble no matter what the original type was (f. e. double value will be cast to int with json_getInt).

13.02.2011   —   Mihael Schmidt
Fixed bug in remove procedure. Replaced string and hex constants with unicode constants.

09.04.2011   —   Mihael Schmidt
Fixed memory management error in toString procedure.

24.06.2011   —   Brian Garland
Remove leading plus (+) from floating point numbers when creating a string from a json object.

Links:
http://www.json.org

Procedure Documentation  

disposeEntryValue  

voiddisposeEntryValue(Pointer)
The value of an entry is deallocated. If the entry is of type object or array it must be disposed.
Parameter:
PointerPointer to an entry
Exported.
Author:
Mihael Schmidt
Date:
14.05.2008

escapeLastToken  

voidescapeLastToken(Pointer)
Double quotes and backslashes must be escape in string values to comply to the JSON specs.

The last element of the token list will be checked for characters which need to be escaped.
Parameter:
PointerPointer to token list
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

getJSONEntry  

PointergetJSONEntry(Pointer, Pointer, ohne Vorzeichen)
Returns a pointer to the entry data structure for the passed key.
Parameter:
Pointer   constPointer to the JSON object
Pointer   constPointer to the key
Numerisch (ohne Vorzeichen) (10)   constKey length
Return value:
PointerPointer to the entry or *null if no such entry exists in this JSON object.
Exported.

isJSONImpl  

voidisJSONImpl(Pointer)
Checks if the passed pointer points to a JSON object.

If the pointer does not point to a JSON object and escape message will be send to the next entry in the call stack.
Parameter:
Pointer   constPointer to the JSON object
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_abortIteration  

voidjson_abortIteration(Pointer)
Resets the iteration of the JSON Object.
Parameter:
Pointer   constPointer to the JSON object
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_clear  

voidjson_clear(Pointer)
Removes all entries from the JSON object.
Parameter:
Pointer   constPointer to the JSON object
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_contains  

Booleanjson_contains(Pointer, Zeichen)
Checks if the JSON object contains an entry with the passed key.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeEntry key
Return value:
Boolean*on = JSON object contains key
*off = JSON object does not contain key
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_create  

Pointerjson_create()
Creates a JSON Object.

The memory allocated for this object must be deallocated with the dispose procedure when finished.
Return value:
PointerPointer to the JSON object
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_dispose  

voidjson_dispose(Pointer)
The memory for the JSON Object will be deallocated and the passed pointer will be set to *null.
Parameter:
PointerPointer to the JSON object
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_get  

Pointerjson_get(Pointer, Zeichen)
Gets the value of entry in the JSON object as a string.

The return value is a pointer to a null terminated string so that it can be easily processed with the %str BIF.

The memory for the return value was allocated will be managed by the JSON object and will be disposed with the dispose procedure. The calling program does not need to deallocate the the memory by itself.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Return value:
PointerPointer to a null terminated string or *null if JSON object does not contain the passed key
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_getArray  

Pointerjson_getArray(Pointer, Zeichen)
Returns the array value of the entry.

If the entry is not of type array an escape message will be send.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Return value:
PointerPointer to the JSON array
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_getBoolean  

Booleanjson_getBoolean(Pointer, Zeichen)
Returns the boolean value of the entry.

If the entry is not of type boolean an escape message will be send.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Return value:
BooleanBoolean value of the entry
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_getDouble  

Fliesskommazahljson_getDouble(Pointer, Zeichen)
Returns the double value of the entry.

If the entry is not of type double an escape message will be send.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Return value:
Numerisch (Fliesskommazahl) (8,)Double value of the entry
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_getEntryType  

Integerjson_getEntryType(Pointer, Zeichen)
Returns the type of the entry.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Return value:
Numerisch (Integer) (10)Entry type
Exported.

json_getInt  

Integerjson_getInt(Pointer, Zeichen)
Returns the integer value of the entry.

If the entry is not of type integer an escape message will be send.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Return value:
Numerisch (Integer) (10)Integer value of the entry
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_getLong  

Integerjson_getLong(Pointer, Zeichen)
Returns the long value of the entry.

If the entry is not of type long an escape message will be send.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Return value:
Numerisch (Integer) (20)Long value of the entry
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_getNext  

Pointerjson_getNext(Pointer)
Iterates through all JSON entries and returns a pointer to the key of the next entry.

If the iteration ends with the last key *null will be returned.

If the iteration is aborted the calling program should use the abortIteration procedure to reset the iteration.
Parameter:
Pointer   constPointer to the JSON object
Return value:
PointerPointer to the key of the next entry or *null if there are no more entries
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_getObject  

Pointerjson_getObject(Pointer, Zeichen)
Returns a pointer to the object.

If the entry is not of type object an escape message will be send.
Parameter:
Pointer   constPointer to the JSON array
Zeichen (65535)   const   variable sizeIndex
Return value:
PointerPointer to the JSON object
Exported.
Author:
Mihael Schmidt
Date:
11.05.2008

json_getString  

Pointerjson_getString(Pointer, Zeichen)
Returns a pointer to the value of the entry for the passed key. The value is null terminated and can be processed with the %str BIF.

If the entry is not of type string an escape message will be send.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Return value:
PointerPointer to a null-terminated string
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_isEmpty  

Booleanjson_isEmpty(Pointer)
Checks if the JSON object contains no entries at all.
Parameter:
Pointer   constPointer to the JSON object
Return value:
Boolean*on = JSON object is empty
*off = JSON object is not empty
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_isNull  

Booleanjson_isNull(Pointer, Zeichen)
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Return value:
Boolean*on = entry is of type null
*off = entry is of another type
Exported.

json_putArray  

voidjson_putArray(Pointer, Zeichen, Pointer)
Adds an entry of type array.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Pointer   constArray
Exported.
Author:
Mihael Schmidt
Date:
19.04.2008

json_putBoolean  

voidjson_putBoolean(Pointer, Zeichen, Boolean)
Adds an entry of type boolean.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Boolean   constValue
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_putDouble  

voidjson_putDouble(Pointer, Zeichen, Fliesskommazahl)
Adds an entry of type double.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Numerisch (Fliesskommazahl) (8,)   constValue
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_putInt  

voidjson_putInt(Pointer, Zeichen, Integer)
Adds an entry of type integer.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Numerisch (Integer) (10)   constValue
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_putLong  

voidjson_putLong(Pointer, Zeichen, Integer)
Adds an entry of type long.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Numerisch (Integer) (20)   constValue
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_putNull  

voidjson_putNull(Pointer, Zeichen)
Adds an entry of type null to the array.
Parameter:
Pointer   constPointer to the JSON array
Zeichen (65535)   const   variable sizeKey
Exported.
Author:
Mihael Schmidt
Date:
11.05.2008

json_putObject  

voidjson_putObject(Pointer, Zeichen, Pointer)
Adds an entry of type object to the array.
Parameter:
Pointer   constPointer to the JSON array
Zeichen (65535)   const   variable sizeKey
Pointer   constPointer to the JSON object
Exported.
Author:
Mihael Schmidt
Date:
11.05.2008

json_putString  

voidjson_putString(Pointer, Zeichen, Zeichen)
Adds an entry of type character.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeKey
Zeichen (65535)   const   variable sizeValue
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_remove  

voidjson_remove(Pointer, Zeichen)
If the JSON object contains such an entry it will be removed.
Parameter:
Pointer   constPointer to the JSON object
Zeichen (65535)   const   variable sizeEntry key
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_size  

Integerjson_size(Pointer)
Returns the number of entries in the JSON object. The keys of the entries are counted. If the JSON object contains arrays the elements of the arrays are ignored.
Parameter:
Pointer   constPointer to the JSON object
Return value:
Numerisch (Integer) (10)number of entries in the JSON object
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

json_srvpgm_init  

voidjson_srvpgm_init()
String formattings are preloaded.
Exported.

json_toString  

voidjson_toString(Pointer)
Creates a null terminated string representation of the JSON object in JSON syntax.

For entries of type string double quotes and backslashes will be escaped (" => " and => \).
Parameter:
Pointer   constPointer to the JSON object
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008

prettyPrint  

voidprettyPrint()
Exported.

sendDiagnosticMessage  

voidsendDiagnosticMessage(Zeichen)
Sends a diagnostic message to the call stack (one level above this one).
Parameter:
Zeichen (200)   constMessage
Exported.
Author:
Mihael Schmidt
Date:
07.03.2009

sendEscapeMessage  

voidsendEscapeMessage(Integer)
A wrapper for the i5/OS API QMHSNDPM.
Parameter:
Numerisch (Integer) (10)   constMessage id
Exported.
Author:
Mihael Schmidt
Date:
20.03.2008