 |
|
ASNA DataGate® Component Suite 5.0
Contents
This release contains changes that can potentially break existing programs written against a previous release of the DataGate Component Suite library, adbactvx.dll. These changes were required to facilitate future upgrades and add required functionality. The modifications are centered primarily to the PrintFileContent object and its default interface, IPrintFileContent.
If your DCS program fits all of the following criteria, you will need to at least rebuild it using the new type library before deploying the program with this new release.
1. Uses the PrintFileContent object for print file access.
2. “Early binding” or “vtable binding” programming language or COM support; for example C++ or Visual Basic 6 .EXE or component compilation. .NET Interop COM support uses early binding as well. AVR programs and scripted environments such as Active Server Pages use “late binding” and should not be affected.
If regeneration is necessary, follow these steps to make sure you pick up the changes in your program:
1. Register adbactvx.dll. This is normally done during the “setup” installation of DCS, but if you want to be sure, you can use the REGSVR32.EXE command. Click Start, Run, then enter REGSVR32.EXE <full path to adbactvx.dll here>. For example: regsvr32 "C:\Program Files\Common Files\ASNA Shared\adbactvx.dll"
2. Regenerate your program. Generally, this will involve recompiling or rebuilding into a binary format.
If your program does not use PrintFileContent or does not require early binding, then regeneration of the program should not be necessary.
If you are programming in a more strongly typed language such as C++ or C#, you may have a bit more work to do. In the new type library, IPrintFileContent no longer inherits from the IFileContent interface, as it did in the previous release. IPrintFileContent still contains all of the methods of IFileContent that are relevant to, and implemented for print files. But several methods that are irrelevant, such as SeekKey, etc., have been removed. This is significant if your vtable-based code expects IPrintFileContent pointers to also be usable as IFileContent pointers. If so, then you could get compilation errors when you rebuild. Unfortunately, in this case you will be forced to redesign your print file access logic.
Also of significance is the use of the Record.SetNew and Record.Add methods. Note that these methods have been changed to expect an IDispatch (Object in VB6) parameter rather than IFileContent. This is because these methods can now accept either an IFileContent or an IPrintFileContent parameter. This change shouldn’t have any effect on your C++ code that passes COM pointers to these methods, since IPrintFileContent and IFileContent both still derive from IDispatch. In C# however, Interop forces you to type cast an object reference to the required type in order to use it in a method call. Thus, your C# program may have code that looks like the following:
ADBAx.PrintFileContent printFile = new
ADBAx.PrintFileContentClass();
ADBAx.Record recHeader = new ADBAx.RecordClass();
. . . other code here to open the print file . . .
recHeader.SetNew((ADBAx.FileContent)printFile, "rptHeader");
. . . other code here to initialize record . . .
recHeader.Add ((ADBAx.FileContent)printFile);
Notice that in the recHeader.SetNew and recHeader.Add calls, the PrintFile object reference is being cast to a FileContent reference. Because of the way Interop exposes COM interfaces, this code will compile without errors with the new type library. However, at run time, the casts will fail, because IPrintFileContent references are no longer also IFileContent references. Simply removing the casts as below will allow the code to work with the new DCS release, because the methods now accept generic object references to PrintFileContent and FileContent objects.
. . . (other code here to open the print file) . . .
recHeader.SetNew(printFile, "rptHeader");
. . . (other code here to initialize record) . . .
recHeader.Add (printFile);
There is a file to assist you in properly installing/uninstalling DataGate Component Suite. The file is titled DCS_Installation_Notes.htm, and can be located in C:\Program Files\Common Files\ASNA Shared, or from the ASNA Suite CD Browser.
The first step to accessing and using the ASNA DataGate Component Suite after it has been installed, is to reference the type library, so you can "see" the objects it contains.
To Access the DCS Type Library
1. Set a reference to the DCS Type Library by using the application's References dialog box. To open the References dialog box, select References (which may reside on the Tools menu, Project menu, etc.
2. Select the reference titled "ASNA DataGate Component Suite Type Library" and select OK.
3. To view the objects within the Type Library, select the Object Browser menu option, which is typically from the View menu, or by pressing F2 or Ctrl+F2 (depending upon the application used).
4. Click on the arrow to the right of the listing of referenced Type Libraries for this project, and select ADBAX, which is strictly the namespace qualifier for the DCS Type Library.
Now all of the objects in the DCS type library will display for you to view.
A comprehensive help file is available to assist you in using DCS. The help file is a compiled HTML help file and is titled ADBAX.CHM.
The help file can be found in C:\Program Files\Common Files\ASNA Shared.
To open the help file, simply double-click the .CHM file. The help file functions as any HTMLHelp file, so you can resize the window, search/highlight text, set favorite topics, and access ASNAs web site, for example.
Examples and Sample Programs are available to assist you in using DCS. These examples include sample "programs" that were installed with DCS in which you can open in AVR or VB 6.0, or sub-sets of AVR and VB examples that can be accessed from within the DCS help file.
Accessing Sample Programs in AVR or VB:
Sample programs for both AVR 4.0 and VB 6.0 are included in C:\Program Files\ASNA\Examples\DCS50. There are 2 folders within \DCS50 called AVR40 and VB6.
\AVR40 - Contains sample programs written in AVR 4.0.
\VB6 - Contains sample programs written in VB 6.0.
To open a sample program, simply double-click on the Project extension in Windows explorer, or Open the desired example from within the AVR or VB IDE. Once the code window is opened, simply Copy (Ctrl+C) the desired code, then Paste (Ctrl+V) into your program.
Accessing Examples in the Help File:
To view a listing of the examples available, either:
1. Enter keywords in the index, such as Examples, Samples, AVR examples, VB Examples, etc.
2. Select the Examples and Sample Programs book from the Contents tab. There will be 2 additional books.
AVR - Contains all example programs written in AVR.
VB - Contains all example programs written in VB.
Once the desired help topic is opened, simply highlight the actual code, then either select Ctrl+C to copy, or right-click on the help topic, and select Copy from the drop-down menu. Then you can Paste (Ctrl+V) the selected code into your program.
Note that these examples are typically small examples to complete a particular task within a larger example, or sample program. Also, throughout various topics, you may notice examples. AVR example code will always have a "gray" background, and VB examples will have a "light yellow" background.
Please note that this information is subject to change.
Currently, DCS applications may
be deployed to target computers in two ways.
One way requires more effort from the system administrator, but offers
more security and a smaller binary file footprint on the target machine. Either way, the installation of the
application code is the responsibility of the programmer and system
administrator. The instructions here
only offer alternatives for installing the DCS run-time components.
Method 1: Install the DCS run-time components
The deployment method requiring the least effort is to simply install DCS using the Setup.exe installer used to install DCS for development. This is the least error-prone method to install the DCS run-time components, however, this will also install the components supporting application development, including Acceler8DB Engine and its associated database management tools.
The advantage of this method is
that if the application uses local databases, or uses Acceler8DB Database
Names, these can be set up during deployment with the ADB Engine tools (note
that Database Names can also be installed with DCS itself).
Method 2: Manually Copy and Register Run-time DLL Files
The alternative deployment method is to simply copy and manually register the DCS run-time DLL files on the target machine. These DLLs, adbcom.dll and adbactvx.dll, are usually found in the \Program Files\Common Files\ASNA Shared directory on the home drive of a machine on which the development Setup.exe installer has been run. These files can be copied to any directory on a target machine and registered with the Windows COM registration utility REGSVR32.EXE. For example, click Start, Run, and enter regsvr32.exe adbcom.dll. Repeat the process for the adbactvx.dll file.
This method does not install any ADB Engine components, so the DCS application must be written so as not to be dependent upon these. That is, the application should not reference ADB Database Names (unless it pre-installs them itself) or local machine databases. Also, this method should not be used if the application accesses Acceler8DB OLE print files.
For either deployment method, no license key installation is required, unless the DCS application is to be debugged or developed on the target machine. The DCS run-time license is enforced on machines used for development purposes.
DCS components may be accessed with the Microsoft .NET run-time environment through the so-called COM/ActiveX Interoperability Layer (or simply, Interop), a fundamental part of the .NET framework. Interop is a subsystem designed to allow access to traditional COM libraries such as DCS, using native .NET conventions and objects.
For the programmer, this means that DCS classes can be used in nearly the same manner as they are in ActiveX development environments. Interop is not able to hide all of the differences between COM and .NET however. The most obvious differences are in the way optional (or default-valued) parameters are handled, and in the way Variant values are wrapped by Interop.
Variant values are used extensively in DCS, due to their flexibility. Variants allow Visual Basic programmers and others to express DCS methods and properties in useful ways. In .NET however, Variants are not directly supported. Rather, Interop replaces the Variants in DCS methods and properties with values of type System.Object, a similar, all-encompassing class type. Values of type System.Object returned from DCS properties or methods can be assigned to variables of other types, just as the Variant values are assignable to other types in ActiveX environments. In C#, these assignments must take the form of a type cast assignment. In VB.NET, an explicit assignment to a variable of the particular type must be performed in order to use the value. This is unlike Visual Basic 6, where the VB run-time can often infer the usage of a Variant via late-binding techniques. In general, when dealing with Variants replaced with System.Objects in .NET, you should always try to assign the System.Object value to a variable of the target type before attempting to use the value, to avoid compilation and run-time errors.
.NET also has no provision for default or optional parameters as often provided by ActiveX libraries such as DCS. This omitted feature at first appears to be hidden by some languages such as VB.NET, which allows the programmer to use default method parameters. However, C# and other .NET languages do not provide this shelter, and all method parameters must be expressed explicitly. One DCS method affected by this is the FileContent class GetEmptyKey method, which may optionally be passed a string identifying the record format to use in generating the key. For single format files, a simple shorthand use of GetEmptyKey may omit the record format string, since there is only one format that can be used. But if this method is used in C#, the record format string must always be specified, or a compilation error will occur.
For more information on Interop, please consult the documentation provided in the .NET Framework SDK, Visual Studio .NET or the Microsoft Developer Network (MSDN).
|
11/15/2007
© 2007.
Amalgamated Software of
|