CoCoS Scripting : PHP

In CoCoS kunnen scripts worden ontwikkelt en worden uitgevoerd in diverse talen. Eén van deze talen is het breedt gedocumenteerde en veel gebruikte PHP. Indien u niet bekend bent met PHP kunnen we de volgende websites ten zeerste aanbevelen:

https://www.w3schools.com/php/

https://www.php.net/

https://www.phptutorial.net/

Script Parameter

tagGet functies

tagGet functies zijn functie die gebruikt kunnen worden om de actuele waarde van een tag op te halen. Indien de normale $cocos->tagGet wordt gebruikt, betreft het altijd de laatste waarde, dit kan zowel de ontvangen als de verstuurde waarde zijn. Gebruik voor het ophalen van de laatste verstuurde waarde $cocos->tagGetSent en voor het ophalen van de laatst ontvangen waarde $cocos->tagGetRecveived.

// get a string value
$tagValue = $cocos->tagGet("tagname");

// get the tag value in integer formace
$tagValue = intval($cocos->tagGet("tagname"));

// get a string value
$tagValue = $cocos->tagGetValue("tagname");

// get the tag value in integer formace
$tagValue = intval($cocos->tagGetValue("tagname"));

// get a string value
$tagValue = $cocos->tagGetReceived("tagname");

// get the tag value in integer formace
$tagValue = intval($cocos->tagGetReceived("tagname"));

tagGetPrevious functies

tagGetPrevious functies kunnen gebruikt worden  om niet de actuele waarde van een tag, maar de voorlaatste waarde op te halen. Indien de normale $cocos->tagGetPrevious wordt gebruikt, betreft het altijd de laatste waarde, dit kan zowel de ontvangen als de verstuurde waarde zijn. Gebruik voor het ophalen van de laatste verstuurde waarde $cocos->tagGetSentValuePrevious en voor het ophalen van de laatst ontvangen waarde $cocos->tagGetReceivedPrevious.

// examples heren

// examples heren

// examples heren

TagWait functies

tagWait functies kunnen gebruikt worden om te wachten totdat de opgegeven tag de opgegeven waarde bevat. Wanneer bijvoorbeeld een reactie wordt verwacht na het uitvoeren van een bepaalde actie, zoals bijv. $cocos->tagSet, kan $cocs->tagWait gebruikt worden om hierop te wachten. 

Let op! Gedurende de $cocos->tagWait, doet het scripts niets anders dan wachten. Dit betreft een synchrone uitvoering en 'blokkeert' de uitvoeren van het script zolang er gewacht wordt op deze waarde. Houdt er rekening mee dat wanneer meerdere scripts met een $cocos->tagWait bezig zijn, dit er mogelijk voor kan zorgen dat hiervoor andere scripts tijdelijk niet uitgevoerd kunnen worden. 

• $cocos->tagWait(string $name, $value, int $timeout [optional, default: 20000]) : bool
  Wacht totdat de opgegeven tag de opgegeven waarde bevat. Optioneel kan hieraan een timeout worden meegegeven hoelang er gewacht mag worgen.
  
  
• $cocos->tagWaitValue(string $name, $value, int $timeout [optional, default: 20000]) : string
  Alias van $cocos->tagWait()
  
  
• $cocos->tagWaitSentValue(string $name, $value, int $timeout [optional, default: 20000]) : bool
  Wacht totdat de opgegeven tag de opgegeven waarde verstuurd heeft. Optioneel kan hieraan een timeout worden meegegeven hoelang er gewacht mag worgen.
  
  
• $cocos->tagWaitReceivedValue(string $name, $value, int $timeout [optional, default: 20000]) : bool
  Wacht totdat de opgegeven tag de opgegeven waarde ontvangen heeft. Optioneel kan hieraan een timeout worden meegegeven hoelang er gewacht mag worgen.

TagSet functies

