ODAX Module

RhoElements 2.x API

Overview

The ODAX Preexisting JavaScript Object module reads from .CSV or .XML files to provide offline data access. If a value of "1" is contained in the <PreloadLegacyODAX> parameter of the Config.xml file, the JavaScript object "odax" will be automatically inserted by RhoElements into the DOM of the running app, and result set stored internally in the "odax" object and manipulated using the exposed methods below.

This API should be used only to provide backward compatibility with legacy applications. For new apps, Zebra recommends implementing such capabilities using Application Cache and Web SQL modules.

Syntax

ODAX (Preexisting JavaScript Object) <META> Syntax

odax.Select('SELECT * FROM \'\\application\\test.xml\';', ',', false);

Methods

NameParametersReturns
Clear
Clears the result set.
Copy
Copies the specified source filename to the destination filename.
Name: Source, Values: String
Description: Full path of the source file name that is to be copied.

Name: Destination, Values: String
Description: Full path of the destination file name.

0 if no error is received. If an error occurs the value from Windows API call GetLastError() is returned, if appropriate.
Delete
Deletes the specified file.
Name: FileName, Values: String
Description: Full path of the file name that is to be deleted.

0 if no error is received. If an error occurs the value from Windows API call GetLastError() is returned, if appropriate.
FileExists
Checks to see whether the specified file exists.
Name: FileName, Values: String
Description: Full path of the file name that is to be checked.

True if the specified file exists, else False if it does not.
Execute
performs INSERT, UPDATE and DELETE statements on the specified file. The file can be either XML or CSV.
Name: SQL Statement, Values: String
Description: String representing the INSERT, UPDATE and DELETE SQL statement to be executed.

Name: Format, Values: 0 or 1
Description: If no extension is supplied the format parameter is used to determine file format (0 = XML, 1 = CSV).

Name: Delimiter, Values: Character
Description: Delimiter which is used in CSV files as a column separator. Even though there is no special use for this in XML files you cannot leave this blank, hence you need to provide a valid value.

Name: First Row, Values: 'True' or 'False'
Description: This denotes that the first row of a CSV file contain the Column Names. If set to false in CSV mode it will retrieve columns as column1, column2 etc.

The count of records affected by the operation or 0 if no records were affected.
Get
Retrieves the column value specified, from the current result set. There must a valid result set in order to successfully execute this command, otherwise the operation will result in an error. In a CSV file, if the firstrow is set to true then strFieldName should have the field name else if firstrow is set to false then Column1 ... ColumnN literals should be used to retrieve the appropriate filed values.
Name: Field Name, Values: String
Description: Field Name to be retrieved.

The value from the specified field in the current result set record or a negative value if an error occurs.
GetLastErrorString
Returns a string containing an error message relating to the last error that occurred.
String containing the last error message.
Move
Moves the specified source filename to the destination filename.
Name: Source, Values: String
Description: Full path of the source file name that is to be moved.

Name: Destination, Values: String
Description: Full file name and path where the file will be moved to.

0 if no error occurs or an error code (see GetLastErrorString).
MoveFirst
Moves the row pointer to the first record of the result set. There must a valid result set in order to successfully execute this command, otherwise the operation will result in an error.
0 if no error occurs or an error code (see GetLastErrorString).
MoveLast
Moves the row pointer to the last record of the result set. There must a valid result set in order to successfully execute this command, otherwise the operation will result in an error.
0 if no error occurs or an error code (see GetLastErrorString).
MoveNext
Moves the row pointer to the next record of the result set. There must a valid result set in order to successfully execute this command, otherwise the operation will result in an error.
0 if no error occurs or an error code (see GetLastErrorString).
MovePrev
Moves the row pointer to the previous record of the result set. There must a valid result set in order to successfully execute this command, otherwise the operation will result in an error.
0 if no error occurs or an error code (see GetLastErrorString).
Select
Queries XML or CSV based database files. This method performs the SQL SELECT statement on the specified file and populates the object's result set.
Name: SQL Statement, Values: String
Description: String representing the SELECT SQL statement to be executed.

Name: Delimiter, Values: Character
Description: Delimiter which is used in CSV files as a column separator. Even though there is no special use for this in XML files you cannot leave this blank, hence you need to provide a valid value.

Name: First Row, Values: 'True' or 'False'
Description: This denotes that the first row of a CSV file contain the Column Names. If set to false in CSV mode it will retrieve columns as column1, column2 etc.

The number of records in the result set or a negative number to indicate an error (see GetLastErrorString).

Remarks

Good Practise

It's good practice to check if the file exists before copying it. To do this use FileExists() method. This will support any file extension and will work as per normal file copy command. If file already exists with the same name in the destination folder/path it would be overwritten.

First Row

