HWTJDEL — Delete a JSON entry

Description

There are several ways to obtain the handles required to delete a given JSON value, depending on the type of value being deleted. See Examples at the end of this service for pseudo-code examples.

Environment

The requirements for the caller are:

Programming requirements

See Syntax, linkage, and programming considerations for details about how to call the z/OS® JSON parser services in the various supported programming languages.

REXX programming considerations for the HWTJDEL service

All information for the HWTJDEL service applies for REXX requests.

Syntax

Write the call as shown in the following syntax diagram. You must code all parameters in the order shown.

CALL HWTJDEL(
        ReturnCode,
        ParserHandle,
        ObjectHandle,
        EntryValueHandle,
        DiagArea);

address hwjson "hwtjdel",
               "ReturnCode",
               "ParserHandle",
               "ObjectHandle",
               "EntryValueHandle",
               "DiagArea."

Parameters

The parameters are explained as follows:

ReturnCode

Returned parameter.

• Type: Integer (non-REXX), character representation of an integer (REXX)
• Length: 4 bytes (non-REXX)

Contains the return code from the service.

ParserHandle

Supplied parameter.

• Type: Character string
• Length: 12 bytes (non-REXX)

Specifies the JSON parser instance to be used.

ObjectHandle

Supplied parameter.

• Type: Integer (non-REXX), character representation of an integer (REXX)
• Length: 4 bytes (non-REXX)

Specifies an object handle representing a particular JSON object (object or array object) that contains the object or array entry to be deleted. The objectHandle value is either zero for the root object or an entry value handle (entryValueHandle) whose JSON type is HWTJ_OBJECT_TYPE or HWTJ_ARRAY_TYPE.

EntryValueHandle

Supplied parameter.

• Type: Integer (non-REXX), character representation of an integer (REXX)
• Length: 4 bytes (non-REXX)

Specifies a handle representing a particular entry to be deleted. The entry value handle must represent an entry contained within the JSON object or JSON array represented by ObjectHandle. If ObjectHandle represents a JSON object, EntryValueHandle must represent a member of the object. If ObjectHandle represents a JSON array, EntryValueHandle must represent an element of the array.

DiagArea (non-REXX)

DiagArea. (REXX)

Returned parameter.

• Type: Character string (non-REXX), stem variable (REXX)
• Length: 132 bytes (non-REXX)

A storage area provided by the caller that might contain additional diagnostic information related to the service call. It consists of a 4-byte integer reason code field and a 128-byte character string error text field.

ABEND codes

Return codes

Examples

The following pseudo-code examples demonstrate several uses of HWTJDEL.

Example 1:

Given the following JSON text:

{  
   "foo":{  
      "mood":"happy",
      "color":"red",
      "bling":"baz"
   },
   "bar":[  "bag", 3, true]
}

To delete the "mood" entry from the "foo" object, first call HWTJSRCH to obtain a handle to the "foo" object.

objectName = "foo"  
rootObject = 0         /* search the root object */
startingHandle = 0  /* start with the first member */

HWTJSRCH ( 
    returnCode,
    parserHandle,
    HWTJ_SEARCHTYPE_GLOBAL,
    objectName,
    length(objectName),
    rootObject,
    startingHandle,
    targetObjectHandle,
    DiagArea
);

The output handle (targetObjectHandle) can then be used on a subsequent call to HWTJSRCH to find the "mood" entry.

entryName = "mood"

HWTJSRCH ( 
    returnCode,
    parserHandle,
    HWTJ_SEARCHTYPE_OBJECT,
    entryName,
    length(entryName),
    targetObjectHandle,
    startingHandle,
    targetEntryHandle,
    diagArea
);

Having obtained the required targetObjectHandle and targetEntryHandle, a call to HWTJDEL would look similar to this:

HWTJDEL(
    returnCode,
    parserHandle,
    targetObjectHandle,
    targetEntryHandle,
    diagArea
);

A subsequent call to HWTJSERI would return a JSON text string reflecting the delete operation.

{  
   "foo":{  
      "color":"red",
      "bling":"baz"
   },
   "bar":[  "bag", 3, true]
}

Example 2:

Deleting an element from a JSON array would require a slightly different sequence of operations.

Given the following JSON text:

{  
   "bar":[  "bag", 3, true, {"a": "somewhere"} ],
   "bling": "blam",
   "pi": 3.14159
}

To delete the fourth entry (the object with a single entry named "a") from the "bar" array , first call HWTJSRCH to obtain a handle to the "bar" array.

arrayName = "bar"
rootObject = 0       /* Search the root */
startingHandle = 0 /* Start at the first member */
targetArrayHandle = 0

HWTJSRCH (
    returnCode,
    parserHandle,
    HWTJ_SEARCHTYPE_GLOBAL,
    arrayName,
    length(arrayName),
    rootObject,
    startHandle,
    targetArrayHandle,
    DiagArea
);

The output handle (targetArrayHandle) can then be used on a subsequent call to HWTJGAEN to retrieve a handle to the fourth array value.

entryIndex = 3 /* Note that array entries are zero-indexed */ 

HWTJGAEN (
    returnCode,
    parserHandle,
    targetArrayHandle,
    entryIndex,
    targetEntryHandle,
    diagArea
);

Having obtained the required targetArrayHandle and targetEntryHandle, a call to HWTJDEL would look similar to this:

HWTJDEL(
    returnCode,
    parserHandle,
    targetArrayHandle,
    targetEntryHandle,
    diagArea
);

{  
   "bar":[  "bag", 3, true ],
   "bling": "blam",
   "pi": 3.14159
}