1. whether the specified data element is supported; and
2. whether it has the necessary read or write privileges

and then set the error code appropriately. This is a pretty minimal set of tests – I’m probably going to have to add some others later – but it’s a starting point. Here’s the code.

function LMSGetValue(varname) {

  // not initialized or already finished
  if ((! flagInitialized) || (flagFinished)) {
    errorCode = '301';
    return '';
  }

  // not implemented
  if ( ! isSupported(varname) ) {
    errorCode = '401';
    return '';
  }

  // not readable
  if ( ! dataElementRead ) {
    errorCode = '404';
    return '';
  }

  // otherwise, return the requested data
  errorCode = '0';
  return cache[varname];

}

// --------------------------------------------------------

function LMSSetValue(varname,varvalue) {

  // not initialized or already finished
  if ((! flagInitialized) || (flagFinished)) {
    errorCode = '301';
    return "false";
  }

  // not implemented
  if ( ! isSupported(varname) ) {
    errorCode = '401';
    return 'false';
  }

  // not writeable
  if ( ! dataElementWrite ) {
    errorCode = '403';
    return 'false';
  }

  // otherwise, set the requested data, and return success value
  cache[varname] = varvalue;
  errorCode = '0';
  return "true";

}

The additions are pretty straightforward.

• Lines 9 to 13, and 37 to 41 check to see whether the data element specified by the SCO is actually implemented (if you remember, I’m currently supporting all of the mandatory data elements, but only two of the optional elements). If the data element isn’t supported, the error code is set to ’401′.
   
• Lines 15 to 19, and 43 to 47 test whether the data element is readable (for the LMSGetValue function) or writeable (for the LMSSetValue function) and, if it fails, sets error code ’404′ or ’403′ respecively.
   

Note that, if the functions are successful, the error code is set to ’0′ before exit to indicate success. According to the SCORM RTE specification, every call to an API function must result in the error code being set – whether it’s successful or not.

Next time, I’m going to step away from the main VSSCORM code and do some work on a test harness that will allow me to monitor the SCO-LMS communications in order to make sure that all of this is working.

In a sensible system, the initialization process would provide the SCO with a complete list of supported elements so that it wouldn’t have to go through all this rigmarole. But that’s too much to hope for, so I need a simple way to check whether a data element is supported or not, and I’ll also need to check whether it’s readable and/or writeable.

I’m going to start with my favorite weapon of choice – a JavaScript object (associative array for the perl and PHP fans). Here it is:

var dataElements = new Object();

dataElements['cmi.core._children'] = 'RO';

dataElements['cmi.core.student_id'] = 'RO';
dataElements['cmi.core.student_name'] = 'RO';

dataElements['cmi.core.lesson_location'] = 'RW';
dataElements['cmi.core.credit'] = 'RO';
dataElements['cmi.core.lesson_status'] = 'RW';
dataElements['cmi.core.entry'] = 'RO';
dataElements['cmi.core.exit'] = 'WO';

dataElements['cmi.core.score._children'] = 'RO';
dataElements['cmi.core.score.raw'] = 'RW';
dataElements['cmi.core.score.max'] = 'RW';
dataElements['cmi.core.score.min'] = 'RW';

dataElements['cmi.core.total_time'] = 'RO';
dataElements['cmi.core.session_time'] = 'WO';

dataElements['cmi.suspend_data'] = 'RW';
dataElements['cmi.launch_data'] = 'RO';

dataElements['cmi.comments'] = 'RW';
dataElements['cmi.comments_from_lms'] = 'RO';

This is nothing more than a list of the supported elements with their read/write status.

Then, to make life a little neater when I come to plug this into the actual code, I’m going to define a simple little function:

function isSupported(dataElementName) {

  // flags
  dataElementSupported = false;
  dataElementRead = false;
  dataElementWrite = false;

  // if the data element is in the list of supported elements
  if (dataElementName in dataElements) {

    rights = dataElements[dataElementName];
    dataElementSupported = true;

    if ( (rights == 'RW') || (rights == 'RO') ) { dataElementRead = true; }
    if ( (rights == 'RW') || (rights == 'WO') ) { dataElementWrite = true; }

  }

  return dataElementSupported;

}

This function simply sets three flags that are available to the LMSSetValue and LMSGetValue functions so that they can test the SCO-supplied input, and generate appropriate error codes.

Next, I’m going to add this to the LMSSetValue and LMSGetValue functions.

Here they are:

function LMSGetLastError() {
  return errorCode;
}

function LMSGetErrorString(thisErrorCode) {
  return errorMessages[thisErrorCode];
}

function LMSGetDiagnostic(thisErrorCode) {
  return errorMessages[thisErrorCode];
}

