jueves, 28 de febrero de 2013

Funciones de Texto - Genexus

Archivos ASCII Delimitados

Los archivos ASCII Delimitados son archivos de texto (modificables con prácticamente cualquier editor de textos) comunmente utilizados para transferir información entre diferentes aplicaciones.

Este tipo de archivos puede ser creado con cualquier DBMS (Oracle, SQL Server, FoxPro, etc.) y presenta las siguientes características:

a.     Cada línea del archivo representa una fila (o registro)
b.     Los campos de cada línea están separados por algún delimitador
c.     Los campos alfanuméricos (Character o Varchar en GeneXus) pueden estar o no delimitados por comillas (“).
d.     Los campos numéricos no contienen comas separadoras de miles y, el separador de decimales es el punto.

El siguiente, es un ejemplo de un archivo delimitado generado a partir de una tabla con los campos CodCli, NomCli, CedCli, NacCli:

1,"Martín Flores",1335789,1960-01-10
2,"Josefina Fernández",3254469,1991-10-12
3,"Alberto Sarmiento",2546689,1987-11-17
4,"Ignacio Martínez",526866,1989-12-11
5,"Manuel González",1523458,1959-07-15
6,"Dalmiro Schmit",2743357,1961-12-09
7,"Juan Beltrán",455310,1950-10-12

Con GeneXus es posible leer este tipo de archivos. Para ello se proveen un conjunto de funciones que permiten abrir el archivo, leer cada registro, copiar el contenido de cada campo a variables o atributos de GeneXus y cerrar el archivo. Por ejemplo, para leer el archivo del ejemplo, el código sería semejante al siguiente:

&i = dfropen( "clients.txt", 80, “,”)
do while dfrnext( ) = 0
    &i = dfrgnum( &CliCod)
    &i = dfrgtxt( &CliNom )
    &i = dfrgnum( &CliCId )
    &i = dfrgdate( &CliFecNac, “ymd”, “-“ )
enddo
&i = dfrclose( )

Como se ve en el ejemplo, no existe un esquema de descripción del registro (orden de los campos) del archivo ASCII delimitado. El orden de los campos está dado por la secuencia en que se llaman a las funciones dbrgnum, dbrgtxt o dbrgdate. Si la secuencia fuera incorrecta, los resultados son impredecibles.

También es posible grabar registros. Esto se realiza en forma análoga a la lectura, mediante el uso de funciones. Por ejemplo, para grabar el archivo del ejemplo anterior, el código GeneXus sería el siguiente:


&i = dfwopen( "clients.txt", ",", '"')
for each
     defined by CliNom
&i = dfwpnum( CliCod)
&i = dfwptxt( CliNom )
&i = dfwpnum( CliCId )
&i = dfwpdate( &CliFecNac, “ymd”, “-“ )
&I = dfwnext()
      endfor
&i = dfwclose( )

Lectura de archivos ASCII delimitados

La siguiente es la descripción detallada de las funciones que permiten acceder y procesar archivos ASCII delimitados.

dfropen
Abre un archivo de texto para su procesamiento. Es la primera función que hay que llamar para comenzar a leer un archivo de texto.

Sintáxis:
dfropen( [, [,  [, ]]])

Parámetros:

puede ser un atributo, variable o constante de tipo char. Su valor será considerado como el nombre del archivo a procesar. Puede o no contener especificaciones de directorio. Si no las tiene, será buscado en el directorio corriente.

puede ser un atributo, variable o constante de tipo numérico, opcional, que indica el tamaño máximo, en cantidad de caracteres, del registro a leer.  Véase que los archivos ASCII delimitados tienen registros (líneas) de largo variable. Si se especifica, el valor debe corresponder a la cantidad máxima de caracteres que puede tener una línea. El valor por defecto es 1024.

puede ser un atributo, variable o constante de tipo character, opcional, que indica cual es el caracter delimitador entre campos. Si se quiere especificar el caracter de tabulación como separador, el valor de este parámetro debe ser el string “\t”.

puede ser un atributo, variable o constante de tipo character, opcional, que indica cual es el caracter delimitador de los campos strings. Sólo el primer carácter del valor del parámetro es considerado. Su valor, puede ser cualquier carácter que no aparezca en los textos. Su valor por defecto es el “ (comillas).

Retorno:
Esta función puede retornar alguno de los siguientes valores:

