lf304, SoftwareDevelopment: La Interfaz de Programación de Aplicaciones -API- de MySQL

<-- | Hogar | Mapa | Indice | Busqueda

Este documento está disponible en los siguientes idiomas: English Castellano ChineseGB Deutsch Francais Nederlands Portugues Russian Turkce Polish

por Özcan Güngör
<ozcangungor(at)netscape.net>

Sobre el autor:
Uso Linux desde 1997. Libertad, flexibilidad y Código Abierto. Son las características que me gustan.

Traducido al español por:
Carlos González Pérez <charly(en)galpon.org>

Contenidos:

Introducción
Tipos de variables de MySQL C
Conectando a MySQL y haciendo una petición
Algunas Funciones Usuales
Lecturas recomendadas
Formulario de "talkback" para este artículo

La Interfaz de Programación de Aplicaciones -API- de MySQL

Resumen:

En este artículo, aprenderemos a usar el API (Interfaz de Programación de Aplicaciones) que viene con MySQL. Para poder entender este artículo, necesitas tener algunas nociones sobre:

Variables en C.
Funciones en C.
Punteros en C.

_________________ _________________ _________________

Introducción

Las APIs de C son distribuidas con el código fuente de MySQL e incluídas en la biblioteca mysqlclient. Se usan para conectar a una base de datos y ejecutar peticiones. Hay algunos ejemplos en el directorio de clientes del código fuente de MySQL.

Tipos de variables de MySQL C

Los siguientes tipos de variables están definidos en la biblioteca de MySQL. Necesitamos estas variables para poder usar las funciones de MySQL. Las variables son explicadas detalladamente pero los detalles no son realmente importantes para escribir código.

MYSQL
La siguiente estructura es la del manejador de comunicaciones que se usa para conectarse a una base de datos.

typedef struct st_mysql {
  NET           net;            /* Communication parameters */
  gptr          connector_fd;   /* ConnectorFd for SSL */
  char          *host,*user,*passwd,*unix_socket,
                *server_version,*host_info,*info,*db;
  unsigned int  port,client_flag,server_capabilities;
  unsigned int  protocol_version;
  unsigned int  field_count;
  unsigned int  server_status;
  unsigned long thread_id;      /* Id for connection in server */
  my_ulonglong affected_rows;
  my_ulonglong insert_id;       /* id if insert on table with NEXTNR */
  my_ulonglong extra_info;              /* Used by mysqlshow */
  unsigned long packet_length;
  enum mysql_status status;
  MYSQL_FIELD   *fields;
  MEM_ROOT      field_alloc;
  my_bool       free_me;        /* If free in mysql_close */
  my_bool       reconnect;      /* set to 1 if automatic reconnect */
  struct st_mysql_options options;
  char          scramble_buff[9];
  struct charset_info_st *charset;
  unsigned int  server_language;
} MYSQL;

MYSQL_RES

Esta estructura representa los resultados de una petición que devuelve columnas. Los datos devueltos se llaman conjunto de resultados.

typedef struct st_mysql_res {
  my_ulonglong row_count;
  unsigned int  field_count, current_field;
  MYSQL_FIELD   *fields;
  MYSQL_DATA    *data;
  MYSQL_ROWS    *data_cursor;
  MEM_ROOT      field_alloc;
  MYSQL_ROW     row;            /* If unbuffered read */
  MYSQL_ROW     current_row;    /* buffer to current row */
  unsigned long *lengths;       /* column lengths of current row */
  MYSQL         *handle;        /* for unbuffered reads */
  my_bool       eof;            /* Used my mysql_fetch_row */
} MYSQL_RES;

MYSQL_ROW

Esta estructura es un tipo libre de representación de datos en una columna. No puedes usarla como una cadena que finaliza con un caracter nulo, porque los datos de esta cadena pueden ser binarios y pueden incluir caracteres nulos.

typedef struct st_mysql_field {
  char *name;                   /* Name of column */
  char *table;                  /* Table of column if column was a field */
  char *def;                    /* Default value (set by mysql_list_fields) */
  enum enum_field_types type;   /* Type of field. Se mysql_com.h for types */
  unsigned int length;          /* Width of column */
  unsigned int max_length;      /* Max width of selected set */
  unsigned int flags;           /* Div flags */
  unsigned int decimals;        /* Number of decimals in field */
} MYSQL_FIELD;

my_ulonglong

