JSONGETMEMBER

JSONGETMEMBER reads a member (or name-value pair) from a piece of JSON text. This function returns a size_t 1 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 JSONGETMEMBER is omitted, the name-value pair is simply read over.

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.
Read syntax diagramSkip visual syntax diagramJSONGETMEMBER( 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

x may have STRUCTURE type.

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