HWTJSRCH — Search

Call the HWTJSRCH service to search for a particular name string.

JSON text is organized by name or value pairs in the form "string":value, where "string" is a descriptor of the value, and where value can be a string in double quotation marks, a number, a boolean value (true, false), a null value, an object, or an array. These structures can be nested.

It is often useful to quickly search for a particular name string in the JSON text. If a string is found, the traversal methods may then be useful to traverse items contained within the found object entry or in subordinate objects.

Description

The HWTJSRCH service searches for a particular "name" string within the entire JSON text or within a specific object. The starting point for the search can be either from the beginning of the text or from a specified handle start point.

Notes:

JSON array entries are simply a sequence of comma-separated values of any data type. As array entries do not have a "name" string, they cannot be searched by the HWTJSRCH service; however, the name of the array object itself can be searched, and nested objects with "name" strings within the specified array.
A global search can be used for searching through JSON text read by the parse service (HWTJPARS). Any text added to the string via the create service (HWJTCREN) cannot be searched globally, but might be searched with an object-scoped search.

Environment

The requirements for the caller are:

Requirement	Details
Minimum authorization:	Supervisor state or problem state, any PSW key.
Dispatchable unit mode:	Task or SRB.
Cross memory mode:	Any PASN, any HASN, any SASN.
AMODE:	31 bit.
ASC mode:	Primary or access register (AR).
Interrupt status:	Enabled for I/O and external interrupts.
Locks:	No locks held.
Control parameters:	Control parameters must be in the primary address space and addressable by the caller.
Linkage:	Standard MVS™ linkage conventions are used.

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 HWTJSRCH service

All information for the HWTJSRCH service applies for REXX requests except:

SearchString replaces SearchStringAddr and SearchStringLen

Syntax

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

Non-REXX parameters	REXX parameters
CALL HWTJSRCH( ReturnCode, ParserHandle, SearchType, SearchStringAddr, SearchStringLen, ObjectHandle, StartingHandle, SearchResultHandle, DiagArea);	address hwtjson "hwtjsrch", "ReturnCode", "ParserHandle", "SearchType", "SearchString", "ObjectHandle", "StartingHandle", "SearchResultHandle", "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.

SearchType

Supplied parameter.

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

Specifies the scope of the search. Valid values are:

HWTJ_SEARCHTYPE_GLOBAL: Search the JSON text, starting at (but not including) the entry represented by the startingHandle parameter, for the first "name" that exactly matches the SearchString for REXX or the string pointed to by the SearchStringAddr parameter for non-REXX. The search is object-ignorant, meaning that there is no scoping of the search to be within the object specified by the startingHandle parameter. The search ends when either the search string is found or the end of the JSON text is reached, whichever occurs first.
HWTJ_SEARCHTYPE_OBJECT: Search the JSON text, starting at (but not including) the entry represented by the startingHandle parameter, for the first "name" within the object specified by the objectHandle parameter that exactly matches the SearchString for REXX or the string pointed to by the SearchStringAddr parameter for non-REXX. The search ends when either the search string is found or the end of the object is reached, whichever occurs first.

SearchString (REXX)

Supplied parameter.

Type: Character string

Specifies the search string name to be searched. End of change

SearchStringAddr (non-REXX)

Supplied parameter.

Type: Pointer
Length: 4 bytes

Specifies the address of the location of the name string that the parser should attempt to locate within the JSON text.

Note:

To search for an empty name string (""), specify a searchStringAddr value of zero. (In this case, the value of searchStringLen must also be zero.) End of change

SearchStringLen (non-REXX)

Supplied parameter.

Type: Integer
Length: 4 bytes

Specifies the length of the search string pointed to by the searchStringAddr parameter.

Note:

To search for an empty name string (""), specify a searchStringLen value of zero. (In this case, the value of searchStringAddr must also be zero.) End of change

ObjectHandle

Supplied parameter.

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

