Fonctions

Les informations sur cette page d’aide concernent à la fois Studio et Desktop Studio.

Une fonction est un bloc de code réutilisable qui accomplit une tâche précise. Chaque fois que vous avez besoin de cette tâche, vous pouvez utiliser la fonction dans votre script. Cela vous évite de perdre du temps et de l'énergie à ajouter du code pour cette tâche dans votre script chaque fois que vous en avez besoin. Cela permet également de garder vos scripts plus propres et moins encombrés en réduisant la quantité de code dans le script.

Les fonctions peuvent :

  • Prendre des données dans le script, les manipuler d'une manière ou d'une autre, puis renvoyer les résultats au script.
  • Effectuer une action ou une série d'actions et transmettre les données résultantes au script.

Certaines fonctions sont intégrées à Studio pour être utilisées dans vos scripts. Vous n'avez rien à ajouter dans votre script pour utiliser une fonction intégrée. Lorsque vous voulez en utiliser un, vous pouvez simplement l’appeler.

Vous pouvez également créer vos propres fonctions personnalisées afin de les utiliser dans un script. Ceci est utile lorsque vous utilisez fréquemment du code dans votre script. Plutôt que de l'ajouter à votre script chaque fois que vous en avez besoin, vous pouvez créer une fonction qui contient le code. Ensuite, lorsque vous avez besoin de ce code, vous pouvez appeler la fonction.

Des exemples d'utilisation de fonctions sont disponibles à télécharger et à importer dans Studio.

Syntaxe

Les noms de fonction comportent une parenthèse ouverte et une parenthèse fermée à la fin : functionName().

Tout texte entre parenthèses représente des paramètres, qui définissent les données transmises entre la fonction et le script : functionName(param1,param2).

Pour créer une fonction personnalisée, utilisez la syntaxe suivante :

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

Dans cette syntaxe :

  • FUNCTION est le mot-clé requis qui marque le début de toutes les instructions de fonction personnalisée.
  • <name> est le nom de la fonction.
  • ([<parameter>] [...]) définit tous les paramètres dont la fonction a besoin.
  • { ... } contient le code de la fonction.
  • [RETURN <data>] est l'instruction à inclure pour transmettre les données de la fonction au script principal.

Vous pouvez donner n'importe quel nom à vos fonctions personnalisées, à condition de suivre les instructions suivantes :

  • Utilisez des caractères alphanumériques (a-z, A-Z, 0-9).

  • Le premier caractère du nom doit être une lettre.
  • Utilisez le caractère de soulignement ( _ ) et le signe dollar ( $ ) n'importe où dans le nom.
  • N'utilisez pas les mots réservés ou les noms des fonctions intégrées.

La syntaxe d’une instruction RETURN est la suivante :

RETURN ou RETURN <var>

Lorsque vous appelez une fonction, utilisez l'une des syntaxes suivantes :

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

Paramètres et arguments

De nombreuses fonctions doivent utiliser des données provenant du script. Vous pouvez faire ceci à l’aide de paramètres et d’arguments.

Les paramètres sont définis lors de la création d'une fonction. Un paramètre est un nom DE variable qui apparaît entre les parenthèses suivant le nom de la fonction. Une fonction peut avoir plus d'un paramètre. Chaque paramètre est séparé des autres par une virgule.Vous pouvez inclure un espace si vous le voulez, mais ce n'est pas obligatoire. Par exemple, la fonction logn(value, base) possède deux paramètres, value et base.

Les données spécifiques que le script transmet à la fonction via les paramètres sont appelées arguments. L'exemple suivant illustre l'utilisation de la fonction intégrée abs(value) dans un script.Dans cet exemple, -42 est l'argument qui est transmis au paramètre value.

ASSIGN abVal = abs(-42)

Dans Studio, tous les paramètres sont obligatoires. Si une fonction est définie avec un paramètre, vous devez transmettre une valeur lorsque vous appelez la fonction. Le nombre d'arguments transmis à la fonction doit correspondre au nombre de paramètres définis.

Le script ne vérifie pas que les arguments sont du bon type ou du bon format. Toutefois, si l'argument n'est pas du type ou du format attendu par la fonction, il est possible que la fonction ne s'exécute pas correctement ou que les résultats ne soient pas exacts.

Si un nombre trop élevé ou trop faible d'arguments est transmis à la fonction, cela provoque une erreur de compilation lorsque vous exécutez le script. Cela peut se produire pour les fonctions intégrées et les fonctions personnalisées.

Formatage des arguments

Lorsque vous appelez une fonction qui requiert des paramètres, vous devez inclure les arguments que vous transmettez à la fonction. Suivez les consignes suivantes pour formater les arguments :

  • Si l'argument est numérique ou une Variable, il n'est pas nécessaire de le placer entre guillemets simples ou doubles.
  • Si l'argument est une variable, il n'est pas nécessaire de l'entourer d'accolades.
  • Si l'argument est alphanumérique et n'est pas une variable, il doit être placé entre guillemets simples ou doubles.

Par exemple, la dateadd() fonction nécessite trois paramètres, unit, date et value.

