Managing Web Services Metadata

In this section:

When the server accesses a Web Services provider, it needs to know how to pass parameters to and accept responses from the Web service operation. For each operation the server will access, you create a synonym that describes the operation and the server mapping, which is provided through the WSDL file for the Web Service.


Top of page

x
Creating Synonyms

How to:

Reference:

x

A synonym defines a unique logical name (also known as an alias) for each Web Services operation. Synonyms are useful because:

Creating a synonym generates a Master File and an Access File. These are metadata that describe the Web Services request to the server.

Each synonym you create represents a single operation.

Note: Each synonym describes the Web Services operations of a particular provider. If the operation parameters are changed, the synonym must be recreated.



x
Procedure: How to Create a Synonym

To create a synonym, you must have previously configured the adapter. You can create a synonym from the Applications or Adapters pages of the Web Console.

  1. From the Web Console menu bar, click Applications.

    The Applications page opens.

  2. Click the New button and select Synonym from the drop-down menu.

    The Select adapter to configure or Select connection to create synonym pane opens.

  3. Click a connection for the configured adapter.

    The first of a series of synonym creation panes opens.

  4. Enter values for the parameters required by the adapter as described in the synonym creation parameters reference.
  5. After entering the parameter values, click Create Synonym.

    The Status pane indicates that the synonym was created successfully.

The synonym is created and added under the specified application directory.

Note:



x
Reference: Synonym Creation Parameters for Web Services

The following list describes the parameters for which you will need to supply values, and related tasks you will need to complete in order to create a synonym for the adapter. These options may appear on multiple panes. To advance from pane to pane, click the buttons provided, ending with the Create Synonym button, which generates the synonym based on your entries.

Filter Operations by Name

Leave this check box blank if you do not wish to filter the operations for which to create synonyms.

Select the check box to filter the operations. You are prompted an operation name. Enter a string for filtering the operations, inserting the wildcard character (%) as needed at the beginning and/or end of the string.

For example, enter: ABC% to select all operations whose names begin with the letters ABC; %ABC to select operations whose names end with the letters ABC; %ABC% to select operations whose names contain the letters ABC at the beginning, middle, or end.

Select Operations button

Click this button to select all or filtered operations.

Validate

Select the Validate check box if you wish to convert all special characters to underscores and perform a name check to prevent the use of reserved names. (This is accomplished by adding numbers to the names.) This parameter ensures that names adhere to specifications. See Validation for Special Characters and Reserved Words for more information.

When the Validate option is unchecked, only the following characters are converted to underscores: '-'; ' '; ' \'; '/'; ','; '$'. No checking is performed for names.

Make unique

Select the Make unique check box if you wish to set the scope for field and group names to the entire synonym. This ensures that no duplicate names are used, even in different segments of the synonym. When this option is unchecked, the scope is the segment.

Strict SOAP data type

By default, a SOAP request generated from a table request omits all elements tags for which screening values are not provided. If this is the behavior you want, leave the Strict SOAP data type box unchecked.

If you wish to pass empty element tags as well as those that contain values, click the Strict SOAP data type check box.

This option applies to both the body and header in a SOAP request.

Select Application

Select an application directory. The default value is baseapp.

Prefix/Suffix

If you have tables with identical table names, assign a prefix or a suffix to distinguish them. For example, if you have identically named human resources and payroll tables, assign the prefix HR to distinguish the synonyms for the human resources tables. Note that the resulting synonym name cannot exceed 64 characters.

If all tables and views have unique names, leave the prefix and suffix fields blank.

Overwrite Existing Synonyms

To specify that this synonym should overwrite any earlier synonym with the same fully qualified name, select the Overwrite existing synonyms check box.

Note: The connected user must have operating system write privileges in order to recreate a synonym.

Default Synonym Name

This column displays the name that will be assigned to each synonym. To assign a different name, replace the displayed value.

To create synonyms

For all operations in the list, select the check box to the left of the Default Synonym Name column.

For specific operations, select the corresponding check boxes.



x
Reference: Managing Synonyms

Once you have created a synonym, you can right-click the synonym name in the Adapter navigation pane of either the Web Console or the Data Management Console to access the following options.

Option

Description

Edit

Opens the Master File for viewing and editing using a graphical interface. If an Access file is used it will be also available.

Edit as Text

Enables you to view and manually edit the Master File synonym.

Note: To update the synonym, it is strongly recommended that you use the graphical interface provided by the Edit option, rather than manually editing the Master File.

Edit Access File as Text

Enables you to view and manually edit the Access File synonym.

Note: This option is available only when an Access File is created as part of the synonym.

Sample Data

Retrieves up to 20 rows from the associated data source.

Data Profiling

Data Profiling provides the data characteristics for synonym columns.

Alphanumeric columns provide the count of distinct values, total count, maximum, minimum, average length, and number of nulls.

Numeric columns provide the count of distinct values, total count, maximum, minimum, average value, and number of nulls.

Refresh Synonym (if applicable)

Regenerates the synonym. Use this option if the underlying object has been altered.

Data Management

Followed by these options, if applicable:

Recreate DBMS Table. Recreates the data source table. You are asked to confirm this selection before the table is regenerated. (Note that the table will be dropped and recreated. During the process, data may be lost.)

Delete All Data. Deletes all existing data. You are asked to confirm this selection before the data is deleted.

Insert Sample Data. Inserts specified number of sample records, populating all fields with counter values.

Impact Analysis

