Está en la página 1de 44

Api Acceso bsico Manual del programador

Descripcin general

Esta Api (Application Programming Interface por sus siglas en ingls) proporciona los servicios bsicos de acceso a bases de datos Firebird, es decir, permite leer y escribir sobre las tablas de las mismas. Cualquier otra Api especializada en Microsip utiliza estos servicios bsicos. Los servicios estn contenidos en la librera ApiMspBasica.dll Estn disponibles las declaraciones externas de las funciones de esta dll para los siguientes lenguajes de programacin:
Lenguaje Delphi Visual Basic .Net Archivo

ApiMspBasicaExt.Pas ApiMspBasicaExt.bas ApiMspDotNetExt.dll


using ApiBas = ApisMicrosip.ApiMspBasicaExt;

Convenciones
PChar Representa un Null Terminated string, el cual es un string de caracteres terminado con el caractr Ascii 0 (como se maneja en el lenguaje C). Nota: cuando el parmetro sea de salida, es decir, cuando la funcin regresa un valor en l, es responsabilidad de la aplicacin reservar espacio suficiente para el buffer donde se recibir el dato. Integer Representa un entero de 4 bytes. Double Representa un valor real (punto flotante) de 8 bytes. Parmetros de salida Existen parmetros en los que las funciones regresan datos; stos se debern pasar por referencia, es decir, se debe pasar el apuntador a una variable del tipo adecuado. En este documento, dichos parmetros se indican con la palabra Var antepuesta al nombre del parmetro. Nota: a los parmetros de tipo Pchar no se les antepone la palabra Var debido a que stos por su naturaleza siempre son apuntadores. Valor de retorno
La mayora de las funciones regresa un entero indicando el cdigo de error obtenido, 0 si no lo hubo.

Existen algunas excepciones en cuanto al valor de retorno, como por ejemplo las funciones que regresan un valor lgico y que no necesitan regresar un cdigo de error; en ese caso, la funcin regresa un 0 para indicar Falso, y un 1 para indicar Verdadero.

Objetos para acceso de datos


El acceso a la base de datos se realiza a travs de instancias de los siguientes tipos de objetos de la dll:

DataBase
Este tipo de objeto se necesita para establecer la conexin a la base de datos.

Transaction

Api- Acceso bsico - Pgina 1 de 44

Api Acceso bsico Manual del programador


Todo acceso a base de datos, ya sea de lectura o de escritura, se hace a travs de una transaccin; y un objeto de transaccin est siempre relacionado con uno de base de datos. Por lo tanto, las lecturas y escrituras que se hagan a travs de una transaccin afectarn a la base de datos a la que sta est ligada.

Dataset
Un dataset se utiliza para leer un conjunto de registros de la base de datos mediante un query de Select y navegar a travs de ellos en forma bi-direccional, es decir, hacia adelante y hacia atrs. Adems, permite modificar o eliminar los registros obtenidos, as como agregar nuevos.

Sql
Un objeto Sql permite ejecutar cualquier estatuto de Sql sobre la base de datos. A diferencia del dataset, si se ejecuta un estatuto de Select mediante un objeto Sql, la navegacin sobre los registros resultantes se permite slo hacia adelante. Si no se necesita la navegacin bi-direccional es recomendable utilizar un objeto Sql en lugar de un Dataset, ya que es ms eficiente.

StoredProc
Este tipo de objeto permite ejecutar procedimientos almacenados de la base de datos (stored procedures).

SemaforoMsp
Un semforo es un mecanismo que utiliza Microsip para asegurar que las tareas crticas de afectacin a la base de datos las haga un usuario a la vez. Por ejemplo, antes de aplicar un nuevo documento al sistema de Inventarios se debe tomar un semforo llamado INVENTARIOS; esto hace que si otros usuarios desean hacer lo mismo en ese momento, esperen su turno. Normalmente no es necesario utilizar las funciones de manejo de semforos directamente, ya que existen otras Apis Microsip especializadas en agregar documentos, que se encargan de ello.

Lista de parmetros
Una lista de parmetros permite guardar diferentes valores, cada uno con su nombre, y despus recuperar los valores a partir del nombre. Algunas funciones de las Apis especializadas tienen como parmetro un objeto de este tipo y establecen los nombres de los elementos que debe contener la lista. El programador, mediante funciones de la Api, crea las instancias necesarias de estos tipos de objetos. La funcin que crea la instancia del objeto regresa un nmero de handle por medio del cual el programador har referencia a ella en lo sucesivo. La dll crea automticamente la instancia nmero 0 (cero) de cada tipo de objeto, excepto para el semforo y la lista de parmetros. De esta forma, el programa slo necesitar crear las instancias adicionales que necesite.

Manejo de errores
La mayora de las funciones de la dll regresan un cdigo de error, 0 si no lo hubo. Adems, la dll guarda la siguiente informacin del error de la ltima funcin ejecutada: FLastErrorCode 0 = no hubo error FLastErrorName Nombre corto del error FLastErrorFunctionName Nombre de la funcin en la que ocurri el error FLastErrorIBExceptionText

Api- Acceso bsico - Pgina 2 de 44

Api Acceso bsico Manual del programador


Si el error provoc una excepcin de Firebird, esta variable guarda el texto del

mensaje de la excepcin. FLastErrorIBCode Si el error provoc una excepcin de Firebird, esta variable guarda el nmero de error que report dicha excepcin.

Funciones para checar errores desde la aplicacin GetLastErrorCode: Integer; stdcall;


Descripcin Regresa el valor de FLastErrorCode.

GetLastIBErrorCode: Integer; stdcall;


Descripcin Regresa el valor de FLastErrorIBCode.

GetLastErrorMessage (ErrorMessage: PChar): Integer; stdcall;


Descripcin Forma un mensaje de error para el usuario, acerca del ltimo error ocurrido. Parmetros ErrorMessage. En este parmetro se regresa el texto del mensaje. No se altera la variable si no hubo error. Valor de retorno Regresa el valor de FLastErrorCode.
Adems, si FLastErrorCode <> 0, asigna a ErrorMessage un texto con el siguiente formato: Error #<FLastErrorCode> en funcin <FLastErrorFunctionName> <LastErrorName> <LastErrorIBExceptionText>

La ltima lnea y su espaciamiento se incluyen slo cuando el FLastErrorCode sea 99, es decir, cuando ocurri una excepcin de Firebird. Nota: Se asume que la aplicacin slo va a mostrar el mensaje si esta funcin regresa un valor <> 0.

SetErrorHandling( ExceptionOnError, MessageOnException: Integer); stdcall


Descripcin Establece la forma de manejar los errores de la dll en la aplicacin. Parmetros ExceptionOnError. 0 1. Si se asigna 1 a este parmetro, se levantar una excepcin de sistema operativo cuando se detecte cualquier error en la dll, de lo contrario, slo se regresa el cdigo de error en la funcin, y es responsabilidad de la aplicacin checarlo. MessageOnException. 0 1. Slo tiene relevancia cuando se asigna 1 al primer parmetro. Si se asigna 1 a este parmetro, se mostrar en una ventana el mensaje del error detectado, antes de levantar la excepcin correspondiente. Notas La dll inicia con estos 2 parmetros en cero.

SuspendExceptions(); stdcall
Descripcin Suspende el levantamiento de excepciones en los errores. Se utiliza cuando se estableci ExceptionOnError = 1 mediante el mtodo SetErrorHandling pero se desea suspender ese

Api- Acceso bsico - Pgina 3 de 44

Api Acceso bsico Manual del programador


comportamiento temporalmente, tpicamente durante cdigo que se ejecuta con los semforos tomados, ya que en ese caso no se desea que se interrumpa la ejecucin del programa. Normalmente este mtodo lo utilizan internamente las Apis de alto nivel durante la aplicacin de un documento. Notas Para terminar la suspensin de excepciones se llama al mtodo RestoreExceptions.

RestoreExceptions(); stdcall
Descripcin Termina la suspensin de excepciones que se haba establecido mediante el mtodo SuspendExceptions. Si las excepciones no estaban suspendidas, este mtodo no tiene ningn efecto.

ExceptionsSuspended (): Integer; stdcall


Descripcin Regresa 1 si las excepciones estn suspendidas actualmente por una llamada previa al mtodo SuspendExceptions, y 0 si no lo estn.

Formas de manejar los errores en una aplicacin


Una forma de manejar los errores en el programa que usa esta dll es la siguiente: Hacer un procedimiento que cheque por error y que reciba como parmetro un Bookmark de tipo Integer el cual sirve para indicar el lugar o lnea de cdigo donde ocurri el error. La lgica del procedimiento sera como sigue: Si GetLastErrorMessage(ErrorMessage)<>0: Mostrar al usuario un mensaje de error con el texto ErrorMessage concatenndole un salto de lnea y el texto LUGAR ==> <Bookmark> Terminar la ejecucin de la aplicacin (Stop). Nota: declarar ErrorMessage como variable string global e inicializada a 255 caracteres aproximadamente para dar cabida a cualquier mensaje de error. Llamar a las funciones de la dll como si fueran procedimientos y no funciones (excepto en las que el valor de retorno no sea un cdigo de error), y despus de cada llamada ejecutar el procedimiento de chequeo de error pasando como parmetro un nmero de bookmark diferente cada vez; este nmero nos ayuda a localizar exactamente la lnea de cdigo que provoc el error. Una forma alternativa de manejar los errores es indicarle a la dll que se desea que se levante una excepcin de sistema operativo cuando se detecte un error, mostrando antes el mensaje de error: SetErrorHandling(1, 1) De esta forma, no es necesario checar por error despus de cada funcin. Si el lenguaje de programacin de la aplicacin que usa esta dll no tiene la capacidad de atrapar excepciones del sistema operativo, es importante hacer MessageOnException = 1 (segundo parmetro) porque la aplicacin no terminar en forma normal debido a que se obtendr un mensaje de error fatal por parte del sistema operativo (despus de mostrar el mensaje de error de la dll). En cambio, si el lenguaje s puede atrapar las excepciones, la aplicacin puede evitar el mensaje de error fatal del sistema operativo. Una desventaja de esta forma de manejar los errores es que no podemos identificar la lnea exacta de cdigo que ocasion el error, pero al menos sabremos el nombre de la funcin.

