JSON PARSE error details

JSON PARSE error handling improvements - Expose Parse messages to application code.

We continue to struggle with problem resolution when specific use cases cause unexpected results from web service calls, resulting in Parse failures. Displaying the payload during error processing is discouraged since it may contain sensitive data that should not be included in job logs. Modifying production source code for problem resolution is discouraged. Reproducing in a test environment is extremely challenging for large applications with many data dependencies.

The WITH DETAIL phrase provides too much detail. ALL Parse messages appear in LEMSG. Many of these are expected conditions in some situations and we would like to suppress them. Displaying all of these messages in job output can be distracting when diagnosing other problems.

When WITH DETAIL is omitted not enough detail is provided. The only indication in the application code is JSON-STATUS and JSON-CODE. These do not provide details such as offset and other message tokens. The messages the application can display are missing these details which causes difficulty in diagnosing problems.

An alternative is needed for application logic to provide more detailed error messages under error conditions (error is determined by the application based on JSON-STATUS and JSON-CODE or other conditions identified by application logic.

Possible solution might be:

WITH DETAIL TO <data-name>

Where <data-name> might be a special register or a user define storage area (declared according to specification).

Additionally, <data-name> could reference a FILE that is open for output. This is less useful, however some customers might find it useful as an option since LEMSG contains more than parse messages.

This would redirect all JSON PARSE messages to program storage instead of LEMSG. The application code could then determine when these might need to be displayed and which messages to display or suppress.

Minimum details needed:

01 MY-JSON-MSG-TBL OCCURS 100 TIMES.

05 JSON-MSG-TXT PIC X(1024). *> Complete text that would be shown in LEMSG

Table would be populated starting from 1 each time JSON PARSE is executed. Application is responsible for capturing messages from prior executions if desired. Application may be responsible for re-init of table prior to any execution. If number of messages exceeds declared occurs, stop writing messages, continue processing (when appropriate). Might need WITH DETAIL TO <data-name> LIMIT <data-name-2>

Next level bonus points:

01 MY-JSON-MSG-TBL OCCURS UNBOUNDED DEPENDING ON JSON-MSG-CNT.

*> JSON-MSG-CNT is probably a special register indicating number of messages written for this parse instance

05 JSON-MSG-ID PIC X(08). *> ex. IGZ0324I

05 JSON-MSG-TXT PIC X(1024). *> Complete text that would be shown in LEMSG

05 JSON-OFFSET PIC 9(9). *> MOST IMPORTANT TOKEN

Extra credit - Possible other details

05 JSON-MSG-TOKENS OCCURS 10 TIMES.

10 JSON-MSG-TOKEN-NAME PIC X(25).

*> ex. JSON-name / JSON-token-found /JSON-tokens-expected

10 JSON-MSG-TOKEN-VALUE PIC X(25).

10 FILLER REDEFINES JSON-MSG-TOKEN.

15 FILLER PIC X(16).

15 JSON-MSG-TOKEN-NUMERIC PIC Z(8)9.

Message tokens can be useful in error handling in application logic. Providing the messages and tokens to the application can enable applications to code better error handling solutions for PARSE conditions. Parsing message text for details is risky since message text can change. Externalizing the token details in explicit variables is helpful.