====== dbSet() ======

Data can be written into the **Database for Contents** during the survey with ''dbSet()''. If an entry already exists with the same key, it will be updated -- otherwise, a new entry will be created. 

An entry can also be deleted from the database with this function.


''void **dbSet**(string //key//, false|string|array //data//)''

  * //key//\\ Database key which will be created, updated, or deleted. The database key must contain between 2 und 63 characters. Umlauts may require more than one character. 
  * //data//\\
    * ''false'' -- Database entry is deleted, if it exists
    * <string> -- If text is specified, this is saved as the first (and only) element for the key
    * <array> -- If an array is submitted as //data//, all elements will be saved as the entry for the key.

**Note:** Each entry in the database has a timestamp with the date and time of the most recent change. By updating with ''dbSet()'', the timestamp will also be updated (even when the data stays the same!). If you only want to update the timestamp, use ''[[:en:create:functions:dbtouch|dbTouch]]''.

===== Example 1 =====

The following PHP code saves the age (variable "SD04_01") and gender (variable "SD02")) under the ID of the current participant, so that these variables can be called up again in a later survey wave ([[:en:create:databank|Database for Contents]]).

<code php>
$data = array(
  value('SD04_01'),
  value('SD02')
);
dbSet(caseSerial(), $data);
</code>


===== Example 2 =====

The following PHP code checks whether an entry with the submitted reference ([[:en:survey:url|URL to the Questionnaire]]) exists. The reference encodes a company. The participant is only allowed to continue with the survey if a max. of 10 people from the company have participated so far.

<code php>
$info = dbGet(reference());
// No access without a valid reference
if ($info == false) {
  text('invalidLink');
  buttonHide();
  pageStop();
}
// The name of the company is in the first field in the database
// and the number of participants is stored in the second field.
replace('%company%', $info[0]);  // Set up placeholder %company% 
if ($info[1] >= 10) {
  text('tooMuch');
  buttonHide();
  pageStop();
}
</code>

The counter is incremented on the last pages in the questionnaire onlt -- otherwise, it would count incomplete questionnaires as well. 


<code php>
// Counter increments by one
if (!isset($counted)) {
  $info = dbGet(reference());
  $info[1]++;
  dbSet(reference(), $info);
  // Together with isset() it ensures it is counted once only
  $counted = true;
  registerVariable('counted');
}
</code>


===== Example 3 =====

Perhaps the reference entry from example 2 should just be deleted when the first participant from the company has filled out the questionnaire. To do so, the second PHP code is modified as follows.

<code php>
dbSet(reference(), false);
</code>