1. Programmer's Guide
  2. OCI Json Descriptor Functions

36 OCI Json Descriptor Functions

This chapter describes the OCIJson Descriptor functions.

This chapter contains these topics:

36.1 Functions for Writing to a JSON Descriptor

Lists functions for writing to a JSON descriptor described in this chapter.

Function Purpose
OCIJsonDomDocSet Deep-copies the JSON DOM Document container and sets the new JSON DOM document in the descriptor.
OCIJsonTextBufferParse

Parses a JSON text buffer of fixed size in the descriptor and manifests the binary image in a form specified by the mode.

OCIJsonTextStreamParse

Parses a JSON read orastream of fixed size in the descriptor and manifests the binary image in a form specified by the mode.

OCIJsonBinaryBufferLoad

Loads a binary image (encoded JSON) from a buffer into the descriptor.

OCIJsonBinaryStreamLoad

Loads a binary image (encoded JSON) from a stream into the descriptor.

OCIJsonClone

Clones the descriptor. Can be used to deep copy a JSON descriptor from one image form to the other.

36.1.1 OCIJsonDomDocSet ()

Deep-copies the JSON DOM Document container and sets the new JSON DOM document in the descriptor.

Purpose

Deep-copies the JSON DOM Document container and sets the new JSON DOM document in the descriptor.

Syntax

sword OCIJsonDomDocSet (
      void        *hndlp, 
      OCIJson     *jsond,  
      JsonDomDoc  *jDomDoc,  
      OCIError    *errhp,  
      ub4          mode 
);

Parameters

Parameter Mode Description
hndlp IN

An allocated OCI Service Context handle or working OCI Environment handle.
jsond IN/OUT

An allocated OCI JSON descriptor.
jDomDoc OUT JSON DOM document container.
errhp IN/OUT

An allocated OCI error handle. If there is an error, it is recorded in err parameter and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet() function.

mode IN
Specifies the mode of execution.

  • OCI_DEFAULT — Is the default mode.

Returns

  • OCI_SUCCESS, if the document is set successfully.
  • OCI_ERROR, in case of an error during execution. OCIError parameter has the necessary error information.

Usage Notes

  • The properties of the source JSON DOM document are preserved in the descriptor. It is the responsibility of the user to free the DOM document pointer that is supplied as the input.
  • A subsequent read function can be called on this descriptor, only if the write operation succeeded without errors. The descriptor is not restored to its previous state if the operation failed.
  • If the supplied handle is OCI service context handle, then the function serializes the calls on that handle.

36.1.2 OCIJsonTextBufferParse ()

Parses a JSON text buffer of fixed size and writes to the descriptor.

Purpose

To parse a JSON text buffer of fixed size and write to the descriptor.

Syntax

sword OCIJsonTextBufferParse (
      void        *hndlp, 
      OCIJson     *jsond,  
      void        *bufp,  
      oraub8       buf_sz,  
      ub4          validation,  
      ub2          encoding,  
      OCIError    *errhp,  
      ub4          mode 
);

Parameters

Parameter Mode Description
hndlp IN

An allocated OCI Service Context handle or working OCI Environment handle.

bufp IN

Pointer to the input buffer.
buf_sz IN Size of the input buffer, in bytes.
validation IN

Parser validation mode. For more information, refer to "JSON Validation Constants" section in "XML C API Reference" guide.
encoding IN

Textual character set encoding of JSON. For more information, refer to "JSON Encoding Constants" section in "XML C API Reference" guide.
errhp IN/OUT

An allocated OCI error handle. If there is an error, it is recorded in err parameter and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet() function.

mode IN
Specifies the mode of execution.

  • OCI_DEFAULT — Is the default mode.

Returns

  • OCI_SUCCESS, if the buffer contained a valid JSON content.
  • OCI_SUCCESS_WITH_INFO, if input textual JSON is NULL.
  • OCI_ERROR, in case of an error during execution. OCIError parameter has the necessary error information.

Usage Notes

  • Each time a write function is called on a descriptor, any pre-existing populated DOM container is freed automatically.
  • A subsequent read function can be called on this descriptor only if this write function succeeded without errors.
  • If the supplied handle is OCI service context handle, then the function serializes the calls on that handle.

