sp_add_jobstep (Transact-SQL)

Artículo
06/18/2013

Agrega un paso (operación) a un trabajo.

Icono de vínculo a temas Convenciones de sintaxis de Transact-SQL

Sintaxis

sp_add_jobstep [ @job_id = ] job_id | [ @job_name = ] 'job_name' 
     [ , [ @step_id = ] step_id ] 
     { , [ @step_name = ] 'step_name' } 
     [ , [ @subsystem = ] 'subsystem' ] 
     [ , [ @command = ] 'command' ] 
     [ , [ @additional_parameters = ] 'parameters' ] 
          [ , [ @cmdexec_success_code = ] code ] 
     [ , [ @on_success_action = ] success_action ] 
          [ , [ @on_success_step_id = ] success_step_id ] 
          [ , [ @on_fail_action = ] fail_action ] 
          [ , [ @on_fail_step_id = ] fail_step_id ] 
     [ , [ @server = ] 'server' ] 
     [ , [ @database_name = ] 'database' ] 
     [ , [ @database_user_name = ] 'user' ] 
     [ , [ @retry_attempts = ] retry_attempts ] 
     [ , [ @retry_interval = ] retry_interval ] 
     [ , [ @os_run_priority = ] run_priority ] 
     [ , [ @output_file_name = ] 'file_name' ] 
     [ , [ @flags = ] flags ] 
     [ , { [ @proxy_id = ] proxy_id 
         | [ @proxy_name = ] 'proxy_name' } ]

Argumentos

[ @job_id = ] job_id
Número de identificación del trabajo al que se agrega el paso. job_id es de tipo uniqueidentifier y su valor predeterminado es NULL.
[ @job_name = ] 'job_name'
El nombre del trabajo al que se agrega el paso. job_name es de tipo sysname y su valor predeterminado es NULL.

[!NOTA]

Se debe especificar job_id o job_name, pero no ambos.
[ @step_id = ] step_id
Número de identificación de secuencia del paso del trabajo. Los números de identificación de paso empiezan desde el 1 y van aumentando consecutivamente. Si se inserta un paso en la secuencia existente, los números de secuencia se ajustan automáticamente. Se proporciona un valor si no se especifica step_id. step_ides de tipo int, con un valor predeterminado de NULL.
[ @step_name = ] 'step_name'
Nombre del paso. step_namees de tipo sysname, sin valor predeterminado.

[ @subsystem = ] 'subsystem'
El subsistema usado por el servicio Agente SQL Server para ejecutar command. subsystem es de tipo nvarchar(40) y puede tener uno de estos valores.

'ACTIVESCRIPTING'

Script Active

Importante
Esta característica se quitará en una versión futura de Microsoft SQL Server. Evite utilizar esta característica en nuevos trabajos de desarrollo y tenga previsto modificar las aplicaciones que actualmente la utilizan.

'CMDEXEC'

Comando del sistema operativo o programa ejecutable

'DISTRIBUTION'

Trabajo del Agente de distribución de replicación

'SNAPSHOT'

Trabajo del Agente de instantáneas de replicación

'LOGREADER'

Trabajo del Agente de registro del LOG de replicación

'MERGE'

Trabajo del Agente de mezcla de replicación

'QueueReader'

Trabajo del Agente de lectura de cola de replicación

'ANALYSISQUERY'

Consulta de Analysis Services (MDX, DMX)

'ANALYSISCOMMAND'

Comando de Analysis Services (XMLA)

'Dts'

Ejecución del paquete de Integration Services

'PowerShell'

Script de PowerShell

'TSQL' (predeterminado)

Instrucción Transact-SQL

[ @command= ] 'command'
Los comandos que va a ejecutar el servicio SQLServerAgent a través de subsystem. command es de tipo nvarchar(max) y su valor predeterminado es NULL. El Agente SQL Server proporciona sustitución de tokens, que ofrece la misma flexibilidad que ofrecen las variables al escribir programas de software.

