Stonebroom.ASPointer Documentation

Stonebroom.ASPointer Documentation

The ASPointer component makes it easy to access and update XML, HTML, ASP and similarly-structured files directly on the server, without having to load them into a browser or other client application. It reads the file on disk and returns the selected content as a string that can be manipulated using script or code. The component can also automatically replace all matching instances in the target document with new content that you specify.

Note: With the exception of the readMetaContent method, elements must follow the XML-style rules, having either a matching end tag (such as </A>) or including the closing forward slash in the opening tag if there is no closing tag (for example <LEGAL />). The component will report the error 'Missing element closing tag </xxxx>' if you specify HTML-style single tag elements such as <P>, <BR> or <HR>.

To do all this, the ASPointer component provides four methods:

readXPointer which returns selected content from an XML, HTML or ASP document.
writeXPointer which updates selected parts of an XML, HTML or ASP document.
readMetaContent which returns selected <META> element content from an HTML or ASP document.
fileListing which returns a custom-formatted listing of the files in any directory.

The distribution pack also includes a Configuration Manager utility that
can be used to set specific default values and apply security settings.

Instantiating the Component

The 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 readXPointer method, in this case retrieving the names of the first three customers in our XML file from the <CUSTOMER_NAME> elements:

In VBScript:

<%
Set objXP = Server.CreateObject("Stonebroom.ASPointer")
strDocument = "/yourdocs/testdoc.xml"
strElement = "CUSTOMER_NAME"
intStart = 1
intCount = 3
strResult = objXP.readXPointer(strDocument, strElement, intStart, intCount)
%>

Alternatively, in JScript:

<%
objXP = Server.CreateObject('Stonebroom.ASPointer');
strDocument = '/yourdocs/testdoc.xml';
strElement = 'CUSTOMER_NAME';
intStart = 1;
intCount = 3;
strResult = objXP.readXPointer(strDocument, strElement, intStart, intCount);
%>

You may need to increase the timeout for the ASP script if you are likely to be processing very large documents, especially when updating them, by inserting a line such as:

<% Script.Timeout = 60 %>

at the top of the ASP page. This example sets the timeout for the page to 1 minute.

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 ASPointer component. This also makes it possible to unload the component on demand without restarting the server.

The readXPointer Method

This returns a string containing one or more sections of an XML, HTML or ASP (or similarly formatted) document based on a set of selection criteria. These criteria are expressed in a syntax and format similar to the W3C XML groups proposals for XPointers. The return value may be a single section of the document or several sections, based on the both the criteria you specify and the actual number of matches to that criteria within the target document. The syntax of the readXPointer method is:

ResultString = readXPointer(DocumentName, [ElementName], [AttributeName], [AttributeValue], [StartInstance], [CountInstances], [ContentType], [SpanFunction], [StringFunction], [ResultSeparator], [MatchesFound])

Parameter

Description

DocumentName

Required. String. A physical or virtual path and name of the document to be accessed. For example C:\My Documents\ThisOne.XML or /WebDocs/ThisOne.XML. You can prevent physical paths from being used with the Configuration Manager utility installed in your Stonebroom\ASPointer directory. Note: when the component is instantiated in applications outside ASP, only physical paths can be used.

ElementName

Optional. String. The name or the generic type of element to be accessed, for example "CUSTOMER_NAME", "SCRIPT" or "TBODY". Values are not case-sensitive. If omitted, the default is "#element". The generic element types that are available are:

#element	any XML or HTML element delimited with < ... >
#dtd	the Document Type Definition delimited with <!DOCTYPE ... >
#comment	any comment delimited with <!-- ... --> or <! ... >
#pi	any XML Processing Instruction delimited with <? ... ?>
#aspcode	any ASP code sections delimited with <% ... %>

AttributeName

Optional. String. The name of an attribute that must be present in the element for it to match and/or be included in the returned list. Values are not case-sensitive. The default if omitted is an asterisk " * " which means that any or no attributes can be present for the element.

AttributeValue

Optional. String. The value of an attribute that must be present in the element for it to match and/or be included in the returned list. Values are not case-sensitive. The default if omitted is an asterisk "*" which means that any attributes can have any values for the element. If both AttributeName and AttributeValue are specified, they are assumed to apply to the same attribute.

StartInstance

