The purpose of FoxBin2Prg is to facilitate the Diff and Merge of Visual FoxPro 9 binaries, which are not natively supported by any source control tool. Traditionally FoxPro comes with a tool named SccText.prg who can make a text representation exporting the source code contained in FoxPro tables with a DBF structure. An enhanced version is available on VFPx named SccTextX, but like his ancestor, have some design limitations, as:
FoxBin2Prg is designed to bring a solution for all of this, and a few more things, which makes tx2 (text) files with PRG-style and enhances compatibility with SCCAPI (SourceSafe) and other SCM tools, like PlasticSCM, Git, Subversion, and the like.
Special remark on Merge operation is made, because it is the most difficult and more used operation when working with SCM tools, and this require that generated text files can be manipulated manually or automatically.
Note: You came from VSS and have the generated .pjm without the real project?
Convert the .pjm to .pjx/.pjt sending to FoxBin2Prg, and it generates the real project again.
TX2 files keep lists of objects and their metadata in a special OBJECTDATA tag, in which the order of the list is the ZOrder of the object, like this example:
This way, you can rearrange the items to alter their ZOrder, and this does auto-renumbering when regenerating binaries.
Starting from v1.19.21 arrays don't need to be preceded with "^" symbol, and methods don't need to be preceded with "*" symbol, whick makes this section more easy to maintain.
On binaries, property ordering is a very different thing. No documentation is available about this, so the only guideline is trying to make it as FoxPro does, but this is not always possible because there are two extreme cases, and variants between the them:
1) The best and easy one, is when defining a class (or control) with his properties: In this case, each class have a phisical record on the scx/vcx table, and all the properties of it are keep toghether, so this ordering can be easily duplicated (look at "TESTS\DATOS_READONLY\f_form_aa.scx file" on foxbin2prg project and open it as a table to see the class per record)
2) The worst and most difficult case, is when there is a container with controls subclassed, and properties are changed on the instance: In this case FoxPro makes a big and unique list of properties of all objects in just one phisical record, so there is no way to know which property corresponds to which class. For this case, I've made a unique list composed of all properties of all classes, ordered according to most common orderings (look at "TESTS\DATOS_READONLY\f_form_aa2.scx file" on foxbin2prg project and open it as a table to see all the properties of all the classes of the same earlier example, in just one record)
For these two cases, and starting from v1.19.22, I've created several props_* files with ordering by class for the 1st case, and a list with all in it (props_all.txt) for the second case, so in case of any problems, rearranging some props will be an easy thing.
Warning: These props_* files are necessary in the foxbin2prg install directory. It's recommended to use the EXE version that have all files included and is faster.
Several Unit Tests (in TESTS directory) are made to make the best effort to cover the most typical use cases. There is also an Excel spreedsheet with the compilation of properties of each class with the order that FoxPro uses internally, and a tab with the all-in-one order for the worst case.
Starting from v1.19.23 this values are just cleared on tx2 files, and regenerated on the binaries, as well the sccdata field, because this way there are no differences when opening/closing certain files, as a PJX, which by default fill some of this fields even if no modifications are made, which causes that SCM tools detect those changes. Having them prefilled, then no changes are detected.
Note: Just data export is implemented, not import, so this is a one way operation!
If you want to export the data of just some tables and not for all of them, the best way is moving the tables for data export to another directory, or even a subdirectory of main data files, and write a foxbin2prg.cfg with DBF_Conversion_Support: 4 for this diretory only, taking advantage of multi-configuration capability introduced on v1.19.25
FoxBin2prg.cfg (Main CFG or Directory CFG)
New foxbin2prg.cfg options for filtering tables from conversion using one or multiple conbinations of filemasks.
Syntax:
DBF_Conversion_Included: <filemask>[ ,<filemask> [ , ... ] ]
DBF_Conversion_Excluded: <filemask>[ ,<filemask> [ , ... ] ]
Example of multiple file masks (separte with ","):
DBF_Conversion_Included: PET*.*, ??ME.DBF, ???.DBF, ?.*
.
New <filename.dbf.cfg> configuration options
These options can be used in any combination inside a dbf particular cfg file, if you create a text file using your dbf filename and adding ".cfg".
Syntax for filename.dbf.cfg contents:
DBF_Conversion_Order: <C_Expression>
DBF_Conversion_Condition: <C_Expression>
Example: customers.dbf.cfg
DBF_Conversion_Order: cust_no
DBF_Conversion_Condition: cust_no > 10
The main purpose of FoxBin2Prg is to be used for Diff and Merge with a SCM tool, so in this scenario the data is not needed, but there are use cases where exporting, importing or manipulating data is needed while making the conversions, and for those cases are this properties.
This is a sample program:
To use the translated messages just rename the .h file language you want to foxbin2prg.h (drop the "en" or "ge" part), open foxbin2prg.pjx project and recompile the EXE. That's all!
Note: The messages on vbs scripts are not translated (are very few), just the FoxPro ones, which have 95% of the messages.
Want to collaborate translating the messages to your language so others can use it?
Just copy foxbin2prg_en.h using your county code in the file name and translate the messages (can be done in 15 minutes or less), and send it to me. I will include it in the next release ;-)
This feature can be disabled on main CFG setting AllowMultiConfig: 0
If you want a special capitalization (ie: capitalize the full name of the file), you can configure this behaviour in "{filename_caps.cfg}" configuration file, which includes syntax examples.
File capitalization occurs when you convert a file, but in the case that the input file can't be converted, no message error ir thrown (ie: when using the PRG version from VFP Command Line with the form to be converted opened)
Debug messages are translated (+90% of debug messages), but capitalization process messages are not, and are available just in Spanish (-10% of debug messages).
Here we need to identify 2 distinct operations: checkin because a binary modification with the IDE and checkin because a merge operation.
Note: If any binary doesn't have the corresponding tx2 file, it can be because it is in use (close opened bin and clear all at VFP command window), or because you really haven't made any changes to the code, in which case you should undo the changes to the binaries that don't have their tx2 files using the "undo" option for these files of your SCM tool.
Note: If at the end of a merge operation there are binaries left, you need to choose the "workspace binaries", because anyway you will regenerate them later from their tx2 files.
For options on integrating FoxBin2Prg with SCM tools, look at this topic:
> FoxBin2Prg and use with SCM tools
- It doesn't generate PRG like code
- It doesn't permit modification of the txa (text) files generated
- Scctext's txa (text) files generated can't be used for merge with SCM tools
- Timestamps and ZOrder fields generate a lot of unnecesary differences all over the text file
FoxBin2Prg is designed to bring a solution for all of this, and a few more things, which makes tx2 (text) files with PRG-style and enhances compatibility with SCCAPI (SourceSafe) and other SCM tools, like PlasticSCM, Git, Subversion, and the like.
Special remark on Merge operation is made, because it is the most difficult and more used operation when working with SCM tools, and this require that generated text files can be manipulated manually or automatically.
Note: You came from VSS and have the generated .pjm without the real project?
Convert the .pjm to .pjx/.pjt sending to FoxBin2Prg, and it generates the real project again.
This are the FoxBin2Prg.cfg configuration file settings and their meaning
| FoxBin2Prg.cfg keywords and Defaults | Description |
|---|---|
| extension: xx2 | FoxBin2Prg extensions ends in '2' (pj2, vc2, sc2, etc), but you can change that. For example you can change pj2 to pja using this: extension: pj2=pja for making it SourceSafe (sccapi v1) compatible |
| DontShowProgress: 0 | By default, a progress bar is shown when processing multiple-files |
| DontShowErrors: 0 | By default, show message errors in a modal messagebox. Specify "1" if don't want to show errors |
| NoTimestamps: 1 | By default, timestamp fields are cleared on tx2 files, because a lot of differencies are generated on binaries and tx2 files with Timestamps activated. This timestamp field is part of the vcx, scx and other Foxpro binary source code files |
| Debug: 0 | By default, don't generate individual <file>.Log with process hints. Activate with "1" to find possible error causes and for debugging |
| ExtraBackupLevels: 1 | By default, one .BAK file is created. With this setting you can make more .N.BAK files, or none at all using 0 |
| ClearUniqueID: 1 | 0=Keep UniqueID, 1=Clear Unique ID. Very useful for Diff and Merge. By default, UniqueID fields are cleared on tx2 files, because a lot of differencies are generated with UniqueID activated |
| OptimizeByFilestamp: 0 | 0=Don't optimize (always regenerate), 1=Optimize (regenerate only when destination filestamp es older). By default this optimization is deactivated, and it is not recommended if using for merge, so bin and tx2 files can be modified seperately |
| AllowMultiConfig: 1 | 1=Allow CFG files per directory. if no CFG found, then use Main CFG. 0=Only use Main CFG. By default is activated, so you can use a foxbin2prg.cfg per directory if needed |
| DropNullCharsFromCode: 1 | 1=Drop NULL chars from source code / 0=Leave NULLs in source code |
| XXX_Conversion_Support: N | Where N is: 0=No support, 1=Generate TXT only (Diff), 2=Generate TXT and BIN (Merge), 4=Generate TXT with DATA for DIFF (DBF only) |
| PJX_Conversion_Support: 2 | Default value is 2 - Bidirectional (tx2 and bin) support activated |
| VCX_Conversion_Support: 2 | Default value is 2 - Bidirectional (tx2 and bin) support activated |
| SCX_Conversion_Support: 2 | Default value is 2 - Bidirectional (tx2 and bin) support activated |
| FRX_Conversion_Support: 2 | Default value is 2 - Bidirectional (tx2 and bin) support activated |
| LBX_Conversion_Support: 2 | Default value is 2 - Bidirectional (tx2 and bin) support activated |
| MNX_Conversion_Support: 2 | Default value is 2 - Bidirectional (tx2 and bin) support activated |
| DBC_Conversion_Support: 2 | Default value is 2 - Bidirectional (tx2 and bin) support activated |
| DBF_Conversion_Support: 1 | Default value is 1 - just tx2 support activated. The support for regenerating DBFs structures (value = 2) are disabled by default to not overrite data accidentally. When activating bidirectional support, keep in mind that Data is not restored, just the structure and indexes!. A value of 4 is used to export Structure and Data, but exported data is not imported again. Use with care. |
FoxBin2Prg Internals
ZOrder
In TX2 files and starting from v1.19.12, the ZOrder, that determines the order on which objects are instantiated and which one is on top, is maintained in a more intuitive and optimal way compared to traditional stored numerical values.TX2 files keep lists of objects and their metadata in a special OBJECTDATA tag, in which the order of the list is the ZOrder of the object, like this example:
DEFINE CLASS cnt_controls AS container && "cnt_controls" class description *< CLASSDATA: Baseclass="container" Timestamp="" Scale="Pixels" Uniqueid="" /> *-- OBJECTDATA items order determines ZOrder *< OBJECTDATA: ObjPath="Check2" UniqueID="" Timestamp="" /> *< OBJECTDATA: ObjPath="Check4" UniqueID="" Timestamp="" /> *< OBJECTDATA: ObjPath="Label_h" UniqueID="" Timestamp="" /> *< OBJECTDATA: ObjPath="Textbox_h" UniqueID="" Timestamp="" /> *< OBJECTDATA: ObjPath="Check1" UniqueID="" Timestamp="" /> *< OBJECTDATA: ObjPath="Check3" UniqueID="" Timestamp="" />
This way, you can rearrange the items to alter their ZOrder, and this does auto-renumbering when regenerating binaries.
PAM Section
Ths section is generated for classes and forms, it is delimited with the <DefinedPropArrayMethod> tag, and have the definition of Properties, Arrays and Methods, with their comments, like this example:DEFINE CLASS c1 AS custom OLEPUBLIC && Description of "c1" class *<DefinedPropArrayMethod> *m: emptymethod_with_comments && This method have no code, just comments. Let's see what happens! *m: mymethod && My Method *p: prop1 && My prop 1 *p: special_prop_with_cr *p: special_prop_with_crlf && Should have CR+LF *a: array_1_d[1,0] && 1 dimension array (1) *a: array_2_d[1,2] && 2 dimension array (1,2) *p: _memberdata && XML Metadata for customizable properties *</DefinedPropArrayMethod>
Starting from v1.19.21 arrays don't need to be preceded with "^" symbol, and methods don't need to be preceded with "*" symbol, whick makes this section more easy to maintain.
Property Ordering
On TX2 files is easy, ordering for methods and properties is done in alphabetical way, like scctext does with methods. This makes comparisons easier and with less differences.On binaries, property ordering is a very different thing. No documentation is available about this, so the only guideline is trying to make it as FoxPro does, but this is not always possible because there are two extreme cases, and variants between the them:
1) The best and easy one, is when defining a class (or control) with his properties: In this case, each class have a phisical record on the scx/vcx table, and all the properties of it are keep toghether, so this ordering can be easily duplicated (look at "TESTS\DATOS_READONLY\f_form_aa.scx file" on foxbin2prg project and open it as a table to see the class per record)
2) The worst and most difficult case, is when there is a container with controls subclassed, and properties are changed on the instance: In this case FoxPro makes a big and unique list of properties of all objects in just one phisical record, so there is no way to know which property corresponds to which class. For this case, I've made a unique list composed of all properties of all classes, ordered according to most common orderings (look at "TESTS\DATOS_READONLY\f_form_aa2.scx file" on foxbin2prg project and open it as a table to see all the properties of all the classes of the same earlier example, in just one record)
For these two cases, and starting from v1.19.22, I've created several props_* files with ordering by class for the 1st case, and a list with all in it (props_all.txt) for the second case, so in case of any problems, rearranging some props will be an easy thing.
Warning: These props_* files are necessary in the foxbin2prg install directory. It's recommended to use the EXE version that have all files included and is faster.
Several Unit Tests (in TESTS directory) are made to make the best effort to cover the most typical use cases. There is also an Excel spreedsheet with the compilation of properties of each class with the order that FoxPro uses internally, and a tab with the all-in-one order for the worst case.
Timestamps and UniqueIds
Timestamp field are used in VFP to track changes with 3rd party tools and UniqueId is used to identify classes inside binaries, but, AFAIK, they are not used by VFP itself. There are 2 switches, enabled by default, that are used to clear this values (ClearUniqueId and NoTimestamps), so no differences are shown for this values constantly changing.Starting from v1.19.23 this values are just cleared on tx2 files, and regenerated on the binaries, as well the sccdata field, because this way there are no differences when opening/closing certain files, as a PJX, which by default fill some of this fields even if no modifications are made, which causes that SCM tools detect those changes. Having them prefilled, then no changes are detected.
DBF Data Export for Diff
Starting at version v1.19.21, and thanks to Doug Hennig proposal and coding, FoxBin2Prg can export DBFs Data, specially intended for small DBFs, as config ones, on which sometimes is needed to track the changes. It is deactivated by default, but can be activated with DBF_Conversion_Support: 4 in foxbin2prg.cfgNote: Just data export is implemented, not import, so this is a one way operation!
If you want to export the data of just some tables and not for all of them, the best way is moving the tables for data export to another directory, or even a subdirectory of main data files, and write a foxbin2prg.cfg with DBF_Conversion_Support: 4 for this diretory only, taking advantage of multi-configuration capability introduced on v1.19.25
FoxBin2prg.cfg (Main CFG or Directory CFG)
New foxbin2prg.cfg options for filtering tables from conversion using one or multiple conbinations of filemasks.
Syntax:
DBF_Conversion_Included: <filemask>[ ,<filemask> [ , ... ] ]
DBF_Conversion_Excluded: <filemask>[ ,<filemask> [ , ... ] ]
Example of multiple file masks (separte with ","):
DBF_Conversion_Included: PET*.*, ??ME.DBF, ???.DBF, ?.*
.
New <filename.dbf.cfg> configuration options
These options can be used in any combination inside a dbf particular cfg file, if you create a text file using your dbf filename and adding ".cfg".
Syntax for filename.dbf.cfg contents:
DBF_Conversion_Order: <C_Expression>
DBF_Conversion_Condition: <C_Expression>
Example: customers.dbf.cfg
DBF_Conversion_Order: cust_no
DBF_Conversion_Condition: cust_no > 10
DBF/DB2 Convertion Hooks
From version v1.19.19 there is a new property "run_AfterCreateTable" and from version v1.19.24 "run_AfterCreate_DB2". The purpose of both properties is to allow the execution of an external program each time a DBF is converted to DB2 or a DB2 is converted to DBF.The main purpose of FoxBin2Prg is to be used for Diff and Merge with a SCM tool, so in this scenario the data is not needed, but there are use cases where exporting, importing or manipulating data is needed while making the conversions, and for those cases are this properties.
This is a sample program:
*-- DEMO HOOK FOR PROCESSING DBFs AND DB2
LOCAL oFB AS 'c_foxbin2prg' OF 'c:\desa\foxbin2prg\foxbin2prg.prg'
oFB = NEWOBJECT( 'c_foxbin2prg', 'c:\desa\foxbin2prg\foxbin2prg.prg' )
oFB.DBF_Conversion_Support = 2
oFB.run_AfterCreateTable = 'p_AfterCreateTable'
oFB.run_AfterCreate_DB2 = 'p_AfterCreate_DB2'
oFB.Ejecutar( 'C:\DESA\foxbin2prg\TESTS\DATOS_TEST\fb2p_dbc.dc2' )
oFB.Ejecutar( 'C:\DESA\foxbin2prg\TESTS\DATOS_TEST\fb2p_dbf.db2' )
oFB.Ejecutar( 'C:\DESA\foxbin2prg\TESTS\DATOS_TEST\fb2p_dbf.dbf' )
oFB = NULL
RETURN
PROCEDURE p_AfterCreateTable
LPARAMETERS lnDataSessionID, tc_OutputFile, toTable
MESSAGEBOX( 'Actual Datasession: ' + TRANSFORM(SET("Datasession")) + CHR(13) ;
+ 'lnDataSessionID: ' + TRANSFORM(lnDataSessionID) )
*-- You can fill the table <tc_OutputFile> here.
INSERT INTO fb2p_dbf (nombre,edad,depto) VALUES ('Fer', 45, 'dpto')
ENDPROC
PROCEDURE p_AfterCreate_DB2
LPARAMETERS lnDataSessionID, tc_OutputFile, toTable
MESSAGEBOX( 'Actual Datasession: ' + TRANSFORM(SET("Datasession")) + CHR(13) ;
+ 'lnDataSessionID: ' + TRANSFORM(lnDataSessionID) )
*-- You can export the data here.
STRTOFILE( nombre + STR(edad,3) + depto, 'c:\temp\data.txt', 1)
ENDPROC
Language Support for messages
As for version v1.19.24 FoxBin2Prg messages are available natively on Spanish, but English and German are available too on external file foxbin2prg_xx.hTo use the translated messages just rename the .h file language you want to foxbin2prg.h (drop the "en" or "ge" part), open foxbin2prg.pjx project and recompile the EXE. That's all!
Note: The messages on vbs scripts are not translated (are very few), just the FoxPro ones, which have 95% of the messages.
Want to collaborate translating the messages to your language so others can use it?
Just copy foxbin2prg_en.h using your county code in the file name and translate the messages (can be done in 15 minutes or less), and send it to me. I will include it in the next release ;-)
Multi-config (config per directory)
Starting at version v1.19.25 FoxBin2Prg allow configuration per directory, overriding the main configuration of FoxBin2Prg directory. The override is by each setting, so you can reconfigure one or more settings and the remaining settings are inherited from main CFG.This feature can be disabled on main CFG setting AllowMultiConfig: 0
File Capitalization
FoxBin2Prg takes care of file capitalization (their extension, specifically), using another program called "{(filename_caps.exe)}" for capitalizing input files and output files. This is because some SCM and DVCS tools are multiplatform, and if you add a "file.ext" and later add a "file.EXT" or "File.Ext", the SCM can interpret them as different files, because on Unix, Linux, Mac and other sistems, they are.If you want a special capitalization (ie: capitalize the full name of the file), you can configure this behaviour in "{filename_caps.cfg}" configuration file, which includes syntax examples.
File capitalization occurs when you convert a file, but in the case that the input file can't be converted, no message error ir thrown (ie: when using the PRG version from VFP Command Line with the form to be converted opened)
Conversion processes Logging
If you want detailed process logging of FoxBin2Prg conversions, to see all internal processes, decisions and used optimizations, you can enable debugging using debug:1 in foxbin2prg.cfg configuration file, and a full log is generated on FoxBin2Prg installation directory.Debug messages are translated (+90% of debug messages), but capitalization process messages are not, and are available just in Spanish (-10% of debug messages).
How to use with a SCM tool
Here we need to identify 2 distinct operations: checkin because a binary modification with the IDE and checkin because a merge operation.
Checkin because a binary modification within the IDE
When you work with the VFP 9 IDE, you modify the binary files (forms, classlib and the like), then you checkin your modifications, but before doing this you regenerate the tx2 files just for the the changed binaries, and once you have all the boundles of bins/tx2, you checkin them.Note: If any binary doesn't have the corresponding tx2 file, it can be because it is in use (close opened bin and clear all at VFP command window), or because you really haven't made any changes to the code, in which case you should undo the changes to the binaries that don't have their tx2 files using the "undo" option for these files of your SCM tool.
Checkin because a merge operation
When you merge a branch, you work on tx2 files seeing and merging differences manually or automatically. When you have done with the merge you need to checkin, but before this, you need to regenerate the binaries (forms, classlib, etc) just from the tx2 files merged, to sync their code. Once you have done, then you checkin the boundle of bins/tx2.Note: If at the end of a merge operation there are binaries left, you need to choose the "workspace binaries", because anyway you will regenerate them later from their tx2 files.
For options on integrating FoxBin2Prg with SCM tools, look at this topic:
> FoxBin2Prg and use with SCM tools