Usar tokens en pasos de trabajos
El Agente SQL Server le permite usar tokens en scripts de pasos de trabajo de Transact-SQL. La utilización de tokens al escribir pasos de trabajo ofrece la misma flexibilidad que las variables al escribir programas de software. Una vez que se inserta un token en un script de pasos de trabajo, el Agente SQL Server sustituye el token en tiempo de ejecución, antes de que el subsistema de Transact-SQL ejecute el paso de trabajo.
.gif "Nota importante") Importante |
|---|
A partir de SQL Server 2005 Service Pack 1, la sintaxis del token del paso de trabajo del Agente SQL Server ha cambiado. Como resultado, todos los tokens que se usan en pasos de trabajo deben adjuntar ahora una macro de escape; de lo contrario, esos pasos de trabajo producirán un error. El uso de las macros de escape y la actualización de pasos de trabajo del Agente SQL Server que usa tokens se describen en las secciones siguientes, "Descripción del uso de tokens", "Tokens y macros del Agente SQL Server" y "Actualizar pasos de trabajo para usar macros". Además, también ha cambiado la sintaxis de SQL Server 2000, que usaba corchetes para llamar a los tokens de pasos de trabajo del Agente SQL Server (por ejemplo, "[DATE]"). Ahora debe delimitar los nombres de los tokens entre paréntesis y colocar un signo de dólar ($) al principio de la sintaxis del token. Por ejemplo: $(ESCAPE_macro name(DATE)) |
Descripción del uso de tokens
.gif "Nota de seguridad") Nota de seguridad |
|---|
Todos los usuarios de Windows que tengan permisos de escritura en el Registro de eventos de Windows pueden tener acceso a los pasos de trabajo activados por alertas del Agente SQL Server o de WMI. Para evitar este riesgo de seguridad, los tokens del Agente SQL Server que se pueden utilizar en los trabajos activados por alertas están deshabilitados de forma predeterminada. Estos tokens son: A-DBN, A-SVR, A-ERR, A-SEV, A-MSG y WMI(property). Tenga en cuenta que en esta versión el uso de los tokens se ha ampliado a todas las alertas. Si necesita usar estos tokens, asegúrese primero de que solo los miembros de los grupos de seguridad de Windows de confianza, como el grupo Administradores, tienen permisos de escritura en el registro de eventos del equipo donde reside SQL Server. A continuación, para habilitar estos tokens, haga clic con el botón secundario en Agente SQL Server en el Explorador de objetos, elija Propiedades y, en la página Sistema de alerta, active la casilla Reemplazar tokens para todas las respuestas de trabajos a alertas. |
La sustitución del token del Agente SQL Server es sencilla y eficaz: el Agente SQL Server reemplaza el token por un valor literal de cadena exacto. Todos los tokens distinguen mayúsculas de minúsculas. Los pasos de trabajo deben tenerlo en cuenta y citar correctamente los tokens utilizados o convertir la cadena de reemplazo al tipo de datos correcto.
Por ejemplo, se puede usar la siguiente instrucción para imprimir el nombre de la base de datos en un paso de trabajo:
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
En este ejemplo, la macro ESCAPE_SQUOTE se inserta con el token A-DBN. En tiempo de ejecución, el nombre de la base de datos apropiada sustituirá al token A-DBN La macro de escape convierte cualquier comilla simple que se pueda pasar de forma inadvertida en la cadena de reemplazo del token. El Agente SQL Server reemplazará una comilla simple con dos comillas simples en la cadena final.
Por ejemplo, si la cadena que se pasa para reemplazar al token es AdventureWorks2012'SELECT @@VERSION --, el comando que ejecuta el paso de trabajo del Agente SQL Server será:
PRINT N'Current database name is AdventureWorks2012''SELECT @@VERSION --' ;
En este caso, la instrucción insertada, SELECT @@VERSION, no se ejecuta. En su lugar, la comilla simple adicional hace que el servidor analice la instrucción insertada como una cadena. Si la cadena de reemplazo del token no contiene una comilla simple, no se convierte ninguno de los caracteres y el paso de trabajo que contiene el token se ejecutará como se espera.
Para depurar el uso de tokens en pasos de trabajo, utilice instrucciones de impresión como, por ejemplo, PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' y guarde la salida del paso de trabajo en un archivo o una tabla. Use la página Avanzadas del cuadro de diálogo Propiedades de paso de trabajo para especificar un archivo o tabla de salida del paso de trabajo.
Tokens y macros del Agente SQL Server
En las siguientes tablas se indican y describen los tokens y macros compatibles con el Agente SQL Server.
Tokens del Agente SQL Server
Token |
Descripción |
|---|---|
(A-DBN) |
Nombre de base de datos. Si el trabajo se ejecuta a causa de una alerta, el valor del nombre de la base de datos sustituye automáticamente a este token en el paso de trabajo. |
(A-SVR) |
Nombre de servidor. Si el trabajo se ejecuta a causa de una alerta, el valor del nombre del servidor sustituye automáticamente a este token en el paso de trabajo. |
(A-ERR) |
Número de error Si el trabajo se ejecuta a causa de una alerta, el valor del número de error sustituye automáticamente a este token en el paso de trabajo. |
(A-SEV) |
Gravedad del error. Si el trabajo se ejecuta a causa de una alerta, el valor de la gravedad del error sustituye automáticamente a este token en el paso de trabajo. |
(A-MSG) |
Texto del mensaje. Si el trabajo se ejecuta a causa de una alerta, el valor del texto del mensaje sustituye automáticamente a este token en el paso de trabajo. |
(DATE) |
Fecha actual (en formato AAAAMMDD). |
(INST) |
Nombre de instancia. Para una instancia predeterminada, este token tendrá el nombre de instancia predeterminado: MSSQLSERVER. |
(JOBID) |
Identificador del trabajo. |
(MACH) |
Nombre del equipo. |
(MSSA) |
Nombre del servicio SQLServerAgent maestro. |
(OSCMD) |
Prefijo del programa usado para ejecutar los pasos de trabajo CmdExec. |
(SQLDIR) |
Directorio en el que se instala SQL Server. El directorio predeterminado es C:\Archivos de programa\Microsoft SQL Server\MSSQL. |
(STEPCT) |
Contador del número de veces que se ha ejecutado este paso (sin incluir los reintentos). Lo puede utilizar el comando del paso para forzar la terminación de un bucle de múltiples pasos. |
(STEPID) |
Id. del paso. |
(SRVR) |
Nombre del equipo en el que se ejecuta SQL Server. Si la instancia de SQL Server es una instancia con nombre, incluye el nombre. |
(TIME) |
Hora actual (en formato HHMMSS). |
(STRTTM) |
La hora (en formato HHMMSS) en la que el trabajo empezó a ejecutarse. |
(STRTDT) |
La fecha (en formato AAAAMMDD) en la que el trabajo empezó a ejecutarse. |
(WMI(property)) |
Para los trabajos que se ejecutan en respuesta a las alertas de WMI, es el valor de la propiedad especificado por property. Por ejemplo, $(WMI(DatabaseName)) proporciona el valor de la propiedad DatabaseName del evento WMI que provocó la ejecución de la alerta. |
Macros de escape del Agente SQL Server
Macros de escape |
Descripción |
|---|---|
$(ESCAPE_SQUOTE(token_name)) |
Convierte las comillas simples (') en la cadena de reemplazo del token. Sustituye una comilla simple por dos comillas simples. |
$(ESCAPE_DQUOTE(token_name)) |
Convierte las comillas dobles ('') en la cadena de reemplazo del token. Sustituye una comilla doble por dos comillas dobles. |
$(ESCAPE_RBRACKET(token_name)) |
Convierte los corchetes de cierre (]) en la cadena de reemplazo del token. Sustituye un corchete de cierre por dos corchetes de cierre. |
$(ESCAPE_NONE(token_name)) |
Sustituye el token sin convertir ninguno de los caracteres de la cadena. Se incluye esta macro para la compatibilidad con versiones anteriores en entornos donde las cadenas de reemplazo de tokens se esperan únicamente de usuarios de confianza. Para obtener más información, vea "Actualizar pasos de trabajo para usar macros" más adelante en este tema. |
Actualizar pasos de trabajo para usar macros
A partir de SQL Server 2005 Service Pack 1, los pasos de trabajo que contienen tokens sin macros de escape producirán un error y devolverán un mensaje de error indicando que el paso de trabajo contiene uno o más tokens que deben actualizarse con una macro antes de poder ejecutar el trabajo.
El artículo 915845 de Microsoft Knowledge Base SQL Server Agent Job Steps That Use Tokens Fail in SQL Server 2005 Service Pack 1 proporciona un script que puede utilizar para actualizar todos los pasos de trabajo que usan tokens con la macro ESCAPE_NONE. Después de usar el script, se recomienda revisar cuanto antes los pasos de trabajo que usan tokens y sustituir la macro ESCAPE_NONE por una macro de escape apropiada para el contexto del paso de trabajo.
La tabla siguiente describe cómo el Agente SQL Server administra el reemplazo de los tokens. Para habilitar o deshabilitar la alerta de sustitución de los tokens, haga clic con el botón secundario en Agente SQL Server en el Explorador de objetos, elija Propiedades y, en la página Sistema de alerta, active o desactive la casilla Reemplazar tokens para todas las respuestas de trabajos a alertas.
Sintaxis de los tokens |
Alerta de sustitución de tokens activada |
Alerta de sustitución de tokens desactivada |
|---|---|---|
Macro ESCAPE utilizada |
Todos los tokens de los trabajos se han sustituido correctamente. |
Los tokens activados por alertas no se han sustituido. Estos tokens son A-DBN, A-SVR, A-ERR, A-SEV, A-MSG y WMI(property). Otros tokens estáticos se han sustituido correctamente. |
Macro ESCAPE no utilizada |
Los trabajos que contienen tokens producen un error. |
Los trabajos que contienen tokens producen un error. |
Ejemplos de actualización de la sintaxis del token
A.Usar tokens en cadenas no anidadas
En el siguiente ejemplo se muestra cómo actualizar un script simple no anidado con la macro de escape apropiada. Antes de ejecutar el script de actualización, el siguiente script de paso de trabajo usa un token de paso de trabajo para imprimir el nombre de la base de datos apropiada:
PRINT N'Current database name is $(A-DBN)' ;
Después de ejecutar el script de actualización, se inserta una macro ESCAPE_NONE antes del token A-DBN. Debido a que se utilizan comillas simples para delimitar la cadena de impresión, se debe actualizar el paso de trabajo mediante la inserción de la macro ESCAPE_SQUOTE, del siguiente modo:
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
B.Usar tokens en cadenas anidadas
En scripts de pasos de trabajo donde se utilizan tokens en cadenas o instrucciones anidadas, éstas deben volver a escribirse como varias instrucciones antes de insertarse en las macros de escape apropiadas.
Por ejemplo, considere el siguiente paso de trabajo, que utiliza el token A-MSG y no se ha actualizado con una macro de escape:
PRINT N'Print ''$(A-MSG)''' ;
Después de ejecutar el script de actualización, se inserta una macro ESCAPE_NONE con el token. No obstante, en este caso, se debería volver a escribir el script sin usar anidamiento e insertar la macro ESCAPE_SQUOTE para convertir los delimitadores que se puedan haber pasado en la cadena de reemplazo del token:
DECLARE @msgString nvarchar(max)
SET @msgString = '$(ESCAPE_SQUOTE(A-MSG))'
SET @msgString = QUOTENAME(@msgString,'''')
PRINT N'Print ' + @msgString ;
Además, tenga en cuenta que en este ejemplo la función QUOTENAME establece el carácter de cita.
C.Usar tokens con la macro ESCAPE_NONE
El siguiente ejemplo es parte de un script que recupera el job_id de la tabla sysjobs y utiliza el token JOBID para rellenar la variable @JobID, que se declaró previamente en el script como un tipo de datos binario. Tenga en cuenta que, debido a que no se requieren delimitadores para los tipos de datos binarios, la macro ESCAPE_NONE se usa con el token JOBID. Una vez que se ejecute el script de actualización, no debería ser necesario actualizar este paso de trabajo.
SELECT * FROM msdb.dbo.sysjobs
WHERE @JobID = CONVERT(uniqueidentifier, $(ESCAPE_NONE(JOBID))) ;