JSONGETVALUE Function

Purpose

Reads a value from a JSON text.

Syntax

JSONGETVALUE(p,l[,v])

Parameters

p

A pointer specifying the address of the JSON text buffer.

l

Specifies the length in bytes of the JSON text buffer.

v

A reference to a PL/I variable, which may be scalar, array, or a structure or a combination. If it is a structure, it must not contain any elements that have * names, have UNION or GRAPHIC attributes, are scaled FIXED BINARY, or are FIXED DECIMAL (p, q) where q < 0 or q > p.

Description

JSONGETVALUE reads a value (value in name-value pair) from the JSON text buffer and returns the number of bytes read. A JSON value may be one of following:

• A number (integer, decimal number, or floating pint number), e.g. 345.67. It typically maps to any arithmetic item
• A string, which must be enclosed in double quotes e.g. "San Francisco". It typically maps to any character item (VARYING, NONVARYING, VARYINGZ)
• true (all lowercase) for boolean value that is true, typically mapping to BIT
• o false (all lowercase) for boolean value that is false, typically mapping to BIT
• o null (all lowercase) for a null value that will not be assigned to the variable

Examples of name-value pairs include:

• 6
• [ 1, 2, 3, 4, 5 ]
• {"D2": 2, "D5": 5}

• [
       { "No": 1, "Name": "Accident","Place": "Maryland", "Really":true},
       { "No": 2, "Name": "Boring",  "Place": "Oregon",  "Really": true},
       { "No": 3, "Name": "Dull",    "Place": "Scotland","Really": true},
       { "No": 4, "Name": "Noplace", "Place": "England","Really": false},
       { "No": 5, "Name": "Why",     "Place": "Arizona", "Really": true},
       { "No": 6, "Name": "Zzyzx",   "Place":"California","Really":true}
  

The ERROR condition is raised if the JSON text is invalid (for example, the value is invalid, etc.). The ONCODE built-in function tells you why the ERROR condition was raised and the ONSUBCODE built-in function will give you the position of the invalid character, which you can use to examine the invalid character and/or replace it with a valid character.

If the third argument is omitted, the data read is effectively thrown away. If the third argument is present, the data is assigned (after appropriate conversions) to the PL/I variable(s). If the variable has the CHARACTER type, it is converted from UTF-8 to character before assignment.

Examples

For a complete program using various JSON built-in functions, see the last example under JSONPUTVALUE.

Example 1:

 Dcl Array(5) fixed bin(31);

Example 2:

Dcl Towns fixed bin(31);

Example 3:

Suppose the buffer (pointed to by bufp) contains

{"FD":[ {"D2": 2, "D5": 5}, {"D2": 4, "D5": 9}]}, then bytes = jsongetvalue(bufp, bufl s3); will assign data to the structure S3.

dcl 1 S3,
       2 fd(2),
         3 d2 fixed bin(15),
         3 d5 fixed dec(7);

Restrictions

None.