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.
How to: Reference: |
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.
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.
The Applications page opens.
The Select adapter to configure or Select connection to create synonym pane opens.
The first of a series of synonym creation panes opens.
The Status pane indicates that the synonym was created successfully.
The synonym is created and added under the specified application directory.
Note:
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.
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.
Click this button to select all or filtered operations.
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.
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.
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 an application directory. The default value is baseapp.
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.
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.
This column displays the name that will be assigned to each synonym. To assign a different name, replace the displayed value.
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.
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 |
---|---|
Open |
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 Open 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. Reorganize. Recreates the data source table preserving original data. Note: This option is not available in the Web Console. |
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 the clipboard. |
Delete |
Deletes the synonym. You are asked to confirm this selection before the synonym is deleted. |
Cut |
Deletes the synonym and places it on the clipboard. |
Properties |
Displays the properties of the synonym, including physical location, last modified date, description, and privileges. |
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:
|
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 |
Header group in the Master File, if one exists. |
HEADERNS |
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. |
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.
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.
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.
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.
Tip: For definitions of other Join configurations that are available through the DMC, see Join Options.
Select EID from the left side and ERID from the right side, then click the = sign between them.
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.
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. |
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
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.
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, $
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.
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
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), $
Element attributes are supported as part of the service input message definition:
<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.
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:
(IF group EQ (ddname))
Only the GROUP describing an array can be used in an in-file construct. For example:
FILEDEF CARRAY DISK C:\Users\.........\countryarray.ftm . . . IF COUNTRY EQ (CARRAY)
Note that only the last screening value is reported for an input array component.
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.
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.
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>
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.
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 |
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.
SET DTSTANDARD = {OFF|ON|STANDARD|STANDARDU}
where:
Does not provide compatibility with the ISO 8601:2000 date-time notation 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.
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 |