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( )
La
siguiente es la descripción detallada de las funciones que permiten acceder y
procesar archivos ASCII delimitados.
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.
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.
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.
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.
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.
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).
La
siguiente es la descripción detallada de las funciones que permiten grabar
archivos ASCII delimitados.
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.
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.
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.
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.
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.
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).
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( )
