List of functions

Description of functions
-----------------------------------------------------------------------------------------------------------------------------------------------------------

new
It is necessary to initiate the dmmXLS XTRA before the first use.

Example - Director
global xls
openXlib the pathName&"dmmXLS.x32"
xls=new(xtra "dmmXLS")

If the library dmmXLS.x32 is located in the XTRAS folder it is enough to insert
global xls
xls=new(xtra "dmmXLS")

Example - Authorware
xls:=NewObject("dmmXLS")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=registration( name: string, code:string)
This function has to be called before the first use of the dmmXLS immediately after its initialisation. Unless the right registration name and number are inserted, an announcement "this is a demo version" will appear.

Parametres
Type of name is string, for the demo version name = "dmm".
Type of code is string, for the demo version code= "demo". The chain for commercial version is unique.
To register the user will receive parameters code and name.

Very important
For safety reasons incorrect parameters can be only inserterted 3 times in the function registration. If you insert incorrect parameters name and code more times the registration is blocked and the XTRA will not work. You will be informed about it by a dialogue window. In this case you´ve got to restart Director or Authorware.

Note
Parameters name="dmm" and code="demo" are not considered as incorrect.
The demo version of the XTRA dmmXLS can only be run in the "Author" mode. In the "Projector" mode the demo version is not functional.

Example - Director
global xls
xls.registration("dmm", "demo")

Example - Authorware
CallObject(xls; "registration"; "dmm"; "demo")

