1. XML C API Reference
  2. JSON DOM Interfaces

17 JSON DOM Interfaces

The JSON Interface for DOM C APIs are grouped into the following sections:

17.1 JSON DOM Functions

The following table summarizes the methods available through the JSON interface of DOM for C APIs.

Table 17-1 Summary of DOM Methods for JSON C Implementation

Function Summary

JsonDomGetRoot

Returns the root node of a DOM, which is one of the three types of nodes.

JsonDomSetRoot

Sets the specified node as the root.

JsonDomGetNumFields

Returns the number of fields within the object.

JsonDomGetArraySize

Returns the number of elements within the array.

JsonDomGetElements

Returns a set of elements from an array in a batch interface.

JsonDomGetNodeType

Returns the type of the node.

JsonDomGetScalarInfoOci

Returns the value information from the scalar node.

JsonDomCreateObject

Creates a new orphan DOM object node.
JsonDomCreateOCIInterval Creates a new DOM scalar node of OCIInterval type.

JsonDomCreateArray

Creates a new orphan DOM array node.

JsonDomCreateString

Creates a new orphan DOM scalar node of string type.

JsonDomCreateBinary

Creates a new orphan DOM scalar node of binary type.

JsonDomCreateFloat

Creates a new orphan DOM scalar node of float type.

JsonDomCreateDouble

Creates a new orphan DOM scalar node of double type.

JsonDomCreateBoolean

Creates a new orphan DOM scalar node of boolean type.

JsonDomCreateOCINumber

Creates a new orphan DOM scalar node of NUMBER type from an OCINumber input.

JsonDomCreateOCIDate

Creates a new orphan DOM scalar node of date type.

JsonDomCreateOCIDateTime

Create a new orphan DOM scalar node of type DATE, TIMESTAMP, or TIMESTAMP WITH TIME ZONE from an OCIDateTime type.

JsonDomCreateNull

Creates a new orphan DOM scalar node of null type.

JsonDomSetField

Sets the value of the specified field to the specified object within DOM.

JsonDomAppendElement

Append an orphan node as a new element in an array, at the last position within the array.

JsonDomFreeNode

Free an orphan node and all its descendants.

JsonDomGetError

Returns an error code for a DOM operation that failed.

JsonDomClearError

Clear the error code for the DOM.

JsonDomGetErrorMessage

Returns a rendered error message for the current DOM error code.

17.1.1 JsonDomGetRoot()

Returns the root node of a DOM, which is one of the three types of nodes (although rare, a scalar with no children is a valid JSON document per the RFC).

Syntax