Pretty simple so far. Next step – testing whether variables are supported and, if so, are they readable and/or writeable.

// ------------------------------------------
//   Status Flags
// ------------------------------------------
var flagFinished = false;
var flagInitialized = false;
var errorCode = '0';

Pretty simple. This variable is accessible to all of the functions that I’ve defined in api.php. So setting an error code is as simple as this (using LMSGetValue as an example):

function LMSGetValue(varname) {

  // not initialized or already finished
  if ((! flagInitialized) || (flagFinished)) {
    errorCode = '301';
    return '';
  }

  // otherwise, return the requested data
  errorCode = '0';
  return cache[varname];

}

You’ll see that I set ’301′ if (for some reason) the API hasn’t been initialized, and ’0′ if the call is successful. Obviously, there are a lot more tests and checks that I need to implement – for example, is the data element readable or not? And is it even supported by the API? I’ll get on to that later.

Next – setting up the API calls to handle the error code.

• LMSGetLastError()
• LMSGetErrorString()
• LMSGetDiagnostic()

I’ve already implemented “stubs” for these functions in my api.php code as noted in Step 10 – Other SCORM API Fuctions. But, before I make these functions active, I need to set up the error codes and related messages in the API code.

The error codes are all detailed in the SCORM 1.2 Runtime Environment specification – section 3.3.3. So, I’m going to set up a JavaScript object (which,having been brought up on perl and PHP, I tend to think of as an ‘associative array’) in the api.php code:

var errorMessages = new Object();
errorMessages['0'] = 'No Error';
errorMessages['101'] = 'General Exception';
errorMessages['201'] = 'Invalid Argument';
errorMessages['202'] = 'Element Cannot Have Children';
errorMessages['203'] = 'Element Not an Array - Cannot Have Children';
errorMessages['301'] = 'API Not Initialized';
errorMessages['401'] = 'Data Model Element Not Implemented';
errorMessages['402'] = 'Invalid Set Value - Element is a Keyword';
errorMessages['403'] = 'Invalid Set Value - Element is Read Only';
errorMessages['404'] = 'Invalid Get Value - Element is Write Only';
errorMessages['405'] = 'Invalid Set Value - Incorrect Data Type';

Why am I using strings e.g. ’201′ rather than numbers as indices? Because it’s one of the (many) idiosyncrasies of the SCORM standard!

Next time, setting and storing the error code.

From the PHP manual:

This function [mysql_escape_string()] is identical to mysql_real_escape_string() except that mysql_real_escape_string() takes a connection handler and escapes the string according to the current character set. mysql_escape_string() does not take a connection argument and does not respect the current charset setting.

The new function – mysql_real_escape_string – has been available since PHP 4.3 and, quite frankly, you really shouldn’t be running on anything older than that! So, at the next release of the RTE, I’ll be changing the database functions in subs.php to reflect this change.

On a final note, it’s still my intention to convert the code to run on a database abstraction layer, but I just haven’t had the time to do that yet!

But, recently, reader ‘deighvan’ reported a similar problem and, even better, came up with a simple solution. So I’ve incorporated a slightly modified form of this solution in a new version of the rte.php file.

Here it is:

<?php 

/*

VS SCORM 1.2 RTE - rte.php
Rev XXXXXXXXXXX was 2009-11-30-01
Copyright (C) 2010, Addison Robson LLC

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA  02110-1301, USA.

*/

// read SCOInstanceID from the GET parameters
$SCOInstanceID = $_GET['SCOInstanceID'] * 1;

?>
<html>
<head>
  <title>VS SCORM</title>
  <script language="javascript">

    var started = false;

    function loadSCO() {
      if (! started) {
        SCO.location.href = '... location of the SCO ...';
      }
      started = true;
    }

    function unloadSCO() {
      setTimeout('API.LMSFinish("");',2000);
    }

  </script>
</head>
<frameset frameborder="0" framespacing="0" border="0" rows="50,*" cols="*" onbeforeunload="unloadSCO();" onunload="unloadSCO();">
  <frame src="api.php?SCOInstanceID=<?php print $SCOInstanceID; ?>" name="API" id="API" noresize onload="loadSCO();">
  <frame src="blank.html" name="SCO" id="SCO">
</frameset>
</html>

And here are the changes … line-by-line:

• Line 35 – I define a Javascript variable called ‘started’ and set it to false. This will be used to prevent the SCO being started twice.
   
• Lines 37 to 42 – I’ve added a new Javascript function that, when called, will load the SCO into the ‘SCO’ frame.
   
• Line 51 – I’ve added an ‘onload’ action. When the api.php code has completely loaded into the frame, this will call loadSCO() which will start the SCO.
   
