Statements for Internet Access and Parsing

This document gives a functional overview of the Natural statements for internet access, PARSE JSON, and PARSE XML, specifies the general prerequisites for using these statements in a mainframe environment, informs about restrictions that apply and contains a list of further references. To take full advantage of these statements, a thorough knowledge of the underlying communication standards is required.

The following topics are covered:

Statements Available

The following Natural statements are available for access to the internet and to JSON and XML documents:

REQUEST DOCUMENT

Functionality

This statement enables you to use the Hypertext Transfer Protocol (HTTP) and the Hypertext Transfer Protocol Secure (HTTPS) in order to access documents on the web with a given Uniform Resource Identifier (URI) or Uniform Resource Locator (URL), that is, the internet or intranet address of a web site.

REQUEST DOCUMENT implements an HTTP client at Natural statement level, which allows applications to access any HTTP server on either the intranet or the internet. The statement has a set of operands, which allows it to formulate HTTP requests according to the needs of the user application. For example, using outbound operands it is possible to send user-defined HTTP headers, form data, or entire documents to an HTTP server. The inbound operands can be used to retrieve a document from the server, to view the entire HTTP header block returned from the server, or to return the values of dedicated headers, etc. Via binary format operands, binary objects such as gif files can be exchanged with the HTTP server as well. For basic authorization purposes, user ID and password operands can be specified. The content of this operand is sent with base64 encoding over the line, according to HTTP standards.

Natural supports the following REQUEST-METHODs:

  • GET - retrieve a document and HTTP headers,

  • HEAD - retrieve HTTP headers only,

  • POST - transfer form data to an HTTP server, and

  • PUT - upload a file to an HTTP server.

The REQUEST-METHOD is normally evaluated automatically, based on the operands coded for the executed REQUEST DOCUMENT statement. However, the predetermined REQUEST-METHOD can be overwritten by an explicit user specification of a REQUEST-METHOD header.

In addition to the standard REQUEST-METHODs mentioned above, the following methods can be specified in a REQUEST-METHOD header:

  • DELETE - delete a document from an HTTP server,

  • PATCH - modify a document on an HTTP server,

  • OPTIONS - retrieve the REQUEST-METHODs supported by an HTTP server, and

  • TRACE - retrieve the message received by an HTTP server.

Example

The following is an example of how the REQUEST DOCUMENT statement can be used to access an externally-located document: 

REQUEST DOCUMENT FROM
"http://bolsap1:5555/invoke/sap.demo/handle_RFC_XML_POST" 
WITH 
USER #User PASSWORD #Password
DATA
NAME 'XMLData' VALUE #Queryxml
NAME 'repServerName' VALUE 'NT2'
RETURN 
PAGE #Resultxml
RESPONSE #rc

Syntax

The syntax of the REQUEST DOCUMENT statement and detailed application hints are to be found in the Statements documentation.

PARSE XML

Functionality

The PARSE XML statement allows you to parse XML documents from within a Natural program.

The PARSE XML statement integrates a full XML parser into Natural, thus allowing Natural applications to parse XML documents in order to easily process their content. The PARSE XML statement opens a processing loop and returns, whenever one of a list of events occurs during the parse process, the respective path through the document, name and value of parsed elements together with some parser status system variables.

Syntax

The syntax of the PARSE XML statement and detailed application hints are to be found in the Statements documentation.

PARSE JSON

Functionality

The PARSE JSON statement enables parsing of JSON documents within a Natural program.

The PARSE JSON statement incorporates a complete JSON parser into Natural, which enables Natural applications to parse JSON documents. Upon executing the PARSE JSON statement, it triggers a processing loop and produces the path, name, and value of the parsed elements, along with specific parser status system variables.

Technical Implementation

When it comes to parsing JSON documents, the following parsing strategies or models are commonly used:

  • DOM (Document Object Model) – an object oriented approach

  • SAX (Simple Access) – a stream-oriented parsing method

The implementation of the PARSE JSON statement in Natural for Linux and Cloud or Natural for Windows is based on the SAX method.

Internally, parsing is conducted on a UTF-8 encoded representation of the document being parsed. If the document is not provided in this encoding, an internal conversion to UTF-8 is carried out prior to parsing. The system automatically verifies the encoding of the document to be parsed. The criteria for this validation and conversion to UTF-8 are based on the following guidelines:

  1. The system checks for a BOM (Byte Order Mark), which marks the encoding of the document.

  2. If no BOM is found, then ENCODED [IN] CODEPAGE (operand2) is considered.

  3. If no ENCODED [IN] CODEPAGE (operand2) is provided then the following guidelines are applied:

    • If the Data Type of the JSON Document (operand1) is specified as 'B' (Binary), then it is be treated as UTF-8 and no code page conversion is carried out.

    • If the Data Type of the JSON Document (operand1) is specified as 'U' (Unicode), then it is treated as UTF-16 and code page conversion to UTF-8 is carried out.

    • If the Data Type of the JSON Document (operand1) is specified as 'A' (Alphanumeric), the code page for the JSON Document (operand1) is identified based on the following criteria for converting the JSON Document (operand1) into UTF-8:

      • The default code page is used when the Natural parameter CP is defined. The default code page can be verified by the system variable *CODEPAGE

      • If a default code page is not available, then the error message NAT1328 is issued.

Note:
Nested parse loops are not permitted in Natural for Linux and Cloud or Natural for Windows.

Syntax

You can find the syntax of the PARSE JSON statement and detailed application hints in the Statements documentation.

Further References

Below is a list of resources that you may find useful.

Useful Links

Below is a collection of links that may be of interest.