![]() |
|||
Version
![]() www.capesoft.com |
|||
Introduction
Features
What
xFilesXML Doesn't Do
Limitations
Future Ideas
What is XML?
xFileXML Quick Start Guide
Loading / Importing & Parsing XML Files
[Suggested Reading]
Creating an XML File or String
[Suggested Reading]
xFiles
Template [Suggested Reading]
Some
Practical Applications of the xFilesXML Class
[Suggested
Reading]
Creating RSS Feed Files
Storing Global Settings in an
XML file
Creating SOAP requests
Using a View to create a filtered, sorted,
XML file
Storing multiple things in the same XML file
Examples
Importing
Advanced Structures
Classes
xFileXML Class - XML loading and saving the easy way.
Jump
Start (great for new users and beginners)
[Suggested Reading]
xFileXML Methods
xFileXML
Properties
xFileLinkDLL Class - Runtime DLL Loading
xFileLinkDLL Jump Start
xFileLinkDLL_Methods
xFileLinkDLL
Properties
FAQ
Support
Clarion
5 and Clarion 5.5 Limitations
Installation
Distribution
License
& Copyright
Version History
![]()
CapeSoft xFiles is a collection of classes for hand-coders.
It provides the following functionality:
We wrote xFiles a number of years ago, and it provided fast XML functionality, which we used in a number of our products (CapeSoft Email Server and CapeSoft Mailer among others). It worked so well, that we decided others would benefit from using it too.
Note: xFiles is for hand coders. This means you will need to call the xFiles methods within your code, for example self.Load() and self.Save(). This accessory is not purely template driven and requires hand-coding to operate.
One of the best things about xFiles is that is it really, really fast (yeah, really, you will be surprised just how fast it is!). This means that it outperforms other XML toolkits (for example the Microsoft SAX toolkit).

