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 en Studio para usarse 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.

Sintaxis

Los nombres de función tienen un conjunto de paréntesis de apertura y cierre 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 da inicio a todas las declaraciones de función personalizada.
• <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:

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

<{<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 los paréntesis que siguen al 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 correcto. Sin embargo, si el argumento no es del tipo o formato que la función espera, es posible que la función no se complete correctamente, o que los resultados no sean precisos.

Si se pasan demasiados o muy pocos argumentos a la función, 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 la cantidad que desea que la función incremente la unidad especificada de la fecha original. El siguiente ejemplo muestra cómo se le da formato a cada parte:

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

El unit es una cadena alfanumérica, por lo que se formatea con comillas simples. La 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 se formatea 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 instrucciones RETURN solo pueden pasar datos al script como un valor de Variable o una matriz. No pueden pasar valores múltiples, a menos que esos valores formen parte de una matriz o un objeto. No pueden pasar objetos, a menos que los objetos se conviertan primero a JSON. Si es necesario, puede convertirlo de nuevo en un objeto en el script.

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 manera en que puede usar una función que no tenga una instrucción RETURN es llamándola como una instrucción.

Si incluye una instrucción RETURN en una función, 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 múltiples 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 de Snippet en su script y, luego, llamarla desde otras acciones de Snippet en el mismo script. Si depurar el Snippet que contiene la definición de la función, se 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 indica al script que lo que sigue 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 las llaves. La colocación de las llaves es flexible. 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 instrucción RETURN, debe ser la última instrucción en la función antes de la llave de cierre.

Obtenga más información sobre la creación de funciones en la página de instrucciones de declaración.

Funciones de llamada 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:

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

El siguiente ejemplo muestra la función append() siendo llamada como una instrucció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:

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

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

Si desea que el resultado de la función se asigne a una Variable, 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 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 de ampersand ( & ) por la palabra and. En el siguiente ejemplo, la función replaceCharacters() se utiliza en lugar de una variable en el valor de cadena de la variable stringRes. Cuando se ejecuta este código, el valor de stringRes se actualiza a MIs animales favoritos SOn los perros y los gatos.

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 la siguiente manera: 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 el 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. El valor inicial de i se pasa a la función como el 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.