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

Function:    NO_APPEND()

Purpose:     Network append blank function with specific error trapping

Syntax:      NO_APPEND( [ color [, msg1 [, msg2 [, msg3 ] ] ] ] )

Arguments:   color       - Optional character string color setting in
                           which to display error messages.  If omitted or
                           an invalid value is passed, the default color
                           is IF( ISCOLOR(), "W+/R", "N/W" )

             msg1        - Optional character string first line message to
                           appear in the error box if an error occurs.  If
                           omitted or an invalid parameter is passed, the
                           default messages shown below are used.

             msg2        - Optional character string second line message
                           to appear in the error box if an error occurs.
                           If omitted or an invalid parameter is passed,
                           the default messages shown below are used.

             msg3        - Optional character string third line message to
                           appear in the error box if an error occurs.  If
                           omitted or an invalid parameter is passed, the
                           default messages shown below are used.

Returns:     True if an APPEND BLANK operation is NOT successful.  A
             return value of False indicates a record was successfully
             appended.

Description: This function, if successful, will append a blank record to
             the currently selected database file.  NO_APPEND() is most
             commonly used in a network environment to provide run time
             recovery options from append failures because of file/record
             locking conflicts, or from disk failures.  It is simpler to
             use because it packages the APPEND BLANK command into a loop
             which will test for NETERR() and allow retry or abort.

Notes:       In a network environment NO_APPEND() abides by the same
             record and file lock logistics as APPEND BLANK.  If
             successful, a record lock is left in place on the newly
             appended record unless a file lock was previously in place,
             in which case the file lock is left intact.

             The NO_APPEND() return value is the reverse of True
             indicating success.  True indicates failure, False success.
             The advantage of this approach is apparent during coding
             because most often, specific branch action is taken if an
             append fails.  See the example for details.

             The default first, second, and third line messages that
             appear in the BOXASK() message box are as follows:

                  +------------------------------------------------+
                  |                                                |
                  |              Append record failed!             |
                  |     Another user must have this file locked    |
                  |           Do you want to re-try? (Y/n)         |
                  |                                                |
                  +------------------------------------------------+

             You should use the default messages unless you ensure that
             the message you give will let the user know they have the
             option to re-try the append operation.

             The default answer to the third line prompt is YES, retry.
             This will keep the append attempt in a loop.  The function
             used to get this response is BOXASK() and is set with a
             timeout value of 30 seconds.  If the user does not respond
             within this time, the function will timeout and attempt to do
             the append.  This allows an append error condition to
             automatically recover without user intervention (like in the
             middle of the night!)  If you program batch mode operations
             and must ensure that the program does not enter a loop, use
             the APPEND BLANK, command directly then test for NETERR().
             See the Clipper manual section on networking operations.

             If you want to skip the first color parameter and get at the
             following message parameters, as in all cases, pass a dummy
             parameter for the color.  Although the color parameter is
             character in type, a null dummy ("") will work fine since the
             parameter is tested with the TYPEC() function which not only
             verifies that it is a character type, but that it is not
             blank (as is a null).

Example:     *-- store empty field values for a new record
             MEMORIZE(.T.)

             *-- get the data
             @ 1,0 SAY "Enter full name" GET M->name
             @ 2,0 SAY "Enter birthdate" GET M->birthdate
             @ 3,0 SAY "Enter age      " GET M->age  PICTURE "##"
             *-- remember to always PICTURE numeric memory variables!
             READ

             *-- now add the new record and put in the data
             IF NO_APPEND()
                SAYINBOX( "R/W", "Record not saved!" )
             ELSE
                MREPLACE()
             ENDIF
             *-- now release the public variables!
             FORGET()

Source:      RL_NO_AP.PRG

See also:    OPENED(), NO_FLOCK(), NO_RLOCK(), TYPEC()