General Information

• I followed the directions on how to install and run the filter, so why won't it work?   In order for the Import Wizard to recognize a filter, the filter must have the proper CMA_Version number (12) and it must expose the required set of API functions, even those it doesn't use. If the Import Wizard doesn't recognize your import filter, try the following steps to isolate the problem.
  • Move the Aaxyz.dll to the location specified for SBCM filters. Create a zero length file called Sample.xyz extension in this location (the name can be anything, but the sample filter uses this name by default). Run the SBCM Start Wizard. If it finds a company called Sample, the SBCM is set up correctly.
    
    
  • If the previous step fails, SBCM is not set up correctly. Try reinstalling or repairing the Small Business Tools setup and then try the previous step again.
    
    
  • If the first step succeeds, the problem may be with the filter. The Import Wizard will only work with filters where CMA_Version = 12 and where all the API functions are exposed. (Nonessential functions must still be exposed but simply return False.) See the sample C++ source file (Aaxyz.cpp) for the minimum function set that all import filters must expose.
    
    
  • Files on which the filter DLL has dependencies may be missing. Use a dependency-checking tool on the filter DLL to ensure that all necessary files are available on the machine.

  You could also be experiencing problems due to one of the following:

  • If you are using DAO for your database access, the CdbDBEngine and CdbDatabase objects must be kept as private members in the Application class, as this code example demonstrates:

    class CFilterApp : public CWinApp
    {
    private:
     CdbDBEngine m_Engine;
     CdbDatabase m_Database;
    };
    

  • Duplicate records in any filter structure can cause filter errors or may be ignored entirely by the filter. To prevent such errors, make sure that records are unique based on the keys for each filter structure.
    
    
  • The Import Wizard requires that at least one account part and one account part value be defined, even when not importing Financial Manager information. The following sample code accomplishes this:

    //+----------------------------------------------------------------
    //
    // Function: CMA_LoadCompany
    //
    // Purpose:
    // CMA_LoadCompany loads CtrlInfo, AcctPart, and Entry.nCount
    // information from the company located in the file at
    // CtrlInfo.sDataPath.
    //
    // The accounting parts are hard-coded here (according to your
    // accounting system).
    // These will be used by the wizard to load your accounting
    // information, in CMA_LoacAcctPartCode();
    //
    // Arguments:
    // CtrlInfo [in] Used as a reference point to the 
    // current company and other settings
    // AcctPart [out] The structure is filled out by the
    // accounting application
    // Entry [out] The structure is filled out by the
    // accounting application
    //
    // Returns: TRUE if all the data about the company could be 
    // successfully loaded, otherwise FALSE
    //
    // Notes: 
    //
    DllExport BOOL CMA_LoadCompany(
     CMA_CTRLINFO& CtrlInfo,
     CMA_ACCTPART& AcctPart,
     CMA_JOURNALENTRY& Entry)
    {
     // Set AcctPart and Rollup fields, will be used by
     // CMA_LoadAcctPartCodes()
     //
     AcctPart.nPartCount = 1;
     AcctPart.nRollupCount = 0;
     AcctPart.nPartNumber = 0;
     // One and only one "Prime" account
     //
     strcpy(AcctPart.aPart[0].szPartName, TEXT("GLAccount"));
     strcpy(AcctPart.aPart[0].szPartType, TEXT("Prime"));
     AcctPart.aPart[0].nAccountType = ACCOUNTTYPE_NONE;
     AcctPart.aPart[0].nFieldSize = 4;
     AcctPart.aPart[0].szRollupOn[0] = NULL;
     strcpy(AcctPart.aPart[0].szBriefHeading, TEXT("G/L"));
     // Seed some value for the progress bar
     //
     Entry.lCount = 1;
     
     return TRUE;
    }
    //+----------------------------------------------------------------
    //
    // Function: CMA_LoadAcctPartCode
    //
    // Purpose: Load AcctPartCode, assigning AcctCats and Rollups 
    // where possible
    // 
    //
    // Arguments:
    // CtrlInfo [in] Used as a reference point to the 
    // current company and other settings
    // AcctPart [in] Used as a reference point to the 
    // previous account part
    // AcctPartCode [out] The structure is filled out by the
    // accounting application
    //
    // Returns: TRUE if another item is found, FALSE otherwise.
    //
    // Notes: 
    //
    DllExport BOOL CMA_LoadAcctPartCode(
     CMA_CTRLINFO& CtrlInfo,
     CMA_ACCTPART& AcctPart,
     CMA_ACCTPARTCODE& AcctPartCode)
    {
     // Clear the acctpart codes
     //
     for (INT i = 0; i < AcctPart.nPartCount; i++)
     {
     strcpy(AcctPartCode.aPartCode[i].szCode, " ");
     }
     if ((0 == AcctPart.nPartNumber))
     {
     // We are a standard account code
     //
     lstrcpyn(
     AcctPartCode.aPartCode[0].szCode,
     TEXT("1010"),
     MAX_CMA_PARTCODE__Code);
     // This is a cash account
     lstrcpyn(
     AcctPartCode.szDescription,
     TEXT("Temp"),
     MAX_CMA_PARTCODE__Code);
     // It is a cash account
     AcctPartCode.nAcctCat = 1010;
     // It is a debit account
     //
     lstrcpyn(
     AcctPartCode.szDrCr,
     TEXT("D"),
     MAX_CMA_ACCTPARTCODE__DrCr);
     // TRUE indicates that there is a valid account code being 
     // returned through the structures that we just assigned.
     //
     return TRUE;
     
     }
     return FALSE;
    }
    

