Función JetCreateInstance

Artículo
06/13/2023

Se aplica a: Windows | Windows Server

Función JetCreateInstance

La función JetCreateInstance asigna una nueva instancia del motor de base de datos para su uso en un único proceso.

Windows XP: JetCreateInstance se introduce en Windows XP.

    JET_ERR JET_API JetCreateInstance(
      __out         JET_INSTANCE* pinstance,
      __in_opt      const tchar* szInstanceName
    );

Parámetros

pinstance

Búfer de salida que recibe la instancia recién creada.

szInstanceName

Identificador de cadena único para la instancia que se va a crear. Esta cadena debe ser única dentro de un proceso determinado que hospeda el motor de base de datos.

Nota Un valor NULL se trata como un identificador de cadena válido para una instancia de . Solo una instancia puede tener un identificador de cadena NULL.

Valor devuelto

Esta función devuelve el tipo de datos JET_ERR con uno de los siguientes códigos de retorno. Para obtener más información sobre los posibles errores de ESE, vea Extensible Storage Engine Errors and Error Handling Parameters.

Código devuelto	Descripción
JET_errSuccess	La operación se ha completado correctamente.
JET_errInstanceNameInUse	El nombre de instancia especificado ya está en uso para este proceso.
JET_errInvalidParameter	Uno de los parámetros proporcionados contenía un valor inesperado o contenía un valor que no tenía sentido cuando se combinaba con el valor de otro parámetro. Esto puede ocurrir para JetCreateInstance cuando la pinstancia es NULL.
JET_errRunningInOneInstanceMode	Error en la operación porque no se puede usar cuando el motor de base de datos funciona en modo de instancia única (modo de compatibilidad de Windows 2000).
JET_errTooManyInstances	No se pudo crear una nueva instancia porque se ha alcanzado el número máximo de instancias. El número máximo de instancias admitidas se configura mediante JetSetSystemParameter mediante JET_paramMaxInstances.

Si se ejecuta correctamente, se asignará una nueva instancia y se devolverá el identificador para ella. En este momento, todos los parámetros del sistema de la instancia tendrán los valores de los parámetros del sistema predeterminados globales. Una vez que se asigne una instancia, debe finalizarse o liberarse más adelante.

En caso de error, se devolverá un error que representa la causa del error y no se asignará ninguna instancia.

Comentarios

Una instancia debe inicializarse con una llamada a JetInit antes de que pueda usarse con cualquier otra cosa que no sea JetSetSystemParameter.

Una instancia se destruye mediante una llamada a la función JetTerm , incluso si esa instancia nunca se inicializó mediante JetInit. El número máximo de instancias que se pueden crear en cualquier momento se controla mediante JET_paramMaxInstances, que se puede configurar mediante una llamada a JetSetSystemParameter. Una instancia es la unidad de capacidad de recuperación para el motor de base de datos. Controla el ciclo de vida de todos los archivos utilizados para proteger la integridad de los datos en un conjunto de archivos de base de datos. Estos archivos incluyen el archivo de punto de comprobación y los archivos de registro de transacciones.

Si la función se realiza correctamente, el motor de base de datos se cambiará automáticamente al modo de varias instancias como efecto secundario de esta llamada. Si la aplicación desea permitir solo una instancia en el proceso, JetInit debe usarse para iniciar el motor de base de datos en el modo de compatibilidad de Windows 2000.

Si está presente, se usará szDisplayName para identificar la instancia en lugares como registro de eventos o hacia otros autores de llamadas, como aplicaciones de copia de seguridad (a través de funciones como JetGetInstanceInfo o JetOSSnapshotFreeze). Si no se proporciona el nombre para mostrar, se usará szInstanceName único en su lugar si está presente; de lo contrario, se devolverá una cadena vacía. Si el motor no tiene establecido el modo en ejecución, después de esta llamada, se establecerá en modo de varias instancias.

La secuencia de inicio típica para un proceso que podría ejecutar varias instancias de Jet sería:

Una llamada a JetCreateInstance2 que asignará y asignará el nombre de la instancia.
Varias llamadas a JetSetSystemParameter para esa instancia para establecer distintos parámetros del sistema. Tenga en cuenta que algunos parámetros del sistema deben ser únicos por instancia (como JET_paramSystemPath o JET_paramLogFilePath), por lo que lo más probable es que tenga que establecer cada uno de ellos.
Inicie la instancia mediante JetInit o JetInit2. Para finalizar o liberar una instancia, se debe usar JetTerm, JetTerm2 .

Si se trata de la primera instancia que se va a iniciar, hay una serie de pasos adicionales que se ejecutarán durante esta llamada para realizar la inicialización y configuración básicas del sistema. Algunos de esos pasos pueden dar lugar a errores específicos a partir de JET_errOutOfMemory pero también otros (consulte los errores anteriores).

Requisitos

Requisito	Value
Cliente	Requiere Windows Vista o Windows XP.
Servidor	Requiere Windows Server 2008 o Windows Server 2003.
Encabezado	Declarado en Esent.h.
Library	Use ESENT.lib.
Archivo DLL	Requiere ESENT.dll.
Unicode	Se implementa como JetCreateInstanceW (Unicode) y JetCreateInstanceA (ANSI).

Consulte también

Archivos extensibles del motor de almacenamiento
JET_ERR
JET_INSTANCE
JetCreateInstance2
JetEnableMultiInstance
JetGetInstanceInfo
JetInit
JetInit2
JetOSSnapshotFreeze
JetSetSystemParameter
JetTerm
JetTerm2

Función JetCreateInstance