-----------------------------------------------------------------------------------------------------------------------------------------------------------
list=xtraVersion()
The function returns information about the XTRA dmmXLS. The function returns values in the format Abstract Data Types:
[#fileType: "Xtra (32)",
 #CompanyName: "Studio dmm",
 #FileDescription: "dmmXLS.x32",
 #FileVersion: "1.8.0.17",
 #InternalName: "dmmXLS.x32",
 #LegalCopyRight: "© Studio dmm 1992-2005",
 #LegalTradeMarks: "",
 #OriginalFileName: "dmmXLS.x32",
 #productName: "dmmXLS.x32",
 #productVersion: "1.8.0.0"]

The meaning of the items is clear and it is not necessary to describe it closer.

Parametres
There are no parametres in this function.

Example - Director
global xls
xv=xls.xtraVersion()
put "FileDescription:" && xv.FileDescription
put "FileVersion:" && xv.FileVersion

Example - Authorware
xv:=CallObject(xls; "xtraVersion")
Trace("FileDescription: " ^ xv[#FileDescription])
Trace("FileVersion: " ^ xv[#FileVersion])

-----------------------------------------------------------------------------------------------------------------------------------------------------------

string=errorMsg()
The function gives text of the error that occured while working with dmmXLS. If everything went well, the function gives an empty chain

Parametres
There are no parametres in this function.

Example - Director
global xls
xls.loadFromFile(the pathName&"data.xls")
error=xls.ErrorMsg()
if error="" then val=xls.getCellString(2, 10)

Example - Authorware
error:=CallObject(xls; "errorMsg")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=isNoError()
The function gives back true, if no error occured during an operation. If an error occurs the function gives back false.

Parametres
There are no parametres in this function.

Example - Director
global xls
xls.loadFromFile(the pathName&"data.xls")
if xls.isNoError() then val=xls.getCellString(2, 10)

Example - Authorware
error:=CallObject(xls; "isNoError")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=errorDialog(dialog: boolean)
Using this function we can set whether a dialogue window, showing error statement appears at the moment of an error or not. This setting only functions in Autor mode and it simplifies the application debugging. If you decide not to set the dialogue window you can check the errors using the function errorMsg().

Parametres
Dialog is the only parameter of the function, whose type is boolean. If the value is true, the dialogue window with error statement is opened with every error in the XTRA. For the parameter value false the window is not shown. Default setting is dialog=false.

Example - Director
global xls
xls.errorDialog(true)

Example - Authorware
CallObject(xls; "errorDialog"; true)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=errorLog(logFile: string, logSave: boolean)
Using this function we can set whether an error is saved to text log file at the time of the error or not. This setting only functions in Autor mode and it simplifies the application debugging.

Parametres
The function has two parametres. The parameter logFile represents name of the log file that we want to save the errors to. Type of the logSave parametre is boolean. If its value is true, every error in the XTRA is saved to log file. If its value is false nothing will be saved. Default setting is logSave=false.

Example - Director
global xls
xls.errorLog(the pathName&"log.txt", true)

Example - Authorware
CallObject(xls; errorLog; FileLocation ^ "log.txt"; true)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=loadFromFile(file:string)
This function reads an xls file for next use. We cannot read the contents of cells, unless it si read using the function loadFromFile.

Parametres
Type of file is string and we insert name of an xls file including the path.

Example - Director
global xls
xls.loadFromFile(the pathName&"data.xls")

Example - Authorware
CallObject(xls; "loadFromFile"; FileLocation ^ "data.xls")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=saveToFile(file:string)
The function saves an xls file on the disc.

Parametres
Type of file is string and we insert name of the xls, including the path.

Example - Director
global xls
xls.saveToFile(the pathName&"data.xls")

Example - Authorware
CallObject(xls; "saveToFile"; FileLocation ^ "data.xls")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=loadFromHttp(url:string)
This function enables to download xls files from the internet using the method get and protocol http. In the case the file has been successfully downloaded the function gives true, otherwise in gives false. To have this function activated in the XTRA you need to have the additive library dmmHttp in the directory where dmmXLS is placed.

Parametres
The function has one parameter being url, whose type is string and it represents Url of the downloaded document.

Note
To be able to download XLS files from a web server you need to allow the format XLS among MIME types.

Example - Director
global xls
xls.loadFromHttp("http://xtra.web-cd.net/data.xls")

Example - Authorware
CallObject(xls; "loadFromHttp"; "http://xtra.web-cd.net/data.xls")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=loadFromZip(zipFile, zipPassword, xlsFile:string)
This function loads xls documents saved in a zip archive. The work procedure is easy. We prepare xls files and compress them to a zip. We can protect this zip with a password. The function loadFromZip enables to read separate files of the archive and to show them in Director or Authorware using XTRA dmmXLS. To have this function activated in the XTRA you need to have the additive library dmmZip in the directory where dmmXLS is placed. In the case the file has been successfully loaded the function gives true, otherwise it gives false.

Parametres
There are 3 parametres in this function. ZipFile is a zip archive, in which we keep the documents. ZipPassword is a password for the zip archive. If there is no password, we insert an empty chain. XlsFile is a name xls file in a zip document. We have to insert the name including the extension.

Example - Director
global xls
xls.loadFromZip(the pathName & "demo.zip", "abc", "data.xls" )

Example - Authorware
CallObject(xls; "loadFromZip"; FileLocation ^ "demo.zip"; "abc"; "data.xls")

-----------------------------------------------------------------------------------------------------------------------------------------------------------


void=setActiveSheet(sheet:integer)
The function sets the actual sheet in xls, which we want to work with.

Parametres
Sheet is number of the sheet in xls, which we want to work with. The parameter can reach the values 1 and higher, depending on how many sheets we define in xls.

Example - Director
global xls
xls.setActiveSheet(2)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 2)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

string=getSheetName()
The function returns name of the actual sheet, set by the function setActiveSheet.

Parametres
There are no parametres in this function.

Example - Director
global xls
xls.setActiveSheet(1)
put xls.getSheetName()

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
val:=CallObject(xls; "getSheetName")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

integer=firstCol()
The function gives number of the first column containing data used in a sheet.

Parametres
There are no parametres in this function.

Example - Director
global xls
minCol=xls.firstCol()

Example - Authorware
minCol:=CallObject(xls; "firstCol")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

integer=lastCol()
The function gives number of the last column containing data used in a sheet.

Parametres
There are no parametres in this function.

Example - Director
global xls
maxCol=xls.lastCol()

Example - Authorware
maxCol:=CallObject(xls; "lastCol")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

integer=firstRow()
The function gives number of the first row containing data used in a sheet.

Parametres
There are no parametres in this function.

Example - Director
global xls
minRow=xls.firstRow()

Example - Authorware
minRow:=CallObject(xls; "firstRow")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

integer=lastRow()
The function gives number of the last row containing data used in a sheet.

Parametres
There are no parametres in this function.

Example - Director
global xls
maxRow=xls.lastRow()

Example - Authorware
maxRow:=CallObject(xls; "lastRow")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

string=getCellString(col:integer, row:integer)
The function reads contents of a cell in xls format and gives it back in string format. If, for example, integer value is included in the cell, it is also converted into string format. If a formula is included in the cell, its value is given back.

Parametres
Col and row are coordinates of the cell, whose contents we want to read. Col is a column coordinate and row is a row coordinate. The values range from firstCol and lastCol, or firstRow and lastRow.

Example - Director
global xls
xls.setActiveSheet(1)
val=xls.getCellString( 2, 10)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
val:=CallObject(xls; "getCellString"; 2; 10)

-----------------------------------------------------------------------------------------------------------------------------------------------------------
void=setCellString(col:integer, row:integer, val: string)
The function saves the content in the string format to a cell in xls document.

Parametres
Col and row are coordinates of the cell, that we want to save the string value to. Col is a coordinate of column and row is a coordinate of row. The values range from firstCol to lastCol, respectively from firstRow to lastRow. Type of val is string and insert a text chain, that we save to a cell.

Note
We can only save to a sheet, that exists. After insertion of values we can save the xls file using the function saveToFile, or we only re-read the values using the function getCellString and thus use the xls file, for example, for some calculations.

Example - Director
global xls
xls.setActiveSheet(1)
xls.setCellString(2, 10, "XTRA")

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
CallObject(xls; "setCellString"; 2; 10; "XTRA")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

string=getCellUTF8String(col:integer, row:integer)
The functions loads the contents of the cell in the xls file, whose format is UNICODE. It is returned as a value of the UTF-8 string type.

Parametres
Col and row are coordinates of the cell, whose contents we want to read. Col is a column coordinate and row is a row coordinate. The values range from firstCol and lastCol, or firstRow and lastRow.

Example - Director
global xls
xls.setActiveSheet(1)
val=xls.getCellUTF8String(2, 10)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
val:=CallObject(xls; "getCellUTF8String"; 2; 10)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=setCellUTF8String(col:integer, row:integer, val: string)
The function saves a value of the UTF-8 string. type to the the cell in the xls document. When saving in Excel, the values are automatically reconverted to the UNICODE format.

Parametres
Col and row are coordinates of the cell, that we want to save the string value to. Col is a coordinate of column and row is a coordinate of row. The values range from firstCol to lastCol, respectively from firstRow to lastRow. Type of val is unicode string and insert a text chain, that we save to a cell.

Note
If you want to save the UTF-8 format to the xls file in the same shape use the function SetCellString.

Example - Director
global xls
xls.setActiveSheet(1)
xls.setCellUTF8String(2, 10, "XTRA")

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
CallObject(xls; "setCellUTF8String"; 2; 10; "XTRA")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=getCellAnsiString(col:integer, row:integer, codePage: integer)
The function loads the contents of the cell in the xls file, whose format is UNICODE. It is returned as a value of the ANSI string type.

Parametres
Col and row are coordinates of the cell, whose contents we want to read. The parameter codePage represents the code page to be used to convert the UNICODE from. In the UNICODE text, only signs included in the appropriate page code can be used. If any other signs are used, they will replaced by question marks.

Example - Director
global xls
xls.setActiveSheet(1)
val=xls.getCellAnsiString(2, 10, 1251)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
val:=CallObject(xls; "getCellAnsiString"; 2; 10; 1251)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

double=getCellDouble(col:integer, row:integer)
The function reads contents of a cell in xls format and gives it back in string double.

Parametres
Col and row are coordinates of the cell, whose contents we want to read. Col is a column coordinate and row is a row coordinate. The values range from firstCol and lastCol, or firstRow and lastRow.

Example - Director
global xls
xls.setActiveSheet(1)
val=xls.getCellDouble(2, 10)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
val:=CallObject(xls; "getCellDouble"; 2; 10)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=setCellDouble(col:integer, row:integer, val: double)
The function saves the content in the double format to a cell in xls document.

Parametres
Col and row are coordinates of the cell, that we want to save the string value to. Col is a coordinate of column and row is a coordinate of row. The values range from firstCol to lastCol, respectively from firstRow to lastRow. Type of val is double and insert a value, that we save to a cell.

Example - Director
global xls
xls.setActiveSheet(1)
xls.setCellDouble(2, 10, 27.102)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
CallObject(xls; "setCellDouble"; 2; 10; 27.102)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

integer=getCellInteger(col:integer, row:integer)
The function reads contents of a cell in xls format and gives it back in integer format.

Parametres
Col and row are coordinates of the cell, whose contents we want to read. Col is a column coordinate and row is a row coordinate. The values range from firstCol and lastCol, or firstRow and lastRow.

Example - Director
global xls
xls.setActiveSheet(1)
val=xls.getCellInteger(2, 10)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
val:=CallObject(xls; "getCellInteger"; 2; 10)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=setCellInteger(col:integer, row:integer, val: integer)
The function saves the content in the integer format to a cell in xls document.

Parametres
Col and row are coordinates of the cell, that we want to save the string value to. Col is a coordinate of column and row is a coordinate of row. The values range from firstCol to lastCol, respectively from firstRow to lastRow. Type of val is integer and insert a value, that we save to a cell.

Example - Director
global xls
xls.setActiveSheet(1)
xls.setCellInteger(2, 10, 27)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
CallObject(xls; "setCellInteger"; 2; 10; 27)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=getCellBoolean(col:integer, row:integer)
The function reads contents of a cell in xls format and gives it back in boolean format.

Parametres
Col and row are coordinates of the cell, whose contents we want to read. Col is a column coordinate and row is a row coordinate. The values range from firstCol and lastCol, or firstRow and lastRow.

Example - Director
global xls
xls.setActiveSheet(1)
val=xls.getCellBoolean(2, 10)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
val:=CallObject(xls; "getCellBoolean"; 2; 10)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=setCellBoolean(col:integer, row:integer, val: boolean)
The function saves the content in the boolean format to a cell in xls document.

Parametres
Col and row are coordinates of the cell, that we want to save the string value to. Col is a coordinate of column and row is a coordinate of row. The values range from firstCol to lastCol, respectively from firstRow to lastRow. Type of val is boolean and insert a value, that we save to a cell.

Example - Director
global xls
xls.setActiveSheet(1)
xls.setCellBoolean(2, 10, false)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
CallObject(xls; "setCellBoolean"; 2; 10; false)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

propertyList=getCellDateTime(col:integer, row:integer)
The function loads the contents of the cell in xls document, whose format is DateTime, and it returns it in Abstract Data Type format, for example [#year:2002, #month:2, #day:2, #hour:8, #minute:27, #second:42].

Parametres
Col and row are coordinates of the cell, whose contents we want to read. Col is a column coordinate and row is a row coordinate. The values range from firstCol and lastCol, or firstRow and lastRow.

Example - Director
global xls
xls.setActiveSheet(1)
val=xls.getCellDateTime(2, 10)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
val:=CallObject(xls; "getCellDateTime"; 2; 10)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=setCellDateTime(col:integer, row:integer, val:propertyList)
The function saves DateTime value to a cell of xls document.The DateTime value is in Abstract Data Type format,
for example [#year:2002, #month:2, #day:2, #hour:8, #minute:27, #second:42].

Parametres
Col and row are coordinates of the cell, that we want to save the DateTime value to. Col is a coordinate of column and row is a coordinate of row. The values range from firstCol to lastCol, respectively from firstRow to lastRow.
Type of val is propertyList and we insert it in the Abstract Data Type format.


Example - Director
global xls
xls.setActiveSheet(1)
val=[#year:2002, #month:2, #day:2, #hour:8, #minute:27, #second:42]
xls.setCellDateTime(2, 10, val)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
CallObject(xls; "setCellDateTime"; 2; 10; val)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=setCellFormula(col:integer, row:integer, formuleStr: string)
The function saves the calculation formula in xls document.

Parametres
Col and row are coordinates of the cell, whose contents we want to read. Col is a column coordinate and row is a row coordinate. The values range from firstCol and lastCol, or firstRow and lastRow. FormuleStr is of the string type and we insert here our own calculation formula that we want to be saved in a cell of the xls document.

Example - Director
global xls
xls.setActiveSheet(1)
xls.setCellFormula(2, 10,, "SUM(C1:C4)")

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
CallObject(xls; "setCellFormula"; 2; 10; , "SUM(C1:C4)")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

integer=getCellIntegerFormula(col:integer, row:integer)
The function calculates the formula saved in the cell and it returns the result in the integer format.

Parametres
Col and row are coordinates of the cell, whose contents we want to read. Col is a column coordinate and row is a row coordinate. The values range from firstCol and lastCol, or firstRow and lastRow.

Example - Director
global xls
xls.setActiveSheet(1)
val=xls.getCellIntegerFormula(2, 10)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
val:=CallObject(xls; "getCellIntegerFormula"; 2; 10)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

double=getCellDoubleFormula(col:integer, row:integer)
The function calculates the formula saved in the cell and it returns the result in the double format.

Parametres
Col and row are coordinates of the cell, whose contents we want to read. Col is a column coordinate and row is a row coordinate. The values range from firstCol and lastCol, or firstRow and lastRow.

Example - Director
global xls
xls.setActiveSheet(1)
val=xls.getCellDoubleFormula(2, 10)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
val:=CallObject(xls; "getCellDoubleFormula"; 2; 10)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

string=getCellStringFormula(col:integer, row:integer)
The function calculates the formula saved in the cell and it returns the result in the string format.

Parametres
Col and row are coordinates of the cell, whose contents we want to read. Col is a column coordinate and row is a row coordinate. The values range from firstCol and lastCol, or firstRow and lastRow.

Example - Director
global xls
xls.setActiveSheet(1)
val=xls.getCellStringFormula(2, 10)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
val:=CallObject(xls; "getCellStringFormula"; 2; 10)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=getCellBooleanFormula(col:integer, row:integer)
The function calculates the formula saved in the cell and it returns the result in the boolean format.

Parametres
Col and row are coordinates of the cell, whose contents we want to read. Col is a column coordinate and row is a row coordinate. The values range from firstCol and lastCol, or firstRow and lastRow.

Example - Director
global xls
xls.setActiveSheet(1)
val=xls.getCellBooleanFormula(2, 10)

Example - Authorware
CallObject(xls; "setActiveSheet" ; 1)
val:=CallObject(xls; "getCellBooleanFormula"; 2; 10)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=insertRow(row:integer, rowCount:integer)
The function adds rows to the actual sheet in the xls document.

Parametres
Row is a number of the row above which we want to add new rows. RowCount is a number of new rows that we want to add.

Example - Director
global xls
xls.insertRow(27,5)

Example - Authorware
CallObject(xls; "insertRow" ; 27; 5)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=deleteRow(row1:integer, row2:integer)
The function deletes rows in the actual sheet in the xls document.

Parametres
Row1 is number of the row that we want to start deleting with. Row2 is number of the row that we want to finish deleting with. Row1<=row2 is valid. If we delete the rows all the rows below will be shifted up.

Example - Director
global xls
xls.deleteRow(4,7)

Example - Authorware
CallObject(xls; "deleteRow" ; 4; 7)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=insertCol(col:integer, colCount:integer)
The function adds empty columns to the actual sheet in the xls document.

Parametres
Col is a number of the column front which we want to add new columns. ColCount is a number of new columns that we want to add.

Example - Director
global xls
xls.insertCol(2,10)

Example - Authorware
CallObject(xls; "insertCol" ; 2; 10)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=deleteCol(col1:integer, col2:integer)
The function deletes columns in the actual sheet in the xls document.

Parametres
Col1 is a number of the column that we want to start deleting with. Col2 is a number of the column that we want to finish deleting with. Col1<=col2 is valid. If we delete the columns all the columns on the right will be shifted left.

Example - Director
global xls
xls.deleteCol(7,9)

Example - Authorware
CallObject(xls; "deleteCol" ; 7; 9)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

Description of events
-----------------------------------------------------------------------------------------------------------------------------------------------------------
onDataHttp progress
This event (callback function) is invoked at the moment when the user starts to download the xls file from the http. It monitores the downloading of the xls file. The parameter progress represents how many percents have already been downloaded. The values ranges from 0 to 100.

Example - Director
on onDataHttp progress
     put progress
end