0       Operación satisfactoria. El archivo fue abierto.
-1       Secuencia incorrecta. Ocurre cuando se llama más de una vez a esta función sin haber llamado antes a la función dfrclose. Si está activado el trace, se verá el mensaje ADF0005 indicando este error.
-2   Error de apertura. Ocurre cuando el archivo identificado por no ha podido abrirse. La causa puede ser identificada claramente habilitando el trace y buscando el mensaje con código ADF0001. Lo más común es que el archivo no exista.
-8       Memoria insuficiente. Ocurre cuando no es posible reservar un buffer de bytes.  Si está activado el trace, se verá el mensaje ADF0007 indicando este error.
dfrnext
Lee el siguiente registro (línea) del archivo de texto delimitado.

Sintáxis:
dfrnext()

Parámetros:
No tiene

Retorno:
Esta función puede retornar alguno de los siguientes valores:

0       Operación satisfactoria. El registro fue leído.
-1       Secuencia incorrecta. Ocurre cuando se llama a esta función antes de llamar a la función dfropen o la llamada a dfropen retornó un valor diferente de cero (error).
-3   Error de lectura. Ocurre cuando se ha producido un error al leer una línea del archivo ASCII delimitado. La causa puede ser identificada claramente habilitando el trace y buscando el mensaje con código ADF0002.
-4   Fin de datos.
dfrgnum
Lee un campo de tipo numérico de la línea actual (leída por dfrnext).

Sintáxis:
dfrgnum( )

Parámetros:
puede ser un atributo o variable de tipo numérico. En él, se almacenará el valor leído.

Retorno:
Esta función puede retornar alguno de los siguientes valores:

0       Operación satisfactoria. El campo fue leído.
-1       Secuencia incorrecta. Ocurre cuando se llama a esta función antes de llamar a la función dfrnext o la última llamada a dfrnext retornó un valor diferente de cero (error). Si el trace está habilitado, se verá el mensaje ADF0004 o ADF0006.
-5       Formato incorrecto. El número en el campo no tiene una forma correcta. La causa más común es que el campo que se pretende leer sea de otro tipo (character, date, etc.). Si el trace está habilitado, se verá el mensaje ADF0008.
dfrgtxt
Lee un campo de tipo character de la línea actual (leída por dfrnext) .

Sintáxis:
dfrgtxt( [, ])

Parámetros:
puede ser un atributo o variable de tipo character o varchar. En él, se almacenará el valor leído.

puede ser un atributo, variable o constante de tipo numérico, opcional, que indica la cantidad máxima de caracteres a leer. Su valor, si se especifica, no debe exceder el tamaño definido para . En caso de omitirse, se asume el tamaño definido para el atributo o variable . Si éste parámetro excede el tamaño de los resultados son impredecibles.

Retorno:
Esta función puede retornar alguno de los siguientes valores:

0       Operación satisfactoria. El campo fue leído.
-1       Secuencia incorrecta. Ocurre cuando se llama a esta función antes de llamar a la función dfrnext o la última llamada a dfrnext retornó un valor diferente de cero (error). Si el trace está habilitado, se verá el mensaje ADF0004 o ADF0006.
-5       Formato incorrecto. El string en el campo no tiene una forma correcta. La causa más común es que el campo que se pretende leer sea de otro tipo (number, date, etc.). Si el trace está habilitado, se verá el mensaje ADF0009.
-6       Overflow. Este es un warning que indica que el largo del string en el registro es mayor al máximo especificado (o asumido) en el parámetro . El valor leído es truncado a caracteres.
dfrgdate
Lee un campo de tipo date de la línea actual (leída por dfrnext). El valor de fecha leído no es ajustado de acuerto con la preference Year Limit.

Sintáxis:
dfrgdate( [, [, ]])

Parámetros:
puede ser un atributo o variable de tipo date. En él, se almacenará el valor leído.

puede ser un atributo, variable o constante de tipo character, opcional, con, al menos, tres caracteres. Indica el formato que tiene la fecha en el campo a leer. Cada carácter del campo puede valer “y”, “m” o “d”. Su combinación genera el formato. Por ejemplo si el string contiene los caracteres “ymd” la fecha del campo a leer se asume (y valida) en formato Año, Mes, Día. Si, por el contrario el string contiene los caracteres “dmy”, la fecha del campo a leer se asume en formato Día, Mes, Año. Es importate notar que los caracteres deben estar en minúscula. El valor por defecto es “ymd”.

puede ser un atributo, variable o constante de tipo character, cuyo valor debe tener, al menos, un caracter. Indica cuál es el separador de los elementos de una fecha. Los valores comunmente utilizados son “/”, “-“ y “.”. El valor por defecto es “-”.