Generates reports on procedures, synonyms, and columns that provide information on the flows/stored procedures available on a particular server, and the synonyms and columns they use. These reports enable you to evaluate changes before they are made by showing which components will be affected. See the Server Administration for UNIX, Windows, OpenVMS, IBM i, and z/OS manual for details about Impact Analysis Reports.

Copy

Copies the synonym to clipboard.

Delete

Deletes the synonym. You are asked to confirm this selection before the synonym is deleted.

Cut

Deletes the synonym and places it in clipboard.

Properties

Displays the properties of the synonym, including physical location, last modified date, and description.



x
Reference: Master File Attributes

Attribute

Description

PROPERTY

Indicates whether the field corresponds to an XML attribute or an XML element.

REFERENCE

Identifies the parent element of the field in the XML hierarchy, as defined by the Web Services XML schema document.

The format is

                        segmentname.fieldname                      

where:

segmentname

Is the name of the Master File segment in which the field resides.

fieldname

Is the name of the field that corresponds to the parent element.



x
Reference: Access File Attributes

Attribute

Description

SEGNAME

Value must be identical to the SEGNAME value in the Master File.

CONNECTION

Indicates a previously declared connection. The syntax is:

CONNECTION=connection                      
VERSION

Web Services version being used. The adapter supports Version 1.1.

ACTION

Web service operation being described.

OBJECT

Fully-qualified name of the Web Services request.

ENCODING

URL of the encoding schema.

TARGETNS

Target name space specified in the WSDL description of the operation. (This will either be global to the Web Service WSDL, or unique to the operation WSDL.)

STYLE

Value of the Web Services document WSDL style element (RPC or Document).

HEADER

The header group in the Master File, if one exists.

HEADNS

The header namespace.

EMPTYTAGS

If ON, passes empty element tags, as well as those for which values have been provided. (If OFF, the default, and element tags with values are passed.)

Applies to both the body and header in a SOAP request.



x
Using Static Joins

Reference:

You can describe various views of the same physical XML document using Master Files and Access Files.

The adapter implements join matching values at run time.

You can use static Joins to create join relationships between hierarchically unrelated integral schema ComplexType definitions using any combination of data nodes.

Any XML tags belonging to these definitions can be used to create join pairs. In addition, you can multiply instances of the same physical segment to reflect logical join relationships as needed.

Using a Join can also provide a way to produce multiple executions of a Web service. However, the user cannot change the properties of the fields that describe the Web service input message. The original WSDL controls the acceptable data types for both the input and output. The Join must be to fields belonging to the root segment, and the ACCESS_PROPERTY parameter must be set to NEED_VALUE. The Join must also be unique to avoid looping.

Note: Static (embedded) Joins are not directly supported by the Create Synonym facility. To take advantage of this feature, after a synonym is generated you must modify its Master and Access Files. The Data Management Console Synonym Editor is the recommended tool for such modifications since it provides an easily identifiable segments hierarchy with drag and drop capability and a visual calculator for KEYFLD/IXFLD modifications. Using the DMC, you can quickly add all duplicate segments to the Master File, then delete any unneeded segments.

In some cases, schemas (such as those produced by Microsoft tools and reflecting relationships between the original MS SQL Server database tables) contain proper XML constraints (unique/key/keyref) for describing joins. You can use this information to modify the Master File:

For an example of how to use the Data Management Console to modify the Master File, see Adding a Static Join From the Data Management Console Synonym Editor.



Example: Adding a Static Join From the Data Management Console Synonym Editor

This example displays a fragment of the WSDL code from which a synonym called GetAllEmployees will be generated.

The schema shows a Constraint relationship between the Employee segment, keyed on the EID field, and the Employee Relative segment, keyed on ERID field.

<xs:unique msdata:PrimaryKey="true" name="Constraint1">
<xs:selector xpath=".//Employee" /> 
<xs:field xpath="EId" /> 
</xs:unique>
 
<xs:unique msdata:ConstraintName="Constraint1" msdata:PrimaryKey="true"
     name="EmployeeRelative_Constraint1">
  <xs:selector xpath=".//EmployeeRelative" />
  <xs:field xpath="ErId" />
  </xs:unique>
<xs:keyref msdata:ConstraintOnly="true"
     name="EmployeeRelative_Employee_EId_EId"
refer="mstns:Constraint1">
<xs:selector xpath=".//EmployeeRelative" /> 
<xs:field xpath="EId" />
</xs:keyref>

