JSONPUTMEMBER Function

Purpose

Adds a member (or name-value pair), as UTF-8, to a JSON text.

Syntax

JSONPUTMEMBER(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

JSONPUTMEMBER encodes the member (name-value pair) to UTF-8 and writes it to the buffer if there is sufficient space. If successful, it returns the number of bytes written. For a description of what a member is, see JSONGETMEMBER.

The ERROR condition is raised if the JSON text buffer has insufficient space to accommodate the member. The ONCODE built-in function tells you why the ERROR condition was raised and the ONSUBCODE built-in function will indicate the number of bytes that were written. The number of bytes actually written will be <= l (second argument).

Examples

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

Example 1:

Suppose Dcl Array(5) fixed bin(31) init(1, 2, 3, 4, 5);, then bytes = jsonputmember (bufp, bufl, Array); will have the following UTF-8 text at the beginning of the buffer: "Array":[1,2,3,4,5] (no spaces).

Example 2:

Suppose Dcl Towns fixed bin(31) init(6);, then bytes = jsonputmember(bufp, bufl, Towns); will have the following UTF-8 text at the beginning of the buffer: "Towns":6

Example 3:

Suppose

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

then bytes = jsonputmember (bufp, bufl, Array); will have the following UTF-8 text at the beginning of the buffer: "S3":{"FD":[{"D2":2,"D5":5},{"D2":4,"D5":9}]}

Restrictions

None.