tagSet functies worden gebruikt om een tag op een bepaalde waarde in te stellen. Optioneel kan de tagSet vertraagd ($cocos->tagSetDelayed) of zonder uitvoering van triggers ($cocos->tagSetNoTriggers) worden aangeroepen. Door de functie $cocos->tagSetCreate te gebruiken wordt bij het instellen van de waarde eerste gecontroleerd of de tag reeds aanwezig is, is dit niet het geval, dan wordt deze aangemaakt.

• $cocos->tagSet(string $name, string $value) : bool
  Schrijft de opgegeven waarde in een tag. Door gebruik te maken van de * als wildcard-teken, kunnen in 1 keer meerdere tags voorzien worden van een waarde.
  
  
• $cocos->tagSetWait(string $name, string $value, int $timeout [optional, default: 20000]) : bool
  Schrijft de opgegeven waarde in een tag en wacht totdat deze waarde terug is onvangen/bevestigd. De opgegeven $timeout is het aantal milliseconden, indien geen $timeout wordt meegegeven, zal hier standaard de waarde 10000 (10 seconden) gebruikt worden. Deze functie geeft als resultaat TRUE wanneer de waarde binnen de gestelde $timeout wordt ontvangen/bevestigd, anders FALSE om aan te geven dat het niet gelukt is.
  
  
• $cocos->tagSetDelayed(string $name, string $value, int $delay [optional, default: 0]) : bool
  Zorgt ervoor dat de opgegeven waarde in de tag wordt geschreven na het verstrijken van de opgegeven vertraging. De opgegeven $delay is het aantal milliseconden.
  
  

  Let op! Er kan maar maximaal 1 vertraging/timer per tag lopen. Elke volgende tagSetDelay zal ervoor zorgen dat voorgaande timers gereset worden en er een nieuwe gestart wordt.

  
  
• $cocos->tagSetNoTriggers(string $name, string $value) : bool
  Schrijft de opgegeven waarde in een tag. In tegenstelling tot $cocos->tagWait() zullen de triggers aan deze tag niet uitgevoerd worden bij deze actie.
  
  
• $cocos->tagSetDelayedNoTriggers(string $name, string $value, int $delay [optional, default: 0]) : bool
  Combinatie van $cocos->tagSetDelayed(); en $cocos->tagSetNoTriggers();
  
  
• $cocos->tagSetCreate(string $name, string $value, string $type [optional, default:'text'], string $comments [optional]) : bool
  Schrijft de opgegeven waarde in een tag. Indien de tag niet bestaat wordt deze aangemaakt. Het op te geven $type kan zijn: 'text', 'bool', 'int', 'decimal' of 'color'. Indien geen $type wordt meegegeven, zal hier standaard de waarde 'text' gebruikt worden. Zie hiervoor ook de pagina TagTypes Gebruik $comments om de nieuw aan te maken tag te voorzien van commentaar/een omschrijving.

Tag functies (overig)

• $cocos->tagGetTimestamp(string $name) : float
  Haalt de tijdstempel op van wanneer deze tag voor het laatste een waarde heeft gehad. Dit kan zowel de ontvangen als de verstuurde waarde zijn.
  
  
• $cocos->tagGetCreate(string $name, string $value=null, string $type [optional, default:'text'], string $comments [optional])
  Haalt de laatst bekende waarde op van een tag. Indien de tag niet bestaat wordt deze aangemaakt. Het op te geven $type kan zijn: 'text', 'bool', 'int', 'decimal' of 'color'. Indien geen $type wordt meegegeven, zal hier standaard de waarde 'text' gebruikt worden. Zie hiervoor ook de pagina TagTypes Gebruik $comments om de nieuw aan te maken tag te voorzien van commentaar/een beschrijving Indien voor $value een waarde wordt opgegeven zal deze (wanneer de tag niet bestond) gelijk worden ingesteld, er vind dan dus óók een tagSet plaats.
  
  
