Create a REQUEST-DOCUMENT Client

This section describes how to create a REQUEST-DOCUMENT client. The following topics are covered:

Introduction

The REQUEST-DOCUMENT Client code generator allows Natural to access Web services by generating a REQUEST-DOCUMENT subprogram based on a Web service WSDL and XSD. In addition, the generator creates a subprogram for each operation (method) in the WSDL and parameter data areas (PDAs) containing parameters that represent the request and response portions of the Web service operation.

The generated REQUEST-DOCUMENT subprogram uses Natural REQUEST DOCUMENT and PARSE XML statements to call the Web service and interpret the response. The subprogram then maps the input parameters to an XML file, which is sent to the Web service via a REQUEST DOCUMENT statement. The response is verified and parsed in the REQUEST-DOCUMENT subprogram and the data is placed into the appropriate output parameters of the PDA. In addition, the generated error PDA informs users of any errors.

A wizard also performs a pre-analysis of the WSDL. If an associated operation requires more than three dimensions, the operation will be disabled on the selection panel because Natural can only handle up to three dimensions. The pre-analysis wizard also checks for cyclic types (a type that is defined in the WSDL and then referenced by another type in the same WSDL). If a cyclic type is found, all operations that reference it will also be disabled.

You can use a REQUEST-DOCUMENT subprogram to perform various functions, such as retrieve the current exchange rate for orders, verify that a postal code and address match, or retrieve inventory information from another application (within or outside the company). The generated subprogram supports Unicode characters, binary arrays and complex structures (arrays of ANY, detailed arrays, etc.).

Note:
To use this feature, the Natural nucleus/profile must be set up to correctly handle XML. For information, see Activate REQUEST DOCUMENT Statement and Activate PARSE XML Statement in the Natural documentation.

Generate the REQUEST-DOCUMENT Subprogram