Importante
En el Service Pack 1 de SQL Server 2005 se ha cambiado la sintaxis de tokens de paso de trabajo del Agente SQL Server. 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. Además, ahora debe escribir 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))

En el Service Pack 1 de SQL Server 2005 se ha cambiado la sintaxis de tokens de paso de trabajo del Agente SQL Server. 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. Además, ahora debe escribir 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))

Para obtener más información sobre estos tokens y actualizar los pasos de trabajo a la nueva sintaxis de los tokens, vea Usar tokens en pasos de trabajos.

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

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

[ @additional_parameters= ] 'parameters'
Solamente se identifica con fines informativos. No compatible. La compatibilidad con versiones posteriores no está garantizada. parameters es ntext, y su valor predeterminado es NULL.
[ @cmdexec_success_code = ] code
Valor devuelto por un comando del subsistema CmdExec para indicar que command se ha ejecutado correctamente. codees de tipo int, con un valor predeterminado de 0.
[ @on_success_action= ] success_action
Acción que se realiza si el paso termina correctamente. success_actiones de tipo tinyint y puede tener uno de estos valores.

Valor

Descripción (acción)

1 (predeterminado)

Salir con éxito

2

Salir con error

3

Ir al paso siguiente

4

Ir al paso on_success_step_id
[ @on_success_step_id = ] success_step_id
El identificador del paso de este trabajo que se ejecuta si el paso se realiza correctamente y success_actiones 4. success_step_ides de tipo int, con un valor predeterminado de 0.
[ @on_fail_action= ] fail_action
Acción que se realiza si el paso da error. fail_actiones de tipo tinyint y puede tener uno de estos valores.

Valor

Descripción (acción)

1

Salir con éxito

2 (predeterminado)

Salir con error

3

Ir al paso siguiente

4

Ir al paso on_fail_step_id
[ @on_fail_step_id= ] fail_step_id
El identificador del paso de este trabajo que se ejecuta si el paso da error y fail_actiones 4. fail_step_ides de tipo int, con un valor predeterminado de 0.
[ @server =] 'server'
Solamente se identifica con fines informativos. No compatible. La compatibilidad con versiones posteriores no está garantizada. serveres de tipo nvarchar(30) y su valor predeterminado es NULL.
[ @database_name = ] 'database'
Nombre de la base de datos en la que se va a ejecutar un paso de Transact-SQL. database es de tipo sysname, con un valor predeterminado de NULL, en cuyo caso se utiliza la base de datos maestra. No se permite usar nombres incluidos entre corchetes ([ ]). Para un paso de trabajo ActiveX, database es el nombre del lenguaje de scripting que utiliza el paso.
[ @database_user_name= ] 'user'
El nombre de la cuenta de usuario que se va a utilizar cuando se ejecuta un paso de Transact-SQL. user es de tipo sysname y su valor predeterminado es NULL. Si user es NULL, el paso se ejecuta en el contexto de usuario del propietario del trabajo en database. El Agente SQL Server solo incluirá este parámetro si el propietario del trabajo es un administrador de sistema de SQL Server. En ese caso, el paso de Transact-SQL dado se ejecutará en el contexto del nombre de usuario de SQL Server determinado. Si el propietario del trabajo no es administrador de sistema de SQL Server, el paso de Transact-SQL siempre se ejecutará en el contexto del inicio de sesión que posea este trabajo y el parámetro @database\_user\_name se omitirá.
[ @retry_attempts= ] retry_attempts
Número de reintentos en caso de que el paso dé error. retry_attemptses de tipo int, con un valor predeterminado de 0, que indica que no se realiza ningún reintento.
[ @retry_interval= ] retry_interval
Tiempo en minutos entre reintentos. retry_intervales de tipo int, con un valor predeterminado de 0, que indica un intervalo de 0 minutos.
[ @os_run_priority = ] run_priority
Reservado.
[ @output_file_name= ] 'file_name'
Nombre del archivo en el que se guarda el resultado de este paso. file_namees de tipo nvarchar(200), con un valor predeterminado de NULL. file_namepuede incluir alguno de los tokens enumerados bajo command. Este parámetro sólo es válido con los comandos que se ejecutan en los subsistemas Transact-SQL, CmdExec, PowerShell, Integration Services o Analysis Services.