![]()
XML is an acronym for Extensible Markup Language. It is an open standard for describing data in a standard, easy to use, format. XML uses a similar tag structure as HTML, however XML tags define what elements contain, and not the format for displaying them. While HTML uses predefined tags, XML allows tags to be defined by the developer. This makes XML extremely flexible, while still being easy to use. XML is an excellent format for transferring and storing information.
XML is more Rigid than HTML, it is not tolerant of errors, XML documents need to be "well formed", which means they must comply with fairly rigid rules.
XML and HTML Tags
Following are examples of XML and HTML tags. Note that the XML statements
define data content, whereas the HTML lines deal with fonts and display (boldface).
XML defines "what it is," and HTML defines "how it looks."
XML
<firstName>Maria</firstName>
<lastName>Roberts</lastName>
<dateBirth>10-29-52</dateBirth>
HTML
<font size="3">Maria
Roberts</font>
<b>October 29, 1952</b>
CapeSoft xFiles reads and writes basic XML, it does not currently support all possible XML, however it will read any XML files that it creates. The intent of xFiles is to be small, fast (very fast), and simple. It is not a generic XML parser and is not intended to read all possible XML documents, although we will expand the support for more complex XML in future versions.
Advantages of XML
For more information visit http://www.w3.org/XML/. XML definition and information based on content from http://www.answers.com/topic/xml.
![]()
![]() |
Keen to get started? Or just don't like wading through all the documentation? This section is just for you - the basics on how to get xFiles working as quickly and simply as possible. |
XML Files come in all shapes and sizes, but reading them into a Clarion structure can usually be done with a single line of code. In additional the File can be either stored on disk, or already be in RAM as a string. Importing from either of these is trivial.
You can use the xFiles extension template to add an XFiles object to your procedure. Or you can hand-code the object declaration in the data section of your procedure. It'll look something like this;
xml xFileXML
The secret to the simplicity of the Load is that the NAME (or External Name attribute) of the fields you are loading matches the xml tags in the xml file. For example, if you have xml that looks like this:
<xml>
<server>www.capesoft.com</server>
<port>80</port>
</xml>
then your group should have the same field names:
Settings Group
Server String(80)
Port Long
End
xFiles simply matches up the names and the tags, and copies the data across for you.
In some cases the xml tags have names that are not legal Clarion field names. Or you may just want to change the tag name to match your field name. In this case set the External Name to match the tag name. For example:
<xml>
<web-server>www.capesoft.com</web-server>
<web-port>80</web-port>
</xml>
then in your group set the external names:
Whatever Group
Server String(80),Name('web-server')
Port Long,Name('web-port')
End
XML allows attributes to be assigned to a tag. For example;
<xml>
<server protocol="http">www.capesoft.com</server>
<port>80</port>
</xml>
This is equivalent to;
<xml>
<server>www.capesoft.com</server>
<protocol>http</protocol>
<port>80</port>
</xml>
xFiles parses attributes exactly as if they were tags. So the group for the above would be
Whatever Group
Protocol String(10)
Server String(80),Name('web-server')
Port Long,Name('web-port')
End
TIP: The order of the fields in the group is not important, except in the case where multiple fields have the same external name.
In multi-record XML xFiles needs to know the FileBoundary and the RecordBoundary. These properties tell xFiles what part of the xml file to parse, and most importantly when a record is complete. For example in the following xml
<?xml version="1.0" encoding="US-ASCII"?>
<table>
<item>
<name>Bruce</name>
<age>29</age>
</item>
<item>
<name>Bob</name>
<age>40</age>
</item>
</table>
The file boundary is <table> (since all the records fall between <table> and </table>) and the record boundary is <item> (since the data we are interested in, the name and age, falls between <item> and </item>)
We can store this file in a Queue, which would look something like this;
NamesQueue Queue
name
String(20)
age Long
End
TIP: The first step is looking at the XML file in question and deciding on the most appropriate structure to load it into. A Group is best if the xml contains a "single record" and is typically used for program settings and things like that. If the structure contains a repeating structure (in other words, multiple records) then a Queue or File is more appropriate. Of course an In-Memory file can be used as a File rather than using a Queue.
TIP: Although a valid XML file always has a single FileBoundary, that wraps the XML from top to bottom, not all systems generate XML that conforms to this standard. So xFiles allows the FileBoundary to be blank. If it is blank, then xFiles parses the file as if there is no file boundary.In the case of a Group, it is possible to set the RecordBoundary blank, and still have a valid XML file. For example;
<?xml version="1.0" encoding="US-ASCII"?>
<data>
<server>www.capesoft.com</server>
<port>80</port>
</data>
XML with Attributes
In this case the FileBoundary should be set to blank and the RecordBoundary should be set to data.
An alternative approach to XML, that the file you have may use, is the use of attributes. This is just another way of storing information. xFiles treats attributes on the record boundary exactly as if they were separate fields. For example;
<record firstname="bruce" lastname="brown">
<dob>1/1/2000</dob>
</record>
is processed as if it was
<record>
<firstname>bruce</firstname>
<lastname>brown</lastname>
<dob>1/1/2000</dob>
</record>
<product>1</product>
<product>2</product>
<product>3</product>
Once you have determined the data structure you will be using, if it is a Queue or a File, you also need to determine the File Boundary and Record Boundary. Once you know that then importing the XML file is a single line of code.
xml.Load(Structure,XmlFileName,[FileBoundary],[RecordBoundary])
The last 2 parameters are optional in the case of a Group, but it's always
better to include them if you know what they are.
For example;
xml.Load(NamesQueue,'c:\temp\names.xml','table','item')
or
xml.Load(Settings,'.\settings.xml')
This is just as easy as loading it from a file. The syntax of the load method changes slightly to accommodate the name, and length, of the string instead of the file name. I.e.
xml.Load(Structure,String,Length,[FileBoundary],[RecordBoundary])
For example;
xml.Load(Settings,SomeString,len(clip(SomeString)))
or
xml.Load(NamesQueue,net.packet.bindata,net.packet.bindatalen,'table',item')
Tip:
Because the String parameter
is passed as a pointer, you can't put a constant in here, you must use a
variable. In other words the following will fail to compile;
xml.Load(Settings,'<server>www.capesoft.com</server>',100)
When two programs want to communicate across the web they often pass their information formatted as XML. Web Services are nothing more than servers that answer "Questions" using XML. This XML is usually wrapped in a SOAP envelope, but not always. A SOAP envelope is nothing more than some extra XML stuff included in the packet.
In short, you do not need to be at all worried about Web Services, or SOAP. It's all just XML, and xFiles can handle it just like any other XML. However it arrives, it will be available to you as a string, and you can parse this string into a Clarion structure just as described in the section above.
Tip: Interacting with a Web Service typically consists of 2 parts. A Request, and a Response. This section deals with handling the Response. For more information on forming the Request, see the section [....]
If, for example, you have used a NetTalk WebClient object to fetch the XML from the server, then you would add a single line of code into the .PageReceived method to parse the incoming reply into a Group, Queue or File. For example, the Convert example does it with this line;
xml.load(resultGroup,self.page,len(clip(self.page)),'','ChangeLengthUnitResponse')
If that page was an RSS feed, then the following line would copy the feed into a Queue.
xml.load(RssQueue,self.page,len(clip(self.page)),'channel','item')
The Queue declaration would look something like this;
RssQueue QUEUE,PRE(rss)
Title STRING(255)
Link STRING(255)
Description STRING(1024)
END
Although XML is a specification for explaining the content of a text file, it does not dictate the structural nature of the text file. For example the following three xml files contain the same information, but the structure of the xml file is different. And it should be noted that these are only three of many possible configurations.
Layout 1: In this layout the line items are included in the xml file, but are not inside the Invoice tag. Each LineItem explicitly includes a link to the Invoice that it belongs to.
<invoice>
<number>4</number>
<customer>Fred</customer>
</invoice>
<lineitem>
<invoice>4</invoice>
<product>xFiles</product>
</lineitem>
<lineitem>
<invoice>4</invoice>
<product>NetTalk</product>
</lineitem>
Layout 2: In this layout the line items are inside the Invoice tag, however they still explicitly link to the Invoice in question.
<invoice>
<number>4</number>
<customer>Fred</customer>
<lineitem>
<invoice>4</invoice>
<product>xFiles</product>
</lineitem>
<lineitem>
<invoice>4</invoice>
<product>NetTalk</product>
</lineitem>
</invoice>
In the third layout the line items are inside the invoice, but there is no explicit link. Rather the position of the line item, in relation to the invoice, determines which record the line items belong to.
<invoice>
<number>4</number>
<customer>Fred</customer>
<lineitem>
<product>xFiles</product>
</lineitem>
<lineitem>
<product>NetTalk</product>
</lineitem>
</invoice>
In simple situations the Layout 1 case, and the Layout 2 case, can easily be handled using a two pass approach. Import the file twice, once for the invoices, and once for the line items. Once the two imports are completed all the necessary records for both tables will have been imported. However there may be cases where the more complicated method, which is required for Layout 3, has some advantages.
For layout three it is necessary to parse the child records as the parent record is being parsed because otherwise there is no way to link child records to their parent.
xFiles includes an example, called inv.app, which is in your \clarion\3rdparty\examples\xfiles\ParentChild folder. It is recommended that you take a moment to look at this example to see the following explanation in action.
The basic strategy for doing a multi-level import is to create 2, or more, xFiles objects. Each object is responsible for one target structure. So in the layout above there is one Xfiles object for the Invoice table (xml1), and one for the LineItems table (xml2). As xml1 reaches a lineitem tag, it calls xml2 with that part of the xml file. Using this strategy there's no limit to the number of levels of children in the original xml file.
![]()
![]() |
Keen to get started? Or just don't like wading through all the documentation? This section is just for you - the basics on how to get xFiles working as quickly and simply as possible. |
In the same way that you can load an XML file into a Clarion structure, you can also create XML files very quickly and easily.
xml.Save(Structure,XmlFileName,[FileBoundary],[RecordBoundary])
The last 2 parameters are optional but it's always
better to include them if you know what they are. Note that if you include one
you will need to include both. In the case of a Group, the FileBoundary can be a
blank string.
For example;
xml.Save(NamesQueue,'c:\temp\names.xml','table','item')
or
xml.Save(Settings,'.\settings.xml')
You can use a Group, Queue, View or File as the structure holding the data being saved.
the method returns 0 if successful, non-zero otherwise. If not successful the errorcode will be in the .Error property, and a description of the error will be in the .ErrorStr property.
xml.Save(Structure,[FileBoundary],[RecordBoundary])
This is the same as saving the xml to a File, except that the XmlFileName parameter is not used. After the call to save, the xml data will be in the property xmlData. The length of this string is in XmlDataLen. For example;
xml.save('NamesQueue')
Blob[1 : xml.XmlDataLen] = xml.XmlData
There are a number of properties which you can set just before doing a save. These properties affect the way the Xml looks.
| Property | Effect |
| DontReplaceColons | By default colons in the field name are replaced with a period. If you wish to suppress this behavior then set this property to 1. |
| OmitXMLHeader | The XML header (usually <?xml version="1.0">) is not added to the top of the file. |
| _pFileBoundary | Typically passed as a parameter of the call to .Save.
This sets the boundary for the outside of the file. <?xml version="1.0"> <file> <record> </record> </file> |
| _pFileBoundaryAttribute | Can be set to allow an attribute string to be included
as part of the file boundary. <?xml version="1.0"> <file albert="fat"> <record> </record> </file> |
| _pRecordBoundary | Typically passed as a parameter of the call to .Save.
This sets the boundary for each record inside the file. <?xml version="1.0"> <file> <item> </item> </file> |
| _pRecordBoundaryAttribute | An attribute string for the record boundary <?xml version="1.0"> <file> <item albert="fat"> </item> </file> |
| RemovePrefix | Default is 1. If set, the prefix is not used when matching fields to tags. |
| RootBoundary | An additional XML boundary around the whole file. <?xml version="1.0"> <root> <file> <record> </record> </file> </root> |
| RootBoundaryAttribute | A string of attributes for the Root Boundary. <?xml version="1.0"> <root albert="fat"> <file> <record> </record> </file> </root> |
| RSSVersion | If you are creating an RSS file, set this property to
the RSS version you are using. For example 2.0 <?xml version="1.0" encoding="ISO-8859-1"?> <rss version="2.0"> If the RssVersion propert is set, the _pFileBoundary is automatically set to <channel> |
| SaveEncoding | The encoding scheme to use for the XML file. Examples
are 'utf-8', 'ISO-8859-1' and 'windows-1252'. <?xml version="1.0" encoding="utf-8"> |
| SaveBlobsAsCData | Default is 1. Blob fields will be encoded as [CDATA] in the XML file. This is necessary for blobs containing binary characters. (ie Non ASCII characters) |
| SaveMemosAsCData | Default is 1. Memo fields will be encoded as [CDATA] in the XML file. This is necessary for memos containing binary characters. (ie Non ASCII characters) |
| SaveStringsAsCData | Default is 0. If set all String fields will be encoded as [CDATA] in the XML file. This is necessary for strings containing binary characters. (ie Non ASCII characters). You can set this property for individual fields. (See Properties which can be set in SaveTweakFieldSettings) |
| StandAlone | Allows you to set the StandAlone property in the xml
header. Can be set to 'yes' or 'no'. <?xml version="1.0" standalone="yes"> |
| SoapBodyBoundary | The name of the SOAP Body boundary. The default is
soap:Body. Only used if .SOAPEnvelope property is set to 1. <?xml version="1.0"> <soap:Envelope> <soap:Body> <file> <record> </record> </file> </soap:Body> </soap:Envelope> |
| SOAPEnvelope | Set this to 1 to include the SOAP envelope boundary (and Soap Body boundary) around the file. |
| SOAPEnvelopeBoundary | The name of the SOAP Envelope boundary. The default is
soap:Envelope. Only used if .SOAPEnvelope property is set to 1. <?xml version="1.0"> <soap:Envelope> <soap:Body> <file> <record> </record> </file> </soap:Body> </soap:Envelope> |
| SOAPEnvelopeBoundaryAttribute | An attribute for the soap:Envelope boundary. The default is xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" <?xml version="1.0"> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <file> <record> </record> </file> </soap:Body> </soap:Envelope> |
| ZipUseZip | Only valid for saving to an XML file on disk. If set, the XML file on disk will be compressed, using the ZIP compression scheme. |
These properties are an array, where the array index is the field number of each field in the Group, Queue, File or View record. Setting these properties allows you to modify behaviour for individual fields in the record.
| Property | Effect |
| ColumnDisabled[x] | If this is set to 1 then the field is not exported to the XML file. If the field is inside a group, then you should adjust the _sGroupLen[x] property as well. |
| _Dimension[x] | If this field is an array, then this contains the size of the array. Note that multi-dimensional arrays are always stored as single dimensioned arrays internally. Bob,dim(5,5) is the same as Bob,dim(25). |
| _sFieldName[x] | The name of the field (In other words the <tag> name). If you change this be sure to change the _sFieldNameLen[x] property as well. |
| _sFieldNameLen[x] | The length of the _sFieldName[x] property. |
| _sFieldNameAttribute[x] | The attribute which will be added to
the _FieldName tag. If you change this be sure to change the _sFieldNameAttributeLen[x]
property as well. For example, if you wish to add the attribute
save="yes" to the field number 3 (called, say, filename) then you'd set _sFieldNameAttribute[3] = 'save="yes"' _sFieldNameAttributeLen[3] = len(clip(_sFieldNameAttribute[3])) and the result would be <filename save="yes> whatever </filename> |
| _sFieldNameAttributeLen[x] | |
| SaveAsBase64[x] | Force this field to be saved as Base64. (Not currently used). |
| SaveAsCData[x] | Force this field to be encoded as [CDATA]. Useful for string fields that contain non-Ascii characters. |
| _sGroupLen[x] | If this field is a group, this contains the number of fields inside the group. If you disable fields inside a group, you should adjust this property as well. |
| _Over[x] | If this field is Over another field, then the parent field number is here. |
These methods allow you to embed code that affects the Save as it is happening.
| Method | Effect |
| SaveCurrentFieldToXML | This method is called for each field as the XML string is created. The first parameter is the field number. This provides you an opportunity to alter the value in the field before it is saved to XML. |
| SaveTweakFieldSettings | Allows you to set field related properties before the save commences. |
| SaveTweakSettings | Allows you to override properties explicitly set in the Init method. |
| ValidateRecord | This method is
called for each record while looping through the Queue, File or View.
You can add your own filter code to this method. Return one of XF:OutOfRange : Terminates the loop immediately XF:Filtered : Cycles to the next record without saving this one to the XML file. XF:Ok : Record is saved to the XML. |
![]()
Check out the Some Practical Applications section for other practical applications for xFiles.
![]()
![]()
In order to use xFiles, you need to add the Global Extension Template initially:
Click on the Global button, and Choose "Extensions", then press the "insert" button.
Choose the "ActivatexFiles - Activate Capesoft's xFiles" from the 'Class xFiles - CapeSoft xFiles - Version x.xx" section.

Remove File Prefix from field Labels - removes the file prefix from fields labels that are entered into the XML file. Note: these settings must match on import and export (if using a different instance of this control template to do the other import/export)
Replace colon in field name with a dot - if checked, all colons in field names are replaced with a dot in the XML tags (a colon is an invalid character in an XML tag)
Encoding method - allows you to select whether to use iso-8859-1, utf-8 or windows-1252. The default method is iso-8859-1, but you can force it to one of the others if you prefer.
Set Logging to - allows you to force debug logging on or off - otherwise you can use the compile time settings that are in the classes (normally off).
Customize Header and Footer - allows you to enter a customizable Header and or Footer (for things like RSS Feeds, etc).
Field Type Overrides - if you don't want to save MEMOs and/or BLOBs into your XML file, then you can disable this with these checkboxes.
CDATA Saving - you can encase your data in CDATA tags - you can select which field type you would like to do this for using these checkboxes
xFiles provides a template to make it simple to add an object to a procedure. To use the template:

The class details tab allows properties to be added to the class and methods to be added, overloaded or customised and provides access to the method and data embeds for the object.
You can populate this control template onto a window, and export a file/queue/group to a file from a button on the window.
![]()
You can setup the following options in the control template:

Local Data - the data source (typically this would be the name of the file to export - or the queue or group)
XML File - the file to export the data to. You can use quotes or a variable name.
Display Status - shows a message after exporting or importing the file.

Remove File Prefix from field Labels - removes the file prefix from fields labels that are entered into the XML file. Note: these settings must match on import and export (if using a different instance of this control template to do the other import/export)
Encoding method - allows you to select whether to use iso-8859-1, utf-8 or windows-1252. The default method is iso-8859-1, but you can force it to one of the others if you prefer.
Set Logging to - allows you to force debug logging on or off - otherwise you can use the compile time settings that are in the classes (normally off).
Customize Header and Footer - allows you to enter a customizable Header and or Footer (for things like RSS Feeds, etc).
Field Type Overrides - if you don't want to save MEMOs and/or BLOBs into your XML file, then you can disable this with these checkboxes.
CDATA Saving - you can encase your data in CDATA tags - you can select which field type you would like to do this for using these checkboxes
Item
QUEUE,PRE()
Title
STRING(252)
Description
STRING(1024)
Link
STRING(252)
ExtraFieldsInHere FieldTypes
END
Your queue must be labeled 'Item' and have the 'Title', 'Description' and 'Link' fields present. You can include additional fields for extra information as well (which will be ignored by the RSS aggregator).
ThisXMLFile.CustomSectionAfterFileBoundary = '<title>My RSS Feed</title><13,10>' |
& ' <description>My Description</description><13,10>' |
& ' <link>www.mywebsite.com</link><13,10>' |
& ' <language>en-US</language><13,10>' |
& ' <webMaster>webmaster@mydomain.com</webMaster><13,10>'
! This will load the existing RSS feed into our RSS feed queue
ThisXMLFile.RSSVersion = '2.0' ThisXMLFile.load(RSSFeedQueue,'RSSFeedfile.xml')
Item.Title = 'My New Item'
Item.Description = 'My new RSS feed description'
Item.Link = 'www.mywebsite.com\MyNewItem.htm'
Add(Item,1)
ThisXMLFile.save(RSSFeedQueue,'RSSFeedfile.xml')
This will create the file locally, and you'll need to upload it (which you will require an FTP process - ideally like NetTalk's SendFTP).
Many people are used to storing global settings in INI files, or perhaps a registry. There' s a much easier way using xFiles to store global settings. Because xFiles stores (and retrieves) a generic group structure, you can add variables without worrying about updating your store variable procedure. The only thing you need to be aware of is that variables stored (and retrieved) must be within a group structure. For example:
GlobalSettings
group, pre(GLOSET)
! Everything in this group will be stored in the XML
settings file
WebSite
string(252)
EmailAddress
string(252)
end
FTPPostWindowThread long ! Not stored in
the XML settings file - we don't want this stored.
In our code, we simply call the save (and load) command for storing (and retrieving) the global settings we require preserved:
ThisXMLFile.save(GlobalSettings,'GlobalSettingsFile.xml')
and
ThisXMLFile.load(GlobalSettings,'GlobalSettingsFile.xml')
SOAP Servers are programs out on the network that you can interact with. Each program is different, but a protocol, SOAP, exists which makes it possible for different programs to communicate with each other.
SOAP packets are usually passed between programs using TCP/IP connections, and wrapped with a HTTP header. A tool like NetTalk makes this really easy to do. However inside the packet the request is formatted using XML, and thus XFiles can be very useful in this regard.
A complete description of SOAP is beyond the scope of this document, however you do not usually need to be a SOAP expert in order to make simple SOAP servers and clients.
You will find some working examples in \Clarion\3rdParty\Examples\SOAPClient. These examples use NetTalk to run, but you can convert them to use other networking tools if you wish.
A SOAP envelope is automatically wrapped around your regular XML if you set the SOAPEnvelope property to 1.
A typical SOAP request looks like this;
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ChangeLengthUnit xmlns="http://www.webserviceX.NET/">
<LengthValue>5</LengthValue>
<FromLengthUnit>Centimeters</FromLengthUnit>
<ToLengthUnit>Inches</ToLengthUnit>
</ChangeLengthUnit>
</soap:Body>
</soap:Envelope>
However different soap servers require different specific tags. To support this xFiles allows you to set the specific text for each part of the packet. Here is the request again, but this time I've replaced the optional parts with the name of the property you can set.
<?xml version="1.0" encoding="SaveEncoding"?>
<SOAPEnvelopeBoundary
SOAPEnvelopeBoundaryAttribute>
<SOAPBodyBoundary>
<_pFileBoundary
p_FileBoundaryAttribute>
<_pRecordBoundary
_pRecordBoundaryAttribute>
<LengthValue>5</LengthValue>
<FromLengthUnit>Centimeters</FromLengthUnit>
<ToLengthUnit>Inches</ToLengthUnit>
</_pRecordBoundary>
</_PFileBoundary>
</SOAPBodyBoundary>
</SOAPEnvelopeBoundary>
The above properties can all be set in the SaveTweakSettings method. Note that the _pFileBoundary tag is optional, and should be set to nothing if it is not required.
Other properties you need to set are .SOAPEnvelope (set to 1 to wrap the XML in a Soap Envelope) and .TagCase (usually you need to set this to XF:CaseAsIs - more on that in a moment.)
For example, the code to create the packet above looks like this
xml.SOAPEnvelope = 1
xml.SaveEncoding = 'utf-8'
Xml._pFileBoundary = ''
Xml._pRecordBoundary = 'ChangeLengthUnit'
Xml._pRecordBoundaryAttribute = 'xmlns="http://www.webserviceX.NET/"'
Xml.TagCase = XF:CaseAsIs
xml.SOAPEnvelopeBoundaryAttribute = |
'xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"'
& |
' xmlns:xsd="http://www.w3.org/2001/XMLSchema"'
&|
' xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"'
xml.SOAPEnvelopeBoundary = 'soap:Envelope'
xml.SOAPBodyBoundary = 'soap:Body'
For the actual XML in the middle, a simple group is all that is required.
RequestGroup GROUP,PRE(Request)
LengthValue DECIMAL(9,3),NAME('LengthValue')
FromLengthUnit STRING(32),NAME('fromLengthUnit')
ToLengthUnit STRING(32),NAME('toLengthUnit')
END
(Take notice of the Name attribute, more on that in a minute.)
After setting all the values in the group to their desired state, you can then create the PostString (ready for the NetTalk side of things) using 2 simple lines of code.
xml.Save(RequestGroup)
PostString = xml.xmldata
The call to Save converts the group into XML, and stores the result in the .XmlData property. Because the .SOAPEnvelope property (and all the other properties) have been set appropriately in SaveTweakSettings, the text that is in .XmlData is the complete SOAP request.
It is worth mentioning a slight complication alluded to earlier which needs
to be taken into account. Most SOAP servers are picky, and require the tag names
to be case sensitive. In other words
<LengthValue>5</LengthValue> is not the same as
<lengthvalue>5</lengthvalue> which is not the same
as
<lengthValue>5</lengthValue>
The most common mistake when speaking to a SOAP server is getting these tag names not-quite-right, and hence the server returns an error. xFiles supports a variety of possible tag cases (when creating the XML) and these are set using the .TagCase property as we saw above. Possible values for .TagCase are XF:CaseLower, XF:CaseUpper, and XF:CaseAsIs.
If your SOAP server requires upper, or lower case tags, then you don't need to worry about the External Name for each field, just set the .TagCase property to the appropriate value and continue. If however the server requires a mixed case (as this example does) then you need to set the Name for each item in your group. Be very careful with the case - in this example the LengthValue tag started with a capital letter, but the fromLengthUnit tag did not.
But wait, there's more. Every so often you come across a SOAP packet that has 2 (or possibly more) parts. Something like this;
<?xml version="1.0"
encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<AuthHeader xmlns="urn:schemas-cardinal-com:2006:04:alaris:gateway:alarisgateway">
<ClientIdentifier>guid</ClientIdentifier>
</AuthHeader>
</soap:Header>
<soap:Body>
<QueryPatientId xmlns="urn:schemas-cardinal-com:2006:04:alaris:gateway:alarisgateway">
<deviceId>string</deviceId>
</QueryPatientId>
</soap:Body>
</soap:Envelope>
Now this SOAP Packet contains 2 parts,
a Header part and a Footer part. Which effectively means the SOAP packet
contains 2 structures (in this case 2 groups). The key to understanding how to
create this packet rests on two items;
a) See this primarily as a Multi-Part xml file, not as a SOAP packet
b) follow the directions below "Storing
Multiple Things in the same XML file"
For completeness sake, here is the code that creates the above packet. However you will need to read the section below before this code will make sense.
Structures
AuthHeader
GROUP,PRE()
ClientIdentifier STRING(255),NAME('ClientIdentifier')
END
QueryPatientId GROUP,PRE()
deviceId
STRING(255),NAME('deviceId')
END
Code
xml.SaveEncoding =
'utf-8'
xml.TagCase = XF:CaseAsIs
xml.RootBoundary = 'soap:Envelope'
xml.RootBoundaryAttribute = |
'xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"' &|
' xmlns:xsd="http://www.w3.org/2001/XMLSchema"' &|
' xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"'
xml.DontCloseTags = 1
Xml._pRecordBoundaryAttribute = 'xmlns="urn:schemas-cardinal-com:2006:04:alaris:gateway:alarisgateway"'
xml.save(AuthHeader,'soap:Header','AuthHeader')
xml.append = 1
xml.DontCloseTags = 0
xml.Save(QueryPatientId,'soap:Body','QueryPatientId' )
As you can see the above commands are Saving the structures to a string, not a file, and as will all strings the result is in xml.xmldata.
Exporting a whole data table, including all records and all fields to an xml file is easy. Simply use the .Save method. For example
xFileXML.Save(Customers, 'customers.xml')
If however you only want to export a subset of the fields, or records, or if you want to specify the sort order for the export, then the above command is too limited. In this case what you need to do is export the xml using a VIEW as the data source, rather than a file.
The Dict example, which you'll find in the \clarion\3rdparty\examples\xfiles\dict folder has an example of creating a view, and then using it to create the xml file.
For example
xml xFileXml
ThisView View(Wages)
Project(wag:Employee)
End
code
xml.Save(ThisView,'employees.xml')
The important thing to remember about views is that you get to decide which fields are included, and which are excluded. In addition you decide what the FILTER and ORDER properties for the view are.
Last, but not least, it's useful to remember that all Browses and Reports in your application are based on Views. Thus it is possible to export the contents of a Browse, or Report, to XML but using this xFiles function, and making use of the views constructed for you by these templates.
Up to now all the examples have shown a single entity (Group, Queue, File or View) being stored in an XML file. However it is possible to store multiple entities in the same file or string.
In order to place multiple entities in the same xml file the following basic steps occur;
1. Get the class ready, by setting the Root-Node (the wrapper around the whole thing) and telling the class not to automatically close the root node.
xml.RootBoundary = 'whatever'
xml.DontCloseTags = 1
2. Save the first entity as normal
xml.Save(ReportFormat ,Loc:XmlName,'Document','Record') !(For saving to a file)
xml.Save(ReportFormat ,'Document','Record') !(For saving to a string)
3. Set the append flag so the following items are appended
xml.append = 1
4. Add as many entities to the file as you like, using the normal techniques. Although the boundaries do not have to be unique you may chose to make them unique so they can be loaded separately later on.
xml.Save(rrDefnFieldsLocalView,Loc:XmlName,'DefnFieldsLocal','Record')
xml.Save(rrDefnFieldsGlobalView,Loc:XmlName,'DefnFieldsGlobal','Record')
5. Finally before sending the final entity, tell the object to close the root tag.
xml.DontCloseTags = 0
xml.Save(rrDefnBandControlsView,Loc:XmlName,'DefnBandControls','Record')
xml.append = 0
NOTE: This approach cannot be used if a zipped xml file is being made using the built-in zipping classes.
The high-precision timer classes are mostly used for a stopwatch effect. You can basically start a number of stopwatches simultaneously to track the time events take to occur.
To make use of the Timer class, add xFiles in the normal manner (i.e. the Global extension template , and the local extension template) - but use the xFileFastTimer class in the template prompt for the class type:

