JSON Class Update
Since my initial post regarding this class, work has continued improving it. A number of fixes and enhancement can be found in the latest version...

• Fixes to parse method - There was a problem with brace matching for "{}" and "[]" when nested in certain ways.
• Fixes to UseUTCDatetime functionality - rules are now as follows:
• UseUTCDateTime = .F. && Datetimes will stringify including Local offset from UTC
• UseUTCDateTime = .T. && Datetimes will stringify as UTC equivalent for Local
• Parse() && will always return Local equivalent
• Fixes to GetTimezoneOffset method - now respects Standard/Daylight boundaries of datetimes
• Fixed Stringify - cursors are serialized to valid JSON now
  
• Added KeyForCursor property - this allows a JSON key to be specified for identifying cursors (defaulted to "VFPData")
• Enhanced Stringify and Parse methods - they now handle the VFP Collection class with aplomb
• Added KeyForItems property - when serializing Collections, the key for the contained JSON object's array property can be defined (defaulted to "items")
• Renamed DateSerializationType property - it is now ParseDateType
• Enhanced Parse - JSON class will now (optionally) respect Class and ClassLibrary properties if they exist in a JSON object being deserialized (see ParseRespectClass property). This means that if you Stringify() a VFP Form and then Parse() the JSON (with ParseRespectClass = .T.) you will get a Form object back rather than an Empty object with the same properties as the Form.

I would consider the JSON class production-ready at this point. This doesn't mean that bugs won't be found in the future, but it has been hammered on enough that I wouldn't hesitate to use it in a production application.

Visual FoxPro Now Listed
I got in touch with Douglas Crockford and was able to get Visual FoxPro listed on JSON.org with a link to my initial post. I appreciate Douglas Crockford taking the time out of his busy schedule to list Visual FoxPro on the JSON site.

Special Thank You
Nearly all of the fixes and enhancements provided in this version of the JSON class were made possible by the help and prodding I received from Frank Dietrich of Berlin. He is an extremely bright fellow. Implementing the Timezone and Daylight vs. Standard stuff drove us both to the brink. I sincerely doubt I could have done it without his help.

Download the JSON class library (approx. 59 KB)

The download contains the JSON class in both VCX and PRG format. They are the same. Use whichever one you prefer.

VFPCompression Bug Fixes
I received some really good feedback after posting my previous blog entry concerning this library from Curt Hamlin and Eduard. There were two bugs there that I felt needed some immediate attention, so in this blog entry I present a version of VFPCompression that addresses them.

The first bug was the one that Curt Hamlin ran into where something screwy was going on if the zip file wasn't somehow relative to the files or folders being zipped. The following code...