• $cocos->tagsFind(string $search) : array
  Haal de namen op van alle tags die overeenkomen met de opgegeven zoekterm. De gevonden tags worden teruggestuurd in een array, waarbij elk element één tagnaam bevat. Gebruik bijvoorbeeld $cocos->tagsFind('*.status') voor het ophalen van alle statussen van alle apparaten. Of bijvoorbeeld $cocos->tagsFind('device_PLC001.*') om alle tags op te halen van apparaat PLC001.
  
  
• $cocos->tagExists(string $name) : bool
  Controlleeert of de tag met de opgegeven naam bestaat.
  
  
• $cocos->tagIncrease(string $name, int $amount [optional, default: 1]) : bool
  Haalt de huidige, actuele waarde op van de opgegeven tag en hoogte deze op met het opgegeven aantal.
  
  
• $cocos->tagDecrease(string $name, int $amount [optional, default: 1]) : bool
  Haalt de huidige, actuele waarde op van de opgegeven tag en verminderd deze op met het opgegeven aantal.
  
  
• $cocos->tagMultiply(string $name, int $amount [optional, default: 1]) : bool
  Haalt de huidige, actuele waarde op van de opgegeven tag en vermenigvuldigt deze met de opgegeven waarde.
  
  
• $cocos->tagDivide(string $name, int $amount [optional, default: 1]) : bool
  Haalt de huidige, actuele waarde op van de opgegeven tag en deelt deze door de opgegeven waarde.
  
  
• $cocos->tagCopy(string $nameOfSourceTag, string $nameOfTargetTag) : bool
  Kopieer de waarde van de opgegeven bron-tag ($nameOfSourceTag) naar de opgegeven doel-tag ($nameOfTargetTag).
  
  
• $cocos->tagMove(string $nameOfSourceTag, string $nameOfTargetTag) : bool
  Verplaatst de waarde van de opgegeven bron-tag ($nameOfSourceTag) naar de opgegeven doel-tag ($nameOfTargetTag).
  
  

  Let op! Bij een tagMove wordt de waarde uit de bron-tag weggehaald. Het gaat hier dus écht om het verplaatsen van de waarde van de ene naar de andere tag.

// examples here
$cocos->tagSimulateReceive("device_FooBar.message", "FooBar");

$cocos->tagSimulateReceive("device_FooBar.message", 1);

$cocos->tagSimulateReceive("device_FooBar.message", ["Foo", "Bar", 1]);

$cocos->tagSimulateReceive("device_FooBar.*", "FooBar");

$cocos->tagSimulateReceive("device_FooBar.*", 1);

$cocos->tagSimulateReceive("*.message", ["Foo", "Bar", 1]);

TagStatus functies

• $cocos->tagGetStatus(string $name) : int
  Verkrijg de status van de tag met de opgegeven naam. 0x0 = Offline, 0x1 = Actief, 0x2 = Gearchiveerd, 0x4 = Verwijderd.
  
  

  Op de pagina TagStatussen staat een volledig overzicht van alle tagstatussen die binnen CoCoS gebruikt worden.

  
  
• $cocos->tagGetState(string $name) : int
  Verkrijg de staat van de tag met de opgegeven naam, bijvoorbeeld 'Ok', 'Warning' of 'Unreliable'.
  
  
• $cocos->tagStateOk(string $name) : bool
  Geeft aan of de tag met de opgegeven naam de status 'Ok' heeft.
  
  
• $cocos->tagStateWarning(string $name) : bool
  Geeft aan of de tag met de opgegeven naam de status 'Warning' heeft.
  
  
• $cocos->tagStateError(string $name) : bool
  Geeft aan of de tag met de opgegeven naam de status 'Error' heeft.
  
  
• $cocos->tagStateUnreliable(string $name) : bool
  Geeft aan of de tag met de opgegeven naam de status 'Unreliable' (onbetrouwbaar) heeft.
  
  
