JSONGETVALUE

JSONGETVALUE reads a value from a piece of JSON text. This function returns a size_t ¹ value that specifies the number of bytes read from the buffer.

Whitespace is permitted anywhere in JSON text, but is ignored except for contributing to the total number of bytes read.

If the JSON text is invalid, the ERROR condition is raised and the ONSUBCODE built-in function gives the index of the invalid character.

If the third argument of JSONGETVALUE is omitted, the value is simply read over.

If the third argument is a structure, the names in the JSON text must match those in the structure. If not, the ERROR condition is raised.

Note: It is not necessary to specify name-value pairs for all the elements in the structure, but any names specified must be in the same order as they are in the structure.

If the third argument is an array, array values can be omitted in which case the corresponding elements of the target array are unchanged.

If any element in the target has the CHARACTER type, the conversion from the UTF-8 source in the JSON text is based on the CODEPAGE compiler option.

p

A pointer that specifies the address of a buffer to be read

n

A size_t value that specifies the number of available bytes in the buffer

x

A variable reference whose value is to be read from the buffer

The variable reference must not contain any of these elements:

UNIONs
Noncomputational elements
GRAPHIC elements
COMPLEX elements
FIXED(p,q) elements with q < 0 or q > p
Unnamed elements

Example 1

The following code assigns the values 2, 3, and 5 to the array B. The value returned would be 7 plus the count of whitespace characters before the closing bracket, ].

  dcl b(3)    fixed bin;
  dcl buffer  char(1000) var;
  dcl p       pointer;
  dcl n       fixed bin(31);


  buffer = utf8( ' [ 2, 3, 5 ]' );
  p = addrdata(buffer);
  n = length(buffer);
  read = jsonGetValue( p, n, b );

Example 2

The following code assigns the values 2 to B(1), 3 to B(2), and leaves B(3) unchanged. The value returned would be 5 plus the count of whitespace characters before the closing bracket, ].

  dcl b(3)    fixed bin;
  dcl buffer  char(1000) var;
  dcl p       pointer;
  dcl n       fixed bin(31);


  buffer = utf8( ' [ 2, 3 ]' );
  p = addrdata(buffer);
  n = length(buffer);
  read = jsonGetValue( p, n, b );

Example 3

The following code assigns 2 to C.D and 3 to C.E. It returns a value greater than or equal to 13.

  dcl 1 c, 2 d fixed bin, 2 e fixed bin;
  dcl buffer  char(1000) var;
  dcl p       pointer;
  dcl n       fixed bin(31);

  buffer = utf8( ' { "D" : 2, "E" : 3 } ' );
  p = addrdata(buffer);
  n = length(buffer);
  read = jsonGetValue( p, n, c );

Example 4

Suppose that a buffer contains the following JSON text, and that the buffer address is P and its length is in N.

   { "PASSES" : 3,
     "DATA" :
       [
            { "NAME" : "Mather",  "ELEVATION" : 12100 }
          , { "NAME" : "Pinchot", "ELEVATION" : 12130 }
          , { "NAME" : "Glenn",   "ELEVATION" : 11940 }
       ]
   }

Then the single invocation of JSONGETVALUE in the following code will fill in the entire structure.

   dcl
     1 info,
       2 passes       fixed bin(31),
       2 data(3),
         3 name       char(20) varying,
         3 elevation  fixed bin(31);

   read = jsonGetValue( p, n, info );