Funciones

Una función es un bloque de código reutilizable que realiza una determinada tarea. Cada vez que necesite esa tarea, puede usar la función en su script. Esto le ahorra el tiempo y el esfuerzo necesarios para agregar código a esa tarea de su script cada vez que lo necesite. También mantiene más limpios sus scripts y menos desordenados al reducir la cantidad de código en el script.

Las funciones pueden:

Tomar datos del script, manipularlos de alguna manera y luego devolver los resultados al script.
Realizar una acción o serie de acciones y pasar al script los datos resultantes.

Algunas funciones están integradas a Studio para usarlas en sus scripts. No necesita agregar nada a su script para usar una función incorporada. Cuando quiera usar una, simplemente puede llamarla.

También puede crear sus propias funciones personalizadas para usarlas en un script. Esto es útil cuando tiene código que con frecuencia usa en su script. En lugar de agregarlo a su script cada vez que lo necesite, puede crear una función que contenga el código. Luego, cuando necesite ese código, puede llamar a la función.

Hay ejemplos disponibles del uso de funciones para que las descargue e importe a Studio.

Sintaxis

Los nombres de funciones tienen un conjunto de paréntesis abiertos y cerrados al final: functionName().

Cualquier texto dentro de los paréntesis son parámetros, que definen los datos que se pasan entre la función y el script: functionName(param1,param2).

Para crear una función personalizada, utilice esta sintaxis:

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

En esta sintaxis:

FUNCTION es la palabra clave requerida que comienza todas las declaraciones de funciones personalizadas.
<name> es el nombre de la función.
([<parameter>] [...]) define los parámetros que requiere la función.
{ ... } contiene el código de la función.
[RETURN <data>] es la declaración que se incluirá para pasar los datos de la función al script principal.

Puede nombrar sus funciones personalizadas como desee siempre que siga estos lineamientos:

Utilice caracteres alfanuméricos (a-z, A-Z, 0-9).
El primer carácter del nombre debe ser una letra.
Utilice el carácter de guión bajo ( _ ) y el signo de dólar ( $ ) en cualquier parte del nombre.
No utilice palabras reservadas ni nombres de funciones integradas.

La sintaxis de una declaración RETURN es:

RETURN o RETURN <var>

Al llamar a una función, utilice una de las siguientes sintaxis:

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

Parámetros y argumentos

Muchas funciones necesitan utilizar datos del script. Puede hacer esto usando parámetros y argumentos.

Se definen los parámetros cuando se crea una función. Un parámetro es un nombre de variable que aparece entre paréntesis después del nombre de la función. Una función puede tener más de un parámetro. Cada parámetro va separado por una coma. Puede incluir un espacio si lo desea, pero no es obligatorio. Por ejemplo, la función logn(value, base) tiene dos parámetros, value y base.

Los datos específicos que pasa el script a la función a través de los parámetros se denominan argumentos. El siguiente ejemplo muestra el uso de la función incorporada abs(value) a un script. En este ejemplo, -42 es el argumento que se pasa al parámetro value.

ASSIGN abVal = abs(-42)

En Studio, son obligatorios todos los parámetros. Si se define una función con un parámetro, debe pasar un valor cuando llame a la función. La cantidad de argumentos que se pasan a la función debe coincidir con la cantidad de parámetros definidos.

El script no verifica que los argumentos sean del tipo o formato correctos. Sin embargo, si el argumento no es el tipo o formato que espera la función, es posible que no se complete correctamente la función o que no sean precisos los resultados.

Si a la función se pasan demasiados o muy pocos argumentos, se produce un error de compilación al ejecutar el script. Esto puede suceder con funciones integradas y con funciones personalizadas.

Formato de los argumentos

Al llamar a una función que requiere parámetros, debe incluir los argumentos que usted está pasando a la función. Siga estos lineamientos para dar formato a los argumentos:

Si el argumento es numérico o una variable, no es necesario encerrarlo entre comillas simples o dobles.
Si el argumento es una variable, no es necesario encerrarlo entre llaves.
Si el argumento es alfanumérico y no es una variable, enciérrelo entre comillas simples o dobles.

Por ejemplo, la dateadd() función requiere tres parámetros: unit, date y value.

Unit define la parte de la fecha que desea que cambie la función, como el año o el mes. Date es la fecha original que desea modificar. Y value es cuánto desea que la función aumente la unidad que se especifica en la fecha original. El siguiente ejemplo muestra cómo se le da formato a cada parte:

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

