harbour-core/harbour/doc/en/memo.txt

/*
 * $Id$
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://www.harbour-project.org
 *
 * Copyright 1999 Jose Lalin <dezac@corevia.com>
 *    MEMOTRAN() documentation
 *    HARDCR() documentation
 *
 * Copyright 2003 Alejandro de Garate <alex_degarate@hotmail.com>
 *    MEMOREAD() documentation
 *    MEMOWRIT() documentation
 *
 * See doc/license.txt for licensing terms.
 *
 */

/*  $DOC$
 *  $FUNCNAME$
 *      MEMOTRAN()
 *  $CATEGORY$
 *      Strings
 *  $ONELINER$
 *      Converts hard and soft carriage returns within strings.
 *  $SYNTAX$
 *      MEMOTRAN( <cString>, <cHard>, <cSoft> ) --> <cConvertedString>
 *  $ARGUMENTS$
 *      <cString> is a string of chars to convert.
 *
 *      <cHard> is the character to replace hard returns with. If not
 *      specified defaults to semicolon.
 *
 *      <cSoft> is the character to replace soft returns with. If not
 *      specified defaults to single space.
 *  $RETURNS$
 *      <cConvertedString> Trasformed string.
 *  $DESCRIPTION$
 *      Returns a string/memo with carriage return chars converted to
 *      specified chars.
 *  $EXAMPLES$
 *      ? MEMOTRAN( DATA->CNOTES )
 *  </fixed>
 *  $TESTS$
 *      @ 1, 1 SAY MEMOTRAN( Data->CNOTES )
 *      will display converted string starting on row two, column two of the
 *      current device.
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      MEMOTRAN() is fully CA-Cl*pper compliant.
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      HARDCR(),STRTRAN()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      HARDCR()
 *  $CATEGORY$
 *      Strings
 *  $ONELINER$
 *      Replace all soft carriage returns with hard carriages returns.
 *  $SYNTAX$
 *      HARDCR( <cString> ) --> <cConvertedString>
 *  $ARGUMENTS$
 *      <cString> is a string of chars to convert.
 *  $RETURNS$
 *      <cConvertedString> Trasformed string.
 *  $DESCRIPTION$
 *      Returns a string/memo with soft carriage return chars converted to
 *      hard carriage return chars.
 *  $EXAMPLES$
 *      ? HARDCR( Data->CNOTES )
 *  </fixed>
 *  $TESTS$
 *      @ 1, 1 SAY HARDCR( Data->CNOTES )
 *      will display converted string starting on row two, column two of the
 *      current device.
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      HARDCR() is fully CA-Cl*pper compliant.
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      MEMOTRAN(),STRTRAN()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      MEMOREAD()
 *  $CATEGORY$
 *      Memo Field
 *  $ONELINER$
 *      Return the text file's contents as a character string
 *  $SYNTAX$
 *      MEMOREAD( <cFileName> ) --> cString
 *  $ARGUMENTS$
 *      <cFileName> is the filename to read from disk.
 *                  It must include the file extension. If file to be read
 *                  lives in another directory, you must include the path.
 *  $RETURNS$
 *      Returns the contents of a text file as a character string.
 *      The maximum size of the file that can be read is the same as the
 *      maximum size of a character string (more than 2 Mb). It has not the
 *      64 Kb limit as in Clipper.
 *      If <cFileName> cannot be found, nor read, function returns a null
 *      string ("").
 *  $DESCRIPTION$
 *      MEMOREAD() is a function that reads the content of a text file (till
 *      now) from disk (floppy, HD, CD-ROM, etc.) into a memory string.
 *      In that way you can manipulate as any character string or assigned
 *      to a memo field to be saved in a database.
 *
 *      MEMOREAD() function is used together with MEMOEDIT() and MEMOWRIT()
 *      to get from disk text from several sources that would be edited,
 *      searched, replaced, displayed, etc.
 *
 *      It is used to import data from other sources to our database.
 *
 *      Note:
 *      MEMOREAD() does not use the settings SET DEFAULT or SET PATH to
 *      search for <cFileName>.
 *      It searches for <cFileName> in the current directory.
 *      If the file is not found, then MEMOREAD() searches in the DOS path.
 *
 *      Over a network, MEMOREAD() attempts to open <cFileName> in read-only
 *      mode and shared.  If the file is used in mode exclusive by another
 *      process, the function will returns a null string ("").
 *
 *      Is one of the most useful Clipper functions!, it really makes simple
 *  $EXAMPLES$
 *      *  This example uses MEMOREAD() to assign the contents of a text
 *         file to a character variable for later search
 *
 *         cFile   := "account.prg"
 *         cString := MEMOREAD( cFile )
 *
 *         IF AT( "Melina", cString) == 0             // check for copyright
 *            MEMOWRIT( cFile, cCopyright + cString ) // if not, add it!
 *         ENDIF
 *
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      MEMOREAD() is fully CA-Cl*pper compliant.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      MEMOEDIT(),MEMOWRIT(),REPLACE
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      MEMOWRIT()
 *  $CATEGORY$
 *      Memo Field
 *  $ONELINER$
 *      Write a memo field or character string to a text file on disk
 *  $SYNTAX$
 *      MEMOWRIT( <cFileName>, <cString>, [<lWriteEof>] ) --> lSuccess
 *  $ARGUMENTS$
 *      <cFileName> is the filename to read from disk.
 *                  It must include the file extension. If file to be read
 *                  lives in another directory, you must include the path.
 *
 *      <cString>   Is the memo field or character string, to be write to
 *                  <cFile>.
 *
 *      <lWriteEof> Is a logic variable that settle if the "end of file"
 *                  character - CHR(26) - is written to disk.
 *                  This parameter is optional. By default is true (.T.)
 *  $RETURNS$
 *      Function returns true (.T.) if the writing operation was successful;
 *      otherwise, it returns false (.F.).
 *  $DESCRIPTION$
 *      This a function that writes a memo field or character string to a
 *      text file on disk (floppy, HD, CD-ROM, etc.)
 *      If you not specified a path, MEMOWRIT() writes <cFileName> to the
 *      current directory. If <cFileName> exists, it is overwritten.
 *
 *      Note:
 *      There is a third parameter (optional), <lWriteEof>, (not found in
 *      Clipper) which let to programmer change the default behavior of
 *      - allways - to write the EOF character, CHR(26) as in Clipper.
 *      If there is no third parameter, nothing change, EOF is written as
 *      in Clipper, the same occurs when <lWriteEof> is set to .T.
 *      But, if <lWriteEof> is set to .F., EOF char is Not written to the
 *      end of the file.
 *
 *      MEMOWRIT() function is used together with MEMOREAD() and MEMOEDIT()
 *      to save to disk text from several sources that was edited, searched,
 *      replaced, displayed, etc.
 *
 *      It is used to export the database to another format.
 *
 *      Note:
 *      MEMOWRIT() do not use the directory settings SET DEFAULT.
 *
 *      Is one of the most useful Clipper functions!, it really makes simple
 *  $EXAMPLES$
 *      *  This example uses MEMOWRIT() to write the contents of a character
 *         variable to a text file.
 *
 *         cFile   := "account.prg"
 *         cString := MEMOREAD( cFile )
 *
 *         IF AT( "Melina", cString) == 0             // check for copyright
 *            MEMOWRIT( cFile, cCopyright + cString ) // if not, add it!
 *         ENDIF
 *
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      MEMOWRIT() is fully CA-Cl*pper compliant.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      MEMOEDIT(),MEMOREAD()
 *  $END$
 */