JsonDomNode *JsonDomGetRoot(
      JsonDomDoc    *jdoc
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

Returns

(JsonDomNode *) root node for the DOM (or NULL if none is set).

Note:

  • The orphan nodes cannot be accessed by descending the tree starting from the root.
  • Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.2 JsonDomSetRoot()

Sets the specified node as the root.

The new node may be a NULL. The new root must be an orphan node, that is, it cannot be a node that exists within the tree descending from the old root, if any.

Orphan nodes are created by constructors, or by copying node(s) from another DOM document, or by unlinking them from the DOM tree.

Syntax

void  JsonDomSetRoot(  
    JsonDomDoc     *jdoc,
    JsonDomNode    *root
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
root
 
IN

Orphan node within the DOM

Returns

(ub4) A count of the number of fields within the object.

Note:

  • The old root and all descendants are freed.
  • Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.3 JsonDomGetNumFields()

Returns the number of fields within the object.

Syntax

ub4 JsonDomGetNumFields(  
    JsonDomDoc     *jdoc,  
    JsonDomObject  *obj
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
obj
 
IN

Object node within the DOM

Returns

(ub4) A count of the number of fields within this object.

17.1.4 JsonDomGetArraySize()

Returns the number of elements within the array.

Orphan nodes are created by constructors, or by copying node(s) from another DOM document, or by unlinking them from the DOM tree.

Syntax

ub4 JsonDomGetArraySize(  
    JsonDomDoc *jdoc,
    JsonDomArray *ary
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
ary
 
IN

Array node within the DOM

Returns

(ub4) A count of the number of elements within this array.

Note:

  • Duplicate field names are not allowed in most DOMs.
  • Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.5 JsonDomGetElements()

Returns a set of elements from an array in a batch interface.

This allows a caller to use a fixed-sized array to iterate over the elements, while still retrieving them in bulk.

Syntax

ub4 JsonDomGetElements(
  JsonDomDoc      *jdoc,
  JsonDomArray    *ary,
  ub4              startPos,
  ub4              fetchSz,
  JsonDomNode     *ndary[]
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
ary
 
IN

Array node within the DOM

 
startPos
 
IN

Starting position (0-based)

 
fetchSz
 
IN

Number of elements to retrieve

 
ndary
 
OUT

Returns nodes from the array

Returns

(ub4) The number of elements returned in the output node array.

Note:

  • The first element at start position 0. The iteration is backed directly by the DOM array, so this interface won't work properly if the array undergoes modification during the iteration.
  • Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.6 JsonDomGetNodeType()

Returns the type of a node.

The possible return values are:

  • JZNDOM_SCALAR
  • JZNDOM_ARRAY
  • JZNDOM_OBJECT

The node may be safely cast to the subclass type. For example, if the return is JZNDOM_SCALAR, the node may be cast to (JsonDomScalar *).

Syntax

jznnodetype JsonDomGetNodeType(
  JsonDomDoc     *jdoc,
  JsonDomNode    *node
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
node
 
IN

Node within the DOM

Returns

(jznnodetype) the type of node (Object, Array, Scalar).

Note:

Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.7 JsonDomGetScalarInfoOci()

Returns a scalar value in the val structure that must be applied by the caller, often a pointer to a local variable in the calling code.

The return structure is a discriminated union. The value's scalar subtype (for example, JZNVAL_NUMBER) is available as the first member, and the scalar's actual value can be read from the appropriate union member.

Syntax

jsonerr  JsonDomGetScalarInfoOci(
  JsonDomDoc       *jdoc,
  JsonDomScalar    *nd,
  jznScalarVal     *val,
  JsonOCIVal       *aux
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
nd
 
IN

Scalar node within the DOM

 
val
 
OUT

Output scalar value

 
aux
 
OUT

Auxiliary output structure

Returns

(jsonerr) An error code. JZNERR_OK (0) indicates no error.

Note:

  • Oracle native types are unpickled and returned in structured form in auxiliary union of type JsonOCIVal*.
  • Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.8 JsonDomCreateObject()

Creates a new DOM object node.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomObject *JsonDomCreateObject(
  JsonDomDoc    *jdoc
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

Returns

(JsonDomObject *) new orphaned DOM object node.

17.1.9 JsonDomCreateOCIInterval()

Creates a new DOM scalar node of OCIInterval type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomScalar *JsonDomCreateOCIInterval(
  JsonDomDoc     *jdoc,
  OCIInterval    *oinv
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
oinv
 
IN

OCIInterval Pointer

Returns

(JsonDomScalar *) new orphaned DOM scalar node.

17.1.10 JsonDomCreateArray()

Creates a new DOM array node.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomArray *JsonDomCreateArray(
  JsonDomDoc *jdoc
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

Returns

(JsonDomArray *) new orphaned DOM array node.

17.1.11 JsonDomCreateString()

Creates a new DOM scalar node of string type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node. The scalar is set to the value of the string argument sval, which is of length slen.

Syntax

JsonDomScalar *JsonDomCreateString(
  JsonDomDoc      *jdoc,
  oratext         *sval,
  ub4              slen
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
sval
 
IN

String buffer pointer

 
slen
 
IN

Length of the string buffer in bytes

Returns

(JsonDomScalar *) new orphaned DOM scalar node

Note:

The string is copied into the DOM's memory space.

17.1.12 JsonDomCreateBinary()

Creates a new DOM scalar node of binary type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node. The scalar is set to the contents of the byte array bval of length blen.

Syntax

JsonDomScalar *JsonDomCreateBinary(
  JsonDomDoc      *jdoc,
  oratext         *bval,
  ub4              blen
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
bval
 
IN

Binary buffer pointer

 
blen
 
IN

Length of the binary buffer

Returns

(JsonDomScalar *) new orphaned DOM scalar node

Note:

The binary value is copied into the DOM's memory space.

17.1.13 JsonDomCreateFloat()

Creates a new DOM scalar node of float type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node. The scalar is set to the float value fval.

Syntax

JsonDomScalar *JsonDomCreateFloat(
  JsonDomDoc      *jdoc,
  float            fval
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
fval
 
IN

Float value

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.14 JsonDomCreateDouble()

Creates a new DOM scalar node of double type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node. The scalar value is set to the double value dval.

Syntax

JsonDomScalar *JsonDomCreateDouble(
  JsonDomDoc      *jdoc,
  double           dval
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
dval
 
IN

Double value

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.15 JsonDomCreateBoolean()

Creates a new DOM scalar node of boolean type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomScalar *JsonDomCreateBoolean(
  JsonDomDoc      *jdoc,
  boolean          bval
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
bval
 
IN

Boolean value

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.16 JsonDomCreateOCINumber()

Creates a new DOM scalar node of NUMBER type from an OCINumber.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomScalar *JsonDomCreateOCINumber(
  JsonDomDoc      *jdoc,
  OCINumber       *onum
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
onum
 
IN

OCINumber pointer

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.17 JsonDomCreateOCIDate()

Creates a new DOM scalar node of DATE type from an OCIDate.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomScalar *JsonDomCreateOCIDate(
  JsonDomDoc      *jdoc,
  OCIDate         *odate
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
odate
 
IN

OCIDate pointer

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.18 JsonDomCreateOCIDateTime()

Creates a new DOM scalar node of DATE, TIMESTAMP or TIMESTAMP WITH TIME ZONE type from an OCIDateTime.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomScalar *JsonDomCreateOCIDateTime(
  JsonDomDoc      *jdoc,
  OCIDateTime     *odtime
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
odtime
 
IN

OCIDateTime pointer

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.19 JsonDomCreateNull()

Creates a new DOM scalar node of JSON null type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomScalar *JsonDomCreateNull(
  JsonDomDoc      *jdoc
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.20 JsonDomSetField()

Sets the value of the specified field to the specified object within DOM.

The field is created if it doesn't exist, otherwise the old value is replaced.

Syntax

jsonerr JsonDomSetField(
  JsonDomDoc       *jdoc,
  JsonDomObject    *obj,
  oratext          *name,
  ub2               namelen,
  JsonDomNode      *node);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
obj
 
IN

Object within the DOM

 
name
 
IN

String with field name to create or replace

 
namelen
 
IN

Length of field name string

 
node
 
IN

Orphan node to set as field value

Returns

(jsonerr) An error code. JZNERR_OK (0) indicates no error.

Note:

The old field value, if any, is freed along with all descendants.

17.1.21 JsonDomAppendElement()

Appends an orphan node as a new element in an array, at the last position within the array.

This function is equivalent to calling JsonDomAddElement and giving the array size as the insertion position.

Syntax

boolean JsonDomAppendElement(
  JsonDomDoc      *jdoc,
  JsonDomArray    *arr,
  JsonDomNode     *node
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
arr
 
IN

Array within the DOM

 
node
 
IN

Orphan node to set an element value

Returns

(boolean). TRUE if the element was appended, else FALSE.

Note:

  • Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.22 JsonDomFreeNode()

Free an orphan node and all descendants.

Syntax

boolean JsonDomFreeNode(
  JsonDomDoc     *jdoc,
  JsonDomNode    *node
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
node
 
IN

Node to free within the DOM

Returns

(boolean). TRUE if freed, FALSE if not an orphan.

Note:

The old field value, if any, is freed along with all descendants.

17.1.23 JsonDomGetError()

Returns an error code for a DOM operation that failed.

Syntax

jsonerr JsonDomGetError(
  JsonDomDoc     *jdoc
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

Returns

(jsonerr) An error code. JZNERR_OK (0) indicates no error.

17.1.24 JsonDomGetErrorMessage()

Returns a rendered error message for the current DOM error code.

Syntax

oratext *JsonDomGetErrorMessage(
  JsonDomDoc    *jdoc,
  jsonerr       *err,
  boolean        clear
);

Returns an empty string if there is no current error. Returns the current error code in the optional <err> argument. If <clear> is TRUE, the internal error in the document is cleared.

Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

 
err
 
OUT

Error code or JZNERR_OK (0) for none 

clear
 
IN

TRUE to clear error after reading

Returns

(oratext *) error message string, NULL on memory error.

17.1.25 JsonDomClearError()

Clear the error code for the DOM.

Syntax

void JsonDomClearError(
  JsonDomDoc     *jdoc
);
Parameter In/Out Description 
jdoc
 
IN

JSON DOM Container

Returns

(void)

17.2 Constants

The below tables list the different types of constants in JSON.

DOM Node Type Constants

Constant Description 
JZNDOM_OBJECT

Indicates that the DOM node is of object type

 
JZNDOM_ARRAY

Indicates that the DOM node is of array type

 
JZNDOM_SCALAR

Indicates that the DOM node is of scalar type

Scalar Value Type Constants

Constant JSON Value Type 
JZNVAL_STRING

String

 
JZNVAL_ORA_NUMBER

Number

 
JZNVAL_TRUE

Boolean true

 
JZNVAL_FALSE

Boolean false

 
JZNVAL_BINARY

Binary

 
JZNVAL_DOUBLE

Double

 
JZNVAL_FLOAT

Float

 
JZNVAL_ORA_DATE

Date

 
JZNVAL_ORA_TIMESTAMP

Timestamp

 
JZNVAL_ORA_DAYSECOND_DUR

Day-second Interval

 
JZNVAL_ORA_YEARMONTH_DUR

Year-month interval

 
JZNVAL_ORA_TIMESTAMPTZ

Timestamp with time zone

 
JZNVAL_NULL

JSON null

Note:

The constants JZNVAL_DOUBLE and JZNVAL_FLOAT map to IEEE FLOAT and DOUBLE respectively, which are most commonly used in programming languages.

JSON Validation Constants

Constant Description 
JZN_ALLOW_NONE

Strict conformance to JSON specification.

 
JZN_ALLOW_UNQUOTED_NAMES

Object field names can appear without being enclosed in double quotes. Example: {a: 123}

 
JZN_ALLOW_SINGLE_QUOTES

Field names and string items can optionally be enclosed in single quote marks. Example: {'a': 'cat'}

 
JZN_ALLOW_UNQUOTED_UNICODE

Allow non-ASCII characters to appear in unquoted field names.

 
JZN_ALLOW_NUMERIC_QUIRKS

Allow common numeric formats that are not strictly conforming to JSON specification. Example: +.123

 
JZN_ALLOW_CONTROLS_WHITESPACE
 Allow ASCII control characters to appear where insignificant whitespace is allowed (normally restricted to tab, newline, carriage-return). Example: a form-feed character 
JZN_ALLOW_TRAILING_COMMAS

Allow a trailing comma to appear in a container without a following item or field/value pair. Example: [1,2,3,]

 
JZN_ALLOW_MIXEDCASE_KEYWORDS

Allow keywords to appear in any case. Normally they are required to be in lower case. Examples: NULL, True

 
JZN_ALLOW_SCALAR_DOCUMENTS

Allow a single scalar item to be considered a valid JSON document. The older RFC required that a document be one of the two container types. The newer RFC allows any item, which includes scalars.

 
JZN_ALLOW_LEADING_BOM

Allow a byte-order-mark to appear as the first character of a JSON document, even if the document is encoded in UTF-8. Normally it's restricted to UTF-16 documents only.

 
JZN_ALLOW_ALL

Turns on all of the above flags.

Note:

The JSON validation constants are bit flags and they can be used in combination.

JSON Encoding Constants

Constant Description 
JZN_INPUT_UTF8

Input is UTF-8 encoding

 
JZN_INPUT_DETECT

Encoding of the input needs to be detected

 
JZN_INPUT_CONVERT

Input requires character set conversion

JSON Printing Constants

Constant Description 
JZNU_PRINT_PRETTY

Render textual JSON pretty printed

 
JZNU_PRINT_ASCII

Render textual JSON with native ASCII, with escape

 
JZNU_PRINT_NUMFORMAT

Render textual JSON with numbers printed canonically