Unit définit la partie de la date que vous souhaitez que la fonction modifie, telle que l'année ou le mois. Date est la date d'origine que vous souhaitez modifier. Et value correspond à la quantité dont vous souhaitez que la fonction augmente l'unité spécifiée de la date d'origine. L'exemple suivant montre comment chaque partie est formatée.

ASSIGN NewDateYearNumeric = dateadd('year', MyDateTime, 1)

Le unit est une chaîne alphanumérique, elle est donc formatée avec des guillemets simples. La date dans cet exemple est une variable, elle n'est donc pas entre guillemets. Si vous transmettez une date sous forme de chaîne, des guillemets seront nécessaires. La value n'est pas formatée car elle est numérique.

Instructions RETURN

Une instruction RETURN met fin à une fonction et redonne le contrôle au script. Elle peut également transmettre des données au script.

RETURN ne peuvent transmettre de données au script que sous forme de valeur de Variable ou de tableau. Ils ne peuvent pas transmettre plusieurs valeurs, sauf si ces valeurs font partie d'un tableau ou d'un objet. Elles ne peuvent pas transmettre d'objets, à moins que les objets ne soient d'abord convertis en JSON. Si nécessaire, vous pouvez le reconvertir en objet dans le script.

La syntaxe d’une instruction RETURN est la suivante :

RETURN ou RETURN <var>

Toutes les fonctions intégrées qui renvoient une valeur au script contiennent une instruction RETURN. Dans les fonctions personnalisées que vous créez, les instructions RETURN sont en option. S'il n'y a pas d’instruction RETURN, la fonction ne peut pas transmettre de valeurs au script. La seule façon d'utiliser une fonction ne comportant pas d'instruction RETURN est de l'appeler comme une instruction.

Si vous incluez une instruction RETURN dans une fonction, elle doit être la dernière ligne de la fonction.

Visibilité du Variable

Par défaut, toutes les valeurs de la fonction sont disponibles et utilisables uniquement à l'intérieur de la fonction. Lorsque la fonction se termine, toutes les valeurs de la fonction sont perdues.Si la fonction contient une instruction RETURN qui transmet une valeur de variable au script, seules les valeurs transmises par l'instruction RETURN sont disponibles en dehors de la fonction.

Si vous incluez dans une fonction personnalisée des variables qui existent dans le script principal, ces variables ont une portée globale. Cela signifie que ces valeurs sont disponibles en dehors de la fonction sans utiliser d’instruction RETURN. De même, si vous déclarez une Variable au sein de la fonction comme Global, sa valeur est disponible dans le script principale. Ce comportement est similaire à celui observé pour les indices.

Lorsque vous utilisez une fonction dans une expression ou comme valeur d'une variable, elle suit le comportement par défaut. Toutefois, si vous appelez une fonction en tant qu'instruction, toutes les valeurs de la fonction ont une portée globale et peuvent être utilisées en dehors de la fonction. Pour les fonctions sans RETURN, c'est la seule façon de les utiliser.

Créer des Fonctions personnalisées

Vous pouvez créer des fonctions personnalisées lorsque vous avez du code que vous voulez pouvoir utiliser à plusieurs endroits dans votre script. Une fonction personnalisée n'est disponible que dans le script où vous l'avez créée. Si vous voulez utiliser une fonction personnalisée dans un autre script, vous devez copier le code de définition de la fonction dans ce script.

You can create a function in one Snippet action in your script, then call it from other Snippet actions in the same script. If you debug the snippet containing the function definition, it's included in the debug. However, the function won't be included when you debug the other snippets.

La syntaxe pour déclarer une fonction personnalisée est la suivante :

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

FUNCTION est un mot-clé qui indique au script que ce qui suit est une fonction personnalisée. Les noms de fonctions doivent suivre les mêmes conventions de dénomination que les autres entités dans les scripts.

  • Utilisez des caractères alphanumériques (a-z, A-Z, 0-9).

  • Le premier caractère du nom doit être une lettre.
  • Utilisez le caractère de soulignement ( _ ) et le signe dollar ( $ ) n'importe où dans le nom.
  • N'utilisez pas les mots réservés ou les noms des fonctions intégrées.

Si la fonction nécessite des paramètres, ceux-ci doivent être placés entre les parenthèses à la fin du nom de la fonction. S'il n'y a pas de paramètres, les parenthèses peuvent être laissées vides. Séparez plusieurs paramètres par des virgules.

Le code qui constitue la fonction se trouve entre les accolades. Le placement des accolades est flexible. Elles peuvent figurer sur la même ligne que le mot-clé FUNCTION et le nom, ou figurer sur des lignes distinctes. Par exemple, les deux définitions de Fonction suivantes sont valables :

FUNCTION myFunction() { ASSIGN var = "value" } 
FUNCTION myFunction() 
{ 
	ASSIGN var = "value"
}

Si la fonction inclut une instruction RETURN, celle-ci doit être la dernière instruction de la fonction avant l'accolade fermante.

Vous pouvez en savoir plus sur la création de fonctions sur la Page instructions de déclaration.