• $cocos->tagStateUnavailable(string $name) : bool
  Geeft aan of de tag met de opgegeven naam de status 'Unavailable' (niet beschikbaar) heeft.

TagLog functies:

• $cocos->tagLogGetLastSample(string $name) : float
  Haalt de tijdstempel op van de laatste keer dat er samples/waardes zijn opgeslagen voor de taglog met de opgegeven naam.
  
  
• $cocos->tagLogSampleNow(string $name) : float
  Forceer het opslaan van samples/waardes van alle tags uit de taglog met de opgegeven naam.

Config functies:

• $cocos->configGet(string $name, string $library [optional], string $collection [optional], string $type [optional]) : string
  Haal een waarde op uit de configuratie van het systeem. Geef hierbij eventueel op voor welke biblotheek, collectie en type item deze configuratie van toepassing is.
  
  
• $cocos->configSet(string $name, string $value, string $library [optional], string $collection [optional], string $type [optional]) : string
  Schrijf een waarde in de configuratie van het systeem. Geef hierbij eventueel op voor welke biblotheek, collectie en type item deze configuratie van toepassing is.
  
  
• $cocos->configSetCreate(string $name, string $value, string $library [optional], string $collection [optional], string $type [optional], string $form [optional, default 'input'], string $comments [optional]) : string
  Schrijf een waarde in de configuratie van het systeem. Geef hierbij eventueel op voor welke biblotheek, collectie en type item deze configuratie van toepassing is. Indien de configuratie-variabele niet bestaat wordt deze aangemaakt. De op te geven $form kan zijn: 'input', 'number', 'toggle', 'select' of 'duration'. Dit bepaald op welke manier de configuratie-variabele ingevoerd kan worden.

Notificatie functies:

• $cocos->notificationSet(string $notification, array $params);
  Activeer een notificatie. Gebruik $notification om aan te geven om welke notificatie het gaat, de waardes uit $parameters zullen gebruikt worden voor het dynamisch genereren van het juiste bericht in de notificatie-lijst.
  
  
• $cocos->notificationAcknowledge(string $notification, array $params);
  Bevestig een notificatie. Gebruik $notification om aan te geven om welke notificatie het gaat. Op basis van de waardes uit $parameters kan een reeds geactiveerde noficatie bevestigd worden.
  
  
• $cocos->notificationAck(string $name);
  Alias van $cocos->notificationAcknowledge()
  
  
• $cocos->notificationSetAndAcknowledge(string $notification, array $params);
  Activeer én bevestig een notificatie. Gebruik $notification om aan te geven om welke notificatie het gaat. Op basis van de waardes uit $parameters kan een reeds geactiveerde noficatie bevestigd worden.
  
  
• $cocos->notificationSetAndAck(string $name);
  Alias van $cocos->notificationSetAndAcknowledge()
  
  
• $cocos->notificationReset(string $notification, array $params);
  Reset een notificatie. Gebruik $notification om aan te geven om welke notificatie het gaat. Op basis van de waardes uit $parameters kan een reeds geactiveerde/bevestigde noficatie gereset worden.
  
  
• $cocos->notificationResetAll(string $notification);
  Reset alle notificaties. Deze functie werkt dus zonder $parameters, maar zal ervoor zorgen dat alle meldingen uit de notificatie-lijst van hetzelfde type gereset worden.

Invoker functies:

Wanneer een script, al dan niet middels een trigger op bijvoorbeeld een tag, wordt uitgevoerd als gevolg van de actie van een gebruiker (bijvoorbeeld iemand die is ingelogd op een bedieningsinterface) kan met behulp van de invoker functies informatie worden opgehaald over wie/welke persoon/vanaf welke locatie/met welk toestel verantwoordelijk was voor de uitvoer van het script.

• $cocos->getInvokerData() : array
  Haalt alle informatie op van de 'invoker' van dit script. Deze informatie bevat met welke applicatie, door welke gebruiker, met welke apparaat en vanaf welke locatie dit script is aangestoten/uitgevoerd.
  
  
