Manual Java 546u8r

MicroCalc J2ME Spreadsheet UserGuide

by Mikhail Zemljanukha

Table of Contents1. Introduction ...........................................................................................................................

What is MicroCalc? ............................................................................................................ 1Main features .................................................................................................................... 1

2. Installation ............................................................................................................................Downloading MicroCalc ..................................................................................................... 2Installing .jar file ................................................................................................................ 2

3. Using MicroCalc ....................................................................................................................Areas of screen .................................................................................................................. 3Navigation mode ................................................................................................................ 3Formula edit screen ............................................................................................................ 4Data types and constant values .............................................................................................. 4Formulas .......................................................................................................................... 5Numeric mode ................................................................................................................... 5Formula view mode ............................................................................................................ 5Pointer support .................................................................................................................. 6

4. Networking ...........................................................................................................................Sync midlet ....................................................................................................................... 7Server side tools ................................................................................................................ 9MS Excel add-on ............................................................................................................... 10

A. GOLD key functions ..............................................................................................................B. Supported handsets .................................................................................................................C. Menu structure .......................................................................................................................D. Data types ............................................................................................................................E. Supported operators and functions .............................................................................................F. BNF grammar of expressions ....................................................................................................G. Limited math support ..............................................................................................................H. Acknowledgements and References ...........................................................................................

iv

Chapter 1. IntroductionWhat is MicroCalc?

MicroCalc is a spreadsheet implemented in J2ME (Java 2 Mobile Edition), this version of Java language is used ondevices with small hardware footprint, such as mobile phones and PDAs.

Main featuresThe short list of MicroCalc features is:

Decimal math support

Trigonometric functions

Datetime data type

Data export into SYLK format

Server-side sheets storage

1

Chapter 2. InstallationMicroCalc is a standard MIDP 1.0 compatible J2ME application (midlet), it should run on any j2me compatiblehandset.

Downloading MicroCalcMicroCalc can be freely downloaded from www.wapindustrial.com. It is distributed in several packages, you maychoose one most suited for your needs:

1. Basic package, includes minimal set of features. It doesn't include SYNC midlet. This package is suitable forhandsets without network access, or when you do not have enough space to install full MicroCalc package.

2. Full package including SYNC midlet. Use it if you want to synchronize data with the server via network(GRPS connection is recommended).

3. MicroCalc Lite, it is the same as the Basic package but its size is even less, to keep it within 30k. This packageis specially designed for Nokia 6310 phones which cannot install midlets larger than 30k.

4. Package for Siemens phones, includes SYLK midlet to export sheets into Siemens

??? SYNC midlet is used to synchronize sheet data between mobile device and network server, you need it to passdata to PC where you can edit sheets with desktop spreadsheet software such as MS Excel.

??? SYLK midlet is used to export sheet data in SYLK format on Siemens phones (it uses Siemens J2MEextensions, and will not work on other handsets).

We also distribute special MicroCalc packages that don't include MathFP library, when its use may infringe thelicence agreement. Differences in math between them are listed in appendix.

Installing .jar fileMidlet installation is device-depended process, refer the documentation on your own phone. In general, there aretwo possible ways to install - via network (OTA, Over The Air) from a server, or directly from PC via cable, IR orbluetooth.

To install via OTA point your WAP browser in the phone to http://wapindustrial.com/microcalc/download.wml andselect package to install. You can select either .jad file (for example microcalc.jad) or .jar if .jad file does not work.The phone will prompt you to download and install the midlet. If you have got problems with installing MicroCalcfrom that page - try to download it from http://wap.midletcentral.com [registration required], or fromhttp://wap.jams.it. These sites are more compatible with operators' wap gates, you should use them if download fromwapindustrial.com site fails.

Many devices allow installing from PC via cable, IR or a bluetooth connection. You may have to use a specialinstallation program (on Motorola phones, for instance), or just sending .jar file to device via IR or bluetooth may do(on Nokia 7650). Consult the documentation on your phone for details.After installing you will see MicroCalc icon in applications list. Its exact location is also device-depended thing - onSiemens phones there is 'java' item in menu, on Nokia 7650 (and all Series 60 devices) java applications are locatedin 'Tools' / 'Applications' subfolder.