See Also:

36.1.3 OCIJsonTextStreamParse ()

Parses textual JSON from a read orastream and writes to the descriptor.

Purpose

To parses textual JSON from a read orastream and write to the descriptor.

Syntax

sword OCIJsonTextStreamParse (
      void         *hndlp, 
      OCIJson      *jsond,  
      orastream    *r_stream,  
      ub4           validation,  
      ub2           encoding,  
      OCIError     *errhp,  
      ub4           mode 
);

Parameters

Parameter Mode Description
hndlp IN

An allocated OCI Service Context handle or working OCI Environment handle.

jsond IN/OUT

An allocated OCI JSON descriptor.
r_stream IN

Pointer to the orastream (read stream) input. For more information, refer to "Package orastream for C APIs" section in "XML C API Reference" guide.

validation IN

Parser validation mode. For more information, refer to "JSON Validation Constants" section in "XML C API Reference" guide.
encoding IN

Textual character set encoding of JSON. For more information, refer to "JSON Encoding Constants" section in "XML C API Reference" guide.

errhp IN/OUT

An allocated OCI error handle. If there is an error, it is recorded in err parameter and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet() function.

mode IN
Specifies the mode of execution.

  • OCI_DEFAULT — Is the default mode.

Returns

  • OCI_SUCCESS, if the read stream contains a valid JSON.
  • OCI_SUCCESS_WITH_INFO, if input textual JSON is NULL.
  • OCI_ERROR, in case of an error during execution. OCIError parameter has the necessary error information.

Usage Notes

  • Each time a parse function is called on a descriptor, any pre-existing populated DOM tree is freed automatically.
  • A subsequent read function can be called on this descriptor only if this write function succeeded without errors.
  • If the input read stream is not open, it is opened automatically. It is the responsibility of the user to close it.
  • If the supplied handle is OCI service context handle, then the function serializes the calls on that handle.

See Also:

36.1.4 OCIJsonBinaryBufferLoad ()

Loads a binary image (encoded JSON) from a buffer into the descriptor.

Purpose

To load a binary image (encoded JSON) from a buffer into the descriptor. 

sword OCIJsonBinaryBufferLoad ( 
      void         *hndlp, 
      OCIJson      *jsond,  
      ub1          *bufp,  
      oraub8        buf_sz,  
      OCIError     *errhp,  
      ub4           mode 
);

Parameters

Parameter Mode Description
hndlp IN

An allocated OCI Service Context handle or working OCI Environment handle.

jsond IN/OUT

An allocated OCI JSON descriptor.
bufp IN

Pointer to the input buffer.

buf_sz IN

Size of the input buffer, in bytes.

errhp IN/OUT

An allocated OCI error handle. If there is an error, it is recorded in err parameter and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet () function.

mode IN
Specifies the mode of execution.

  • OCI_DEFAULT — Is the default mode.

Returns

  • OCI_SUCCESS, if the buffer contained a valid JSON content.
  • OCI_SUCCESS_WITH_INFO, if input textual JSON is NULL.
  • OCI_ERROR, in case of an error during execution. OCIError parameter has the necessary error information.

Usage Notes

  • Each time a write function is called on a descriptor, any pre-existing populated DOM container is freed automatically.
  • A subsequent read function can be called on this descriptor only if this write function succeeded without errors.
  • If the input read stream is not open, it is opened automatically. It is the responsibility of the user to close it.
  • If the supplied handle is OCI service context handle, then the function serializes the calls on that handle.

36.1.5 OCIJsonBinaryStreamLoad ()

Loads a binary image (encoded JSON) from a stream into the descriptor.

Purpose

To load a binary image (encoded JSON) from a stream into the descriptor.

Syntax

sword OCIJsonBinaryStreamLoad ( 
      void         *hndlp, 
      OCIJson      *jsond,  
      orastream    *r_stream,  
      oraub8        buf_sz,  
      OCIError     *errhp,  
      ub4           mode 
);

Parameters

Parameter Mode Description
hndlp IN

An allocated OCI Service Context handle or working OCI Environment handle.

jsond IN/OUT

An allocated OCI JSON descriptor.
r_stream IN

