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 the JSON text, but is ignored except for contributing to the total number of bytes read.

If the JSON text contains invalid JSON, 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 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.

Under the compiler option JSON(PARSE(V1)):

If the JSON source specifies more values for an array than in the target declaration, then the ERROR condition will be raised (reporting that a closing bracket ] was not found when expected)
If the third argument is a structure, then 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.

Under the compiler option JSON(PARSE(V2)):

If the JSON source specifies more values for an array than in the target declaration:
- If SUBSCRIPTRANGE is enabled, then the SUBSCRIPTRANGE condition will be raised
- Otherwise, the excess values will be ignored
If the third argument is a structure and a name in the JSON text does not match any name in the structure:
- If CONFORMANCE is enabled, then the CONFORMANCE condition will be raised and the ONJSONNAME built-in function will return the unmatched name
- Otherwise, the name and its JSON-value will be ignored

Note: It is not necessary to specify name-value pairs for all the elements in the structure, and it is not necessary that the names are specified in the same order as they are in the structure.

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

x may have STRUCTURE type.

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 );