Working in the Data Management Console, you can quickly establish a Join relationship between the Employee and EmployeeRelative Segments in the synonym in order to be able to report against both segments at the same time.

  1. Open the DMC and open the Application Directory folder where the synonym is located.
  2. Double-click the synonym GetAllEmployees - Web Services in the navigation pane, then click the Modeling View tab. The segment relationships are initially represented as follows:

    Notice that both Employee and EmployeeRelative are children of the Response segment in the generated synonym.

    Your goal is to report against both segments at the same time, which is not something you can do using this structure. To accomplish that task, you must first make the EmployeeRelative segment a child of the Employee segment, an easy adjustment using the DMC Segment View.

  3. Click the Segment View tab. You will see the following pane, in which Employee and Employee Relative are both children of segment Response, as shown in Modeling View:

  4. Drag the EmployeeRelative segment and drop it onto the Employee segment. EmployeeRelative is now a child of Employee, as shown in the revised Tree pane.

  5. Next, you must set up the relationship that shows how the two segments are joined. Remember that in the schema the Employee segment and the EmployeeRelative segment are joined where EID = ERID.

    To mirror this relationship, click the Ellipsis (...) for Keyfld in the EmployeeRelative segment on the right pane. The Join Properties dialog box opens. This is where you will define the nature of the join relationship between the two segments.

  6. In the Venn Diagram box at the bottom left, click the outer portion of the left circle to specify a Left Outer Join. This option retrieves all records from the left-hand data source, along with any matching records from the right-hand data source. In this example, that means you will be able to display Employee values in the report even when the employees do not have any relatives.

    Tip: For definitions of other Join configurations that are available through the DMC, see Join Options.

  7. At the top of the dialog box, the Left Source Column displays fields from the Employee segment and the Right Source Column displays fields from the EmployeeRelative segment.

    Select EID from the left side and ERID from the right side, then click the = sign between them.

  8. Click OK to complete the Join and close the Join Properties dialog box.
  9. Click the Modeling View tab to verify the modified structure in which EmployeeRelative is a child of Employee, providing the relationship you need to meet your reporting requirements.



x
Reference: Join Options

This chart defines the Join options that are available in the Venn Diagram box in the Data Management Console.

Inner Join indicates that two data sources are connected by an inner join and that only rows that appear in both tables used in the Join are extracted.

Left Outer Join indicates that two data sources are connected by a left outer join and that all rows are extracted from the left data source, as well as the columns from the right source that match.

Right Outer Join indicates that two data sources are connected by a right outer join and that all rows are extracted from the right data source, as well as the columns from the left source that match.

Full Outer Join indicates that two data sources are connected by a full outer join and that all rows are extracted from both data sources.

Cross Join indicates that two data sources are connected by a cross join, or Cartesian product of two tables. It consists of all possible pairs of rows between the two tables.


Top of page

x
What Is a WSDL File?

Reference:

A Web Services Description Language (WSDL) file is an XML document that describes a Web Service. A WSDL file contains the following key elements:

WSDL Element

Definition

definitions

Root element of all WSDL documents. It defines the name of the web service, declares multiple namespaces used throughout the remainder of the document, and contains all the service elements described here.

types

Describes all the data types used between the client and server. WSDL is not tied exclusively to a specific typing system, but it uses the W3C XML Schema specification as its default choice. If the service uses only XML Schema built-in simple types, such as strings and integers, the types element is not required.

message

Describes a one-way message, whether it is a single message request or a single message response. It defines the name of the message and contains zero or more message part elements, which can refer to message parameters or message return values.

portType

Combines multiple message elements to form a complete one-way or round-trip operation. For example, a portType can combine one request and one response message into a single request/response operation, most commonly used in SOAP services. Note that a portType can (and frequently does) define multiple operations.

binding

Describes the concrete specifics of how the service will be implemented on the wire. WSDL includes built-in extensions for defining SOAP services, and SOAP-specific information therefore goes here.

service

Defines the address for invoking the specified service. Most commonly, this includes a URL for invoking the SOAP service.



Example: WSDL Segment for Generating a Master File for FindAddress Web Service

The following shows the elements for the input and output for the FindAddress Web Service function:

