JSONGETMEMBER

JSONGETMEMBER reads a member (or name-value pair) 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 JSONGETMEMBER is omitted, the name-value pair 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.

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.


>>-JSONGETMEMBER(p,n-+----+-)----------------------------------><
                     '-,x-'

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 name-value pair 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

The name-value pair must consist of the variable's name as a JSON string followed by a colon and the variable's value.

Examples

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

   { "passes" : 3,
     "data" :
       [
            { "name" : "Mather",     "elevation" : 12100 }
          , { "name" : "Pinchot",    "elevation" : 12130 }
          , { "name" : "Glenn",      "elevation" : 11940 }
       ]
   }

When compiled with the option JSON(CASE(ASIS)), the following code allocates an appropriately sized structure and then fills it in. The JSON compiler option is needed so that the names are accepted in lower case.

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

   read = 0;
   read += jsonGetObjectStart(p+read,n-read);
   read += jsonGetMember(p+read,n-read,passes);
   allocate info;
   read += jsonGetComma(p+read,n-read);
   read += jsonGetValue(p+read,n-read,data);
 	 read += jsonGetColon(p+read,n-read);
   read += jsonGetValue(p+read,n-read,data);

Note that this code works equally well if the buffer contains more data. See the following example:

 { "passes" : 5,
     "data" :
       [
            { "name" : "Muir",       "elevation" : 11980 }
          , { "name" : "Mather",     "elevation" : 12100 }
          , { "name" : "Pinchot",    "elevation" : 12130 }
          , { "name" : "Glenn",      "elevation" : 11940 }
          , { "name" : "Forester",   "elevation" : 13100 }
       ]
   }