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.

Now, it’s time to start up again and tackle a couple of issues that I’ve been wanting to deal with:

• error codes and error messages;
• a logging capability to help diagnose SCO to LMS communication problems.

So, with that in mind, in my next post I’m going to start attacking the error codes and messages.

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!