Pointer to the orastream (read stream) input. For more information, refer to "Package orastream for C APIs" section in "XML C API Reference" guide.
errhp IN/OUT

An allocated OCI error handle. If there is an error, it is recorded in err parameter and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet () function.

mode IN
Specifies the mode of execution.

  • OCI_DEFAULT — Is the default mode.

Returns

  • OCI_SUCCESS, if the read stream contained a valid JSON.
  • OCI_SUCCESS_WITH_INFO, if input textual JSON is NULL.
  • OCI_ERROR, in case of an error during execution. OCIError parameter has the necessary error information.

Usage Notes

  • Each time a write function is called on a descriptor, any pre-existing populated DOM container is freed automatically.
  • A subsequent read function can be called on this descriptor only if this write function succeeded without errors.
  • If the input read stream is not open, it is opened automatically. It is the responsibility of the user to close it.
  • If the supplied handle is OCI Service context handle, then the function serializes the calls on that handle.

See Also:

Package orastream for C APIs

36.1.6 OCIJsonClone ()

Clones the descriptor and its associated JSON content.

Purpose

To clone the descriptor and its associated JSON content.

sword OCIJsonClone ( 
      OCISvcCtx    *svchp, 
      OCIJson      *src_jsond,  
      OCIJson      *dest_jsond,  
      OCIError     *errhp,  
      ub4           mode 
);

Parameters

Parameter Mode Description
svchp IN

An allocated OCI Service Context handle.
src_jsond IN

A valid source JSON Document descriptor.
dest_jsond IN/OUT

Destination locator, allocated and data copied from the source.

errhp IN/OUT

An allocated OCI error handle. If there is an error, it is recorded in err parameter and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet () function.

mode IN
Specifies the mode of execution.

  • OCI_DEFAULT — Is the default mode.

Returns

  • OCI_SUCCESS, if the document was cloned successfully.
  • OCI_ERROR, in case of an error during execution. OCIError parameter has the necessary error information.

Usage Notes

  • Can be used to deep copy a JSON descriptor from source to destination, altering the image form to the other.
  • Each time a write function is called on a descriptor, any pre-existing populated DOM container is freed automatically.
  • A subsequent read function can be called on this descriptor only if this write function succeeded without errors.
  • If the input read stream is not open, it is opened automatically. It is the responsibility of the user to close it.
  • The function serializes the calls on the provided service context handle.

36.2 Functions for Reading from a JSON Descriptor

Lists functions for reading from a JSON descriptor .

Function Purpose
OCIJsonDomDocGet Returns the DOM Document container from a descriptor and manifests the binary image in a form specified by the mode.
OCIJsonToTextBuffer

Returns the textual string representation of the JSON content in the descriptor. The textual string is written to the buffer of the user.

OCIJsonToTextStream

Returns the textual string representation of the JSON content in the descriptor. The textual string is written to the write stream of the user.

OCIJsonToBinaryBuffer

Returns the binary image bytes from a JSON document descriptor into the buffer of the user.

OCIJsonToBinaryStream

Returns the binary image bytes from a JSON document descriptor into the write-stream of the user.

OCIJsonBinaryLengthGet

Returns the size of the binary representation of JSON in bytes.

36.2.1 OCIJsonDomDocGet ()

Returns the DOM Document container from a descriptor similar to the form set in the descriptor.

Purpose

To get the DOM document container from a descriptor similar to the form set in the descriptor. 

sword OCIJsonDomDocGet ( 
      OCISvcCtx    *svchp, 
      OCIJson      *jsond,  
      JsonDomDoc  **jDomDoc,  
      OCIError     *errhp,  
      ub4           mode 
);

Parameters

Parameter Mode Description
svchp IN

An allocated OCI Service Context handle.

jsond IN

An allocated OCI JSON descriptor.
jDomDoc OUT JSON DOM document container pointed to by the JSON descriptor.
errhp IN/OUT

An allocated OCI error handle. If there is an error, it is recorded in err parameter and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet() function.

mode IN
Specifies the mode of execution.

  • OCI_DEFAULT — Is the default mode.

Returns

  • OCI_SUCCESS, if the document is successfully returned.
  • OCI_SUCCESS_WITH_INFO, if the OCIJson descriptor was empty.
  • OCI_ERROR, in case of an error during execution. OCIError parameter has the necessary error information.