ZipOpen("F:\MyZipFile.zip") && note zip is going to F: drive
ZipFolder("C:\MyFolder\", .F.)  && note folder being zipped is on C: drive
ZipClose()

...would result in an empty zip file being created (not good). While the other bug was the one that Eduard reported where the ZipFolderQuick function wasn't applying the optional password to the files being zipped. To make a long story short, I was able to verify that these were actual bugs in the library, and I have uploaded a new version of VFPCompression.fll that fixes them.

VFPCompression Enhancement
Something that I didn't like in the FLL was that in order to extract the contents of a zip to a particular folder that folder had to already exist in the file system. I decided that the FLL should try and create a folder if it doesn't already exist when extracting, which it now does.

VFPCompression FLL Download (approx. 38 KB)

The VFP Compression Library sample code and documentation can still be found at my previous blog entry.

Search Revisited
I've spoken about the work I was doing with Windows Desktop Search (WDS) and Visual FoxPro before on this blog here and here. Though the project I present in this blog entry began when WDS 2.0 was the latest and greatest, it was rewritten for WDS 3.0 and has been revamped some and tested with WDS 4.0 (the latest and greatest as of this writing). In any event, this project was being considered by Microsoft (MS) for inclusion as part of Sedna, but never made the cut. I later obtained permission from MS to release it on my own, but haven't found time to test it or post it until now.

Foxy Search Value
There are many things of value in the Foxy Search sample...

• Shows how to properly use the WDS OLEDB Provider from VFP.
• Provides a guide to the proper SQL syntax for WDS.
• Includes a list of fields available via the OLEDB Provider. (see fields.dbf)
• Provides VFP develpers a class for working with WDS and ultimately returning search results as VFP cursors.

If nothing else, Foxy Search provides a pretty good sample for messing with when trying out various aspects of WDS. It does not provide examples of the creation or use of IFilters, handlers, or thumbnail extractors - if you are looking for those you'll have to look elsewhere at the moment.

Foxy Search Errors
It should be noted that Foxy Search can, and will, throw errors depending on the combinations of display fields, filters, and/or sorting chosen. Rather than attempt to restrict what can and can't be chosen to lessen the errors, I felt it was easier to just allow the developer using it to mess around with everything and see what is and what isn't possible. Feel free to change the Throw Error in the Catch of the form's GetSearchResults method to handle the various errors you run into if you feel like it (or just comment it out if you want it to fail silently).

Don't Have Windows Desktop Search?
You can check whether you have Windows Desktop Search and what version of it is on your system by looking in the Control Panel's Add & Remove Programs or by looking in your registry under the "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Desktop Search" key where there is a "Version" value. If you don't have WDS (or you are running an outdated version) you can go to the MS site to download and install WDS v4.0.

Until next time... Visual FoxPro Rocks!

Download Foxy Search 1.0 (approx. 89 KB)

Figure 1: Shows Foxy Search being used to find all of the FOXUSER files on my system and display information about each result.

 

VFPConnection Library Update
It hasn't been too many days since I posted an update to this library. The two big enhancements in that update was SSL support and a mechanism for tracing. It was fairly well received and appeared to work well for those that downloaded it, but I mentioned at the end of that blog entry that I wanted to do a few other enhancements surrounding FTP commands and HTTP Posts. This update provides that functionality among other things.

What's New
I've added 10 new functions to the FLL and documentation. These include:

• HTTPSimplePost
• HTTPPost
• FTPCommands
• FTPSCommands
• URLEncode
• URLDecode
• DateStrToEpochSec
• SetConnectTimeout
• SetResponseTimeout
• CurlVersion

I've also done some refactoring within the library and a few performance enhancements (though it was pretty darn fast to already).

What's Next
If you download and use this library then you might consider taking the time to provide me feedback and any suggestions you may have for further improving it. The update provided here is a testament to the fact that your feedback is valuable and an integral part of the improvement process for the stuff I provide to the VFP Community.

Until next time... Visual FoxPro Rocks!

VFPConnection FLL Download (400 KB approx.)

VFPConnection.FLL Sample Use Code:

*!* The code below isnot designed to run all at once
*!* Run the individual examples seperately

********************************************************************
*!* Upload Examples
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
*!* FILE
?FILEGet("File:///C:\Source.txt", "C:\Destination.txt", "MyProgress()", "MyTrace()")
*!* FTP
?FTPGet("FTP://UserName:Password@somedomain.com/directory/Source.zip", "C:\Destination.zip", "MyProgress()", "MyTrace()")
*!* FTPS
?FTPSGet("FTPS://UserName:Password@somedomain.com:21/directory/Source.zip", "C:\Destination.zip", "MyProgress()", "MyTrace()")
*!* HTTP
?HTTPGet("http://www.somedomain.com/Source.htm", "C:\Destination.htm", "MyProgress()", "MyTrace()")
*!* HTTPS
?HTTPSGet("https://www.somedomain.com/Source.htm", "C:\Destination.htm", "MyProgress()", "MyTrace()")
SET LIBRARY TO

********************************************************************
*!* Download Examples
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
*!* FILE
?FILEPut("C:\Source.txt", "File:///C:\Destination.txt", "MyProgress()", "MyTrace()")
*!* FTP
?FTPPut("C:\Source.zip", "FTP://UserName:Password@somedomain.com/directory/Destination.zip", "MyProgress()", "MyTrace()")
*!* FTPS
?FTPSPut("C:\Source.zip", "FTPS://UserName:Password@somedomain.com:21/directory/Destination.zip", "MyProgress()", "MyTrace()")
*!* HTTP
?HTTPPut("C:\Source.htm", "http://www.somedomain.com/Destination.htm", "MyProgress()", "MyTrace()")
*!* HTTPS
?HTTPSPut("C:\Source.htm", "https://www.somedomain.com/Destination.htm", "MyProgress()", "MyTrace()")
SET LIBRARY TO

********************************************************************
*!*ToString Examples
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
*!* FILE
?FILEToStr("C:\Source.txt")
*!* FTP
?FTPTOSTR("FTP://UserName:Password@somedomain.com:21/directory/Source.txt")
*!* FTPS
?FTPSTOSTR("FTPS://UserName:Password@somedomain.com:21/directory/Source.txt")
*!* HTTP
?HTTPToStr("http://www.somedomain.com/Source.txt")
*!* HTTPS
?HTTPSToStr("https://www.somedomain.com/Source.txt")
SET LIBRARY TO

********************************************************************
*!* HTTP Post Examples
********************************************************************
*!* Simple HTTP Post
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
LOCAL lcPost
m.lcPost ="fname=John&lname=Smith"
?HttpSimplePost("http://www.snee.com/xml/crud/posttest.cgi", m.lcPost, "", "MyTrace()")
SET LIBRARY TO

*!* MultiPart/Form-Data HTTP Post
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
LOCAL ARRAY aryPost(2,2)
aryPost(1,1) ="fname" && name
aryPost(1,2) ="test first" && value
aryPost(2,1) ="lname" && name
aryPost(2,2) ="test last" && value
?HttpPost("http://www.cs.tut.fi/cgi-bin/run/~jkorpela/echo.cgi", @aryPost, "", "MyTrace()")
SET LIBRARY TO

********************************************************************
*!* FTP Commands Example
********************************************************************
*!*Rename FTP Directory
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
LOCAL ARRAY aryFTPCommands(4)
aryFTPCommands(1) ="CWD /"
aryFTPCommands(2) ="PWD"
aryFTPCommands(3) ="RNFR MyDir"
aryFTPCommands(4) ="RNTO RenamedMyDir"
?FTPCommands("FTP://username:password@somedomain.com/", @aryFTPCommands, "MyTrace()")
*!* ?FTPSCommands("FTPS://username:password@somedomain.com/", @aryFTPCommands, "MyTrace()")
SET LIBRARY TO

********************************************************************
*!* URL Encode/Decode Example
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
LOCAL lcString, lcEncoded, lcDecoded
m.lcString ="A!B@C#D$E%F^G&H*I(J)K_L-M=N+O[P]Q{R}S|T\U:V;W'X,Y.Z<0>1/2?3©4©5©6©7©8©9"
m.lcEncoded = UrlEncode(m.lcString)
m.lcDecoded = UrlDecode(m.lcEncoded)
?"Escaped: "+ m.lcEncoded
?"Unescaped: "+ m.lcDecoded
?"Original : "+ m.lcString
SET LIBRARY TO

********************************************************************
*!* Setting Timeouts Example
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
SetConnectTimeout(30) && Defaultis 10 seconds
SetResponseTimeout(30) && Defaultis 10 seconds
SET LIBRARY TO

********************************************************************
*!* Datetime Stringto the number of seconds from Epoch (12 Midnight on January 1, 1970)
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
?DateStrToEpochSec("Sun, 06 Nov 1994 08:49:37 GMT")
?DateStrToEpochSec("Sunday, 06-Nov-94 08:49:37 GMT")
?DateStrToEpochSec("Sun Nov 6 08:49:37 1994")
?DateStrToEpochSec("06 Nov 1994 08:49:37 GMT")
?DateStrToEpochSec("06-Nov-94 08:49:37 GMT")
?DateStrToEpochSec("Nov 6 08:49:37 1994")
?DateStrToEpochSec("06 Nov 1994 08:49:37")
?DateStrToEpochSec("06-Nov-94 08:49:37")
?DateStrToEpochSec("1994 Nov 6 08:49:37")
?DateStrToEpochSec("GMT 08:49:37 06-Nov-94 Sunday")
?DateStrToEpochSec("94 6 Nov 08:49:37")
?DateStrToEpochSec("1994 Nov 6")
?DateStrToEpochSec("06-Nov-94")
?DateStrToEpochSec("Sun Nov 6 94")
?DateStrToEpochSec("1994.Nov.6")
?DateStrToEpochSec("Sun/Nov/6/94/GMT")
?DateStrToEpochSec("Sun, 06 Nov 1994 08:49:37 CET")
?DateStrToEpochSec("06 Nov 1994 08:49:37 EST")
?DateStrToEpochSec("Sun, 12 Sep 2004 15:05:58 -0700")
?DateStrToEpochSec("Sat, 11 Sep 2004 21:32:11 +0200")
?DateStrToEpochSec("20040912 15:05:58 -0700")
?DateStrToEpochSec("20040911 +0200")
SET LIBRARY TO

********************************************************************
*!* Determine the version of libcurl and OpenSSL that were used for VFPConnection.fll
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
?CURLVERSION()
SET LIBRARY TO

***********************
FUNCTION MyProgress() && Callback from the FLL - can be used to track operation progress
***********************
*!* You can create your own function, procedure or method to handle this and name it whatever you want.
*!* The nConnectTotalBytes and nConnectBytesSoFar are private variables created on-the-fly by the FLL
?m.nConnectTotalBytes
?m.nConnectBytesSoFar
ENDFUNC

***********************
FUNCTION MyTrace() && Callback from the FLL - used to provide a detailed trace of the operation
***********************
*!* You can create your own function, procedure or method to handle this and name it whatever you want.
*!* The nTraceDataType and cTraceData are private variables created on-the-fly by the FLL
#DEFINE TYPE_TEXT 0
#DEFINE TYPE_HEADER_IN 1
#DEFINE TYPE_HEADER_OUT 2
#DEFINE TYPE_DATA_IN 3
#DEFINE TYPE_DATA_OUT 4
#DEFINE TYPE_SSL_DATA_IN 5
#DEFINE TYPE_SSL_DATA_OUT 6
#DEFINE TYPE_END 7
?ICASE(m.nTraceDataType = TYPE_TEXT, "STATUS:", ;
m.nTraceDataType = TYPE_HEADER_IN, "<RECV HEADER: ", ;
m.nTraceDataType = TYPE_HEADER_OUT, ">SEND HEADER: ", ;
m.nTraceDataType = TYPE_DATA_IN, "<RECV DATA: ", ;
m.nTraceDataType = TYPE_DATA_OUT, ">SEND DATA: ", ;
m.nTraceDataType = TYPE_SSL_DATA_IN, "<RECV SSL DATA: ", ;
m.nTraceDataType = TYPE_SSL_DATA_OUT, ">SEND SSL DATA: ", ;
m.nTraceDataType = TYPE_END, "END: ", "UNKNOWN: ")
??m.cTraceData
ENDFUNC

VFPConnection.FLL Documenation:

---

Function FTPGet()

Signature: FTPGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to download a file from an FTP site.

In order to specify port or login information you would simply include them in cSourceURL, such as “FTP://myusername:mypassword@myftpsite.com:21/mydir/myfile.zip”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function FTPSGet()

Signature: FTPSGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to download a file from an FTP site that provides FTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

In order to specify port or login information you would simply include them in cSourceURL, such as “FTPS://myusername:mypassword@myftpsite.com:21/mydir/myfile.zip”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function HTTPGet()

Signature: HTTPGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to download a file from a website.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function HTTPSGet()

Signature: HTTPSGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to download a file from a a website that provides HTTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function FILEGet()

Signature: FILEGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The full path and file name to the file you wish to copy.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback – An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to copy a file from a local or remote location.

The format for the cSourceURL parameter is slightly different than you might expect. In order to copy file C:\MyDir\MyFile.zip you would specify cSourceURL as “FILE:// C:\MyDir\MyFile.zip”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function FTPPut()

Signature: FTPPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want uploaded.

cDestinationURL - The URL to where the file specified in cSource should be uploaded to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to upload a file to an FTP site.

In order to specify port or login information you would simply include them in cDestinationURL, such as “FTP://myusername:mypassword@myftpsite.com:21/mydir/myfile.zip”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function FTPSPut()

Signature: FTPSPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want uploaded.

cDestinationURL - The URL to where the file specified in cSource should be uploaded to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to upload a file to an FTP site that provides FTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

In order to specify port or login information you would simply include them in cDestinationURL, such as “FTPS://myusername:mypassword@myftpsite.com:21/mydir/myfile.zip”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function HTTPPut()

Signature: HTTPPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want uploaded.

cDestinationURL - The URL to where the file specified in cSource should be uploaded to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to upload a file to a website.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function HTTPSPut()

Signature: HTTPSPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want uploaded.

cDestinationURL - The URL to where the file specified in cSource should be uploaded to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to upload a file to a website that provides HTTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function FILEPut()

Signature: FILEPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want copied.

cDestinationURL - The full path and file name where the file specified in cSource should be copied to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to copy a file to a local or remote location.

The format for the cDestinationURL parameter is slightly different than you might expect. In order to copy file C:\MyDir\MyFile.zip you would specify cDestinationURL as “FILE:// C:\MyDir\MyFile.zip”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function FTPToStr()

Signature: FTPToStr(cSourceURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to return a string from.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Character Data - the contents of the file specified by cSourceURL

Remarks:

This function provides the ability to retrieve a file from an FTP site as a string.

In order to specify port or login information you would simply include them in cSourceURL, such as “FTP://myusername:mypassword@myftpsite.com:21/mydir/myfile.txt”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function FTPSToStr()

Signature: FTPSToStr(cSourceURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to return a string from.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Character Data - the contents of the file specified by cSourceURL

Remarks:

This function provides the ability to retrieve a file as a string from an FTP site that provides FTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

In order to specify port or login information you would simply include them in cSourceURL, such as “FTPS://myusername:mypassword@myftpsite.com:21/mydir/myfile.txt”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function HTTPToStr()

Signature: HTTPToStr(cSourceURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to retrieve a file from a website as a string.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function HTTPSToStr()

Signature: HTTPSToStr(cSourceURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to retrieve a file as a string from a website that provides HTTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function HTTPSimplePost()

Signature: HTTPSimplePost(cPostURL, cPostData[, cProgressCallback[, cTraceCallback]])

Parameters:

cPostURL - The URL to which you want to post.

cPostData - A string consisting of a series of key-value pairs.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

The key-value pairs sent to cPostData are in the form of key1=value1. Additional key-value pairs must be delimited by "&", such as "firstname=John&lastname=Smith".

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

---

Function HTTPPost()

Signature: HTTPPost(cPostURL, aPostData[, cProgressCallback[, cTraceCallback]])

Parameters:

cPostURL - The URL to the file you wish to download.

aPostData - A multi-dimensional array containing key-value pairs

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

The aPostData array must be sent in by reference. The key-value pairs in aPostData must have the keys in column 1 and the values in column 2, such as:

aPostData(1,1) = "firstname"
aPostData(1,2) = "John"
aPostData(2,1) = "lastname"
aPostData(2,2) = "Smith"

---

Function FTPCommands()

Signature: FTPCommands(cFTPURL, aCommands[, cProgressCallback[, cTraceCallback]])

Parameters:

cFTPURL - The URL to the FTP site you wish to interact with.

aCommands - A single dimension array containing the commands you wish to have run on the FTP site.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

In order to specify port or login information you would simply include them in cFTPURL, such as “FTP://myusername:mypassword@myftpsite.com:21/.

The aCommands array must be sent in by reference. The aCommands is an array of FTP commands (as defined by RFC 959), such as:

aCommands(1) = "CWD /"
aCommands(2) = "PWD"
aCommands(3) = "RNFR MyDir"
aCommands(4) = "RNTO RenamedMyDir"

---

Function FTPSCommands()

Signature: FTPSCommands(cFTPSURL, aCommands[, cProgressCallback[, cTraceCallback]])

Parameters:

cFTPSURL - The URL to the FTP site you wish to interact with.

aCommands - A single dimension array containing the commands you wish to have run on the FTP site.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

In order to specify port or login information you would simply include them in cFTPSURL, such as “FTPS://myusername:mypassword@myftpsite.com:21/.

The aCommands array must be sent in by reference. The aCommands is an array of FTP commands (as defined by RFC 959), such as:

aCommands(1) = "CWD /"
aCommands(2) = "PWD"
aCommands(3) = "RNFR MyDir"
aCommands(4) = "RNTO RenamedMyDir"

---

Function URLEncode()

Signature: URLEncode(cString)

Parameters:

cString - The string you want encoded (escaped).

Return Value:

Character - returns the encoded equivalent of cString.

Remarks:

This function provides libcurl's "URL Escape" functionality. Any character in cString that is not a-z, A-Z, or 0-9 will be deemed unsafe and be replaced with a "%" followed by the unsafe character's hex equivalent. For instance spaces are replaced with %20 because the ASCII value of a space is 32 (0x20 in hex).

---

Function URLDecode()

Signature: URLDecode(cString)

Parameters:

cString - The string you want decoded (unescaped).

Return Value:

Character - returns the decoded equivalent of cString.

Remarks:

This function provides libcurl's "URL Unescape" functionality. Any character in cString that has been escaped/encoded with a "%" followed by its hex equivalent will be decoded to its plaintext equivalent. For instance %20 will be turned back into a space - CHR(32).

---

Function SetConnectionTimeout()

Signature: SetConnectionTimeout(nSeconds)

Parameters:

nSeconds - The number of seconds any connection operation in VFPConnection should wait before failing due to timeout.

Return Value:

None

Remarks:

This function effects all connection operations in VFPConnection. The default value for the connection timeout is 10 seconds.

---

Function SetResponseTimeout()

Signature: SetResponseTimeout(nSeconds)

Parameters:

nSeconds - The number of seconds any operation in VFPConnection should wait for a response before failing due to timeout.

Return Value:

None

Remarks:

This function effects all operations in VFPConnection that are designed to wait for a server response. The default value for the response timeout is 10 seconds.

---

Function DateStrToEpochSec()

Signature: DateStrToEpochSec(cDateTime)

Parameters:

cDateTime - A datetime string in one of the many formats.

Return Value:

Numeric - returns the number of seconds between Epoch and the datetime specified by cDateTime.

Remarks:

This function is useful when attempting to convert datetime strings you may encounter when working with web-based applications. RFC2616 specifies which datetime string formats are acceptable for HTTP applications and, in short, there are a lot of them. For instance...

Sun, 06 Nov 1994 08:49:37 GMT
Sunday, 06-Nov-94 08:49:37 GMT
Sun Nov 6 08:49:37 1994
06 Nov 1994 08:49:37 GMT
06-Nov-94 08:49:37 GMT
Nov 6 08:49:37 1994
06 Nov 1994 08:49:37
06-Nov-94 08:49:37
1994 Nov 6 08:49:37
GMT 08:49:37 06-Nov-94 Sunday
94 6 Nov 08:49:37
1994 Nov 606-Nov-94
Sun Nov 6 94
1994.Nov.6
Sun/Nov/6/94/GMT
Sun, 06 Nov 1994 08:49:37 CET
06 Nov 1994 08:49:37 EST
Sun, 12 Sep 2004 15:05:58 -0700
Sat, 11 Sep 2004 21:32:11 +0200
20040912 15:05:58 -0700
20040911 +0200

...are all acceptable. There are also a number of situations where you may be required to use or know the number of seconds since midnight January 1, 1970 (a.k.a. epoch - due to unix and POSIX systems which count time this way). In any event, this function is provided as a crutch if needed.

---

Function CurlVersion()

Signature: CurlVersion()

Parameters:

None

Return Value:

String - the versions of libcurl and OpenSSL that were used in VFPConnection

Remarks:

This may be of some interest to VFP developers who are asking for enhancements or want to ensure that this library is using the latest and greatest. The static libraries for libcurl and OpenSSL were both built from the latest source available at the time using Visual Studio 2003 and ActivePerl.

VFPCompression Update
This update contains a fix that effects the Unzip routines and a new function called ZipComment(). I've also updated the sample code and documentation that is provided with this library.

The bug that was fixed pertained to 0 byte (length) files were being ignored when a zip file's contents were extracted. The Zip routines were handling the 0 byte length files correctly.

The ZipComment() function allows you to add, replace or delete the global zipfile comment for a specified zip file. The code at the bottom of this blog entry shows an example of its use and the documentation now includes this function.

Special Thank You
Special thanks goes out to Mike Sue-Ping who posted out on the Universal Thread about the bug that is fixed in this update.

What's Next
I still plan to add more functionality to this FLL (ability to create cabs and self-extracting archives, better error handling, etc.). I'm hopeful that those of you that download this library will take the time to provide me feedback and any suggestions you may have for further improving it. If you do find a bug, please comment on it here and/or contact me directly. Note the "Contact Craig Boyd" link to the right of this blog entry.

Until next time... Visual FoxPro Rocks!

VFP Compression Update:

VFPCompression FLL Download (37 KB approx.)

VFP Compression Sample Code:

****************************
*!* Example 1
****************************
*!* Zip a file quickly withor without password protection.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipFileQuick("C:\MyFile1.txt")
?ZipFileQuick("C:\MyFile2.txt", "MyPassword")
SET LIBRARY TO

****************************
*!* Example 2
****************************
*!* Zip a folder quickly withor without respect
*!*for relative pathing of the files. Password
*!* protection can be included if desired.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipFolderQuick("C:\MyFolder")
?ZipFolderQuick("C:\MyFolder2", .T., "MyPassword")
?ZipFolderQuick("C:\MyFolder2", .F., "MyPassword")
SET LIBRARY TO

****************************
*!* Example 3
****************************
*!* Unzip a zip file quickly withor without respect
*!*for relative pathing of the files. Password
*!* protection can be included if desired.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?UnzipQuick("C:\MyFile.zip", "C:\")
?UnzipQuick("C:\MyFolder.zip", "C:\", .T.)
?UnzipQuick("C:\MyFolder.zip", "C:\", .F., "MyPassword")
SET LIBRARY TO

****************************
*!* Example 4
****************************
*!* Create a zip file, add some files to it
*!*andthen close it when done. Respect
*!*for relative pathing and Password
*!* protection can be included if desired.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipOpen("MyZipFile.zip", "C:\", .F.)
?ZipFile("C:\SomeFile.txt", .F.)
?ZipFile("C:\AnotherFile.txt", .F., "MyPassword")
?ZipClose()
SET LIBRARY TO

****************************
*!* Example 5
****************************
*!* Create a zip file, add some folders to it
*!*andthen close it when done. Respect
*!*for relative pathing and Password
*!* protection can be included if desired.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipOpen("C:\MyZipFile.zip")
*!* ?ZipOpen("MyZipFile.zip", "C:\", .F.)
?ZipFolder("C:\MyFolder\", .F.) && trailing backslash isoptional
?ZipFolder("C:\AnotherFolder", .F., "MyPassword")
?ZipClose()
SET LIBRARY TO

****************************
*!* Example 6
****************************
*!* Compress and decompress a stringin memory.
*!* The amount of compression is pretty remarkable.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
CLEAR
lcOriginal = REPLICATE("Visual FoxPro Rocks!",100)
?"Original Length: "+ TRANSFORM(LEN(lcOriginal))
?
lcCompressed = ZipString(lcOriginal)
?"Compressed: "+ lcCompressed
?"Compressed Length: "+ TRANSFORM(LEN(lcCompressed))
?
?"Length Savings: "+ TRANSFORM(LEN(lcOriginal) -LEN(lcCompressed)) +" bytes"
?
lcUncompressed = UnzipString(lcCompressed)
*!* ?"Uncompressed: "+ lcUncompressed
?"Uncompressed Length: "+ TRANSFORM(LEN(lcUncompressed))
?"Equals Original: "+IIF(lcUncompressed == lcOriginal, "YES", "NO")
IF !(lcUncompressed == lcOriginal)
    EXIT
ENDIF
SET LIBRARY TO

****************************
*!* Example 7
****************************
*!* Demonstrates the callback functionality
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
ZipCallback("MyCallback()") && Start Event Handling - Any Function/Procedure/Method (in scope of course)
?ZipOpen("MyZip.zip", "C:\", .F.) && create zip file
?ZipFile("C:\MyFile.txt", .F.) && compress file into zip
?ZipClose() && done zipping
?UnzipQuick("C:\MyZip.zip", "C:\") && unzip contents of Test.zip to C:\
ZipCallback("") && StopEvent Handling
SET LIBRARY TO

*****************************
FUNCTION MyCallback()
    *****************************
    *!* Variables below are created on the fly
    *!* by the FLL when the ZipCallback feature is used

    *!* Depends on the value of nZipEvent
    ?cZipObjectName && Name of Zip, File, or Folder being processed

    *!* Events that fire MyCallback
    *!* 0 = Open Zip
    *!* 1 = Start Zip/Unzip of File
    *!* 2 = Read/Write File (nZipBytes will contain value of bytes read forevent)
    *!* 3 -End Zip/Unzip of File
    *!* 4 - Folder Opened
    *!* 5 - Close Zip
    ?nZipEvent

    *!*Number of Bytes read (Event 3)
    ?nZipBytes

ENDFUNC

****************************
*!* Example 8
****************************
*!* Demonstrates how to use the UnzipAFileInfo()
*!*and UnzipAFileInfoByIndex() functions.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
UnzipOpen("C:\MyZip.zip")
UnzipGotoTopFile()
UnzipAFileInfo("laTestArray1")
UnzipClose()
showfileinfo(@laTestArray1)
?
UnzipOpen("C:\MyZip.zip")
UnzipAFileInfoByIndex("laTestArray2",2)
UnzipClose()
showfileinfo(@laTestArray2)
SET LIBRARY TO

FUNCTION showfileinfo(aFileInfo)
    LOCAL lnCounter
    LOCAL ARRAY aCaptions(13)
    aCaptions(1) ="File Name"
    aCaptions(2) ="Comment"
    aCaptions(3) ="Version"
    aCaptions(4) ="Version Needed"
    aCaptions(5) ="Flags"
    aCaptions(6) ="Compression Method"
    aCaptions(7) ="DateTime"
    aCaptions(8) ="CRC"
    aCaptions(9) ="Compressed Size"
    aCaptions(10) ="Uncompressed Size"
    aCaptions(11) ="Internal Attribute"
    aCaptions(12) ="External Attribute"
    aCaptions(13) ="Folder"
    FOR lnCounter = 1 TO 13
        ?aCaptions(lnCounter)
        ?aFileInfo(lnCounter)
        ?TYPE("aFileInfo(lnCounter)")
    ENDFOR
ENDFUNC

****************************
*!* Example 9
****************************
*!* Manipulate the global zipfile comment of a zip file.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
ZipComment("C:\MyZip1.zip", "Hello") && addorreplace a global comment to a zip file
ZipComment("C:\MyZip2.zip", "") && delete a global comment from a zip file
SET LIBRARY TO

VFP Compression Documentation:

Function ZipString()

Signature: ZipString(cString[, nLevel])

Parameters:

cString - The character string you wish to compress

nLevel - The compression level to use which is 1 through 9 (1 is the fastest, while 9 is the best compression). The default value for this parameter is 6.

Return Value:

Character Data - the compressed version of cString.

Remarks:

This function is particularly useful in a client-server application given that strings of data (such as memo fields, character fields, and xml) can be compressed before sending them across the network and then extracted at the other end (using UnzipString).

---

Function ZipFileQuick()

Signature: ZipFileQuick(cFileName[, cPassword])

Parameters:

cFileName - The fully qualified file name (full path) of the file you wish to have compressed.

cPassword - The password you wish to protect the zipped file with.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

The zip file that this function creates will have the same file name as cFileName, with the extension as ".zip".

---

Function ZipFolderQuick()

Signature: ZipFolderQuick(cFolderName[, lIgnorePaths[, cPassword]])

Parameters:

cFolderName - The full path to the folder you wish to have zipped.

cPassword - The password you wish to protect the zipped files with.

lIgnorePath - If you wish to ignore the relative path of the file into the zip file that is being created you would pass .T. for this parameter. The default value for this parameter is .F. which means that the relative path will be respected.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

The zipfile that this function creates will have the same file name as cFolderName, with the extension as ".zip".

---

Function ZipOpen()

Signature: ZipOpen(cZipFileName[,cFolderName[,lAppend]])

Parameters:

cZipFileName - The file name or full path of the zip file you wish to create.

cFolderName - The full path of the folder in which you want cZipFileName created.

lAppend - If the zip file you are compressing to exists you can choose to append to it by passing .T. to this parameter. Defaults to .F..

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

ZipOpen() is used in conjunction with the matching ZipClose(). The usual series of function calls would consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.

---

Function ZipClose()

Signature: ZipClose()

Parameters: None

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

ZipClose() must be called after issuing a ZipOpen(). The usual series of function calls would consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.

---

Function ZipFile()

Signature: ZipFile(cFileName[,lIgnorePath[,cPassword]])

Parameters:

cFileName - The file name or full path of the file you wish to compress.

lIgnorePath - If you wish to ignore the relative path of the file into the zip file that is being created you would pass .T. for this parameter. The default value for this parameter is .F. which means that the relative path will be respected.

cPassword - The password you wish to protect the zipped file with.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

ZipFile() is used between calls to ZipOpen() and ZipClose(). The usual series of function calls would consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.

The cPassword is usually the same for all files within a zip, however it does not need to be the same. Different passwords can be specified for different files and you can even selectively password protect files within the zip.

---

Function ZipFileRelative()

Signature: ZipFileRelative(cFileName[,cRelativePath[, cPassword]])

Parameters:

cFileName - The file name or full path of the file you wish to compress.

cRelativePath - The relative path you wish to have saved in the zip for this file. This allows you to set up the structure (relative paths) in the zip different from the actual relative paths of the files you are compressing.

cPassword - The password you wish to protect the zipped file with.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

ZipFileRelative() is used between calls to ZipOpen() and ZipClose(). The usual series of function calls would consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.

The cPassword is usually the same for all files within a zip, however it does not need to be the same. Different passwords can be specified for different files and you can even selectively password protect files within the zip.

---

Function ZipFolder()

Signature: ZipFolder(cFolderName[,lIgnorePaths[, cPassword]])

Parameters:

cFolderName - The full path to the folder you wish to compress.

lIgnorePaths - If you wish to ignore the relative path of the folder into the zip file that is being created you would pass .T. for this parameter. The default value for this parameter is .F. which means that paths will be respected.

cPassword - The password you wish to protect the zipped file with.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

ZipFolder() is used between calls to ZipOpen() and ZipClose(). The usual series of function calls would consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.

---

Function UnzipString()

Signature: UnzipString(cString)

Parameters:

cString - The compressed string you wish to uncompress.

Return Value:

Character Data - the extracted version of cString.

Remarks:

The string to be extracted must have been compressed with the ZipString() function or other compression function that is compatible with the compress or compress2 functions in zlib.

---

Function UnzipQuick()

Signature: UnzipQuick(cZipFileName, [cOutputFolderName[, lIgnorePaths[, cPassword]]])

Parameters:

cZipFileName - The fully qualified file name (full path) of the zip file you wish to have extracted.

cOutputFolderName - The full path to the folder you wish to extract the contents of the zip to.

cPassword - The password to use when unzipping the file.

lIgnorePaths - If you wish to ignore the relative paths that are contained in the zip file you would pass .T. for this parameter. The default value for this parameter is .F. which means that the relative paths will be respected.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

The file and folders in the zip file will be extracted into the same folder as the cZipFileName resides in.

---

Function UnzipOpen()

Signature: UnzipOpen(cZipFileName)

Parameters:

cZipFileName - The file name or full path of the zip file you wish to uncompress.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipOpen() is used in conjunction with the matching UnzipClose(). The usual series of function calls would consist of opening the zip file using UnzipOpen, uncompressing files and/or folders using Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.

---

Function UnzipClose()

Signature: UnzipClose()

Parameters: None

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipClose() must be called after issuing an UnzipOpen(). The usual series of function calls would consist of opening the zip file using UnzipOpen, uncompressing files and/or folders using Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.

---

Function Unzip()

Signature: Unzip([lIgnorePaths[, cPassword]])

Parameters:

lIgnorePaths - If you wish to ignore the relative paths that are contained in the zip file you would pass .T. for this parameter. The default value for this parameter is .F. which means that the relative paths will be respected.

cPassword - The password to use when unzipping the file.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

Unzip() is used between calls to UnzipOpen() and UnzipClose() to uncompress the entire zip file. The files and folders contained in the zip file will be extracted to the same folder as the zip file resides in unless a call to UnzipSetFolder() has been previously issued. The usual series of function calls would consist of opening the zip file using UnzipOpen, uncompressing files and/or folders using Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.

---

Function UnzipTo()

Signature: UnzipTo(cOutputFolderName[, lIgnorePaths[, cPassword]])

Parameters:

cOutputFolderName - The folder into which the zip file contents should be extracted.

lIgnorePaths - If you wish to ignore the relative paths that are contained in the zip file you would pass .T. for this parameter. The default value for this parameter is .F. which means that the relative paths will be respected.

cPassword - The password to use when unzipping the file.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipTo() is used between calls to UnzipOpen() and UnzipClose(). The functionality of this is similar to calling UnzipSetFolder() and then Unzip(). The usual series of function calls would consist of opening the zip file using UnzipOpen, uncompressing files and/or folders using Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.

---

Function UnzipFile()

Signature: UnzipFile(cOutputFolderName[, lIgnorePaths[, cPassword]])

Parameters:

cOutputFolderName - The folder into which the current file (cotained in the zip) should be extracted.

lIgnorePaths - If you wish to ignore the relative path of the current file you would pass .T. for this parameter. The default value for this parameter is .F. which means that the relative path will be respected.

cPassword - The password to use when unzipping the file.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipFile() is used between calls to UnzipOpen() and UnzipClose() to extract the currently selected file contained in the zip file. UnzipFile() is used in conjunction with the UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions. You can think of the contents of a zip file as records in a table. In this sense UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions are used to move the record pointer and the UnzipFile function is used to extract the file that the record pointer is currently on.

The cPassword is usually the same for all files within a zip, however it does not need to be the same. Just keep in mind that passwords can be specified for different files within a zip and when you are unzipping such an archive you will need to change the cPassword accordingly.

---

Function UnzipByIndex()

Signature: UnzipByIndex(nIndex[, cOutputFolderName[,lIgnorePaths, cPassword]]])

Parameters:

nIndex - The index number of the file to be extracted.

cOutputFolderName - The folder into which the zip file contents should be extracted.

lIgnorePaths - If you wish to ignore the relative path for this file that is contained in the zip file you would pass .T. for this parameter. The default value for this parameter is .F. which means that the relative path will be respected.

cPassword - The password to use when unzipping the file.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipByIndex() is used between calls to UnzipOpen() and UnzipClose() to extract a file by the position (index) it holds in the zip file. UnzipByIndex() is used in conjunction with the UnzipFileCount function. You can think of the contents of a zip file as records in a table. In this sense UnzipFileCount would give you the record count for the table and the UnzipByIndex function be used to extract a particular file by record number.

The cPassword is usually the same for all files within a zip, however it does not need to be the same. Just keep in mind that passwords can be specified for different files within a zip and when you are unzipping such an archive you will need to change the cPassword accordingly.

---

Function UnzipFileCount()

Signature: UnzipFileCount()

Parameters: None

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipFileCount() is used between calls to UnzipOpen() and UnzipClose() to retrieve the number of files that are contained in the zip file. It does not actually extract anything. UnzipFileCount() is used in conjunction with the UnzipByIndex function. You can think of the contents of a zip file as records in a table. In this sense UnzipFileCount would give you the record count for the table and the UnzipByIndex function be used to extract a particular file by record number.

---

Function UnzipSetFolder()

Signature: UnzipSetFolder(cOutputFolderName)

Parameters:

cOutputFolderName - The folder into which the zip file contents should be extracted.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipSetFolder() is used between calls to UnzipOpen() and UnzipClose() to set the output folder for extracted zip contents. It does not actually extract anything. The usual series of function calls would consist of opening the zip file using UnzipOpen, calling UnzipSetFolder to set the output folder, uncompressing files and/or folders using Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.

---

Function UnzipGotoTopFile()

Signature: UnzipGotoTopFile([cExtension])

Parameters:

cExtension - The file extension to use as a filter for file type. All other file types will be ignored and only the first file of the type specified will be selected in the zip file.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipGotoTopFile() is used between calls to UnzipOpen() and UnzipClose() to select a particular file in the contents of the open zip file. UnzipGotoTopFile() is used in conjunction with the UnzipFile function to extract a particular file from the zip. By using the cExtension optional parameter you can select the first record of a particular file type. You can think of the contents of a zip file as records in a table. In this sense UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions are used to move the record pointer and the UnzipFile function is used to extract the file that the record pointer is currently on.

---

Function UnzipGotoNextFile()

Signature: UnzipGotoNextFile([cExtension])

Parameters:

cExtension - The file extension to use as a filter for file type. All other file types will be ignored and only the next file of the type specified will be selected in the zip file.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipGotoNextFile() is used between calls to UnzipOpen() and UnzipClose() to select a particular file in the contents of the open zip file. UnzipGotoNextFile() is used in conjunction with the UnzipFile function to extract a particular file from the zip. By using the cExtension optional parameter you can select the next record of a particular file type. You can think of the contents of a zip file as records in a table. In this sense UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions are used to move the record pointer and the UnzipFile function is used to extract the file that the record pointer is currently on.

---

Function UnzipGotoFileByName()

Signature: UnzipGotoFileByName(cFileName[, lIgnoreFilePath])

Parameters:

cFileName - The file name of the file you wish to select in the zip file contents. You can specify a relative path as well to narrow down the search.

lIgnoreFilePath - If you wish to just find a file of a particular name in the zip file you can pass .T. for this parameter and the relative path of the file will be ignored. The first matching file of the name specified in cFileName will be selected in the zip contents.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipGotoFileByName() is used between calls to UnzipOpen() and UnzipClose() to select a particular file in the contents of the open zip file by file name and/or relative path. UnzipGotoFileByName() is used in conjunction with the UnzipFile function to extract a particular file from the open zip file. You can think of the contents of a zip file as records in a table. In this sense UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions are used to move the record pointer and the UnzipFile function is used to extract the file that the record pointer is currently on.

---

Function UnzipGotoFileByIndex()

Signature: UnzipGotoFileByIndex(nIndex)

Parameters:

nIndex - The index number of the file to be selected.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipGotoFileByIndex() is used between calls to UnzipOpen() and UnzipClose() to select a particular file by the position it physically holds in the contents of the open zip file. UnzipGotoFileByIndex() is used in conjunction with the UnzipFile function to extract a particular file from the zip file contents. You can think of the contents of a zip file as records in a table. In this sense UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions are used to move the record pointer and the UnzipFile function is used to extract the file that the record pointer is currently on.

---

Function UnzipAFileInfoByIndex()

Signature: UnzipAFileInfoByIndex(cArrayName, nIndex)

Parameters:

cArrayName - Name of the VFP array to be created with file information in it.

nIndex - The index number of the file you want to return information about.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Creates an array with 13 rows (elements) in it. The rows contain various pieces of information regarding the file that is held in the zip file at nIndex. The following table describes the contents and data type of each row in the array:

Row	Array Content	Data Type
1	File Name	Character
2	Comment	Character
3	Version	Numeric
4	Version Needed	Numeric
5	Flags	Numeric
6	Compression Method	Numeric
7	DOS Date	Datetime
8	CRC	Numeric
9	Compressed Size	Numeric
10	Uncompressed Size	Numeric
11	Internal Attribute	Numeric
12	External Attribute	Numeric
13	Folder	Logical

Remarks:

The array that is created will have whatever name was specified by cArrayName. Should the array already exist it will release it and recreate it. UnzipAFileInfoByIndex() is used between calls to UnzipOpen() and UnzipClose() to show information about a particular file. The file is referred to by the position it physically holds in the contents of the open zip file. You can think of the contents of a zip file as records in a table. In this sense the UnzipAFileInfoByIndex function is used to refer to and retrieve information about a particular record number in the zip file.

---

Function UnzipAFileInfo()

Signature: UnzipAFileInfo(cArrayName)

Parameters:

cArrayName - Name of the VFP array to be created with file information in it.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Creates an array with 13 rows (elements) in it. The rows contain various pieces of information regarding the currently selected file in the zip. The following table describes the contents and data type of each row in the array:

Row	Array Content	Data Type
1	File Name	Character
2	Comment	Character
3	Version	Numeric
4	Version Needed	Numeric
5	Flags	Numeric
6	Compression Method	Numeric
7	DOS Date	Datetime
8	CRC	Numeric
9	Compressed Size	Numeric
10	Uncompressed Size	Numeric
11	Internal Attribute	Numeric
12	External Attribute	Numeric
13	Folder	Logical

Remarks:

The array that is created will have whatever name was specified by cArrayName. Should the array already exist it will release it and recreate it. UnzipAFileInfo() is used between calls to UnzipOpen() and UnzipClose() to show information about a particular file. Use the UnzipAFileInfo function in conjunction with UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions to return information regarding a particular file contained in the open zip file. You can think of the contents of a zip file as records in a table. In this sense the UnzipAFileInfo function is used to refer to and retrieve information about the record that the record pointer is currently on within the zip file.

---

Function ZipCallback()

Signature: ZipCallback(cFunction)

Parameters:

cFunction - A string denoting a function, procedure, or method that you want fired whenever a zip event occurs, such as "MyCallback()".

Return Value: None

Events:

When one of the following zip events occurs the function/procedure/method specified by the cFunction parameter will be called. cZipObjectName, nZipEvent, and nZipBytes are private variables created on-the-fly by the FLL. They will contain the values specified in the table below.

Event Description	cZipObjectName (character)	nZipEvent (numeric)	nZipBytes (numeric)
Zip Opened	Name and path of zip file	0	N/A
Zip/Unzip File Start	Name and path of file being zipped/unzipped	1	N/A
Zip Read or Unzip Write	Name and path of file being zipped/unzipped	2	Number of bytes currently being read or written
Zip/Unzip File End	Name and path of file being zipped/unzipped	3	N/A
Zip/Unzip Folder Opened	Name and path of folder being zipped/unzipped	4	N/A
Zip Closed	Name and path of zip file	5	N/A

Remarks:

Event handling is started as soon as you call ZipCallback and pass it the name of a function, procedure, or object method. ZipCallback provides a way for you to hook into the internal events happening inside of the VFPCompression FLL. nZipBytes reports the number of bytes currently being read during zip (2048 bytes at a time) or written during unzip (4096 bytes at a time) of an individual file. In order to turn off event handling simply call the ZipCallback with an empty length string, such as ZipCallback("").

---

Function ZipComment()

Signature: ZipComment(cZipFileName, cComment)

Parameters:

cZipFileName - The file name or full path to the zip file you wish to add, replace, or delete the comment on.

cComment - A string containing the comment (maximum of 255 characters)

Return Value:

None - returns .T. if successful or .F. if the operation has failed.

Remarks:

If a comment does not exist in the zip file, the string designated in cComment will be added. However, if a comment already exists in the zip file, the existing comment will be replaced with the cComment specified. This replacement functionality allows you to also delete an existing comment in a zip file by passing an empty string to the cComment parameter.

 

Virtual Earth
Billed as "...the integrated mapping, imaging, search, and data visualization platform", Microsoft's Virtual Earth (VE) is an awesome mapping service that can be consumed and manipulated using the VE Map contol and JavaScript. In order to get a feel for what VE is capabable of, head on over to the VE Interactive SDK and try some of the examples provided. There is plenty of documentation, blog entries and articles available online that provide general VE overviews and detail the specific features the service provides, so I won't spend a lot of time explaining what VE is and what it does. I want to explain enough so that you can understand the goals of the VFP Virtual Earth wrapper class library that I'm presenting in this blog entry. I figure you can do a few online searches if you're interested in a deeper or broader understanding of VE and its specific features.

Virtual Earth Map Control
In order to understand VE from a developer standpoint you'll need to be familiar with the Virtual Earth Map Control. The VE Map Control and the JavaScript classes/enumerations that make it up are provided via a web handler (.ashx file). I find it is more understandable to think of it as a library rather than a control. The VEMap class (which is part of the VE Map Control) is what I would consider the actual control that is seen within a web page. Perhaps I'm splitting hairs here, but I found it to be a helpful distinction in my mind when first starting to work with VE.

Creating Your First VE Web Page
It's pretty simple to add the VE Map Control to a web page and use it to instantiate an instance of the VEMap class. Here's the basic HTML needed in order to create such a page...

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <title>Virtual Earth</title>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <script type="text/javascript" src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.2"></script>
        <script type="text/javascript">
            var map =null;
            function startVE()
            {
                map =new VEMap('myMap');
                map.LoadMap();
            }
            function cleanUp()
            {
                if (map !=null) map.Dispose();
            }
        </script>
    </head>
    <body onload="startVE();" onunload="cleanUp();" style="margin: 0px">
        <div style="overflow: hidden; width: 100%; height: 100%;" id="myMap" />
    </body>
</html>

You should note that the first script tag specifies the web handler mapcontrol.ashx as the source. Also, note how an instance of VEMap is created using the body's onload and is eventually disposed of in the cleanUp() function via the body's onunload. In any event, it's pretty easy stuff given the results (go ahead and cut and paste that bit of code into an HTML file and view it in Internet Explorer).

What About Desktop Applications?
Obviously, given the architecture and heavy reliance on JavaScript, this stuff was made for web applications. But what about desktop applications that require geocoding of addresses, distance measurements, scheduling based on zones, or routing with turn-by-turn directions? I mean, Virtual Earth would work great if there was just some way to run an HTML page on a VFP form... Oh wait, Microsoft has provided us the WebBrowser control! Just drop that ActiveX control on a form and make a quick call to something like, Thisform.Olecontrol1.Navigate("file:///C:\VETest.html"). Looks like we're in business.

The only thing that's left to do after that is write all of the JavaScript code that interacts with the VE Map Control. Awesome! Except that... erm... you may not know very much JavaScript (even though you're a kick-butt VFP developer), and you may need VFP code to freely interact with the JavaScript objects (or vice versa), and how the heck do you get JavaScript to read your database where all of your addresses are stored? And... And...

Virtual Earth Wrapper for VFP
OK, so the previous section outlines the thought process that eventually lead to the class library that I built to tackle these problems. While working on a VFP project for a customer that involved VE, I looked at that list of classes and enumerations for the Virtual Earth Map Control version 6.2 and basically thought, "Wouldn't it be super cool if those were all VFP classes??!!".

I needed a class library (.vcx) wrapper for VE. This would contain all of the same classes (VFP equivalents) and a few super slick ways to commuicate and convert between VFP and JavaScript. With those in hand it would simply be a matter of hammering out the 5-10 thousand lines of code and comments to make it happen. I won't go into the particulars of everything I ended up doing in order to make this work (you can look in the class library's code yourself if you're interested), but I did end up using the JSON class I created to handle most of the conversions and transport (data interchange) between the two languages.

As you'll see in the download, the class library wrapper (virtualearth.vcx) is pretty much a carbon copy of the VE classes. So, most of the documentation and code that's online for VE is of benefit when using it. In addition to the virtualearth.vcx, I've also provided a sample project and form (see screenshot below), so you can try this stuff out right away. The sample project is also intended to provide a little more information regarding how to do some of the things that a developer might want to do with VE in a desktop application. I usually find that learning by example is one of the fastest ways to get up to speed on a technology I'm not very familiar with.

Special Thank You
Before I wrap this blog entry up, I want to express my appreciation for Marc Lyon's efforts. He provided me early feedback and testing for this class library. His enthusiasm for this project was also one of the driving forces behind my completing it as fast as I did.

I also want to thank my client (you know who you are) who has been kind enough to allow me to share this work with the VFP Community. You're about as generous and kind as they come.

What's Next
Just have fun with Virtual Earth in VFP and see if virtualearth.vcx is useful to you and your applications. In a perfect world, you'd report back to me with any bugs you find, create some examples of your own and blog about them, or seek to improve the library in some way. If you do improve virtualearth.vcx, I'd appreciate it if you would contact me and share the improvements you've implemented. Thank you in advanced to those of you that decide to follow any of the above suggestions.

Until next time... Visual FoxPro Rocks!

Download VirtualEarth.vcx and Sample (approx. 222 KB)

Figure 1: A sample form provided in the download. It gives developers a starting point when beginning to work with the virtualearth.vcx.

 

The Visual FoxPro Grid Control
I've often been heard to say that Visual FoxPro's grid is one of the greatest controls ever devised. I still feel that way, but wouldn't it be nice if some of the functionality that our customers want implemented in the grid came stock? You know, features like: sorting, filtering, incremental search, saving user preferences, and exporting to Excel. It'd be even cooler if this type of functionality could be implemented on any Visual FoxPro grid (regardless of the recordsource) by simply dropping a class on a form, setting a single property and writing a single line of code. Well, that's what I have set out to create with the class I present in this blog entry.

First Shown at Southwest Fox 2008
At Southwest Fox 2008, I presented a session entitled "Creating a Professional VFP Application from Start to Finish" in which I showed an earlier version of GridExtras. I've improved on it since then, so if you attended Southwest Fox 2008 you may want to get the control and sample from here rather than the session download. For those of you that didn't attend Southwest Fox 2008 (you should have - it was a blast!), you can see the basic functionality provided by GridExtras in the screenshots provided at the bottom of this blog entry.

How to Use the Class
I've provided a sample.exe application in the download so you can try it out and see how it's implemented. However, the basic steps are:

• Drop an instance of the gridextras onto your form or container (one gridextras for each grid you want to enhance).
• Set the GridExtras' GridExpression property to a string that will evaluate at runtime to the grid you are enhancing - "Thisform.Grid1" is the default value for this property.
• Call the GridExtras' Setup() method whenever your grid is ready to go. I have no way of knowing if you are setting the recordsource at runtime, or whether you are adding columns in code, so this method is provided as a way for you to control when GridExtras will begin interacting with the grid.

That's all there is to getting GridExtras up and running for a grid in your application. As I say, I've included a sample in the download, so if you have any questions about how this is done just review the sample or you can post a comment here on my blog and I'll do my best to answer it.

Other Properties of Note
There are a few other GridExtras properties you may want to take note of and use, such as:

• CompanyName and ProductName - these properties are used to determine where to save the user's grid preferences file which is profile isolated (C:\Users\Craig\AppData\Roaming\MyCompany\MyProduct\gridprefs.tmp on Vista or  C:\Documents and Settings\Craig\Application Data\MyCompany\MyProduct\gridprefs.tmp on Windows XP)
• AllowGridExport, AllowGridFilter, AllowGridPreferences, AllowGridSort - these properties allow you to turn certain features of the class off or on depending on your needs.
• TemplateTable - this property determines where GridExtras looks for the gridextras.dbf which is used to save the grid templates the user creates (user can save their filters and sorts to be able to easily recreate them at a later time). This property may need to be set if you plan to keep the gridextras table out on a network path such as with the shared database folder for your application.

What's Next
Just have fun with GridExtras and see if it's useful to you and your applications. In a perfect world, you'd find some way to improve it (add additional export formats, provide a column lock feature, etc.). If you do improve GridExtras, I'd appreciate it if you would contact me and share the improvements you've implemented. Thank you in advanced to those of you that decide to do so.

Until next time... Visual FoxPro Rocks!

Download GridExtras and Sample (approx. 170 KB)

Figure 1: GridExtras provides sorting, incremental search, and filtering capabilities to any Visual FoxPro grid.

 

Figure 2: GridExtras has additional features such as the ability to go semi-transparent and the ability to save the user's preferences (column order and width).

 

Figure 3: In addition to the features provided by GridExtras through a grid's column headers, there is also an icon added to the bottom right of the grid that allows the user to access the "Grid Templates and Export" screen seen in Figure 4.

 

Figure 4: The grid templates help the user save grid views so they can recreate them quickly in the future. The export feature of GridExtras can create XLS, XLSX, XLB, and XLM Excel formats. The grid's header captions are used to name the Excel columns when data is exported.

 

What is JSON?
If you are unfamiliar with JSON, you can dig into the particulars about it here and here. The short explanation is that JSON provides a format for serializing and deserializing variables, arrays, and class instances. For those of you that may not know what serializing and deserializing are, think of serializing as turning a cursor into XML and then think of deserializing as turning XML back into a cursor. Basically the process of turning an instance of MySomething into a string and then turning that string back into an instance of the same MySomething.

Now, besides the obvious advantages of being able to serialize and deserialize VFP values and objects (persisting them on disk or passing them across the wire, just to name a couple), it becomes really useful when you find that you have to interact with Javascript from your Visual FoxPro application. I ran into this while working with Virtual Earth in a webbrowser control (more on that in an upcoming blog entry). I wanted to use JSON as part of my solution because it would allow me to easily move values, instances, and data back and forth between Visual FoxPro and the Javascript that was running inside a page being displayed in the webbrowser control. I could have done without it, but it's a lot more slick when using JSON.

JSON for VFP
If you visited the first "here" in my first paragraph in the section above you may have noted that they have a rather impressive list of languages that provide support, in some manner, for JSON at the bottom of the page. You may have also noted that Visual FoxPro was absent from that list. Now, that doesn't mean that no one has ever done this sort of thing before. In fact, Rick Strahl provides VFP/JSON support through his wwJSONSerializer class and FoxWeb provides similar functionality through it's fwJSON object. And, here in this blog entry, I'm going to provide you with another class that provides JSON support. So, hopefully someday we can get this class and the others listed on the json.org site (anyone know who to call or write to?).

Why Another JSON Class?
So, if Rick and FoxWeb already provide classes, it begs the question, "Why did I decide to write one too?". Well...

• When I started working on this I didn't know that Rick even provided such a class in web connect. As for FoxWeb, I've never used it, so I don't know what their object does. Heck, for all I know there are other classes out there besides these two. If you know of any others, please feel free to comment on this blog entry with a link.
• My JSON class provides additional support for some things when compared to the functionality of wwJSONSerializer:
  • Multi-dimensional array support
  • Replacer support on stringify
  • Reviver support on parse
  • Beautification/indetation support
  • Performance enhancements via FLL
  • A few other things, but those are the main ones
• The implementation of my JSON class is patterned after json2.js (by Douglas Crockford), which means:
  • The main methods are Stringify() and Parse()
  • It supports datetimes in ISO8601 format (other formats available)
  • Provides the same default escaping of characters (other modes available).
• Because I wanted to try my hand at this?

There's no better way that I know of to learn something than to write a wrapper or even a class that directly interacts with another library or API. So, I wrote a top-notch JSON class library. I am using it in a production project at this end (my customer was kind enough to give me permission to share it) and I am blogging about it in the hopes some of you may find it useful.

How to Use the JSON Class
In the class, I have provided lots of comments in the code to help document this thing. Also, provided in the download is a jsontests.prg that provides some sample use code you can look at to get started. For the sake of blog brevity... in order to serialize a Visual FoxPro object to JSON you'd do the following:

m.loJSON = CREATEOBJECT("JSON")
SET CLASSLIB TO (LOCFILE("JSON.VCX", "VCX", "Locate JSON Class Library")) additive
m.loObjectIn = CREATEOBJECT("Custom"
m.lcObjectJSON = m.loJSON.Stringify(m.loObjectIn, null, CHR(9))
?m.lcObjectJSON

...and then to deserialize that JSON string you'd do this:

m.loObjectOut = m.loJSON.Parse(m.lcObjectJSON)
?m.loObjectOut.Class

As I say, the code is heavily commented (so check it out) and I'll be doing a blog entry in the near future regarding a Virtual Earth class library I've written for VFP that shows some real world uses for JSON within VFP.

Special Thank You
I sincerely appreciate the efforts of those of you that have already been providing valuable feedback, such as Steven Black and Marc Lyon. Also, Rick Strahl, who provided help and sage advice to me via Twitter as I worked through the particulars of this class. It's always nice to have someone advising you who has already "been there, done that".

What's Next
I'm hopeful that those of you that download this class will take the time to provide me feedback and any suggestions you may have for further improving it.

Until next time... Visual FoxPro Rocks!

Download the JSON class library (approx. 52 KB)

The download contains the JSON class in both VCX and PRG format. Use whichever one you are more comfortable with (they are the same).

Same Old, Same Old
Far too often developers will either not implement error handling in their applications (allowing VFP's default error handler to prevail) or they will display a simple messagebox containing a few pieces of error information such as the values returned from Visual FoxPro's Error(), Message() and Lineno() functions. In either case, this type of error handling is usually woefully inadequate. Not only are these approaches of little use to the user, it is probably disconcerting (if not a little frightening) to them. The possible end result of these approaches: bugs go unreported, error information is not captured, and the user's overall confidence in the application is shaken.

A Possible Approach to Error Handling
At Southwest Fox 2008, I presented a session entitled "Creating a Professional VFP Application from Start to Finish" in which I showed the error handler that I use in a number of applications I have developed. That error handler is presented here as one possible approach you can take when implementing error handling in your Visual FoxPro applications. There is sure to be room for improvement, but the state informaiton it gathers is pretty extensive and I've found that most users find the error screen (see screen shots below) to be non-threatening/reassuring when exceptions arise.

How to Use the Error Handler
In order to implement the error handler in your own applications, you'll need the functions and the ON ERROR command that are in the main.prg of the sample application (provided in the download below). You'll also want to include the issues.scx form in your project and set the MyCompany, MyProduct, MyTechEmailAddress, and MyTechPhoneNumber properties of the issues form with your information. That's about all there is to it. I have included an FLL with the sample, but this is merely used to facilitate the transmittal of the error information via email. If you implement another method of transmission (such as a post to a Web Connection web application), then you needn't include the FLL.

To try the error handler out you can download the sample below and, after setting the issues form properties as noted above, simply build the project provided and run the executeable you've built. A form is provided that allows you to submit an issue manually as a customer would and also to throw an error to see how the error handler works in an exception situation.

Due Credit
Most of the code that you'll find in the main.prg for collecting error information came from the book "Special Edition Using Visual FoxPro 6". And, the code that is used to terminate the process after the exception has occured is from work done by Doug Hennig. So, special thanks to those two sources.

What's Next
Just have fun with the error handler and see if it's useful to you and your applications. In a perfect world, you'd find some way to improve it (add screenshot ability, refactor the code, etc.). If you do improve the error handler, I'd appreciate it if you would contact me and share the improvements you've implemented. Thank you in advanced to those of you that decide to do so.

Until next time... Visual FoxPro Rocks!

Download Error Handling Sample (approx. 41 KB)

Figure 1: The screen the user sees when an exception occurs.

 

Figure 2: Respecting the user's privacy, they are allowed to view what the error report contains before it is sent.

 

Figure 3: The screen also allows the user to provide additional information before submitting the error report.

Getting the Longitude and Latitude for an Address
Just finished answering a question out on UniversalThread regarding how to get the Longitude and Latitude from an address. Following is the Visual FoxPro code I came up with for doing it. I'm posting it here simply so I can find it later (maybe a few readers will find it interesting or useful too). In any event, here's the code...

LOCAL lcAddress, lcLongitude, lcLatitude
m.lcAddress ="7651 209th Street North,Forest Lake,MN"
GetLongLatFromAddress(m.lcAddress, @m.lcLongitude, @m.lcLatitude)
MESSAGEBOX("Longitude: "+ m.lcLongitude + CHR(13) +"Latitude: "+ m.lcLatitude, 64, "Geo Information")

************************
FUNCTION GetLongLatFromAddress(tcAddress, tcLongitude, tcLatitude)
************************
LOCAL lcAddress, lcURL, loXMLHTTP as MSXML2.XMLHTTP, lcReturn
m.loXMLHTTP = CreateObject("MSXML2.XMLHTTP")
m.lcAddress = UrlEncode(m.tcAddress, .F.)
m.lcAddress = HandleUnsafeChars(m.lcAddress)
m.lcURL ="http://rpc.geocoder.us/service/rest?address="+ m.lcAddress
m.loXMLHTTP.open("GET", m.lcURL, .F.) && third parameter needed to avoid need to check readyState
m.loXMLHTTP.send()
m.lcReturn = m.loXMLHTTP.responseText
m.tcLongitude = STREXTRACT(m.lcReturn,"<geo:long>", "</geo:long>",1,1)
m.tcLatitude = STREXTRACT(m.lcReturn,"<geo:lat>", "</geo:lat>",1,1)
RETURN m.lcReturn
ENDFUNC

************************
FUNCTION UrlEncode(tcString, tlNoPlus)
    ************************
    LOCAL lcReturn, lcChar, lnCounter
    m.lcReturn=""
    FOR m.lnCounter = 1 TO LEN(m.tcString)
        m.lcChar = SUBSTR(m.tcString, m.lnCounter, 1)
        IF ATC(m.lcChar,"ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789") > 0
            m.lcReturn = m.lcReturn + m.lcChar
            LOOP
        ENDIF
        IF ASC(m.lcChar) = 32 AND !m.tlNoPlus
            m.lcReturn = m.lcReturn +"+"
            LOOP
        ENDIF
        m.lcReturn = m.lcReturn +"%"+ RIGHT(TRANSFORM(ASC(m.lcChar),"@0"),2)
    ENDFOR
    RETURN m.lcReturn
ENDFUNC

************************
FUNCTION HandleUnsafeChars(tcString)
    ************************
    LOCAL lcReturn, lcBuffer, lnBufferSize
    #DEFINE ICU_BROWSER_MODE 0x2000000
    DECLARE INTEGER InternetCanonicalizeUrl IN wininet;
        STRING sURL, STRING @sBUFFER, INTEGER @nLength, INTEGER nFlags
    m.lnBufferSize = 250
    m.lcBuffer = REPLICATE(CHR(0), m.lnBufferSize)
    IF InternetCanonicalizeUrl (m.tcString, @m.lcBuffer, @m.lnBufferSize, ICU_BROWSER_MODE) != 0
        m.lcReturn = LEFT(m.lcBuffer, m.lnBufferSize)
    ELSE
        m.lcReturn =""
    ENDIF
    RETURN m.lcReturn
ENDFUNC

The Problems
Visual FoxPro 9.0's APPEND FROM and COPY TO commands are incompatible with the new Excel 2007 file formats (XLS, XLSX, XLSB, and XLSM). You may have noticed that I included XLS which you would think is supported, but just try saving your Excel 97-2003 XLS workbook in compatibility mode in Excel 2007 and then using the APPEND FROM command on it. VFP will complain about the validity of the file - in short, it doesn't work. And, the COPY TO command is simply stuck in the dark ages with XLS and XL5 available. OK, so all of that is the first problem.

The second problem with the APPEND FROM and COPY TO commands is that they don't allow you to specify the columns/fields, a where/for clause, or specify a target range/printable region. We're pretty much stuck with specifying a workbook. APPEND FROM does allow for an optional SHEET parameter, but that's merely adequate not super cool.

The third problem is that the usual workaround suggested for the problems above is to use automation, and automation is super slow due to the COM overhead incurred. It also introduces an additional dependency on having Excel 2007 installed on the machine on which the code is executing. The 'slow' is never acceptable (VFP applications can be a number of things, but slow is not one of them) and the additional dependency, while acceptable in certain instances, is a show-stopper if you are running these types of operations on say a web server that doesn't have Excel 2007 installed on it.

The Solution
I was working on a solution for a client of mine that required that I consume and create XLS, XLSX, XLSB, and XLSM files without the user needing to have Excel 2007 installed. After throwing a proof-of-concept together, I enlisted the help of my friend Bo Durban. The code provided in a zip at the end of this post is what we came up with after a couple intense coding sessions. Special thanks to my client for allowing me to share it.

The Code
The code includes 2 main functions: AppendFromExcel() and CopyToExcel(). There are also 4 helper functions: AWorkSheets(), AWorkSheetColumns(), CreateExcelTemplate(), and EmptyFieldToNull() that you might find useful or interesting. The code:

• Does not require Office 2007
• Can append from xls, xlsx, xlsm, and xlsb file formats
• Can create and copy to xls, xlsx, xlsm, and xlsb file formats
• Supports all Excel tables (worksheets, ranges, and printable regions)
• Allows target worksheet columns and table fields to be specified
• Allows header row in worksheet to have spaces in the names of the columns by enclosing them in standard brackets, for instance [My Column #1]
• Provides support for SQL Where clause or VFP For clause expressions
• Is super fast
• Probably does a few other things I'm not thinking of right now :)

In any event, download/extract the prg, uncomment/modify the Sample Usage code at the top of the prg to suit, and have fun! I orginally included the code at the bottom of this post, but the code made this blog entry crazy wide because of some very long lines of binary in it. So, here's the download link for the prg file that contains the stuff you need...

VFPExcel2007Functions.zip (19.14 KB)

Note: Additional refactoring is still needed and this definitely cries out for a class to be built, but the code works fully as-is. If you have any problems running the code (especially if a Select Data Source dialog pops up) you might want to check the OLEDB provider comments and alternatives provided in the code.

I'm sure you've seen it on the news by now or somewhere else on the internet, but if not then here is a link...

http://www.todayszaman.com/tz-web/detaylar.do?load=detay&link=143041

I was on my way back from my daughter's baby shower while Claire and my two youngest children sought saftety in the basement of our home in Forest Lake, MN. It was a scarey deal. We were fortunate in that everyone is safe and the power was only off for about 12 hours which we sat out at a motel across from the Mall of America. Others in Hugo (just south of us) were not as fortunate. Our prayers are with everyone effected by this severe weather event.

I've been through Hugo, MN twice since the tornado went through. There are lots of downed trees and houses that are completely demolished as if a bomb struck them. The local authorities have most of Hugo roped off with Police tape and are detouring traffic around it. All-in-all it makes a person so grateful for what they've got. How blessed most of us are.

Here are some pictures of the devastation...

http://www.startribune.com/galleries/19251959.html?location_refer=East%20Metro