Valores vinculados para sentencias preparadas

    int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
    int sqlite3_bind_double(sqlite3_stmt*, int, double);
    int sqlite3_bind_int(sqlite3_stmt*, int, int);
    int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
    int sqlite3_bind_null(sqlite3_stmt*, int);
    int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
    int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
    int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
    int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);

En los textos de entrada de sentencias SQL para sqlite3_prepare_v2() y sus variantes, los literales pueden ser reemplazados por un parámetro que coincida con una de las siguientes plantillas:

    ?
    ?NNN
    :VVV
    @VVV
    $VVV

En las plantillas anteriores, NNN representa un literal entero, y VVV un identificador alfanumérico. Los valores de esos parámetros (también llamados "nombres de parámetros de host" o "parámetros SQL") pueden ser asignados usando las funciones sqlite3_bind_*() definidas aquí.

El primer argumento para una función sqlite3_bind_*() siempre es un puntero a un objeto sqlite3_stmt devuelto por una función sqlite3_prepare_v2() o una de sus variantes.

El segundo argumento es el índice del parámetro SQL a asignar. El parámetro SQL más a la izquierda tiene un índice de valor 1. Cuando el mismo parámetro SQL nombrado se usa más de una vez, la segunda y siguientes apariciones tienen el mismo índice que la primera. Los índices para parámetros con nombre se pueden buscar, si se desea, usando la función sqlite3_bind_parameter_index(). El índice para parámetros "?NNN" es el valor de NNN. El valor NNN debe estar entre 1 y sqlite3_limit(SQLITE_LIMIT_VARIABLE_NUMBER) (por defecto: 999).

El tercer argumento es el valor del para enlazar con el parámetro.

Si estas funciones tienen un cuarto argumento, su valor es el número de bytes en el parámetro. Siendo claros: el valor es el número de bytes en el valor, no el número de caracteres. Si el cuarto parámetro es negativo, la longitud de la cadeba es el número de bytes hasta el primer cero terminador. Si se proporciona un cuarto parámetro no negativo a sqlite3_bind_text() o sqlite3_bind_text16() entonces el parámetro debe ser el desplazamiento de bytes donde el terminador nulo debe estar asumiendo que la cadena esté terminada con NUL. Si aparecen caracteres NUL en desplazamientos de bytes menores que el valor del cuarto parámetro entonces la cadena resultante contendrá NULs en su interior. El resultado de expresiones que implican cadenas NUL está indefinido.

El quinto argumento de sqlite3_bind_blob(), sqlite3_bind_text() y sqlite3_bind_text16() es un destructor usado para eliminar la cadena o el BLOB despúes de que SQLite haya terminado con él. El destructor es invocado para eliminar la cadena o el BLOB aunque la llamada a sqlite3_bind_blob(), sqlite3_bind_text() o sqlite3_bind_text16() falle. Si el quinto argumento es el valor especial SQLITE_STATIC, entonces SQLite asume que la información esta en el espacio estático, y no necesita ser liberado. Si el quinto argumento tiene el valor SQLITE_TRANSIENT, entonces SQLite hace su propia copia privada del dato inmediatemente, antes de que la función sqlite3_bind_*() regrese.

La función sqlite3_bind_zeroblob() vincula un BLOB de longitud N que se llena con ceros. Un zeroblob usa una cantidad de memoria fija (sólo un entero para contener su tamaño) mientras es procesado. Los zeroblobs están destinados para usarse como marcadores para BLOBs cuyo contenido será escrito más tarde usando funciones de entrada/salida de BLOB incrementales. Un valor negativo para el zeroblob produce un BLOB de longitud cero.

Si cualquiera de las funciones sqlite3_bind_*() es invocada con un puntero NULL para la sentencia preparada o con una sentencia preparada para la que sqlite3_step() haya sido invocada más recientemente que sqlite3_reset(), entonces la llamada retorna con SQLITE_MISUSE. Si a cualquier función sqlite3_bind_() se le pasa una sentencia preparada que ha finalizado, el resultado es indefinico, y probablemente perjudicial.

Los enlaces no se eliminan por la función sqlite3_reset(). Los parámetros no enlazados se interpretan como NULL.

Las funciones sqlite3_bind_* retornan SQLITE_OK si tienen éxito o un código de error si algo ha ido mal. Se retorna SQLITE_RANGE si el índice del parámetro está fuera de rango. Se retorna SQLITE_NOMEM si malloc() falla.

Ver también: sqlite3_bind_parameter_count(), sqlite3_bind_parameter_name() y sqlite3_bind_parameter_index().