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

Function:    CATF()

Purpose:     Copy array values to database fields (Copy Array To Fields)

Syntax:      CATF( array [, memcopies [, first [, last ]]] )

Arguments:   array       - Array of values to copy into database fields.

             memcopies   - Optional logical flag to copy array values to
                           existing public memory variables with the same
                           names as database fields.

             first       - Optional numeric value indicating the first
                           field in the database to be copied.  If not
                           specified the default is field #1.

             last        - Optional numeric value indicating the last
                           field in the database to be copied.  If not
                           specified the default is FCOUNT().

Returns:     True if all elements copied successfully.

Description: CATF() is a function to copy values of each array element in
             the specified array to the corresponding ordinal field in the
             current record of the currently selected database, optionally
             specifying to copy these array values to memory variable
             copies rather than to the actual database fields.

             This function is useful for stacking database record data
             into and out of arrays.  The companion function is CFTA() to
             copy fields to arrays, and the MEMORIZE() - MREPLACE() -
             FORGET() team of functions.  Typically a database's record
             contents are placed in PUBLIC variables with MEMORIZE(),
             edited, then saved back to the database with MREPLACE(), then
             released with the FORGET() function.  CATF() and CFTA() let
             you temporarily hold and stack these field values into arrays
             which can be later retrieved, or copied (saved) into the
             database, or another database with the same structure.  This
             forms a nice set of functions for simply manipulating data
             among numbers of databases that share the same structure.

Notes:       Assumes that ARRAY has at least FCOUNT() elements and that
             the array element positions match up with the database field
             numbers and also that the data type in each array element
             MATCHES the data type of the corresponding database record.
             This also assumes that if the database fields are being
             REPLACEd that any necessary file or record locks are in
             place.

             The database whose structure defines the fields being
             replaced MUST be currently selected since CATF() uses the
             field definitions from the currently selected database for
             its operations.

Example:     *-- swap data between record #1 and record #2 in a database
             DECLARE rec1[FCOUNT()], rec2[FCOUNT()]

             GOTO 1               && record #1
             CFTA(rec1)           && copy field values to rec1 array
             GOTO 2               && record #2
             CFTA(rec2)           && copy field values to rec2 array
             CATF(rec1)           && shove in record #1's field values
             GOTO 1               && back to record #1
             CATF(rec2)           && copy rec2 array field values in

Source:      RL_CATF.PRG

See also:    CFTA(), FORGET(), MEMORIZE(), MREPLACE()