Función JetCreateInstance2

Se aplica a: Windows | Windows Server

Función JetCreateInstance2

La función JetCreateInstance2 se usa para asignar una nueva instancia del motor de base de datos para su uso en un único proceso, con un nombre para mostrar especificado.

Windows XP:JetCreateInstance2 se presenta en Windows XP.

    JET_ERR JET_API JetCreateInstance2(
      __out         JET_INSTANCE* pinstance,
      __in_opt      const tchar* szInstanceName,
      __in_opt      const tchar* szDisplayName,
      __in          JET_GRBIT grbit
    );

Parámetros

pinstance

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

szInstanceName

Especifica un 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.

szDisplayName

Nombre para mostrar de la instancia que se va a crear. Cuando este parámetro no está presente, se supone que su valor es NULL.

grbit

Reservado para uso futuro. Cuando este parámetro no está presente, se supone que su valor es cero.

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.

Observaciones

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, el parámetro szDisplayName se usará 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á el parámetro szInstanceName único en su lugar, si está presente, 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 para cada instancia (como JET_paramSystemPath o JET_paramLogFilePath), por lo que es más probable que sea necesario establecer cada uno de ellos.

• Inicie la instancia mediante JetInit o JetInit2. Para finalizar o liberar una instancia, use JetTerm o 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. Varios de esos pasos pueden dar lugar a errores específicos a partir de JET_errOutOfMemory pero también otros (consulte Valores devueltos para obtener más información).

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 JetCreateInstance2W (Unicode) y JetCreateInstance2A (ANSI).

Consulte también

JET_ERR
JET_INSTANCE
JetCreateInstance
JetEnableMultiInstance
JetGetInstanceInfo
JetInit
JetInit2
JetOSSnapshotFreeze
JetSetSystemParameter
JetTerm
JetTerm2