Functies

Een functie is een herbruikbaar codeblok dat een bepaalde taak uitvoert. Telkens wanneer u die taak nodig hebt, kunt u de functie in uw script gebruiken. Dit bespaart u de tijd en inspanningen die zijn vereist om code toe te voegen voor die taak aan uw script, telkens wanneer u die nodig hebt. Dit houdt uw scripts ook altijd schoner en minder rommelig door de hoeveelheid code in het script te verminderen.

Functies kunnen:

• Neem gegevens van het script, manipuleer ze en stuur dan de resultaten terug naar het script.
• Voer een actie of een reeks acties uit en geef de resulterende gegevens door aan het script.

Sommige functies zijn geïntegreerd in Studio voor gebruik in uw scripts. U hoeft niets toe te voegen aan uw script om een ingebouwde functie te gebruiken. Wanneer u een functie wilt gebruiken, kunt u deze gewoon oproepen.

U kunt ook uw eigen aangepaste functies maken voor gebruik in een script. Dit is nuttig wanneer u code hebt die u frequent gebruikt in uw script. In plaats van het telkens wanneer u het nodig hebt, toe te voegen aan uw script, kunt u een functie maken die de code bevat. Wanneer u dan die code nodig hebt, kunt u de functie oproepen.

Syntax

Functienamen hebben een set van open en gesloten haakjes aan het einde ervan: functionName().

Elke tekst tussen haakjes is een parameter die de gegevens definieert die tussen de functie en het script zijn gepasseerd: functionName(param1,param2).

Gebruik deze syntaxis om een aangepaste functie te maken:

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

In deze syntaxis:

• FUNCTION is het vereiste trefwoord dat alle aangepaste functieverklaringen start.
• <name> is de naam van de functie.
• ([<parameter>] [...]) definieert alle parameters die de functie vereist.
• { ... } bevat de code van de functie.
• [RETURN <data>] is de verklaring die moet worden opgenomen om gegevens door te geven van de functie naar het hoofdscript.

U kunt uw aangepaste functies een willekeurig naam geven, zoals u deze richtlijnen volgt:

• Gebruik alfanumerieke tekens (a-z, A-Z, 0-9).

• Het eerste teken in de naam moet een letter zijn.
• Gebruik het onderstrepingsteken (_) en het dollarteken ($) overal in de naam.
• Gebruik geen gereserveerde woorden of de namen van ingebouwde functies.

De syntax voor een RETURN-verklaring is:

RETURN of RETURN <var>

Gebruik van een van de volgende syntaxis wanneer u een functie oproept::

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

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

Parameters en argumenten

Talrijke functies moeten gegevens van het script gebruiken. U kunt dit doen met parameters en argumenten.

Parameters worden gedefinieerd wanneer een functie wordt gemaakt. Een parameter is een variabele naam die verschijnt tussen de haakjes die de naam van de functie volgen. Een functie kan meer dan één parameter hebben. Elke parameter is gescheiden door een komma. Als u dat wilt kunt u een spatie opnemen, maar dat is niet vereist. De functie logn(value, base) heeft bijvoorbeeld twee parameters value en base.

De specifieke gegevens die het script doorgeeft in de functie via de parameters, worden argumenten genoemd. Het volgende voorbeeld toont het gebruik van de ingebouwde functie abs(value) in een script. In dit voorbeeld is -45 het argument dat wordt doorgegeven in de value-parameter.

ASSIGN abVal = abs(-42)

In Studio zijn alle parameters vereist. Als een functie is gedefinieerd met een parameter, moet u een waarde doorgeven waarin u de functie oproept. Het aantal argumenten dat is doorgegeven in de functie, moet overeenkomen met het aantal gedefinieerde parameters.

Het script controleert niet of de argumenten het juiste type of formaat zijn. Als het argument echter niet van het type of formaat is dat de functie verwacht, zal de functie niet worden voltooid of zijn de resultaten mogelijk niet nauwkeurig.

Als teveel of te weinig argumenten worden doorgegeven in de functie, veroorzaakt dit een compilatiefout wanneer u het script uitvoert. Dit kan gebeuren voor ingebouwde functies en aangepaste functies.

Argumentopmaak

Wanneer u een functie oproept die parameters vereist, moet u de argumenten opnemen die u doorgeeft in de functie. Volg deze richtlijnen voor het opmaken van de argumenten:

• Als het argument numeriek of een variabele is, hoeft u het niet tussen enkele of dubbele aanhalingstekens te plaatsen.
• Als het argument een variabele is, hoeft u het niet tussen accolades te zetten.
• Als het argument alfanumeriek en geen variabele is, plaatst u dat tussen enkele of dubbele aanhalingstekens.

De dateadd() -functie vereist bijvoorbeeld drie parameters, unit, date en value.

Unit Definieert het deel van de datum waarop de functie moet wijzigen, zoals het jaar of de maand. Date Is de originele datum die u wilt wijzigen. En value is hoeveel de functie de opgegeven eenheid van de originele datum moet vermeerderen. Het volgende voorbeeld laat zien hoe elk deel is opgemaakt:

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

De unit is een alfanumerieke string en wordt daarom opgemaakt met enkele aanhalingstekens. De date in dit voorbeeld is een variabele en heeft daarom geen aanhalingstekens. Als u een stringdatum passeert, zijn aanhalingstekens vereist. De value is niet opgemaakt omdat het een numerieke waarde is.

Retourverklaringen

Een RETURN-verklaring eindigt een functie en geeft de controle terug aan het script. Dit kan ook gegevens terug doorgeven naar het script:

RETURN-Verklaringen kunnen alleen gegevens doorgeven aan het script als een variabele waarde of een array. Ze kunnen niet meerdere waarden doorgeven, tenzij die waarden deel uitmaken van een array of een object. Ze kunnen geen objecten doorgeven, tenzij de objecten eerst worden geconverteerd naar JSON. Indien nodig kunt u dit terug converteren naar een object in het script.

De syntax voor een RETURN-verklaring is:

RETURN of RETURN <var>

Alle ingebouwde functies die een waarde retourneren naar het script, bevatten een RETURN-verklaring. In aangepaste functies die u maakt, zijn RETURN-verklaring optioneel. Als er geen RETURN-verklaring is, kan de functie geen waarden terug doorgeven aan het script. De enige manier waarop u een functie kunt gebruiken die geen RETURN-verklaring heeft, is door het op te roepen als een verklaring.

Als u een RETURN-verklaring opneemt in een functie, moet he de laatste lijn in de functie zijn.

Zichtbaarheid van variabelen

Het standaard gedrag is dat alle waarden in de functie alleen beschikbaar en bruikbaar zijn met de functie. Wanneer de functie eindigt, gaan alle waarden in de functie verloren. Als de functie een RETURN-verklaring bevat die een variabele waarde terug doorgeeft naar het script, zijn alleen de waarden die zijn doorgegeven via de RETURN-verklaring beschikbaar buiten de functie.

Als u variabelen opneemt in een aangepaste functie die bestaat in het hoofdscript, hebben die variabelen een algemene scope. Dit betekent dat deze waarden beschikbaar zijn buiten de functie zonder een RETURN-verklaring te gebruiken. Op dezelfde manier is de waarde van een variabele, als u deze binnen de functie als algemeen declareert, beschikbaar in het hoofdscript. Dit is vergelijkbaar met het gedrag dat merkbaar is in subscripts.

Als u een functie gebruikt in een expressie of als de waarde van een variabele, volgt deze het standaardgedrag. Als u echter een functie oproept als een verklaring, hebben alle waarden in de functie een algemene scope en zijn ze beschikbaar voor gebruik buiten de functie. Voor functies zonder een RETURN, is dit de enige manier waarop ze kunnen worden gebruikt.

Aangepaste functies maken

U kunt aangepaste functies maken wanneer u nuttig wanneer u code hebt die u op meerdere plaatsen in uw script wilt gebruiken. Een aangepaste functie is alleen beschikbaar binnen het script waar u het maakt. Als u een aangepaste functie in een ander script wilt gebruiken, moet u de functiedefinitiecode kopiëren in dat script.

U kunt een functie maken in één Snippet-actie in uw script en het dan oproepen van andere Snippet-acties in hetzelfde script. Als u de snippet die de functiedefinitie bevat debugt, is deze opgenomen in de debug. De functies zal echter niet worden opgenomen bij het debuggen van de andere snippets.

De syntaxis voor het declareren van een aangepaste functie is:

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

FUNCTION is een trefwoord dat het script laat weten dat hetgeen volgt een aangepaste functie is. Functienamen moeten dezelfde naamgevingsrichtlijnen als andere entiteiten in scripts volgen:

• Gebruik alfanumerieke tekens (a-z, A-Z, 0-9).

• Het eerste teken in de naam moet een letter zijn.
• Gebruik het onderstrepingsteken (_) en het dollarteken ($) overal in de naam.
• Gebruik geen gereserveerde woorden of de namen van ingebouwde functies.

Als de functie parameters vereist, plaatst u ze tussen de haakjes aan het einde van de functienaam. Als er geen parameters zijn, kunnen de haakjes leeg blijven. Scheid meerdere parameters met komma's.

De code waaruit de functie wordt gemaakt, wordt tussen accolades geplaatst. De plaatsing van accolades is flexibel. Ze kunnen op dezelfde regel als het FUNCTION trefwoord en de naam staan, of ze kunnen op afzonderlijke regels staan. Beide van de volgende zijn bijvoorbeeld geldige functiedefinities:

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

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

Als de functie een RETURN-verklaring bevat, moet dit de laatste verklaring in de functie zijn vóór de afsluitende accolade.

functie gebruikt geen string, geen aanhalingstekens, maar veronderstelt variabele als er geen aanhalingstekens en geen nummer of boolean zijn

Raadpleeg de pagina Declaratieverklaringen voor meer informatie over het maken van functies.

Help Automatisch invullen voor aangepaste functies

U kunt Help Automatisch invullen toevoegen voor uw aangepaste functies. Dit is tekst van knopinfo die verschijnt wanneer u de naam van de functie begint te typen in het Snippet editor-venster. Dit helpbestand verschijnt alleen wanneer de functie met puntnotatie wordt opgeroepen.

Afbeelding weergeven

U kunt deze knopinfo gebruiken om nuttige informatie over de functie te geven. U kunt dit bijvoorbeeld gebruiken om de parameters van de functie te definiëren.

Om Help automatisch invullen toe te voegen, voegt u een opmerking toe op dezelfde lijn als de functiedeclaratie. Om bijvoorbeeld de knopinfo te maken die in de vorige afbeelding wordt weergegeven, zal uw functiedeclaratie er als volgt uitzien:

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

Als u Help Automatisch invullen toevoegt aan een functie, moeten de accolades die de functiecode bevatten, op een afzonderlijke regel van de functiedefinitie worden geplaatst. Het script beschouwt alle tekst na de twee schuine strepen als deel van de opmerking. Als de accolades op dezelfde regels staan, neemt het script ze op in de opmerking.

Functies oproepen in een script

Wanneer u een functie wilt gebruiken in uw script, moet u deze oproepen. Er zijn drie manieren waarop u de functie kunt oproepen. Niet elke optie werkt voor alle functies. De beschikbare opties voor een bepaalde functie, hangen af van het feit of de functie een waarde retourneert. U kunt een functie oproepen:

• Alleen, zoals een verklaring. Deze optie werkt met alle functies.
• Op een plaats waar u een variabele of expressie zou gebruiken. Deze optie werkt alleen met functies die een waarde retourneren.
• Met een variabele die een puntnotatie gebruikt. Deze optie werkt alleen met functies die een waarde retourneren.

Een functie oproepen als een verklaring

Een verklaring is een codelijn met een opdrachttrefwoord dat het script vertelt wat het moet doen. U kunt een functie gebruiken als een verklaring. Wanneer u dat doet, hebt u geen speciaal opdrachttrefwoord nodig, zoals met andere verklaringen in een snippet. De code in de functie vertelt het script wat het moet doen.

U kunt elke functie oproepen als een verklaring. Als een functie geen RETURN-verklaring bevat, is dit de enige manier waarop u deze kunt oproepen. Dit is omdat een RETURN-verklaring gegevens van de functies terug in het script doorgeeft. Als er geen RETURN is, kan het script alleen toegang krijgen tot de gegevens in de functie door het op te roepen als een verklaring.

De syntaxis voor het oproepen van functies als een verklaring is:

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

Het volgende voorbeeld toont de append()-functie die wordt opgeroepen als een verklaring:

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)

Een functie in de plaats van een variabele gebruiken

Wanneer een functie een waarde retourneert, kunt u deze overal gebruiken waar u een variabele of expressie zou gebruiken. Het script kan de waarde die de functie retourneert, gebruiken zoals de waarde van de variabele of het resultaat van de expressie.

De syntaxen voor het gebruik van een functie in de plaats van een variabele zijn:

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

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

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

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

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

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