2

Chapter 3. Using MicroCalcMicroCalc interface is similar to the desktop spreadsheet software such as MS Excel, with certain limitationsregarding small screen size of handheld devices and general limitations in available resources, such as heap memorysize (this limits the amount of data that can be placed on a sheet), and application code size.

Areas of screenHere goes a screenshot of MicroCalc running in Motorola iDEN i95cl emulator. The MicroCalc screen consists offollowing parts:

row headers, located at the left side of screen, shows row numbers

column headers, located at the top of screen, show column names

formula bar, normally it's not shown but in some screen modes it replaces the column header, usually displayscontent of the current cell

the cursor, current selected cell, is drawn in reverse color (a black cell with white text in it)

Navigation modeThis is a standard mode used to review values in sheet cells, and to scroll the visible part of sheet (the window) tothe desired area of the sheet. To move current selection use keys:

LEFT arrow (when arrows are supported by particular device), or 4 button - move selection left.RIGHT arrow, or 6 button - move selection right.

UP arrow, or 2 button - move selection up.

DOWN arrow, or 8 button - move selection down.

3

Some devices don't have arrow buttons (usually represented by a joystick) or pointers (sticks), so we emulate arrowswith numeric buttons, to allow using MicroCalc on such handsets. If you want to use numeric buttons to inputvalues into cells you can switch to numeric mode (described below).If your device supports pointer you can just click on a cell to select it, the second click will open the formula editscreen.

If you go out of the screen MicroCalc will scroll the window to keep the cursor within.

After selecting a cell you can enter values in it, by switching to numeric mode or entering the formula edit screen.

Formula edit screenTo enter this screen you can press OK button (also often referred as FIRE in games). Usually it's the second softkeybutton after the menu one. This screen is also available via menu Cell.../Edit.

When formula edit screen opens for an empty cell it automatically inserts '=' character which must be used beforeexpressions, if you want to enter a constant you are to delete '=' and then may type constant. To simplify input ofdecimals there is a numeric mode, it's more convenient in use then the formula screen.

The formula screen allows entering any character supported by your device, even national characters (non-English).To switch between codepages, lower/upper caps or number/text modes (including T9) refer the documentation onyour device/ MicroCalc uses standard input functionality of a particular device, so it's a device-depended thing.

In formula edit screen you can enter both constant values and formulas. Formulas are usually used to makedependencies between cells, when a value in a cell depends on other cell.

For example let the cell with address [A1] (from here further we give a cell address in square brackets) have thevalue 5. To enter it select the cell [A1] in navigation mode, then enter formula edit screen, delete '=' letter and type5. Select OK button (on softkey or in menu).Now select the cell [A2] and type formula '=A1+3', then select OK button. MicroCalc calculates the formula andshows 8 in the [A2] cell. Now each time the value in [A1] changes [A2] is also recalculated. In general [A1] mayalso have a formula, and so on.

So we see formulas are entered with the '=' letter before expressions, in contrary with constant values that may notbegin with '=' (still if you want to display in a cell text starting with '=' you can use string constant, see below)

Data types and constant valuesCells may consist of not only decimal values but dates as well, text strings (usually used as comments to the numericvalues and formulas) and some other not often used data types. Here go few examples of constants:

1234.456 - a decimal constant, dot is used as decimal separator.

to enter a text just type it (in formula edit mode of course), for example "this is a string" (without quotes). If youwant to enter a text that may be considered as other data type as well, you need to put ' (apostrophe) before thetext, for example '1234.5678. Note that cells with text values are left aligned, in contrary with decimals.

11/2/2003 - a date in dd/mm/yyyy format

There also are 2 other datatypes, long integer and boolean. Refer the appendix for more info.

Please note you can change format of displayed values in menu Cell.../Format... There are some options for setting

Using MicroCalc

4

number of digits after the dot for decimals, and datetime options, such as day/month order and date separator.