<!-- edited with XMLSPY v5 rel. 3 U (http://www.xmlspy.com)-->
<wsdl:definitions
   xmlns:tns="http://arcweb.esri.com/v2"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
   xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
   xmlns="http://schemas.xmlsoap.org/wsdl/"
   xmlns:tme="http://www.themindelectric.com/"
xmlns:ns11="http://www.themindelectric.com/package/
com.esri.is.services.common.v2.geom/"
xmlns:ns12="http://www.themindelectric.com/package/com.esri.is.services.common.v2/"
xmlns:ns13="http://www.themindelectric.com/package/
com.esri.is.services.glue.v2.addressfinder/"
   xmlns:ns14="http://www.themindelectric.com/package/java.lang/"
   targetNamespace="http://arcweb.esri.com/v2" name="AddressFinder">
 <wsdl:types>
     <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.themindelectric.com/package/
com.esri.is.services.glue.v2.addressfinder/">
   <xsd:complexType name="Address">
    <xsd:sequence>
     <xsd:element name="houseNumber" nillable="true" type="xsd:string"/>
     <xsd:element name="street" nillable="true" type="xsd:string"/>
     <xsd:element name="intersection" nillable="true" type="xsd:string"/>
     <xsd:element name="city" nillable="true" type="xsd:string"/>
     <xsd:element name="state_prov" nillable="true" type="xsd:string"/>
     <xsd:element name="zone" nillable="true" type="xsd:string"/>
     <xsd:element name="country" nillable="true" type="xsd:string"/>
    </xsd:sequence>
   </xsd:complexType>
   <xsd:complexType name="AddressFinderOptions">
    <xsd:sequence>
     <xsd:element name="dataSource" nillable="true" type="xsd:string"/>
    </xsd:sequence>
   </xsd:complexType>
  </xsd:schema>
  <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.themindelectric.com/package/ 
com.esri.is.services.common.v2.geom/">
  <xsd:complexType name="Point">
   <xsd:sequence>
     <xsd:element name="x" type="xsd:double"/>
     <xsd:element name="y" type="xsd:double"/>
   <xsd:element name="coordinateSystem" nillable="true"        
type="ns11:CoordinateSystem"/>
   </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="CoordinateSystem">
   <xsd:sequence>
     <xsd:element name="projection" nillable="true" type="xsd:string"/>
     <xsd:element name="datumTransformation" nillable="true" type="xsd:string"/>
   </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="Envelope">
   <xsd:sequence>
     <xsd:element name="minx" type="xsd:double"/>
     <xsd:element name="miny" type="xsd:double"/>
     <xsd:element name="maxx" type="xsd:double"/>
     <xsd:element name="maxy" type="xsd:double"/>
     <xsd:element name="coordinateSystem" nillable="true"          
type="ns11:CoordinateSystem"/>
   </xsd:sequence>
  </xsd:complexType>
 </xsd:schema>
 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.themindelectric.com/package/       
com.esri.is.services.common.v2/">
  <xsd:import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
  <xsd:import namespace="http://www.themindelectric.com/package/       
com.esri.is.services.common.v2.geom/"/>
  <xsd:complexType name="LocationInfo">
   <xsd:sequence>
    <xsd:element name="matchType" nillable="true" type="xsd:string"/>
    <xsd:element name="candidates" nillable="true" type="ns12:ArrayOfLocation"/>
    <xsd:element name="hasMore" type="xsd:boolean"/>
    <xsd:element name="errorCode" nillable="true" type="xsd:string"/>
   </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="Location">
    <xsd:sequence>
     <xsd:element name="point" nillable="true" type="ns11:Point"/>
     <xsd:element name="description1" nillable="true" type="xsd:string"/>
     <xsd:element name="description2" nillable="true" type="xsd:string"/>
     <xsd:element name="score" type="xsd:double"/>
     <xsd:element name="matchType" nillable="true" type="xsd:string"/>
     <xsd:element name="type" nillable="true" type="xsd:string"/>
     <xsd:element name="locationExtent" nillable="true" type="ns11:Envelope"/>
    </xsd:sequence>
  </xsd:complexType>
   <xsd:complexType name="ArrayOfLocation">
    <xsd:complexContent>
     <xsd:restriction base="soapenc:Array">
       <xsd:attribute ref="soapenc:arrayType" wsdl:arrayType="ns12:Location[]"/>
     </xsd:restriction>
    </xsd:complexContent>
   </xsd:complexType>
  </xsd:schema>
  <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.themindelectric.com/package/java.lang/">
     <xsd:import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
     <xsd:complexType name="ArrayOfstring">
      <xsd:complexContent>
       <xsd:restriction base="soapenc:Array">
         <xsd:attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:string[]"/>
       </xsd:restriction>
      </xsd:complexContent>
     </xsd:complexType>
  </xsd:schema>
 </wsdl:types>
   <message name="getAddress0In">
     <part name="point" type="ns11:Point"/>
     <part name="addressFinderOptions" type="ns13:AddressFinderOptions"/>
     <part name="token" type="xsd:string"/>
   </message>
   <message name="getAddress0Out">
     <part name="Result" type="ns13:Address"/>
   </message>
  <portType name="IAddressFinder">
     <operation name="getAddress" parameterOrder="point addressFinderOptions token">
       <documentation>Returns an address from an x,y-coordinate.</documentation>
        <input name="getAddress0In" message="tns:getAddress0In"/>
        <output name="getAddress0Out" message="tns:getAddress0Out"/>
     </operation>
  </portType>
  <binding name="IAddressFinder" type="tns:IAddressFinder">
    <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
  <operation name="getAddress">
    <soap:operation soapAction="getAddress" style="rpc"/>
     <input>
      <soap:body use="encoded" encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/" 
     namespace="http://arcweb.esri.com/v2"/>
     </input>
     <output>
      <soap:body use="encoded" encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/" 
  namespace="http://arcweb.esri.com/v2"/>
     </output>
  </operation>
  </binding>
  <service name="AddressFinder">
    <port name="IAddressFinder" binding="tns:IAddressFinder">
      <soap:address location="http://arcweb.esri.com/services/v2/AddressFinder"/>
    </port>
  </service>
</wsdl:definitions>

The following Master File is generated from the Create Synonym process:

FILENAME=M6ILO, SUFFIX=SOAP    , $
  SEGMENT=GETADDRESS, SEGTYPE=S0, $
   GROUP=POINT, ALIAS=point, USAGE=A76, ACTUAL=A100, $
    FIELDNAME=X, ALIAS=x, USAGE=D20.2, ACTUAL=A20, ACCESS_PROPERTY=(NEED_VALUE), $
    FIELDNAME=Y, ALIAS=y, USAGE=D20.2, ACTUAL=A20, ACCESS_PROPERTY=(NEED_VALUE), $
   GROUP=COORDINATESYSTEM, ALIAS=coordinateSystem, USAGE=A60, ACTUAL=A60, $
    FIELDNAME=PROJECTION, ALIAS=projection, USAGE=A30, ACTUAL=A30,
      MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), $
    FIELDNAME=DATUMTRANSFORMATION, ALIAS=datumTransformation, USAGE=A30, ACTUAL=A30,
      MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), $
   GROUP=ADDRESSFINDEROPTIONS, ALIAS=addressFinderOptions, USAGE=A30, ACTUAL=A30, $
    FIELDNAME=DATASOURCE, ALIAS=dataSource, USAGE=A30, ACTUAL=A30,
      MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), $
    FIELDNAME=TOKEN, ALIAS=token, USAGE=A30, ACTUAL=A30, 
      ACCESS_PROPERTY=(NEED_VALUE), $
    FIELDNAME=__RESPONSE, USAGE=TX80L, ACTUAL=TX, ACCESS_PROPERTY=(INTERNAL), $
  SEGMENT=RESPONSE, SEGTYPE=S0,SEGSUF=XML     , PARENT=GETADDRESS, 