Specifies a handle representing a particular JSON object (object or array object) at which to start the search. An objectHandle is either a value of zero for the root object, or an entryValueHandle whose JSON type is HWJT_OBJECT_TYPE or HWTJ_ARRAY_TYPE. This parameter must be specified for a searchType of HWTJ_SEARCHTYPE_OBJECT and must be set to zero for a searchType of HWTJ_SEARCHTYPE_GLOBAL.

StartingHandle

Supplied parameter.

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

Specifies any handle value returned by a prior parser service call, or a value of zero.

If the searchType is HWTJ_SEARCHTYPE_GLOBAL, the search starts at (but not including, unless the value is zero) the specified handle within the JSON text.

If the searchType is HWTJ_SEARCHTYPE_OBJECT, the search starts at (but not including, unless the value is zero) the specified handle, if the startingHandle is either within the object specified by objectHandle or the startingHandle is zero (start searching at the beginning of the object).

If multiple instances of the same name string occur within the search scope, the searchResultHandle that is returned on one invocation of the search service can be used as the startingHandle for the next invocation.

SearchResultHandle

Returned parameter.

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

The returned handle that represents the next instance of the search string found after the specified starting point.

DiagArea (non-REXX)

DiagArea. (REXX)

Returned parameter.

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

A storage area provided by the caller that may 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.

If the string is not found, a "not found" return code is returned. If there are multiple strings with the same name string value, only the first is returned. The caller can issue another search request to find the next instance of this name string.

ABEND codes

If the toolkit is unable to properly access the user-supplied parameter list, the call might result in a X'04D' ABEND with a reason code of X'000Byyyy' for one of the following reasons:

yyyy: Reason
0000: The parameters passed by the caller are not in the primary address space.
0001: The number of parameters passed by the caller is incorrect.

Return codes

When the service returns control to the caller, GPR 15 and the returnCode parameter contain a hexadecimal return code, as listed in Table 1.

