Click above to get retro games delivered to your door ever month!

   Application Development
------------------------------------------------------------------------------

   When developing Advantage applications, there are many areas that can
   cause potential problems.  Several key issues are identified below.

   General
   *  A work area using the Advantage RDD can only use files that are
      on a file server on which the Advantage server is loaded/started.
      If you are trying to use a file that is on a local drive (fixed
      disk on your workstation or floppy) or on a server without the
      Advantage server loaded/started, your application will return an
      error. Move the files to the server where the Advantage server is
      loaded/started.

   *  The indexes opened in a work area must reside on the same server
      as the table. They can be in different directories or
      volumes, but they must be on the same file server.

   *  You may get an "Advantage Client Incompatible with Advantage Server"
      or "Advantage server not available" error when opening a table.
      This is due to running a previous version of an Advantage server with
      the new version of Advantage RDD. Verify the Advantage server version
      is the same or newer than the Advantage RDD version.

   *  To maintain a connection between a client and the server, by default,
      the DOS client opens a zero-byte temporary file in the directory of
      the first file opened on the server. Thie file is deleted when the
      client disconnects. There will be a problem connecting to the server
      if the first file opened resides in a directory where the client has
      no READ rights, but the client does have READ rights for the
      particular table being opened. The path to the zero-byte
      temporary "semaphore connection" file is configurable in the Advantage
      Database Server. Change this path to a directory where all clients
      have READ privileges and reload the Advantage Database Server.

   *  Variables that are used in an index key expression, FOR expression,
      or WHILE expression must first be initialized to a value with the
      appropriate data type. An error "BASE/1003  Variable does not
      exist: cVar" called from dbSetIndex(0) or ordListAdd(0) may occur
      if the variable is not initialized.

   *  If Advantage creates an index on the server, an EVAL clause status
      bar may show the index as 100% done, but it may take several more
      seconds before the index is actually completed. The steps taken to
      create an index are:

           1. Extract a block of records.
           2. Sort that block of records.
           3. Repeat steps 1 and 2 until all records in the table
              have been extracted.
           4. Once all records have been extracted and sorted, write
              the index pages.

      When using the EVAL clause, the percentage of indexing done is
      based solely upon how many records have been extracted from the
      table. Thus, the time spent performing the first three
      steps of index creation is the only time reflected in an EVAL
      clause status bar.

      With CA-Clipper, the key extraction and sorting process is very
      slow relative to the writing of the index pages. Nearly the
      entire creation of the index is spent extracting and sorting
      keys. Because of this, the EVAL clause status bar will
      accurately reflect the percentage of index creation that has
      been performed.

      Advantage, on the other hand, extracts index keys very quickly.
      Since key extraction is done more efficiently, the time needed
      to write the index pages is about the same as the time needed
      to extract and sort index keys. Because the EVAL clause
      percentage of indexing done is based solely upon the time used
      to extract and sort records, a UDF status bar may show an
      Advantage index creation as being 100% done when in actuality
      it is only partially completed. On the same note, if the EVAL
      UDF returns an .F. to abort an index creation, it can only be
      aborted during the extraction and sorting phase of the index
      creation.


   Linking
   *  If both Advantage RDDs (DBFNTXAX and DBFCDXAX) are being linked
      into an application, a warning or error about a multiple definition
      of the symbol "_AXDEF_RDDNAME" may occur. This warning can be
      ignored.

   *  When using RTLink with the link script provided, you may receive
      warnings that RTLink attempted to overlay modules which were not
      referenced.  The warnings are generated because the link script
      lists ALL modules that can be overlaid, and some are not being
      referenced by the application.  These warnings can be ignored.

   *  International (localized) version only: If the error "unresolved
      external _dcmp" occurs during linking, it is probably because you
      have a U.S. version of CA-Clipper 5.2, and are linking with the
      International version of the Advantage RDD. To resolve this issue:

      1.   Use a localized version of CA-Clipper (e.g. French, German,
           etc.) with the International version of the Advantage RDD.

      or,

      2.   Use the U.S. version of the Advantage RDD and the Advantage
           server with the U.S. character set.

      To change the Advantage RDD version, re-install the Advantage
      Database Server, choosing the correct character set, and re-install
      the Advantage RDDs, specifying the localized version, from the
      installation diskettes.

   *  Custom indexes are supported with the DBFCDXAX RDD for .cdx and
      .idx indexes only. The functions to add and remove keys from an
      customer index, AX_KeyAdd() and AX_KeyDrop(), are also only
      supported for the DBFCDXAX RDD. A 6035 error will occur if a
      custom index operation is attempted with the DBFNTXAX RDD.

   *  If an index does not appear to be built as fast as expected,
      verify that a value of zero is returned from a function call to
      AX_ExprError() after building the index. If AX_ExprError() returns
      a non-zero value, the index was unable to be built on the server,
      and was instead built by Advantage on the client.

   *  NETWARE ENVIRONMENTS ONLY:
      If you receive an "Invalid Connection" error, verify the server
      with the Advantage NLM loaded is one of the first eight servers to
      which the client is connected. The server with ADS.NLM loaded must
      be one of the first eight servers to which a client is connected.

   *  A warning about a multiple definition of the symbols "SET",
      "__SET", "__SETHANDLER" and "__SETSTRUCT" may occur when linking.
      This warning can be ignored. Advantage supplies its own "Set"
      routine so that the "Set" settings, such as SET DELETED, can be
      sent to the Advantage Expression Engine.


   Advantage TPS Applications

   *  If an application ends without a corresponding COMMIT TRANSACTION
      statement to a BEGIN TRANSACTION statement, the Advantage Database
      Server will perform an automatic rollback of all updates made since
      the BEGIN TRANSACTION statement. This situation should never be
      permitted to occur in an application.

   *  In order to use the commands and function BEGIN TRANSACTION, COMMIT
      TRANSACTION, ROLLBACK TRANSACTION, and AX_Transaction(), the current
      work area must be using a table opened with an Advantage RDD. If not,
      a 6034 error, "Advantage work area required for transaction", will
      result.

   *  If an application received a 6101 "Transaction command out of
      sequence" error, then the application contains a nested transaction.
      A BEGIN TRANSACTION command must be followed by either a COMMIT
      TRANSACTION or a ROLLBACK TRANSACTION before another BEGIN
      TRANSACTION can be issued.  Also, a COMMIT TRANSACTION or a ROLLBACK
      TRANSACTION cannot be issued without first issuing a successful
      BEGIN TRANSACTION.

   *  If an application received a 6102 error, "XXXXXX is illegal during a
      transaction", where XXXXXX is the illegal command, then the
      application issued an illegal command or function during a transaction.
      The following commands and their associated functions are illegal and
      will not be performed when used within a transaction.

       UNLOCK, AX_UnLock(), dbUnlock(), dbUnlockAll(), dbRUnlock()
       PACK, ZAP
       REINDEX, dbReindex()
       DELETE TAG, AX_KillTag(), ordDestroy()
       AX_DBFEncrypt(), AX_DBFDecrypt()
       AX_File2BLOB()
       AX_IsLocked()
       AX_CopyTo(), AX_AppendFrom()
       CLOSE, CLOSE INDEXES, AX_ClearOrder(), dbCloseArea(), dbClearIndex()

   Note:  A CLOSE command will not only cause an error, it will actually
   close the table and any open indexes in the work area and then rollback
   the current transaction.

   *  If an application received a 7001 "Out of memory" error, check to see
      if the Advantage error log, ADS_ERR.DBF, contains the OS error code
      "9032". If so, either: 1) Increase the number of TPS list elements
      allocated by the Advantage Database Server at load/start time using
      the Transaction List Elements setting in the configuration; or,
      2) Decrease the number of updates used within transactions.
      If this error occurs, contact Extended Systems Technical Support.
      Save the ADS_ERR.DBF along with the following information
      to give to Extended Systems: the Number of Connections setting, and
      the Transaction List Elements setting.

      NetWare Environments Only: If you are using the Advantage NLM,
      please also provide to Extended Systems Technical Support information
      regarding the Max Used Connections value (located on the Advantage
      NLM screen), and all three Max Used values located on the
      "TPS List Information" screen in the Advantage Management Utility.

   *  If a failure, such as a server disk write error, occurs on the network
      file server during a transaction rollback, a failed transaction will
      result (error code 9057). If the file server crashes while one or more
      applications are in the midst of a transaction, failed transaction(s)
      will also result. You may reload the Advantage Database Server to
      automatically cleanup the failed transaction. You may also create a
      CA-Clipper application to cleanup the transaction. See the function,
      AX_TPSCleanup(), to create a cleanup application.

   Error Object
   In most cases, run-time errors can be detected by your code.  When an
   error is encountered, an error message is generated and passed to an
   error object in your CA-Clipper error handler.  For advanced Advantage
   commands and functions, an error code is also accessible using
   AX_Error().  If you are using advanced features, check the AX_Error()
   error status before proceeeding in your application.

   If you are integrating the Advantage TPS to implement transactions, you
   may want to integrate the ROLLBACK TRANSACTION command into your error
   handler. Errors occurring within transactions may be easily managed with
   the error handler. When managing errors in your error handler, keep in
   mind the error may not have occurred within a transaction.

   If a run-time error occurs, identify the error class and specific
   message.  Advantage will use the instance variable, "OSCode", in the
   CA-Clipper error object.  You may see error codes in the OSCode field
   6xxx, 7xxx, 8xxx and 9xxx range.