Optional. Integer. The first instance of the matching element or content that will be selected/included in the returned list. For example, 3 indicates that the component will only return content starting from the third instance that matches the selection criteria. The default if omitted is 1.

CountInstances

Optional. Integer. The maximum number of matchings elements or sections of content that will be selected/included in the returned list. For example, 5 indicates that the component will only return the five instances starting from StartInstance that match the selection criteria, or all if there are less than this. The default if omitted is 1. The value 0 (zero) selects all the instances up to a maximum capability for the component of 32000.

ContentType

Optional. String. Indicates the type of content to return from matched/selected content. The options are:

outerMarkup	the entire selected element or content item including the opening and closing tags or markup delimiters (such as <? and ?>).
innerMarkup	only the content of the selected element or item, excluding the opening and closing tags or markup delimiters but including any contained markup - such as child elements.
innertext	only the text content of the selected element or item, excluding all markup and child elements.

SpanFunction

Optional. String. Similar to an XPointer Span function, it contains a pair of element names separated by a comma, to indicate a sub-section of the currently selected content that should be returned. For example "NAME,PHONE" will return the content of the document from the opening NAME tag to the closing PHONE tag. The ContentType parameter must be set to outerMarkup when using this parameter, and it cannot be used at the same time as the StringFunction parameter.

StringFunction

Optional. String. Similar to an XPointer String function, this contains four parameters separated by commas, to indicate a purely text (i.e. no markup) sub-section of the currently selected content that should be returned. For example "instance,text_to_find,char_offset,num_chars". The parameter meanings are:

instance	the instance of text_to_find to use, for example 3 indicates the third matching instance. Must be greater than zero.
text_to_find	a text string that is searched for within the current content. If this part of the function is also enclosed in double quotes, the match is case-sensitive.
char_offset	the number of characters after the start of the matched string (or before it if the value is negative) to start from.
num_chars	the number of characters to include as the returned content, must be greater than zero.

ResultSeparator

Optional. String. One or more characters that are used to delimit the returned file list string. Can be set to any string of characters, including HTML. The default if omitted is the ASCII zero Chr(0) character. A simple way to handle the list is with the VBScript Split function:

FileNameArray = Split(FileListString, Delimiter)

MatchesFound

Optional. Integer. On return, contains the number of matches found, and hence the number of items included in the return string. If the function fails, the value returned will be -1 and the result string will contain a description of the error.

The writeXPointer Method

This method selects content in an XML, HTML or ASP document in exactly the same way as the readXPointer method. The difference is that all instances of the matched content are replaced by the string specified in the first parameter to the method. The return value of the method is the number of matched sections found in the document, or -1 if operation fails. On return, the optional ErrorResult parameter contains the original content of the matched sections or the error message. The syntax of the writeXPointer method is:

NumberMatches = writeXPointer(NewContent, DocumentName, [ElementName], [AttributeName], [AttributeValue], [StartInstance], [CountInstances], [ContentType], [SpanFunction], [ResultSeparator], [ErrorResult])

Parameter	Description
NewContent	Required. String. The content that will replace the existing content in the target document, for each element or item that matches the criteria in the other parameters of this function. To remove existing content, specify an empty string ("") for this parameter.
DocumentName	Required. String. See the readXPointer description above.
ElementName	Optional. String. See the readXPointer description above.
AttributeName	Optional. String. See the readXPointer description above.
AttributValue	Optional. String. See the readXPointer description above.
StartInstance	Optional. Integer. See the readXPointer description above.
CountInstances	Optional. Integer. See the readXPointer description above.
ContentType	Optional. String. See the readXPointer description above.
SpanFunction	Optional. String. See the readXPointer description above.
ResultSeparator	Optional. String. See the readXPointer description above.
ErrorResult	Optional. String. A string that is updated to contain the original values of the replaced content, or a descriptive error message if the method fails.

The readMetaContent Method

Addded in version 1.20, this method selects content from <META> elements in an HTML or ASP document in a similar way to the readXPointer method. The return value may be the content from a single <META> element or several such elements, based on the both the criteria you specify and the actual number of matches to that criteria within the target document. The syntax of the readMetaContent method is:

ResultString = readMetaContent(DocumentName, [MetaNameValue], [StartInstance], [CountInstances], [EqualsChars], [ResultSeparator], [MatchesFound])

The return value is a string containing the name/value pairs from matching <META> elements in the form of one or more:

{name_value}{equals_characters}{content_value}