POSITION=__RESPONSE, $
    FIELDNAME=RESPONSE, ALIAS=getAddress0Out, USAGE=A1, ACTUAL=A1, 
ACCESS_PROPERTY=(INTERNAL), $
  SEGMENT=RESULT, SEGTYPE=S0, PARENT=RESPONSE, $
    FIELDNAME=RESULT, ALIAS=Result, USAGE=A1, ACTUAL=A1, 
ACCESS_PROPERTY=(INTERNAL),
      REFERENCE=RESPONSE, PROPERTY=ELEMENT,  $
    FIELDNAME=HOUSENUMBER, ALIAS=houseNumber, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $
    FIELDNAME=STREET, ALIAS=street, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $
    FIELDNAME=INTERSECTION, ALIAS=intersection, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $
    FIELDNAME=CITY, ALIAS=city, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $
    FIELDNAME=STATE_PROV, ALIAS=state_prov, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $
    FIELDNAME=ZONE, ALIAS=zone, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $
    FIELDNAME=COUNTRY, ALIAS=country, USAGE=A30, ACTUAL=A30,
      MISSING=ON,
      REFERENCE=RESULT, PROPERTY=ELEMENT,  $

The following Access File is generated from the Create Synonym process:

SEGNAME=GETADDRESS, CONNECTION=CON06, VERSION=1.1, OBJECT=getAddress,
  ACTION=getAddress, ENCODING=http://schemas.xmlsoap.org/soap/encoding/,
  TARGETNS=http://arcweb.esri.com/v2, STYLE=RPC, $
 ID=ns11, NS=http://www.themindelectric.com/package/
    com.esri.is.services.common.v2.geom/   , $
  FIELD=point, TYPE=Point, NS_ID=ns11, $
  FIELD=coordinateSystem, TYPE=CoordinateSystem, NS_ID=ns11, $
 ID=ns13, NS=http://www.themindelectric.com/package/
    com.esri.is.services.glue.v2.addressfinder/   , $
  FIELD=addressFinderOptions, TYPE=AddressFinderOptions, NS_ID=ns13, $

You can use the following procedure to retrieve data from the FindAddress Master File:

SET ALL=ON
TABLE FILE FINDADDRESS
PRINT LOCATION.X LOCATION.Y
WHERE FINDADDRESS.HOUSENUMBER EQ '27'
WHERE FINDADDRESS.STREET EQ 'Stevenson Drive'
WHERE FINDADDRESS.ZONE EQ '07746'
WHERE FINDADDRESS.DATASOURCE EQ 'GDT.Streets.US'
END


Example: WSDL Document With SOAP Header

The Create Synonym process generates an extra group in the root segment to describe the SOAP HEADER layout, as defined in the WSDL document.

The following WSDL describes a SOAP header:

Binding section:

<input>
  <soap:body use="literal"/>
  <soap:header part="header" message="tns:jobsHeader" use="literal"/>
</input>

Message description:

<message name="jobsHeader">
  <part element="tns:ibsinfo" name="header"/>
</message>

Types section:

<xs:element name="ibsinfo">
  <xs:complexType>
      <xs:sequence>
          <xs:element type="xs:string" name="service"/>
          <xs:element type="xs:string" name="method"/>
          <xs:element type="xs:string" name="license"/>
          <xs:element type="xs:string" minOccurs="0" name="disposition"/>
          <xs:element type="xs:string" minOccurs="0" name="Username"/>
          <xs:element type="xs:string" minOccurs="0" name="Password"/>
          <xs:element type="xs:string" minOccurs="0" name="language"/>
      </xs:sequence>
  </xs:complexType>
</xs:element>

The resulting Master File contains:

SEGMENT=LOCATION, SEGTYPE=S0, $
  GROUP=HEADER, ALIAS=Header, USAGE=A210, ACTUAL=A210, $
  GROUP=IBSINFO, ALIAS=ibsinfo, USAGE=A210, ACTUAL=A210, $
   FIELDNAME=SERVICE, ALIAS=service, USAGE=A30, ACTUAL=A30,
      ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=METHOD, ALIAS=method, USAGE=A30, ACTUAL=A30,
      ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=LICENSE, ALIAS=license, USAGE=A30, ACTUAL=A30,
      ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=DISPOSITION, ALIAS=disposition, USAGE=A30, ACTUAL=A30,
     ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=USERNAME, ALIAS=Username, USAGE=A30, ACTUAL=A30,
     ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=PASSWORD, ALIAS=Password, USAGE=A30, ACTUAL=A30,
     ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=LANGUAGE, ALIAS=language, USAGE=A30, ACTUAL=A30,
     ACCESS_PROPERTY=(NEED_VALUE), $

The resulting Access File contains:

SEGNAME=LOCATION, CONNECTION=PSIBS, VERSION=1.1, OBJECT=LOCATION,
  ACTION=EFREM.LOCATIONRequest@test@@, HEADER=HEADER,
  TARGETNS=urn:iwaysoftware:ibse:jul2003:LOCATION,
  HEADERNS=urn:schemas-iwaysoftware-com:iwse, STYLE=DOCUMENT, $

Note that the SOAP header is generated in the SOAP request if a value is provided (either explicitly in the request or implicitly via default values in the Master File) for at least one of the header components. If no header values are available, the SOAP header is not generated.



