VSSCORM » Run Time Environment

VSSCORM » Run Time Environment http://www.vsscorm.net A Very Simple SCORM Interface Tue, 20 Jul 2010 17:08:37 +0000 en hourly 1 http://wordpress.org/?v=3.0.1 Step 56 – mysql_escape_string http://www.vsscorm.net/2010/07/19/step-56-mysql_escape_string/ http://www.vsscorm.net/2010/07/19/step-56-mysql_escape_string/#comments Mon, 19 Jul 2010 14:05:55 +0000 Steve Addison http://www.vsscorm.net/?p=1514 Continue reading →]]> I don’t refer to the PHP manual very much for commonly used functions, so I almost missed this one. The ‘mysql_escape_string’ function that’s used in subs.php to prepare data for insertion into the database is deprecated as of PHP 5.3 and should be replaced with ‘mysql_real_escape_string’.

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!

]]> http://www.vsscorm.net/2010/07/19/step-56-mysql_escape_string/feed/ 0 Step 55 – Delaying Loading of the SCO http://www.vsscorm.net/2010/07/16/step-55-delaying-loading-of-the-sco/ http://www.vsscorm.net/2010/07/16/step-55-delaying-loading-of-the-sco/#comments Fri, 16 Jul 2010 13:45:07 +0000 Steve Addison http://www.vsscorm.net/?p=1554 Continue reading →]]> In the past, I’ve had some intermittent problems with a SCO loading but showing a Javascript error. Although I couldn’t pin it down conclusively, it seemed to result from an incomplete download of some kind. Since forcing a reload with CTRL-R or CTRL-F5 usually solved the problem, I just put it down to something that I had to live with because SCORM forces us to use Javascript which can be very fickle.

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.

]]> http://www.vsscorm.net/2010/07/16/step-55-delaying-loading-of-the-sco/feed/ 2 Step 54 – Error Handling? http://www.vsscorm.net/2010/07/13/step-54-error-handling/ http://www.vsscorm.net/2010/07/13/step-54-error-handling/#comments Tue, 13 Jul 2010 14:52:31 +0000 Steve Addison http://www.vsscorm.net/?p=1507 Continue reading →]]> The problem SCO described in Step 52 is now working correctly, so why do I need to look any further? There’s a more subtle problem.

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.

SCORM 1.2 RTE Specification – Page 3-9

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:

SCORM 1.2 RTE Specification – Page 3-9

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!

]]> http://www.vsscorm.net/2010/07/13/step-54-error-handling/feed/ 0 Step 53 – Delaying the Closing Sequence http://www.vsscorm.net/2010/07/11/step-53-delaying-the-closing-sequence/ http://www.vsscorm.net/2010/07/11/step-53-delaying-the-closing-sequence/#comments Sun, 11 Jul 2010 21:21:38 +0000 Steve Addison http://www.vsscorm.net/?p=1505 Continue reading →]]> I’m still trying to fix the problem that my reader’s SCO highlighted (described in this post). I’ve implemented the optional data element that it’s trying to use – cmi.comments – but that hasn’t fixed the problem. So I need to look elsewhere.

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 …

]]> http://www.vsscorm.net/2010/07/11/step-53-delaying-the-closing-sequence/feed/ 2 Step 52 – cmi.comments and cmi.comments_from_lms http://www.vsscorm.net/2010/07/09/step-52-cmi-comments-and-cmi-comments_from_lms/ http://www.vsscorm.net/2010/07/09/step-52-cmi-comments-and-cmi-comments_from_lms/#comments Sat, 10 Jul 2010 00:33:24 +0000 Steve Addison http://www.vsscorm.net/?p=1500 Continue reading →]]> A reader recently contacted me with a problem that raised some interesting issues. Hopefully, we’ve now resolved the problem but, since the issues might well occur with other SCOs, what I’d like to do is to walk through the process and show how the VSSCORM RTE has to be modified to deal with this situation.

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.

SCORM 1.2 RTE Specification – Page 3-35

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.

SCORM 1.2 RTE Specification – Page 3-36

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.

]]> http://www.vsscorm.net/2010/07/09/step-52-cmi-comments-and-cmi-comments_from_lms/feed/ 2 Download VS SCORM 1.2 RTE Rev 2.1 http://www.vsscorm.net/2010/04/30/download-vs-scorm-1-2-rte-rev-2-1/ http://www.vsscorm.net/2010/04/30/download-vs-scorm-1-2-rte-rev-2-1/#comments Fri, 30 Apr 2010 07:39:21 +0000 Steve Addison http://www.vsscorm.net/?p=1254 Continue reading →]]> After a somewhat longer time than I’d planned, here’s Rev 2.1 of the VSSCORM 1.2 RTE. It includes the following changes from Rev 2.0:

Fix for the “cmi.score.raw” bug described in this post.
Fix for the “ab initio” bug described in this post.
Adds the “flagFinished” and “flagInitialized” variables to store API state information as discussed in this post.

You can download the code bundle using this link.

If you’re upgrading, it should be pretty simple since the new files simply replace the old ones – no need to change the database or file structure.

Next time, some thoughts on where this project is taking me.

]]> http://www.vsscorm.net/2010/04/30/download-vs-scorm-1-2-rte-rev-2-1/feed/ 5 Another Bug in VS SCORM 1.2 RTE Rev 2.0 http://www.vsscorm.net/2010/03/19/another-bug-in-vs-scorm-1-2-rte-rev-2-0/ http://www.vsscorm.net/2010/03/19/another-bug-in-vs-scorm-1-2-rte-rev-2-0/#comments Fri, 19 Mar 2010 19:22:38 +0000 Steve Addison http://www.vsscorm.net/?p=1244 Continue reading →]]> An eagle-eyed reader of the blog has brought the following bug to my attention.

