JavaScript in SCRIPTOR:

In den ASCII-Dateien der Scripte und in vielen Tabellenfeldern von SCRIPTOR können Parameter und JavaScript-Ausdrücke ausgewertet werden. Solche Ausdrücke werden mit “<%= ... %>” markiert. Das Ergebnis der Auswertung ersetzt dann den Originalausdruck.
Zur Auswertung wird die Microsoft Variante “JScript” verwendet. Es muß der “Microsoft Scripting Host” installiert sein. Hier findet sich die Originaldokumentation.

Beispiele:

SCRIPTOR-Ausdruck	Endergebnis	Erklärung
Die <%= 1+2*3 %> Zwerge ...	Die 7 Zwerge ...	Jeder JavaScript-Ausdruck ist erlaubt.
COPY *.* <%=TMPDIR%>	COPY *.* E:\TMP	Die SCRIPTOR-Variable “TMPDIR” hat hier den Wert “E:\TMP”.

SCRIPTOR-Parameter und die von SCRIPTOR bereitgestellten Funktionen brauchen in der JavaScript-Source nicht besonders markiert zu werden. De facto kann unter SCRIPTOR ein erweiterter JavaScript-Funktionsumfang genutzt werden.

Varianten der <%..%> Notation:

Syntax	Semantik	anwendbar in
<%= expr %>	Der JavaScript/SCRIPTOR-Ausdruck expr wird ausgewertet, das Ergebnis ersetzt	Script-Text, Tabellen-Zellen
<% JavaScript-Programm-code %>	Eingebetteter JavaScript-Programmcode, der bei der Erzeugung des Scriptes ausgeführt wird. Verarbeitung nach dem Muster von ASP/JSP-serverseitigem HTML: Das Script-Template wird in ein JavaScript-Programm umgewandelt. Jede normale Zeile des Script-Templates wird in eine  “writeln(zeile) ;” Anweisung umgesetzt, alles zwischen <% und %> wird unverändert ins resultierende JavaScript-Programm übernommen. Das resultierende JavaScript-Programm wird ausgeführt. Als Ergebnis druckt es den Text des ursprünglichen Scriptes aus, allerdings verändert durch den zusätzlichen Programmcode.	Script-Text
<%! param, param, ... %>	Definiert die nur im Script verwendeten lokalen Parameter als SCRIPTOR-Parameter. Anschliessend können sie im Script benutzt werden, vor der Abarbeitung werden ihre Werte vom User abgefragt. Siehe Funktion DEFINE().	Script-Text
<%@ include file = expr %>	In den Script-Text wird eine andere Textdatei importiert. Der Dateiname ist ein JavaScript-Stringausdruck. Unter Windows wird normalerweise der Backslashs “\” als Pfad-Separator verwendet. Dieser muss in JScript-Strings als “\\” angegeben werden, alternativ ist auch der normale Slash “/” erlaubt. Soll JavaScript-Sourcecode importiert werden, muss dieser in der Includedatei mit <%..%> umgeben sein.	Script-Text
<%-- text --%>	Kommentar	Script-Text

Wie wird ein Ziel-Script aus dem Template durch JavaScript erzeugt?

Die häufigste Anwendung für <%..%> ist der Aufbau von “if..then..else”-Strukturen, die - abhängig von bestimmten SCRIPTOR-Parametern - nur bestimmte Teile des Script-Templates kopieren.
Beispiel für ein fiktives Script, das einen Verzeichnis-Inhalt anzeigt, wobei durch die aktuelle Configuration ein UNIX-Server oder der lokale PC ausgewählt wird:

<% if (OS_TYPE == "UNIX") { %> rsh -l <%=USER%> <%=SERVER%> ls -al <% } else { %> dir <% }%>

Daraus wird folgendes JavaScript-Programm erzeugt (das wiederum das Ziel-Script erzeugen soll):

function main()  {   if (scriptor.ScriptGetParam("OS_TYPE") == "UNIX") {    scriptor.Writeln("") ;    scriptor.Write("rsh -l ") ;    scriptor.Write("guest")    scriptor.Write(" ") ;    scriptor.Write("bigmachine")    scriptor.Writeln(" ls -al") ;   } else {    scriptor.Writeln("") ;    scriptor.Writeln("dir") ;   }    scriptor.Writeln("") ;  }

Besonderheiten dabei:

