From 5514ca7b0df6c1fdde6b18b10e0affb73393acb6 Mon Sep 17 00:00:00 2001 From: Alejandro de Garate Date: Thu, 17 Jul 2003 21:41:36 +0000 Subject: [PATCH] Added MEMOREAD(), MEMOWRIT() documentation --- harbour/ChangeLog | 6 ++ harbour/doc/en/memo.txt | 151 +++++++++++++++++++++++++++++++++- harbour/doc/es/memo.txt | 174 +++++++++++++++++++++++++++++++++++++--- 3 files changed, 319 insertions(+), 12 deletions(-) diff --git a/harbour/ChangeLog b/harbour/ChangeLog index 45906618f3..44f57c3cdf 100644 --- a/harbour/ChangeLog +++ b/harbour/ChangeLog @@ -8,6 +8,12 @@ 2002-12-01 23:12 UTC+0100 Foo Bar */ +2003-07-17 17:43 UTC-0400 Alejandro de Garate + * doc/en/memo.txt + + Added MEMOREAD(), MEMOWRIT() documentation + * doc/es/memo.txt + + Added MEMOREAD(), MEMOWRIT() documentation + 2003-07-17 17:34 UTC-0400 Alejandro de Garate * source/rtl/memofile.c + Added an optional 3rd parameter to MEMOWRIT(), , to decide diff --git a/harbour/doc/en/memo.txt b/harbour/doc/en/memo.txt index dcd8dadfb7..2d59c247a5 100644 --- a/harbour/doc/en/memo.txt +++ b/harbour/doc/en/memo.txt @@ -10,6 +10,10 @@ * MEMOTRAN() documentation * HARDCR() documentation * + * Copyright 2003 Alejandro de Garate + * MEMOREAD() documentation + * MEMOWRIT() documentation + * * See doc/license.txt for licensing terms. * */ @@ -25,10 +29,10 @@ * MEMOTRAN( , , ) --> * $ARGUMENTS$ * is a string of chars to convert. - + * * is the character to replace hard returns with. If not * specified defaults to semicolon. - + * * is the character to replace soft returns with. If not * specified defaults to single space. * $RETURNS$ @@ -89,3 +93,146 @@ * MEMOTRAN(),STRTRAN() * $END$ */ + +/* $DOC$ + * $FUNCNAME$ + * MEMOREAD() + * $CATEGORY$ + * Memo Field + * $ONELINER$ + * Return the text file's contents as a character string + * $SYNTAX$ + * MEMOREAD( ) --> cString + * $ARGUMENTS$ + * 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 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 . + * It searches for in the current directory. + * If the file is not found, then MEMOREAD() searches in the DOS path. + * + * Over a network, MEMOREAD() attempts to open 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-Clipper 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( , , [] ) --> lSuccess + * $ARGUMENTS$ + * 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. + * + * Is the memo field or character string, to be write to + * . + * + * 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 to the + * current directory. If exists, it is overwritten. + * + * Note: + * There is a third parameter (optional), , (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 is set to .T. + * But, if 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-Clipper compliant. + * $PLATFORMS$ + * All + * $FILES$ + * Library is rtl + * $SEEALSO$ + * MEMOEDIT(),MEMOREAD() + * $END$ + */ + + + diff --git a/harbour/doc/es/memo.txt b/harbour/doc/es/memo.txt index 41dfe9b738..6438a602ea 100644 --- a/harbour/doc/es/memo.txt +++ b/harbour/doc/es/memo.txt @@ -6,8 +6,9 @@ * Las siguientes partes son derechos adquiridos de sus autores individuales. * www - http://www.harbour-project.org * - * Copyright 2000 Alejandro de G rate + * Copyright 2000-2003 Alejandro de G rate * Documentaci¢n en Espa¤ol de: MEMOTRAN(), HARDCR() + * MEMOREAD(), MEMOWRIT() * * Vea doc/license.txt por los t‚rminos de la licencia. * @@ -28,8 +29,9 @@ * es el car cter para reemplazar los retornos de carro "duro". * Si no es especificado por defecto es el punto y coma. * - * es el c racter para reemplazar los retornos de carro "blandos" - * Si no es especificado, por defecto es un espacio en blanco. + * es el c racter para reemplazar los retornos de carro + * "blandos". Si no es especificado, por defecto es un espacio + * en blanco. * $RETURNS$ * MEMOTRAN() retorna , la cadena transformada. * $DESCRIPTION$ @@ -37,7 +39,8 @@ * carro han sido convertidos a los caracteres especificados. * $EXAMPLES$ * * El siguiente ejemplo formatea un campo memo conteniendo un mensaje - * de error en una cadena adecuada para ser enviada a la funci¢n ALERT() + * de error en una cadena adecuada para ser enviada a la funci¢n + * ALERT() * * cMensaje = MEMOTRAN( Errores->MENSAJE ) * ALERT( cMensaje, aOpciones ) @@ -45,6 +48,8 @@ * R * $COMPLIANCE$ * Esta funci¢n es totalmente compatible con CA-Clipper. + * $PLATFORMS$ + * Todas * $FILES$ * La librer¡a asociada es rtl * $SEEALSO$ @@ -67,13 +72,13 @@ * $RETURNS$ * HARDCR() retorna , la cadena transformada. * $DESCRIPTION$ - * Esta funci¢n retorna una cadena/memo donde los caracteres de retorno de - * carro automaticos ¢ "blandos" ( CHR(141) ) son convertidos a caracteres - * de retorno de carro forzado ¢ "duro" CHR(13). + * Esta funci¢n retorna una cadena/memo donde los caracteres de retorno + * de carro automaticos ¢ "blandos" ( CHR(141) ) son convertidos a + * caracteres de retorno de carro forzado ¢ "duro" CHR(13). * $EXAMPLES$ * * El siguiente ejemplo asigna a una variable de cadena, el campo memo - * NOTAS existente en la base Clientes, transformado para mostrarlo por - * pantalla. + * NOTAS existente en la base Clientes, transformado para mostrarlo + * por pantalla. * cNotas = HARDCR( Clientes->NOTAS ) * ? cNotas * @@ -88,12 +93,161 @@ * R * $COMPLIANCE$ * Esta funci¢n es totalmente compatible con CA-Clipper. + * $PLATFORMS$ + * Todas * $FILES$ * La librer¡a asociada es rtl * $SEEALSO$ * MEMOTRAN(),STRTRAN() * $END$ - */ + */ + +/* $DOC$ + * $FUNCNAME$ + * MEMOREAD() + * $CATEGORY$ + * Campo Memo + * $ONELINER$ + * Retorna el contenido de un archivo como cadena de caracteres + * $SYNTAX$ + * MEMOREAD( ) --> + * $ARGUMENTS$ + * Nombre del archivo a leer. Debe incluir la extensi¢n. + * Si el archivo se encuentra en otro subdirectorio, se + * debe incluir el path. + * $RETURNS$ + * Retorna el contenido de un archivo de texto como una cadena de + * caracteres . + * El tama¤o m ximo del archivo, que puede ser le¡do, es el mismo que + * el tama¤o m ximo de una cadena de caracteres (m s de 2 Mb). Harbour + * no tiene el l¡mite de 64 Kb como en Clipper. + * Si no puede ser encontrado o le¡do, la funci¢n retorna + * una cadena de caracteres, vacia (""). + * $DESCRIPTION$ + * MEMOREAD() es una funci¢n que lee el contenido de un archivo de texto + * (hasta ahora) desde un archivo en disco (floppy, HD, CD-ROM, etc.) + * De esa forma Ud. puede manipular el contenido como cualquier cadena + * de caracteres ¢ asignarlo a un campo memo para ser guardado en una + * base de datos. + * + * La funci¢n MEMOREAD() es usada junto con MEMOWRIT() y MEMOEDIT() + * para obtener de disco, texto de diferentes fuentes y que podr¡a ser + * objeto de edici¢n, b£squeda, reemplazo, visualizaci¢n, etc. y luego + * ser escrito a la base de datos. + * + * Es usada para importar datos desde otras fuentes a la base de datos. + * + * Nota: + * MEMOREAD() no usa los seteos SET DEFAULT y SET PATH para buscar por + * . + * Esta funci¢n busca por en el directorio actual. + * Si el archivo no se encuentra, entonces MEMOREAD() busca en el path + * del D.O.S. + * + * Sobre un entorno de red, MEMOREAD() intenta abrir el archivo + * en modo de s¢lo-lectura y compartido. Si el archivo es + * usado en modo exclusivo (no compartido) por otro proceso o programa + * la funci¢n devolver  una cadena vacia (""). + * + * Es una de las funciones de Clipper m s £til, realmente lo hace f cil. + * $EXAMPLES$ + * * Este ejemplo usa MEMOREAD() para asignar el contenido de un + * archivo de texto a una variable para una b£squeda posterior. + * + * cFile := "account.prg" + * cString := MEMOREAD( cFile ) + * + * IF AT( "Melina", cString) == 0 // chequea el copyright + * MEMOWRIT( cFile, cCopyright + cString ) // si falta, ponerlo ! + * ENDIF + * + * $STATUS$ + * R + * $COMPLIANCE$ + * Esta funci¢n es totalmente compatible con CA-Clipper. + * $PLATFORMS$ + * Todas + * $FILES$ + * La librer¡a asociada es rtl + * $SEEALSO$ + * MEMOEDIT(),MEMOWRIT(),REPLACE + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * MEMOWRIT() + * $CATEGORY$ + * Campo Memo + * $ONELINER$ + * Escribe un campo memo ¢ una cadena a un archivo de texto en disco + * $SYNTAX$ + * MEMOWRIT( , , [] ) --> lExito + * $ARGUMENTS$ + * Nombre del archivo a leer. Debe incluir la extensi¢n. + * Si el archivo se encuentra en otro subdirectorio, se + * debe incluir el path. + * + * Es un campo memo o una cadena de caracteres, a ser + * escrita en . + * + * Es una variable l¢gica que determina si el car cter + * de fin de archivo - CHR(26) - se escribe a disco. + * Este par metro es opcional. Su valor por defecto es + * verdadero (.T.) + * $RETURNS$ + * La funci¢n devuelve verdadero (.T.) si la operacion de escritura fue + * exitosa, de otro modo, ‚sta devuelve falso (.F.). + * $DESCRIPTION$ + * Esta es una funci¢n que escribe un campo memo ¢ una cadena de + * caracteres a un archivo de texto en disco (floppy, HD, CD-ROM, etc.) + * Si Ud. no especifica un path, MEMOWRIT() escribe en el + * directorio actual. Si existe ‚ste ser  sobreescrito. + * + * Nota: + * Existe un tercer par metro opcional (que est  ausente + * en Clipper), el cual le permite al programador cambiar en tiempo de + * ejecuci¢n el comportamiento (por defecto) de escribir - siempre - + * el car cter de fin de archivo, CHR(26) como en Clipper. + * Si no existe un tercer parametro, nada cambia, EOF es escrito como + * en Clipper, lo mismo ocurre cuando es puesto en .T. + * Pero, si es puesto en .F., el car cter EOF no es + * escrito al final del archivo. + * + * La funci¢n MEMOWRIT() es usada junto con MEMOREAD() y MEMOEDIT() para + * grabar a disco texto de diferentes fuentes y que pudo haber sido + * objeto de edici¢n, b£squeda, reemplazo, visualizaci¢n, etc. + * + * Esta funci¢n es usada para exportar la base de datos a otro formato. + * + * Nota: + * MEMOWRIT() no usa el seteo de directorio SET DEFAULT. + * + * Es una de las funciones de Clipper m s £til, realmente lo hace f cil. + * $EXAMPLES$ + * * Este ejemplo usa MEMOWRIT() para escribir el contenido de una + * variable de caracteres a un archivo de texto + * + * cFile := "account.prg" + * cString := MEMOREAD( cFile ) + * + * IF AT( "Melina", cString) == 0 // chequea el copyright + * MEMOWRIT( cFile, cCopyright + cString ) // si falta, ponerlo ! + * ENDIF + * + * $STATUS$ + * R + * $COMPLIANCE$ + * Esta funci¢n es totalmente compatible con CA-Clipper. + * $PLATFORMS$ + * Todas + * $FILES$ + * La librer¡a asociada es rtl + * $SEEALSO$ + * MEMOEDIT(),MEMOREAD() + * $END$ + */ +