Example: WSDL Document With Output Headers

The Create Synonym process generates extra output segment(s) to describe the header data returned by a SOAP request. Segments describing the header and body parts of the SOAP response become children of the response segment and siblings to each other.

WSDL fragment

<operation name="TrackMessagesBulk">
< soap:operation soapAction="http://www.strikeiron.com/TrackMessagesBulk"
       style="document" />
  <input>
    <soap:body use="literal" />
  </input>
 <output>
   <soap:body use="literal" />
    <soap:header message="s0:TrackMessagesBulkResponseInfo"
          part="ResponseInfo" use="literal" />
  </output>
</operation>

Generated Master File

SEGMENT=RESPONSE, SEGTYPE=S0, SEGSUF=XML , PARENT=TRACKMESSAGESBULK
      POSITION=__RESPONSE, $
  FIELDNAME=RESPONSE, ALIAS=Envelope, USAGE=A1, ACTUAL=A1,
      ACCESS_PROPERTY=(INTERNAL), $
  FIELDNAME=HEADER, ALIAS=Header, USAGE=A1, ACTUAL=A1,
      ACCESS_PROPERTY=(INTERNAL), $
  FIELDNAME=BODY, ALIAS=Body, USAGE=A1, ACTUAL=A1,
      ACCESS_PROPERTY=(INTERNAL), $
SEGMENT=HEADER, SEGTYPE=S0, PARENT=RESPONSE, $
  FIELDNAME=RESPONSE, ALIAS=ResponseInfo, USAGE=A1, ACTUAL=A1,
      ACCESS_PROPERTY=(INTERNAL), REFERENCE=HEADER, $
  FIELDNAME=RESPONSECODE, ALIAS=ResponseCode, USAGE=I11, ACTUAL=A11,
      REFERENCE=HEADER.RESPONSE, PROPERTY=ELEMENT,  $
  FIELDNAME=RESPONSE1, ALIAS=Response, USAGE=A30, ACTUAL=A30,
      REFERENCE=HEADER.RESPONSE, PROPERTY=ELEMENT,  $
SEGMENT=BODY, SEGTYPE=S0, PARENT=RESPONSE, $
  FIELDNAME=RESPONSE, ALIAS=TrackMessagesBulkResponse, USAGE=A1,
      ACTUAL=A1, ACCESS_PROPERTY=(INTERNAL), REFERENCE=BODY, $
  FIELDNAME=TRACKMESSAGESBULKRESULT, ALIAS=TrackMessagesBulkResult,
      USAGE=A1, ACTUAL=A1, ACCESS_PROPERTY=(INTERNAL),
      REFERENCE=BODY.RESPONSE, PROPERTY=ELEMENT,  $


x
Reference: Multiple Headers

The Adapter for Web Services converts multiple header body definitions in the WSDL document into Master File components. Each input header body becomes a separate GROUP description for the input SOAP segment. For each output header body, a special field description is created in the response segment.



Example: WSDL Document With Mixed Content

Complex data types with the MIXED property are supported in the SOAP response document.

<xsd:element name="letterBody">
    <xsd:complexType mixed="true">
        <xsd:sequence>
            <xsd:element name="salutation">
                <xsd:complexType mixed="true">
                    <xsd:sequence>
                        <xsd:element name="name" type="xsd:string"/>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
            <xsd:element name="quantity" type="xsd:positiveInteger"/>
            <xsd:element name="productName" type="xsd:string"/>
            <xsd:element name="shipDate" type="xsd:date" minOccurs="0"/>
        </xsd:sequence>
    </xsd:complexType>
</xsd:element>

The resulting Master File contains:

SEGMENT=LETTERBODY, SEGTYPE=S0, $
 FIELDNAME=LETTERBODY, ALIAS=letterBody, USAGE=A50, ACTUAL=A50, $
 FIELDNAME=SALUTATION, ALIAS=salutation, USAGE=A50, ACTUAL=A50,
  REFERENCE=LETTERBODY, PROPERTY=ELEMENT, $
 FIELDNAME=NAME, ALIAS=name, USAGE=A50, ACTUAL=A50,
  REFERENCE=SALUTATION, PROPERTY=ELEMENT, $
 FIELDNAME=QUANTITY, ALIAS=quantity, USAGE=P32, ACTUAL=A32,
  REFERENCE=LETTERBODY, PROPERTY=ELEMENT, $
 FIELDNAME=PRODUCTNAME, ALIAS=productName, USAGE=A50, ACTUAL=A50,
  REFERENCE=LETTERBODY, PROPERTY=ELEMENT, $
 FIELDNAME=SHIPDATE, ALIAS=shipDate, USAGE=YYMD, ACTUAL=A10, MISSING=ON,
  REFERENCE=LETTERBODY, PROPERTY=ELEMENT, $

The Adapter for Web Services does not preserve the original sequence of text components and descendant elements. The following SOAP response document and report illustrate this limitation:

<letterBody>
    <salutation>Dear Mr.
        <name>Robert Smith</name>.
    </salutation>
    Your order of 
    <quantity>1</quantity>
    <productName>BabyMonitor</productName> 
    shipped from our warehouse on
    <shipDate>1999-05-21</shipDate>.
</letterBody>
 
LETTERBODY       SALUTATION NAME           QUANTITY PRODUCTNAME SHIPDATE
----------       ---------- ----           -------- ----------- --------
 
