Define a dynamic array on a cataloged subroutine

The following example illustrates defining the attribute, values, and subvalues for the input request and output response arguments of the check-inv.sub subroutine.

About this task

The purpose of this example is to illustrate setting up the check-inv.sub subroutine to return a description, list price, sale price and quantity on hand at a given warehouse location for a given product. This example assumes that 2 arguments employing the dynamic-array Binding Mode (described in the table below) have been created on the check-inv.sub subroutine during the subroutine creation process. See Creating a Web Service Operation (Cataloged Subroutine) or Creating a Web Service Resource (Cataloged Subroutine) for more information on creating a cataloged subroutine Web Service Operation or Resource.

Argument Number Name Usage Binding Mode Dynamic Array Name
1 REQUEST input dynamic-array inventory.request
2 RESPONSE output dynamic-array inventory.response

Now the dynamic arrays must be fully defined.

Procedure

  1. Right-click the dynamic array from the MV Web Service Explorer and select the Edit Dynamic Array option.

    The dynamic array displays in the Editor panel. In this case, the inventory.request dynamic array has been opened for editing.

    Now you can define the attributes, values and subvalues for the inventory.request dynamic array argument 1 part of this dynamic array.

  2. Click Add.

    The Field Definition dialog box opens.

  3. Specify your values for each field you want to include in the dynamic array, and then click OK when you are done defining each field.
    For information on data typing, see D3 processing code mapping to XML datatypes.
    Note:
    • If the Multi Value Type is selected, the Element text box displays in the dialog box.
    • If the Sub Value Type is selected, the Element and Sub Element text boxes display in the dialog box.

    In this example, we will create 3 fields on the inventory.request dynamic array:

    Name Attribute Data Type Type Element Sub Element
    customer.id 1 string Single    
    item.id 2 string Multi Value items  
    location.id 3 string Sub Value items locations

    The resulting definition is illustrated as follows:

    Because customer.id is specified as a Single, this element will contain no nested elements. item.id is specified as a Multi Value with a parent element named items. location.id is specified as a Sub Value element to the locations element (which is also a child element to the items parent element).

    The resulting XML structure used in the SOAP or REST request is illustrated as follows:

    <customer.id></customer.id>
    <items>
    <item.id></item.id>
    <locations>
    <location.id></location.id>
    </locations>
    </items>
  4. Click Save when you have defined all of the required fields.

    Now we will define the attributes, values, and subvalues for the inventory.response dynamic array argument 2 part of this dynamic array.

  5. This time, right-click the inventory.response dynamic array from the MV Web Service Explorer and select the Edit Dynamic Array option.

    The inventory.response dynamic array displays in the Editor panel.

  6. Click Add to begin defining your fields. In this example, we will create 8 fields on the inventory.response dynamic array:
    Name Attribute Data Type Type Element Sub Element
    customer.id 1 string Single    
    item.id 2 string Multi Value items  
    description 3 string Multi Value items  
    list.price 4 decimal Multi Value items  
    sale.price 5 decimal Multi Value items  
    location.id 6 string Sub Value items inventory
    location.name 7 string Sub Value items inventory
    quantity.on.hand 8 int Sub Value items inventory

    The resulting definition is illustrated as follows:

    Because customer.id is specified as a Single, this element will contain no nested elements. item.id, description, list.price and sale.price are specified as Multi Values with a parent element named items. location.id, location.name and quantity.on.hand are specified as Sub Value elements to the inventory element (which is also a child element to the items parent element).

    The resulting XML structure used in the SOAP or REST response is illustrated below:

    <customer.id></customer.id>
    <items>
    <item.id></item.id>
    <description></description>
    <list.price></list.price>
    <sale.price></sale.price>
    <inventory>
    <location.id></location.id>
    <location.name></location.name>
    <quantity.on.hand></quantity.on.hand>
    </inventory>
    </items>
  7. Click Save when you have defined all of the required fields.
    Tip: You can copy a dynamic array defined on a cataloged subroutine to another cataloged subroutine from the MV Web Service Explorer. To accomplish this, simply drag the desired dynamic array from one subroutine and drop it into a another. This displays the Dynamic Array Definition dialog box where you can specify a name for the dynamic array. After specifying the name, click OK to complete the copy operation. The new dynamic array displays in the specified cataloged subroutine.
    Note: The Toolkit will store the dynamic array attribute definitions grouped by Element and Sub Element, regardless of the attribute number or order in which they are entered. For example, if attributes were entered as illustrated below when creating the dynamic array:

    After saving, the attributes will be rearranged as illustrated below:

    Note: All names within an input dynamic array must be unique. In the following example, if you pass Date within the Shipped element, the date will be written to both the Ordered and Shipped dates:

    In this example, where DateOrdered and DateShipped are used, there is no confusion:

    Now that we have defined all of the fields for our dynamic array, we can test the Web Service and display the SOAP or REST request and response. See Test a web service that employs a dynamic array for testing instructions.