In all cases in the php code, you use the string “ab initio” as the value for cmi.core.entry when it is the first time a SCO is used.

According to the SCORM 1.2 spec doc, SCORM_1.2_RunTimeEnv.pdf – page 3-22, (page 34 of the file), the value should be “ab-initio” with a hyphen.

This affects line 124 of subs.php in VS SCORM 1.2 RTE Rev 2.0:

initializeElement('cmi.core.entry','ab initio');

which should read:

initializeElement('cmi.core.entry','ab-initio');

I haven’t check the Rev 1.x release, but it shouldn’t be too hard to do a quick search of the code if you haven’t upgraded to Rev 2.0 (strongly recommended for speed reasons alone).

The fix will be in Rev 2.1 of the RTE which I’ll try to post next week.

]]> http://www.vsscorm.net/2010/03/19/another-bug-in-vs-scorm-1-2-rte-rev-2-0/feed/ 0 Step 51 – Testing for API Session State http://www.vsscorm.net/2010/01/22/step-51-testing-for-api-session-state/ http://www.vsscorm.net/2010/01/22/step-51-testing-for-api-session-state/#comments Fri, 22 Jan 2010 21:23:26 +0000 Steve Addison http://www.vsscorm.net/2010/01/22/step-51-testing-for-api-session-state/ Continue reading →]]> In Step 48, I introduced a flag to indicate whether a session had been finished or not. In that post, it was used to ensure that LMSFinish wasn’t called multiple times. But I really ought to extend it to make sure that none of the API functions are processed after the session has been closed.

In addition, I should probably make sure that no API calls are processed before the API session has been initialized. This isn’t as much of a problem as long as the SCO has been well-written since, according to the SCORM standard, LMSInitialize should always be the first API function called by the SCO/course.

So, building on the work I did in Step 48, I’m going to introduce a second JavaScript variable – flagInitialized – into api.php:

var flagFinished = false;
var flagInitialized = false;

There are now five API calls to be changed so that they test for appropriate values of flagInitialized and flagFinished.

1. LMSInitialize

This API call can only be executed if the session HASN’T already been initialized, and the session HASN’T been closed. So I modify my code like this:

function LMSInitialize(dummyString) {

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

  // set initialization flag
  flagInitialized = true;

  // return success value
  return "true";

}

If either flagInitialized or flagFinished is set to ‘true’, execution of the function will be aborted. If it proceeds, line 7 sets the ‘flagInitialized’ variable so that other API calls know that the session is initialized.

2. LMSFinish

This API call can only be executed if the session HAS been initialized but HAS NOT yet been closed. So the code looks like this

function LMSFinish(dummyString) {

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

  ...
  ...

  // set finish flag
  flagFinished = true;

  // return to calling program
  return "true";

}

Very similar to LMSInitialize except that I only allow the code to run if flagInitialized is set to ‘true’, and flagFinished is set to ‘false’. If the function executes correctly, line 10 sets flagFinished to ‘true’ so that there can be no further communication between the SCO/course and the LMS.

3. LMSGetValue, LMSSetValue and LMSCommit

Finally, I need to add the following code to each of these three API calls to ensure that the code is only executed if the session HAS been initialized, but HAS NOT been closed.

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

And that’s it.

]]> http://www.vsscorm.net/2010/01/22/step-51-testing-for-api-session-state/feed/ 1 Bug in VSSCORM 1.2 RTE Rev 2.0 http://www.vsscorm.net/2010/01/20/bug-in-vs-scorm-1-2-rte-rev-2-0/ http://www.vsscorm.net/2010/01/20/bug-in-vs-scorm-1-2-rte-rev-2-0/#comments Wed, 20 Jan 2010 19:38:10 +0000 Steve Addison http://www.vsscorm.net/?p=1226 Continue reading →]]> I recently spotted a bug in VS SCORM 1.2 RTE Rev 2.0. Line 54 of finish.php reads:

$rawscore = readElement('cmi.score.raw');

It should read:

$rawscore = readElement('cmi.core.score.raw');

I’ll incorporate this fix in a new release of the RTE once I’ve made a few other improvements.

]]> http://www.vsscorm.net/2010/01/20/bug-in-vs-scorm-1-2-rte-rev-2-0/feed/ 0 A Simple SCORM 1.2 Content Package http://www.vsscorm.net/2010/01/20/a-simple-scorm-1-2-content-package/ http://www.vsscorm.net/2010/01/20/a-simple-scorm-1-2-content-package/#comments Wed, 20 Jan 2010 19:11:56 +0000 Steve Addison http://www.vsscorm.net/?p=1212 Continue reading →]]> If you want a very simple test case, you can use this content package – a single SCO consisting of:

a title page;
3 test questions (the correct answer in each case is “true”); and
a results page.

It was created using Lectora, runs in a 760 x 550 window, and sets ‘cmi.core.lesson_status’ to “passed” to indicate completion. The SCO entry point is ‘a001index.html’.

You can download it from here

Hope it helps!

]]> http://www.vsscorm.net/2010/01/20/a-simple-scorm-1-2-content-package/feed/ 0