Your order of shipped from our warehouse on .  Dear Mr. . Robert Smith
1        BabyMonitor 1999/05/21


Example: WSDL Document With Abstract Input Data Type

The adapter generates an input field with ACTUAL and USAGE formats of A1. The ACCESS property for this field is initially set to INTERNAL to prevent a front-end tool from requesting an input value. A user can modify the definition manually, if necessary.

Message description:

<message name="ivpIn">
    <part element="m1:ivp" name="parameters"/>
</message>
Input message definition:
<xs:element name="ivp">
    <xs:complexType>
        <xs:sequence/>
    </xs:complexType>
</xs:element>

The resulting Master File contains:

FIELDNAME=IVP, ALIAS=ivp, USAGE=A1, ACTUAL=A1, ACCESS_PROPERTY=(INTERNAL), $

Top of page

x
Mapping Attributes and Default Values

Element attributes are supported as part of the service input message definition:



Example: WSDL Document With Mapped Attributes and Default Values
<xs:element name="component">
  <xs:complexType>
     <xs:simpleContent>
        <xs:extension base="xs:string">
            <xs:attribute use="optional" default="browse" name="perform">
             <xs:simpleType>
               <xs:restriction base="xs:string">
                   <xs:enumeration value="browse"/>
                   <xs:enumeration value="insert"/>
                   <xs:enumeration value="update"/>
                </xs:restriction>
              </xs:simpleType>
            </xs:attribute>
        </xs:extension>
     </xs:simpleContent>
  </xs:complexType>
</xs:element>

The resulting Master Files contains:

FIELDNAME=COMPONENT, ALIAS=component, USAGE=A30, ACTUAL=A30,
 ACCESS_PROPERTY=(NEED_VALUE), $
 
FIELDNAME=PERFORM, ALIAS=perform, USAGE=A6, ACTUAL=A6,
 ACCESS_PROPERTY=(NEED_VALUE),
 
XDEFAULT='browse',
ACCEPT='browse' OR 'insert' OR 'update',
REFERENCE=COMPONENT, PROPERTY=ATTRIBUTE, $

Note that if no explicit value is provided for the field, the XDEFAULT value is used when the SOAP request is generated.


Top of page

x
Using Arrays as Input Values

The Adapter for Web Services supports the use of arrays as input values. An array is described in the Master File using the GROUP definition with ACCESS_PROPERTY=ARRAY_ITEM. GROUP describes one instance of an object. You can provide input values for the array of objects using the following methods:

Note that only the last screening value is reported for an input array component.



Example: Using Arrays as Input Values

In the following example a segment defining the structure of an ESRI SOAP request retrieves a list of coordinates for the set of addresses. GROUP ADDRESSES are used to define one object item from the ADDRESSES array. The GROUP definition is extended by adding ACCESS_PROPERTY=ARRAY_ITEM and providing input values for the fields that comprise the array.

Master File

SEGMENT=FINDADDRESS, SEGTYPE=S0, $
 GROUP=ADDRESSES, ALIAS=addresses, USAGE=A210, ACTUAL=A210,
 ACCESS_PROPERTY=ARRAY_ITEM, $ 
   FIELDNAME=HOUSENUMBER, ALIAS=houseNumber, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='2815', $
   FIELDNAME=STREET, ALIAS=street, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='PRAIRIE AVE.', $
   FIELDNAME=INTERSECTION, ALIAS=intersection, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), $
   FIELDNAME=CITY, ALIAS=city, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='MIAMI BEACH', $
   FIELDNAME=STATE_PROV, ALIAS=state_prov, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='FL', $
   FIELDNAME=ZONE, ALIAS=zone, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='33140', $
   FIELDNAME=COUNTRY, ALIAS=country, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='US', $
 GROUP=ADDRESSFINDEROPTIONS, ALIAS=addressFinderOptions, USAGE=A30,
 ACTUAL=A30, $
   FIELDNAME=DATASOURCE, ALIAS=dataSource, USAGE=A30, ACTUAL=A30,
     MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE),
     XDEFAULT='GDT.Streets.US', $
   FIELDNAME=TOKEN, ALIAS=token, USAGE=A120, ACTUAL=A120,
     ACCESS_PROPERTY=(NEED_VALUE, AUTHTOKEN), $
   FIELDNAME=__RESPONSE, USAGE=TX80L, ACTUAL=TX,
     ACCESS_PROPERTY=(INTERNAL), $

Note: Although not illustrated in this example, you can use the ACCESS_PROPERTY=ARRAY_ITEM value to create nested GROUP definitions in which an inner GROUP object serves as an array inside an array. Using nested arrays, you can describe virtually any hierarchical object.

Screening on Leaf Components

Following are illustrations of the two variations on lazy OR screening on leaf components.

Note that it is not necessary to provide values for all fields in a GROUP since XML array item objects can be built with the subset of object components. However, the two screening methods have different conventions for dealing with missing values, as illustrated in the following examples.

Both of these requests produce identical elements in the MATCH array.

Explicit screening by field

When you are specifying lazy OR screening conditions for individual fields in a GROUP, the number of values and their positions must be the same for all field in the array GROUP.

Notice that each field below has three values. When an array is generated from this input, the first values in each line will be aligned, the seconds values will be aligned, and the third values will be aligned. Therefore, if values are omitted or misplaced, the alignment will be incorrect.

