Utiliser des jetons dans les étapes d'un travail

S’applique à :SQL ServerAzure SQL Managed Instance

SQL Server Agent vous permet d’utiliser des jetons dans des scripts d’étape de travail Transact-SQL . Ces jetons avec lesquels vous rédigez des étapes de travail vous offrent la même flexibilité que les variables lors de l'écriture de programmes logiciels. Après avoir inséré un jeton dans un script d'étape de travail, SQL Server Agent le remplace au moment de l'exécution avant que le sous-système Transact-SQL n'exécute l'étape de travail.

Comprendre l’utilisation des jetons

SQL Server Agent : Le remplacement du jeton est simple et efficace, SQL Server Agent remplace le jeton par une valeur de chaîne littérale exacte. Tous les jetons respectent la casse. Vous devez tenir compte de ce changement dans vos étapes de travail et nommer correctement les jetons utilisés, ou bien convertir la chaîne de remplacement en type de données correct.

Par exemple, vous pouvez utiliser l'instruction suivante pour imprimer le nom de la base de données dans une étape de travail :

PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;

Dans cet exemple, la macro ESCAPE_SQUOTE est insérée avec le jeton A-DBN . Au moment de l’exécution, le jeton A-DBN est remplacé par le nom de base de données approprié. La macro d'échappement interprète comme des caractères d'échappement tous les guillemets simples transmis par inadvertance à la chaîne de remplacement des jetons. SQL Server Agent remplace un guillemet simple par deux guillemets simples dans la chaîne finale.

Par exemple, si la chaîne transmise en vue de remplacer le jeton est AdventureWorks2022'SELECT @@VERSION --, la commande exécutée par l'étape de travail SQL Server Agent sera la suivante :

PRINT N'Current database name is AdventureWorks2022''SELECT @@VERSION --' ;

Dans ce cas, l’instruction insérée, SELECT @@VERSION, n’est pas exécutée. À la place, le guillemet simple supplémentaire incite le serveur à analyser l'instruction insérée en tant que chaîne. Si la chaîne de remplacement de jetons ne contient aucun guillemet simple, aucun caractère n’est interprété comme caractère d’échappement et l’étape de tâche contenant le jeton s’exécute comme prévu.

Pour déboguer l'usage de jetons dans vos étapes de travail, utilisez des instructions d'impression, telles que PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' , et enregistrez la sortie des étapes de travail dans un fichier ou une table. Ouvrez la page Avancé de la boîte de dialogue Propriétés de l’étape du travail pour spécifier une table ou un fichier de sortie pour les étapes de travail.

Jetons et macros de SQL Server Agent

Les tableaux suivants répertorient et décrivent les jetons et les macros pris en charge par SQL Server Agent.

Jetons de SQL Server Agent

Macros d'échappement de SQL Server Agent

Mettre à jour les étapes de la tâche pour utiliser des macros

La table suivante décrit comment le remplacement des jetons est contrôlé par SQL Server Agent. Pour activer/désactiver le remplacement des jetons, cliquez avec le bouton droit sur SQL Server Agent dans l’Explorateur d’objets, sélectionnez Propriétés, puis dans la page Système d’alerte , cochez ou décochez la case Remplacer les jetons pour toutes les réponses de travaux aux alertes .

Exemples de mise à jour de syntaxe de jeton

Vous trouverez ci-dessous des exemples de syntaxe de jeton pour illustrer l’utilisation de ces commandes.

A. Utilisation de jetons dans des chaînes non imbriquées

L'exemple suivant explique comment mettre à jour un script non imbriqué simple avec la macro d'échappement appropriée. Avant d'exécuter le script de mise à jour, le script d'étape de travail suivant utilise un jeton d'étape de travail pour imprimer le nom de base de données correct :

PRINT N'Current database name is $(A-DBN)' ;

Après l'exécution du script de mise à jour, une ESCAPE_NONE macro est insérée avant le jeton A-DBN . Du fait que les guillemets simples sont utilisés pour délimiter la chaîne d'impression, vous devez mettre à jour l'étape de travail en insérant la macro ESCAPE_SQUOTE comme suit :

PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;

B. Utilisation de jetons dans des chaînes imbriquées

Dans les scripts d'étape de travail où les jetons sont utilisés dans des chaînes ou des instructions imbriquées, les instructions imbriquées doivent être réécrites sous forme de plusieurs instructions avant d'insérer les macros d'échappement appropriées.

Par exemple, considérez l’étape de tâche suivante qui utilise le jeton A-MSG et n’a pas été mise à jour avec une macro d’échappement :

PRINT N'Print ''$(A-MSG)''' ;

Après l'exécution du script de mise à jour, une macro ESCAPE_NONE est insérée avec le jeton. Néanmoins, dans ce cas, il vous faudrait réécrire le script sans avoir recours à l'imbrication comme illustré ci-après, puis insérer la macro ESCAPE_SQUOTE pour interpréter correctement en tant que caractères d'échappement les délimiteurs susceptibles d'être transmis à la chaîne de remplacement des jetons :

DECLARE @msgString nvarchar(max);
SET @msgString = '$(ESCAPE_SQUOTE(A-MSG))';
SET @msgString = QUOTENAME(@msgString,'''');
PRINT N'Print ' + @msgString;

C. Utilisation de jetons avec la macro ESCAPE_NONE

L’exemple suivant s’inscrit dans un script chargé d’extraire le job_id dans la table sysjobs et utilise le jeton JOBID pour remplir la variable @JobID déclarée plus tôt dans le script en tant que type de données binaire.

DECLARE @JobID uniqueidentifier
SET @JobID = $(ESCAPE_NONE(JOBID))

Cela affecte directement la valeur du jeton JOBID à @JobID, éliminant les requêtes de base de données inutiles et les conversions implicites, en répondant aux préoccupations soulevées dans la section C.

Voir aussi

• Implémenter des travaux
• Gérer les étapes de travail