sp_add_jobstep (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 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 SQL Server para ejecutar command. subsystem es de tipo nvarchar(40) y puede ser uno de los valores siguientes.

  Valor	Descripción
  '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'
  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 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 consecuencia, ahora todos los tokens 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 tokens de pasos de trabajo del Agente SQL Server (por ejemplo, "[DATE]"). 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_nombre de macro(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(propiedad). 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'
  Solo se identifica con fines informativos. 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'
  Solo se identifica con fines informativos. 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. database es de tipo sysname y su valor predeterminado es NULL, en cuyo caso se utiliza la base de datos maestra. No se permiten nombres incluidos entre corchetes ([ ]). Para un paso de trabajo ActiveX, database es el nombre del lenguaje de scripts 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
  Reservado.

• [ @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 tokens que se indican en command. Este parámetro solo es válido con comandos que se ejecutan en los subsistemas de Transact-SQL, CmdExec, SQL Server Integration Services de PowerShell o SQL Server Analysis Services.

• [ @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 identificador 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.

Valores de código de retorno

0 (correcto) o 1 (error)

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. Al resto de usuarios se les debe conceder 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.

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 AdventureWorks. Además, en este ejemplo se especifican 5 reintentos, cada uno de los cuales se produce tras una espera de 5 minutos.

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

Vea también

Referencia

Conceptos