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

  Sx_KeyAdd():

  Syntax:  Sx_KeyAdd( [nTagNo | cTagName [, nOrder | cIndexName],] [cValue] )

           nTagNo     = Position of tag within compound index file.  If
                         the file is an .IDX, use the file order number.
           cTagName   = Name of the tag to add the key to.  If the file is
                         an .IDX, use the name of the .IDX file.
           nOrder     = Position of index in list of indexes.
           cIndexName = Name of the index to add the key to.
           cValue     = A value to store in the index, when using a multi-
                        -key index.  NOTE: This parameter is only for
                        use on indexes created with the sxChar(), sxNum(),
                        sxDate(), or sxLog() functions.  It is not for
                        indexes created with the EMPTY clause.

  Returns:   Logical .T. if the key was successfully added, or .F. if an
             error occurred.

  Description:    This function is used to manually add a key to an index.
                  The current record in the current table is used to create
                  a new key entry for the current or specified index.  If
                  the current or specified index is a compound index (.CDX)
                  then the key is added to the active tag.

                  The new key is added to the index or tag only if:

                     * The record pointer is positioned on a record (not
                       EOF).
                     * The key does not already exist in the index/tag.
                     * The key satisfies the index/tag filter condition,
                       if any.

                  If no arguments are specified, then Sx_KeyAdd() uses the
                  current index file and current tag (if applicable).  If
                  only one argument is supplied, then nOrder/cIndexName is
                  assumed.  0 (zero) can be used for either nTagNo or nOrder
                  to specify the current tag or index, respectively.

                  This function can be used to "roll-your-own" index.  When
                  used in conjunction with Sx_KeyDrop(), this opens up a
                  world of new possibilities for customized indexes.

    NOTE:  This function is NOT supported under SIXNTX.


  PRACTICAL USES:

    Perhaps you are currently using a logical field in your database to
    indicate if a record should be included in a process (i.e., a report).
    You might have a hot-key set up in your browse that your user presses to
    toggle that record between TRUE and FALSE.  Instead of taking up one
    byte for each record in your database, you can use an RYO index.  When
    they hit that hot-key, you just Sx_KeyAdd() that record into the RYO
    index!  See the RYODEMO.PRG program for an example of this usage.

    Multi-Keyed RYO indexes can be used to:

      . SEEK on key words from a memo field
      . Create spell-checker dictionaries
      . Add an index key for every word in a field
      . Store record data directly in the index file instead of in the DBF
      . Create context-sensitive help systems


  Example:

    #include "SIXCDX.CH"

    // Create a standard Roll-Your-Own (RYO) Index

    USE test VIA "SIXCDX"               // Open database
    INDEX ON last TO last EMPTY         // Create EMPTY index file
    GOTO 10                             // Select a record
    Sx_KeyAdd()                         // Add a key for this record
    ? Sx_KeyData()                      // Displays key value for this rec
    ? Sx_KeyCount()                     // Display number of keys in index

    // Create a Multi-Keyed, Free-Format RYO Index

    INDEX ON sxChar(12) TO phones       // Create empty index file
    GOTO 100                            // Select a record
    Sx_KeyAdd( 0,0,"213-555-1212" )     // Add one phone number for this rec
    Sx_KeyAdd( 0,0,"213-555-9999" )     // Add another to the same record
    Sx_KeyAdd( 0,0,"310-222-9876" )     // And yet another phone number!
    ? Sx_KeyCount()                     // Display number of keys in index

    // Now display all phone numbers for this record
    IF Sx_FindRec( 100, .F. )           // Find first key for this record
      ? Sx_KeyData()                    // Display first phone number
      DO WHILE Sx_FindRec( 100, .T. )   // Find any other keys for this rec
        ? Sx_KeyData()                  // Display other phone numbers
      ENDDO
    ENDIF


  NOTE: See the MULTIKEY.PRG and HYPER.PRG programs for some more examples
        of using Sx_KeyAdd() with Multi-Keyed RYO indexes.