Porting to newer TeamDeveloper versions
In order to successfully port to a newer Team Developer version you can follow these tips and tricks.
Depending on the size and usage of particular TD features you may have to manually change your ported sources.
Initially to get more grip on the process you will have to 'know' your current application:
What is the structure of your current sources
- Library structure
- Generally applications are structured using libraries. The main application (apt, app) includes libraries and they in turn include libraries also.
- It is good to have knowledge about this. Make a diagram of the include tree. Which library includes others.
- In fact, it is sound to have such an overview anyway, it shows the dependencies between parts of your sources.
- Having such an overview makes a bottom-up approach more easily.
- Usage of Team Developer features
- Depending on the functionality and implementation of your application, it may use certain out-of-the-box TD features.
- Make a list of used components. For instance, which VT objects are used or others like qcktabs.
- Also make a list of database drivers used.
- Does your application use dynalibs? Make an overview where they are used, and from which sources they are build.
- When you initially think about those features and get them in a list, you will be hinted on probable issues.
- Before porting, read the release notes for the destination TD version ! Look for specific notes concerning your used TD features.
- It may describe changed functionality, solved bugs or indications when certain functionality is deprecated.
- Usage of third party components
- Know which external components are used. They can be third party dll's or ActiveX objects.
- Especially, when you build dll's using the Team Developer C lib or CDK, be aware of this.
- It will require more or less manual porting depending on the components.
- File formats
- In order to have more grip on the internals of your sources, check how your apt/app and libraries are saved.
- Big rule here is : have it all in TEXT format.
- This makes finding specific hidden settings more easily. Using a text editor, you can inspect your sources in more detail
- Using the IDE, many internal settings are hidden. To correct any specific issues, a text editor like notepad can access those hidden settings.
- So, if your source structure is saved as normal or compiled, be aware before porting, you will have to save them all as text !
Know your destination TD environment
- It is obvious to say you will first have to get knowledge about the TD version you are porting to.
- Read the release notes of the destination version in front. Also read all notes of the versions in between.
- For instance, if you port from 1.5.1 to 4.2, read all release notes present from 1.5.1, 2.x, 3.x up to 4.2.
- They contain hints on changed functionality, fixed bugs, deprecated features etc etc.
- You can not port a deprecated functionality, you should use other features which are present in your destination version.
- If you are uncertain, create a simple testcase in your current version and try to port or rewrite so
- it works in your destination TD version.
- Also query the community forum for hints. Some of us have already found issues and possible steps when encountering them while porting.
- Ask help or info on the community forum if you need it.
- When porting to TD5.1 or later version, be aware it is a UNICODE version. This means using features of external dll's need to be inspected.
- For instance, the dll may have two versions of a function. One for ANSI (used in pre TD 5.x versions) and one for UNICODE.
- It may be obligated to change the function declarations from the ANSI to the UNICODE version to work properly in TD 5.x or up.
- Gupta has created some white papers on this. Read them carefully !
- Also the forums have many hints on specific issues concerning usage of external functions.
Prepare and create porting environment
Before starting the port, beware to create a safe and adequate environment first.
- TD installations
- It is wise to install the newer TD version on a fresh Windows system which does not have other TD installations.
- Due to path settings it may happen your sources reference the wrong TD version.
- For instance, it may load the wrong VisualToolchest libraries (vt*.apl) or at runtime the wrong dll's.
- If you are not able to get a fresh workstation, be sure to remove all references to prior TD installations from the path (user and system path).
- Also make sure there are no path settings which points to TD sources or custom build dll's for your past projects.
- Try to avoid mixing of TD versions, it will become confusing and will create failure for your porting.
- You can test this by trying to execute a TD build application on the workstation. It will not start and give errors when there are
- no references to the TD runtime present.
- You could also try to load an apt/app there. When TD can not find custom build libraries or dll's, you can safely assume all references to older TD versions are gone.
- Install additional tooling
- Later on while porting you will use extra tooling to help you with the process.
- It is recommended to have at least these tools :
- Text Editor
- Any text editor will do, like notepad. There are more powerful tools like UltraEdit which gives better search and replace features.
- A nice free but powerful editor is Notepad++
- Spy tools
- To inspect which dll's are loaded and what all references are, you should use a spy tool.
- Using such a tool you can detect dll's loaded in your current application and point you to additional work while porting.
- For instance, you can see your application uses a custom dll which references the TD runtime library. Those dll's must be recompiled using the destination TD library.
- When testing the ported application it is needed to inspect the loaded dll's and see where they come from.
- It can hint you to custom dll's or third party components which must be addressed also while porting.
- A recommended free tool is DependencyWalker.
- Another free one is Process Explorer.
- Text search & replace
- To detect which items or settings are located within your sources, a text search tool can help.
- For instance, you can find a specific text like "vti42.dll" in several sources (app/app/apl) situated within a directory/folder.
- It is handy to get a list of all occurrences of dll's, includes, settings etc from all sources in one list.
- A nice free tool for this is Text Crawler.
- To be able to use this, all your sources must be saved as TEXT format as described in the previous paragraph.
- Backup your original sources
- DO MAKE A BACKUP FIRST. DO NOT PORT YOUR ORIGINAL SOURCES !!!!!
- To be sure not to loose your original sources, make a complete copy of all your apt/app/apl files.
(As example here, the procedure describes a port from TD 2000 to TD4.2. Replace in mind your actual situation environments)
You must be sure every file is saved in TEXT format. If it is not, open them all in the source TD version (eg TD2000) environment and save them "as text".
The first step is to copy all your sources and dependencies into one folder.
A sound way to port is a bottom-up procedure. This means you convert your sources beginning with the most low level library.
For instance, your have this structure :
Main.apt Includes: Base1.apl Includes: Base2.apl Base2.apl Includes: Base1.apl Base1.apl No includes
In this case, Base1.apl is the most low level library.
Open the library in your destination TD environment (eg TD 4.2) and immediately save it (overwrite).
At this point you do not need to compile/build. Only open and save action.
Be sure if you save the sources it will be saved again in TEXT format.
Repeat this until all sources are opened and saved as described up until you have opened/saved the main app/apt. To check if you have touched every file, you can use Windows Explorer to see the dates. They should all have a new date.
If you encounter errors wile opening files, ignore them at this point. This first step is only to convert the source into the new TD format.
When all files are touched, do a first check by opening the main app/apt to see if it loads without errors.
When you encounter an error indicating it can not find a library, make sure it is situated in the port folder along with the other files.
If it is there, open it separately into the new TD environment and save it as TEXT.
Now create a list of all used dll's in your sources. A quick way is to use a text search tool like described in the previous paragraph.
Here a sample when using WinGrep :
- Using Windows Explorer, right-click on the folder where your ported files are stored
- You will get a context menu. Select "Windows Grep" from the options.
- WinGrep loads and presents a search dialog
- Start the search by pressing OK. It will search all occurrences of ".dll" within all sources
- After search, select "View->All matches". It will present all occurrences in a list including the filename of the source
- Windows dll declaration
- These are default Windows dll's like user32.dll, kernel32.dll etc. These are probably ok and need no special treatment.
- Except when you port from 16 bits to 32 bit or from ANSI to UNICODE. When that is the case you will need to open all
- TD source files listed in WinGrep and inspect the function declarations.
- TD 5.x (UNICODE) : investigate if you need to change the function declaration from A to W version. Not all declarations need
- to be changed. It depends on the parameter declarations if TD 5.x can do an automatic conversion between ANSI and UNICODE.
- Search for more info on this on the Unify website to see if you need to change specific declarations.
- Third party dll declaration
- Same applies to these kinds of dll's. Check if you need to change declarations to 32 bit or UNICODE when needed.
- Custom dll build on TD C lib declaration
- These are the hardest to port. You will need to recompile the dll (eg in VisualStudio) using a changed reference to the TD runtime library.
- If you have such dll's you probably know what to do. If not, ask on the forum for help and info.
- TD runtime dll declaration
- If you encounter declarations for TD runtime dll's like visual toolchest dll's, you have two options :
- 1) Remove the declaration in the source file and include the appropriate VT library. You will have the default declarations then which is the most safe.
- 2) Change the dll name in the declaration. Open the source and change the dllname to the appropriate name used in the new TD environment, eg vt31.dll to vt42.dll
- DLL references in properties and other locations within your source
- Depending on the dll, change the name to the correct one (eg vt31.dll to vt42.dll) using a text editor.
Be sure you have checked all dll occurrences in all your source files and threat them accordingly.
There should be no old TD runtime dll references left and all custom dll's must be treated to get your application working.
Iterate the WinGrep step until you have touched all dll issues and corrected them.
If you use ActiveX/COM components in your application you might have to re-generate the AX libraries.
Depending on the version step (eg 3.0 -> 3.1) it is not needed to re-generate the ActiveX/COM library using the ActiveX explorer.
A step like 1.x to 3.x you definitely need to. It is sound to re-generate all ActiveX libraries for sure using your new TD environment.
While testing your ported application and you see issues in ActiveX, a re-generation could solve it.
Now it is time to open your sources and compile them. If all dependencies are corrected there should be no errors.
Best is bottom-up which means open and compile low level libraries first and get them compileable.
Repeat this and correct any found issues.
Finalizing and tweaking
At this point, you can do first runtime checks.
Load your main application and compile it. If you still find compile errors, you will need to zoom into the issue to see where the cause lies.
If parts do not compile, you may decide to temporarily comment it. Try to get most of your application compileable without errors.
Keep hard parts for later and focus on the main chunks.
When all compiles ok, try to do your first runs. Execute and see what issues arise.
Most of them will be caused by incorrect dll declarations. Pinpoint and fix them.
If you have too many issues at this point, try to split your application into testable parts. For instance, try do get specific functionality working
using small testcases. Get them working and increase the scope of the functionality step by step and solve issues along the way.
Do thorough runtime tests. The new TD environment may react differently or your previously build workarounds could fail.