• $cocos->getInvokerRelationName() : string
  De naam van de relatie die dit script heeft aangestoten/uitgevoerd.
  
  
• $cocos->getInvokerUsersName() : string
  De naam van de gebruiker die dit script heeft aangestoten/uitgevoerd.
  
  
• $cocos->getInvokerName() : string
  De naam van de relatie (indien beschikbaar) die dit script heeft aangestoten/uitgevoerd. Indien niet beschikbaar zal de naam van de gebruiker worden teruggestuurd.
  
  
• $cocos->getInvokerLocation() : string
  De naam van de topologie/locatie vanaf waar dit script is aangestoten/uitgevoerd.
  
  
• $cocos->getInvokerIntercomNumber() : string
  Intercom-nummer van het toestel, gekoppeld aan de topologie/locatie vanaf waar dit script is aangestoten/uitgevoerd.

Apparaat functies:

• $cocos->deviceRestart(string $prefix) : bool
  Markeer het apparaat, op basis van de prefix, om te gaan herstarten
  
  
• $cocos->deviceRestartByPrefix(string $name);
  Alias van $cocos->deviceRestart()
  
  
• $cocos->deviceRestartByName(string $name) : bool
  Markeer het apparaat, op basis van de naam, om te gaan herstarten

ApparaatStatus functies:

• $cocos->deviceGetStatus(string $name) : int
  Verkrijg de status van het apparaat met de opgegeven naam. 0x0 = Offline, 0x1 = Actief, 0x2 = Gearchiveerd, 0x4 = Verwijderd.
  
  
• $cocos->tagGetState(string $name) : int
  Verkrijg de staat (waarde van de status-tag) van het apparaat met de opgegeven naam. 0x2 = Running, 0x20 = Connected, 0x4000 = Available etc.
  
  

  Op de pagina CoCoS Apparaat Statussen staat een volledig overzicht van alle apparaatstatussen die binnen CoCoS gebruikt worden.

  
  
• $cocos->deviceStateRunning(string $name) : bool
  Geeft aan of de status-tag van het apparaat met de opgegeven naam de waarde 'Running' (0x2) heeft.
  
  
• $cocos->deviceStateConnected(string $name) : bool
  Geeft aan of de status-tag van het apparaat met de opgegeven naam de waarde 'Connected' (0x20) heeft.
  
  
• $cocos->deviceStateAvailable(string $name) : bool
  Geeft aan of de status-tag van het apparaat met de opgegeven naam de waarde 'Available' (0x4000) heeft.
  
  
• $cocos->deviceStatePingOk(string $name) : bool
  Geeft aan of de status-tag van het apparaat met de opgegeven naam de waarde 'PingOk' (0x100000) heeft.
  
  
• $cocos->deviceStateWarning(string $name) : bool
  Geeft aan of de status-tag van het apparaat met de opgegeven naam de waarde 'Warning' (0x100) heeft.
  
  
• $cocos->deviceStateError(string $name) : bool
  Geeft aan of de status-tag van het apparaat met de opgegeven naam de waarde 'Error' (0x200) heeft.
  
  
• $cocos->deviceStateLost(string $name) : bool
  Geeft aan of de status-tag van het apparaat met de opgegeven naam de waarde 'Lost' (0x10000) heeft.
  
  
• $cocos->deviceStateGone(string $name) : bool
  Geeft aan of de status-tag van het apparaat met de opgegeven naam de waarde 'Gone' (0x20000) heeft.

URL functies:

• $cocos->urlCall(string $url, array $headers [optional]) : string
  Gebruik deze functie om een URL aan te roepen. Optioneel kan een array met header worden opgegeven, die zullen worden meegestuurd met het request. Bijvoorbeeld $headers = array('User-Agent' => 'CoCoS').
  
  
• $cocos->urlGet(string $url, array $headers [optional]) : string
  Alias van $cocos->urlCall()
  
  
