ODBCConn/es: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		La unidad ODBCConn implementa una conexión SQLdb con fuentes de datos ODBC.
2	2
3	3		## Descripción
4	4
5	5		### ODBC
6	6
7	7		ODBC (Open Database Connectivity) o conectividad abierta de base de datos es una tecnología que permite conectar a una gran variedad de bases de datos utilizando una sola API, en concreto la API ODBC.
8	8
9	9		Existen implementaciones ODBC para distintas plataformas estando disponibles los drivers para la mayoría de los sistemas de gestión de bases de datos actuales. La documentación oficial sobre ODBC se puede encontrar en la siguiente dirección:
10	10
11	11		[MSDN ODBC site](http://msdn.microsoft.com/library/default.asp?url=/library/en-us/odbc/htm/dasdkodbcoverview.asp).
12	12
13	13		### TODBCConnection
14	14
15	15		FreePascal se distribuye con las cabeceras (headers) ODBC; encontrándose en las unidades `odbcsql` y `odbcsqldyn`.
16	16
17	17		`TODBCConnection` es un descendiente de `TSQLConnection` que aporta un agradable envoltorio OOP para ODBC utilizando el framework SQLdb.
18	18
19	19		En Lazarus se puede encontrar el componente `TODBCConnection` en la solapa SQLdb. También se puede utilizar el componente `TODBCConnection` añadiendo `ODBCConn` en la claúsula uses.
20	20
21	21		Se han implementado las siguientes características:
22	22
23	23		- Ejecutar consultas (queries) y recabar cojuntos de resultados.
24	24		- La mayor parte de tipos de campos, incluyendo blobs.
25	25		- query parameters (tipos string (cadena) e integer (entero)).
26	26		- Preparando consultas (queries).
27	27		- UpdateIndexDefs (lo que permite utilizar ApplyUpdates); parche remitido a fpc-devel, May 2, 2007.
28	28
29	29		Otras implementaciones están pendientes y son:
30	30
31	31		- Soporte de transacción adecuada; actualmente cada conexión corresponde a una transacción.
32	32		- Algunos tipos de campo.
33	33		- SQL_TYPE_UTC* (están mencionados en la documentación sobre ODBC , pero parece que no se están utilizando en la implementación).
34	34		- SQL_INTERVAL_* (¿Que debería corresponder con TFieldType?).
35	35		- SQL_GUID (TGUIDField no había sido implementado hasta recientemente).
36	36
37	37		### ¿ Porque utilizar ODBC ?
38	38
39	39		FreePascal se distribuye con componentes para conectar a varias bases de datos tales como MySQL, PostGreSQL, Firebird, Oracle, etc. Para aquellas bases de datos que no figuran en la lista, tales como MS-Access, ODBC es una buena opción. Actualmente, el componente TODBCConnection está diseñado para sortear (circumvent) la estricta licencia de MySQL para aplicaciones que no sean GPL o que no cumplan con MySQL AB's [excepción FLOSS](http://www.mysql.com/company/legal/licensing/foss-exception.html).
40	40
41	41		## Installing ODBC and ODBC Drivers
42	42
43	43		Antes de poder conectar a una base de datos utilizando ODBC, es necesario instalar primero:
44	44
45	45		- Un gestor de drivers ODBC (Driver Manager).
46	46		- Un driver ODBC específico para la DBMS a la cual se va a conectar.
47	47
48	48		### The ODBC Driver Manager
49	49
50	50		#### Windows
51	51
52	52		Windows contiene un gestor de drivers ODBC que podemos utilizar para realizar configuraciones con cierta facilidad y que se puede encontrar en las siguientes ubicaciones dependiendo del sistema operativo:
53	53
54	54		- El elemento Orígenes de datos (ODBC) que se encuentra en Herramientas administrativas dentro del Panel de control (Win 2000, XP, Vista).
55	55		- El elemento Orígenes de datos (32-bit) que se encuentra en el Panel de control (Win 9x, ME).
56	56		- El elemento ODBC en el Control Panel (Win NT)
57	57
58	58		![](/wiki-images/3/39/WinXPODBCDataSourceAdministratorDrivers.png)
59	59
60	60		#### Unix / Linux
61	61
62	62		Dos gestores de drivers ODBC muy conocidos para plataformas de tipo UNIX son [unixODBC](http://www.unixodbc.org) y [iODBC](http://www.iodbc.org). T`ODBCConn` es conocido por funcionar con unixODBC; su compatibilidad con iODBC está todavía pendiente de verificación.
63	63
64	64		##### Debian
65	65
66	66		Para Debian se puede instalar el paquete unixodbc mediante los siguientes mandatos:
67	67
68		-	~~`aptitude install unixodbc`\~~
69		-	~~`aptitude install unixodbc-bin # si necesitas algunas utilidades GUI (Interface gráfica de usuario)`~~
	68	+	``` pascal
	69	+	aptitude install unixodbc
	70	+	aptitude install unixodbc-bin # si necesitas algunas utilidades GUI (Interface gráfica de usuario)
	71	+	```
70	72
71	73		La unidad `odbcsqldyn` , y por tanto `odbcconn`, buscarán un fichero llamado `libodbc.so`. No aceptará un fichero del estilo `libodbc.so.1` o `libodbc.so.1.0.0`. El paquete unixodbc de debian no crea un enlace simbólico (symlink) con el nombre `/usr/lib/libodbc.so`; por lo que el usuario deberá:
72	74
73	75		- Crear el enlace manualmente: `ln -s libodbc.so.1 /usr/lib/libodbc.so`, o bien
74	76		- Instalar el paquete unixodbc-dev, el cual si creará el enlace.
75	77
76	78		Si se tiene instalado el paquete unixodbc-bin entonces se puede arrancar el programa `ODBCConfig` para configurar los drivers ODBC y los DSN.
77	79
78	80		![](/wiki-images/b/bf/ODBCDataSourceAdministratorAbout.PNG)
79	81
80	82		##### Ubuntu
81	83
82	84		Para Ubuntu, seguir las instrucciones para Debian.
83	85
84	86		Nota: el paquete unixodbc-bin puede no estar disponible desde el repositorio por defecto de paquetes.
85	87
86	88		### ODBC Drivers
87	89
88	90		(esta información falta por completar)
89	91
90	92		## Conectando a una fuente de datos ODBC
91	93
92	94		Los parámetros para conectar a una fuente de datos ODBC se describen en una cadena de conexión. Se trata de una cadena del estilo `NAME=VALUE;NAME=VALUE`.
93	95
94	96		`TODBCConnection` aporta un envoltorio sobre esta cadena de conexión. Algunas de sus propiedades se mapean a pares de nombre/valor en la cadena de conexión, pudiéndose especificar parametros personalizados en la propiedad `Params` (la cual es `TStrings`).
95	97
96	98		### Cadena de conexión ODBC
97	99
98	100		Antes de pasar a los detalles de este envoltorio, se deben tener unos conocimientos básicos acerca de como se identifica una fuente de datos ODBC. Primero de todo, un gestor de drivers ODBC ofrece dos caminos para realizar la configuración de un conjunto de parámetros:
99	101
100	102		- DSN (DataSource Name): una fuente de datos que puede escogerse o bien para el sistema o para un usuario, identificado por un único nombre. Los DSN se pueden configurar utilizando el administrador de fuente de datos ODBC o bien editando manualmente el fichero (o registro) `odbc.ini`.
101	103		- Fichero DSN: un fichero que contiene parámetros de conexión. Un administrador de fuente de datos ODBC permite habitualmente crear un fichero DSN desde el entorno gráfico de usuario (GUI).
102	104
103	105		Los parámetros en un DSN o fichero DSN se pueden combinar siempre con parámetros adicionales en la cadena de conexión, por ejemplo para especificar una contraseña.
104	106
105	107		La especificación ODBC define unos cuantos parámetros que pueden utilizarse en la cadena de conexión:
106	108
107	109		- Dos parámetros especiales, `DSN` y `FILEDSN`, permiten seleccionar un conjunto de parámetros predefinidos, tal como se describe arriba.
108	110		- El `DRIVER` especifica que driver ODBC driver utilizar. Obviamente este es un parámetro muy importante.
109	111		- Los parámetros `UID` y `PWD` se utilizan para aportar el nombre de usuario (username) y la contraseña (password).
110	112
111	113		Todos los demás parámetros son dependientes del driver seleccionado.
112	114
113	115		Se debe revisar la documentación del driver específico para aprender más sobre los parámetros disponibles y sus nombres.
114	116
115	117		### Propiedades de TODBCConnection
116	118
117	119		La siguiente tabla describe el mapeo de las propiedades de `TODBCConnection` a las cadenas de parámetros de conexión ODBC:
118	120
119	121		\| Propiedad \| Tipo \| Cadenas de parámetros de conexión \|
120	122		\|----\|----\|----\|
121	123		\| `Driver` \| `string` \| `DRIVER` \|
122	124		\| `DatabaseName` \| `string` \| `DSN`, no para cosas como `DATABASENAME`, el cual no es parte del ODBC standar \|
123	125		\| `FileDSN` \| `string` \| `FILEDSN` \|
124	126		\| `Password` \| `string` \| `PWD` \|
125	127		\| `UserName` \| `string` \| `UID` \|
126	128		\| `HostName` \| `string` \| none; no existe parámetro correspondiente en el estandar ODBC \|
127	129		\| `Params` \| `TStrings` \| Utilizarlo para especificar parámetros personalizados. Cada elemento debe tener el formato `NAME=VALUE`. \|
128	130
129	131		Hay que fijarse en que `TODBCConnection` tendrá cuidado con los valores del parámetro escaping en la cedena de conexión (cuando se requiere).
130	132
131	133		La propiedad booleana `LoginPrompt` no está implementada todavía. Esto puede requerir encontrar el manejador (handle) correcto de ventana, por lo que un driver puede mostrar un diálogo en el GUI para especificar parámetros.
132	134
133	135		Tener en cuenta que esto no se controla mediante la cadena de conexión pero si por el último parámetro de la función de la API ODBC `SQLDriverConnect`.
134	136
135	137		### Ejemplos
136	138
137	139		En esta sección se muestran algunos ejemplos de conexión con ciertas DBMS utilizando su driver específico ODBC. La sintaxis utilizada en los ejemplo es como la de los ficheros *.lfm. Esto deberia permitir interpretarlos de una forma sencilla.
138	140
139	141		#### Conectando con MySQL
140	142
141	143		Para una referencia de los parámetros soportados por el driver MyODBC, ver:
142	144
143	145		[1](http://dev.mysql.com/doc/refman/5.0/en/myodbc-configuration-connection-parameters.html).
144	146
145	147		El nombre del driver difiere un poco dependiendo de la plataforma y versión de MyODBC; algunos ejemplos de esto son:
146	148
147		-	~~`Driver = 'MySQL' (Unix) `\~~
148		-	~~`Driver = 'MySQL ODBC 3.51 Driver' (Windows)`\~~
149		-	~~`Driver = 'MySQL Connector/ODBC v5' (Windows)`~~
	149	+	```text
	150	+	Driver = 'MySQL' (Unix)
	151	+	Driver = 'MySQL ODBC 3.51 Driver' (Windows)
	152	+	Driver = 'MySQL Connector/ODBC v5' (Windows)
	153	+	```
150	154
151	155		Otros parámetros:
152	156
153		-	~~`UserName = 'myUsername'`\~~
154		-	~~`Password = 'myPassword'`\~~
155		-	~~`Params.Strings = (`\~~
156		-	~~` 'SERVER=example.com',`\~~
157		-	~~` 'PORT=3306',`\~~
158		-	~~` 'DATABASE=myDatabase'`\~~
159		-	~~`)`~~
	157	+	```text
	158	+	UserName = 'myUsername'
	159	+	Password = 'myPassword'
	160	+	Params.Strings = (
	161	+	'SERVER=example.com',
	162	+	'PORT=3306',
	163	+	'DATABASE=myDatabase'
	164	+	)
	165	+	```
160	166
161	167		#### Conectando a MS Access
162	168
163	169		En Windows, puedes utilizar:
164	170
165		-	~~`Driver = 'Microsoft Access Driver (*.mdb)'`\~~
166		-	~~`Params.Strings = (`\~~
167		-	~~` 'DBQ=C:\trayecto\a\mi\basededatos.mdb'`\~~
168		-	~~`)`~~
	171	+	```text
	172	+	Driver = 'Microsoft Access Driver (*.mdb)'
	173	+	Params.Strings = (
	174	+	'DBQ=C:\trayecto\a\mi\basededatos.mdb'
	175	+	)
	176	+	```
169	177
170	178		Nota: El driver ODBC de MS-ACCESS parece no soportar la función API `SQLPrimaryKeys` API , por lo que `UpdateIndexDefs` dará fallo. Actualmente debes establecert `SQLQuery.ReadOnly:=true;` para evitar que se genere una excepción hasta que se añada código que testee por la disponibilidad de la función en el driver.
171	179
172	180		## Depurando ODBC
173	181
174	182		Existen varias facilidades en ODBC que ayudan en el depurado de una aplicación ODBC.
175	183
176	184		### Mensajes de error
177	185
178	186		Cada llamada a la API ODBC retorna un ćodigo de éxito; si se produce un error esto permite recabar más información realizando llamadas a `SQLGetDiagRec`. (En aras a la exhaustividad los campos están también disponibles cuando una llamada a la API retorna `SQL_SUCCES_WITH_INFO`.)
179	187
180	188		`TODBCConnection` chequea el código retornado por cada llamada ODBC y construye una `EODBCException`. El `mensaje` de esta excepción consta de:
181	189
182	190		- Un mensaje identificando que esta haciendo `TODBCConnection` cuando se produce el error.
183	191		- El código retornado por la llamada a la API ODBC (e.g. `SQL_ERROR`).
184	192		- Un número de campos de diagnóstico (obtenidos utilizando `SQLGetDiagRec`); cada campo consta de tres campos:
185	193		- Un código de error de 5 caracteres identificando el error.
186	194		- Un 'código nativo de error'.
187	195		- Un mensaje descriptivo del error.
188	196
189	197		Nota: si se obtiene un error del tipo 'Function sequence error' en la sección de finalización de la unidad `ODBCConn`, entonces probablemente consista en que no se han limpiado apropiadamente todas las consultas (queries) y conexiones (connections).
190	198
191	199		### Seguimiento o rastreo
192	200
193	201		La mayoría de los gestores de ODBC tienen una opción de seguimiento en la cual se genera un log de todas las llamadas a la API ODBC. Esto puede ser muy útil para el depurado de una aplicación ODBC. El interface gráfico de usuario (GUI) del administrador de bases de datos ODBC tanto en entornos Windows como UNIX tienen una solapa donde se puede configurar la opción de seguimiento. Por supuesto el log que genera es sobre todo útil para diseñadores que están familiarizados con la API ODBC, pero puede ayudar a identificar un problema puntual cuando es necesario también por parte de los usuarios. Además dicho log biene muy bien para enviarse como fichero anexo, como por ejemplo para dar más información al desarrollador de la aplicación cuando un usuario obtiene un error que no puede solucionar, pasando a formar parte de su listado de seguimiento de errores o bien para solicitar ayuda a terceros que de esta forma cuentan con más información para dar una posible solución más pormenorizada.
194	202
195	203		---
196	204		From the Free Pascal wiki, page "ODBCConn/es", as it stood on 2011-04-26 after a change by Aevora, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
197	205		Category: Castellano
198	206		Category: Español

Back to history