unit es una cadena alfanumérica, por lo que usa un formato con comillas sencillas. date en este ejemplo es una variable, por lo que no tiene comillas. Si pasara una fecha en cadena, requeriría comillas. El value no tiene formato porque es numérico.

Declaraciones de DEVOLUCIÓN

Una declaración RETURN finaliza una función y devuelve el control al script. También puede devolver datos al script.

Las declaraciones RETURN pueden pasar únicamente datos al script como un valor de una variable o arreglo. No pueden pasar valores múltiples, a menos que esos valores sean parte de un arreglo o de un objeto. No pueden pasar objetos, a menos que los objetos se conviertan primero a JSON. Si es necesario, en el script puede convertirlo otra vez en un objeto.

La sintaxis de una declaración RETURN es:

RETURN o RETURN <var>

Todas las funciones integradas que devuelven un valor al script contienen una declaración RETURN. En las funciones personalizadas que usted crea, las declaraciones RETURN son opcionales. Si no hay una declaración RETURN, la función no puede devolver ningún valor al script. La única forma de utilizar una función que no tiene una declaración RETURN es llamándola como declaración.

Si en una función incluye una declaración RETURN, debe ser la última línea de la función.

Visibilidad Variable

El comportamiento predeterminado es que estén disponibles todos los valores de la función y se pueden utilizar únicamente dentro de la función. Cuando finaliza la función, se pierden todos los valores de la misma. Si la función contiene una declaración RETURN que devuelve al script el valor una variable, solo estarán disponibles los valores que se pasen a través de la declaración RETURN fuera de la función.

Si en una función personalizada incluye variables que existen en el script principal, esas variables tienen un alcance global. Esto significa que dichos valores están disponibles fuera de la función sin usar una declaración RETURN. De igual manera, si declara como global una variable dentro de la función, su valor está disponible en el script principal. Esto es similar al comportamiento que se observa en los subscripts.

Cuando utiliza una función en una expresión o como el valor de una variable, sigue el comportamiento predeterminado. Sin embargo, si llama a una función como una declaración, todos los valores de la función tienen alcance global y se pueden usar fuera de la función. En las funciones sin RETURN, esta es la única forma en que se pueden usar.

Crear funciones personalizadas

Puede crear funciones personalizadas cuando tenga código que desee poder usar en varios lugares de su script. Una función personalizada está únicamente disponible dentro del script donde lo cree. Si desea utilizar una función personalizada en un script diferente, debe copiar en ese script el código de definición de la función.

Puede crear una función en una acción Snippet en su script y luego llamarla desde otras acciones Snippet en el mismo script. Si depura el snippet que contiene la definición de la función, se le incluye en la depuración. Sin embargo, no se incluirá la función cuando depure los demás snippets.

La sintaxis para declarar una función personalizada es:

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

FUNCTION es una palabra clave que le permite al script saber que lo que siguiente es una función personalizada. Los nombres de las funciones deben seguir los mismos lineamientos de nomenclatura que las demás entidades de los scripts:

Utilice caracteres alfanuméricos (a-z, A-Z, 0-9).
El primer carácter del nombre debe ser una letra.
Utilice el carácter de guión bajo ( _ ) y el signo de dólar ( $ ) en cualquier parte del nombre.
No utilice palabras reservadas ni nombres de funciones integradas.

Si la función requiere parámetros, colóquelos entre paréntesis al final del nombre de la función. Si no hay ningún parámetro, se pueden dejar vacíos los paréntesis. Separe los parámetros múltiples con comas.

El código que compone la función va entre llaves. Es flexible la ubicación de las llaves. Pueden ir en la misma línea que la palabra clave FUNCTION y el nombre, o pueden estar en líneas separadas. Por ejemplo, las dos siguientes son definiciones de funciones válidas:

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

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

Si la función incluye una declaraciónRETURN, debe ser la última declaración en la función antes de la llave de cierre.

La función no considera que es una cadena, si no hay comillas, sino que asume que es una variable si no hay comillas y no es un número o un valor booleano.

Puede obtener más información sobre la creación de funciones en la página de Declaraciones.

Ayuda de autocompletar en las funciones personalizadas