Table 1. Return codes for the HWTJSRCH service
Hexadecimal return code Equate symbol	Meaning and action
0 HWTJ_OK	Meaning: Successful completion. Action: None.
101 HWTJ_PARSERHANDLE_INV	Meaning: Program error. The parserHandle parameter specified on the service call is not a valid parser handle (one that was returned by the HWTJINIT service). Action: Check for a probable coding error.
102 HWTJ_PARSERHANDLE_INUSE	Meaning: Program error. Two possible reasons can result in this return code: The parser handle is being used by another caller. Only one outstanding z/OS JSON parser service can use the same parser handle. A previous service request using this parser handle resulted in an ABEND, and the parser instance was unable to indicate that its use of the parser handle has completed. Action: Check for a probable coding error. While all z/OS JSON parser service calls are synchronous (blocking), if more than one task, process, or thread is running simultaneously and using the same parser handle, only one is allowed access. Change the application such that only one thread attempts to use the same parser handle at a time. If the application detected an ABEND while the z/OS JSON parser was invoked, the parser instance associated with the parser handle might be permanently locked. To release the storage associated with the parser work area, issue the HWTJTERM service call with a forceOption of HWTJ_NOFORCE. If this fails with the same return code, issue another HWTJTERM service call with a forceOption of HWTJ_FORCE.
103 HWTJ_INACCESSIBLE_PARM	Meaning: Program error. The application passed an input or output parameter which was inaccessible by the parser. See General programming considerations for details about z/OS JSON parser recovery processing. Action: Check for a probable coding error. Likely, the recovery of the caller detected this return code as a result of the parser abnormally ending with a `X'0C4'` system ABEND. Check the diagArea for an explanation as to which parameter was attempting to be accessed when the parser service calls abnormally ended. See General programming considerations for details about actions to consider for this return code.
104 HWTJ_HANDLE_INV	Meaning: Program error. The value specified for the objectHandle parameter is not valid, or a nonzero value objectHandle value was specified for a searchType of HWTJ_SEARCHTYPE_GLOBAL. Action: Check for a probable coding error. If the searchType is HWTJ_SEARCHTYPE_OBJECT, then pass either: An object handle or entry value handle on the objOrEntryHandle parameter that was returned on a prior z/OS JSON parser service call A value of zero for the root object If the searchType is HWTJ_SEARCHTYPE_GLOBAL, specify a value of zero for the objectHandle parameter.
105 HWTJ_HANDLE_TYPE_ERROR	Meaning: Program error. The specified objectHandle does not represent an object or array object (JSON data type of HWTJ_OBJECT_TYPE or HWTJ_ARRAY_TYPE). Action: Check for a probable coding error. Correct the mismatched handle and specify an objectHandle value that represents an object or array object handle.
10A HWTJ_ROOT_OBJECT_MISSING	Meaning: Program error. There is no JSON text to search. Action: Check for a probable coding error. Invoke the parse service (HWTJPARS) to associate JSON text with the specified parser instance before invoking the search service (HWTJSRCH).
601 HWTJ_JSRCH_SEARCHTYPE_INV	Meaning: Program error. The caller specified an invalid searchType. Action: Check for a probable coding error. The caller should change the searchType value to one of the valid values.
602 HWTJ_JSRCH_SRCHSTRADDR_INV	Meaning: Program error. The caller specified a value of zero for the address of the search string buffer. Action: Check for a probable coding error. Specify the actual address of the buffer containing the search string. Note: Specifying a bad search string buffer address other than zero may result in the parser terminating with a `X'0C4'` system ABEND. See the description of the HWTJ_INACCESSIBLE_PARM return code for more information.
603 HWTJ_JSRCH_SRCHSTRLEN_INV	Meaning: Program error. The caller specified a value of zero for the length of the search string buffer. Action: Check for a probable coding error. Specify the actual length of the search string buffer. Note: Specifying a bad search string buffer length other than zero may result in the parser terminating with a `X'0C4'` system ABEND. See the description of the HWTJ_INACCESSIBLE_PARM return code for more information.
604 HWTJ_JSRCH_STARTINGHANDLE_INV	Meaning: Program error. The specified startingHandle value is not valid for one of the following reasons: The caller specified a bad handle value that was not returned by a prior z/OS JSON parser service call. If the searchType is HWTJ_SEARCHTYPE_OBJECT, the startingHandle value is either not zero or not the value of a valid handle within the object specified by the objectHandle parameter. Action: Check for a probable coding error. Validate that the startingHandle parameter contains either a zero or a valid handle. Also, if the searchType is HWTJ_SEARCHTYPE_OBJECT, verify that the startingHandle is within the object specified by the objectHandle parameter.
605 HWTJ_JSRCH_SRCHSTR_NOT_FOUND	Meaning: The name string was not found in the search scope specified by the caller. If the searchType was HWTJ_SEARCHTYPE_GLOBAL, the name string was not found anywhere from the startingHandle to the end of the JSON text. If the searchType was HWTJ_SEARCHTYPE_OBJECT, the name string was not found anywhere in the object specified by objectHandle (from the startingHandle to the end of the object). Action: Check for a probable coding error. If the string was supposed to be found, verify that the searchType, startingHandle, and objectHandle (if applicable) are specified correctly. If all of these values are correct and the name string still cannot be found, verify that the JSON text being parsed actually contains the name string that the caller specified.
F01 HWTJ_INTERRUPT_STATUS_INV	Meaning: Program error. The calling program is disabled. The system rejects the service request. Action: Check the calling program for a probable coding error.
F02 HWTJ_LOCKS_HELD	Meaning: Program error. The calling program is holding one or more locks. The system rejects the service request. Action: Check the calling program for a probable coding error.
F03 HWTJ_UNSUPPORTED_RELEASE	Meaning: The operating system level does not support this service. The system rejects the service request. Action: Remove the calling program from this system, install it on a system that supports z/OS JSON parser services, and run the calling program again.
FFF HWTJ_UNEXPECTED_ERROR	Meaning: System error. The service encountered an unexpected error. The system rejects the service call. Action: Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM® Support Center.