Creating and Editing the Client Definition File

The Client Definition File (CDF) contains all of the information needed by the SOAPAMCP process to map an IPM to a Web service request and map the Web service response back to an IPM. You use the WSDL2CDF utility to generate a CDF file from the Web Services Description Language (WSDL) file that describes the Web service you want to access.

It is common for Web services to use arbitrary-length strings and unbounded arrays in their type definitions. Since your application will use interprocess messages (which have a finite size) to access Web services, you must set specific limits on the sizes of these items. This may require some minor editing of the CDF that was generated by WSDL2CDF.

This section explains the Client Definition File creation and editing process.

Creating the Client Definition File using WSDL2CDF

The WSDL2CDF utility creates a Client Definition File (CDF) by reading the Web Service Description Language (WSDL) file that describes the target Web service and augmenting it with mapping information. The CDF contains all of the information needed by the SOAPAMCP process to map a request IPM to a Web service request and map the Web service response back to an reply IPM. Some minor manual tuning of the generated CDF may be required, however. See Editing the Client Definition File, below, for more information.

CODE

tacl> run WSDL2CDF -wsdl http://soapam.nuwave-tech.com/services/bankdemo/bankdemo.wsdl -cdf bankcdf

Refer to the WSDL2CDF Command Line Reference for complete details.

Editing the Client Definition File

You use the WSDL2CDF utility to create your Client Definition File (CDF). However, there a few circumstances in which it may be necessary or desirable to edit the CDF that WSDL2CDF produced:

to change the maximum length of a string-type element
to change the upper boundary of an array-type element
to specify an alternate name for an element
to specify an alternate data type for an element

The Client Definition File (CDF) is an XML-format text file. You can edit it with any text editor. Be sure to observe the rules for XML; that all attribute values be quoted, for example. Refer to the Client Definition File Reference for complete details on structure of the Client Definition File.

Changing the maximum length of a string or upper bound of an array

It is common for Web services to use arbitrary-length strings and unbounded arrays in their type definitions. Since your application will use interprocess messages (which have a finite size) to access Web services, you must set specific limits on the sizes of these items.

The WSDL2CDF utility does this for you automatically when creating the Client Definition File (CDF). By default, it sets all string elements to a maximum length of 32 characters and all arrays to a maximum of two occurrences. You can override these settings by using the -stringsize and -maxoccurs command line parameters. However, WSDL2CDF applies the same sizes to all of the string elements and all of the array elements in the CDF, which may not be appropriate for your application. In such cases, you must manually adjust the sizes by editing the CDF.

Here's an example of a string element whose size was set to '32' by WSDL2CDF:

<element name="mystring" type="string" size="32"/>

To change the maximum length of the string element 'mystring' to 256, change the entry to:

<element name="mystring" type="string" size="256"/>

Here's an example of an array element whose upper bound (maxOccurs) was set to '2' by WSDL2CDF because the WSDL did not specify an upper bound:

<element name="myarray" type="SomeComplexType" minOccurs="0" maxOccurs="2"/>

To change the upper bound of the myarray to 8, change the entry to:

<element name="myarray" type="SomeComplexType" minOccurs="0" maxOccurs="8"/>

Bear in mind that changing the sizes of elements will change the size of the interprocess message your application must send to access the Web service, and that the maximum size of an interprocess message is 32,767 bytes.

Specifying an alternate name for an element

The CDF is used by the CDF2DDL utility to generate DDL descriptions of the IPMs your application will use to access the Web service. CDF2DDL will adjust the names of the elements it generates to conform to DDL naming rules (maximum length, reserved word conflicts, etc.). This may result in somewhat cryptic element names in the generated DDL. Although you can manually change the names in the DDL, the changes will be lost if you ever need to run CDF2DDL again. Instead, add the "ddlName" attribute to the element to specify the name that CDF2DDL should use in the DDL it generates. For example:

<element name="ThirdPartyProductDetailsItemCount" type="unsignedNumeric" size="4"/>

produces this DDL:

02 ThirdPartyProductDetails01 PIC 9(4).

which, when output as COBOL, will look like this:

02 THIRDPARYPRODUCTDETAILS01 PIC 9(4).

whereas

<element name="ThirdPartyProductDetailsItemCount" type="unsignedNumeric" size="4" ddlName="THIRD-PARTY-PROD-DET-COUNT" />

produces this DDL:

02 THIRD-PARTY-PROD-DET-COUNT PIC 9(4).

which, when output as COBOL, will look like this:

02 THIRD-PARTY-PROD-DET-COUNT PIC 9(4).

Refer to Element Name Considerations for more information.

Specifying an alternate data type

The WSDL2CDF utility generates alternate data types for the types contained in the WSDL depending on the language bias you specify with the -language command line parameter. For example, if the WSDL contains an element whose type is 'float' and you specify 'COBOL', WSDL2CDF sets the CDF element type="numeric", with size="19" and scale="6", since COBOL does not support floating-point data.

<element name="myfloat" type="numeric" size="19" scale="6" xsdType="float"/>

However, this default alternate type may not be appropriate for your application. You may wish to change the precision (size) or scale, or you may wish to specify a different type altogether, such as 'string':

 <element name="myfloat" type="string" size="16" xsdType="float"/>