Retorno:
Esta función puede retornar alguno de los siguientes valores:

0       Operación satisfactoria. El campo fue leído.
-1       Secuencia incorrecta. Ocurre cuando se llama a esta función antes de llamar a la función dfrnext o la última llamada a dfrnext retornó un valor diferente de cero (error). Si el trace está habilitado, se verá el mensaje ADF0004 o ADF0006.
-5       Formato incorrecto. El string en el campo no tiene una forma correcta. La causa más común es que el campo que se pretende leer sea de otro tipo (number, date, etc.).
-7       Fecha no válida. El valor encontrado en el campo no corresponde a una fecha válida. Normalmente ocurre porque el formato () o el separador () no corresponde a los existentes en el archivo. Si el trace está habilitado, se verá el mensaje ADF0010.
-10El parámetro tiene un formato incorrecto. Si el trace está habilitado, se verá el mensaje ADF0012.
dfrclose
Cierra el archivo abierto por dfropen. Esta función debe ser llamada después de una llamada satisfactoria (sin error) a dfropen.

Sintáxis:
dfrclose()

Parámetros:
No tiene.

Retorno:
Esta función puede retornar alguno de los siguientes valores:

0       Operación satisfactoria. El archivo fue cerrado.
-1       Secuencia incorrecta. Ocurre cuando se llama a esta función antes de llamar a la función dfropen o la última llamada a dfropen retornó un valor diferente de cero (error).

Grabación de archivos ASCII delimitados

La siguiente es la descripción detallada de las funciones que permiten grabar archivos ASCII delimitados.

dfwopen
Abre un archivo de texto para su procesamiento. Es la primera función que hay que llamar para comenzar a leer un archivo de texto.

Sintáxis:
dfwopen( [,  [, ]]])

Parámetros:
puede ser un atributo, variable o constante de tipo char. Su valor será considerado como el nombre del archivo a procesar. Puede o no contener especificaciones de directorio. Si no las tiene, será creado en el directorio corriente.

puede ser un atributo, variable o constante de tipo character, opcional, que indica cual es el caracter delimitador entre campos. Si se quiere especificar el caracter de tabulación como separador, el valor de este parámetro debe ser el string “\t”.

puede ser un atributo, variable o constante de tipo character, opcional, que indica cual es el caracter delimitador de los campos strings. Sólo el primer carácter del valor del parámetro es considerado. Su valor, puede ser cualquier carácter que no aparezca en los textos. Su valor por defecto es el “ (comillas).

Retorno:
Esta función puede retornar alguno de los siguientes valores:

0       Operación satisfactoria. El archivo fue abierto.
-1       Secuencia incorrecta. Ocurre cuando se llama más de una vez a esta función sin haber llamado antes a la función dfwclose. Si está activado el trace, se verá el mensaje ADF0005 indicando este error.
-2   Error de apertura. Ocurre cuando el archivo identificado por no ha podido abrirse. La causa puede ser identificada claramente habilitando el trace y buscando el mensaje con código ADF0001. Lo más común es que el archivo no exista.
-8       Memoria insuficiente. Ocurre cuando no es posible reservar un buffer de bytes.  Si está activado el trace, se verá el mensaje ADF0007 indicando este error.
dfwnext
Graba el registro con los valores especificados por las llamadas anteriores a dfwptxt, dfwpnum, etc. en el archivo de texto delimitado.

Sintáxis:
dfwnext()

Parámetros:
No tiene

Retorno:
Esta función puede retornar alguno de los siguientes valores:

0       Operación satisfactoria. El registro fue leído.
-1       Secuencia incorrecta. Ocurre cuando se llama a esta función antes de llamar a la función dfwopen o la llamada a dfwopen retornó un valor diferente de cero (error).
-9   Error de grabación. Ocurre cuando se ha producido un error al grabar la línea en el archivo ASCII delimitado. La causa puede ser identificada claramente habilitando el trace y buscando el mensaje con código ADF0003.
dfwpnum
Graba un campo de tipo numérico en el registro actual del archivo ASCII delimitado.

Sintáxis:
dfwpnum( , )

Parámetros:
puede ser un atributo, variable o constante de tipo numérico. Su valor será el grabado en el campo correspondiente..

puede ser un atributo, variable o constante de tipo numérico, opcional, que indica la cantidad de decimales a especificar en el campo.

