Accessing JSON-format Data

Overview

JSON is a light-weight data format for transmitting data in JavaScript and many other programing languages. Appeon provides two objects (eon_cjsonnode & eon_cjsonnodearray) to help developers easily handle the JSON-format data. These two objects are supported in PowerServer Web and PowerServer Mobile.

  • eon_cjsonnode is for manipulating the JSON node (a collection of name/value pairs), including parsing names/values from a string, adding/removing name/value pairs, converting the node to a string etc. A JSON node can contain name/value pairs, JSON nodes, and JSON arrays.

    A JSON node begins with left brace ("{") and ends with right brace ("}"), and each name is followed by colon (":") and the name/value pairs are separated by comma (","), for example:

    {
    "firstname": "Brett", 
    "lastname": "Zhang", 
    "email": "brett.zhang@appeon.com" 
    }
  • eon_cjsonnodearray is for manipulating the array values (an ordered list of values) of the JSON node, including parsing values from a string, adding/removing values, converting the array to a string etc. A JSON array can contain values, JSON nodes, and JSON arrays.

    A JSON array begins with left bracket ("[") and ends with right bracket ("]"), and values are separated by comma (","), for example:

    { "people": [
    {"firstname": "Brett", "lastname": "Zhang", "email": "brett.zhang@appeon.com"},
    {"firstname": "Jason", "lastname": "Li", "email": "jason.li@appeon.com"},
    {"firstname": "Mary", "lastname": "Wang", "email": "mary.wang@appeon.com"}
    ] }

eon_cjsonnode

of_addkey

Description

Adds a key (name/value pair) under the current JSON node.

Syntax

of_addkey ( string as_keyname, any aa_keyvalue )

Argument

Description

as_keyname

Name of the new key. When the name already exists, it will be overwritten.

aa_keyvalue

Value of the new key.

Supported data type of the value: long, boolean, string, double, eon_cjsonnode, & eon_cjsonnodearray

Return value

None

of_clearnode

Description

Clears all of the keys (name/value pairs) under the current JSON node.

Syntax

of_clearnode ( )

Return value

None

of_deletekey

Description

Removes a key (name/value pair) from the current JSON node.

Syntax

of_deletekey ( string as_keyname )

Argument

Description

as_keyname

Name of the key to be deleted.

Return value

None

of_getkeybyindex

Description

Gets the name of the key specified by the index.

Syntax

of_getkeybyindex ( integer ai_index )

Argument

Description

ai_index

Value of the index pointing to a key.

Return value

String. The name of the key specified by the index.

Null if the key does not exist.

of_gettypebyindex

Description

Gets the data type of the value specified by the index.

Syntax

of_gettypebyindex ( integer ai_index )

Argument

Description

ai_index

Value of the index pointing to a key.

Return value

Integer. Data type of the value specified by the index:

0 - null

1 - string

2 - number (including long and double)

3 - boolean

4 - eon_cjsonnodearray

5 - eon_cjsonnode

-1 - invalid value

of_gettypebykey

Description

Gets the data type of the value for the specified key name.

Syntax

of_gettypebykey ( string as_keyname )

Argument

Description

as_keyname

Name of the key.

Return value

Integer. Data type of the value.

0 - null

1 - string

2 - number (including long and double)

3 - boolean

4 - eon_cjsonnodearray

5 - eon_cjsonnode

-1 - invalid value

of_load

Description

Loads the JSON-format string into the current JSON node.

Syntax

of_load ( string as_jsonstring )

Argument

Description

as_jsonstring

The JSON-format string. Make sure the string complies with the JSON and JavaScript language standards:

  • The key name is case sensitive.

  • The key name must be included in double quotation marks.

  • The string value must be included in double quotation marks.

  • The boolean values (true/false) must be in lower case.

  • The boolean value, double value, and long value need not be included in double quotation marks.

Return value

Boolean

True - Success.

False - Failed to load.

of_setvalue

Description

Sets the value for the specified key.

Syntax

of_setvalue ( string as_keyname, any aa_keyvalue )

Argument

Description

as_keyname

Name of the key.

aa_keyvalue

Value of the key.

Supported data types include: long, boolean, string, double, eon_cjsonnode, & eon_cjsonnodearray

Return value