• Der Parameter ‘OS_TYPE’ wird durch den Ausdruck “scriptor.ScriptGetParam ("OS_TYPE")” abgefragt (sein Wert ist hier “UNIX”). Ebenso ist ‘USER’ = ‘guest’ und ‘SERVER’ = ‘bigmachine’.
• Die Ausgabe ins Ziel-Script erfolgt mit der Funktion “scriptor.write()”. Alle SCRIPTOR-internen Funktionen bekommen bei der Programmerzeugung automatisch das Prefix “scriptor.”.

Durch Start dieses JavaScript-Programms innerhalb von SCRIPTOR wird schließlich das lauffähige Ziel-Script erzeugt. Man sieht ihm seine Herkunft nicht mehr an:

rsh -l guest bigmachine ls -al

SCRIPTORs erweiterte JavaScript-Funktionen (“build-in-functions”):

Zusätzlich zu den JavaScript-Funktionen sind unter SCRIPTOR noch weitere Funktionen verfügbar, die auf die Besonderheiten der Textverarbeitung bei der Scripterzeugung abgestimmt sind. Sie wurden all ad hoc bei Bedarf eingebaut. Oft sind es einfach nützliche, publizierte Delphi-Funktionen, einen großen Entwurfsplan gibt es nicht.

Funktion	Bedeutung
WRITE(text)	Gibt “text” in das Zielscript aus. Keine Rückgabe.
WRITELN(text)	Gibt “text” in das Zielscript aus und macht danach einen Zeilenwechsel. Keine Rückgabe.
CONFIGGETPARAM(configname, paramname)	Fragt den Wert eines Parameters einer beliebigen, nicht-aktiven Configuration aus der Datenbank ab.
ERROR(msg)	Veranlasst, dass die Scripterzeugung mit der angegebenen Fehlermeldung abgebrochen wird.
EXTRACTCHAR(text, i)	Gibt das i-te Zeichen von text zurück. Beginn mit 1. Beispiel:  EXTRACTCHAR('hello!', 3) -> 'e'.
EXTRACTCHAR_C(text, i)	text wird als C-String interpretiert, in dem Einzelzeichen mit der \-Notation kodiert werden. Die \ werden ausgewertet, dann wie EXTRACTCHAR. Beispiel:  EXTRACTCHAR_C('hello\nworld', 6) -> '\n', nicht '\'.
CONVERT_C(text)	ersetzt Einzelzeichen < 32 durch \x Sequenzen. Entfernt die abschliessende \0. Ersetzt “\” durch “\\”, ebenso für “ und ‘.
EXTRACTWORD(text, i, sepchars)	gibt das i-te Wort aus text zurück. Wortgrenzen sind die Zeichen aus dem String “sepchars” Für das erste Wort muss i=0 sein. Beispiel: EXTRACTWORD('myfile.ext’, 0, ‘.’) -> ‘myfile’.
EXTRACTFILEDRIVE(fname)	Gibt den Laufwerksbuchstaben inkl.”:” zurück. fname muß ein voller Pfad sein, sonst ‘’.
EXTRACTFILEPATH(fname)	Gibt den Pfad inkl. “\” zurück. fname muss ein voller Pfad sein, sonst ‘’.
EXTRACTFILENAME(fname)	Gibt den Dateinamen und die Extension zurück.
EXTRACTSHORTPATHNAME(fname)	Wandelt den fname in die alte 8.3-Darstellung. Wenn fname nicht existiert, wird ‘’ geliefert.
EXPANDPATH(fname)	Erweitert einen unvollständigen Pfad.
FILEEXISTS(fname)	True, wenn die Datei fname existiert.
READFILECONTENT(fname, line_format,line_separator)	Gibt die Zeilen in einer Textdatei verkettet als ein String zurück. Die Zeilen werden durch den String “lineseparator” verbunden, führende und nachfolgende Spaces werden gelöscht. Nur nicht-leere Zeilen werden zurückgegeben. Mit dieser Funktion können z.B. Kommandozeilenparameter für beliebige Programme aus Dateien geladen werden. Der Parameter “line_format” wird derzeit nicht benutzt.
WRITEFILECONTENT(fname, line_format,line_separator,string)	Schreibt den Wert von “string” als mehrere Zeilen in eine Textdatei. Als Zeilentrenner im String wird “lineseparator” verwendet. Mit dieser Funktion können z.B. Kommandozeilenparameter für beliebige Programme in Dateien geschrieben werden. Der Parameter “line_format” wird derzeit nicht benutzt.
FORMAT(fmt, arg)	Zahlenformatierung, wie printf(), Dokumentation siehe Delphi. Nur ein Argument erlaubt, fmt darf nach “%” enthalten: D, U, X: Argument wird als integer ausgewertet. E, F, G, N, M: Argument wird als float ausgewertet. S: Argument wird als String ausgewertet.
UPPERCASE(text)	“text” wird in GROSSSCHRIFT zurückgegeben
REPLACE(text, search, replace)	Ersetzt in text jede Zeichenfolge “search” durch “replace”. Mit Rekursion, aber Begrenzung auf 100 Ersetzungen.
DEFINE(parameter)	Definiere einen nur im Script verwendeten lokalen Parameter als SCRIPTOR-Parameter. Anschliessend kann er im Script benutzt werden, vor der Abarbeitung wird sein Wert vom User abgefragt. Keine Rückgabe. (Veraltet, stattdessen “<%!”-Tag benutzen!)
DEFINED(parameter)	True, wenn parameter ein bekannter SCRIPTOR-Parameter ist.
GETIPADDRESS(host)	IP name resolution: Gibt die numerische IP-Adresse von “host” zurück. Oder “”, falls Fehlschlag.
REGISTRYKEY(key)	Liest einen Registry-Key aus. key muss ein absoluter Pfad sein. Er muss mit einem dieser Rootkeys beginnen: 'HKEY_CURRENT_CONFIG', 'HCC', 'HKEY_CURRENT_USER', 'HCU', 'HKEY_LOCAL_MACHINE',  'HLM', 'HKEY_USERS'.
OS_PATH(path)	Schreibt einen Dateipfad mit “/” oder mit “\”. Wenn der Parameter OS_TYPE = “UNIX” ist, werden alle “\” in path in “/” umgewandelt. Sonst werden alle “/” in “\” gewandelt.
OS_COMMENT(text)	Schreibt Kommentare für UNIX-sh oder DOS mit ‘rem’ oder ‘#’. Wenn OS_TYPE = ‘UNIX’ ist, wird ‘rem’ in ‘#’ gewandelt, sonst umgekehrt.

Ladbare JavaScript-Funktionen (“add-on-library-functions”)

Zusätzlich zu den eingebauten (build-in) Funktionen können auch zusätzliche Funktionen in Javascript geschrieben werden. Nur durch dieses Feature ist es möglich, in allen “<%=..%>” -Ausdrücken eigene Funktionen zu benutzen. Die zusätzlichen Funktionen werden in einer Defintionsdatei als normaler JavaScript-Code angegeben. Diese Definitionsdatei heisst defaultmässig “SCRIPTORLIB.JS” und steht im selben Verzeichnis wie “Scriptor.exe”. Mit der Kommandozeilenoption “/JSCRIPTLIB” kann aber auch eine andere JScript-Sourcedatei geladen werden.

Es ist kein Fehler, wenn die Defaultdatei “ScriptorLib.js” nicht existiert. Andere Fehler beim Laden bewirken beim Start von SCRIPTOR eine Fehlermeldung und den Programmabbruch.

In den JavaScript-Biliotheks-Funktionen können wie gehabt build-in-Funktionen und Scriptor -Parameter benutzt werden.

Zuweisungen an SCRIPTOR-Parameter

Innerhalb von “<% .. %>” können auch Zuweisungen an die von SCRIPTOR verwalteten Parameter gemacht werden. Die so geänderten Parameter werden automatisch in der Datenbank dauerhaft gespeichert. Es gelten folgende Einschränkungen:

• Parameter können nur durch eine einfache Zuweisung der Form
  “parameter = Ausdruck”
  verändert werden. Compound-assign (“+=”, “-=”. “*=”, ...) und increment/decrement (“++”, “--”) führen zu Fehlermeldungen.
• Zuweisungen an Parameter sollten nur innerhalb von Script-Sourcen gemacht werden, nie in <%=..%>-Ausdrücken, die in Tabellenspalten von SCRIPTOR-Datenbank eingetragen wurden. Grund: diese werden unvorhersagbar oft in beliebiger Reihenfolge ausgewertet. Die Veränderungen der Parameter würden also ziemlich unkontrollierbar erfolgen.
• Der Datentyp der Parameter ist immer String. Für numerische Rechnungen muss die Funktion “parseFloat()” verwendet werden. Beispiel:
  “BUILD_NUMMER = parseFloat(BUILD_NUMMER) + 1”.
• Es können nur Zuweisungen an solche Parameter gemacht werden, die nicht durch das “ReadOnly”-Flag geschützt sind.
• Die Änderungen werden nur in der Datenbank gespeichert, wenn der gesamte Scriptlauf fehlerfrei beendet wurde.