====== caseData() ======

''array **caseData**()''\\
''array **caseData**(array Filter, [boolean EmptyValues])''\\
''array **caseData**(string Filter, [boolean EmptyValues])''

The function ''caseData()'' returns all answer codes and text inputs from the current interview or a part of it.

  * //Filter//\\  Specify here rubrics and/or questions for which the data is to be determined. The syntax of this parameter is described in the instructions for ''[[:de:create:functions:getvariables]]''. 
  * //EmptyValues//\\ By default, no data will be included from questions that have not (yet) been asked in the interview, and no data will be included from open text entries where respondents have not entered anything. Specify ''true'' as the second parameter to include such (non-)data as well.\\ **Note:** Codes for missing answers (e.g. -9 for "asked but not answered") will be included in any case.


===== Return value =====

The function returns an associative array with the variable names as keys and the data as values.

<code php>
[
  'AB01_01' => 1,
  'AB01_02' => 2,
  'AB01_03' => 5,
  'AB01_04' => 2,
  'AB01_05' => -9
]
</code>

The function returns answer codes for closed questions. This corresponds to the output format ''%%'code'%%'' in the function ''[[value]]''.


===== Example: Preset data from previous interview =====

If a survey is conducted regularly with the same persons, some answers from the previous questionnaire should be automatically transferred to the new questionnaire.

One challenge is to identify the person so that a mapping between survey waves is possible. If the invitation to the survey is done by [[:en:survey:mailing|serial mail]], the person identifier SERIAL is available for this purpose, which can be determined by means of ''[[caseserial]]''.

The data from the previous interview can be stored in the [[:en:create:databank]]. As a key for the entry the person identifier is suitable. To maintain the link between variable labels and data, the data is encoded as a JSON string using ''json_encode()''.

So, for example, if the demographic data is to be carried over into the next questionnaire, the data must be stored in the content database in the first interview. In the following example, the relevant questions can be found in the "SD" and "PA" sections. The following PHP code must be placed on a page where all relevant questions have already been asked. So if the demographics are queried on pages 12 to 15, the PHP code must be placed on page 16 at the earliest.


<code php>
// A unique key
// Generate from the person ID
$serial = caseSerial();

// Save only if a personal ID is present
if ($serial) {
    // A prefix (e.g. 'data-') is helpful if you
    // want to use the database for other purposes
    $key = 'data-'.$serial;
  
    // Retrieve the actual data of the interview
    $data = caseData(['SD','PA']);
  
    // Code this data and write it to the
    // content database
    $package = json_encode($data);
    dbSet($key, $package);
}
</code>

In the following questionnaire you can now read out the data -- and if data is available for the person, write it directly into the variable using ''[[put]]''. For example, use ''caseData()'' to make sure that there are no answers yet. The following PHP code would be placed in the second questionnaire on the first page.

<code php>
$currentData = caseData(['SD','PA']);
$serial = caseSerial();

// Write data only if in the interview
// data is not yet available and if a
// person ID is available
if ($serial && empty($currentData)) {
    $key = 'data-'.$serial;
    $entry = dbGet($key);
    
    // Proceed only if data is available
    if ($entry) {
        $data = json_decode($entry[0]);
        
        // Proceed only if data is valid
        if ($data) {
            // Set all variables separately
            foreach ($data as $varName => $value) {
                // The third parameter (true) allows,
                // to set non-internal variables
                put($varName, $value, true);
            }
        }
    }
}
</code>

**Note:** This PHP code writes the existing data directly into the data set. Thus, the data is available even if the respondent does not fill out the corresponding pages (anymore) or corrects them. Alternatively, the function ''[[preset]]'' can be used instead of ''put()''. However, this must be called on each page, on which relevant questions stand. For this it would be useful to store a function under //PHP-Functions// in the questionnaire, and call it on all affected pages.

**Note:** The storage space in the database for content is limited to 64kb per entry. Keep this in mind if you have significantly more than 1000 variables or very long text responses or raw data in the dataset.


===== Example: Transmitting responses for further processing =====

Sometimes the data should be transmitted directly to another server via API for further processing. For this the functions ''[[sendJSON]]'' can be used. The function ''sendJSON()'' works directly together with caseData().

To send the entire interview data to the URL ''%%https://api.example.com/analyze.php%%'', you would insert an additional page before the "last page" in the questionnaire and the following PHP code on top of it.

<code php>
$data = caseData();
sendJSON('https://api.example.com/analyze.php', $data);
</code>