None

of_size

Description

Gets the total number of the keys (name/value pairs) under the current JSON node.

Syntax

of_size ( )

Return value

Integer. The total amount of the keys.

-1 - It is called in PowerBuilder, or there is an error.

of_torawstring

Description

Converts the keys (name/value pairs) under the current node to a special JSON-format string. Different from the standard format, the key value in the special format will not be included in double quotation marks automatically. The developer use this function according to the need of excluding double quotes in a key value, for example, to generate the proper date format in a JSON string.

Syntax

of_torawstring ( )

Return value

String. The JSON-format string.

of_tostring

Description

Converts all of the keys (name/value pairs) under the current node to a standard JSON-format string.

Syntax

of_tostring ( )

Return value

String. The JSON-format string.

of_valuearray

Description

Gets the value (array) of the specified key.

Syntax

of_valuearray ( string as_keyname )

Argument

Description

as_keyname

Name of the key.

Return value

eon_cjsonnodearray. The array value (eon_cjsonnodearray object) of the specified key.

Null if the specified key does not exist or the value is not an array.

of_valueboolean

Description

Gets the boolean value of the specified key.

Syntax

of_valueboolean ( string as_keyname )

Argument

Description

as_keyname

Name of the key.

Return value

Boolean. The value of the specified key.

Null if the specified key does not exist or the value is not a boolean.

of_valuedouble

Description

Gets the double value of the specified key.

Syntax

of_valuedouble ( string as_keyname )

Argument

Description

as_keyname

Name of the key.

Return value

Double. The value of the specified key.

Null if the specified key does not exist or the value is not a double.

of_valuelong

Description

Gets the long value of the specified key.

Syntax

of_valuelong ( string as_keyname )

Argument

Description

as_keyname

Name of the key.

Return value

Long. The value of the specified key.

Null if the specified key does not exist or the value is not a long.

of_valuenode

Description

Gets the value (eon_cjsonnode object) of the specified key.

Syntax

of_valuenode ( string as_keyname )

Argument

Description

as_keyname

Name of the key.

Return value

eon_cjsonnode. The value (eon_cjsonnode object) of the specified key.

Null if the specified key does not exist or the value is not an eon_cjsonnode object.

of_valuestring

Description

Gets the string value of the specified key.

Syntax

of_valuestring ( string as_keyname )

Argument

Description

as_keyname

Name of the key.

Return value

String. The value of the specified key.

Null if the specified key does not exist or the value is not a string.

Code examples

To add a JSON node with name/value pairs and convert the node to this string: {"type":"work", "value":"212-555-1234", "pref":"false"}

eon_cjsonnode node2
node2 = Create eon_cjsonnode
node2.of_addkey ("type", "work")
node2.of_addkey ("value", "212-555-1234")
node2.of_addkey ("pref", false)
node2.of_tostring () //exports this node to a string

eon_cjsonnodearray

of_append

Description

Adds a value or an eon_cjsonnode object or an eon_cjsonnodearray object at the end of the array.

Syntax 1

of_append ( any aa_keyvalue )

Argument

Description

aa_keyvalue

Value to be added.

Supported data types include long, boolean, string, double, eon_cjsonnode, & eon_cjsonnodearray.

Syntax 2

of_append ( eon_cjsonnode anvo_node )

Argument

Description

anvo_node

The eon_cjsonnode object to be added.

Syntax 3

of_append ( eon_cjsonnodearray anvo_nodearray )

Argument

Description

anvo_nodearray

The eon_cjsonnodearray object to be added.

Return value

None

of_cleararray

Description

Clears all of the values of the current array.

Syntax

of_cleararray ( )

Return value

None

of_getarraynodebyindex

Description

Gets the value (eon_cjsonnodearray object) specified by the index.

Syntax

of_getarraynodebyindex ( integer ai_index )

Argument

Description

ai_index

Value of the index.

Return value

eon_cjsonnodearray.

Null if the value is not an eon_cjsonnodearray object.

of_getboolbyindex

Description

Gets the boolean value specified by the index.

Syntax

of_getboolbyindex ( integer ai_index )

Argument

Description

ai_index

Value of the index.

Return value

Boolean.

Null if the value is not a boolean.

of_getdoublebyindex

Description