If width of a decimal exceed the column width MicroCalc displays ##### instead of cutting the string, as it is donefor string data type. To fix it you need to increase the column width (menu Column.../Width), or to reduce numberof displayed digits after the dot (menu Cell../Format.../Number). When entering decimal value into a cell thecolumn width is fitted to result automatically.

FormulasCalculated formulas start with the '=' letter. You can use both regular math operators + - / * and function calls, forexample: =2*3/5+3.2

Example: [A1]:=pi()/4 (this denotes a formula entered in cell [A1]Example: [A2]:=sin(A1)^sin(A1)+cos(A1)^cos(A1)Refer the appendix for detailed list of functions you can use in formulas.

Numeric modeThere is a special mode for quick input of numeric values (decimals) into cells without going to formula edit screen.By pressing # key (POUND) (it is also referred as GOLD key in this documentation) and 0 key you can enter thismode. The "NUM:" prompt appears in the formula bar, and now numeric buttons can be used to enter decimalvalues. Use * (STAR) to enter the decimal dot, and # (pound) to finish input. Negative values can be entered bydouble pressing the * key.

Formula view modeBy pressing GOLD then 9 keys you can enter formula view mode, in which status bar shows the cell formulas. Youcan still navigate the sheet by arrows keys, as in the navigation mode.

Press GOLD-9 again to switch off this mode.

Using MicroCalc

5

Pointer supportSome devices (such as SonyEricsson P800 and Motorola A008) provide pointer support. You can click on a cell toselect it, the second click will open the formula edit screen.

To scroll the window select a cell on the border, row and column headers can be used to scroll to up/left as well.

Using MicroCalc

6

Chapter 4. NetworkingThe main use of MicroCalc is standalone editing of spreadsheet data on a handset device. Still there is someadditional functionality you can get if using networking capabilities of the software, particularly you can import/export data into handset. To perform this we have to exchange data via a server on network which is used as abroker between your desktop PC (with Excel spreadsheet, for instance), and MicroCalc software in your phone. Thisis done because current implementation of java in mobile phones doesn't allow to exchange data from a handsetapplication with external sources, except network ones using HTTP protocol. This is a general limitation of almostall J2ME MIDP 1.0 based phones existing on the market.

So we provide MicroCalc users with accounts on our network server at wapindustrial.com [http://wapindustrial.com]to use for:

backuping data on network server from handset device. This may be useful to save space on hadsets with littlepersistent memory storage

moving spreadsheet data into new versions of MicroCalc. On many devices you lose application data whenreinstalling it (to upgrade MicroCalc version in our case), so uploading data from old version to server thenrestoring them back in new one just saves your data between MicroCalc versions. Moreover, since data format innew version may be change, it can be converted on server side .

to export data from handset to desktop spreadsheet in SYLK format (only it is supported at the moment) to import data from an external spreadsheet in XML format. At the moment MS Excel is supported with special

add-on.

To access your data on the network server you can use following software/interfaces:

Synchronization midlet called Sync from MicroCalc suite installed on your phone, to upload and download datafrom handset to server

Web interface to manage your sheets on the server site using a web browser such as Internet Explorer.

WAP interface to manage your sheets on the site using a wap browser built in handset

Web interface to upload data to server in XML format

MS Excel add-on software, to prepare XML files from Excel sheets

Sync midletSync midlet is a part of MicroCalc suite. We have implemented it as a standalone application and haven't included itinto the basic package to reduce its size, since it may prevent installing MicroCalc on constraint devices, and whenusers don't need networking at all (on non-GPRS devices it is usually quite expensive to make data calls, forexample).After Sync midlet starts you have following choices:

7

If you select the Update command it will retrieve the list of sheets stored on server, to compare their names andversion numbers with the sheets in handset storage, to determine which sheets are to be uploaded or downloaded.When downloading catalog midlet provides the account info - login and password, to access the user's private dataon the server. If you have registered at the wapindustrial site and got an account, you can type it via menu commandSync Options. Initially the 'anonymous' login with empty password are used.

Sync midlet keeps a copy of server catalog info locally, and this allows you to skip downloading the catalog nexttime, if you are sure nothing has changed on the server or you are not interested in the changes. Still if you uploadedfiles from other sources than this handset, say from desktop PC or other mobile phone, you would need to refreshthe catalog from the server.

On next step Sync will build the list of files to be uploaded/downloaded to/from the server. Newly created sheetsand updated sheets are included into the list:

Files to upload start with -> characters, to download start with

After you selected sheets to synchronize and started the process midlet shows the log window until it finishessynchronization:

The synchronization process may take long time depending on network latencity and amount of data beingtransferred. You may stop synchronization by pressing Cancel button. When process finishes the button captionchanges to OK. Pressing it returns you to the start screen, where you can use Exit command in menu to quit thewhole midlet.

Now if you launch MicroCalc spreadsheet midlet you can see the downloaded files. The files uploaded duringsynchronization can be accessed on the server site, it is descibed in the next section.

Server side toolsOn the wapindustrial site [http://www.wapindustrial.com/microcalc/catalog/do.asp] you can manage sheets in yourpersonal folder. After logging in you will see the list of sheets stored on the server, and can view content of a sheet,and even formula in a cell. The software doesn't support editing sheet data in browser window yet, except the DeleteSheet operation.

On the sheets page you can upload a new sheet to the storage on server, from an XML text file.

There are following options available in web interface:

Registration - you need to select login name, password and to specify the email address where the registrationinformation will be sent to. Email address isn't a necessary field, it may be empty

Networking

9

Logging in/out.

Viewing list of sheets being stored on server side.

Viewing content of whole sheet, in tabular form

Viewing content of a cell, including formula info

Deleting sheet

Viewing content of sheet in SYLK format - this is used to transfer sheets from handset to external spreadsheetsoftware such as MS Excel or OpenOffice. To open SYLK file in MS Excel you will need to previously savepage on hard disk (using "save target as" command in browser) and then you can open it in Excel.

Uploading sheet in XML format - this is used to transfer sheets created in MS Excel into handset. The tool toprepare XML files is described below.

MS Excel add-onAs mentioned above, you can transfer a sheet from MS Excel to the server (and then to handset) uploading it asXML file. To build the file in MS Excel environment we developed an Excel add-on called mc4me.xla, it can bedownloaded from our site. To install it open Excel menu "Tools/Add-ons" and point to the .xla file.

After the add-on installed you can press Ctrl-Shift-M to open MicroCalc export screen. You need to enter full pathwhere the generated XML file will be stored. This path is saved in the source file so you won't need to retype it nexttime. Only current active sheet can be exported, the range of cells to export is automatically calculated from usedrange of the sheet, the name of sheet being saved is also taken after the name of the source sheet.

Networking

10

Only sheets with formulas supported by MicroCalc can be exported, but the export add-on doesn't check it, and anerror will occur at a later stage when the sheet is uploaded to the server. This add-on is in a beta version, you mayencounter problems since it hasn't been thoroughly tested.

Networking

11

Appendix A. GOLD key functionsWith pressing the # (pound, also called GOLD in this manual) button you can access following operations:

GOLD-0 (press # key then 0 key) enters numeric mode, to finish it press GOLD again. GOLD-9 enters formula view mode, to finish it press GOLD-9 again.

GOLD-1 copies the selected cell.

GOLD-2 pastes copied cell.

GOLD-3 scrolls the window up.

GOLD-6 scrolls the window down.

GOLD-4 scrolls the window left.

GOLD-5 scrolls the window right.

12

Appendix B. Supported handsetsMicroCalc is fully compatible with MIDP 1.0 and should work without any problem on any J2ME enabled device.Particularly it was tested on:

SonyEricsson P800

Motorola iDEN i50sx

Motorola Accompli 008/6288

Motorola Accompli 388

Nokia 6310i

Nokia 3410

Nokia 3510i

Nokia 7650

Nokia 7210

Nokia 6100

Nokia 6610

Siemens SL45i

Siemens M50

Siemens MT50

Siemens S55

We also tested MicroCalc in Motorola iDEN emulator of i95cl, i90c, i85s phones. MicroCalc was tested with PalmOS MIDP as well.

A competent list of J2ME enabled phones can be found on Sun's site at http://wireless.java.sun.com/device

13

Appendix C. Menu structureAfter launching MicroCalc you see the start menu:

Load sheet - shows the list of sheets stored in persistent memory of device, to select one to load.

New sheet - shows new sheet screen, to set title and size of newly created sheet.

About - shows short instruction and version info.

Exit - quits the program.

The work menu is:

Cell... - Cell operation submenu

Edit - enters Formula edit screen. If the cell was empty it automatically inserts '=' letter in edit box

14

Clear - clears selected cell content

Copy - copies selected cell to clipboard

Paste - insert content of copied cell into selected cell. The relative references in formula will be corrected, ifany.

Format... - submenu for format options

Number - enters screen of options to format decimal values, allows to change number of digits after thedot

Date/Time - screen for date/time format options, such as date separator, day/month order, time partvisibility

Clear - clears format of selected cell

Column... - column operations submenu

Width - prompts for width of selected cell column

Insert - insert column screen, you can specify number of columns to insert before corrent column

Delete - delete column screen, number of specified columns will be deleted.

Row... - row operations submenu

Insert - insert row screen, you may specify number of rows to insert before current row. You may also copycontent from the rows above/below into newly created rows.

Delete - screen to specify how many rows to delete starting from the current row.

Sheet... - sheet operations submenu

New - create new sheet screen

Save - prompts for the name of sheet to save data to. Using this screen you may copy sheet into file with newname (it other word, it allows you to copy sheet). This operation doesn't control if a sheet with the samename exists.

Load - shows list of the sheets being stored in device memory, to select one to load. If the current sheet hasbeen modified since last save this operation displays a message and allows to cancel. Note that afterdismissing changes you will have to perform the operation again.

In this screen you also can delete sheets from the list (and device memory as well). Delete - prompts to delete current sheet. The sheet will be removed from the persistent memory of device.

Resize - prompts for new size of the sheet. New columns and rows will be added or removed.

Menu structure

15

About - shows short instruction and version info.

Exit - quits the program.

Suspension points ... after the name of menu item show that it has subitems, so it is a submenu.

To select a menu item you can press SELECT button (usually it is the most used handset button). There are alsoadditional commands to navigate in menu, they are OK, Back and Cancel commands. The behavior of OK is thesame as SELECT button, it selects a menu item. Back moves up in menu hierarchy, to the parent menu you camefrom. If you already are in the top menu it brings you back top the sheet. You also can use Cancel button to leavemenu from any level of hierarchy.

The command assignment to buttons depends on particular device, they may be assigned to dedicated softbuttons orbe placed in additional menu, called "Options" or "Menu".

Menu structure

16

Appendix D. Data typesMicroCalc can operate with the following data types:

long integer, values range from -9223372036854775808 to 9223372036854775807. Values with this datatypeare displayed with the 'L' letter after the number, and this letter must be used to enter long integer constant inexpressions as well, otherwise it is considered as a float point constant.

Constant example: 123L

Expression example: =34L+5L

decimal number, 64 bits for the fraction part and 16 bits for the exponent part. This data type is used by defaultfor numeric values.

Constant example: 1234.5678

Expression example: =1234.5678/2.3+8-(6.1+3)You can set number of digits displayed after the dot in a cell via menu Cell.../Format.../Number

String constant

Constant example: 'this is a string (with a quote at the beginning, or without, if it's not a decimal)Expression example: "string number " & 123+5 (concatenation with the result of math expression, result will be"string number 128")Cells with string values are left aligned, in contrary with decimal values that are right-aligned.

Boolean. This data type represents 2 possible values, TRUE and FALSE. It's mostly used in expressions wherelogical operations required, such as IF() function.Constant example: FALSE

Expression example: =if(A1

Appendix E. Supported operators andfunctions

operators: () + - / *, ^ (power - only in MicroCalc version with MathFP library), & (string concatenation)Example: =124+5/4*(7+2)

math functions: SIN,COS,TAN,COT, ASIN,ACOS,ATAN,ATAN2, SQRT,LN,ABS,EXP,POW, SUMExample: =sin(pi()/2)If a function has got several arguments they are separated with comma, example: =pow(2,3)Note: COT, LN, EXP, POW function are available only in MicroCalc package with MathFP library.

logical functions: IF,AND,OR

Example: =if(A1>0,A1,-A1) (returns absolute value of cell [A1], the same as =abs(A1)) constants PI(), E() (don't forget brackets - they are implemented as functions without arguments). Note: E()

constant is available only with MathFP library.

18

ADDRESS :=COLUMN ROW |COLUMN ROW ':' COLUMN ROW;

COLUMN :=LETTER |LETTER LETTER;

ROW := SHORT_NUMBER

FUNCTION :=TEXT '(' ARGUMENTS ')';

ARGUMENTS :=NOTHING |COMPARE |COMPARE ',' ARGUMENTS;

BNF grammar of expressions

20

Appendix G. Limited math supportFreeware version of MicroCalc uses 3rd party developed MathFP library (from www.jScience.com) to perform mathcalculations (since J2ME itself doesn't support floating point math). For cases when using of MathFP may infringeMathFP licence (free only for non-commercial apps) we also distribute MicroCalc packages without it, with our ownimplementation of floating point math. We plan to license MathFP later.

There are some differences between these math implementations, shortly listed below:

MathFP uses fixed point math, 40 bits for the integer part and 24 bits for the fraction. Our implementationoperates with floating point values, with 64 bits for the fraction part and 16bits for exponent. So MathFPproduces less precise results but works faster.

Our implementation doesn't support exp(), pow() and ln() functions. The E() constant is absent too.

21

Appendix H. Acknowledgements andReferences

We would like to say thanks to people for:

the MathFP java library from jScience Technologies [http://www.jscience.com] used in non-commercial versionof MicroCalc. This library implements fixed point math since the J2ME itself doesn't support float point math.

the MicroEmulator midlet emulator, an opensource java project from SourceForge[http://microemulator.sourceforge.net]. We use it to demonstrate MicroCalc midlet in applet in browser windowon our site.

the jUnit java testing tool, an opensource project from SourceForge [http://junit.sourceforge.net]. We use it toperform tests suites while modifying the MicroCalc code.

Sun One Studio (aka Forte) for Java, J2ME edition, from Sun Microsystems site [http://forte.sun.com/], forproviding an excellent Java IDE, and of course, for Java technology itself, including J2ME SDK.

Apache Ant opensource project from Apache site [http://ant.apache.org], we use it to build MicroCalc packages Apache Tomcat, an opensource project from Apache site [http://jakarta.apache.org/tomcat/], we use this JSP

servlet engine on server side (MicroCalc server engine). DocBook XML based markup language for text documents. This manual is written in docbook format. We use

XSL stylesheets from docbook.sourceforge.net [http://docbook.sourceforge.net/] to transform it to FO andHTML formats, and then to PDF file using Apache FOP tools. We aren't good at these tools yet, so thedocumentation layout isn't good - sorry.

the jRefactory java refactoring tool, an opensource project from SourceForge [http://jrefactory.sourceforge.net]. the OpenOffice, an opensource project from www.openoffice.org [http://www.openoffice.org/], for providing

open XML interfaces for office (spreadsheets as well) software, particularly XMerge[http://xml.openoffice.org/xmerge/] project to synchronize with handheld devices.

Rational Rose UML modeling tool from IBM [http://www.rational.org/]

the Uncommon Lisp, an opensource lisp implementation in java language from Michael Bayne[http://www.go2net.com/internet/deep/1997/03/19/body.html], we plan to adopt it as MicroCalc script language.

Also we would like to mention a very good developers support from hardware manufactures, such as Nokia(Nokia J2ME SDK), Motorola (Motorola J2ME SDK, iDEN J2ME SDK) and Siemens (Siemens J2ME SDK).

These internet forums need to me mentioned as well: forum.nokia.com[http://discussion.forum.nokia.com/forum/] and http://forum.java.sun.com [http://forum.java.sun.com/] whichalways were (and are) great sources of java/j2me related information.

22

Manual Java 546u8r

Documents

Transcript of Manual Java 546u8r