Api- Acceso bsico - Pgina 4 de 44

Api Acceso bsico Manual del programador

Manejo de Ids de los registros


La mayora de las tablas de la base de datos de empresa Microsip tienen como primer campo un identificador nico de tipo entero. La base de datos da la facilidad de generar automticamente el valor para este campo cuando se dan de alta nuevos registros. La manera de hacerlo es asignando 1 a dicho campo al insertar el registro. Nota importante: se recomienda siempre dejar que la base de datos determine el identificador en nuevos registros, ya que de otra manera se puede interferir con la captura que se hace desde los sistemas Microsip y provocar problemas graves. Al hacer el Post del dataset, es decir, al escribir el registro, la base de datos detecta que el campo de Id vale 1 y genera un nmero nico para dicho campo. El campo del dataset en la aplicacin sigue valiendo 1, es decir, no se conoce el valor generado por la base de datos a menos que declaremos el query de Refresh para el dataset (ver funcin DtstRefreshQry). Nota: muchas veces no necesitamos conocer el Id generado pues no se utiliza ms adelante en la lgica del programa; pero hay ocasiones en que s se necesita, por ejemplo cuando el registro es el maestro en una relacin maestro-detalle y debemos ligar los registros del dataset detalle con el maestro mediante el Id del maestro.

Api- Acceso bsico - Pgina 5 de 44

Api Acceso bsico Manual del programador

Objeto DataBase
NewDB: Integer; stdcall;
Descripcin Crea un nuevo objeto Database. Valor de retorno Regresa el Handle del nuevo objeto.

DBCount: Integer; stdcall;


Descripcin Regresa el nmero de objetos Database creados hasta el momento, incluyendo el que se crea automticamente. Los nmeros de estos objetos van del 0 al DBCount-1, por ejemplo, si existen 3 objetos, sus nmeros de handle van del 0 al 2.

DBConnect(DBHandle: Integer; DatabaseName, UserName, Password: PChar): Integer; stdcall;


Descripcin Establece la conexin a una base de datos. Parmetros DBHandle. Nmero del objeto Database a utilizar. NombreBaseDatos. Es el nombre de la base de datos a la que se desea conectar, incluye la ruta completa. Ejemplo: C:\Microsip datos\Empresa.fdb. UserName. Nombre del usuario de Firebird. Password. Clave secreta del usuario de Firebird. Valor de retorno 0 = Conexin exitosa. 1 = Handle inexistente. 2 = Transaccin aun no asignada 3 = Base de datos inexistente. 4 = Usuario o password incorrectos. 5 = Base de datos actualmente conectada. 6 = Error al checar la licencia de la Api Microsip. Notas Cuando se utiliza un objeto Database diferente al default (0), antes de realizar la conexin a la base de datos se debe crear una transaccin ligada a este objeto (ver funcin NewTrn). Con referencia al error #6, ver la seccin Licencia de la Api Microsip.

DBDisconnect(DBHandle: Integer): Integer; stdcall;


Descripcin Termina la conexin a una base de datos cerrando antes cualquier dataset o sql asociado con la misma. Parmetros DBHandle. Nmero del objeto Database a utilizar. -1 = Desconectar todas las bases de datos actualmente conectadas. Valor de retorno 0 = Desconexin exitosa o base de datos actualmente desconectada. 1 = Handle inexistente.

Api- Acceso bsico - Pgina 6 de 44

Api Acceso bsico Manual del programador


Notas Es importante que, antes de terminar su ejecucin, el programa se desconecte de todas las bases de datos que utiliz, ya que de lo contrario ste puede terminar anormalmente mostrando mensajes de error, adems de no liberar la licencia de la Api Microsip (ver seccin correspondiente).

DBConnected(DBHandle: Integer): Integer; stdcall;


Descripcin Indica si una base de datos est conectada actualmente. Parmetros DBHandle. Nmero del objeto Database a utilizar. Valor de retorno 0 = Base de datos no conectada o hubo error. 1 = Base de datos conectada. Errores 1 = Handle inexistente. Notas Si esta funcin regresa 0, puede ser ya sea porque la base de datos est desconectada, o porque hubo un error; para distinguir el caso se debe checar por GetLastErrorCode.

DBCloseDatasets (DBHandle: Integer): Integer; stdcall;


Descripcin Cierra todo dataset y sqls asociados con una base de datos sin cerrar la conexin a la misma. Parmetros DBHandle. Nmero del objeto Database a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Base de datos actualmente desconectada.

DBGetDefaultTrn (DBHandle: Integer): Integer; stdcall;


Descripcin Regresa el handle de la transaccin de default de la base de datos indicada, es decir, de la primera transaccin asignada a la base de datos. Parmetros DBHandle. Nmero del objeto de base de datos a utilizar. Valor de retorno 0..n = Handle de la transaccin de default. -1 = Hubo error. Se debe checar GetLastErrorCode. Errores 1 = Handle inexistente. 2 = Base de datos sin transaccin default. 3 = Handle de transaccin inexistente.

Api- Acceso bsico - Pgina 7 de 44

Api Acceso bsico Manual del programador