Gets the double value specified by the index.

Syntax

of_getdoublebyindex ( integer ai_index )

Argument

Description

ai_index

Value of the index.

Return value

Double

Null if the value is not a double.

of_getlongbyindex

Description

Gets the long value specified by the index.

Syntax

of_getlongbyindex ( integer ai_index )

Argument

Description

astr_connection

Value of the index.

Return value

Long

Null if the value is not a long.

of_getnodebyindex

Description

Gets the value (eon_cjsonnode object) specified by the index.

Syntax

of_getnodebyindex ( integer ai_index )

Argument

Description

ai_index

Value of the index.

Return value

eon_cjsonnode.

Null if the value is not an eon_cjsonnode object.

of_getstringbyindex

Description

Gets the string value specified by the index.

Syntax

of_getstringbyindex ( integer ai_index )

Argument

Description

ai_index

Value of the index.

Return value

String

Null if the value is not a string.

of_gettypebyindex

Description

Gets the data type of the value specified by the index.

Syntax

of_gettypebyindex ( integer ai_index )

Argument

Description

ai_index

Value of the index.

Return value

Integer. Data type of the value:

0 - null

1 - string

2 - number

3 - boolean (including long and double)

4 - eon_cjsonnodearray

5 - eon_cjsonnode

-1 - Invalid value

of_insertatindex

Description

Inserts a value or an eon_cjsonnode object or an eon_cjsonnodearray object at the position specified by the index.

Syntax 1

of_insertatindex ( integer ai_index, any aa_keyvalue )

Argument

Description

ai_index

Value of the index.

aa_keyvalue

The key value to be inserted.

Support data types include long, boolean, string, double, eon_cjsonnode, & eon_cjsonnodearray.

Syntax 2

of_insertatindex ( integer ai_index, eon_cjsonnode anvo_node )

Argument

Description

ai_index

Value of the index.

anvo_node

The eon_cjsonnode object to be inserted.

Syntax 3

of_insertatindex ( integer ai_index, eon_cjsonnodearray anvo_nodearray )

Argument

Description

ai_index

Value of the index.

anvo_nodearray

The eon_cjsonnodearray object to be inserted.

Return value

None

of_load

Description

Loads the JSON-format string into the current array.

Syntax

of_load ( string as_jsonstring )

Argument

Description

as_jsonstring

The JSON-format string. Make sure the string complies with the JSON and JavaScript language standards.

Return value

Boolean

True - Success.

False - Failed to load.

of_removebyindex

Description

Removes the value specified by the index.

Syntax

of_removebyindex ( integer ai_index )

Argument

Description

ai_index

Value of the index.

Return value

None

of_size

Description

Gets the total amount of the values in the array.

Syntax

of_size ( )

Return value

Integer. The total amount of values in the array.

-1 - It is called in PowerBuilder, or there is an error.

of_tostring

Description

Converts the array to the standard JSON-format string.

Syntax

of_tostring ( )

Return value

String. The standard JSON-format string.

Code examples

To add a JSON array with string values and convert the array to this string: ["displayName","organizations"]

eon_cjsonnodearray  array1
array1 = create  eon_cjsonnodearray
array1.of_append ( "displayName" )
array1.of_append ( "organizations" )
array1.of_tostring () //exports this array to a string

To add a JSON array with values of various types and convert the array to this string: [{"type":"work", "value":"212-555-1234", "pref":"false"}, {"type":"mobile", "value":"917-555-5432", "pref":"false"}, {"type":"home", "value":"203-555-7890", "pref ":"false"}]

eon_cjsonnodearray   array2
array2 = create eon_cjsonnodearray
eon_cjsonnode node2
node2 = Create eon_cjsonnode
node2.of_addkey ("type", "work")
node2.of_addkey ("value", "212-555-1234")
node2.of_addkey ("pref", false)
array2.of_append (node2)
node2.of_setvalue ("type", "mobile")
node2.of_setvalue ("value", "917-555-5432")
node2.of_setvalue ("pref", true)
array2.of_append (node2)
node2.of_setvalue ("type", "home")
node2.of_setvalue ("value", "203-555-7890")
node2.of_setvalue ("pref", false)
array2.of_append (node2)
array2.of_toString() //exports this array to a string