To do all this, the ASP2XML component provides two methods:
The ASP2XML component is inserted into the page, and the methods used, in the same way as the standard components supplied with Active Server pages. The following code demonstrates the simplest use of the getXML method:
In VBScript:
<%
Set objAX = Server.CreateObject("Stonebroom.ASP2XML")
strConnect = "SERVER=yourserver;DSN=yourdsn"
strKeyField = "kBookCode"
strQuery = "SELECT * FROM BookList"
strXMLDoc = objAX.getXML(strConnect, strKeyField, strQuery)
%>
Alternatively, in JScript:
<%
objAX = Server.CreateObject('Stonebroom.ASP2XML');
strConnect = 'SERVER=yourserver;DSN=yourdsn';
strKeyField = 'kBookCode';
strQuery = 'SELECT * FROM BookList';
strXMLDoc = objAX.getXML(strConnect, strKeyField, strQuery);
%>
You may need to increase the timeout for the ASP script if you are likely to be processing large documents, by inserting a line such as:
<% Script.Timeout = 120 %>at the top of the ASP page. This example sets the timeout for the page to 2 minutes. The component is a fully COM-compliant ActiveX® DLL, and so it can also be used directly in other environments outside ASP. However, note that evaluation versions of the component can only be used in ASP.
Note: If you are using Internet Information Server version 4, you may like to set the 'Run in separate memory space (isolated process)' option on the Virtual Directory page of the Properties dialog for any directories where you have pages that use the ASP2XML component. This also makes it possible to unload the component on demand without restarting the server.
This returns an XML document containing the data extracted from the data source. The data that is included depends on either a SQL query statement, or on the individual values of the table name, field names, criteria and sort order. The XML document can alternatively be written to a disk file instead for use by this or another application.
The syntax of the getXML method is:
XMLDocument = getXML(ConnectionString,
RecordKeyFields,
[SQLQueryString],
[TableName],
[FieldList],
[CriteriaString],
[OrderBy],
[DiskFileName],
[OmitDataTypes],
[NamespacePrefix],
[NamespaceURI],
[OriginalValues],
[HTMLEncode])
This is used to update the source data using an XML document based on the one returned from the getXML method. You can also use it with XML documents that you create directly as long as they follow the correct format. Click here for information on the XML document format and how to edit it. The numeric (Long) return value from the putXML method indicates the number of records updated, or -1 if the method fails for any reason.
The syntax of the putXML method is:
RecordsUpdated = putXML(ConnectionString,
XMLString,
ErrorResultString,
[ReplaceApostrophe],
[DebugMode],
[ForceUpdates],
[HTMLUnEncode])
The getXML Method
Parameter
Description
ConnectionString
Required. String. The connection details for the data source from which the data will be extracted. This can be the name of an existing DSN available on the server, or it can include specific details of the connection. For example:
DRIVER={SQLServer};SERVER=sunspot;DATABASE=pubs;UID=username;PW=secret
RecordKeyFields
Required. String. One or more field names that specify the complete primary or unique key of the records in the table. If more than one field name is specified, separate them with commas, i.e.: kBookCode, dReleaseDate.
SQLQueryString
Optional. String. A complete and valid SQL statement that will be used to extract the required records from the data source. Not required if the TableName and FieldList parameters are specified. Note that the query string must specify all the fields that are listed in the the RecordKeyFields parameter, in other words the recordset that it creates must contain all the key fields. If this is not the case, an error will occur.
TableName
Optional. String. The name of the table from which the records are to be extracted. If you do not wish to update the original data, you can experiment with joined tables. However, the component can only update single tables. Not required if a complete SQL query is specified in the SQLQueryString parameter.
FieldList
Optional. String. One or more field names to specify the fields that will be included for the records in the returned XML. If more than one field name is specified, separate them with commas, i.e.: kBookCode, dReleaseDate, tTitle. Not required if a complete SQL query is specified in the SQLQueryString parameter. If both the FieldList and SQLQueryString paremeters are omitted, the component will include all fields (*) in the returned XML. Note that the field list must specify all the fields that are listed in the the RecordKeyFields parameter, in other words the recordset that it creates must contain all the key fields. If this is not the case, an error will occur.
CriteriaString
Optional. String. One or more conditions or criteria for selecting the records to be included in the returned XML. This should follow the syntax of your data source, for example: kBookCode='048x' AND tTitle LIKE 'HTML%'. It is the equivalent to the WHERE clause in a SQL statement without the 'WHERE' keyword. Not required if a complete SQL query is specified in the SQLQueryString parameter.
OrderBy
Optional. String. One or more field names to specify the sort order of the records in the returned XML. If more than one field name is specified, separate them with commas. Follow field names with the word DESC (or equivalent depending on your data source) to sort in descending order, i.e.: kBookCode, dReleaseDate DESC. Not required if a complete SQL query is specified in the SQLQueryString parameter.
DiskFileName
Optional. String. Specifies the full path and filename of a disk file where the XML document will be placed. Any existing file with the same name is replaced by the new file. In this case, the string returned by the getXML method is simply the status report for the process. Note that you must set appropriate access permissions for the folder where the file is created. See the installation instructions for more details.
OmitDataTypes
Optional. Boolean. Added in version 1.10. When True the component does not include the data type attributes in each field within the XML document it creates. This makes it easier to use the document with applications that are confused by attributes within the element name tags - for example the Databinding Agent in Internet Explorer 5 when used with an XML data Island. See Databinding in IE5 for more details. The default when this parameter is omitted is False and data type attributes are included in the XML document.
NamespacePrefix
Optional. String. Added in version 1.10. It you wish to assign the XML elements generated by the component to a specific namespace, rather than to the default namespace, you must provide a value for both this and the NamespaceURI parameter. This parameter is the prefix that will be used to locally reference the namespace in each element, for example <myprefix:element_name>.
NamespaceURI
Optional. String. Added in version 1.10. It you wish to assign the XML elements generated by the component to a specific namespace, rather than to the default namespace, you must provide a value for both this and the NamespacePrefix parameter. This parameter is the URI that is used to uniquely identify the local namespace prefix, for example
<myprefix:root_element_name xmlns:myprefix="myURI">
OriginalValues
Optional. Boolean. Added in version 1.30. When True (the default if omitted), the original values of the data fields are included in the XML document, allowing integrity checking to take place in concurrent multi-user environments. Can be set to False to improve performance and reduce the XML document size in single-user environments.
HTMLEncode
Optional. Boolean. Added in version 1.40. When True (the default if omitted), the returned XML string or the XML file written to disk will have all characters that are not legal in XML (i.e. '<', '>', '&', accented or special characters) converted to the equivalent entity reference.
The putXML Method
Parameter
Description
ConnectionString
Required. String. The connection details for the data source from which the data will be extracted. This can be the name of an existing DSN available on the server, or it can include specific details of the connection. For example:
DRIVER={SQLServer};SERVER=sunspot;DATABASE=pubs;UID=username;PW=secret
XMLString
Required. String. The XML document that specifies the updates to be made on the data source. Click here for information on the XML document format and how to edit it.
ErrorResultString
Required. String. A variable that the component can update to provide a text return message indicating the outcome of the method. This can also contain the debug information or an error message.
ReplaceApostrophe
Optional. String. The character(s) to be used to replace apostrophes in text values when updating the data source. The default if omitted is two apostrophes (i.e. each one is doubled) which provides the correct result in many databases. You can instead specify Chr(96) for the Windows ANSI 'reverse' apostrophe character, or any other character(s) as required.
DebugMode
Optional. Boolean. If True, the ErrorResultString parameter of the function will include full details of the parsing and update process for each record on return. The default is False.
ForceUpdates
Optional. Boolean. Added in version 1.30. When False (the default if omitted), the original values of the data fields are compared to the current values before the record update is applied. If one or more of the original field values has changed, the update is abandoned and details are returned in the ErrorResultString parameter. This ensures data integrity in concurrent multi-user environments. Can be set to True to force changes to be applied, even if the original values have changed. To improve performance and reduce the XML document size in single-user environments, set the OriginalValues parameter to False when calling the getXML method and set this parameter to True when calling the putXML method.
HTMLUnEncode
Optional. Boolean. Added in version 1.40. When True (the default if omitted), the XML string supplied in the XMLString parameter will have all XML entity references (such as '<', '>', '&', accented or special characters) converted back to the equivalent character before being applied to the database.
©2005 Stonebroom Limited, England