• $cocos->urlPost(string $url, $data [optional], string $format [optional], array $headers [optional]) : string
  Deze functie roept een URL aan, door gebruik te maken van de POST methode. Gebruik de $data-parameter om extra data mee te sturen met het request. Dit kan zowel een string als een array zijn. In het geval van een array wordt deze, op basis van het opgegeven $format, geconverteerd. Gebruik 'json' voor de parameter $format om de opgegeven array in de $data-parameter om te vormen naar een JSON-object. Indien er geen $format wordt opgegeven, zal de array in de $data-parameter gebruikt worden als regulieren URL-parameters. Indien de $data-parameter een string is, zal deze 1-op-1 worden doorgestuurd. Gebruik optioneel de $headers-parameters om extra headers mee te sturen met het request.
  
  
• $cocos->urlPut(string $url, $data [optional], string $format [optional], array $headers [optional]) : string
  Deze functie roept een URL aan, door gebruik te maken van de PUT methode. Zie de functie $cocos->urlPost() voor het gebruik van de parameters $data, $format en $headers.
  
  
• $cocos->urlPatch(string $url, $data [optional], string $format [optional], array $headers [optional]) : string
  Deze functie roept een URL aan, door gebruik te maken van de PATCH methode. Zie de functie $cocos->urlPost() voor het gebruik van de parameters $data, $format en $headers.
  
  
• $cocos->urlDelete(string $url, $data [optional], string $format [optional], array $headers [optional]) : string
  Deze functie roept een URL aan, door gebruik te maken van de DELETE methode. Zie de functie $cocos->urlPost() voor het gebruik van de parameters $data, $format en $headers.

Log functies:

• $cocos->logError(string $message, string $comments [optional, default: '']);
  Log een bericht naar het systeem van het type error. Gebruik $message voor het bericht dat getoond wordt in het logboek. Gebruik $comments om de log-regel te voorzien van extra commentaar/opmerkingen.
  
  
• $cocos->logWarning(string $message, string $comments [optional, default: '']);
  Log een bericht naar het systeem van het type error. Gebruik $message voor het bericht dat getoond wordt in het logboek. Gebruik $comments om de log-regel te voorzien van extra commentaar/opmerkingen.
  
  
• $cocos->logInfo(string $message, string $comments [optional, default: '']);
  Log een bericht naar het systeem van het type error. Gebruik $message voor het bericht dat getoond wordt in het logboek. Gebruik $comments om de log-regel te voorzien van extra commentaar/opmerkingen.
  
  
• $cocos->logDebug(string $message, string $comments [optional, default: '']);
  Log een bericht naar het systeem van het type error. Gebruik $message voor het bericht dat getoond wordt in het logboek. Gebruik $comments om de log-regel te voorzien van extra commentaar/opmerkingen.

script functies

script functies zijn functies/methodes die gebruikt kunnen worden om vanuit het ene script een ander script aan te roepen. Dit script wordt dan toegevoegd aan de 'script wachtrij' en asynchroon uitgevoerd.

// Store the name of the current script into variable $myName.
//
$myName = $cocos->getScriptName();

// Run script with name 'someScript'. Use the same values for parameters $source
// and $value as the original script.
//
$cocos->runScript("someScript");

// Run script with name 'someScript'. Use custom values for parameters $source
// and $value.
//
$cocos->runScript("someScript", "someSource", "someValue");

// Run script with name 'someScript'. Use the same value for parameter $source,
// but a custom value for parameter $value
//
$cocos->runScript("someScript", $source, "someOtherValue");

// Run script with name 'someScript'. Use a custom value for parameter $source,
// but the same value for parameter $value
//
$cocos->runScript("someScript", "someOtherSource", $value);

// Run script with name 'someScript'. Use the name of the current script as value
// for parameter $source and a custom vlaue for parameter $value.
//
$cocos->runScript("someScript", $cocos->getScriptName(), 'someValue');