Ecs XTRA pluginXLS for XML Socket Multiuser Server - eClever  

Download

pluginXLS (400 kB)

Description
The library pluginXLS is a tool to work with Microsoft Excel files in XML Socket Multiuser Server - eClever. You don’t have to have installed Microsoft Excel, Microsoft Jet Provider nor any other programs on your computer. The XTRA pluginXLS works autonomously and it will enable you to work with remote XLS files in products such as Flash, Flex, Director, Authorware etc.

History

04.08.2007		Version 1.2.0		The work with file parameter in pluginXLS.ecs.config file was changed.
07.06.2007		Version 1.1.0		File pluginXLS.config was rename to pluginXLS.ecs.config
03.04.2007		Version 1.0.0		XTRA creation

Demo version
A fully-working demonstrative version is available. It will work for 2 minutes. Then you have to restart the XML Socket Multiuser Server - eClever.

Installation
1. You have to copy the files pluginXLS.ecs and pluginXLS.ecs.config to the folder XTRAS. This folder must be a part of the XML Socket Multiuser Serveru - eClever root.
2. In eClever.config in the section XTRAS you have to allow the use of pluginXLS.ecs, for example

<xtras>
     <xtra name="testXLS" file="pluginXLS.ecs"/>
</xtras>

3. In eClever.config in the section domain you have to allow the use of pluginXLS.ecs, for example

<domain name="demo1" password="pass1" xtras="testXLS" maxUsers="0" ...

4. You have to fill in the configuration file. The configuration file pluginXLS.ecs.config has the following shape

<xtra>
     <licence name="dmm" code="xls"/>
     <data file="d:\abc.xls">
           <read domains="domA#domB" rooms="roomA#roomB" nickNames="nameA#nameB"/>           
           <write domains="domC#domD" rooms="roomC#roomD" nickNames="nameC#nameD"/>
    </data>
</xtra>

Section license
If the right name and code are not inserted you can only use the XTRA during 2 minutes. After this time has elapsed the XTRA stops functioning.

Section Data
File is an xls file including path to it. If the full path to the xls file is not defined, for example c:\abc.xls, then it is considered to be the directory xtras.
Example:
For: file="abc.xls" the file abc.xls must be placed in the directory xtras.
For: file="test\abc.xls" the file abc.xls must be placed in the directory xtras\test.
 
In the section “read” and “write” you define who is going to have the right to use the file. You can assign the rights either on the level domain or room or nickname. You can assign them separately for reading and writing. Section “read” or “write” can always contain only one attribute from domains, rooms or nickname. You have to insert the domain, room and nickname separated by the sign #. Their number is not limited.

Note: If all attributes are defined in pluginXLS.ecs.config in “read” and “write” they will be processed in this order: domains, rooms or nickname, it means that only the attribute domains will be relevant. If only attributes rooms and nickname are defined only the first one will be relevant.

Example 1
If you want to allow use of the XTRA only for the users who want to read and who are logged in the domain domA and domB then the section “read” will be defined in this shape

<read domains="domA#domB">

Example 2
If you want to allow use of the XTRA only for the users who want to write and who are logged in the domain domC and domD then the section “write” will be defined in this shape

<write rooms="roomC#roomD">

Example 3
If you want to allow use of the XTRA only for the users who want to read and write and who are logged in using the names nameA and nameB then the sections “read” and “write” will be defined in this shape

<read nickNames="nameA#nameB"/>
<write nickNames="nameA#nameB"/>

Note: If you want to use more xls files in XML Socket Multiuser Server - eClever you just have to create copies of pluginXLS.ecs and pluginXLS.ecs.config. Name them for example pluginXLS_2.ecs and pluginXLS_2.ecs.config (the first part must be identical). In pluginXLS_2.ecs.config define another xls file and you can start working. Of course you have to allow the new XTRA in eClever.config and in the sections  socket-server/xtras and domain.

How the XTRA pluginXLS works?
a) The client has to send an XML request to the XML Socket Multiuser Server - eClever in the following shape

<protocol>
     <xtra sid="10">
           <data name="testXLS" function="functionA">
               <request> ..... </request>
           </data>
     </xtra>
</protocol>

where “name” represents name of the XTRA, defined in eClever.config in the section socket-server/xtras. In the attribute function you have to insert name of the function you want to call. In the section request insert the required parameters. These parameters differ from one function to another so that’ s why they will be explained separately going along with every function.

b) The XML Socket Multiuser Server - eClever will reply to client by a message having this shape

<protocol>
     <response action="xtra" errorCode="0" sid="10"/>
          <data name="testXLS" function="functionA">
               <result state="ok"> ..... <result>
           </data>
</protocol>

The required values are returned in the section result.

In case an error occurred during work with the XTRA the client will receive a reply in the following shape

<protocol>
     <response action="xtra" errorCode="0" sid="10"/>
          <data name="testXLS" function="functionA">
                <result state="error"> <error>Error in xml</error></result>
         </data>
</protocol>

Note: errorCode="0" means that the XML Socket Multiuser Server - eClever worked with the XTRA pluginXLS.ecs without any error but status=”error” means that an internal error occurred in pluginXLS.ecs.

Reading of data from an xls file – getCellValueRef

XML request sent by the client to the Server

<protocol>
     <xtra sid="10">
          <data name="testXLS" function="getCellValueRef">
               <request>
                     <xls sheet="1" cell="A1"/>
                     <xls sheet="1" cell="B8"/>
               </request>
          </data>
     </xtra>
</protocol>

Sheet represents a number of sheet in the xls file, we want to work with.
Cell is the cell that we want to read values from.

XML reply to the client

<protocol>
     <response action="xtra" errorCode="0" sid="10"/>
     <data name="testXLS" function="getCellValueRef">
           <result state="ok">
                <xls sheet="1" cell="A1"><![CDATA[value1]]></xls>
                <xls sheet="1" cell="B8"><![CDATA[value2]]></xls>
           <result>
     </data>
</protocol>