• How can my accounting application determine where to install its filter?   To determine where to install your filter, use the path specified in the registry setting, "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\9.0\CMA\CmaPath." If this registry key does not exist, use the registry setting "HKEY_LOCAL_MACHINE\Software\Microsoft\Office\9.0\CMA\SBTBinDirPath" and append "\Sbt\SBCM" to this value to get the proper path in which to install the filter.

  This registry key location may change in future releases of the product and is only guaranteed to work with the Office 2000 release of the SBCM and SBFM.

• Why am I getting an access violation when calling MFC database classes or ODBC functions?   When you use MFC database classes or ODBC functions, make sure that the database objects are destroyed before the call to the destructor and that no ODBC APIs are called within the destructor. For any "termination" of the database objects, a different function can be written and called before the destructor. If you depend on the default destructor, make sure that you specifically destroy all database objects. If you have declared database objects as globals in the class, they will be "destroyed" when they go out of scope, which would be after the call to the destructor. It's better, therefore, to use pointers so that you can specifically allocate memory to them and later delete them, or "wrap" them all in a different class and then create and delete an instance of that class.

  Also keep in mind that if you are opening the database in CMA_FindFirstCompany, it will not be available in CMA_LoadCompany since the filter DLL is unloaded after CMA_FindClose. The second time the DLL is loaded (to import the data) CMA_FindFirstCompany is not called.

• Why can't I use SBFM to test my filter?   SBFM is only installed in the following regions: the United States, Canada, Australia, and the United Kingdom. Please change your regional setting to one of these settings in order to install SBFM.
  
  
• Can you elaborate more on the general approach of the SDK to repeated function calls?   The basic approach that this SDK uses for repeated calls to functions is that the function must return True until there are no more records to process, then it returns False. When a filter returns False from a function that is called repeatedly, the data in the structure is not used. Thus, the filter should return True for the function for the last record in the record set, then return False next time the function is called to indicate that there is no more data available for processing.
  
  
• How will the user select the source data to run a filter?   For information on how this works, see the section Verifying the Data File and Retrieving the Company Name. This information is available at any time to the user.
  
  
• How do I handle situations where there are multiple sources of data?   In some cases, the source application will contain information in several different files. Since the Import Wizard can only find one file related to a company's data, the import filter needs to handle any scenarios where additional files need to be located. This information can be stored in the registry or in a file that has pointers to the other data files. Another method is to pass more than one file extension in the szSearchFilename member of the CMA_PACKAGE structure. When calling the CMA_FindFirstCompany function, the Import Wizard will need to determine if the file found belongs to a data set already identified during the CMA_FindFirstCompany call or if it is another data set.
  
  
• If multiple company data files are contained in the same physical file, how do I tell which company was selected for import by the user?   In order to access a specific company in a database file containing multiple companies, szDataPath must contain an ID of some kind that can be parsed by the CMA_LoadCompany function (for example, "C:\Data\Abc.dat:FS", where FS identifies a particular company within C:\Data\Abc.dat). When CMA_LoadCompany is called, you can read the current value of szDataPath to determine which company was selected by the user.
  
  
• How does the filter process determine if the source application data file has been moved, and if so, what remedies are available?   The Import Wizard cannot determine if the source application data file has moved. If the user moves the data file and then runs an update on a data set that uses this file, the Import Wizard will return an error message stating that the source data file could not be found. If there are methodologies that can be used in your import filter to help locate a data file, these should be implemented where possible.
  
  
• Given the reliance on physical file names, how do I use DSNs as a connection source?   For some import filters, it makes sense to use ODBC or another method of database connection to perform the data reading that an import filter needs. However, this approach requires a DSN, which is not handled by the Import Wizard in this version. Either the import filter will already know what the DSN is named (if the source application uses a hard-coded DSN name) or there is a method to create a DSN from a physical file name. Please refer to MSDN for more details on how to create a DSN from a physical file name.

  During the CMA_Initialize call, open up a connection to your database and create some temporary files on the local hard drive representing the different companies for which you have data (in other words, CompanyA.dtf, CompanyB.dtf, and so forth). By doing this and making sure that CMA_PACKAGE.szSearchFileName matches the file name extension you use above, you will get a call on each file created above through CMA_FindFirstCompany. For each file, set CMA_CTRLINFO.szCompanyName and CMA_CTRLINFO.szDataPath. Make sure the value of szDataPath allows you to identify this data set if the user selects it. After the user selects a company for importing, CMA_CTRLINFO.szDataPath will contain the value the user selected. An alternate approach is to just look for the filter DLL. If the DLL is installed on the system, you should be able to find it yourself. When looking for companies, CMA_FindFirstCompany will return the first company; calls to CMA_FindNextCompany will return the list of other companies. The only drawback with this approach is that you can have two installations of the DLL on your machine, so make sure that you only return companies for one of your DLLs.