To start the timer, code the following where it is required:
MyTimer.StartTimer(1)
!Start timer 1
MyTimer.StartTimer(2) !Start timer 2
![]()
Notes on getting started.
The examples are an excellent place to get started. The JumpStart example is a quick and easy way to see how to use xFiles with the minimum of code or effort. The xFiles Demo example is also an good place to see a few of the basic uses of xFiles, it uses the xFileXML and xFileBinary classes and demonstrates a few of the basic of using xFiles classes.
| xFiles Examples | |||
| Jumpstart | Clarion\3rdparty\Examples\xFiles\JumpStart The result of following the JumpStart section. The most basic example of how to use xFiles. The app file is xfJump.app. See JumpStart for more details. |
||
| Demo | Clarion\3rdparty\Examples\xFiles\Demo A basic example of using xFiles, this example exports a browse (either as a Queue, or as a View) to an XML file. It also demonstrates the usage of the xFileBinary class to load the XML file into a string so that it can be displayed. |
||
| Demo FE |
Clarion\3rdparty\Examples\xFiles\Demo FE This is a modified version of the Basic example. It uses File Explorer to display the XML instead of loading the string into a text control. This allows the XML to be displayed with color syntax highlighting and interactivity. The example is identical except for the ViewXML window which doesn't use the xFileBinary class, it just displays the XML file using File Explorer. See www.capesoft.com/accessories/fileexplorersp.htm for more information on CapeSoft File Explorer. This example is for Clarion 5.5 and above (File Explorer does not support Clarion 5). |
||
| Demo Full |
Clarion\3rdparty\Examples\xFiles\Demo Full A fuller example application, which
also demonstrates creating the XML from a queue in memory (using a string)
as well as writing to a file and loading the XML file into the browse
queue. This example will grow significantly in future releases to demonstrate
the full functionality of xFiles. |
||
| Dict | Clarion\3rdparty\Examples\xFiles\Dict An example of source procedures in an app that export a file to xml, and a view to xml. |
||
| Simple Project |
Clarion\3rdparty\Examples\xFiles\Simple Project A very simple project and CLW file. Includes the xFiles.inc
files and uses a xFileBinary object to write data to disk. |
||
| Convert |
Clarion\3rdparty\Examples\xFiles\SOAPClient\Convert A simple SOAP example that connects to a SOAP server out on the web. |
||
The goal of this section is to document the techniques used to import structures that, while legal, are in some way obtuse. Various cunning techniques are covered here, although you may not need to use any of them in normal XML importing operations.
1. Importing the whole xml data record into a field in the destination structure
There are cases when you want to parse the incoming xml into fields as normal, but you also want to store the original xml for the whole record in a field. Indeed this may be the only field in your incoming structure. To do this set the StoreWholeRecord property to 1, and make a field in your receiving structure with the same name as the Record Boundary. Note that if the xml you are importing contains a Field with this name as well, then you cannot make use of this option, or the whole xml will overwrite the incoming field value.
2. Importing from XML where there are multiple fields with the same name
It is legal in XML to have multiple fields (or attributes) which are siblings of each other, with the same name. For example;
<product>
<name>Car</name>
<price type="purchase">22000</price>
<price type="lease">2000</price>
</product>
This can be imported by using a well-crafted strcture, as well as making use of the Name attribute. The structure for the above would be;
Product Group
name String(20)
type1 String(20),name('type')
price1 Long,name('price')
type2 String(20),name('type')
price2 Long,name('price')
End
Note that in the above structure the external names are
duplicated. This is legal.
Notice also that the order of the fields is critical. Without the ability to
match exclusively on the name, xFiles will take the order of the fields into
account.
Lastly notice that the attribute comes before
the field. so the Type comes before the Price.
This lists the Classes provided by xFiles at this time, along with a description of the functionality provided by each class.
| xFiles Classes | |||
| xFileBinary | Binary file
handling - high speed reading and writing of all file types (binary and
text) with minimal coding (simply call a single method to load the file
into memory using a string or save a file from memory to disk.) |
||
| xFileExplode | Handling decompression of files
compressed using the PKWare implode/explode algorithm. Does not support
compression. |
||
| xFileFastTimer | High speed,
accurate timers. |
||
| xFileLinkDLL | Easy support for run time linking
of DLLs and locating procedures in the DLLs when loaded.
Click Here To see the
QuickStart guide. |
||
| xFileSettings | An easy to
use replacement for GetINI and PutINI - writes to XML files instead of
INI files. |
||
| xFileXML | Write any queue, group, view or file to
an XML file and read XML files directly into a queue, file or group.
Click Here to see the QuickStart guide. |
||
| xFileZip | Handles compression
and decompression using a ZIP algorithm. |
||
| xFileBase | Internal
base class, does not contain accessible functionality |
||
| xFileBaseCompress | Internal
base class for compression |
||
The methods for each class is listed below, along with a fuller explanation of what the classes do. See the Examples for more. Please note this section of the documentation is under construction and we are expanding it to include all class methods and a full description, usage information, examples etc.
| xFileXML Methods | |||
| The XFileXML class provides the ability to easily load XML files from disk into a group, file or queue, and save a group, file, view or queue to disk as an XML file. Writing a data structure to disk can be done by calling a single Save method. Similarly, reading an XML file into a group, file or queue is as simple as calling the Load method. |
|||
| AddRecord | Add a record to the object loaded by xFileXML (queues and files only). | ||
| Copy | Copy data to or from the data structure being used by xFileXML. Allows the contents of a queue to be copied into a File being used, or data from a different queue or group to be copied into the queue or group used by the xFileXML object. | ||
| Init | Initialise an xFileXML object to use a particular queue and data structure. | ||
| Load | Load from file to the data structure. | ||
| Save | Save to the XML file (or create the XML in memory). | ||
| Advanced Class Methods | |||
| Generic File Loading and Saving | |||
| SaveBinData | Saves the binData string property to the file name specified. | ||
| LoadBinData | Loads a file into the binData string property. | ||
| XML file modification and settings | |||
| CreateFooter | Creates a string that is appended after the file data. | ||
| CreateHeader | Creates the XML header that is added to the file. | ||
| LoadTweakSettings | Called when the Save is about to be done to allow the object setting to be modified before the save code is executed. | ||
| SaveTweakSettings | Called when the Load is about to be done to allow the object setting to be modified before the load code is executed. | ||
| Record handling and management | |||
| GetValue | Gets a value of a field when passed the field name (Files only). | ||
| SetValue | Sets the value of a field when passed the name and value (Files only). | ||
| InsertFileRecord | Inserts a record in the file (File only). | ||
| UpdateFileRecord | Updates a record in the file (File only). | ||
| RecordCount | Returns the number of records in the file or queue. | ||
| FreeFileData | Deletes all records in the file. | ||
| FreeGroupData | Clears the group. | ||
| FreeQueueData | Deletes all queue records. | ||
| ValidateRecord | Used when reading into a Queue, or File, or writing from a Queue, File, or View. This method allows you to suppress records by returning the value | ||
| AddOldField | If one of the fields in your Group, Flie, Queue or View has changed, and exported XML files exist that are still using the old field names, you can use this to tell XFiles to import the the value into the renamed field. | ||
| LoadAllOldFields | This is called when Load is called. Embed your calls to AddOldField() here, after the parent call. | ||
| CleanFileName | Called when a file is saved to ensure there are no invalid characters in the file name. | ||
| xFileXML Properties | |||
|
|
|||
| dontReplaceColons | Replaces colons with full stops when writing prefixes to the file (on by default) | ||
| IgnoreGroupTags | Ignores groupings when loading and saving. | ||
| loadFields | Specify the number of fields to load | ||
| saveFields | Specify the number of fields to save | ||
| addFields | Set the number of fields to add when the AddRecord()method is called | ||
| dontLoadLastFields | Exclude certain fields when loading | ||
| dontCopyLastFields | Exclude certain fields fields when the Copy() method is called | ||
| dontAddLastFields | Exclude certain fields when the AddRecord() method is called | ||
| columnDisabled | An array of columns that allows specific columns to be ignored when loading and saving | ||
| _pFileBoundary | A custom boundary for the XML data (the tag that begins and ends the data being read or written). If this property is set to nothing then it will be ignored. | ||
| _pFileBoundaryAttribute | Added to the file boundary tag when writing an XML file. | ||
| _pRecordBoundary | A custom boundary tag for delimiting records in the XML file | ||
| _pRecordBoundaryAttribute | Added to the record boundary tag when writing an XML file. | ||
| binData | The internal string that stores data being read or written to and from XML files | ||
| binDataLen | The length of the internal data storage (binData) string | ||
| xmlData | A string that stores the XML created when using the loadFromString and saveToString options | ||
| xmlDataLen | The length of the xmlData property in bytes. | ||
| saveToString | Modifies the Save() method's behaviour so that it creates the XML and save it to the xmlData property rather than writing it to disk (save to memory). | ||
| SOAPEnvelope | Set this to 1 to generate a SOAP heading, and envelope, around the XML. | ||
| SOAPEnvelopeBoundary | Sets the <Soap:Envelope>tag | ||
| SOAPEnvelopeBoundaryAttribute | Optionally include attributes in the <Soap:Envelope> tag | ||
| SOAPBodyBoundary | Sets the <Soap:Body>tag | ||
| TagCase | Determines the case of the field Tags in the XML. Set to XF:CaseLower (default),XF:CaseUpper or XF:CaseAsIs. | ||
| UpdateAsWhole | If an incoming record updates an existing record, then assume the incoming record overwrites _all_ the fields of the existing record. Note this mode is not supported if the file has memo or blob fields. | ||
| loadFromString | Modifies the Load() method's behaviour so that it loads directly from memory using the xmlData property rather than loading from a file. | ||
| OmitXMLHeader | Creates the XML files without the header line | ||
| dontCleanFileName | If this is set the CleanFileName method will not check for invalid characters when saving the XML file. This property is not normally used. | ||
| StoreWholeRecord | If set to true, and there is a field in the structure with the same name as the record boundary, then the xml for the whole record is placed in that field. | ||
![]()
| xFileLinkDLL Methods | |||
| The xFilesLinkDLL class provides runtime DLL loading. This allows you to load a DLL when your program is running and access functions provided by that DLL. The DLL itself is not linked into your application at compile to using a LIB file. This is useful when your application depends on an external DLL, or there is functionality that is only provided when a particular DLL is available, or for functions that are specific to certain version of Windows etc. |
|||
| Construct | Constructor that is called when the object is created. | ||
| Destruct | Destructor that is called when the object is destroyed. | ||
| LinkDLLFunction | Loads a function from a DLL. If the DLL is not already loaded it loads the library. | ||
| Init | Initialisation method, does not perform any functionality and is provided for overriding the default behaviour. | ||
| xFileLinkDLL Properties | |||
| dontDisplayMessages | Replaces colons with full stops when writing prefixes to the file (on by default) | ||
| _DLLModules | Specify the number of fields to load | ||
![]()
xFileXML.AddRecord
(<any p_F1>,<any p_F2>,<any p_F3>, ...)
Adds a record to the xFilesXML record queue. The method takes up to 20 ANY parameters,
which allows the addition of records to a queue where the type of a field is
not known.
Parameters:
| Parameter | Description |
| <any p_F1>,<any p_F2>,<any p_F3>, ... | Up to 20 parameters of the ANY type can be passed. Each parameter populates a field in the record that is to be added to the queue. |
See Also:
xFileXML.Load(), xFileXML.Save()
xFileXML.Copy (*Group p_Group, byte p_Direction=0)
xFileXML.Copy (*Queue
p_Queue, byte p_Direction=0)
Copies the records from the internal xFileXML group/queue property to the passed
group/queue, or from the passed group/queue to the xFiles group/queue. The direction
parameter specifies whether the data is copied from the parameter to the xFilesXML
property or from the property to the passed variable.
Parameters:
| Parameter | Description |
| *Group p_Group or *Queue p_Queue | The queue or group to copy to or from (depending on the value of the direction parameter). |
| byte p_Direction | If p_Direction is 0 then the data is copied from
the xFilesXML object to the passed group/queue. If p_Direction is 1 then records are copied from the passed queue or group to the xFilesXML object. |
See Also:
xFileXML.Load(), xFileXML.Save()
xFileXML.Init
(*Queue p_Queue, string p_FileName)
xFileXML.Init (*Group p_Group, string p_FileName)
xFileXML.Init (*File p_File, string p_FileName)
xFileXML.Init (*View p_View, string p_FileName)
Initialises the xFileXML object to the a particular data structure and file, you can call this method at any point to change the data structure that is read from and written to, and the XML file that is used. If you are setting any of the class properties such as LoadFields and SaveFields then Init must be call after setting the class properties in order to use them.
Note: As well as passing a Queue, you can also pass a Group, File or View to the Init method to have xFiles read and write using a group, file, view or queue. (Views are Write-Only, not Read).
Note: You don't need to call
Init
unless you set advanced class properties like xFileXML.loadFields, xFileXML.saveFields
and xFileXML.copyFields. If you set these properties to change which fields
are saved then you need to use the first method above and call
Init().
Otherwise you can call the Load and Save methods and pass them the queue/group/file/view
and file name without calling Init().
Parameters:
| Parameter | Description |
| *Queue p_Queue or *Group p_Group | The label of the queue or group that the data is read from and written to. |
| string p_FileName | The name of file to read from and write to. |
Examples
| Example |
! DATA myQueue queue from string(80) to string(80) end xmlFileName string(260) ! CODE xmlFileName = 'myXmlFile.xml' thisFileXML.Init(myQueue, xmlFileName) |
See Also:
xFileXML.Load(), xFileXML.Save()
xFileXML.Load
(*Queue p_Queue, string p_fileName, <string p_FileBoundary>,<string
p_RecordBoundary>)
xFileXML.Load (*Group
p_Group, string p_fileName, <string p_FileBoundary>,<string p_RecordBoundary>)
xFileXML.Load (*File p_File, string p_fileName, <string p_FileBoundary>,<string p_RecordBoundary>)
xFileXML.Load (*Queue p_Group, *String p_XMLString, Long p_XMLStringLength, <string p_FileBoundary>,<string p_RecordBoundary>)
xFileXML.Load (*Group p_Group, *String p_XMLString, Long p_XMLStringLength, <string p_FileBoundary>,<string p_RecordBoundary>)
xFileXML.Load (*File p_File, *String p_XMLString, Long p_XMLStringLength, <string p_FileBoundary>,<string p_RecordBoundary>)
xFileXML.Load
()
Loads an XML file into the data structure.
The first parameter is the Clarion data structure that will receive the parsed XML. Valid structures are a Queue, File or Group.
The second parameter is the name of the file on disk, or the name of the string which is holding the XML in memory. If the XML is in a string, then an additional parameter, the length of the string, is required at this point.
Following this are 2 optional parameters that allow you to specify the File Boundary, and Record Boundary tags.
The .Load method (no parameters) ultimately loads the XML
into the specified structure. It is included here for completeness but it should
not usually be called directly.
Parameters
| Parameter | Description |
| *Queue p_Queue or *Group p_Group or *File p_File |
The queue, file or group that the xml data will be loaded into. |
| string p_FileName | The name of file to read from. |
| *String p_XMLString | The string variable containing the whole, valid, XML data. |
| Long p_XMLStringLength | The length of the XML string. |
| <string p_FileBoundary> | The file boundary tag in the XML file. Optional. Default is file, view, queue or group. If the p_FileBoundary parameter is set then the p_RecordBoundary parameter must be set as well. |
| <string p_RecordBoundary> | The Record boundary tag in the XML file. Optional. Default is item (for File or Queue) or data (for Group). If the p_RecordBoundary parameter is set then the p_FileBoundary parameter must be set as well. |
Examples
| Example 1 - Calling Load by passing the data structure and file name. |
! DATA myQueue queue from string(80) to string(80) end xmlFileName string(260) CODE xmlFileName = 'myXmlFile.xml' thisFileXML.Load(myQueue, xmlFileName) |
| Example 2 - Calling Load after calling Init |
! DATA myGroup group from string(80) to string(80) end xmlFileName string(260) CODE xmlFileName = 'myXmlFile.xml' thisFileXML.Init(myGroup, xmlFileName) thisFileXML.Load() |
See Also:
xFileXML.Save(), xFileXML.Init(), Loading XML Files
xFileXML.Save
(*Queue p_Queue, string p_fileName, <string p_FileBoundary>,<string p_RecordBoundary>)
xFileXML.Save (*File p_File, string p_fileName, <string p_FileBoundary>,<string p_RecordBoundary>)
xFileXML.Save
(*View p_View, string p_fileName, <string p_FileBoundary>,<string p_RecordBoundary>)
xFileXML.Save (*Group
p_Group, string p_fileName, <string p_FileBoundary>,<string p_RecordBoundary>)
xFileXML.Save
(*Queue p_Queue, <string p_FileBoundary>,<string p_RecordBoundary>)
xFileXML.Save (*File p_File <string p_FileBoundary>,<string p_RecordBoundary>)
xFileXML.Save
(*View p_View <string p_FileBoundary>,<string p_RecordBoundary>)
xFileXML.Save (*Group
p_Group <string p_FileBoundary>,<string p_RecordBoundary>)
xFileXML.Save ()
Saves a Clarion data structure into an XML file, or string.
The first parameter is the Clarion data structure that holds the data to be exported. Valid structures are a Queue, File, View or Group.
The second parameter is the name of the file on disk. If the XML is to be stored in a string, in memory, then this parameter is ignored.
Following this are 2 optional parameters that allow you to specify the File Boundary, and Record Boundary tags.
The .Save method (no parameters) ultimately saves the XML into the file or string. It is included here for completeness but it should not usually be called directly.
Parameters:
| Parameter | Description |
| *Queue p_Queue or *Group p_Group or *File p_File or *View p_View |
The label of the queue, file, view or group that contains the data to be saved to the XML file or string. |
| string p_FileName | The name of the XML file to store the data in. If this file does not exist it will be created. If this parameter is omitted completely then the XML will be written into a string. This string is accessible after the call to .Save in the object's XmlData property. The length of the string is in the XmlDataLen property. |
| <string p_FileBoundary> | The file boundary tag in the XML file. Optional. Default is file, view, queue or group. If the p_FileBoundary parameter is set then the p_RecordBoundary parameter must be set as well. |
| <string p_RecordBoundary> | The Record boundary tag in the XML file. Optional. Default is item (for File or Queue) or data (for Group). If the p_RecordBoundary parameter is set then the p_FileBoundary parameter must be set as well. |
Examples
| Example 1 - Calling Save by passing the data structure and file name |
! DATA myQueue queue from string(80) to string(80) end xmlFileName string(260) CODE xmlFileName = 'myXmlFile.xml' thisFileXML.Save(myQueue, xmlFileName) |
See Also:
xFileXML.Load(), xFileXML.Init()
xFileXML.SaveBinData (<string fileName>)
Saves the current contents of the binData property to disk using the either the file name passed using the fileName parameter, or the file name set when the Init() method of the object was called. This method along with the LoadBinData() provides generic reading and writing of files to and from memory. This method does not parse the string in any way and will not load the data into a queue, group or file. Use the Load() method to load XML files into data structures. This method essentially exposes the generic file handling provided by the parent xFileBinary class, which provides file handling (reading and writing) along with on the fly compress/decompression etc..
When used in conjunction with the .saveToString property this can be used to customise the XML produced before writing it to disk by calling SaveBinData.
Note: To create a ZIP compressed file containing the data in the .binData string, set the ZipUseZip property to 1 before calling the SaveBinData. This same technique can be use to ZIP compress and decompress XML files on-the-fly using the Load() and Save() methods.
Parameters
| Parameter | Description |
| string fileName | An optional parameter that specifies the name of the file to save. This must be passed if the Init() method has not been called to set the file name. |
Return Values
If the call fails it returns zero and the ErrorTrap method of the class is called with the error details. You can add code to the ErrorTrap method to display errors, log them to debug output etc.
Examples
| Example 1 - Saving data from the binData string to disk |
|
code
if not
xFileXml.binData &= null Dispose(xFileXml.binData) end xFileXml.binData &= new string(myXmlSize) xFileXml.binDataLen = myXmlSize ! Add data to the string, such as custom XML xFileXml.binData = Clip(string1) & Clip(string2) xFileXml.SaveBinData('myfileName.xml') |
See Also
LoadBinData(), Save(), Load(), binData, binDataLen, saveToString, loadFromString
xFileXML.LoadBinData (<string fileName>)
Loads a string directly into the binData property of the class with doing any parsing or handling of the contents of the file. When this method is called the .binData property of the class is receives the contents of the file (memory allocation and disposable is handled by the class). In addition the .binDataLen property of the class is set to the size of the file loaded (in bytes).The .binData property is a string.
This method along with SaveBinData() expose generic file reading and writing using the xFileXML class. This can be useful when used with the .saveToString and .loadFromString properties. The data can be loaded and manipulated manually before the Load() and Save() methods are called to load (or save) the data to and from memory.
Note: To load a ZIP compressed file, set the _ZipUseZip property to 1 before calling the LoadBinData() method. This same technique can be use to ZIP compress and decompress XML files on-the-fly using the Load() and Save() methods.
Parameters
| Parameter | Description |
| string fileName | An optional parameter that specifies the name of the file to load. This must be passed if the Init() method has not been called to set the file name. |
Return Values
If the call fails it returns zero and the ErrorTrap method of the class is called with the error details. You can add code to the ErrorTrap method to display a message, handle the error, log error etc.
Examples
| Example 1 - Load data from the to disk to the xFileXML.binData string |
| code xFileXml.
LoadBinData('myfileName.xml') ! the .binData now contains the contents of the file |
See Also
SaveBinData(),Save(),Load(), binData, binDataLen,
saveToString, loadFromString
![]()
![]()
Sets the header for the XML file and adds
it to the .binData string. This is called before
data is added to the XML file. The string created is a standard XML header such
as:
'<?xml version="1.0"?><13,10>'
Note: If the .saveEncoding property is set then this string includes the encoding for the file. The .binData property is set to the string created by this method and a carriage return, linefeed pair is added to the end of the header string (ASCII 13, 10) as indicated in the code snippet above. The binDataLen property is set to the length of the .binData string property (the number of bytes in the header).
Parameters
None
Return Values
None
See Also
Creates the footer for the XML file. This is simply the closing tag for the file, such as the file boundary (see the ._pFileBoundary property). In general this method does not need to be overridden unless a custom header has been created or additional wrapper tags have been added.
Note: The footer is appended to the .binData string and the .binDataLen property incremented by the number of bytes added.
Parameters
None
Return Values
None
See Also
A purely virtual method that allows the programmer to override the settings before the Load() method actually loads and parses the XML file. Use this for setting the file or record boundaries or other settings that need to be customised to load a specific file.
Parameters
None
Return Values
None
See Also
A purely virtual method that allows the programmer to override the settings before the Save() method actually creates the XML file. Use this for setting the file or record boundaries or other settings that need to be customised before the XML is created and saved to disk or memory.
Parameters
None
Return Values
None
See Also
xFileXMLGetValue (string p_Field, long p_dim = 0)
Retrieves the value of a field when passed the name of the field. For multi dimensional fields (Clarion 6 only) the second parameter allows the dimension to be retrieved to be specified. Note that the Init()() method must have been called to specify the data structure that the xFilesXML object is manipulating before this method is called.
Note: This method is thread safe and wraps access to queues in a critical section. All the methods in xFiles are built to ensure thread safe access to data (including global, unthreaded data)
Parameters
| Parameter | Description |
| string p_Field | A string that contains the name of the field to be fetched. |
| long p_dim | An optional parameter that specifies which dimension to fetch for multi dimensioned fields. Supported in Clarion 6 only |
Return Values
The value of the field is returned as an ANY variable. If the field is not found an empty string is returned.
See Also
SetValue()
xFileXMLSetValue ( string p_Field, string p_Value, long p_dim = 0)
Sets the values of a specified field. Works for queues, groups and files. Note that the Init method must have been called to specify the data structure that the xFilesXML object is manipulating before this method is called.
Note: This method is thread safe and wraps access to queues in a critical section. All the methods in xFiles are built to ensure thread safe access to data (including global, unthreaded data).
Parameters
| Parameter | Description |
| string p_Field | A string that contains the name of the field to be to be set. |
| string p_Value | A string that contains the value to set the field to |
| long p_dim | An optional parameter that specifies which dimension to set for multi dimensioned fields. Supported in Clarion 6 only |
Return Values
Returns zero for success and -1 if the field is note found.
See Also
GetValue()
This method adds the contents of the current file buffer as a new record in the file that is associated with xFiles. This method is not generally used directly.
Note: The Load(), Save() or Init() method must be called before this method is used in order for the xFilesXML object to be associated with a particular data structure.
Note: This method only supports files and does not update any relationships.
Parameters
None
Return Values
None
See Also
This method updates the current file record with the contents of the current file buffer. This method is not generally used directly.
Note: The Load(), Save() or Init() method must be called before this method is used in order for the xFilesXML object to be associated with a particular data structure.
Note: This method only supports files and does not update any relationships.
Parameters
None
Return Values
None
See Also
InsertFileRecord()
Returns the number of records in the File or Queue that is associated with the xFiles object.
Note: The Load(), Save() or Init() method must be called before this method is used in order for the xFilesXML object to be associated with a particular data structure.
Parameters
None
Return Values
The number of records in the Queue or File that is currently associated with the xFilesXML object.
See Also
Deletes all records in the File associated with this object. All records are removed, however no relationships are updated. This method is not generally called directly. This method only applies if the xFilesXML object is being used with a File.
Note: The Load(), Save() or Init() method must be called before this method is used in order for the xFilesXML object to be associated with a particular data structure.
Parameters
None
Return Values
The number of records in the Queue or File that is currently associated with the xFilesXML object.
See Also
Clears all fields in the group that is associated with the xFileXML object. This method only applies if the xFilesXML object is being used with a Group.
Note: The Load(), Save() or Init() method must be called before this method is used in order for the xFilesXML object to be associated with a particular data structure.
Parameters
None
Return Values
None.
See Also
Deletes all records in the Queue associated with this object. This method only applies if the xFilesXML object is being used with a Queue.
Note: The Load(), Save() or Init() method must be called before this method is used in order for the xFilesXML object to be associated with a particular data structure.
Parameters
None.
Return Values
None.
See Also
xFileXML.AddOldField (string p_OldFieldName, string p_InFilePos), long
If one of the fields in your Group, Flie, Queue or View has changed, and exported XML files exist that are still using the old field names, you can use this to tell XFiles to import the the value into the renamed field. You should embed your calls to this method in the LoadAllOldFields procedure, after the parent call, as this gets call when Load is called.
Parameters
| Parameter | Description |
| string p_OldFieldName | A string that contains the odl name of the field |
| string p_InFilePos | The position in the file record at which this field resides. |
A typical call to this procedure would look something like this:
MyXML.AddOldField('OldFieldName', where(OldFieldFile.Record, OlfFieldFile.OldFieldName))
Return Values
Returns 0 if adding this old fieldname was successful. Will only fail if there is no more space for extra fieldnames. The maximum is XF:MaxFields.
See Also
![]()
This is called when Load is called. Embed your calls to AddOldField() here, after the parent call. Be sure to embed after the parent call as the parent call clears all the old fieldnames (used for the previous load).
Parameters
None.
Return Values
None.
See Also
xFileXML.CleanFileName (string p_Filename, long p_flag=0)
This is called when Load is called to
ensure that the file name has no invalid characters. ASCII control characters
with values below 21 are replaced by spaces and characters that are illegal in
Windows file names (* / \ ? < > :) are removed. Use this method to remove all
non-legal characters from a string so that it can be used in a file name. Note
that this method removes backslashes ( \ ) so it should be used on just the file
name, but NOT the path.
! to use it on a Path set the flag to XF:ALLOWBACKSLASH this flag also
implicitly allows a : in character 2 (for example 'c:\temp.xml'). Illegal
characters are replaced with a space.
To disable this behaviour set the xFileXML.dontCleanFileName property to 1.
Parameters
p_FileName
The name of the file to be saved, excludes the path to the file (unless the p_flag parameter is set to XF:ALLOWBACKSLASH to allow backslashes and handle paths). For example 'settings.xml'.
p_flag
This is a flag to override the default behaviour and allow back slashes. If this contains XF:ALLOWBACKSLASH then backslashes are allowed. Use this to allow paths to be checked.
Return Values
Returns the valid file name, after illegal characters have been removed.
These are some of the properties of the xFileXML class that you might find useful to set directly.
| loadFields | long |
This allows the number of fields to be loaded to be different from the number of fields in the queue, for example the first 5 fields might contain data, and the second 5 might be for temporary data, or the result calculations that aren't stored in the XML file. Setting loadFields to 5 will load the first 5 fields of the queue from the XML file, even if there are ten fields in the queue or file. See the Load() method. |
|
| copyFields | long |
The number of fields to copy between the two data structures when calling the Copy() method. Allows the number of fields being used to be limited. |
|
| addFields | long |
The number of fields to add when inserting a record into the queue by calling the AddRecord() method. |
|
| dontCopyLastFields | long |
The same as the dontLoadLastFields property, except for copying from one queue to another using the Copy() method. |
|
| dontAddLastFields | long |
Performs the same function as dontCopyLastFields, except for the AddRecord() method - it limits the number of fields that are added when inserting a record into the queue. |
|
| _pRecordBoundary | pString(252) |
This is the boundary between each record in the queue of file being loaded. This allows the tag used as the record boundary to be specified. |
|
| binDataLen | long |
| The size of the
binData property (in
bytes). This is set automatically when an XML file is loaded from disk. |
|
| xmlData | &string |
A string that is populated with the XML by the Save() method, if saveToString is set to 1. This allows XML to be "saved" into memory rather than written to disk directly.
See Also |
|
| xmlDataLen | long |
The length (in bytes) of the xmlData string property. The xmlData property is used for loading and saving XML to and from memory rather than from disk. See Also Properties: loadFromString, saveToString Methods: Load(), Save() |
|
| saveToString | pString(252) |
When this property is set the Save() method saves the XML data in the xmlData string instead of writing it to disk. The Save() method can be passed a blank file name if this is set, as the file name parameter is not used.
See Also |
|
| SOAPEnvelope | long |
When this property is set the Save() method wraps a SOAP envelope around the XML data.
See Also |
|
| SOAPEnvelopeBoundary | pString(252) |
This property determines the text for the Soap Envelope tag, to be used if the XML is wrapped as a SOAP request. The default is <soap:Envelope>. Be aware that some SOAP servers may treat this tag in a case sensitive manner.
See Also |
|
| SOAPEnvelopeBoundaryAttribute | pString(252) |
This property lets you set the attribute (if any is required) of the Soap Envelope Boundary tag.
See Also |
|
| SOAPBodyBoundary | pString(252) |
This property determines the text for the Soap Body tag, to be used if the XML is wrapped as a SOAP request. The default is <soap:Body>. Be aware that some SOAP servers may treat this tag in a case sensitive manner.
See Also |
|
| TagCase | pString(252) |
The field name tags are automatically detected for you by the xFiles class. In some XML situations the case of these tags may be important. This property gives you control over the case used. This property defaults to XF:CaseLower. Other options are XF:CaseUpper and XF:CaseAsIs. In order to have mixed case tags, the Name property for each field in the group/file/queue must be set. This property only applied to field-level tags, not header or boundary tags.
See Also |
|
| loadFromString | pString(252) |
|
|
|
| omitXMLHeader | long |
Omits the first tag in the XML file. See CreateHeader and CreateFooter for more information on the header and footer tags. |
|
| dontCleanFileName | long |
If set to 1 the CleanFileName method will not remove invalid characters from the file name, but simply return it as-in. This should not be used in normal circumstances. |
|
xFileLinkDLL.LinkDLLFunction (string p_DLLName, string p_FunctionName, *long p_fpFunction)
This method loads a function from a DLL when passed the name of the DLL and the name of the function to locate. If the DLL has not already been loaded it loads the DLL. The address of the function is located and stored in the passed p_fpFunction parameter .
Parameters
| Parameter | Description |
| string p_DLLName | A string containing the name of the DLL that contains the function to load. If this library has not already been loaded then the method will load it before locating the required function address. |
| string p_FunctionName | The name of the function to locate in the library. |
| *long p_fpFunction | A long that will receive the address of the function in the library. |
Return Values
Returns zero for success, or an error code if it fails.
Examples
See the "Runtime DLL Loading QuickStart Guide" for a full example and how to declare and use the addresses returned.
| Example 1 - Load a function called 'unzOpen' from a DLL called 'zip.dll' |
| code ret = xLinkDLL.LinkDLLFunction ('zip.dll', 'unzOpen', fp_unzOpen) |
See Also
These are some of the properties of the xFileLinkDLL class that you might find useful to set directly.
| dontDisplayMessages | long |
This option ensures that an error message is not displayed if a DLL fails to load or a function cannot be located. Set this option to 1 to not displayed error messages. The .ErrorTrap method will still be called with the message details when this is set to 1. |
|
xFileXML
1)
I declare the object and call Load/Save but nothing happens.
xFiles provides two ways to handle loading and saving of XML files:
- Without needing the Init method, you can call Load and Save and pass the data structure and file name directly to the load and save methods:
xFileXML.Load(p_Queue, fileName)
xFileXML.Save(p_Queue, fileName)
- By calling Init to set the data structure to use and the file name, then calling Load and Save:
xFileXML.Init(p_Queue, fileName) ! Call Init to set which data structure and file to use
xFileXML.Load()
xFileXML.Save()
You don't need to use the second method and call Init unless you set advanced class properties like xFileXML.LoadFields, xFileXML.SaveFields and xFileXML._CopyFields. If you set these properties to change which fields are saved then you need to use the first method above and call Init.
![]()
![]()
| CapeSoft Support | |||
|
|
|||
| Telephone |
+27 21 715 4000
|
||
| Fax |
+27 21 715 2535
|
||
| Post |
PO Box 511, Plumstead, 7801, Cape Town, South Africa
|
||
xFiles may be purchased for $59 from:
| CapeSoft Sales | |||
| Web | |||
|
|
|||
| Telephone |
+27 21 715 4000
|
||
| Fax |
+27 21 715 2535
|
||
| Post |
PO Box 511, Plumstead, 7801, Cape Town, South Africa
|
||
| Buy Online | |||
| Web | |||
![]()
To download the latest installation please visit
the CapeSoft
Downloads page.
Upgrades are free. This may not always be the case, but upgrades
have been free for our accessories for the past 10 years.
To install extract the Installation Program from the SAF file using the free CapeSoft Safe Reader (download for free from http://www.capesoft.com/utilities/Safe/safereader.htm).
Run the Installation Program for your version of Clarion.
This template is copyright © 2005-2010 by CapeSoft Software.
None of the included files may be distributed. Your programs
which use xFiles can be distributed without any xFiles royalties.
Each developer needs his own license to use xFiles. (Need to buy
more licenses?)
This product is provided as-is. Use it entirely at your own risk. Use of this
product implies your acceptance of this, along with the recognition of the
copyright stated above. In no way will CapeSoft Software, their
employees or affiliates be liable in any way for any damages or business losses you may
incur as a direct or indirect result of using this product
![]()
Version 2.10 (24 August 2010)
Version 2.09 (4 August 2010)
Version 2.08 (23 July 2010)
Version 2.07 (12 July 2010)
Version 2.06 (18 May 2010)
Version 2.05 (2 April 2010)
Version 2.04 (March 2010)
Version 2.03 (1 March 2010)
Version 2.02 (17 February 2010)
Version 2.00 (5 January 2010)
Version 1.99 (11 December 2009)
Version 1.98
Version 1.97
Version 1.96
Version 1.95
Version 1.94 (20 August 2009)
Version 1.93 (13 August 2009)
Version 1.92 (28 July 2009)
Version 1.91 (21 July 2009)
Version 1.90 (15 July 2009)
Version 1.89 (13 July 2009)
Version 1.88 (18 May 2009)
Version 1.87 (6 May 2009)
Version 1.86 (17 April 2009)
Version 1.85 (4 April 2009)
Added support for nested groups for both load and save.
added "standalone" property which can be se to "yes" or
"no" as desired. For example;
<?xml version="1.0" standalone="yes">
Fixed regression in XML Settings class. FileBoundary and RecordBoundary attributes now set correctly.
Fixed over-zealous error reporting in _close method. Closing an already closed file no longer results in an error.
New Jump-Start section added to the docs - Creating an XML File or String
Fixed regression with Load methods not using default
FileBoundary and RecordBoundary properties.
VERY IMPORTANT NOTE: These
properties are now no longer set to default values by the INIT method. If
you are using the (obsolete) Load mechanism of
xml.Init()
xml.Load()
Then you will need to set these two properties before the call to .Load.
(Before or after .Init is fine.) EG
self._pRecordBoundary = 'item' ! or 'data'
self._pFileBoundary = 'queue' ! or 'file', or 'view', or 'group'
As an alternative use the new forms of .Load and .Save.
Added extra Load methods to support setting the FileBoundary and RecordBoundary in the Load command.
Created a new Jump-Start section in the Docs - Loading / Importing & Parsing XML Files
Version 1.30 Beta (29 June 2007)
Version 1.23 Beta (1 May 2007)
Version 1.22 Beta (15 February 2007)
Version 1.20 Beta (06 February 2007)
Version 1.10 Beta (3 August 2006)
Version 1.09 Beta (19 June 2006)
Version 1.08 Beta (19 June 2006)
Version 1.07 Beta (6 June 2006)
Version 1.05 Beta (27 February 2006)
Version 1.04 Beta (10 November 2005)
Version 1.03 Beta (8 November 2005)
Version 1.02 Beta (13 September 2005)
Version 1.01 Beta (08 September 2005)
Version 1.00 Beta (31 August 2005)