Usage Notes

  • By default, the function returns a document container (JsonDomDoc *) in the mode specified earlier. If it was never specified earlier, the function returns an immutable DOM.
  • The JSON DOM container returned by this function is bound to the descriptor and should not be explicitly freed by the user. It is automatically freed when the JSON descriptor is freed.
  • The function serializes the calls on the provided service context handle.

36.2.2 OCIJsonToTextBuffer ()

Returns the textual string representation of the JSON content in the descriptor. The textual string is written to the buffer of the user.

Purpose

To return the textual string representation of the JSON content in the descriptor.

sword OCIJsonToTextBuffer ( 
      OCISvcCtx    *svchp, 
      OCIJson      *jsond,  
      oratext      *bufp,  
      oraub8       *byte_amtp,  
      ub4           wflags,       
      OCIError     *errhp,  
      ub4           mode 
);

Parameters

Parameter Mode Description
svchp IN

An allocated OCI Service Context handle.

jsond IN An allocated OCI JSON descriptor.
bufp IN/OUT

The pointer to a buffer into which the textual JSON is read. The length of the allocated memory is assumed to be byte_amtp.

byte_amtp IN/OUT
  • IN - The input size of the linear buffer.
  • OUT - The number of bytes read into the user buffer.
wflags IN

Writer flags for output textual JSON. For more information, refer to "JSON Printing Constants" section in "XML C API Reference" guide
errhp IN/OUT

An allocated OCI error handle. If there is an error, it is recorded in err parameter and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet ().

mode IN
Specifies the mode of execution.

  • OCI_DEFAULT — Is the default mode.

Returns

OCI_SUCCESS, if the textual string was written to the steam successfully.

OCI_SUCCESS_WITH_INFO, if the OCIJson descriptor is empty.

OCI_ERROR, in case of an error during execution. OCIError parameter has the necessary error information.

Usage Notes

  • An error is returned if the input buffer it not big enough to accommodate the textual JSON. In such a case, the user can use the streaming interface or provide a bigger buffer.
  • The textual JSON returned is in AL32UTF8 character set.
  • The function serializes the calls on the provided service context handle.

See Also:

JSON Printing Constants

36.2.3 OCIJsonToTextStream ()

Returns the textual string representation of the JSON content in the descriptor. The textual string is written to the write stream of the user.

Purpose

To return the textual string representation of the JSON content in the descriptor.

sword OCIJsonToTextStream (
      OCISvcCtx    *svchp, 
      OCIJson      *jsond,  
      orastream    *w_stream,  
      oraub8       *byte_amtp,  
      ub4           wflags,  
      OCIError     *errhp,  
      ub4           mode 
);

Parameters

Parameter Mode Description
svchp IN

An allocated OCI Service Context handle.
jsond IN

An allocated OCI JSON descriptor.
w_stream IN

Pointer to the orastream (write stream) input. For more information, refer to "Package orastream for C APIs" section in "XML C API Reference" guide.
byte_amtp OUT

Total number of bytes corresponding the textual JSON written to the stream.
wflags IN

Writer flags for output textual JSON. For more information, refer to "JSON Printing Constants" section in "XML C API Reference" guide.

errhp IN/OUT

An allocated OCI error handle. If there is an error, it is recorded in err parameter and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet () function.

mode IN
Specifies the mode of execution.

  • OCI_DEFAULT — Is the default mode.

Returns

  • OCI_SUCCESS, if the textual string was written to the steam successfully.
  • OCI_SUCCESS_WITH_INFO, if the OCIJson descriptor is empty.
  • OCI_ERROR, in case of an error during execution. OCIError parameter has the necessary error information.

Usage Notes

  • The textual JSON returned will be in AL32UTF8 character set.
  • If the input read stream is not open, it is opened automatically. It is the responsibility of the user to close it.
  • The function serializes the calls on the provided service context handle.

See Also:

36.2.4 OCIJsonToBinaryBuffer ()

Returns the binary image bytes in a JSON document descriptor into the buffer of the user.

Purpose

To the binary image bytes in a JSON document descriptor into the buffer of the user.

Syntax

