Kapitel 14. Action-Befehle und -Blöcke

ersetzt die erste Missing-Stelle eines Arrays ARRAY durch VALUE. Wenn der Array vollständig belegt ist, macht die Anweisung nichts.

	    add(ARRAY, VALUE);
	  

Array container[3];
actionblock set_container = {
    set( container[1] = 1 );
    set( container[3] = 3 );
};

actionblock add_container = {
  add(container, 7);
};

continueActionblock = { print(container); };
// ergibt in actionlog.txt:
// PrintAction: variable: container; value: 1 7 3 
          

hängt TEXT an TextElement TEXTVAR an.

	    appendText(TEXTVAR, "TEXT");
	  

appendText(textelem, "... wird angehängt");
          

setzt den Fortschrittsbalken um #QUESTIONS Stellen weiter, sofern BEDINGUNG zutrifft. Alternativ (und gebräuchlicher) kann der Fortschrittsbalken auch innerhalb von Filtern für Fragen, Screens und Blöcken definiert werden, siehe „Filter an Fragen, Blöcken, Screens“.

	    changePBar((BEDINGUNG) #QUESTIONS);
	  

changePBar((var eq 1) 2);
          

abhängig vom arrayInitMode wird jedem Element von ARRAY der Missing-Wert _missing oder der jeweilige Stellenindex zugewiesen.

	    clear(ARRAY);
	  

[bei arrayInitMode=missing]
ARRAY-Inhalt vor  clear(): { 1, 2, 3, 4, 5 }
ARRAY-Inhalt nach clear(): {  ,  ,  ,  ,   }
          

steht für decrement und verringert den Wert von VAR um 1.

	    dec(VAR);
	  

Mit exit wird das Interview am Ende des aktuellen Actionblocks mit FINISHCODE beendet und die Endseite angezeigt.

	    exit(FINISHCODE);
	  

Die Funktionen suchen in einem Array (ARR) den niedrigsten bzw. den höchsten Wert und speichern den Index der Fundstelle in einer Variablen (VAR).

	    findMinValIndex(ARR, VAR)
	  

compute min = 0;
compute max = 0;
set( arr = [1 3 5 -1 6:9 0 0] ); // {1, 3, 5, -1, 6, 7, 8, 9, 0, 0}
findMinValIndex(arr, min); // min erhält Wert 4
findMaxValIndex(arr, max); // max erhält Wert 8	    
	  

Der ActionBefehl

	    getCountValue(VAR, "KEY")
	  

ruft Zählerstände ab, die in der Datei countvars.lst im Studienverzeichnis gepflegt werden. Dabei wird zuerst der Zähler KEY inkrementiert und anschließend an die Variable VAR übergeben.

compute z1 = 0;

textq welcome;
text="
  Herzlich Willkommen!<br />
  Sie sind der @insert(z1). Teilnehmer an dieser Befragung!
";
initactionblock={
  getCountValue(z1, "zaehler1");
};
          

Mit dem Anzeigen der Frage wird der Zählerstand erhöht. Die Nachrichten werden der Reihe nach wie folgt angezeigt:

Sie sind der 1. Teilnehmer an dieser Befragung!
Sie sind der 2. Teilnehmer an dieser Befragung!
Sie sind der 3. Teilnehmer an dieser Befragung!
	  

Die Datei countvars.lst besteht aus einfachen Key-Value Paaren:

zaehler1 0
zaehler2 0
zaehler3 0
	  

steht für increment und erhöht den Wert von VAR um 1.

	    inc(VAR);
	  

erhöht den Wert einer QUOTAVAR explizit um 1.

	    incQuota(QUOTAVAR);
	  

hängt in der Labelliste von Frage FRAGENAME nach dem Label mit Code CODE ein neues Label LABEL ein. Je nach Fragetyp muss hierbei darauf geachtet werden, dass die ursprünglich angelegte Frage auch genug Platz hat, alle möglichen Antworten zu speichern. Wäre die Frage im gegebenen Beispiel eine MultiQ, müsste mit oversizeArray(1); dafür gesorgt werden, dass die ursprünglich mit 2 Labels angelegte Frage ausreichend Platz dafür hat auch alle 3 Antwortcodes zu speichern.

	    insertLabels(FRAGENAME, CODE, [ LABEL ]);
	  

multiq bekannt;
labels=
1 "Lafite Rothschild"
3 "Haut-Brion"
;
initActionBlock={
  insertLabels(bekannt, 1, [ 2 "Mouton Rothschild" ]);
};
oversizeArray(1);
          

verschiebt jedes Element von ARRAY, das ungleich dem Missing-Wert _missing ist, nach links (zum kleinsten Index), indem es so viele Plätze wie möglich mit Missing-Werten tauscht, siehe auch ralign.

	    lalign(ARRAY);
	  

ARRAY-Inhalt vor  lalign(): {  , 2, 3,  , 5, 6,  ,  ,   }
ARRAY-Inhalt nach lalign(): { 2, 3, 5, 6,  ,  ,  ,  ,   }
          

kopiert den Inhalt von Variable VAR2 in VAR1. Der Unterschied zu set ist, dass nicht nur ein Wert/Zahl/Ergebnis zugewiesen wird, sondern der gesamte Inhalt einer Variable in eine andere. So lassen sich z.B. auch ganze Array-Inhalte kopieren.

	    load(VAR1 = VAR2);
	  

dient zur Belegung von Variablen und Fragen eines Interviews. Der Befehl stellt eine HTTP Anfrage an die Webadresse URL und erwartet eine Antwort mit Daten im JSON Format. Der zweite Parameter data="INFO" ist optional und kann zusätzliche Informationen bei der Anfrage übermitteln. Die angegebenen Werte werden in die benannten Variablen übernommen, sofern sie existieren. Der Befehl funktioniert analog zu readJsonDataFile.

	    performHttpRequest( url="URL"; data="INFO"; ); 
	  

performHttpRequest(
   url="http://www.gessgroup.de/AntwortServlet";
   data="optionale Zusatzinformation";
);
///////////////////////////////
// Server-Antwort:
///////////////////////////////
// {
//    "variables": {
//       "singleq": 4,
//       "multiq": [2, 3, 5, 7, 9],
//       "openq": "dies ist ein text",
//       "numq": [14, 19, 5, 27],
//       "sgq.1": [1,2,3,2],
//       "mgq.1.1": [1,2,3],
//       "mgq.1.2": [2,1]
//    }
// }
          

aus den angegebenen Zahlen wird mit pow(BASE, EXPONENT) eine Potenz gebildet und schreibt sie in die Variable VAR.

             set(var = pow(10, 3)); // 10^3
          

schreibt den Inhalt von Variable VAR in eine Zeile der Datei actionlog.lst in das text-Verzeichnis der Studie. Ist die Datei nicht vorhanden, wird sie neu angelegt.

	    print(VAR);
	  

schreibt den angegebenen TEXT in eine Zeile der Datei actionlog.lst in das text-Verzeichnis der Studie. Ist die Datei nicht vorhanden, wird sie neu angelegt.

	    printText("TEXT");
	  

verschiebt jedes Element von ARRAY, das ungleich dem Missing-Wert _missing ist, nach rechts (zum größten Index), indem es so viele Plätze wie möglich mit Missing-Werten tauscht, siehe auch lalign.

	    ralign(ARRAY);
	  

ARRAY-Inhalt vor  ralign(): {  , 2, 3,  , 5, 6,  ,  ,   }
ARRAY-Inhalt nach ralign(): {  ,  ,  ,  ,  , 2, 3, 5, 6 }
          

dient zur Belegung von Variablen und Fragen eines Interviews. Der Befehl sucht in einer strukturierten Datendatei FILE nach einer Zeile mit Schlüsselwert VAR, und übernimmt die darin angegebenen Werte in die entsprechenden Variablen, sofern sie existieren. FILE muss sich im text-Ordner der jeweiligen Studie befinden.

	    readDataFile(FILE, VAR);
	  

// z.B. für ID 67
readDataFile("data1.txt", _respid);
///////////////////////////////
// data1.txt
///////////////////////////////
// ...
// 67 ( (p_intnr "einunddreißig") (s1 "6") )
// ...
          

Bitte beachten: Wenn VAR eine numerische Information ist (angelegt z.B. Compute oder NumQ), sollte DecimalFormat (s. „ Textersatz mit @insert “ verwendet werden. Sonst kann es passieren, dass große Zahlen in Exponentialschreibweise gewandelt oder eine Nachkommastelle zugefügt werden und dadurch die Suche keine Treffer liefert.

dient zur Belegung von Variablen und Fragen eines Interviews. Der Befehl liest einen JSON formatierten Datensatz FILE ein und übernimmt angegebene Werte in die benannten Variablen, sofern sie existieren. FILE muss sich im Preset-Ordner der Q. Installation befinden (siehe auch „Konfigurationsdatei qonline.cfg“).

	    readJsonDataFile(FILE);
          

readJsonDataFile("data1.json");
///////////////////////////////
// data1.json
///////////////////////////////
// {
//    "variables": {
//       "singleq": 4,
//       "multiq": [2, 3, 5, 7, 9],
//       "openq": "dies ist ein text",
//       "numq": [14, 19, 5, 27],
//       "sgq.1": [1,2,3,2],
//       "mgq.1.1": [1,2,3],
//       "mgq.1.2": [2,1]
//    }
// }
          

liest eine Sprach-Ressourcen-Datei FILE aus dem text-Verzeichnis der Studie ein und ändert zu diesem Zeitpunkt alle in der Quelle enthaltenen Textinformationen.

	    readTextRessource(FILE);
	  

if(lang eq 1) {
  readTextRessource("englisch.lrs");
};
          

ersetzt einen oder mehrere Werte VAL in ARRAY durch _missing.

	    remove(ARRAY, VAL, VAL, ...);
	  

ARRAY-Inhalt vor  remove():            { 3, 2, 3, 5, 5, 6, 1, 6, 6 }
ARRAY-Inhalt nach remove(ARRAY, 2, 6): { 3,  , 3, 5, 5,  , 1,  ,   }
          

entfernt Werte, die mehrfach in ARRAY enthalten sind. Nur ihr jeweils erstes Vorkommnis bleibt erhalten. Alle weiteren werden durch den Missingwert _missing ersetzt.

	    removeDuplicates(ARRAY);
	  

ARRAY-Inhalt vor  removeDuplicates(): { 3, 2, 3, 5, 5, 6, 1, 6, 6 }
ARRAY-Inhalt nach removeDuplicates(): { 3, 2,  , 5,  , 6, 1,  ,   }
          

versetzt die Werte eines ARRAY um die angegebene Stellenanzahl nach links.

            rotateLeft(ARRAY, ANZ-STELLEN);
          

ARRAY-Inhalt vor rotateLeft(): {1 2 3 4 5}
ARRAY-Inhalt nach rotateLeft(ARR, 2) : {3 4 5 1 2}
          

rundet den Wert der angegebenen Variable VAR auf eine ganze Zahl.

            set(var = round(var));
          

bettet Javascript Syntax in Actionblöcke ein. Mit @insert() können Werte von Q. Variablen ins Javascript eingebunden werden. @save(VAR = VAL); definiert welche Werte am Ende der Ausführungslogik in welche Q. Variablen zurückgespielt werden. Dieser Befehl benötigt Java 8 und ist unter Android noch nicht verfügbar.

            script("JAVASCRIPT");
          

compute nhTestResult = 5;
compute x = 0;
compute y = 0;
compute z = 0;
Array nhTestArray[3];
OpenQ te;

vararray xyz = (x y z te nhTestArray);

// ...
Actionblock ab = {
  script("
    var x = 1;
    var y = 2;
    var z = @insert(nhTestResult);
    var arr = new Array();
    arr.push(x);
    arr.push(y);
    arr.push(z);
  
    @save(xyz[1]) = x;
    @save(xyz[2]) = y;
    @save(xyz[3]) = z;
    @save(nhTestResult) = x+y+z;
    @save(xyz[5]) = arr;
    @save(xyz[4]) = 'nachher';
  ");
};
          

weist Variable VAR den Wert VALUE zu. VALUE kann auch das Ergebnis einer Berechnung sein.

	    set(VAR = VALUE);
	  

set(var = 0);
set(var = a * b + 1);
          

Im Gebrauch mit Arrays kann set einen Array in einem Schritt belegen. Ab Arrayindex 1 werden dabei fortlaufend alle Stellen belegt, für die Werte angegeben wurden. Überschüssige Werte werden nicht berücksichtigt.

array arr[10];
set( arr = [1 3 5 -1 6:9 0 0] ); // {1, 3, 5, -1, 6, 7, 8, 9, 0, 0}	    
          

(Die Schreibweise 6:9 kürzt die Angabe 6 7 8 9 ab.)

Setzt den aktuellen Screen neu und greift sofort bei nächster Teilnehmerinteraktion. Verwirft Eingaben in Screens, die ein Timeout überdauern oder wenn setCurrentScreen in einem InitActionBlock verwendet wird.

          setCurrentScreen(SCREEN);
          

 // Kann syntaktisch mit/ohne Anführungszeichen geschrieben werden.

 // Ohne Anführungszeichen wird die Screenexistenz geprüft 
TimeoutActionBlock = { setCurrentScreen(m4); };
 // Mit Anführungszeichen kann z.B. @insert() verwendet werden
 //     setCurrentScreen("@insert(te_m4)");
 //     setCurrentScreen("m4");
          

legt das Dezimaltrennzeichen fest (Voreinstellung Komma: ",")

	          setDecimalSeparator(".");
	        

legt das Tausendertrennzeichen fest (Voreinstellung Punkt: ".")

	   setGroupingSeparator(",");
	  

Mit dem Befehl setNextScreen wird in der Umfrage ein einmalig definierter Sprung initiiert, ohne dass der vorher definierte Pfad dabei verändert wird. setNextScreen kann an beliebiger Stelle für einen beliebigen Screen verwendet werden. Bei der Benutzung ist zu beachten, dass der Fortschrittsbalken nicht kompatibel mit dem Überspringen der Fragen oder Screens ist und daher weder parallel zum Interviewverlauf fortschreitet, noch parallel abschließt.

	    setNextScreen(SOURCE,TARGETSCREEN);
	  

setNextScreen(a,c);
          

ordnet die Inhalte von ARRAY zufällig neu an.

	    shuffle(ARRAY);
	  

ARRAY-Inhalt vor  shuffle(): { 1, 2, 3, 4, 5 }
ARRAY-Inhalt nach shuffle(): { 4, 3, 5, 1, 2 }
          

schneidet die ersten ANZAHL Zeichen des Inhalts von VAR ab und speichert das Resultat in TEXTELEMENT.

	    strCutLeft(TEXTELEMENT, VAR, ANZAHL);
	  

TextElement cutlery;
OpenQ q1;
text="Bitte etwas eingeben";
continueActionBlock={ strCutLeft(cutlery, q1, 2); };
          

schneidet die letzten ANZAHL Zeichen des Inhalts von VAR ab und speichert das Resultat in TEXTELEMENT.

	    strCutRight(TEXTELEMENT, VAR, ANZAHL);
	  

sortiert die Inhalte von ARR1 aufsteigend (ascending) oder absteigend (descending) an. Synchron zu dem Schema, wie die Elemente in ARR1 ihre Positionen verändern, wird auch ARR2 umsortiert.

	    syncsort(ARR1, ARR2, ascending|descending);
	  

syncsort(array1, array2, ascending);

// ARRAY-Inhalte vor  syncsort(): array1{ 3, 7, 1, 9, 4 } array2{ 1, 2, 3, 4, 5 }
// ARRAY-Inhalte nach syncsort(): array1{ 1, 3, 4, 7, 9 } array2{ 3, 1, 5, 2, 4 }
          

schreibt einen Rohdatensatz FILE in den Studienordner der Studie SURVEYNAME, der die angegebenen Variablen VAR im JSON Format enthält.

	    writeJsonToSurvey(SURVEYNAME, FILE, (VAR, VAR, ...));
	  

Das Beispiel:

writeJsonToSurvey(beispielstudie, "case123.json", (sq1 sgq.1));
	  

ergibt

///////////////////////////////
// case123.json
///////////////////////////////
{
  "rvars": [
    {
      "name": "sq1",
      "value": "3.0"
    },
    {
      "name": "sgq.1",
      "value": "4.0 4.0 5.0 5.0"
    }
  ]
}