Retorno:
Esta función puede retornar alguno de los siguientes valores:

0       Operación satisfactoria. El campo fue grabado.
-1       Secuencia incorrecta. Ocurre cuando se llama a esta función antes de llamar a la función dfwopen o la última llamada a dfwopen retornó un valor diferente de cero (error). Si el trace está habilitado, se verá el mensaje ADF0004.
dfwptxt
Graba un campo de tipo character en el registro actual del archivo ASCII delimitado.

Sintáxis:
dfwptxt( [, ])

Parámetros:
puede ser un atributo, variable o constante de tipo character. Su valor será el grabado en el campo correspondiente..

puede ser un atributo, variable o constante de tipo numérico, opcional, que indica la cantidad máxima de caracteres a grabar. En caso de omitirse, se asume el tamaño definido para el parámetro .

Retorno:
Esta función puede retornar alguno de los siguientes valores:

0       Operación satisfactoria. El campo fue grabado.
-1       Secuencia incorrecta. Ocurre cuando se llama a esta función antes de llamar a la función dfwopen o la última llamada a dfwopen retornó un valor diferente de cero (error). Si el trace está habilitado, se verá el mensaje ADF0004.
dfwpdate
Graba un campo de tipo date en el registro actual del archivo ASCII delimitado. Si tiene el valor nulo de GeneXus, se grabará la fecha "00/00/0000".

Sintáxis:
dfwpdate( [, [, ]])

Parámetros:
puede ser un atributo o variable de tipo date. En él, se almacenará el valor leído. No puede ser una constante.

puede ser un atributo, variable o constante de tipo character, opcional, con, al menos, tres caracteres. Indica el formato que tiene la fecha en el campo a grabar. Cada carácter del campo puede valer “y”, “m” o “d”. Su combinación genera el formato. Por ejemplo si el string contiene los caracteres “ymd” la fecha del campo a grabar se asume en formato Año, Mes, Día. Si, por el contrario el string contiene los caracteres “dmy”, la fecha del campo a leer se asume en formato Día, Mes, Año. Es importate notar que los caracteres deben estar en minúscula. El valor por defecto es “ymd”.

es un parámetro de tipo caracteres opcional con, al menos, un caracter. Indica cuál es el separador de los elementos de una fecha. Los valores comunmente utilizados son “/”, “-“ y “.”. El valor por defecto es “-”.

Retorno:
Esta función puede retornar alguno de los siguientes valores:

0       Operación satisfactoria. El campo fue grabado.
-1       Secuencia incorrecta. Ocurre cuando se llama a esta función antes de llamar a la función dfwopen o la última llamada a dfwopen retornó un valor diferente de cero (error). Si el trace está habilitado, se verá el mensaje ADF0004.
-5       Formato incorrecto. El string en el campo no tiene una forma correcta. La causa más común es que el campo que se pretende leer sea de otro tipo (number, date, etc.).
-10El parámetro tiene un formato incorrecto. Si el trace está habilitado, se verá el mensaje ADF0012.
dfwclose
Cierra el archivo abierto por dfwopen. Esta función debe ser llamada después de una llamada satisfactoria (sin error) a dfwopen.

Sintáxis:
dfwclose()

Parámetros:
No tiene.

Retorno:
Esta función puede retornar alguno de los siguientes valores:

0       Operación satisfactoria. El archivo fue cerrado.
-1       Secuencia incorrecta. Ocurre cuando se llama a esta función antes de llamar a la función dfwopen o la última llamada a dfwopen retornó un valor diferente de cero (error).

Consideraciones sobre los archivos ASCII delimitados

Sólo puede estar abierto un archivo ASCII delimitado en un momento específico. La función dfropen retornará un error si se la llama más de una vez sin haber llamado previamente a dfrclose.

Es posible ignorar los campos del final de un registro al llamar a dfrnext cuando queden campos por leer. No es posible ‘saltearse’ campos. Si se quiere leer el campo número 5 es necesario leer los 4 anteriores.

Es posible leer registros con diferentes formatos como en el siguiente ejemplo:

&i = dfropen( "invoices.txt", 80, “,”)
do while dfrnext( ) = 0
    &i = dfrgtxt( &RecType)
    if &RecType = “H”
       &i = dfrgnum( &InvNum )
       &i = dfrgdate( &InvDat, “ymd”, “/“)
       ...
    else
       &i = dfrgnum( &PrdNum )
       &i = dfrgnum( &InvQty)
       ...
    endif
enddo
&i = dfrclose( )