Zipping and Unzipping for Clients, Part 2 Richard David Hodder

Transcription

1 Seite 1 von 8 Issue Date: FoxTalk June 2000 Zipping and Unzipping for Clients, Part 2 Richard David Hodder rickhodder@msn.com The first part of this article introduced us to the DynaZIP-AX controls from InnerMedia, Inc.: ActiveX controls that give developers programmatic control over creating and reading ZIP files. This month, Richard David Hodder takes a closer look at these controls, with particular emphasis on the features that provide for customization and internationalization of text and dialogs. In the first part of this article, back in the April edition of FoxTalk, I introduced you to the DynaZIP controls. This month, I ll delve deeper into the controls. One of the difficulties experienced when developing with ActiveX controls is that the controls are black boxes: Program source for the controls isn t included or accessible. Why is this important? Because there are often aspects of the control s visual interface that developers would like to change. Some controls (like the DynaZIP controls) can display status thermometers during processes. These thermometers might not look like the thermometers used in your application framework, and could interfere with the "look and feel" of your applications. Some message box dialogs that are presented to application users contain awkward or confusing messages. For example, when the DynaZIP Zip control can t find any files that match the ItemList while zipping, it pops up a dialog that says "Nothing to do!" Other message box dialogs are targeted toward developers more than application users (one of my favorites in FoxPro is the infamous "Fatal Error 6 while reporting Error 6"). Problems like these usually can t be addressed, because these elements have been hard-coded (compiled) into the ActiveX control. The DynaZIP controls have what are called "callback events" to provide hooks for addressing the problems mentioned above, as well as other amazing things. I ll begin this article by defining what callback events are, and then I ll describe the callback events that the DynaZIP controls have. Callback events C++ has a variable type called a function pointer, which, as the name suggests, is a pointer to the address of a function in memory. C++ can use this function pointer to call the function, rather than calling the function by its defined name. A function pointer (let s say a pointer to a function called CallDate) is often passed as a parameter to another function (let s say a function called AfterHotDateCheckList). At some point during the execution of AfterHotDateCheckList, the function pointer to CallDate is used to execute the CallDate function. Function pointers used in this manner are referred to as "Callback" functions. The behavior of the AfterHotDateCheckList function can be modified by passing different function pointers as a parameter. VFP doesn t have a function pointer type, but the DynaZIP ActiveX controls surface callback event methods that fire during the zipping and unzipping processes. The VFP developer can put code into these event methods to act on the information passed to them. I ll describe each of the callback events (MajorStatus, MinorStatus, Message, Rename and MemToMem) in the following sections. Both of the DynaZIP controls have the same callback events, which have the same basic functions, so I ll present them once for both. You won t find any events named MajorStatus, MinorStatus, Rename, Message, or MemToMem on the interface of the DynaZIP controls. On the ZIP control, you ll see ZIPMajorStatus, ZIPMinorStatus, ZIPRenameCallback, ZIPMessageCallback, and ZIPMemToMemCallback. On the UNZIP control, you ll see UNZIPMajorStatus, UNZIPMinorStatus, and so on. Each of the callback events also has a corresponding flag property that determines whether the callback event should fire. These flag properties are named MajorStatusFlag, MessageCallbackFlag, MinorStatusFlag, and RenameCallbackFlag. There s no MemToMemCallbackFlag, since a specific action starts the MemToMem (ZIP_MEMTOMEM or UNZIP_MEMTOMEM). The flag properties all hold logical values: If the value is.t., the corresponding event fires, otherwise the event does not fire. Important things about using the callback events All parameter information passed to the callback events is passed by reference. This allows you to change the information that DynaZIP is using by simply changing the value of the parameters. The callback events will fire only if AutoYield is set to.f. The appropriate callback flag (such as MajorStatusFlag) must be set to.t. for each callback event that should be processed. I ll begin my discussion of the DynaZIP callback events with the MajorStatus and MinorStatus callback events. These two callback events provide the ability to replace the progress thermometer included with DynaZIP-AX, with your own custom progress thermometer. The events intercept the status information (such as the name of item being zipped, percent complete, and similar items) that would be sent to the DynaZIP thermometer. The developer can then present the same information in a custom progress thermometer. MajorStatus callback event Information passed to this event conveys the overall status (a macro view) of the zipping/unzipping process. The following parameters are passed to the MajorStatus callback event:

2 Seite 2 von 8 ItemName (Character): A string that describes the overall status of the zipping/unzipping progress currently in action (such as "Processing List. Please Wait ", "Item 1 of 32", and similar items). Percent (Numeric): This contains a number between 0 and 100 that corresponds to the overall percent completed. Cancel (Numeric): This provides a way to cancel the action currently in progress. Setting this value parameter to a non-zero value will cancel the current action. Your custom status thermometer might have a Cancel button on it. The Cancel button on your thermometer can set this parameter to a non-zero value to stop the zipping process. Since these parameters are all passed by reference, you might be tempted to internationalize/translate the ItemName parameter from within this event but don t. By the time the MajorStatus callback event fires, the text in ItemName has already passed through the Message callback event for customization/translation. The following must be true, or else the MajorStatus callback event won t fire: The MajorStatusFlag must be set to.t. Application.AutoYield must be set to.f. When zipping, the ZipSubOptions can t include ZSO_EXTERNALPROG (ZSO_EXTERNALPROG means that DynaZIP is using the thermometer display with which it ships, so there s no need to fire this event). When unzipping, the UnZipSubOptions can t include USO_EXTERNALPROG (USO_EXTERNALPROG means that DynaZIP is using the thermometer display with which it ships, so there s no need to fire this event). These last two items had me pulling my hair out for a while. I was trying to use the MajorStatus and MinorStatus callback events to present my own status thermometer while zipping files, but for some reason, neither of the callback methods was firing. It turned out that I had included ZSO_EXTERNALPROG as one of the ZIPSubOptions. MinorStatus callback event Information passed to this event conveys the status of the current item being zipped/unzipped (a micro view). The following parameters are passed to the MinorStatus callback event: ItemName (Character): A string that describes the status of the item that is currently being zipped/unzipped (the name of the file being zipped/unzipped). Percent (Numeric): This contains a number between 0 and 100 that corresponds to the percent completed of the item being zipped/unzipped. Cancel (Numeric): This provides for a way to cancel the action. Setting this value parameter to a non-zero value will cancel the current action. In contrast to the MajorStatus callback event, this parameter will cancel the action only if the MINORCANCEL suboption (ZIP_ MINORCANCEL or UNZIP_ MINORCANCEL) is set on the ZipSubOptions or the UnzipSubOptions properties. Similarly to the Major Status callback event, these parameters are all passed by reference, and you might be tempted to internationalize/translate the ItemName parameter from within this event but don t. By the time the MinorStatus callback event fires, the text in ItemName has already passed through the Message callback event for customization/translation. The following must be true, or else the MinorStatus callback event won t fire: The MinorStatusFlag must be set to.t. Application.AutoYield must be set to.f. When zipping, the ZipSubOptions can t include ZSO_EXTERNALPROG (ZSO_EXTERNALPROG means that DynaZIP is using the thermometer display with which it ships, so there s no need to fire this event). When unzipping, the UnZipSubOptions cannot include USO_EXTERNALPROG (USO_EXTERNALPROG means that DynaZIP is using the thermometer display with which it ships, so there s no need to fire this event). The following code demonstrates the use of both the MajorStatus and MinorStatus callback events to display a custom thermometer during the zipping progress: #INCLUDE DZ32.H *-- Create Thermometer form DO FORM Therm NAME gotherm LINKED *-- Create caretaker and get zip object LOCAL locaretaker, lozip locaretaker = CREATEOBJECT("ZipCaretaker") lozip = locaretaker.ozip *-- Tell the zip object what we want to do lozip.itemlist = SYS(5)+CURDIR()+"*.bak" lozip.zipfile = SYS(5)+CURDIR()+"bak.zip" lozip.zipsuboptions = 0

