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
-
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.
-
Click Add.
The Field Definition dialog box opens.
-
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>
-
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.
-
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.
-
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>
-
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.