IF HOUSENUMBER EQ '2815' OR 'Two' OR '1250'
IF STREET EQ 'PRAIRIE AVE.' OR 'Penn Plaza' OR 'Broadway'
IF CITY EQ 'MIAMI BEACH' OR 'NY' OR 'NY'
IF STATE_PROV EQ 'FL' OR 'NY' OR 'NY'
IF ZONE EQ '33140' OR '10121' OR '10001'
IF COUNTRY EQ 'US' OR 'US' OR 'US'

Note that there are no values for the INTERSECTION field in this screening request. When specifying individual fields explicitly you can simply omit any fields you are not interested in including in the array.

Screening for a whole group

When you specify lazy OR screening conditions for the GROUP, values for individual fields in the GROUP must be separated by a slash (/). Missing values like INTERSECTION must be accounted for using two consecutive slashed (//) on each line of the screening request.

IF COUNTRY EQ '2815/PRAIRIE AVE.//MIAMI BEACH/FL/33140/US' OR 
              'Two/Penn Plaza//NY/NY/10121' OR 
              '1250/Broadway//NY/NY/10001'

In this example, INTERSECTION is represented by // after STREET and before CITY.


Top of page

x
Using Arrays as Input Values for XML Elements and Their Attributes

You can apply standard Web Services array methodology to XML attribute values that are associated with parent XML array element values. The Parent array element is described with the ARRAY_ITEM value in the ACCESS_PROPERTY parameter. Associated attributes are linked to the parent element using the REFERENCE parameter, with the PROPERTY parameter set to ATTRIBUTE. You can supply input values for the element and attributes as you would for a regular array.



Example: Using Arrays as Input Values for an XML Element and its Attributes

Master File fragment:

FIELDNAME=KEY, ALIAS=key, USAGE=A30, ACTUAL=A30,
  ACCESS_PROPERTY=(ARRAY_ITEM), $
FIELDNAME=NAME, ALIAS=name, USAGE=A30, ACTUAL=A30,
  ACCESS_PROPERTY=(NEED_VALUE), REFERENCE=KEY, PROPERTY=ATTRIBUTE,  $

Request fragment with screening statements:

IF KEY EQ 'SHARE' OR 'BAE01A'
IF NAME EQ 'Setid' OR 'Location'

Generated SOAP request:

The screening statements yield an array of key/name occurrences in the soap request:

<SOAP-ENV:Body>
    <m:GetQuote xmlns:m="http://ws.cdyne.com/">
       <m:key xsi:type="xsd:string" name="Setid"  >SHARE</m:key>
       <m:key xsi:type="xsd:string" name="Location" >BAE01A</m:key> 
   </m:GetQuote>
</SOAP-ENV:Body>

Top of page

x
Modifying Namespace Qualifiers in WSDL Schemas

Namespace qualifiers are generated in the SOAP request document in accordance with the WSDL schemas. You can modify qualification rules in the Access File to affect how the SOAP XML request is built.

Qualification control information is stored in the Access File on the segment, namespace (Id), and element/attribute (Master File field) levels.

New parameters are introduced in the Access File in both the Segment and ID records:

A new FORM parameter is introduced in the Field record that describes the element or attribute.

Acceptable values for the new parameters are qualified and unqualified.

The default behavior (full qualification for all elements in the Header and Body, and no qualification for the attributes) is applied when no new parameters are found in the Access File.

See the XML Schema Part 0: Primer, which you can access at http://www.w3.org/TR/2001/REC-xmlschema-0-20010502/#NS, for details about Advanced Concepts: Namespaces, Schemas & Qualification.


Top of page

x
Data Type Support

The following table lists how the server maps XSD data types in a Master File.

XSD Data Type

USAGE

ACTUAL

string

A30

A30

double

D20.2

A20

float

F15.2

A15

decimal

P20.3

A20

int

I11

A11

short

I6

A6

long

P20

A20

boolean

A5

A5

dateTime

HYYMDm

For related information, see Date-Time Processing.

A35

time

HHISsm

A15

date

YYMD

A10

gYearMonth

HYYM

A8

gYear

HYY

A5

gMonthDay

HMD

A6

gDay

HD

A3

gMonth

HM

A4

integer

P33

A33

nonPositiveInteger

P33

A33

negativeInteger

P33

A33

nonNegativeInteger

P32

A32

unsignedLong

P20

A20

unsignedInt

P10

A10

unsignedShort

I5

A5

positiveInteger

P32

A32

byte

I4

A4

unsignedByte

I4

A4

normalizedString

A30

A30

token

A30

A30

Name

A30

A30

NMTOKEN

A30

A30

ID

A30

A30

hexBinary

A30

A30

language

A30

A30

anyURI

A30

A30

QName

A30

A30



x
Date-Time Processing

How to:

Date-time formats can produce output values and accept input values that are compatible with the ISO 8601:2000 date-time notation standard.



x
Syntax: How to Enable ISO Standard Date-Time Notation
SET DTSTANDARD = {OFF|ON|STANDARD|STANDARDU}

where:

OFF

Does not provide compatibility with the ISO 8601:2000 date-time notation standard.

ON|STANDARD

Enables recognition and output of the ISO standard formats, including use of T as the delimiter between date and time, use of period or comma as the delimiter of fractional seconds, use of Z at the end of "universal" times, and acceptance of inputs with time zone information. STANDARD is a synonym for ON.

STANDARDU

Enables ISO standard formats (like STANDARD) and also, where possible, converts input strings to the equivalent "universal" time (formerly known as "Greenwich Mean Time"), thus enabling applications to store all date-time values in a consistent way.


iWay Software