sp_add_jobstep (Transact-SQL)

Actualizado: 14 de abril de 2006

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

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 va a agregar el paso. job_id es de tipo uniqueidentifier y su valor predeterminado es NULL.

• [ @job_name = ] 'job_name'
  Nombre del trabajo al que se va a agregar 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. Si no se especifica step_id, se proporciona un valor. step_ides de tipo int y su valor predeterminado es NULL.

• [ @step_name = ] 'step_name'
  Es el nombre del paso. step_namees de tipo sysname y no tiene valor predeterminado.

• [ @subsystem = ] 'subsystem'
  Subsistema utilizado por el servicio del Agente Microsoft SQL Server para ejecutar command. subsystemes de tipo nvarchar(40) y puede ser uno de los valores siguientes.

  Valor	Descripción
  'ACTIVESCRIPTING'	Secuencia de comandos Active
  'CMDEXEC'	Comando del sistema operativo o programa ejecutable
  'DISTRIBUTION'	Trabajo del Agente de distribución de réplica
  'SNAPSHOT'	Trabajo del Agente de instantáneas de réplica
  'LOGREADER'	Trabajo del Agente de registro del LOG de réplica
  'MERGE'	Trabajo del Agente de mezcla de réplica
  'QueueReader'	Trabajo del Agente de lectura de cola de réplica
  'ANALYSISQUERY'	Consulta de Analysis Services (MDX, DMX)
  'ANALYSISCOMMAND'	Comando de Analysis Services (XMLA)
  'Dts'	Ejecución del paquete de Integration Services
  'TSQL' (predeterminado)	Instrucción Transact-SQL

• [ @command= ] 'command'
  Comandos que va a ejecutar el servicio SQLServerAgent mediante subsystem. command es de tipo nvarchar(max) y su valor predeterminado es NULL. El Agente SQL Server proporciona sustitución de símbolos, 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 símbolos de paso de trabajo del Agente SQL Server. Como consecuencia, ahora todos los símbolos utilizados en los pasos de trabajo deben ir acompañados de una macro de escape; de lo contrario, dichos pasos de trabajo no funcionarán correctamente. Además, también ha cambiado la sintaxis de SQL Server 2000, que utilizaba corchetes para llamar a los símbolos de pasos de trabajo del Agente SQL Server (por ejemplo, "[DATE]"). Ahora debe escribir los nombres de los símbolos entre paréntesis y colocar un signo de dólar ($) al principio de la sintaxis del símbolo. Por ejemplo: $(ESCAPE_nombre de macro(DATE))

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

  Nota de seguridad:

  Todos los usuarios de Windows que tengan permisos de escritura en el Registro de sucesos 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 testigos del Agente SQL Server que se pueden utilizar en los trabajos activados por alertas están deshabilitados de forma predeterminada. Estos testigos son: A-DBN, A-SVR, A-ERR, A-SEV, A-MSG.y WMI(propiedad). Si necesita usar estos símbolos, asegúrese primero de que sólo los miembros de los grupos de seguridad de Windows de confianza, como el grupo Administradores, tienen permisos de escritura en el registro de sucesos del equipo donde reside SQL Server. Para habilitar estos símbolos, 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 símbolos para todas las respuestas de trabajos a alertas.

• [ @additional_parameters= ] 'parameters'
  Identificado para fines informativos solamente. No compatible. La compatibilidad con versiones posteriores no está garantizada. parameters es de tipo 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 y su valor predeterminado es 0.

• [ @on_success_action= ] success_action
  Acción que se debe realizar si el paso se ejecuta con éxito. success_actiones de tipo tinyint y puede ser uno de los valores siguientes.

  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
  Id. del paso de este trabajo que se debe ejecutar si el paso tiene éxito y success_actiones 4. success_step_ides de tipo int y su valor predeterminado es 0.

• [ @on_fail_action= ] fail_action
  Acción que se debe realizar si se produce un error en el paso. fail_actiones de tipo tinyint y puede ser uno de los valores siguientes.

  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
  Id. del paso de este trabajo que se debe ejecutar si se produce un error en el paso y fail_actiones 4. fail_step_ides de tipo int y su valor predeterminado es 0.

• [ @server =] 'server'
  Identificado para fines informativos solamente. No compatible. La compatibilidad con versiones posteriores no está garantizada. server es de tipo nvarchar(30) y su valor predeterminado es NULL.

• [ @database_name= ] 'database'
  Nombre de la base de datos en la que va a ejecutarse un paso Transact-SQL. databasees de tipo sysname y su valor predeterminado es NULL, en cuyo caso se utiliza la base de datos master. Para un paso de trabajo ActiveX, database es el nombre del lenguaje de secuencias de comandos que utiliza el paso.

• [ @database_user_name= ] 'user'
  Nombre de la cuenta de usuario que va a utilizarse al ejecutar 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.

• [ @retry_attempts= ] retry_attempts
  Número de reintentos que se deben utilizar si este paso tiene errores. retry_attemptses de tipo int y su valor predeterminado es 0, lo que indica que no se produce ningún reintento.

• [ @retry_interval= ] retry_interval
  Cantidad de tiempo en minutos entre reintentos. retry_intervales de tipo int y su valor predeterminado es 0, lo que indica un intervalo de 0 minutos.

• [ @os_run_priority = ] run_priority
  Identificado para fines informativos solamente. No compatible. La compatibilidad con versiones posteriores no está garantizada.

• [ @output_file_name= ] 'file_name'
  Nombre del archivo en que se guardará la salida de este paso. file_namees de tipo nvarchar(200) y su valor predeterminado es NULL. file_namepuede incluir uno o más de los testigos que se indican en command. Este parámetro sólo es válido con los comandos que se ejecutan en los subsistemas Transact-SQL o CmdExec.

• [ @flags= ] flags
  Es una opción que controla el comportamiento. flags es de tipo int y puede ser uno de los valores siguientes.

  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)

• [ @proxy_id = ] proxy_id
  Número de Id. del proxy con el que se ejecuta el paso de trabajo. proxy_id es de tipo int y su valor predeterminado es 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 y su valor predeterminado es 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.

Conjuntos de resultados

Ninguno

Notas

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 de la función fija de seguridad sysadmin.

El proxy se puede identificar mediante proxy_name o proxy_id.

Permisos

De forma predeterminada, los miembros de la función fija de servidor sysadmin pueden ejecutar este procedimiento almacenado. A otros usuarios debe concederse una de las siguientes funciones fijas 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 estas funciones, vea Funciones fijas 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 de la función fija de servidor sysadmin tienen acceso a todos los proxy. Se debe conceder acceso al proxy de forma explícita al resto de los usuarios.

Valores de código de retorno

0 (correcto) o 1 (error)

Ejemplos

En este ejemplo se crea un paso de trabajo que cambia el acceso a la base de datos de modo que sea de sólo lectura para la base de datos AdventureWorks. 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'exec sp_dboption ''sales'', ''read only'', ''true''', 
    @retry_attempts = 5,
    @retry_interval = 5 ;
GO

Vea también

Referencia

sp_add_job (Transact-SQL)
sp_add_schedule (Transact-SQL)
sp_delete_jobstep (Transact-SQL)
sp_help_job (Transact-SQL)
sp_help_jobstep (Transact-SQL)
sp_update_jobstep (Transact-SQL)
Procedimientos almacenados del sistema (Transact-SQL)

Otros recursos

Ver y modificar trabajos

Ayuda e información

Obtener ayuda sobre SQL Server 2005

Historial de cambios