Data structure parameter in low-code

Starting in release 5.8.0, Profound.js supports the usage of data structure parameter in the plugins "Call IBM i Program" and "Call Service Program Procedure". This page documents two examples of that usage.

Example 1: Get data from web service as a Javascript JSON object, and pass that to an RPG program as a data structure.

Suppose you have a current RPG program named WRITECUST that takes as input a data structure parameter named custData, and use that data to write to a customer file named CUSTADROUT, as shown below.

     FcustadrOutuf a e           k disk
      *
     D custData        ds
     D  custno                        4s 0
     D  name                         30
     D  street                       30
     D  city                         20
     D  state                         2
     D  postal                       10
      *
     C     *entry        plist
     C                   parm                    custData
      *
     C     custno        delete    custadrf
     C                   write     custadrf
     C                   move      *on           *inlr
     C                   return

Suppose further that you want to use low-code to consume a REST web service that returns that customer data as a JSON object, and you want to pass that data to the current RPG program to write out to file CUSTADROUT. You can implement that in low-code as follows.

Use plugin "Consume REST service" to call a web service that, given a customer number as input, returns the data as a JSON object. Put the response into a work variable named custData.

The custData as returned from that REST service might be a JSON object like this:

{
  "custno": 1234,
  "name": "Industrial Supply Ltd",
  "street": "123 Sesame Street",
  "city": "New York",
  "state": "NY",
  "postal": "12345-4321"
}

Use plugin "Call IBM i Program" to call the IBM i program. For the parameter definition, if the "data type" is "data stucture", the "elements" question is displayed. Click button "Define subfields..." to display a dialog where you can define the data structure subfields, as defined in the RPG code. For the "argument value" question, specify the work variable custData.

When the IBM i program is called, data in the JSON object custData is passed to the RPG data structure parameter custData.

Example 2: Use Profound API (PAPI) to create a GET web service by calling a current RPG program that takes a customer number as input and returns a customer data structure as output.

Suppose you have a current RPG program named "GETCUST" as shown below, and you want to turn that into a web service using Profound API and low-code.

     Fcustadrp  if   e           k disk
      *
     D custnoIn        s              4s 0
      *
     D custDataOut     ds
     D  custno                        4s 0
     D  name                         30
     D  street                       30
     D  city                         20
     D  state                         2
     D  postal                       10
      *
     C     *entry        plist
     C                   parm                    custnoIn
     C                   parm                    custDataOut
      *
     C                   clear                   custDataOut
     C     custnoIn      chain     custadrp
     C                   move      *on           *inlr
     C                   return

You can create a PAPI file, define a "get" route, with the Input Parameters and Output Parameters as shown below.

In the API Logic panel, use the low-code plugin "Call IBM i Program" to call program GETCUST. Define the parameters to match with those of the RPG program.  For the parameter with data type of "data structure", click button "Define subfields..." to specify the data structure subfields. Specify the answers to the other questions as shown. The API input field custno is passed to the RPG program in parameter field custnoIn, and the RPG parameter field custDataOut is passed back to the API output field data.

• For Profound.js release 5.8.2 and later, you have 2 options to capture the output:

1) Capture the output directly into API output property output["data"].

2) Capture the output into a work variable (e.g. custDataWorkVar, in case you want to use that data for something else besides setting the API output), then use plugin "Set API output" to use that work variable to set the API output property output["data"].

• For Profound.js releases earlier than 5.8.2, you only have the 2nd option above. That is, you need to capture the output into a work variable first (e.g. custDataWorkVar) , then use that work variable to set the API output property output["data"].

The URL for this web service might be something like this, to get data for customer number 1234:

http://host:port/run/myapp/wsapi/getcust/1234

The JSON data returned should be like this:

{
  "data": {
    "custno": 1234,
    "name": "My Company                    ",
    "street": "123 Sesame Street             ",
    "city": "New York            ",
    "state": "NY",
    "postal": "12345-4321"
  }
}

Notes on data structure parameter:

• The subfield names as defined in low-code dialog "Define Data Structure Fields" do not have to match the field names as defined in the RPG program.
• However, the attributes (data type, length, etc) must match.
• Nested data structures are supported. You can define a subfield as data type "data structure", then right click on the subfield and take option "Add child subfield" to define the subfields for that data structure subfield. Below is an example where the subfield "addr" is a data structure made up of four child subfields.
• 
• If you specify the option "capture output" as "Into work variable":
  • You do not have to declare the work variable previously; it's declared for you.
  • The work variable is a JavasScript object, with one property for each subfield of the data structure, so in low-code you can refer to each "subfield" as workvar.subfield.
  • In the actual PJS code generated for the plugin, API pjs.toObject() is used to convert the data from the RPG data structure into the JavaScript object workvar. You can refer to that API for more information.
• If you have the RPG code for the parameter interface, you do not have to manually define the parameters. You can click button "Extract parameters from RPG code snippet", paste the RPG code, and click button "Generate Parameters". The definitions for all parameters (including data structure parameters) are populated for you in the low-code plugin panel. For a data structure parameter, after it's extracted from the RPG code, you can click button "Define subfields..." to verify that the subfield definitions are correct as extracted.
•