Page History

...

The variable value is completely flexible.  It can be a simple integer or a complex data structure.  This is accomplished by serializing the value before saving it to the database.  YAML will be is used to serialize the data.  YAML is a human friendly data serialization standard for all programming languages (http://yaml.org/).  YAML modules are available for Perl, PHP, and many other languages:

• Perl: http://search.cpan.org/~ingy/YAML-0.68/lib/YAML.pm
• PHP: http://code.google.com/p/spyc

Because the data is serialized into a highly compatible format, the backend and frontend can utilize common variables.  It will be easy for the frontend to provide a means to configure variables by capturing the data entered into a web page, constructing a data structure, serializing it via a PHP YAML module, and then saving the data structure in the variable table.  The backend can then access the identical data structure using a Perl YAML module to deserialize the data.

Backend Interface

The variable table will be table is utilized by backend code via functions provided by the DataStructure.pm module:

...

Database Table Structure

The variable table will have has the following columns:

• id
  • variable.id contains a unique auto-incremented unsigned integer value
  • The id column is consistent with most other columns in the VCL database
• name
  • variable.name contains a string
  • variable.name values must be unique
  • variable.name provides a human-friendly means of identifying a variable
• value
  • variable.value contains an encoded string which is a YAML serialized representation of the data
  • The string stored in variable.value is programatically serialized before it is stored and programatically unserialized deserialized when it is retrieved
  • Various programming languages have the ability to transform data to/from YAML
  • Serialization allows multiple languages to share and modify the same data structures
• setby
  • variable.setby contains a string which indicates who/where and who last set the data
  • variable.setby is mainly used for debugging purposes
  • variable.setby can be NULL but should be set whenever a row is altered
• timestamp
  • variable.timestamp contains the date and time when the variable was last set
  • variable.timestamp is automatically updated whenever a row is inserted or altered because the "ON UPDATE CURRENT_TIMESTAMP" column attribute is set

SQL table definition

CREATE TABLE IF NOT EXISTS `variable` (
  `id` smallint(5) unsigned NOT NULL auto_increment,
  `name` varchar(128) NOT NULL default '',
  `value` longtext NOT NULL,
  `setby` varchar(40128) default NULL,
  `timestamp` timestampdatetime NOT NULL default CURRENT_TIMESTAMP on update CURRENT_TIMESTAMP,
  PRIMARY KEY  (`id`),
  UNIQUE KEY `name` (`name`)
) ENGINE=InnoDB InnoDB DEFAULT CHARSET=utf8latin1 AUTO_INCREMENT=1 ;

Examples

...

my %kms_configuration = (
 '3'"ECU" => '"192.168.22.33:1688'",
 '1'"NCSU" => '"kms-server.ncsu.edu'",
);
my $serialized_data = YAML::Dump(\%kms_configuration);
$self->data->set_variable('"kms-configuration'", $serialized\%kms_dataconfiguration);

The keys represent affiliation IDs and the correspond to the affiliation.name column in the database.  The values represent the addresses (phony) of Windows Vista/2008 KMS activation servers.

This hash is serialized by DataStructure.pm::set_variable() using the YAML module's Dump function which transforms the hash into:

---
3ECU: 192.168.22.33:1688
1NCSU: kms-server.ncsu.edu

The following row is saved in the variable table by the DataStructure.pm::set_variable() subroutine:

To retrieve the data:

my $kms_configuration = $self->data->get_variable("kms-configuration");
my $kms_address = $kms_configuration->{$affiliation_id};

Example 2:

A more elaborate data structure is created in Perl containing an array of hashes. One of the hash values (email) can be multivalued because the value is an anonymous array:

my @contacts = (
 {
  '"firstname'" => '"Joe'",
  '"lastname'" => '"Doe'",
  '"email'" => ['"joe@somewhere.org'", '"jdoe22@unity.ncsu.edu'"],
  '"employee_id'" => 3342
 },
 {
  '"firstname'" => '"Jane'",
  '"lastname'" => '"Doe'",
  '"email'" => ['"jane@somewhere.org'"],
  '"employee_id'" => 7865
 }
);  
my $serialized_data = YAML::Dump(\@contacts); 
$self->data->set_variable('"contacts'", $serialized_data\@contacts);

DataStructure.pm::set_variable() uses YAML::Dump transforms to transform this data structure into:

...

To retrieve the data:

my @returned_contacts = @{$self->data->get_variable('contacts')};
for my $contact (@returned_contacts) {
   print "Name: $contact->{firstname} $contact->{lastname}\n";
   for my $email_address (@{$contact->{email}}) {
      print "Email: $email_address\n";
   }
   print "---\n";
}