3 Seite 3 von 8 lozip.extprogtitle = "Zipping up bak files..." gotherm.caption = lozip.extprogtitle *-- Set flags to allow events to fire lozip.majorstatusflag =.T. lozip.minorstatusflag =.T. Application.AutoYield =.F. lozip.actiondz=zip_add Application.AutoYield =.T. DEFINE CLASS ZipCaretaker AS FORM *-- adds an instance of ZipControl to *-- the form with the name ozip ADD OBJECT ozip AS ZipControl ENDDEFINE DEFINE CLASS ZipControl AS OLEControl OLEClass="dzactxctrl.dzactxctrl.1" PROC ZipMajorStatus LPARAMETERS itemname,percent,cancel *-- Tell thermometer form to update the major status gotherm.updatemajor(itemname,percent,cancel) gotherm.resetminorpercent() ENDPROC PROC ZipMinorStatus LPARAMETERS itemname,percent,cancel *-- Tell thermometer form to update the minor status gotherm.updateminor(itemname,percent,cancel) ENDPROC ENDDEFINE Figure 1 shows a screen shot of the thermometer displayed to the user. The Therm form is available in the accompanying Download file. Figure 1: Shows a screen shot of the thermometer. Message callback event During the process of zipping and unzipping information, many text messages are generated by the DynaZIP controls: Text is displayed on status thermometers (such as "Processing List of Files. Please Wait "). Information is written to log files (such as "XYZ.TXT [added]"). Message boxes are displayed to prompt or inform the user of a situation (such as "Please insert the first disk of the Multi-

4 Seite 4 von 8 Volume set. Press OK when ready or Cancel to abort.") Before a text message is displayed to the user, written to the log file, or displayed in a message box, the DynaZIP controls pass the text message to the Message callback event. This provides the perfect opportunity for the developer to customize or internationalize the message, or even to use a VFP message box or custom dialog to present the information to the user where a message box is called for (such as "Please insert the first diskette "). Here s an example of customizing a message. When zipping, the first thing that the DynaZIP Zip control does is build a list of the information that is about to be zipped. The control generates the message "Processing List of Files. Please Wait " to display on the thermometer. Before being displayed, the message is sent to the Message callback event. A grumpy developer could then change the message to "I am building your #@$%&!! list of files. Keep your pants on, I m going as fast as I can. " Text messages like the one presented in the last paragraph are pretty straightforward, but certain messages are more tricky to customize. Some messages contain what I call "embedded variable information." For example, consider the string "Item 1 of 10." This string raises several questions: How do I know which item is currently being processed, or how many total items need to be processed? (In other words, where do I get the 1 and the 10?) Do I need to keep a running count? Do I have to parse out the 1 and the 10, in order to put them in the correct places in the customized string? (Do I have to parse out what s between the word "Item" and the word "of" to extract the "1" and then parse out what follows the word "of" to extract the "10"?) The DynaZIP controls use a technique similar to the MsgSvc utility in Steven Black s INTL Toolkit to handle this situation. The message passed to the message callback event can contain placeholders for pieces of information embedded in the text message. For example, the "Item 1 of 10" text message arrives in the message callback event as the text message "Item %s of %s." To customize this message, create a message that includes the two %s placeholders. For example, the developer could change the string "Item %s of %s" to "File %s of %s." What happens to the placeholders? When you leave the message callback event, DynaZIP substitutes the values for the embedded parameters. For example, the change above converts the "Item 1 of 10" message to "File 1 of 10." No intervention is required. Piece of cake! The following parameters are passed to the Message callback event: MsgID (Numeric): This parameter is an ID that conveys what type of message event has occurred. There are basically two types of message events. First, there are event types that require a message box dialog to be displayed to the user. For example, when unzipping a multivolume ZIP file, a message event will fire with a MsgId of MSGID_DISK. This message event fires because it s necessary to present a message box to the user prompting for a particular diskette. Second, there s an event type (MSGID_CHANGE) that receives a string that s about to be presented to the user. The #DEFINEs for these IDs all have "MSGID" prefixes. MbType (Numeric): This parameter indicates which message box dialog should be displayed to the user. Its value is equivalent to the ndialogboxtype parameter in VFP s MESSAGE BOX() command: It determines things such as which buttons are on the message box, which button has focus, and similar items. p1 (Numeric) and p2 (Numeric): These are general parameters passed by the DynaZIP controls that have meaning for certain MsgId values. For instance, when a message event occurs with a MsgId of MSGID_ZFORMAT, it means that there was a ZIP Multi-Volume Disk Formatting/Wiping Failure. The p1 value conveys whether it was a disk formatting error (p1=0) or a disk wiping failure (p1=1). These codes are covered in the manual. sz1 (Character): This parameter holds the text of the message. If the MsgId is of the type that requires a dialog to be displayed, then this is the text that will be shown in the message box window. Otherwise this value is the string that the developer is being given the opportunity to customize. sz2 (Character): This parameter holds the text that will be used as the titlebar caption of the message box if DynaZIP presents it to the user. rc (Numeric): An integer value corresponding to one of the acceptable standard Message box return values for the associated MsgId. These values all have the prefix "ID" (such as IDOK, IDCANCEL, and similar items) and can be found in Foxpro.H. If you choose to replace the DynaZIP dialog with your own, it s important that you set the value of this parameter to the return value of the message box you surface. The return codes that apply to each of the MsgIds can be found in the manual. If rc is 0, then DynaZIP will present a dialog to the user. Here are two examples that demonstrate the two message event type categories. This first example demonstrates a message event type that doesn t require a dialog. During the zipping and unzipping process, the DynaZIP controls generate messages that convey the current status of the process. As each file is being processed, a message callback event is fired with a MsgId equal to MSGID_CHANGE and an sz1 equal to "Item %s of %s." The developer can change this message by overwriting the value of the sz1 parameter. Here s an example of customizing a message using the Message callback event: LPARAMETERS MsgId, MbType, sz1, sz2, rc *-- Customize the "Item %s of %s." *-- message only. IF MsgId = MSGID_CHANGE AND ; sz1 = "Item %s of %s." sz1 = "Scooby Snack %s out of %s"

5 Seite 5 von 8 ENDIF RETURN This code was obviously written by a developer for Hanna-Barbera, Inc. (the producers of the cartoon "Scooby Doo"). Any embedded placeholders (such as %s) in the sz1 parameter are resolved automatically at the end of each MSGID_CHANGE event. For example, in the code above, if the DynaZIP control is currently processing the fourth file out of 10 files, sz1 will contain "Scooby Snack 4 out of 10." The message for this event type (MSGID_CHANGE) could easily be internationalized by passing the value in sz1 to the I() function of INTL. This next example demonstrates a message event type that requires a dialog. Message events that require a dialog actually generate several message events. For instance, if no files match the ItemList during the creation of a ZIP file called "c:\rick.zip," a message box needs to be presented to the user, saying that there is nothing to do. Here are the message callback events that fire: First, a message event fires with a MsgId of MSGID_CHANGE and an sz1 of "Nothing to do!" (the contents of the message box). Next, a message event fires with a MsgId of MSGID_CHANGE and an sz1 of "DynaZIP Zip Error" (the title of the message box). Finally, a message event fires with a MsgId of MSGID_ERROR (requires a message box dialog) and an sz1 of "Nothing to do! (c:\rick.zip)" and an sz2 of "DynaZIP Zip Error." Notice that the individual text messages that make up the message box dialog each generate a message event. Since embedded parameters (such as %s) are resolved at the end of each of the individual MSGID_CHANGE events, by the time the MSGID_ERROR event type fires, any embedded parameters (such as Item %s of %s) have already been resolved (such as Item 1 of 10). This means that if you want to customize the text of a dialog, it s important to customize it when the MSGID_CHANGE events fire. Presenting your own special dialog to present the message can be done for any MsgId not equal to MSGID_CHANGE. Here s an example of customizing a dialog using the Message callback event: LPARAMETERS MsgId, MbType, sz1, sz2, rc *-- Customize the "Nothing To Do!" *-- dialog only. IF MsgId = MSGID_ERROR AND p1 = ZE_NONE *-- Display a VFP message box using the *-- passed message box contents (sz1) *-- with a customized title caption rc = MESSAGEBOX(sz1,MbType,"My Application Name") ENDIF RETURN The message box used for this event type could easily be internationalized by using the INTL MsgSvc utility: rc = MsgSvc("MSGID_ERROR", sz1) Rename callback event This callback event falls under the category of "Way Cool!" This event fires once per file that s being zipped or unzipped. Information passed to this event pertains to the file currently being processed (name, date, time, and attributes). The Rename callback event gives you the opportunity to change the information regarding the file being zipped or unzipped. When zipping, changing this information means that the entry in the ZIP file will have updated information (the original entry that was being zipped is untouched). When unzipping, changing this information means that the file being written to disk will have updated information (the entry in the ZIP file is untouched). The following is the list of parameters passed to the Rename callback event: ItemName (Character): This is the name of the file being zipped or unzipped. While zipping, changing this parameter changes the name of the item in the ZIP file. While unzipping, changing this parameter changes the name of the file being written to disk. IDate (Numeric): This is a binary representation of the file s last modification date. You can read the manual to find out more about this binary format. I ve included two functions in a program called ZIPFXN.PRG. These functions help with conversion between this binary format and the VFP date format. ConvertIDateToDate(IDate) returns the VFP date corresponding to the passed IDate value. ConvertDateToIDate(VFPDate) returns the IDate value corresponding to the passed VFP date value. ITime (Numeric): This is a binary representation of the file s last modification time. You can read the manual to find out more about this binary format. I ve included two functions in a program called ZIPFXN.PRG. These functions help with conversion between this binary format and the VFP 24-hour time character format. ConvertITimeToTime(ITime) returns the VFP 24-hour time character value corresponding to the passed ITime value. ConvertTimeToITime(VFPTime) returns the ITime value corresponding to the passed VFP 24-hour time character value.

6 Seite 6 von 8 LAttrib (Numeric): This is a binary representation of the attributes of the file. You can read the manual to find out more about this binary format. I ve included two functions in a program called ZIPFXN.PRG in this month s files. These functions help with conversion between this binary format and a string that represents all attributes of the file. ("R" for ReadOnly, "H" for Hidden, "S" for System, and "A" for Archive: in other words, a hidden system file would return the string "HS"). ConvertLAttribToString (LAttrib) returns the string corresponding to the passed Lattrib value. ConvertStringToLAttrib(AttributeString) returns the LAttrib value corresponding to the attribute string. OrigItemName (Character): When unzipping, this is the original item name as it appears in the ZIP file. When zipping, this is the original unmodified name of the file being zipped (including drive and path). Changing this parameter has no effect. Rc (Numeric): Setting this variable to zero means that the renaming was successful. I ll now present two examples of how this callback event can be used. The first example will demonstrate how to use the Rename callback event during unzipping. For the sake of example, let s say that your accountant periodically sends you a ZIP file containing spreadsheets regarding the invoices and receipts your business has received by month. He uses the naming convention XXXInv.XLS for invoices and XXXRec.XLS for receipts, where XXX is the three-letter month abbreviation (such as JAN,FEB, and similar abbreviations). The following is an example of the contents of a ZIP file you might receive: MARInv.XLS MARRec.XLS APRInv.XLS APRRec.XLS Your application requires a different organization of the XLS files. There s a Year directory with subdirectories for each month. Another requirement is that when the files get put into this new directory structure, the three-letter month designation will be stripped off. So after the unzipping is done, the files should be organized as follows: Year +-- MAR +--- Inv.XLS (formerly MARInv.XLS) +--- Rec.XLS (formerly MARRec.XLS) +-- APR +--- Inv.XLS (formerly APRInv.XLS) +--- Rec.XLS (formerly APRRec. XLS) When unzipping, you could put the following code into the Rename callback event to strip off the month from the name of the XLS, and add the path to put it into a directory corresponding to the month: LPARAMETERS ItemName,iDate,iTime, ; lattrib,origitemname,rc LOCAL lcmonthdirectory, ; lcfile, lcitemname *-- ItemName is the file being unzipped *-- Get name of file without directory IF AT("\",ItemName)!=0 lcfile = SUBSTRC(ItemName,RAT("\",ItemName)+1) ELSE lcfile = ItemName ENDIF *-- Get Month from file name lcmonthdirectory = LEFTC(lcFile,3)+"\" *-- Strip month from file name lcfile = SUBSTRC(lcFile,4) *-- Build the new name and path lcitemname = this.destination+ ;

7 Seite 7 von 8 "\Year\"+lcMonthDirectory+lcFile *-- overwriting value of itemname renames *-- the file being written out ItemName = lcitemname So if the ItemName = "MARInv.XLS," then the event changes the ItemName to "Year\MAR\Inv.XLS." Very powerful indeed! I m now going to demonstrate how to tackle the same problem from the zipping side of things, also using the Rename callback event. For the sake of example, you decide that the accountant should be giving you a ZIP file that knows where to put the files: In other words, it has already renamed the files and includes the proper paths. All you have to do, then, is unzip the ZIP file (without using DynaZIP if you want) and everything will fall into its proper place. The code that will accomplish this is very similar to the code we saw previously: LPARAMETERS ItemName,iDate,iTime, ; lattrib,origitemname,rc LOCAL lcmonthdirectory, ; lcfile, lcitemname lcitemname = "" *-- ItemName is the file being zipped *-- Get name of file without directory IF AT("/",ItemName)!=0 lcfile = SUBSTRC(ItemName,RAT("/",ItemName)+1) lcitemname = SUBSTRC(ItemName,1,RAT("/",ItemName)-1) ELSE lcfile = ItemName ENDIF *-- Get Month from file name lcmonthdirectory = LEFTC(lcFile,3)+"/" *-- Strip month from file name lcfile = SUBSTRC(lcFile,4) lcitemname = lcitemname+ ; "Year/"+lcMonthDirectory+lcFile *-- overwriting value of itemname renames *-- the file being written out ItemName = lcitemname Using such code, the ZIP file would contain the following pathed items: Year\MAR\Inv.XLS Year\MAR\Rec.XLS Year\APR\Inv.XLS Year\APR\Rec.XLS Pretty snazzy, huh? The previous two Rename event code samples are nearly identical. However, there s an important, subtle difference: the direction of the slashes. For some reason, the direction of the "slashes" in the path of the item in the itemname parameter is reversed when zipping. In other words, forward slashes ("/") are used in the path instead of the normal DOS back

8 Seite 8 von 8 slashes ("\"): in other words, the file name \MYDIR\ABC.TXT comes across as /MYDIR/ABC.TXT.! There are two files called ZIPREN.PRG and UNZREN.PRG that contain the full source code for the two code samples above in the accompanying Download file. MemToMem callback event I m afraid I have to retract a statement that I made in April s article. In that piece, I said that the ZIP_MEMTOMEM AND UNZIP_MEMTOMEM actions couldn t be used from VFP. That statement was incorrect. Mea culpa, mea culpa, mea maxima! Please do your part to spread the word to any VFP developers you meet. In fact, do yourself the service of pulling out April s article and striking through the statements with a big honking permanent red marker! The MemToMem callback event allows you to compress a string into another string (hence the name MemToMem). This has applications in compressing (and uncompressing) string information into memo fields and when encrypting the information with a password as well. I won t go into the specifics of this callback event in this article because it would take up too much space. A demonstration of the use of this callback event can be found in the sample files included with the DynaZIP-AX installation: These files are named VFPMEMTOMEM*.*. Order of callback event firing To get a better idea of how the callback events work together, I ve created a program file called CALLORD.PRG that logs the callback events that fire, as well as what was passed to them, and then uses a form called ZIPLOG to display the information. These files are available in the accompanying Download file. Summary This month I described the DynaZIP features that help developers to customize/internationalize text and dialogs presented to the user. Once more, I have nothing but high praise for the DynaZIP product. Feel free to contact me with your feedback or thoughts. Next time I ll present a small framework that makes the controls easier to use and extend.