• Line 52 – When the frameset starts, I’m going to load a blank document into the ‘SCO’ frame. Why not just start with an empty frame (i.e. src=”)? Because, if I’m going to be running over an SSL connection, Internet Explorer considers an empty frame to be an insecure document and will pop up a warning message that’s annoying, and also worrying to many students.
   

So I try it out, and it seems to work much more smoothly than before. Once again, thanks to reader ‘deighvan’ for the suggestion.

The ‘datamodel.element._children’ mechanism described in the SCORM RTE specification seems to have been developed so that there’s a way for a SCO to determine which data elements are supported.

For example, if the SCO was to do this:

var supported = LMSGetValue('cmi.core._children');

the variable ‘supported’ would be set to ‘student_id,student_name,lesson_location,credit,lesson_status,entry,score,total_time,exit,session_time’ which is a list of the data elements in the cmi.core group that the LMS supports. This allows a SCO to determine whether or not it can use a particular data element before it tries to do so. And this is all well and good except …

… it doesn’t cover all of the optional data elements. The data element that the problem SCO was trying to use – cmi.comments – is not part of the cmi.core group of data elements, so looking at the value of cmi.core._children wouldn’t have helped. In fact, cmi.comments isn’t part of any group at all.

Now, the SCORM 1.2 RTE says that:

• If an element IS supported but contains no child elements, an empty string is returned.
• If an element IS NOT supported, an empty string is returned.

So there would be no way to use ‘_children’ to determine if cmi.comments was supported since:

var supported = LMSGetValue('cmi.comments._children');

would always return an empty string. Instead, according to the specification, one has to look at the error codes:

So, if I execute the following:

var supported = LMSGetValue('cmi.comments._children');
var lasterror = LMSGetLastError();

then variable ‘lasterror’ is set to 401, and I know that the cmi.comments element is NOT supported.

OK – it seems pretty odd to me that a system would be designed to cover some, but not all, of the optional data elements. But there it is – we’re going to have to live with it.

And it highlights a more fundamental issue that I need to fix – I’ve been very lax with my handling of the error codes so far – that has to change!

The SCO is trying to save the user’s comments to the LMS database when the SCO is closed. So, perhaps, the API code isn’t being given enough time to commit all of the data values to the database before everything shuts down.

To try to fix this, I’m going to add a delay to the closing sequence. As a reminder, here’s what my rte.php looks like right now.

<?php 

/*

VS SCORM 1.2 RTE - rte.php
Rev 2009-11-30-01
Copyright (C) 2009, Addison Robson LLC

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA	02110-1301, USA.

*/

// read SCOInstanceID from the GET parameters
$SCOInstanceID = $_GET['SCOInstanceID'] * 1;

?>
<html>
<head>
	<title>VS SCORM</title>
</head>
<frameset
  frameborder="0"
  framespacing="0"
  border="0"
  rows="100,*"
  cols="*"
  onbeforeunload="API.LMSFinish('');"
  onunload="API.LMSFinish('');">
	<frame src="api.php?SCOInstanceID=<?php print $SCOInstanceID; ?>" name="API">
	<frame src="... location of the course ..." name="course">
</frameset>
</html>

In lines 40 and 41 of the listing above, you’ll see that I’ve arranged for the LMSFinish() function to be called directly when the frameset tries to close down. I’m now going to change this by making the frameset call a Javascript function called unloadSCO() which, in turn, calls LMSFinish() after a delay. I’ve also taken the opportunity to re-name the frame from ‘course’ to ‘SCO’ to make the SCORM purists happy!

<?php 

/*

VS SCORM 1.2 RTE - rte.php
Rev XXXXXXXXXXX was 2009-11-30-01
Copyright (C) 2010, Addison Robson LLC

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA	02110-1301, USA.

*/

// read SCOInstanceID from the GET parameters
$SCOInstanceID = $_GET['SCOInstanceID'] * 1;

?>
<html>
<head>
	<title>VS SCORM</title>
	<script language="javascript">
		function unloadSCO() {
			setTimeout('API.LMSFinish("");',2000);
		}
	</script>
</head>
<frameset
  frameborder="0"
  framespacing="0"
  border="0"
  rows="50,*"
  cols="*"
  onbeforeunload="unloadSCO();"
  onunload="unloadSCO();">
	<frame src="api.php?SCOInstanceID=<?php print $SCOInstanceID; ?>" name="API" id="API" noresize">
	<frame src="... location of the course ..." name="SCO" id="SCO">
</frameset>
</html>

I now try it again, and it works! The students can write notes and they’re successfully saved to the database when the course closes.