• How do I handle the scenario where I do not have information for a Boolean or amount data structure member?   For these scenarios, just use an empty field, as specified in the "String Requirements" section. The Import Wizard will convert this to the appropriate null value.
  
  
• Will the Import Wizard be supported in a scenario where Office is installed on a server and run locally?   For this version, this scenario is not supported by SBCM. Therefore, the filter writer does not need to address this in this version. However, the filter should be written so that this support may be enabled in the future.
  
  
• What if my filter requires a local installation of the source application?   During the CMA_FindFirstCompany call, if you can determine that there is valid accounting data on the machine but no instance of the source application, you should display a dialog prompting the user to install the source application. If the filter cannot determine whether there is an instance of the source application, or if it cannot prompt the user to install the source application, CMA_FindFirstCompany should return False so that the data file doesn't appear as an option in the New Database Wizard.
  
  
• How can a filter support multiple versions of the same accounting application?   When calling the CMA_LoadPackage function, the szName member of the CMA_PACKAGE structure contains the name of the accounting application that is displayed when a data file is found. If your filter works with multiple versions of the accounting application, you must either make this definition generic for all versions or create separate API calls for each version that the filter DLL supports.
  
  
• How should I handle any dialog boxes that a filter needs to display?   The filter should use the hwndParent value in CMA_CTRLINFO for the handle of any dialog boxes that it displays. This will ensure that filter dialogs are modal with respect to the New Database Wizard.
  
  
• How many files should be required by the filter?   The filter should ideally include only one file for an import filter. However, there are cases in which it makes sense to use resource files that are already installed by your source application. In these cases, you can assume that the source application will already be installed for the filter process to work.
  
  
• How should I set the code-alignment property for my project?   When setting your code-generation property for your project, set the Alignment property to 1 byte (the default for some development platforms is 8 bytes). This helps ensure that the filter code will run smoothly.
  
  
• Must the import filter be developed in Visual C++?   Since the Import Wizard is written in C++ with straight APIs, we recommend that Microsoft Visual C++ be used for filter development. You can mimic APIs by using other languages such as Delphi or Pascal. Documentation on how to do this can be found in various publications or on the Internet. Microsoft does not have in-house expertise on developing with these systems, however, and will only support development of import filters written in Microsoft Visual C++.
  
  
• What security considerations are important to keep in mind?   Due to the sensitive nature of accounting information, all filters should respect the security that is set by the user on their accounting data. When it is called to begin the filtering process on a data set, the filter should first determine whether the data is password-protected. If it is, the filter must then make sure that the user running the filter has adequate security permissions to extract the data from the accounting application. There are various methods for doing this, such as displaying a simple password dialog box to prompt the user for a valid password, adding hooks to the security object contained within the accounting application to validate the user, or any other suitable method. All of these methods will ensure adequate security permissions by using the window handle passed in the function CMA_LoadCompany.

  For accounting applications that allow various permission levels and various levels of access to the accounting information, the filter should assume that any user running it has administrative-level permissions and access to all the data contained within the accounting application.

• How should my filter handle checking passwords and providing feedback to the user if a password is invalid?   If an incorrect password is given, the filter should give an appropriate message to the user. In addition, when checking passwords, make sure that the correct password followed by empty spaces is not accepted as a valid password.
  
  
• How will security be implemented on the database created by the Import Wizard?   Due to the sensitive nature of accounting information, all information that is imported via the Import Wizard will be secured by using Jet native security. During the import process, the user who is creating the SBCM database will be made the admin of the database and all other permissions will be revoked. This user can then assign database access permissions to other users. SBCM will contain three levels of security that a user can be assigned to:
  • Low – The user can only access organization and contact information.
    
    
  • Medium – The user will have the permissions assigned to the Low security group and will also have access to invoice and product information.
    
    
  • High – The user will have permissions for access to any information contained in the SBCM database.