The run-time API (application programming interface) methods provide a standardized way for SCOs to communicate with the LMS while shielding the communication implementation from the SCO developer.

There are eight run-time API functions provided by the SCORM run-time environment:
• Initialize("")
• Terminate("")
• GetValue(parameter)
• SetValue(parameter1, parameter2)
• Commit("")
• GetLastError()
• GetErrorString(parameter)
• GetDiagnostic(parameter)

Trident has built-in support for the SCORM Run-Time API. Trident contains HTML and JavaScript editors for SCOs that have content-assist for API objects and methods.

Session Methods

Session methods are used to initiate and terminate data communication between a SCO and an API instance. Calling a session method may change the API instance's current error code.

The Initialize("") function is used to initiate the communication session. It allows the LMS to handle LMS specific initialization issues.

Initialize() parameters (all required):
• "" - always an empty string

Initialize() return values:
• true - returned if communication session initialization was successful as determined by the LMS
• false - returned if the communication session initialization was not successful

The Terminate("") function is used to terminate the communication session. It is used by the SCO when the SCO has determined that it no longer needs to communicate with the LMS.

Terminate() parameters (all required):
• "" - always an empty string

Terminate() return values:
• true - returned if communication session termination was successful as determined by the LMS
• false - returned if the communication session termination was not successful

Data-Transfer Methods

The GetValue(parameter) function requests information from the LMS. It permits the SCO to request information from the LMS, including the value of data model elements.

GetValue() parameters (all required):
• parameter - the name of a Run-time Data Model element (e.g. "learner.learner_id")

GetValue () return values:
• The value of the data model element parameter
• An empty characterstring ("") - if an error occurs (GetLastError() should be called to determine the nature of the error)

The SetValue(parameter1, parameter2) function is used to request the transfer to the LMS of the value of data model elements.

SetValue() parameters (all required):
• parameter1 - the name of a Run-time Data Model element (e.g. "learner.learner_id")
• parameter2 - the value to set the data model element to

SetValue() return values:
• true - returned if the value of parameter2 was accepted for the data model element parameter1
• false - if an error occurs (GetLastError() should be called to determine the nature of the error)

The Commit("") function requests forwarding to the persistent data store any data from the SCO that may have been cached by the API instance. The method can be used to guarantee that data set by SetValue() is persisted to reduce the likelihood that data is lost due to communication session interruption or abnormal session termination prior to a call to Terminate().

Commit() parameters (all required):
• "" - always an empty string

Commit() return values:
• true - returned if the commit succeeded
• false - returned if the commit failed

Support Methods

The GetLastError() function requests the error code for the current error state of the API instance.

GetLastError() parameters (all required):
• (none)

GetLastError() return values:
• the error code reflecting the current error state of the API instance

The GetErrorString(parameter) function retrieves a textual description of the current error state.

GetErrorString() parameters (all required):
• parameter - an error code (e.g. "301")

GetLastError() return values:
• the LMS-specific error string for the passed error code (maximum length of 255 characters)

The GetDiagnostic(parameter) function exists for LMS specific use and allows the LMS to define additional diagnostic information through the API instance.

GetDiagnositc() parameters (all required):
• parameter - an implementer-specific value for diagnostics

GetDiagnositc () return values:
• the LMS-specific diagnostic string for the passed parameter

The Run-Time API (application programming interface) is the communication mechanism for informing the LMS of the communication state and between a content object and the LMS (e.g., initialized, terminated, and/or in an error condition), and is used for retrieving and storing data (e.g., score and time limits) between the LMS and the SCO.

Only launched SCOs (not Assets) make use of the RTE API.

API usage guidelines:
• The function names are all case-sensitive.
• The function parameters are all case-sensitive. Data model parameters are to be represented as lower case.
• Each call to an API function, other than Support methods (GetLastError, GetErrorString, GetDiagnostic), sets the error code.
• All parameters passed between the SCO and the API instance are treated as ECMAScript characterstring. All parameter values shall be compatible with the data types and formats described by the data models that use the API for communication.

RTE/LMS implementations are responsible for providing an API instance that SCOs can use. The API instance is exposed as an object in the Document Object Model (DOM), typically as a JavaScript variable. The LMS must launch the SCO in a browser window that is a dependent window (i.e., "pop-up" window) or child frame of the browser window that exposes the API instance.

SCOs are responsible for retrieving the API instance provided by the RTE/LMS. Typically this is done, via JavaScript, by recursively searching the parent and/or opener window hierarchy until the API instance is found. The mandatory name for the object in the browser DOM that is associated with the API instance is API_1484_11.

Once a SCO finds an API instance, the SCO is required, at a minimum, to issue Initialize("") and Terminate("") API calls.

The API instance will establish a communication session with the RTE/LMS when Initialize() is called. The communication session will end when Terminate() is called.
 

The states an API instance transitions through:

• Not Initialized - before Initialize() is called
• Running - after Initialize() is successfully called and before Terminate() is successfully called
• Terminated - after Terminate() is successfully called

The run-time API (application programming interface) methods provide a standardized way for SCOs to communicate with the LMS while shielding the communication implementation from the SCO developer.

There are eight run-time API functions provided by the SCORM run-time environment:
• Initialize("")
• Terminate("")
• GetValue(parameter)
• SetValue(parameter1, parameter2)
• Commit("")
• GetLastError()
• GetErrorString(parameter)
• GetDiagnostic(parameter)