But that’s not the end of things …

Here’s what was happening. The SCO in question was a technical training course – the subject is unimportant – and it ran OK except for one problem. The SCO author(s) had very helpfully provided a small text area on the SCO screens where a student could write notes and have them saved between sessions – in effect, online ‘PostIt’ notes. The problem was that the notes weren’t being saved to the database when the SCO was closed.

After digging around in the code, it became obvious that the SCO was storing all of the notes on the client side while the SCO was running – probably in a cookie, or maybe in a Javascript variable – until the SCO window was closed at which point it attempted to save them to the LMS database. Here’s the Javascript from the SCO (not the RTE) that seems to be failing.

function getCommentsData() {
  return scormGetValue("cmi.comments");
}

function setCommentsData(sSuspend) {
  scormSetValue("cmi.comments", sSuspend+"");
}

The first thing that to note is that the SCO is using the (optional) cmi.comments data element rather than the (mandatory) cmi.suspend_data element. And, to be fair, that’s what the cmi.comments data element is provided for.

So, as the first step in trying to fix the problem, I’m going to add the optional element cmi.comments and, while I’m at it, the related data element cmi.comments_from_lms.

I’m going to start with the LMSSetValue() function in the api.php file where I have to declare the cmi.comments data element as writeable (line 14):

function LMSSetValue(varname,varvalue) {

  // not initialized or already finished
  if ((! flagInitialized) || (flagFinished)) { return "false"; }

  // is this a writeable data element?
  if (
    (varname=='cmi.core.lesson_location') ||
    (varname=='cmi.core.lesson_status') ||
    (varname=='cmi.core.exit') ||
    (varname=='cmi.core.session_time') ||
    (varname=='cmi.core.score.raw') ||
    (varname=='cmi.core.suspend_data') ||
    (varname=='cmi.comments')
  ) {

    // set the requested data, and return success value
    cache[varname] = varvalue;
    return "true";

  }

  // not a writeable data element
  else {

    // return failure value
    return "false";

  }

}

Note that I don’t have to do anything with the cmi.comments_from_lms data element since it’s read-only. Now, in the LMSCommit() function, I make a corresponding change to add cmi.comments to the data being transferred to the LMS (line 24):

function LMSCommit(dummyString) {

  // not initialized or already finished
  if ((! flagInitialized) || (flagFinished)) { return "false"; }

  // create request object
  var req = createRequest();

  // code to prevent caching
  var d = new Date();

  // set up request parameters - uses POST method
  req.open('POST','commit.php',false);

  // create a POST-formatted list of cached data elements
  // include only SCO-writeable data elements
  var params = 'SCOInstanceID=&code='+d.getTime();
  params += "&data[cmi.core.lesson_location]="+urlencode(cache['cmi.core.lesson_location']);
  params += "&data[cmi.core.lesson_status]="+urlencode(cache['cmi.core.lesson_status']);
  params += "&data[cmi.core.exit]="+urlencode(cache['cmi.core.exit']);
  params += "&data[cmi.core.session_time]="+urlencode(cache['cmi.core.session_time']);
  params += "&data[cmi.core.score.raw]="+urlencode(cache['cmi.core.score.raw']);
  params += "&data[cmi.suspend_data]="+urlencode(cache['cmi.suspend_data']);
  params += "&data[cmi.comments]="+urlencode(cache['cmi.comments']);

  // request headers
  req.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
  req.setRequestHeader("Content-length", params.length);
  req.setRequestHeader("Connection", "close");

  // submit to the server for processing
  req.send(params);

  // process returned data - error condition
  if (req.status != 200) {
    alert('Problem with AJAX Request in LMSCommit()');
    return "false";
  }

  // process returned data - OK
  else {
    return "true";
  }

}

Now to look at subs.php where I need to add both of these elements to the list so that they’re initialized when the SCO first starts. Pretty simple – I add the following lines to the initializeSCO() function (omitting most of the other lines for clarity):

function initializeSCO() {

  ...
  ...

  // comments
  initializeElement('cmi.comments','');
  initializeElement('cmi.comments_from_lms',getFromLMS('cmi.comments_from_lms'));

  ...
  ...

}

cmi.comments starts out as an empty string, but the cmi.comments_from_lms data element needs to be initialized with a value from the LMS. So my final task is to change the getFromLMS() function:

function getFromLMS($varname) {

  switch ($varname) {

    ...
    ...

    case 'cmi.comments_from_lms':
      $varvalue = "";
      break;

    ...
    ...

  }

  return $varvalue;

}

Now, I’ve added the new data elements and I run the SCO again. No good – the problem is still there. There must be another problem that I haven’t spotted.