Puede agregar ayuda de autocompletar en sus funciones personalizadas. Este es un texto de información sobre herramientas que aparece cuando comienza a escribir el nombre de la función en la ventana Snippet Editor. Esta ayuda solo aparece cuando llama a la función con notación de puntos.

Puede utilizar estas sugerencias sobre las herramientas para brindar información útil sobre la función. Por ejemplo, puede usarlas para definir los parámetros de la función.

Para agregar ayuda de autocompletar, agregue un comentario en la misma línea de la declaración de la función. Por ejemplo, para crear la información sobre herramientas que se muestra en la imagen anterior, la declaración de la función se vería así:

FUNCTION MyAppend(a,b) // My function to append the text
{
   RETURN "{a}{b}"
}

Si a una función agrega ayuda de autocompletar, deben colocarse en una línea separada de la definición de la función las llaves que contienen el código de la función. El script considera que todo el texto después de las dos barras diagonales forma parte del comentario. Si las llaves están en la misma línea, el script las incluye en el comentario.

Llamado de funciones en un script

Cuando quiera utilizar una función en su script, debe llamarla. Hay tres formas de llamar a una función. No todas las opciones funcionan con todas las funciones. Las opciones disponibles con una función determinada dependen de si la función devuelve un valor. Puede llamar a una función:

Sola como una declaración. Esta opción funciona con todas las funciones.
En un sitio donde usaría una variable o expresión. Esta opción funciona únicamente con funciones que devuelven un valor.
Con una variable si se usa notación de puntos. Esta opción funciona únicamente con funciones que devuelven un valor.

Llamar a una función como una Declaración

Una declaración es una línea de código con una palabra clave de comando que le dice qué hacer al script. Puede utilizar una función como declaración. Cuando lo haga, no necesitará una palabra clave de comando especial, como sucede con otras declaraciones en un snippet. El código de la función le dice al script qué hacer.

Puede llamar a cualquier función como declaración. Si una función no contiene una declaración RETURN, esa es la única forma de llamarla. Esto se debe a que una declaración RETURN pasa otra vez los datos de la función al script. Cuando no hay un RETURN, llamarla como declaración es la única forma en que el script tiene acceso a los datos de la función.

La sintaxis para llamar a las funciones como declaración es:

El siguiente ejemplo muestra cómo se llama a la función append() como declaración :

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)

Utilice una función en vez de una variable

Cuando una función devuelve un valor, puede usarla en cualquier lugar donde usaría una variable o expresión. El script puede usar el valor que devuelve la función como lo haría con el valor de la variable o el resultado de la expresión.

Las sintaxis para usar una función en vez de una variable son:

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

Si desea que se asigne a una variable el resultado de la función, puede llamar a la función como parte de una declaración ASSIGN. Por ejemplo, ASSIGN var = otherVar.function() Sin embargo, hay un caso en el que esto no funciona, y es llamar a una función miembro de la GetRESTproxy() función.

El siguiente ejemplo muestra cómo se utiliza una función que devuelve un valor. Esta es la función de ejemplo:

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

Esta función reemplaza el carácter ampersand ( & ) con la palabra and. En el siguiente ejemplo, se utiliza la función replaceCharacters() en vez de una variable en el valor de cadena de la variable stringRes. Cuando se ejecuta este código, se actualiza el valor de stringRes a My favorite animals are dogs and cats.

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

Utilice una función con notación de puntos

Cuando las funciones devuelven un valor, puede usarlas con variables usando notación de puntos. Esto adjunta la función a la variable, de esta forma: variable.function(). Cuando llama a una función de esta manera, se pasa a la función el valor de la variable. Esta opción funciona únicamente con funciones que devuelven un valor.

La sintaxis para usar una función con notación de puntos:

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

El siguiente ejemplo muestra este método. Esta es la función:

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

Este es un ciclo FOR que utiliza la función MyAppend con la variable ph:

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

El resultado del ciclo FOR es: ph="123456789".

Cuando llama a una función usando notación de puntos, el valor de la variable a la que se adjunta se pasa a la función como argumento para el primer parámetro. En el ejemplo anterior, el valor inicial de ph se pasa a la función MyAppend() como argumento para el parámetro a. Es por eso que llamar a la función incluye únicamente un argumento cuando la definición de la función tiene dos parámetros. Se pasa el valor inicial de i a la función como argumento para el parámetro b.

El beneficio de llamar a funciones con notación de puntos es que le permite agregar ayuda de sugerencias sobre herramientas para la función.