sword OCIJsonToBinaryBuffer (    
      OCISvcCtx    *svchp, 
      OCIJson      *jsond,  
      ub1          *bufp,  
      oraub8       *byte_amtp  
      OCIError     *errhp,  
      ub4           mode 
);

Parameters

Parameter Mode Description
svchp IN

An allocated OCI Service Context handle.
jsond IN

A valid JSON Document descriptor.

bufp IN/OUT

The pointer to a buffer into which the textual JSON is read. The length of the allocated memory is assumed to be byte_amtp.

byte_amtp IN/OUT

  • IN - The input size of the linear buffer.

  • OUT - The number of bytes read into the user buffer.

errhp IN/OUT

An allocated OCI error handle. If there is an error, it is recorded in err parameter and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet () function.

mode IN
Specifies the mode of execution.

  • OCI_DEFAULT — Is the default mode.

Returns

  • OCI_SUCCESS, if the document image was read successfully.
  • OCI_SUCCESS_WITH_INFO, if the OCIJson descriptor was empty.
  • OCI_ERROR, in case of an error during execution. OCIError parameter has the necessary error information.

Usage Notes

  • An error occurs if the input size buffer is not big enough to accommodate the binary image size. In that case, the user might use a streaming interface, or find the actual image size using OCIJsonBinaryLengthGet ()
  • If the JSON descriptor holds a mutable DOM, then this function returns the bytes corresponding to the linear binary representation.
  • The function serializes the calls on the service context handle.

36.2.5 OCIJsonToBinaryStream ()

Returns the binary image bytes in a JSON document descriptor into the writestream of the user.

Purpose

To get the binary image bytes in a JSON document descriptor into the writestream of the user.

Syntax

sword OCIJsonToBinaryStream (     
      OCISvcCtx    *svchp, 
      OCIJson      *jsond,  
      orastream    *w_stream,  
      oraub8       *byte_amtp,  
      OCIError     *errhp,  
      ub4           mode 
);

Parameters

Parameter Mode Description
svchp IN

An allocated OCI Service Context handle.
jsond IN

An allocated OCI JSON descriptor.
w_stream IN

Pointer to the orastream (write stream) input. For more information, refer to "Package orastream for C APIs" section in "XML C API Reference" guide.
byte_amtp OUT Total number of bytes corresponding to the textual JSON.
errhp IN/OUT

An allocated OCI error handle. If there is an error, it is recorded in err parameter and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet () function.

mode IN
Specifies the mode of execution.

  • OCI_DEFAULT — Is the default mode.

Returns

  • OCI_SUCCESS, if the textual string is written to the stream successfully.
  • OCI_SUCCESS_WITH_INFO, if the OCIJson descriptor was empty
  • OCI_ERROR, in case of an error during execution. OCIError parameter has the necessary error information.

Usage Notes

  • If the binary image in the JSON descriptor is in the form of a DOM tree, this function writes the bytes corresponding to the linear representation.
  • If the input read stream is not open, it is opened automatically. It is the responsibility of the to close it.
  • The function serializes the calls on the service context handle.

See Also:

Package orastream for C APIs

36.2.6 OCIJsonBinaryLengthGet ()

Returns the size of the binary representation of JSON in bytes.

Purpose

To get the size of the binary representation of JSON in bytes.

Syntax

sword OCIJsonBinaryLengthGet (     
      OCISvcCtx    *svchp, 
      OCIJson      *jsond,  
      oraub8       *byte_amtp,  
      OCIError     *errhp,  
      ub4           mode 
);

Parameters

Parameter Mode Description
svchp IN

An allocated OCI Service Context handle.
jsond IN

A valid JSON Document descriptor.

byte_amtp OUT The number of bytes in the JSON image.
errhp IN/OUT

An allocated OCI error handle. If there is an error, it is recorded in err parameter and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet () function.

mode IN
Specifies the mode of execution.

  • OCI_DEFAULT — Is the default mode.

Returns

  • OCI_SUCCESS, if the length of the document image was read successfully.
  • OCI_ERROR, in case of an error during execution. OCIError parameter has the necessary error information.

Usage Notes

  • If the binary image in the JSON descriptor is in the form of a DOM tree, this function writes the bytes corresponding to the linear representation.
  • The function serializes the calls on the service context handle