El tipo usado para el número de columnas y para mysql_affected_rows(), mysql_num_rows(), y mysql_insert_id().
Este tipo provee un rango de 0 a 1.84e19. En algunos sistemas, al intentar escribir un valor del tipo my_ulonglong no funcionará. Para imprimir cada uno de estos valores, conviértelo a unsigned long y usa el formato %lu de printf. Ejemplo: printf(Number of rows: %lu\n", (unsigned long) mysql_num_rows(result));

typedef unsigned long my_ulonglong;

Conectando a MySQL y haciendo una petición

Ahora, asumiré que está instalado MySQL, y que has creado un usuario y una tabla en la base de datos. En caso de que haya algún problema, por favor consulta la página de MySQL.

Como he dicho antes las bibliotecas de MySQL están en la biblioteca mysqlclient. Así que cuando compilemos un programa MySQL es necesario añadir la opción -lmysqlclient al compilador. Las cabeceras (headers) de MySQL están en /usr/include/mysql (aunque esto depende de tu distribución Linux). La cabecera de tu programa tendrá algo parecido a esto:

#include <mysql/mysql.h>

Los tipos de variables y funciones de MySQL están incluidos en esta cabecera (header).

Ahora necesitamos crear la varibale que se usa para conectar a la base de datos. Se hace simplemente con:

MYSQL *mysql;

Antes de conectar a una base de datos, debemos llamar a la siguiente función para inicializar la variable mysql:

mysql_init(MYSQL *mysql)

Entonces la

MYSQL * STDCALL mysql_real_connect(MYSQL *mysql, 
                                   const char *host, 
                                   const char *user,
                                   const char *passwd,
                                   const char *db,
                                   unsigned int port,
                                   const char *unix_socket,
                                   unsigned int clientflag);

función es llamada para conectar a la base de datos host es el hostname (nombre del sistema) del servidor MySQL. user es el usuario con el cual queremos conectarnos. passwd es la contraseña. db es la base de datos a la que queremos conectarnos, port es el número de puerto TCP/IP del servidor MySQL. unix_socket es el tipo de conexión. clientflag es el flag que hace que MySQL corra como ODBC. En este artículo será 0. Esta función devuelve 0 cuando la conexión se establece.

Ahora podemos conectarnos a una base de datos y hacer una petición:

char *query;

Usando esta cadena podemos construir cualquier sentencia SQL y hacer la petición. La función que ejecuta la petición es:

int STDCALL mysql_real_query(MYSQL *mysql, 
                             const char *q,
                             unsigned int length);

mysql es la variable que hemos usado. q es la cadena de petición SQL. length es la longitud de la cadena. Si la petición se produce sin errores, la función devuelve 0.

Después de hacer una petición, necesitamos una variable en MYSQL_RES para poder disponer de los resultados de la petición. La siguiente línea crea esa variable:

MYSQL_RES *res;

Entonces

mysql_use_result(MYSQL *query)

La función se usa para leer los resultados.

Aunque podemos hacer peticiones fácilmente, necesitamos otras funciones para usar los resultados. La primera es:

MYSQL_ROW STDCALL mysql_fetch_row(MYSQL_RES *result);

Esta función transforma los resultados en columnas. Como te habrás dado cuenta, la función devuelve una variable del tipo de MYSQL_ROW. La siguiente línea crea dicha variable:

MYSQL_ROW row;

Como ya se ha explicado la variable row es un arreglo de cadenas. Esto quiere decir que row[0] es la primera columna de la primera fila y row[1] es la segunda columna de la primera fila. Cuando usamos mysql_fetch_row, la variable toma los datos de la siguiente fila del resultado. Cuando alcanzamos el final del resultado la función devuleve un valor negativo. Al final necesitamos cerrar la conexión:

mysql_close(MYSQL *mysql)

Algunas Funciones Usuales

Veamos cómo obtener el número de campos de una tabla. La siguiente función hace eso:

unsigned int STDCALL mysql_num_fields(MYSQL *mysql);

Esta función devuelve el número de campos de la tabla.

Para obtener el número de columnas del resultado de una petición usa:

my_ulonglong STDCALL mysql_num_rows(MYSQL_RES *res);

my_ulonglong STDCALL mysql_affected_rows(MYSQL *mysql);

Esta función se usa para conocer el número de columnas que son afectadas por peticiones de INSERT, DELETE o UPDATE. Nótese que la función devuelve el tipo my_ulonglong.

Finalmente algún código de ejemplo:

#include <mysql/mysql.h>
#include <stdio.h>

void main(){
   MYSQL *mysql;
   MYSQL_RES *res;
   MYSQL_ROW row;
   char *query;
   int t,r;

   mysql_init(mysql);
   if (!mysql_real_connect(mysql,"localhost","mysql",
        "mysql","deneme",0,NULL,0))
   {
       printf( "Error connectin ot database: %s\n",mysql_error(mysql));
   }
   else printf("Connected...\n");

   query="select * from Deneme";

   t=mysql_real_query(mysql,query,(unsigned int) strlen(query));
   if (t)
   {
      printf("Error making query: %s\n",
              mysql_error(mysql));
   }
   else printf("Query made...\n");
   res=mysql_use_result(mysql);
   for(r=0;r<=mysql_field_count(mysql);r++){
           row=mysql_fetch_row(res);
           if(row<0) break;
           for(t=0;t<mysql_num_fields(res);t++){
                   printf("%s ",row[t]);
           }
           printf("\n");
   }
   mysql_close(mysql);
}

Lecturas recomendadas

La página de MySQL: www.mysql.com
Documentos que vienen con el código fuente de MySQL. (Probablemente bajo el directorio /usr/doc)

Formulario de "talkback" para este artículo

Cada artículo tiene su propia página de "talkback". A través de esa página puedes enviar un comentario o consultar los comentarios de otros lectores

Ir a la página de "talkback"

<--, regresar al índice de este número

Información sobre la traducción:

tr --> -- : Özcan Güngör <ozcangungor(at)netscape.net>

en --> es: Carlos González Pérez <charly(en)galpon.org>

2003-12-03, generated by lfparser version 2.41