Objeto Transaction
NewTrn (DBHandle, TrnType: Integer): Integer; stdcall;
Descripcin Crea un nuevo objeto Transaction. Parmetros DBHandle. Nmero de objeto Database al que pertenecer la transaccin. TrnType. Tipo de transaccin. 0 = Snapshot Se utiliza para slo lectura. Se ignoran los cambios que hagan otras transacciones que estn activas al momento de activar esta transaccin, o que se activen posteriormente. 1 = ReadCommittedRecVer Se utiliza para slo lectura. Se reconocen los cambios que hagan otras transacciones que estn activas al momento de activar esta transaccin, o que se activen posteriormente. Slo se ignoran los cambios cuya transaccin no haya hecho Commit aun. 2 = ReadCommittedWait Se utiliza para lectura y escritura. Se reconocen los cambios que hagan otras transacciones que estn activas al momento de activar esta transaccin, o que se activen posteriormente. Si se intenta leer o escribir un rengln que tenga en ese momento cambios de otra transaccin con Commit pendiente, la operacin entra en estado de espera hasta que se haga el Commit. 3 = ReadCommittedNoWait Se utiliza para lectura y escritura. Es igual que el tipo 2 excepto que este tipo no entra en estado de espera cuando el Commit est pendiente sino que regresa un error inmediatamente. Valor de retorno 1..n = Handle del nuevo objeto. 0 = Hubo error. Se debe checar GetLastErrorCode Errores 1 = Tipo de transaccin incorrecto. 2 = Handle inexistente. Notas La transaccin default (#0) se crea con tipo Snapshot pero se puede reconfigurar mediante la funcin TrnConfig.

TrnCount: Integer; stdcall;


Descripcin Regresa el nmero de objetos Transaction creados hasta el momento, incluyendo el que se crea automticamente. Los nmeros de estos objetos van del 0 al TrnCount-1, por ejemplo, si existen 3 objetos, sus nmeros de handle van del 0 al 2.

TrnStart (TrnHandle: Integer): Integer; stdcall;


Descripcin Inicia la operacin de una transaccin.

Api- Acceso bsico - Pgina 8 de 44

Api Acceso bsico Manual del programador


Parmetros TrnHandle. Nmero del objeto Transaction a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Transaccin actualmente activa. Notas Se debe activar la transaccin antes de realizar accesos a la base de datos.

TrnInTransaction (TrnHandle: Integer): Integer; stdcall;


Descripcin Indica si una transaccin est activa. Parmetros TrnHandle. Nmero del objeto Transaction a utilizar. Valor de retorno 0 = Transaccin inactiva o hubo error. 1 = Transaccin activa. Errores 1 = Handle inexistente. Notas Si esta funcin regresa 0, puede ser ya sea porque la transaccin est inactiva, o porque hubo un error; para distinguir el caso se debe checar por GetLastErrorCode.

TrnCommit (TrnHandle: Integer): Integer; stdcall;


Descripcin Guarda permanentemente los cambios a la base de datos hechos desde el ltimo TrnStart de una transaccin, y desactiva la transaccin. Parmetros TrnHandle. Nmero del objeto Transaction a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Transaccin actualmente inactiva.

TrnRollback (TrnHandle: Integer): Integer; stdcall;


Descripcin Cancela los cambios a la base de datos hechos desde el ltimo TrnStart de una transaccin, y desactiva la transaccin. Parmetros TrnHandle. Nmero del objeto Transaction a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Transaccin actualmente inactiva.

TrnConfig (TrnHandle, TrnType: Integer): Integer; stdcall;


Descripcin Modifica el Tipo de una transaccin. Se usa por ejemplo cuando se desea reutilizar una transaccin dentro de un mismo programa pero con otro tipo, o cuando se desea utilizar la transaccin default (#0) con un tipo diferente al que tiene originalmente (Snapshot).
Api- Acceso bsico - Pgina 9 de 44

Api Acceso bsico Manual del programador


Parmetros TrnHandle. Nmero del objeto Transaction a utilizar. TrnType. Ver descripcin de este parmetro en la funcin NewTrn. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Transaccin actualmente activa. 3 = Tipo de transaccin incorrecto.

Api- Acceso bsico - Pgina 10 de 44

Api Acceso bsico Manual del programador

Objeto Dataset
NewDtst (TrnHandle: Integer): Integer; stdcall;
Descripcin Crea un nuevo objeto Dataset. Parmetros TrnHandle. Nmero del objeto Transaction bajo el cual se harn los accesos del dataset. Valor de retorno 1..n = Handle del nuevo objeto. 0 = Hubo error. Se debe checar GetLastErrorCode Errores 1 = Handle de transaccin inexistente

DtstCount: Integer; stdcall;


Descripcin Regresa el nmero de objetos Dataset creados hasta el momento, incluyendo el que se crea automticamente. Los nmeros de estos objetos van del 0 al DtstCount-1, por ejemplo, si existen 3 objetos, sus nmeros de handle van del 0 al 2.

DtstConfig (DtstHandle, TrnHandle: Integer): Integer; stdcall;


Descripcin Modifica la transaccin a la que estar ligado un dataset. Se usa por ejemplo cuando se desea reutilizar un dataset dentro de un mismo programa pero bajo otra transaccin diferente a la de su creacin (y probablemente sobre otra base de datos). Parmetros DtstHandle. Nmero del objeto Dataset a configurar. TrnHandle. Nmero de objeto Transaction al que se desea ligar el dataset. Valor de retorno 0 = Operacin exitosa. 1 = Handle de dataset inexistente. 2 = Handle de transaccin inexistente. 3 = Dataset actualmente abierto.

DtstSelQry (DtstHandle: Integer; Query: PChar): Integer; stdcall;


Descripcin Establece el query de Select de un dataset. Este query es el que se ejecuta cuando el dataset es abierto, y determina el conjunto de registros (y campos) sobre el que se va a trabajar. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Query. Estatuto de SQL de tipo Select. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente abierto. 99 = Query incorrecto. Notas El query es cualquier estatuto vlido de Select, es decir, puede contener Joins, Where, Order by etc.
Api- Acceso bsico - Pgina 11 de 44

Api Acceso bsico Manual del programador


Se puede obtener un subconjunto de los campos de la tabla listando sus nombres en el query, o bien, utilizar * para obtenerlos todos. El query puede contener parmetros en su clusula Where a los cuales se les da valor antes de abrir el dataset por medio de las funciones DtstParamAs... Los parmetros se especifican anteponiendo : al nombre del mismo. Ejemplo: SELECT * FROM PAISES WHERE PAID_ID = :PAIS_ID

DtstInsQry (DtstHandle: Integer; Query: PChar): Integer; stdcall;


Descripcin Establece el query de Insert de un dataset. Este query es el que se ejecuta cuando se efectua un DtstPost para un nuevo registro el cual fue previamente insertado con DtstInsert. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Query. Estatuto de SQL de tipo Insert. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente abierto. 99 = Query incorrecto. Notas No es necesario establecer este query si no se van a insertar nuevos registros con el dataset; por ejemplo, hay ocasiones en que slo se modificarn los registros existentes. El query debe tener la siguiente forma: INSERT INTO <nombre de tabla> ( <lista de campos> ) VALUES ( <lista de parmetros> ) Donde: La lista de campos se forma con los nombres de los campos separados por comas. La lista de parmetros se forma igual que la lista de campos pero anteponiendo : a cada nombre de campo. Por ejemplo: INSERT INTO PAISES (PAIS_ID, NOMBRE, NOMBRE_ABREV) VALUES (:PAIS_ID, :NOMBRE, :NOMBRE_ABREV)

DtstUpdQry (DtstHandle: Integer; Query: PChar): Integer; stdcall;


Descripcin Establece el query de Update de un dataset. Este query es el que se ejecuta cuando se efectua un DtstPost para un registro el cual fue previamente modificado con DtstEdit. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Query. Estatuto de SQL de tipo Update. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente abierto. 99 = Query incorrecto.

Api- Acceso bsico - Pgina 12 de 44

Api Acceso bsico Manual del programador


Notas No es necesario establecer este query si no se van a modificar los registros del dataset; por ejemplo, hay ocasiones en que slo se insertarn registros nuevos. El query debe tener la siguiente forma: UPDATE <nombre de tabla> SET <nombre de campo> = :<nombre de campo>, <nombre de campo> = :<nombre de campo> WHERE <campo llave> = :<campo llave> Por ejemplo: UPDATE PAISES SET NOMBRE = :NOMBRE, NOMBRE_ABREV = :NOMBRE_ABREV WHERE PAIS_ID = :PAIS_ID Los parmetros de este tipo de query son sustituidos automticamente, es decir, basta con hacer DtstEdit al registro actual del dataset, asignarle valores a los campos, y hacer DtstPost. Obviamente, la condicin para que esto funcione asi es que los campos involucrados en este query se llamen igual que en el query de Select. Es importante la clusula Where en este query para afectar slo el registro siendo modificado, ya que de otra manera se afectaran todos los registros de la tabla.

DtstDelQry (DtstHandle: Integer; Query: PChar): Integer; stdcall;


Descripcin Establece el query de Delete de un dataset. Este query es el que se ejecuta cuando se efectua un DtstDelete para el registro actual. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Query. Estatuto de SQL de tipo Delete. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente abierto. 99 = Query incorrecto. Notas No es necesario establecer este query si no se van a eliminar registros del dataset; por ejemplo, hay ocasiones en que slo se insertarn registros nuevos. El query debe tener la siguiente forma: DELETE FROM <nombre de tabla> WHERE <campo llave> = :<campo llave> Por ejemplo: DELETE FROM PAISES WHERE PAIS_ID = :PAIS_ID Los parmetros de este tipo de query son sustituidos automticamente, es decir, basta con hacer DtstDelete al registro actual del dataset. Obviamente, la condicin para que esto funcione asi es que los campos involucrados en este query se llamen igual que en el query de Select. Es importante la clusula Where en este query para eliminar slo el registro actual, ya que de otra manera se eliminaran todos los registros de la tabla.

DtstRefreshQry (DtstHandle: Integer; Query: PChar): Integer; stdcall;


Descripcin Establece el query que se ejecuta automticamente cada vez que se hace un DtstPost al dataset, y que sirve para volver a leer los campos del registro que acabamos de escribir.
Api- Acceso bsico - Pgina 13 de 44

Api Acceso bsico Manual del programador


Su uso principal es para recuperar el Id del registro recin dado de alta, cuando la base de datos gener el Id automticamente (al haberle asignado 1 al campo de Id). Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Query. Estatuto de SQL de tipo Select. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente abierto. 99 = Query incorrecto. Notas Este query debe seleccionar los mismos campos que el query de Select del dataset pero para un registro especfico, es decir, para el registro que acabamos de escribir. Dicho registro se localiza por medio de uno o ms campos, diferentes al del Id, que lo identifican como nico. Por ejemplo, para la tabla de PAISES, este query sera: SELECT * FROM PAISES WHERE NOMBRE = :NOMBRE Aqu, el campo Nombre identifica tambin en forma nica al pas. Otro ejemplo, para la tabla de DOCTOS_VE SELECT * FROM DOCTOS_VE WHERE TIPO_DOCTO = :TIPO_DOCTO AND FOLIO = :FOLIO En este caso la unin de tipo de documento y el folio identifican al registro en forma nica. Nota: los nombres de los parmetros del query deben existir como campos del dataset.

DtstSetParamAsString (DtstHandle: Integer; ParamName, ParamValue: PChar): Integer; stdcall;


Descripcin Asigna un valor a un parmetro de tipo String del query de Select de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. ParamName. Nombre del parmetro. ParamValue. Valor a asignar al parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente abierto. 3 = Parmetro inexistente. Notas Esta funcin se utiliza antes de abrir un dataset cuando su query de Select contiene parmetros. El nombre del parmetro debe ser el mismo utilizado en el query de Select sin incluir los :.

DtstSetParamAsDateTime (DtstHandle: Integer; ParamName: PChar; Day, Month, Year, Hour, Minute, Second: Word): Integer; stdcall;
Descripcin Asigna un valor a un parmetro de tipo Fecha, Hora, o Fecha_Hora del query de Select de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar.
Api- Acceso bsico - Pgina 14 de 44

Api Acceso bsico Manual del programador


ParamName. Nombre del parmetro. Day. Nmero de da del mes. Debe ser vlido para el mes y el ao dados. Month. Nmero de mes de la fecha. Debe estar entre 1 y 12. Year. Ao de la fecha. Debe estar entre 1 y 9999 Hour. Hora del da. Debe estar entre 0 y 23. Minute. Nmero de minuto. Debe estar entre 0 y 59. Second. Nmero de segundo. Debe estar entre 0 y 59. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente abierto. 3 = Parmetro inexistente. 4 = Valor incorrecto del parmetro. Notas Esta funcin se utiliza antes de abrir un dataset cuando su query de Select contiene parmetros. El nombre del parmetro debe ser el mismo utilizado en el query de Select sin incluir los :. Cuando el parmetro del query es de tipo fecha, es decir, no lleva hora, pasar cero en los componentes de la hora. Cuando el parmetro del query es de tipo hora, es decir, no lleva fecha, pasar cero en los componentes de la fecha.

DtstSetParamAsInteger (DtstHandle: Integer; ParamName: PChar; ParamValue: Integer): Integer; stdcall;


Descripcin Asigna un valor a un parmetro de tipo entero del query de Select de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. ParamName. Nombre del parmetro. ParamValue. Valor a asignar al parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente abierto. 3 = Parmetro inexistente. Notas Esta funcin se utiliza antes de abrir un dataset cuando su query de Select contiene parmetros. El nombre del parmetro debe ser el mismo utilizado en el query de Select sin incluir los :.

DtstSetParamAsDouble (DtstHandle: Integer; ParamName: PChar; ParamValue: Double): Integer; stdcall;


Descripcin Asigna un valor a un parmetro de tipo Double del query de Select de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. ParamName. Nombre del parmetro. ParamValue. Valor a asignar al parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente abierto. 3 = Parmetro inexistente.
Api- Acceso bsico - Pgina 15 de 44

Api Acceso bsico Manual del programador


Notas Esta funcin se utiliza antes de abrir un dataset cuando su query de Select contiene parmetros. El nombre del parmetro debe ser el mismo utilizado en el query de Select sin incluir los :.

DtstSetParamAsNull (DtstHandle: Integer; ParamName: PChar): Integer; stdcall;


Descripcin Asigna el valor Null a un parmetro del query de Select de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. ParamName. Nombre del parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente abierto. 3 = Parmetro inexistente. Notas Esta funcin se utiliza antes de abrir un dataset cuando su query de Select contiene parmetros y se desea hacer Null uno de ellos. El nombre del parmetro debe ser el mismo utilizado en el query de Select sin incluir los :.

DtstOpen (DtstHandle: Integer): Integer; stdcall;


Descripcin Ejecuta el query de Select del dataset, y deja disponible el conjunto de registros resultantes del mismo para poder ser accesados mediante otras funciones de este Api. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Base de datos aun no conectada 3 = Dataset actualmente abierto. 4 = Query de Select no asignado. 99 = Error de Firebird.

DtstClose (DtstHandle: Integer): Integer; stdcall;


Descripcin Ciarra el dataset y libera los recursos que sus registros ocupaban. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. Notas Si el dataset est actualmente cerrado, esta funcin no hace nada y regresa xito.

DtstFirst (DtstHandle: Integer): Integer; stdcall; DtstNext (DtstHandle: Integer): Integer; stdcall; DtstPrev (DtstHandle: Integer): Integer; stdcall; DtstLast (DtstHandle: Integer): Integer; stdcall;

Api- Acceso bsico - Pgina 16 de 44

Api Acceso bsico Manual del programador


Descripcin Estos comandos permiten navegar a travs de los registros resultantes del dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 99 = Error de Firebird.

DtstEof (DtstHandle: Integer): Integer; stdcall;


Descripcin Indica si ya se lleg al final de los registros de un dataset durante una navegacin secuencial hacia adelante. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Valor de retorno 0 = Falso (no se ha llegado al final) o hubo error (se debe checar GetLastErrorCode). 1 = Verdadero (ya se lleg al final). Errores 1 = Handle inexistente 2 = Dataset actualmente cerrado. 99 = Error de Firebird.

DtstBof (DtstHandle: Integer): Integer; stdcall;


Descripcin Indica si ya se lleg al inicio de los registros de un dataset durante una navegacin secuencial hacia atrs. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Valor de retorno 0 = Falso (no se ha llegado al inicio) o hubo error (se debe checar el GetLastErrorCode). 1 = Verdadero (ya se lleg al inicio). Errores 1 = Handle inexistente 2 = Dataset actualmente cerrado. 99 = Error de Firebird.

DtstRecordCount (DtstHandle: Integer): Integer; stdcall;


Descripcin Regresa el nmero de registros que contiene un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Valor de retorno 0..n = Nmero de registros. Se regresa 0 tambin si hubo error (checar GetLastErrorCode). Errores 1 = Handle inexistente 2 = Dataset actualmente cerrado. 99 = Error de Firebird.

Api- Acceso bsico - Pgina 17 de 44

Api Acceso bsico Manual del programador DtstGetFieldAsString (DtstHandle: Integer; FieldName, FieldValue: PChar): Integer; stdcall;
Descripcin Obtiene el valor de un campo de tipo String del registro actual de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo. FieldValue. En este parmetro se regresa el valor actual del campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente.

DtstGetFieldAsDate (DtstHandle: Integer; FieldName: PChar; Var Day, Month, Year: Word): Integer; stdcall;
Descripcin Obtiene el valor de un campo de tipo Date del registro actual de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo. Day, Month, Year. En estos parmetros se regresan los componentes de la fecha que contiene el campo actualmente. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo Date.

DtstGetFieldAsTime (DtstHandle: Integer; FieldName: PChar; Var Hour, Minute, Second: Word): Integer; stdcall;
Descripcin Obtiene el valor de un campo de tipo Time del registro actual de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo. Hour, Minute, Second. En estos parmetros se regresan los componentes de la hora que contiene el campo actualmente. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo Time.

DtstGetFieldAsDateTime (DtstHandle: Integer; FieldName: PChar; Var Day, Month, Year, Hour, Minute, Second: Word): Integer; stdcall;
Descripcin Obtiene el valor de un campo de tipo DateTime del registro actual de un dataset.

Api- Acceso bsico - Pgina 18 de 44

Api Acceso bsico Manual del programador


Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo. Day, Month, Year, Hour, Minute, Second. En estos parmetros se regresan los componentes de la fecha y hora que contiene el campo actualmente. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo DateTime.

DtstGetFieldAsInteger (DtstHandle: Integer; FieldName: PChar; Var FieldValue: Integer): Integer; stdcall;
Descripcin Obtiene el valor de un campo de tipo Integer del registro actual de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo. FieldValue. En este parmetro se regresa el valor actual del campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo Integer.

DtstGetFieldAsDouble (DtstHandle: Integer; FieldName: PChar; Var FieldValue: Double): Integer; stdcall;
Descripcin Obtiene el valor de un campo de tipo Double del registro actual de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo. FieldValue. En este parmetro se regresa el valor actual del campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo Double.

DtstGetFieldAsMemo (DtstHandle: Integer; FieldName, FieldValue: PChar): Integer; stdcall;


Descripcin Obtiene el valor de un campo de tipo String del registro actual de un dataset, cuyo contenido puede ser multi-lneas, es decir, que puede contener saltos de lnea (caracteres 13 y 10). Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo.

Api- Acceso bsico - Pgina 19 de 44

Api Acceso bsico Manual del programador


FieldValue. En este parmetro se regresa el valor actual del campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente.

DtstSetFieldAsString (DtstHandle: Integer; FieldName, FieldValue: PChar): Integer; stdcall;


Descripcin Establece el valor de un campo de tipo String del registro actual de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo. FieldValue.Valor a asignar al campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente. 4 = Registro actual no est en modo de edicin. Notas Esta funcin se utiliza cuando se est modificando el registro actual del dataset, habiendo llamado antes a la funcin DtstInsert o DtstEdit.

DtstSetFieldAsDate (DtstHandle: Integer; FieldName: PChar; Day, Month, Year: Word): Integer; stdcall;
Descripcin Establece el valor de un campo de tipo Date del registro actual de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo. Day, Month, Year. Estos parmetros contienen los componentes de la fecha a asignar al campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo Date. 5 = Valor incorrecto de los componentes de la fecha. 6 = Registro actual no est en modo de edicin. Notas Esta funcin se utiliza cuando se est modificando el registro actual del dataset, habiendo llamado antes a la funcin DtstInsert o DtstEdit.

DtstSetFieldAsTime (DtstHandle: Integer; FieldName: PChar; Hour, Minute, Second: Word): Integer; stdcall;
Descripcin Establece el valor de un campo de tipo Time del registro actual de un dataset.

Api- Acceso bsico - Pgina 20 de 44

Api Acceso bsico Manual del programador


Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo. Hour, Minute, Second. Estos parmetros contienen los componentes de la hora a asignar al campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo Time. 5 = Valor incorrecto de los componentes de la hora. 6 = Registro actual no est en modo de edicin. Notas Esta funcin se utiliza cuando se est modificando el registro actual del dataset, habiendo llamado antes a la funcin DtstInsert o DtstEdit.

DtstSetFieldAsDateTime (DtstHandle: Integer; FieldName: PChar; Day, Month, Year, Hour, Minute, Second: Word): Integer; stdcall;
Descripcin Establece el valor de un campo de tipo DateTime del registro actual de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo. Day, Month, Year, Hour, Minute, Second. Estos parmetros contienen los componentes de la fecha y hora a asignar al campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo DateTime. 5 = Valor incorrecto de los componentes de la fecha o la hora. 6 = Registro actual no est en modo de edicin. Notas Esta funcin se utiliza cuando se est modificando el registro actual del dataset, habiendo llamado antes a la funcin DtstInsert o DtstEdit.

DtstSetFieldAsInteger (DtstHandle: Integer; FieldName: PChar; FieldValue: Integer): Integer; stdcall;


Descripcin Establece el valor de un campo de tipo Integer del registro actual de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo. FieldValue. Valor a asignar al campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo Integer.
Api- Acceso bsico - Pgina 21 de 44

Api Acceso bsico Manual del programador


5 = Registro actual no est en modo de edicin. Notas Esta funcin se utiliza cuando se est modificando el registro actual del dataset, habiendo llamado antes a la funcin DtstInsert o DtstEdit.

DtstSetFieldAsDouble (DtstHandle: Integer; FieldName: PChar; FieldValue: Double): Integer; stdcall;


Descripcin Establece el valor de un campo de tipo Double del registro actual de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo. FieldValue. Valor a asignar al campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo Double. 5 = Registro actual no est en modo de edicin. Notas Esta funcin se utiliza cuando se est modificando el registro actual del dataset, habiendo llamado antes a la funcin DtstInsert o DtstEdit.

DtstSetFieldAsMemo (DtstHandle: Integer; FieldName, FieldValue: PChar): Integer; stdcall;


Descripcin Establece el valor de un campo de tipo String del registro actual de un dataset cuyo contenido puede ser multi-lneas, es decir, que puede contener saltos de lnea (caracteres 13 y 10). Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo. FieldValue.Valor a asignar al campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente. 4 = Registro actual no est en modo de edicin. Notas Esta funcin se utiliza cuando se est modificando el registro actual del dataset, habiendo llamado antes a la funcin DtstInsert o DtstEdit.

DtstSetFieldAsNull (DtstHandle: Integer; FieldName: PChar): Integer; stdcall;


Descripcin Asigna el valor Null a un campo del registro actual de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. FieldName. Nombre del campo.

Api- Acceso bsico - Pgina 22 de 44

Api Acceso bsico Manual del programador


Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Campo inexistente. 4 = Registro actual no est en modo de edicin. Notas Esta funcin se utiliza cuando se est modificando el registro actual del dataset, habiendo llamado antes a la funcin DtstInsert o DtstEdit.

DtstInsert (DtstHandle: Integer): Integer; stdcall;


Descripcin Inserta un nuevo registro en blanco a un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Query de Insert no asignado. 99 = Error de Firebird Notas Despus de insertar el registro en blanco se debe asignar valor a los campos del mismo, y finalmente, ejecutar el mtodo DtstPost para escribir sobre la base de datos.

DtstEdit (DtstHandle: Integer): Integer; stdcall;


Descripcin Pone el registro actual de un dataset en modo de edicin, de manera que se puedan modificar los valores de sus campos. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Query de Edit no asignado. 99 = Error de Internase Notas Despus de poner en modo de edicin al registro actual, se asigna valor a los campos del mismo que se deseen modificar, y se ejecuta el mtodo DtstPost para escribir los cambios sobre la base de datos.

DtstDelete(DtstHandle: Integer): Integer; stdcall;


Descripcin Elimina el registro actual de un dataset. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado.
Api- Acceso bsico - Pgina 23 de 44

Api Acceso bsico Manual del programador


3 = Query de Delete no asignado. 99 = Error de Firebird

DtstCancel (DtstHandle: Integer): Integer; stdcall;


Descripcin Cancela los cambios hechos al registro actual de un dataset si stos no han sido escritos mediante la funcin DtstPost. Se utiliza para cancelar tanto un DtstInsert como un DtstEdit. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Registro actual no est en modo de edicin.

DtstPost (DtstHandle: Integer): Integer; stdcall;


Descripcin Escribe los cambios hechos al registro actual de un dataset en la base de datos. Se utiliza para escribir en la base de datos tanto el nuevo registro despus de un DtstInsert, como los cambios hechos despus de un DtstEdit. Parmetros DtstHandle. Nmero del objeto Dataset a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Dataset actualmente cerrado. 3 = Registro actual no est en modo de edicin. 99 = Error de Firebird Notas Al ejecutar esta funcin se lanza el query de Insert o de Update del dataset segn sea el caso, llenndose sus parmetros a partir de los campos del registro. Cabe recordar que la escritura del registro se hace definitiva hasta que se ejecute el TrnCommit del la transaccin del dataset, o que se puede anular ejecutando en su lugar el TrnRollback de la misma.

DtstLink (MasterDtstHandle, SlaveDtstHandle: Integer): Integer; stdcall;


Descripcin Establece una relacin maestro-esclavo entre dos datasets. Al establecerse esta relacin, cada vez que
se visite un registro diferente en el dataset maestro (incluyendo el primer registro que se visita automticamente al abrir el dataset), se lleva a cabo lo siguiente: Se cierra el dataset esclavo. Cada parmetro del query de Select del dataset esclavo, cuyo nombre coincida con el de un campo del dataset maestro, recibe el valor actual de ste ltimo. Se abre el dataset esclavo. Nota: normalmente los parmetros del query de Select del dataset esclavo son los campos que lo ligan con el dataset maestro. Por ejemplo, si se trata de la relacin de un encabezado de documento con sus renglones de detalle, el campo en comn sera el Id del documento.

Api- Acceso bsico - Pgina 24 de 44

Api Acceso bsico Manual del programador


Parmetros MasterDtstHandle. Nmero del objeto Dataset que ser el maestro. SlaveDtstHandle. Nmero del objeto Dataset que ser el esclavo. Valor de retorno 0 = Operacin exitosa. 1 = Handle maestro o esclavo inexistente. 2 = Dataset maestro o esclavo actualmente abierto.

DtstUnLink (SlaveDtstHandle: Integer): Integer; stdcall;


Descripcin Destruye la relacin maestro-esclavo en la que participa como esclavo un dataset. Parmetros SlaveDtstHandle. Nmero del objeto Dataset que actualmente es esclavo. Valor de retorno 0 = Operacin exitosa. 1 = Handle esclavo inexistente. 2 = Dataset esclavo actualmente abierto.

Api- Acceso bsico - Pgina 25 de 44

Api Acceso bsico Manual del programador

Objeto SQL
NewSql (TrnHandle: Integer): Integer; stdcall;
Descripcin Crea un nuevo objeto Sql. Parmetros TrnHandle. Nmero del objeto Transaction bajo el cual se harn los accesos del sql. Valor de retorno 1..n = Handle del nuevo objeto. 0 = Hubo error. Se debe checar GetLastErrorCode Errores 1 = Handle de transaccin inexistente

SqlCount: Integer; stdcall;


Descripcin Regresa el nmero de objetos sql creados hasta el momento, incluyendo el que se crea automticamente. Los nmeros de estos objetos van del 0 al SqlCount-1, por ejemplo, si existen 3 objetos, sus nmeros de handle van del 0 al 2.

SqlConfig (SqlHandle, TrnHandle: Integer): Integer; stdcall;


Descripcin Modifica la transaccin a la que estar ligado un objeto Sql. Se usa por ejemplo cuando se desea reutilizar un sql dentro de un mismo programa pero bajo otra transaccin diferente a la de su creacin (y probablemente sobre otra base de datos). Parmetros SqlHandle. Nmero del objeto Sql a configurar. TrnHandle. Nmero de objeto Transaction al que se desea ligar el sql. Valor de retorno 0 = Operacin exitosa. 1 = Handle de sql inexistente. 2 = Handle de transaccin inexistente. 3 = Sql actualmente abierto.

SqlQry (SqlHandle: Integer; Query: PChar): Integer; stdcall;


Descripcin Establece el query a ejecutar en un objeto Sql. Si este query es de tipo Select, al ejecutarlo quedar disponible un conjunto de registros resultantes para navegar. Nota: la navegacin en este caso es slo hacia adelante. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. Query. Estatuto de SQL a ejecutar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 99 = Query incorrecto. Notas El query es cualquier estatuto vlido de SQL.

Api- Acceso bsico - Pgina 26 de 44

Api Acceso bsico Manual del programador


El query puede contener parmetros a los cuales se les da valor antes de ejecutarlo, por medio de las funciones SqlSetParamAs... Los parmetros se especifican anteponiendo : al nombre del mismo. Ejemplo: INSERT INTO PAISES (PAIS_ID, NOMBRE) VALUES (:PAIS_ID, :NOMBRE)

SqlSetParamAsString (SqlHandle: Integer; ParamName, ParamValue: PChar): Integer; stdcall;


Descripcin Asigna un valor a un parmetro de tipo String del query de un objeto sql. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. ParamName. Nombre del parmetro. ParamValue. Valor a asignar al parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Sql actualmente abierto. 3 = Parmetro inexistente. Notas Esta funcin se utiliza antes de ejecutar el query de un Sql cuando ste contiene parmetros. El nombre del parmetro debe ser el mismo utilizado en el query sin incluir los :.

SqlSetParamAsDateTime (SqlHandle: Integer; ParamName: PChar; Day, Month, Year, Hour, Minute, Second: Word): Integer; stdcall;
Descripcin Asigna un valor a un parmetro de tipo Fecha, Hora, o Fecha_Hora del query de un objeto Sql. Parmetros DtstHandle. Nmero del objeto Sql a utilizar. ParamName. Nombre del parmetro. Day. Nmero de da del mes. Debe ser vlido para el mes y el ao dados. Month. Nmero de mes de la fecha. Debe estar entre 1 y 12. Year. Ao de la fecha. Debe estar entre 1 y 9999 Hour. Hora del da. Debe estar entre 0 y 23. Minute. Nmero de minuto. Debe estar entre 0 y 59. Second. Nmero de segundo. Debe estar entre 0 y 59. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Sql actualmente abierto. 3 = Parmetro inexistente. 4 = Valor incorrecto del parmetro. Notas Esta funcin se utiliza antes de ejecutar el query de un Sql cuando ste contiene parmetros. El nombre del parmetro debe ser el mismo utilizado en el query sin incluir los :. Cuando el parmetro del query es de tipo fecha, es decir, no lleva hora, pasar cero en los componentes de la hora. Cuando el parmetro del query es de tipo hora, es decir, no lleva fecha, pasar cero en los componentes de la fecha.

Api- Acceso bsico - Pgina 27 de 44

Api Acceso bsico Manual del programador SqlSetParamAsInteger (SqlHandle: Integer; ParamName: PChar; ParamValue: Integer): Integer; stdcall;
Descripcin Asigna un valor a un parmetro de tipo entero del query de un objeto Sql. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. ParamName. Nombre del parmetro. ParamValue. Valor a asignar al parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Sql actualmente abierto. 3 = Parmetro inexistente. Notas Esta funcin se utiliza antes de ejecutar el query de un Sql cuando ste contiene parmetros. El nombre del parmetro debe ser el mismo utilizado en el query sin incluir los :.

SqlSetParamAsDouble (SqlHandle: Integer; ParamName: PChar; ParamValue: Double): Integer; stdcall;


Descripcin Asigna un valor a un parmetro de tipo Double del query de un objeto Sql. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. ParamName. Nombre del parmetro. ParamValue. Valor a asignar al parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Sql actualmente abierto. 3 = Parmetro inexistente. Notas Esta funcin se utiliza antes de ejecutar el query de un Sql cuando ste contiene parmetros. El nombre del parmetro debe ser el mismo utilizado en el query sin incluir los :.

SqlSetParamAsMemo (SqlHandle: Integer; ParamName, ParamValue: PChar): Integer; stdcall;


Descripcin Asigna un valor a un parmetro de tipo String del query de un objeto sql, cuyo contenido puede ser multi-lneas, es decir, que puede contener saltos de lnea (caracteres 13 y 10). Parmetros SqlHandle. Nmero del objeto Sql a utilizar. ParamName. Nombre del parmetro. ParamValue. Valor a asignar al parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Sql actualmente abierto. 3 = Parmetro inexistente. Notas Esta funcin se utiliza antes de ejecutar el query de un Sql cuando ste contiene parmetros.

Api- Acceso bsico - Pgina 28 de 44

Api Acceso bsico Manual del programador


El nombre del parmetro debe ser el mismo utilizado en el query sin incluir los :.

SqlSetParamAsNull (SqlHandle: Integer; ParamName: PChar): Integer; stdcall;


Descripcin Asigna el valor Null a un parmetro del query de un objeto sql. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. ParamName. Nombre del parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Sql actualmente abierto. 3 = Parmetro inexistente. Notas Esta funcin se utiliza antes de ejecutar el query de un Sql cuando ste contiene parmetros y se desea hacer Null uno de ellos. El nombre del parmetro debe ser el mismo utilizado en el query sin incluir los :.

SqlExecQuery (SqlHandle: Integer): Integer; stdcall;


Descripcin Ejecuta el query de un objeto Sql, y si ste es de tipo Select, deja disponible el conjunto de registros resultantes del mismo para poder ser accesados mediante otras funciones de este API. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Base de datos aun no conectada 3 = Sql actualmente abierto. 4 = Query no asignado. 99 = Error de Firebird.

SqlClose (SqlHandle: Integer): Integer; stdcall;


Descripcin Ciarra el query y libera los recursos que ste ocupaba. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. Notas Si el Sql est actualmente cerrado, esta funcin no hace nada y regresa xito.

SqlNext (SqlHandle: Integer): Integer; stdcall;


Descripcin Avanza al siguiente registro resultante de un objeto Sql. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. Valor de retorno 0 = Operacin exitosa.

Api- Acceso bsico - Pgina 29 de 44

Api Acceso bsico Manual del programador


1 = Handle inexistente. 2 = Sql actualmente cerrado. Nota: este error se da tambin cuando el query ejecutado no es de tipo Select. 99 = Error de Firebird.

SqlEof (SqlHandle: Integer): Integer; stdcall;


Descripcin Indica si ya se lleg al final de los registros de un Sql durante la navegacin. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. Valor de retorno 0 = Falso (no se ha llegado al final) o hubo error (se debe checar el GetLastErrorCode). 1 = Verdadero (ya se lleg al final). Nota: este resultado se obtiene tambin cuando el query ejecutado no es de tipo Select o el Sql est cerrado. Errores 1 = Handle inexistente 99 = Error de Firebird.

SqlRecordCount (SqlHandle: Integer): Integer; stdcall;


Descripcin Regresa el nmero de registros que obtuvo el query de un objeto sql. Se usa slo cuando el query es de tipo Select. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. Valor de retorno 0..n = Nmero de registros. Se regresa 0 tambin si hubo error (checar el GetLastErrorCode). Errores 1 = Handle inexistente 2 = Sql actualmente cerrado. 3 = El query ejecutado no es de tipo Select. 99 = Error de Firebird. Notas Debido a que un objeto Sql es de ms bajo nivel (aunque ms eficiente que un dataset), en la implementacin interna de esta funcin, para poder contar los registros resultantes se debe cerrar el Sql, volverlo abrir, recorrer todos sus registros y finalmente, volverlo a abrir. Por esta razn puede resultar ms aficiente utilizar otro objeto Sql con un Select Count(*) para contar los registros. Al terminar la ejecucin de esta funcin, el registro actual del Sql ser el primero.

SqlGetFieldAsString (SqlHandle: Integer; FieldName, FieldValue: PChar): Integer; stdcall;


Descripcin Obtiene el valor de un campo de tipo String del registro actual de un Sql. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. FieldName. Nombre del campo. FieldValue. En este parmetro se regresa el valor actual del campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente.
Api- Acceso bsico - Pgina 30 de 44

Api Acceso bsico Manual del programador


2 = Sql actualmente cerrado. 3 = Campo inexistente.

SqlGetFieldAsDate (SqlHandle: Integer; FieldName: PChar; Var Day, Month, Year: Word): Integer; stdcall;
Descripcin Obtiene el valor de un campo de tipo Date del registro actual de un Sql. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. FieldName. Nombre del campo. Day, Month, Year. En estos parmetros se regresan los componentes de la fecha que contiene el campo actualmente. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Sql actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo Date.

SqlGetFieldAsTime (SqlHandle: Integer; FieldName: PChar; Var Hour, Minute, Second: Word): Integer; stdcall;
Descripcin Obtiene el valor de un campo de tipo Time del registro actual de un Sql. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. FieldName. Nombre del campo. Hour, Minute, Second. En estos parmetros se regresan los componentes de la hora que contiene el campo actualmente. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Sql actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo Time.

SqlGetFieldAsDateTime (SqlHandle: Integer; FieldName: PChar; Var Day, Month, Year, Hour, Minute, Second: Word): Integer; stdcall;
Descripcin Obtiene el valor de un campo de tipo DateTime del registro actual de un Sql. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. FieldName. Nombre del campo. Day, Month, Year, Hour, Minute, Second. En estos parmetros se regresan los componentes de la fecha y hora que contiene el campo actualmente. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Sql actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo DateTime.

Api- Acceso bsico - Pgina 31 de 44

Api Acceso bsico Manual del programador SqlGetFieldAsInteger (SqlHandle: Integer; FieldName: PChar; Var FieldValue: Integer): Integer; stdcall;
Descripcin Obtiene el valor de un campo de tipo Integer del registro actual de un Sql. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. FieldName. Nombre del campo. FieldValue. En este parmetro se regresa el valor actual del campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Sql actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo Integer.

SqlGetFieldAsDouble (SqlHandle: Integer; FieldName: PChar; Var FieldValue: Double): Integer; stdcall;
Descripcin Obtiene el valor de un campo de tipo Double del registro actual de un Sql. Parmetros SqlHandle. Nmero del objeto Sql a utilizar. FieldName. Nombre del campo. FieldValue. En este parmetro se regresa el valor actual del campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Sql actualmente cerrado. 3 = Campo inexistente. 4 = Campo no es tipo Double.

SqlGetFieldAsMemo (SqlHandle: Integer; FieldName, FieldValue: PChar): Integer; stdcall;


Descripcin Obtiene el valor de un campo de tipo String del registro actual de un sql cuyo contenido puede ser multi-lneas, es decir, que puede contener saltos de lnea (caracteres 13 y 10). Parmetros SqlHandle. Nmero del objeto Sql a utilizar. FieldName. Nombre del campo. FieldValue. En este parmetro se regresa el valor actual del campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Sql actualmente cerrado. 3 = Campo inexistente.

Api- Acceso bsico - Pgina 32 de 44

Api Acceso bsico Manual del programador

Objeto Stored procedure


NewSp (TrnHandle: Integer): Integer; stdcall;
Descripcin Crea un nuevo objeto StoredProc. Parmetros TrnHandle. Nmero del objeto Transaction bajo el cual se harn los accesos del stored procedure. Valor de retorno 1..n = Handle del nuevo objeto. 0 = Hubo error. Se debe checar GetLastErrorCode Errores 1 = Handle de transaccin inexistente

SpCount: Integer; stdcall;


Descripcin Regresa el nmero de objetos StoredProc creados hasta el momento, incluyendo el que se crea automticamente. Los nmeros de estos objetos van del 0 al SpCount-1, por ejemplo, si existen 3 objetos, sus nmeros de handle van del 0 al 2.

SpConfig (SpHandle, TrnHandle: Integer): Integer; stdcall;


Descripcin Modifica la transaccin a la que estar ligado un StoredProc. Se usa por ejemplo cuando se desea reutilizar un StoredProc dentro de un mismo programa pero bajo otra transaccin diferente a la de su creacin (y probablemente sobre otra base de datos). Parmetros SpHandle. Nmero del objeto de sp a configurar. TrnHandle. Nmero de objeto de transaccin al que se desea ligar el sql. Valor de retorno 0 = Operacin exitosa. 1 = Handle de sql inexistente. 2 = Handle de transaccin inexistente. 3 = Sql actualmente abierto. Notas tcnicas Asignar a la propiedad Database del sp la base de datos asociada con la transaccin dada.

SpName (SpHandle: Integer; ProcName: PChar): Integer; stdcall;


Descripcin Establece el nombre del stored procedure a ejecutar en un objeto StoredProc. Parmetros SpHandle. Nmero del objeto StoredProc a utilizar. ProcName. Nombre del stored procedure. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Base de datos aun no conectada 99 = Stored procedure no existe en la base de datos.

Api- Acceso bsico - Pgina 33 de 44

Api Acceso bsico Manual del programador


Notas El stored procedure debe ser del tipo Execute, es decir, no debe ser de los que regresan un conjunto de registros. El stored procedure puede requerir parmetros para su ejecucin, a los cuales se les da valor antes de ejecutarlo, por medio de las funciones SpSetParamAs....

SpSetParamAsString (SpHandle: Integer; ParamName, ParamValue: PChar): Integer; stdcall;


Descripcin Asigna un valor a un parmetro de entrada de tipo String del stored procedure de un objeto StoredProc. Parmetros SpHandle. Nmero del objeto StoredProc a utilizar. ParamName. Nombre del parmetro. ParamValue. Valor a asignar al parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Nombre del stored procedure aun no asignado. 3 = Parmetro inexistente. 4 = Parmetro no es de entrada. Notas Esta funcin se utiliza antes de ejecutar el stored procedure de un Sp cuando ste contiene parmetros de entrada.

SpSetParamAsDateTime (SpHandle: Integer; ParamName: PChar; Day, Month, Year, Hour, Minute, Second: Word): Integer; stdcall;
Descripcin Asigna un valor a un parmetro de entrada de tipo Fecha, Hora, o Fecha_Hora del stored procedure de un objeto StoredProc. Parmetros SpHandle. Nmero del objeto StoredProc a utilizar. ParamName. Nombre del parmetro. Day. Nmero de da del mes. Debe ser vlido para el mes y el ao dados. Month. Nmero de mes de la fecha. Debe estar entre 1 y 12. Year. Ao de la fecha. Debe estar entre 1 y 9999 Hour. Hora del da. Debe estar entre 0 y 23. Minute. Nmero de minuto. Debe estar entre 0 y 59. Second. Nmero de segundo. Debe estar entre 0 y 59. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Nombre del stored procedure aun no asignado. 3 = Parmetro inexistente. 4 = Parmetro no es de entrada. 5 = Valor incorrecto del parmetro. Notas Esta funcin se utiliza antes de ejecutar el stored procedure de un StoredProc cuando ste contiene parmetros de entrada. Cuando el parmetro es de tipo fecha, es decir, no lleva hora, pasar cero en los componentes de la hora.
Api- Acceso bsico - Pgina 34 de 44

Api Acceso bsico Manual del programador


Cuando el parmetro es de tipo hora, es decir, no lleva fecha, pasar cero en los componentes de la fecha.

SpSetParamAsInteger (SpHandle: Integer; ParamName: PChar; ParamValue: Integer): Integer; stdcall;


Descripcin Asigna un valor a un parmetro de entrada de tipo entero del stored procedure de un objeto StoredProc. Parmetros SpHandle. Nmero del objeto StoredProc a utilizar. ParamName. Nombre del parmetro. ParamValue. Valor a asignar al parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Nombre del stored procedure aun no asignado. 3 = Parmetro inexistente. 4 = Parmetro no es de entrada. Notas Esta funcin se utiliza antes de ejecutar el stored procedure de un StoredProc cuando ste contiene parmetros de entrada.

SpSetParamAsDouble (SpHandle: Integer; ParamName: PChar; ParamValue: Double): Integer; stdcall;


Descripcin Asigna un valor a un parmetro de entrada de tipo Double del stored procedure de un objeto StoredProc. Parmetros SpHandle. Nmero del objeto StoredProc a utilizar. ParamName. Nombre del parmetro. ParamValue. Valor a asignar al parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Nombre del stored procedure aun no asignado. 3 = Parmetro inexistente. 4 = Parmetro no es de entrada. Notas Esta funcin se utiliza antes de ejecutar el stored procedure de un StoredProc cuando ste contiene parmetros de entrada.

SpSetParamAsNull (SpHandle: Integer; ParamName: PChar): Integer; stdcall;


Descripcin Asigna el valor Null a un parmetro de entrada del stored procedure de un objeto StoredProc. Parmetros SpHandle. Nmero del objeto StoredProc a utilizar. ParamName. Nombre del parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente.

Api- Acceso bsico - Pgina 35 de 44

Api Acceso bsico Manual del programador


2 = Nombre del stored procedure aun no asignado. 3 = Parmetro inexistente. 4 = Parmetro no es de entrada. Notas Esta funcin se utiliza antes de ejecutar el stored procedure de un Sp cuando ste contiene parmetros de entrada y se desea hacer Null uno de ellos.

SpExecProc (SpHandle: Integer): Integer; stdcall;


Descripcin Ejecuta el Stored Procedure de un objeto StoredProc asignado previamente Parmetros SpHandle. Nmero del objeto StoredProc a utilizar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Base de datos aun no conectada 3 = Nombre del Stored Procedure aun no asignado 99 = Error de Firebird.

SpGetParamAsString (SpHandle: Integer; ParamName, ParamValue: PChar): Integer; stdcall;


Descripcin Obtiene el valor de un parmetro de salida de tipo String del stored procedure de un objeto StoredProc. Parmetros SpHandle. Nmero del objeto StoredProc a utilizar. ParamName. Nombre del parmetro. ParamValue. En este parmetro se regresa el valor actual del campo. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Nombre del stored procedure aun no asignado. 3 = Parmetro inexistente. 4 = Parmetro no es de salida.

SpGetParamAsDate (SpHandle: Integer; ParamName: PChar; Var Day, Month, Year: Word): Integer; stdcall;
Descripcin Obtiene el valor de un parmetro de salida de tipo Date del stored procedure de un objeto StoredProc. Parmetros SpHandle. Nmero del objeto StoredProc a utilizar. ParamName. Nombre del parmetro. Day, Month, Year. En estos parmetros se regresan los componentes de la fecha que contiene el parmetro actualmente. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Nombre del stored procedure aun no asignado. 3 = Parmetro inexistente.

Api- Acceso bsico - Pgina 36 de 44

Api Acceso bsico Manual del programador


4 = Parmetro no es de salida. 5 = Parmetro no es tipo Date.

SpGetParamAsTime (SpHandle: Integer; ParamName: PChar; Var Hour, Minute, Second: Word): Integer; stdcall;
Descripcin Obtiene el valor de un parmetro de salida de tipo Time del stored procedure de un objeto StoredProc. Parmetros SpHandle. Nmero del objeto StoredProc a utilizar. ParamName. Nombre del parmetro. Hour, Minute, Second. En estos parmetros se regresan los componentes de la hora que contiene el parmetro actualmente. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Nombre del stored procedure aun no asignado. 3 = Parmetro inexistente. 4 = Parmetro no es de salida. 5 = Parmetro no es tipo Time.

SpGetParamAsDateTime (SpHandle: Integer; ParamName: PChar; Var Day, Month, Year, Hour, Minute, Second: Word): Integer; stdcall;
Descripcin Obtiene el valor de un parmetro de salida de tipo DateTime del stored procedure de un objeto StoredProc. Parmetros SpHandle. Nmero del objeto StoredProc a utilizar. ParamName. Nombre del parmetro. Day, Month, Year, Hour, Minute, Second. En estos parmetros se regresan los componentes de la fecha y hora que contiene el parmetro actualmente. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Nombre del stored procedure aun no asignado. 3 = Parmetro inexistente. 4 = Parmetro no es de salida. 5 = Parmetro no es tipo DateTime.

SpGetParamAsInteger (SpHandle: Integer; ParamName: PChar; Var ParamValue: Integer): Integer; stdcall;
Descripcin Obtiene el valor de un parmetro de salida de tipo Integer del stored procedure de un objeto StoredProc. Parmetros SpHandle. Nmero del objeto StoredProc a utilizar. ParamName. Nombre del parmetro. ParamValue. En este parmetro se regresa el valor actual del parmetro. Valor de retorno 0 = Operacin exitosa.

Api- Acceso bsico - Pgina 37 de 44

Api Acceso bsico Manual del programador


1 = Handle inexistente. 2 = Nombre del stored procedure aun no asignado. 3 = Parmetro inexistente. 4 = Parmetro no es de salida. 5 = Parmetro no es tipo Integer.

SpGetParamAsDouble (SpHandle: Integer; ParamName: PChar; Var ParamValue: Double): Integer; stdcall;
Descripcin Obtiene el valor de un parmetro de salida de tipo Double del stored procedure de un objeto StoredProc. Parmetros SpHandle. Nmero del objeto StoredProc a utilizar. ParamName. Nombre del parmetro. ParamValue. En este parmetro se regresa el valor actual del parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = Nombre del stored procedure aun no asignado. 3 = Parmetro inexistente. 4 = Parmetro no es de salida. 5 = Parmetro no es tipo Double.

Api- Acceso bsico - Pgina 38 de 44

Api Acceso bsico Manual del programador

Objeto SemaforoMsp
NewSem (DBHandle: Integer): Integer; stdcall;
Descripcin Crea un nuevo objeto de tipo SemaforoMsp. Parmetros DBHandle. Nmero del objeto Database sobre cuya base de datos Microsip se usarn los semforos. Valor de retorno 0..n = Handle del nuevo objeto. 0 = Hubo error. Se debe checar GetLastErrorCode. Errores 1 = Handle de base de datos inexistente.

SemCount: Integer; stdcall;


Descripcin Regresa el nmero de objetos SemaforoMsp creados hasta el momento. Los nmeros de estos objetos van del 0 al SemCount-1, por ejemplo, si existen 3 objetos, sus nmeros de handle van del 0 al 2.

SemGetSemaforos(SemHandle: Integer; NombresSemaforos: PChar): Integer; stdcall;


Descripcin Toma los semforos indicados. Si alguno est actualmente ocupado, espera a que ste se libere. Esta funcin regresa hasta que obtenga todos los semforos indicados. Si hay semforos actualmente tomados, stos se liberan antes de tomar los nuevos. Parmetros SemHandle. Nmero del objeto SemaforoMsp a utilizar. NombresSemaforos. Es la lista de nombres de semforos a tomar separados por comas. Ejemplo: INVENTARIOS,VENTAS. Valor de retorno 0 = Toma de semforos exitosa. 1 = Handle inexistente. 2 = Base de datos aun no asignada. 3 = Conexin a la base de datos aun no establecida. 4 = Semforos no indicados. Notas Los nombres de los semforos son convenciones entre aplicaciones. Checar con Microsip los nombres de sus semforos.

SemRelSemaforos(SemHandle: Integer): Integer; stdcall;


Descripcin Libera los semforos que se tengan tomados actualmente con el objeto indicado. Si no hay semforos tomados esta funcin no hace nada, es decir, no se marca error. Parmetros SemHandle. Nmero del objeto SemaforoMsp a utilizar. Valor de retorno 0 = Liberacin de semforos exitosa.

Api- Acceso bsico - Pgina 39 de 44

Api Acceso bsico Manual del programador


1 = Handle inexistente. 2 = Base de datos aun no asignada. 3 = Conexin a la base de datos aun no establecida.

SemGetSemaforoNoWait(SemHandle: Integer; NombreSemaforo: PChar): Integer; stdcall;


Descripcin Toma el semforo indicado, si ste est ocupado regresa inmediatamente sin esperar a que se libere. Si hay semforos actualmente tomados, stos se liberan antes de tomar el nuevo. Parmetros SemHandle. Nmero del objeto SemaforoMsp a utilizar. NombreSemaforo. Es el nombre del semforo a tomar. Ejemplo: INVENTARIOS. Valor de retorno 0 = Toma de semforo exitosa. 1 = Handle inexistente. 2 = Base de datos aun no asignada. 3 = Conexin a la base de datos aun no establecida. 4 = Semforo no indicado. 5 = Semforo ocupado.

SemConfig (SemHandle, DBHandle: Integer): Integer; stdcall;


Descripcin Modifica la base de datos a la que estar ligado un SemaforoMsp. Se usa por ejemplo cuando se desea reutilizar un objeto SemaforoMsp dentro de un mismo programa pero bajo otra base de datos diferente a la de su creacin. Parmetros SemHandle. Nmero del objeto SemaforoMsp a configurar. DBHandle. Nmero de objeto Database al que se desea ligar el objeto SemaforoMsp. Valor de retorno 0 = Operacin exitosa. 1 = Handle de semforo inexistente. 2 = Handle de base de datos inexistente.

Api- Acceso bsico - Pgina 40 de 44

Api Acceso bsico Manual del programador

Objeto Lista de parmetros


NewPL: Integer; stdcall;
Descripcin Crea una nueva lista de parmetros. Valor de retorno Regresa el Handle del nuevo objeto.

PLCount: Integer; stdcall;


Descripcin Regresa el nmero de listas de parmetros existentes.

PLParamCount (PLHandle, var ParamCount: Integer): Integer; stdcall;


Descripcin
Regresa el nmero de parmetros que contiene una lista.

Parmetros PLHandle. Nmero del objeto de la lista de parmetros. ParamCount. En este parmetro se regresa el nmero de elementos que contiene la lista. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente.

PLSetParamValue (PLHandle: Integer; ParamName, ParamValue: PChar): Integer; Stdcall;


Descripcin Establece el valor de un parmetro de la lista. Si an no existe el parmetro, ste se agrega a la lista. Parmetros PLHandle. Nmero del objeto de la lista de parmetros. ParamName. Nombre del parmetro. ParamValue. Valor que se desea asignar al parmetro Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. Ejemplo Supongamos que una funcin que deseamos llamar tiene la siguiente definicin: function EnviaCorreo(ParamListHandle: Integer): Integer; Y requiere que la lista de parmetros contenga USUARIO, PASSWORD y PUERTO. Los pasos para llamar a la funcin son los siguientes: Creamos el objeto de lista de parmetros PLHandle := NewPL; Agregamos los parmetros a la lista PLSetParamValue(PLHandle, USUARIO,pedro@hotmail.com); PLSetParamValue(PLHandle, PASSWORD,abc123); PLSetParamValue(PLHandle, PUERTO,25); Llamamos a la funcin Result := EnviaCorreo(PLHandle);

Api- Acceso bsico - Pgina 41 de 44

Api Acceso bsico Manual del programador PLGetParamValue (PLHandle: Integer; ParamName, ParamValue: PChar): Integer; Stdcall.
Descripcin Obtiene el valor de un parmetro de la lista dado su nombre, si no existe el parmetro, se regresa un string vaco. Parmetros PLHandle. Nmero del objeto de la lista de parmetros. ParamName. Nombre del parmetro. ParamValue. En este parmetro se regresa el valor actual del parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente.

PLGetParamName (PLHandle , Index: Integer; ParamName: PChar): Integer; Stdcall.


Descripcin
Obtiene el nombre del parmetro con el ndice indicado. Los parmetros de una lista estn numerados del 0 al N-1, donde N es el nmero de elementos de la lista.

Parmetros PLHandle. Nmero del objeto de la lista de parmetros. Index. Indica el ndice del parmetro. ParamName. En este parmetro se regresa el nombre del parmetro. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente. 2 = ndice fuera de rango.

PLDeleteParam (PLHandle: Integer; AParamName: PChar): Integer; Stdcall.


Descripcin Elimina de la lista un parmetro, si no existe el parmetro, no hace nada. Parmetros PLHandle. Nmero del objeto de la lista de parmetros. ParamName. Nombre del parmetro a eliminar. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente.

PLClear(PLHandle: Integer): Integer; Stdcall.


Descripcin
Elimina todos los parmetros de la lista.

Parmetros PLHandle. Nmero del objeto de la lista de parmetros. Valor de retorno 0 = Operacin exitosa. 1 = Handle inexistente.

Api- Acceso bsico - Pgina 42 de 44

Api Acceso bsico Manual del programador

Liberacin de recursos
Es importante que, antes de terminar su ejecucin, el programa libere las recursos que utiliz de las Apis Microsip, ya que de lo contrario ste puede terminar anormalmente mostrando mensajes de error.

LiberarRecursos; stdcall;
Descripcin Libera los recursos utilizados por la Api bsica y por las dems Apis especializadas que se hayan utilizado en el programa.

Api- Acceso bsico - Pgina 43 de 44

Api Acceso bsico Manual del programador

Licencia de la Api Microsip


Para utilizar la Api Microsip desde una aplicacin, es necesario que exista la licencia correspondiente en el candado del usuario. La existencia de la licencia se checa cuando se llama a la funcin DBConnect no habiendo ninguna base de datos conectada. Si no existe la licencia en el candado, o todas estn siendo utilizadas en ese momento, se obtiene un mensaje de error y la conexin no se realiza. Igualmente, al llamar a la funcin DBDisconnect, si ya no quedan ms bases de datos conectadas, se libera la licencia que se estaba utilizando. En un ambiente multiusuario, si la aplicacin termina su ejecucin y no se desconecta de las bases de datos que estaba utilizando, la licencia no se liberar e impedir que otro usuario la reutilice.

Api- Acceso bsico - Pgina 44 de 44