Valor	Descripción (acción)
1 (predeterminado)	Salir con éxito
2	Salir con error
3	Ir al paso siguiente
4	Ir al paso on_success_step_id

Valor	Descripción (acción)
1	Salir con éxito
2 (predeterminado)	Salir con error
3	Ir al paso siguiente
4	Ir al paso on_fail_step_id

[ @flags= ] flags
Es una opción que controla el comportamiento. flags es de tipo int y puede tener uno de estos valores.

Valor	Descripción
0 (predeterminado)	Sobrescribir el archivo de salida
2	Anexar al archivo de salida
4	Escribir la salida del paso de trabajo Transact-SQL en el historial de pasos
8	Escribir el registro en la tabla (sobrescribir el historial existente)
16	Escribir el registro en la tabla (anexar al historial existente)
32	Escribir todo el resultado en el historial de trabajos
64	Crear un evento Windows para usarlo como señal y que se anule el paso de trabajo de Cmd

[ @proxy_id = ] proxy_id
Número de identificación del proxy con el que se ejecuta el paso de trabajo. proxy_id es de tipo int, con un valor predeterminado de NULL. Si no se especifica proxy_id, proxy_name o user_name, el paso de trabajo se ejecuta como la cuenta de servicio para el Agente SQL Server.
[ @proxy_name = ] 'proxy_name'
Nombre del proxy con el que se ejecuta el paso de trabajo. proxy_name es de tipo sysname, con un valor predeterminado de NULL. Si no se especifica proxy_id, proxy_name o user_name, el paso de trabajo se ejecuta como la cuenta de servicio para el Agente SQL Server.

Valores de código de retorno

0 (correcto) o 1 (error)

Conjuntos de resultados

Ninguno

Comentarios

sp_add_jobstep se debe ejecutar desde la base de datos msdb.

SQL Server Management Studio ofrece un método gráfico sencillo para administrar trabajos y es el método recomendado para crear y administrar la infraestructura de trabajo.

Un paso de trabajo debe especificar un proxy a menos que el creador del paso de trabajo sea miembro del rol fijo de seguridad sysadmin.

El proxy se puede identificar mediante proxy_name o proxy_id.

Permisos

De forma predeterminada, los miembros del rol fijo de servidor sysadmin pueden ejecutar este procedimiento almacenado. Al resto de usuarios se les debe conceder uno de los siguientes roles fijos de base de datos del Agente SQL Server en la base de datos msdb:

SQLAgentUserRole
SQLAgentReaderRole
SQLAgentOperatorRole

Para obtener más información acerca de los permisos de estos roles, vea Roles fijos de base de datos del Agente SQL Server.

El creador del paso de trabajo debe tener acceso al proxy para el paso de trabajo. Los miembros del rol fijo de servidor sysadmin tienen acceso a todos los proxy. Se debe conceder acceso al proxy de forma explícita al resto de los usuarios.

Ejemplos

En este ejemplo se crea un paso de trabajo que cambia el acceso a la base de datos de modo que sea de solo lectura para la base de datos Sales. Además, en este ejemplo se especifican 5 reintentos, cada uno de los cuales se produce tras una espera de 5 minutos.

[!NOTA]

En este ejemplo se da por supuesto que el trabajo Weekly Sales Data Backup ya existe.

USE msdb;
GO
EXEC sp_add_jobstep
    @job_name = N'Weekly Sales Data Backup',
    @step_name = N'Set database to read only',
    @subsystem = N'TSQL',
    @command = N'ALTER DATABASE SALES SET READ_ONLY', 
    @retry_attempts = 5,
    @retry_interval = 5 ;
GO