The delimiter and firstrow are a Select. If firstrow is set to true when creating a table with INSERT, then the field names are written to the first row as column names.

Query needed after Execute

The current result set becomes invalid after any Execute (INSERT, UPDATE, DELETE) and arbitrary values will be returned by MoveFirst etc. A new SELECT query must be performed to get valid results.

Backwards Compatibility

The ODAX Preexisting JavaScript Object provides backwards compatibility with code written for PocketBrowser and also supports the syntax below. Because RhoElements inserts the object 'odax' on the page automatically when 'PreloadLegacyODAX' is configured to be '1' you can not create your own objects by this name, see below:


<script>
  //  Old PocketBrowser syntax supported by ODAX
  var myObj = new ActiveXObject("CeODAX.ODAX"); 

  //  Note: var odax = new ... will fail because the object already exists on the page.
  myObj.Delete('\\windows\\crazy_frog.wav');
</script>

Requirements

RhoElements Version1.0.0 or above
Supported DevicesAll supported devices except: Enterprise Tablet
Minimum RequirementsNone.
PersistenceImmediate - These methods are actioned immediately.

HTML/JavaScript Examples

The Following example shows usage of the odax object to manipulate files on the device:

<script>
   //  Copy a file
   var srcFileName = '\\application\\test.xml';
   var destFileName = '\\windows\\test.xml';
   var status1 = odax.Copy(srcFileName, destFileName);

   //  Move a file
   var status2 = odax.Move(srcFileName, destFileName);

   //  Check if a file exists
   if( true == odax.FileExists(destFileName))
   {
      alert("File: "+ destFileName + " Exists!");
   }

   //  Delete a file
   var status3 = odax.Delete(destFileName);

</script>

The following example inserts records to a XML file:

<script>
   var FieldValue1 = 'Red';
   var FieldValue2 =  Green';
   var FieldValue3 = 'Blue';

   var QueryString = 'INSERT INTO \'\\application\\test.xml\' (field1,field2,field3) VALUES (';
   QueryString += '\''+FieldValue1+'\',';
   QueryString += '\''+FieldValue2+'\',';
   QueryString += '\''+FieldValue3+'\');';
   var count = odax.Execute(QueryString,0,',',false);
</script>

The following example inserts records to a CSV file:

<script>
   var QueryString = 'INSERT INTO \'\\application\\test.csv\' (field1,field2,field3) VALUES (';
   QueryString += '\''+FieldValue1+'\',';
   QueryString += '\''+FieldValue2+'\',';
   QueryString += '\''+FieldValue3+'\');';
   var count = odax.Execute(QueryString,1,',',true);
</script>

The following example updates records in a XML file

<script>
   var fieldValue = 'Orange';
   var conditionField = 'Red';

   var QueryString = 'UPDATE \'\\application\\test.xml\' SET field1=';
   QueryString += '\''+ fieldValue +'\'';
   QueryString += ' WHERE field1=\'';
   QueryString += conditionField +"\';"
   var count = odax.Execute(QueryString,0,',',false);
</script>

The following example deletes records in a XML file

<script>
   var conditionField = 'Red';

   var QueryString = 'DELETE FROM \'\\application\\test.xml\' WHERE field1=';
   QueryString += '\''+ conditionField +'\';';
   var count = odax.Execute(QueryString,0,',',false);
</script>

The following example clears the resultset after a query is executed:

<script>
   var count = odax.Select('SELECT * FROM \'\\application\\test.xml\';', ',', false);
   odax.Clear();
</script>

The following JavaScript gets the column 'field1' from the resultset:

<script>
   var count = odax.Select('SELECT * FROM \'\\application\\test.xml\';', ',', false);
   var colval = odax.Get("field1");
</script>

The following JavaScript moves the row pointer to the first record of the resultset:

<script>
   var count = odax.Select('SELECT * FROM \'\\application\\test.xml\';', ',', false);
   var result = odax.MoveFirst();
</script>

The following JavaScript moves the row pointer to the next record in the resultset:

<script>
   var count = odax.Select('SELECT * FROM \'\\application\\test.xml\';', ',', false);
   var result = odax.movenext();
</script>

The following JavaScript moves the row pointer to the previous record in the resultset:

<script>
   var count = odax.Select('SELECT * FROM \'\\application\\test.xml\';', ',', false);
   var result = odax.moveprev();
</script>

The following JavaScript moves the row pointer to the last record of the resultset

<script>
   var count = odax.Select('SELECT * FROM \'\\application\\test.xml\';', ',', false);
   var result = odax.movelast();
</script>

The following JavaScript selects all records from a XML file:

<script>
   var count = odax.Select('SELECT * FROM \'\\application\\test.xml\';', ',', false);
</script>