Appel de Fonctions dans un script

Lorsque vous voulez utiliser une fonction dans votre script, vous devez l'appeler. Il existe trois façons d’appeler une fonction. L'Option ne fonctionne pas pour toutes les fonctions. Les options disponibles pour une fonction donnée dépendent du fait que la fonction renvoie ou non une valeur. Vous pouvez appeler une fonction :

  • Seule, comme une instruction. Cette option s'applique à toutes les fonctions.
  • À l'endroit où vous utiliseriez une variable ou une expression. Cette option ne fonctionne qu'avec les fonctions qui renvoient une valeur.
  • Avec une variable utilisant la notation par points. Cette option ne fonctionne qu'avec les fonctions qui renvoient une valeur.

Appel d’une Fonction en tant qu’instruction

Une instruction est une ligne de code contenant un mot-clé de commande qui indique au script ce qu'il doit faire. Vous pouvez utiliser une fonction comme une instruction. Lorsque vous le faites, vous n'avez pas besoin d'un mot-clé de commande spécial, comme avec les autres instructions dans un extrait. Le code dans la fonction indique au script ce qu'il doit faire.

Vous pouvez appeler n’importe quelle fonction comme une instruction.Si une fonction ne contient pas d’instruction RETURN, c'est la seule façon de l'appeler. En effet, l'instruction RETURN renvoie les données de la fonction dans le script. Lorsqu'il n'y a pas de RETURN, l'appel en tant qu'instruction est le seul moyen pour le script d'accéder aux données de la fonction.

La syntaxe pour appeler des fonctions en tant qu'instruction est la suivante :

<functionName><([parameter], [parameter], [...])>

L'exemple suivant montre comment la fonction append() est appelée comme une instruction :

IF TEST = 1
{
  ASSIGN originalString = "My name"
  ASSIGN originalString2 = "Whose pajamas are these? "
  ASSIGN appendWithEscape = $"They're the cat's pajamas."			
}
originalString.append(" is Inigo Montoya.")
originalString2.append(AppendWithEscape)

Utilisation d’une Fonction à la place d'une variable

Lorsqu'une fonction renvoie une valeur, vous pouvez l'utiliser partout où vous utiliseriez une variable ou une expression. Le script peut utiliser la valeur retournée par la fonction comme s'il s'agissait de la valeur de la variable ou du résultat de l'expression.

Les syntaxes permettant d'utiliser une fonction à la place d'une variable sont les suivantes :

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

Si vous souhaitez que le résultat de la fonction soit affecté à une variable, vous pouvez appeler la fonction dans le cadre d'une instruction ASSIGN. Par exemple, ASSIGN var = otherVar.function(). Toutefois, il existe un cas où cela ne fonctionne pas : il s'agit d'appeler une fonction membre de la GetRESTproxy() fonction.

L’exemple suivant montre comment utiliser une fonction qui renvoie une valeur. Voici un exemple de fonction :

FUNCTION replaceCharacters(string)
{
	ASSIGN adjustedString = string.replace("&", "and")
	RETURN adjustedString
}			

Cette fonction remplace le caractère ET commercial ( & ) par le mot and. Dans l'exemple suivant, la fonction replaceCharacters() est utilisée à la place d'une variable dans la valeur de chaîne de la variable stringRes. Lorsque ce code s'exécute, la valeur de stringRes est mise à jour en My favorite animals are dogs and cats.

ASSIGN testString = "dogs & cats"
ASSIGN stringRes = "My favorite animals are {replaceCharacters(testString)}."

Utilisation d’une Fonction avec la notation par points

Lorsque les fonctions renvoient une valeur, vous pouvez les utiliser avec des variables en utilisant la notation par point. Ceci attache la fonction à la variable, comme ceci : variable.function(). Lorsque vous appelez une fonction de cette manière, la valeur de la variable est transmise à la fonction.Cette option ne fonctionne qu'avec les fonctions qui renvoient une valeur.

Syntaxe d'utilisation d'une fonction avec la notation par point :

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

L'exemple suivant illustre cette approche. Voici la fonction :

FUNCTION MyAppend(a,b)
{
   RETURN "{a}{b}"
}	

Ceci est ne boucle FOR qui utilise la fonction MyAppend avec la variable ph :

FOR i=1 TO 9
{
   ph = "{ph.MyAppend(i)}"
}

Le résultat de la boucle FOR est : ph="123456789".

Lorsque vous appelez une fonction en utilisant la notation par point, la valeur de la variable à laquelle elle est attachée est transmise à la fonction en tant qu'argument du premier paramètre. Dans l'exemple précédent, la valeur initiale de ph est transmise à la fonction MyAppend() en tant qu'argument pour le paramètre a. C'est pourquoi l'appel de la fonction ne comporte qu'un seul argument lorsque la définition de la fonction a deux paramètres. La valeur initiale de i est transmise à la fonction comme argument pour le paramètre b.

L’avantage d’appeler les fonctions avec la notation par points est qu’elle vous permet d’ajouter une aide sous forme d’infobulle pour la fonction.