Start of instruction setTo generate a REQUEST-DOCUMENT subprogram and data areas

  1. Open the context menu in the Project Explorer view for the NaturalONE project into which you want to generate the modules.

    Or:
    Open the context menu in the Project Explorer view for the library into which you want to generate the modules.

  2. Select Code Generation > New Request Document Client.

    The Define Request Document Client Details panel is displayed. For example:

    Screenshot: Define Request Document Client Details

    Using this panel, you can:

    Task Procedure
    Select another NaturalONE project in which to generate the REQUEST-DOCUMENT client modules. Type the name of the project in Project or select Browse to display a window listing the existing projects for selection. The project must currently exist.
    Select a folder in which to generate the REQUEST-DOCUMENT client modules. Type the name of the folder in Folder or select Browse to display a window listing the existing folders for selection. The folder must currently exist within the selected NaturalONE project.

    Note:
    This option allows you to generate modules into more complex library structures (for example, "Natural-Libraries/my library (MYLIB)/SRC"). When this option is not specified, the modules will be generated into the basic library folder (for example, "Natural-Libraries/MYLIB/SRC", "Natural-Libraries/MYLIB/Subprograms", etc.).

    Assign a prefix to the generated Natural module names. Type the prefix in Natural module prefix.

    Several Natural modules are created during generation, such as PDAs, subprogram(s), and LDA(s). This prefix will be used as the first character in the module names to help identify them as belonging to this REQUEST-DOCUMENT client.

    Replace an existing subprogram with the same name in the same library with the one you are creating. Select Overwrite if exists.

  3. Type the location of the Natural library in which to generate the subprogram and associated modules in Library.

    The library must currently exist.

    Or:
    Select Browse to display a window listing the existing libraries for selection.

    Note:
    The libraries listed for selection are based on the current project.

  4. Type a valid WSDL path (HTTP location) in WSDL location.

    Or:
    Select Browse to display a window listing WSDL locations for selection.

    The code generator will scan the selected WSDL file for each Web service operation and generate a separate subprogram for each one.

    Notes:

    1. WSDLs that use SOAP RPC encoding (http://schemas.xmlsoap.org/soap/encoding) are not supported. SOAP RPC encoding does not conform to the Web Service Interoperability standards (WS-I). For more information, refer to http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html#refinement16448072.
    2. By default, Refresh is selected and the code generator will retrieve the operations defined for the Web service. If you do not want the operations retrieved, deselect Refresh.

  5. Select Finish to generate the REQUEST-DOCUMENT client with all default operations.

    Or:
    Select Next to select which operations to generate.

    The wizard reads the specified WSDL, determines which operations it contains, and displays the Select Web Services Operations panel, showing the operations defined for the Web service. Each operation is represented by a line in a table. For this example, "C:\Inetpub\wwwroot\wsdls\ALLTYP2.wsdl" was used as the WSDL location:

    Screenshot: Select Web Services Operations Panel

    The Select Web Service Operations panel displays the following details for each operation:

    • Whether a subprogram will be generated (yes)

    • Which operation will be generated (ALLTYP2)

    • Which binding will be used (SOAP)

    • What the generated subprogram will be named (ALLTYP21)

    Using this panel, you can:

    Task Procedure
    Suppress the generation of one or more operations. Deselect the operation(s) in Generate and a REQUEST-DOCUMENT subprogram will not be generated for that operation. A subprogram will only be generated for each operation that is selected in Generate.

    Note:
    A minimum of one operation must be selected.

    Change the type of binding used. Select another type of binding in Binding.

    Note:
    The wizard defaults to the binding that is appropriate for the specified WSDL. We recommend that you do not change the default binding.

    Change the name of the subprogram to be generated. Type the new name in Subprogram.
    Select all operations. Select Select All. This option allows you to quickly select all operations.
    Deselect all operations. Select Deselect All. This option allows you to quickly deselect all operations.

    Note:
    A minimum of one operation must be selected.

    Use Unicode format instead of alphanumeric format for variables in the data areas. Select Use Unicode instead of Alpha fields for data areas. Select this option if the Web service passes Unicode data. With Natural, this is determined by whether the Natural server is configured to use Unicode variables. If the Natural server is not configured to use Unicode, do not select this option and the generator will generate a REQUEST-DOCUMENT client that contains no Unicode variables.

    Note:
    This option defaults to the value defined for the Generate Unicode Dynamics option in the Preferences window for Natural. For information, see Set Natural Preferences.

    Generate data areas using an alternate Natural format for decimal or double Web service fields. Select Use alternate Natural format for Web service decimal/double fields. Select this option if you want to generate data areas using an alternate Natural format for Web service fields of type decimal or double and then type the new format in the input field.

    Note:
    If this option is not selected, the default Natural format will be used (F8).

    Note:
    If desired, a Generation Progress window can be displayed during generation. For information, see Set Code Generation Preferences.

  6. Select Finish.

    The subprogram is generated using the current specifications. When generation is complete, the available user exits are displayed in the Outline view (see User Exits for the REQUEST-DOCUMENT Subprogram) and the generated modules are displayed in the Project Explorer. For example:

    request document example

    The generated subprogram is displayed in the editor view. For example:

    graphics/request-document-example-in-editor.png

  7. Save the generated module.

    At this point, you can:

    • Define user exits for the subprogram. For information, see Defining User Exits.

    • Use the NaturalONE Testing option to test the subprogram. For information, see Test a Subprogram Directly in Application Testing.

    • Use NaturalONE functionality to upload the generated subprogram to the server.

User Exits for the REQUEST-DOCUMENT Subprogram

The Outline view for the REQUEST-DOCUMENT subprogram displays the available user exits. For example:

graphics/user-exits-in-outline-view-request-document.png

You can use these exits to define additional processing.

Notes:

  1. All user exits are empty when generated.
  2. For information about adding custom code within user exits, see Defining User Exits.

Define XML Substitution Characters

The generated REQUEST-DOCUMENT subprogram translates special characters (such as xml tags) in and out of the data it passes. To determine the substitutions for these characters, the REQUEST-DOCUMENT subprogram uses the CDXMLSU2 subprogram and CDRDOCA2 parameter data area (PDA) in the SYSTEM library. The REQUEST-DOCUMENT subprogram calls CDXMLSU2 to set up the XML substitution characters. Both of these modules are shipped with the Construct runtime project.

Note:
For information about adding this project, see Add the Construct Runtime Project.

The following example shows CDXMLSU2 in the editor view:

graphics/cdxmlsu2-in-editor.png

Tip:
Within the editor, you can quickly find locations that must be changed by searching for "/* CUSTOMIZE".

To change settings for the XML substitution characters, use the GENERATE-CODE user exit. For example:

graphics/cdxmlsu2-in-editor-generate-code-user-exit.png

In this example, the LOCAL-DATA user exit defines the Natural format for the #DOUBLE-QUOTE and #MAX-REPLACEMENTS values and the size of the #REPLACEMENT-TABLE array. The GENERATE-CODE user exit resizes the #REPLACEMENT-TABLE array and defines the logic and substitution values for #DOUBLE-QUOTE.

This section covers the following topics:

Add XML Substitution Characters

Start of instruction setTo add xml substitution characters

  1. Select and open CDXMLSU2 in the Construct runtime project.

  2. Increase the size of the #MAX-REPLACEMENTS value for the #REPLACEMENT-TABLE array by "n" in the LOCAL-DATA user exit, where "n" is the number of substitution characters you are adding.

  3. Assign the #SEARCH-STRING and #REPLACE-STRING values and indexes for each substitution character you are adding.

  4. Stow the CDXMLSU2 subprogram in the SYSTEM library.

Modify XML Substitution Characters

Start of instruction setTo modify xml substitution characters

  1. Select and open CDXMLSU2 in the Construct runtime project.

  2. Change the #SEARCH-STRING and #REPLACE-STRING values and indexes for each substitution character you are modifying.

  3. Stow the CDXMLSU2 subprogram in the SYSTEM library.

Delete XML Substitution Characters

Start of instruction setTo delete xml substitution characters

  1. Select and open CDXMLSU2 in the Construct runtime project.

  2. Decrease the size of the #MAX-REPLACEMENTS value for the #REPLACEMENT-TABLE array by "n" in the LOCAL-DATA user exit, where "n" is the number of substitution characters you are deleting.

  3. Delete the #SEARCH-STRING and #REPLACE-STRING values and indexes for each substitution character you are deleting.

  4. Stow the CDXMLSU2 subprogram in the SYSTEM library.