lines where {name_value} is the value of the NAME attribute of the <META> element, {content_value} is the value of the CONTENT attribute, and {equals_characters} is the value of the EqualsChars parameter. These lines are delimited with the character specified as the ResultSeparator parameter. On return, the optional MatchesFound parameter contains the number of files in the list, or -1 if there was an error.

Parameter	Description
DocumentName	Required. String. See the readXPointer description above.
MetaNameValue	Optional. String. The name of the <META> element(s) to select. The name is not case-sensitive when matching the target document. However, in order to match correctly, the elements must be of the form: <META NAME="name_value" CONTENT="content_value"> with only a single space before the words NAME and CONTENT, and no other spaces or characters.
StartInstance	Optional. Integer. See the readXPointer description above.
CountInstances	Optional. Integer. See the readXPointer description above.
EqualsChars	Optional. String. The character(s) that will be used between the contents of the NAME and CONTENT attribute values in the result string. If omitted, the default is "$eq$". You can use "=" to get a normal equals sign.
ResultSeparator	Optional. String. See the readXPointer description above.
MatchesFound	Optional. Integer. See the readXPointer description above.

The fileListing Method

This method provides a list of the names of files that are stored on the server in a specified directory. You can also specify the text and HTML that is placed between each file name in the returned list as a delimiter. The syntax ot the fileListing method is:

FilesListString = fileListing(FileListRoot, [FileSpecification], [ListSeparator], [MatchesFound])

The return value is a string containing the file names, delimited with the character specified as the ListSeparator parameter. On return, the optional MatchesFound parameter contains the number of files in the list, or -1 if there was an error.

Parameter	Description
FileListRoot	String. Can be either the full physical path or the virtual path of the directory where the files that are to be listed reside. You can prevent physical paths from being used with the Configuration Manager utility installed in your Stonebroom\ASPointer directory.
FileSpecification	Optional String. A specification of files to include in the listing. Can include wildcards if required - i.e. *reports.xml** or accounts.. The default if omitted is .* (all files).
ListSeparator	Optional String. One or more characters that are used to delimit the returned file list string. Can be set to any string of characters, including HTML. The default if omitted is the string "<BR>" + Chr(13) + Chr(10) which provides a carriage return in both text and HTML formats. A simple way to handle the list is with the VBScript Split function: FileNameArray = Split(FileListString, Delimiter)
MatchesFound	Optional Integer. The number of files in the returned list, or -1 if an error was encountered.

Configuration and Security

The ASPointer component buffers the contents of the files that it processes in memory. It is possible to change the size of this buffer from the default of 2KB (2048 characters) to suit your data files. The component also provides wide-ranging access to all the drives and directories of your server, and could possibly be used by unwelcome visitors to access and even cause damage to the server installation. To prevent this, you can set options that control how much freedom the component has to access files and directories.

All the configuration and security settings are stored in Windows Registry under the key:

HKEY_LOCAL_MACHINE\SOFTWARE\Stonebroom\ASPointer\

The settings are:

Key	Description
AllowVirtualDocReadOnly	A value of "1" prevents the DocumentName parameter of the readXPointer method from being set to a physical path. Only virtual (i.e. Web site) directories can be specified as the source of documents to access. The default value of "0" allows either physical or virtual directories to be specified.
AllowVirtualDocWriteOnly	A value of "1" prevents the DocumentName parameter of the writeXPointer method from being set to a physical path. Only virtual (i.e. Web site) directories can be specified as the source of documents to update. The default value of "0" allows either physical or virtual directories to be specified.
AllowVirtualFileListOnly	A value of "1" prevents the FileListRoot parameter of the fileListing method from being set to a physical path. Only virtual (i.e. Web site) directories can be specified as the source of files to list. The default value of "0" allows either physical or virtual directories to be specified.
BufferLengthCharacters	Specifies the default size of the read buffer for the component. The optimum value depends on your system free memory, disk speed, and concurrent activity. Acceptable values are from 128 to 65536 characters. The default if not set is "2048", giving a 2KB buffer. Note that small values increase the possibility that the component may fail to find elements, or the matching end tags, that are spread over several lines in the source document.

A simple program to set these values without having to access the registry directly is supplied with ASPointer. The program is named XPConfig.exe. It is installed by default in the Program Files\Stonebroom\ASPointer folder of your system, and is available from the Start menu.