urnDraw()

int|false urnDraw(string UrnenKennung, string FrageKennung, [string Ablegen])

Mit urnDraw() entnehmen Sie einen Zettel (eine Zahl oder eine Kombination mehrerer Werte) aus einer Urne. Wenn alle Zettel aus der Urne gezogen und abgelegt wurden, dann wird die Urne von Neuem gefüllt.

Details zur Verwendung von Urnen finden Sie im Kapitel Randomisierung mit Urnen.

• UrnenKennung
  Die Kennung der Urne gibt an, aus welcher Urne der Zettel gezogen werden soll.
• FrageKennung
  Geben Sie hier die Kennung einer Frage vom Typ interne Variablen an, in welcher die gezogene Kombination gespeichert werden soll.
• Ablegen
  Hier können Sie festlegen, ob die Kombination sofort abgelegt werden soll oder erst später. Falls Sie nichts angeben, wird die Kombination sofort abgelegt.
  • 'now' Die Kombination wird sofort abgelegt
  • 'end' Die Kombination wird abgelegt, wenn/falls der Teilnehmer die letzte Seite des Fragebogens erreicht
  • 'man' Die Kombination wird manuell durch Aufruf von urnPutAway() abgelegt
  • 'no' Die Kombination wird gar nicht abgelegt – es wird eine Ziehung mit Zurücklegen durchgeführt

Die Funktion liefert im Normalfall eine Zahl (int) zurück, zum wievielten Male die Urne gerade geleert wird. Für eine neu angelegte (oder zurückgesetzte) Urne wird die 1 zurückgegeben. Wurde die Urne einmal vollständig geleert, wird bei der nächsten Ziehung mittels urnDraw() die 2 zurückgegeben.

Für den Fall, dass bei der Ziehung ein Fehler auftritt (z.B. ungültige UrnenKennung oder FrageKennung) wird der Bool'sche Wert false zurückgegeben.

Hinweis: Falls innerhalb eines Interviews mehrere Kombinationen aus derselben Urne gezogen werden sollen, müssen unterschiedliche Frage-Kennungen angegeben werden.

Hinweis: In den internen Variablen dürfen vor der Ziehung noch keine Werte gespeichert worden sein, z.B. via put().

Hinweis: Damit sich Interviewpartner nicht nach Belieben eine Kombination auswählen können, wird pro Interview nur einmal gezogen und – falls die Person die Seite mit der Ziehung nochmals aufruft – diese Ziehung auch beibehalten. Das heißt, dass Sie beim Testen durch Aktualisieren der Browser-Ansicht immer den gleichen Zettel bekommen werden. Um einen neuen Zettel zu bekommen, müssen Sie den Fragebogen neu starten.

Im folgenden Beispiel wird ein Zettel aus der Urne „Personen“ gezogen (diese Urne enthält Kombinationen aus jeweils 2 Zahlen) und die gezogene Kombination in den Variablen von IV01 gespeichert. Anschließend wird die gezogene Kombination einfach nur angezeigt.

urnDraw('Personen', 'IV01');
html('<p>Auf dem Zettel steht die Kombination '.value('IV01_01').' - '.value('IV01_02').'</p>');

Hinweis: Im einfachsten Fall besteht eine Kombination nur aus einem einzigen Wert.

Hinweis: Lesen Sie für umfangreiche Beispiel das Kapitel Randomisierung.

Mithilfe des Rückgabewerts können Sie die Erhebung beenden, wenn die Urne ausreichend oft geleert wurde. Der folgende PHP-Code zeigt nach der dritten Leerung (also wenn jeder Zettel 3-mal gezogen wurde) den Textbaustein „over“ an und blendet zugleich den Weiter-Knopf aus.

$round = urnDraw('Personen', 'IV01');
if ($round > 3) {
  text('over'); // Den entsprechenden Textbaustein muss man unter "Textbausteine und Beschriftung" anlegen
  buttonHide();  // Blendet alle Knöpfe aus
  pageStop();  // Führt keine weiteren Inhalte auf der Seite mehr aus (falls unter dem PHP-Code noch Fragen, Texte o.ä. stehen)
}