BlackBerry JDE Version 3.6 Release Notes
PLEASE READ THE LEGAL NOTICES SET OUT AT THE END OF THIS DOCUMENT. This document provides information about the BlackBerry Java Development Environment version 3.6.

Contents

Changes in this release (refer to page 1) Known issues (refer to page 3) Additional information (refer to page 6)

Changes in this release

This section describes changes in the BlackBerry JDE version 3.6 since version 3.2.1.

API additions

The BlackBerry JDE version 3.6 includes the following new APIs: Package
net.rim.blackberry.api.mail net.rim.blackberry.api.mail.event net.rim.blackberry.api.menuitem

Description

The mail API enables applications to interact with the BlackBerry messages application to send, receive, and open email messages. The application menu item API enables applications to add menu items to BlackBerry applications, such as the address book, calendar, and messages. The PIM API enables applications to interact with BlackBerry personal information management (PIM) applications, including address book, tasks, and calendar.
net.rim.blackberry.api.pim

Package

net.rim.blackberry.api.options
The options API enables applications to add handheld option items to the handheld Options application. The cryptographic APIs provide data security capabilities, including data encryption and decryption, digital signatures, data authentication, and certificate management. The notifications API provides methods to trigger event notifications and respond to system-wide and application-specific events. The synchronization API enables applications to use the BlackBerry Desktop Software to back up and restore data, or synchronize data with a desktop application. New classes in this package provide functionality such as persistent data storage, interprocess communication (IPC), SMS, network communication using datagrams, and application management.
net.rim.device.api.crypto net.rim.device.api.crypto.*
net.rim.device.api.notification
net.rim.device.api.synchronization
net.rim.device.api.system

Tools enhancements

The following enhancements have been made to the BlackBerry JDE: Size limit for.cod files: There is no longer a size limit of 128 KB for.cod files. A single class still cannot exceed 128 KB (64 KB of code and 64 KB of data, such as images or other resources). A single resource cannot exceed 64 KB. Additional handheld support in simulator: The BlackBerry JDE includes.dll files for each released handheld type. To simulate a specific handheld model, in the IDE, on the Edit menu, click Preferences. Click the Simulator tab. Click the Advanced tab. In the Simulator Command line field, change the OS<version>.dll command to specify the type of handheld that you want to simulate: For BlackBerry 5800 Series of wireless handhelds, type OS5800.dll. For BlackBerry 6700 Series of wireless handhelds on GPRS networks, type OS6700.dll. For BlackBerry 6700 Series of wireless handhelds on CDMA networks, type OS6700.dll /wc. For BlackBerry 6500 Series of wireless handhelds, type OS6500.dll /wi.
Email Server Simulator: The BlackBerry JDE includes an email server simulator (ESS) that enables applications that use the BlackBerry Mail API to send and receive email between the handheld simulator and either a desktop email application, such as Microsoft Outlook Express, or POP3 and SMTP servers. The default PIN that is set in the ESS is incorrect. Change the PIN to 0x2100000A, which is the default PIN for the handheld simulator. Refer to the BlackBerry Developer Guide Volume 2 for more information. In this release, to send and receive email using the ESS, you must start the handheld simulator from the IDE. You cannot start the simulator using the Start menu short cut or using the run.bat file. If you start the handheld simulator from a command prompt, specify the /rport=0x4d4e parameter.
BlackBerry Java Development Environment Release notes
IDE: In the Preferences window, on the Simulator tab, you must create a new simulator profile before you can change basic or advanced options. To reset the simulator to its default parameters, from the Profile drop-down list, choose Default Simulator.

Fixed issues

The following issues have been fixed in BlackBerry JDE version 3.6. Issue #

T3755 T4462 T4483 T6870

The net.rim.device.api.ui.Keypad.map and setMap methods now handle lowercase letters correctly. The RichTextField.keyChar() method now works correctly. The Dialog.ask method now works correctly. When the javax.microedition.lcdui.ItemStateListener is invoked, the listener now provides a reference to items in a ChoiceGroup that have changed. Previously, the listener returned null. The net.rim.device.api.util.IntMultiMap default constructor no longer allows duplicate key-value mappings. The net.rim.device.api.util.IntMultiMap constructor now allows an intial size of 0. The default constructor for net.rim.device.api.ui.component.DateField now works correctly. The constructor for net.rim.device.api.ui.component.RadioButtonField now works correctly.

T7940 T8539 T8674

Known issues
The following known issues exist in BlackBerry JDE version 3.6. Issue #
The net.rim.device.api.ui.container.FlowFieldManager.nextFocus method returns -1 when scrolling vertically towards the first or last field. The net.rim.device.api.ui.component.EditField.isCursorPositionSet() method returns false if the cursor was set programmatically. The method returns true if the cursor was set by the user. The net.rim.device.api.component.DateField.setDate methods allow date values that are outside the valid range specified in the API documentation. The net.rim.device.api.ui.text.URLTextFilter methods allow the % and # characters.

T7528 T7529 T7942

The net.rim.device.api.ui.Manager.moveFocus method performs movements inconsistently.

Issue #

The net.rim.device.api.collection.util.UnsortedReadableList.setElements() method sets size to an incorrect value when an out-of-bounds count is passed to the method. For example, if setElements( Oject[] elements, -20 ) is invoked, invoking size() returns -20. Attempting to read any elements throwns an exception. The net.rim.device.api.system.Bitmap.createBitmapFromBytes method does not always throw an IllegalArgumentException as specified in the API documentation. If a negative length is provided in the length parameter, an ArrayIndexOutOfBoundsException is thrown. If a value of 0 is provided for the scale parameter, an ArithmeticException is thrown. The net.rim.device.api.ui.Screen.invalidate() method throws an IllegalStateException if it is not called from the event thread. As a workaround, the screen must first acquire the event lock or invoke invokeLater(). The appropriate AlertListener method, such AlertListener.buzzerdone(), is not invoked after an alert is completed. The net.rim.device.api.ui.text.IPTextFilter methods do not accept uppercase letters. The net.rim.device.api.synchronization.ConverterUtilities class does not provide a readShort method. In the simulator, the net.rim.device.api.ui.Keypad.getAltedChar and getUnaltedChar methods do not return the correct character on all handheld types. On an actual handheld, the methods return the correct character. The compiler that is included with the BlackBerry JDE does not work correctly on computers with a Cyrillic locale set. When an invalid style is provided as a parameter to the net.rim.device.api.ui.Font.derive methods, the methods return a font with a style that is neither the requested font nor the original font. The IDE Online Help cannot be printed. Attempting to print can cause the IDE to stop responding. Base 4 formatting is inconsistent: when set using net.rim.device.api.util.NumberUtilities. appendNumber( StringBuffer, long, int ), the number might return with a negative sign if it is negative, whereas with appendNumber( StringBuffer, int, int ), the number does not return with a negative sign. The state of a net.rim.device.api.util.IntMultiMap is not reset correctly when IntMultiMap.clear() is invoked, so further operations can throw an ArrayIndexOutOfBoundsException. The net.rim.device.api.util.Arrays.fill(long[] array, long element, int offset, int length) method does not work correctly. The method does not use the length parameter and instead fills the rest of the array with the value of the element parameter. The net.rim.device.api.i18n.MessageFormat.setFormats() method does not set a new list of sub-formatters.

T10498

T12310 T12351

T12620

T12858

T12908

T13438 T13550

T13553

T13558

SDR369

SDR421
The net.rim.device.api.ui.Screen.scroll() method always returns true, even when focus is not moved to a new field. The net.rim.device.api.io.SharedInputStream.setCurrentPosition( int currentPosition ) method throws an IllegalArgumentException if the currentPosition parameter is set to a negative value. The net.rim.device.api.ui.component.RadioButtonField(String,RadioButtonGroup,boolean) constructor does not throw a NullPointerException if a null value is passed in for the RadioButtonGroup parameter. The API documentation is incorrect. The DeviceInfo.getOSVersion() method returns the incorrect OS version. In the BlackBerry Mail API, to list folders of a particular type, do not use the Folder.OUTBOX constant. Use Folder.SENT. The net.rim.device.api.mime.MIMEInputStream.skip(long n) method throws an IllegalArgumentException when n is negative. This behavior is not specified in the API documentation. In the BlackBerry MailAPI, multiple text body parts are not added correctly to a multipart message. Separate body parts are added, but each has the same text as the last body part that is added. Uninstalling the JDE does not remove shortcuts from the Start menu. The sample code in the com_rim_bb_pimdemo project contains an error. In EventScreen.java, in sendInvitations() at line 212, the string that is passed to the toSerialFormat method should be one of the strings from the array queried from the previous line (the string with the substring 2.0 contained). When an application opens an HttpConnection using the Mobile Data Service, if the host server does not exist, an IOException is not thrown. A result code of 400 is returned. When an appication attempts to connect to a Mobile Data Service that does not exist or is unreachable, the connection blocks for approximately two minutes before timing out. When adding a StringItem to a Form, a new line is currently inserted. The Form does not scroll back to the beginning when an Item is inserted. The net.rim.device.api.ui.component.LabelField.setText(ResourceBundleFamily family,int id) method does not work. Other forms of LabelField.setText work correctly. Invoking net.rim.device.api.ui.container.MainScreen.setTitle(ResourceBundleFamily family, int id) can cause a StackOverflowError. Workaround: Do not invoke this method on the event thread when the containing screen has no title (no previous call to setTitle has occurred).

SDR569

SDR657

SDR3259 SDR3545

SDR3780

SDR4590

SDR4598 SDR4882

SDR5385

SDR5707

SDR7628

SDR7639

SDR7996

When the BlackBerry JDE is installed on Windows NT, the Mobile Data Service and Email Server Simulators cannot start. To correct this problem, add the following code to the start of the setBMDSEnv.bat file in the ESS and MDS folders:
set temp=%cd% if not [%temp%] == "%cd%" goto macroExists cd > _pwd for /f tokens="tokens=*" %%f in (_pwd) do set cd=%%f del _pwd :macroExists

SDR8376

When you send email messages from the handheld simulator using the email server simulator, the email message can appear with two "from" addresses in the email client, such as Microsoft Outlook Express. The second "from" address is the PIN of the handheld simulator, and should not appear. MIDlets cannot auto run on startup. In the IDE, in project properties, do not select the Auto-run on startup option if Project type is set to MIDlet. If you write a client application that listens for incoming data from a push application, do not write code that closes and re-opens the network connection after pushed data is received. This approach can cause incoming pushed data to be lost, if data arrives before Connector.open is invoked again after a previous push. The HTTPPushDemo.java sample included with the BlackBerry JDE, and the sample code in the Developer Guide, use the incorrect approach. Visit the BlackBerry Developer Zone knowledge base for an updated code sample. Future versions of BlackBerry handheld software contain a change to the MD2Digest class. To prevent future problems with binary compatibility, do not use the MD2Digest class directly; instead, use the base class Digest and the factory DigestFactory.

Additional information

This section provides information in addition to the BlackBerry Java Developer Guide.

PIM APIs

The PIM APIs might change in future releases to maintain consistency with the PDAP specification. You might have to modify and recompile applications that use the PIM APIs.
Using the BlackBerry Mail API
Applications that use the BlackBerry Mail API require that the BlackBerry Attachment Service software is loaded onto the handheld. Edit the.alx file to add the <requires> tag:

<requires id="net.rim.blackberry.api" /> <requires id="net.rim.java.docViewer" />
Refer to the BlackBerry JDE Developer Guide Volume 2, chapter 2 Integrating email, for more information.
Distributing files for BlackBerry Mail and PIM APIs
If your application uses the BlackBerry Mail or PIM APIs, you must redistribute updated.cod files for these APIs with your application. The.cod files that are included with desktop software version 3.6 are no longer up-to-date. An updated installation package for the BlackBerry Mail and PIM APIs is available on the BlackBerry Developer Zone web site. An installer is included that installs the required.cod files to the correct location on the users desktop. Visit http://www.blackberry.com/developers for more information.
Requesting code signatures
In the IDE, you must build all projects in the workspace before you can request signatures. To request signatures, in the IDE, on the Build menu, click Request Signatures. Refer to the BlackBerry Java Developer Guide Volume 2 Advanced Topics for more information on code signing.

Simulator time

When you invoke System.currentTimeMillis(), in the simulator, the time that is returned is the local time of the host machine on which the simulator is running, not GMT. The time returned matches local time, but the time zone in the settings is GMT.

Using.alx files

When the IDE generates an.alx file for a project, it adds a placeholder value in the <directory> tag. To load an application using the desktop software, you must first edit the.alx file: either remove the value in the <directory> tag (so the.alx file and.cod files must exist in the same folder) or place the.cod file in a subfolder and change the value in the <directory> tag to this folder name. Refer to the BlackBerry Java Developer Guide Volume 1 Fundamentals for more information on generating.alx files and the.alx file format.
Wireless application deployment
To make applications available on a web server for users to download wirelessly, you must set up the web server to set MIME types appropriately: File

.jad files.jar files.cod files

MIME type

text/vnd.sun.j2me.app-descriptor application/java-archive application/vnd.rim.cod
Refer to the chapter Deploying applications wirelessly in the BlackBerry Developer Guide Volume 1 Fundamentals for more information.
Note: This document is provided for informational purposes only, and does not constitute a binding legal document. RIM assumes no responsibility for any typographical, technical or other inaccuracies in this document, and makes no warranties, express or implied, with respect to the content of this document. RIM reserves the right to periodically change information that is contained in this document; however, RIM makes no commitment to provide any such changes, updates, enhancements or other additions to this document to you in a timely manner or at all. IN NO EVENT SHALL RIM BE LIABLE TO ANY PARTY FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES FOR ANY USE OF THIS DOCUMENT, INCLUDING WITHOUT LIMITATION, RELIANCE ON THE INFORMATION PRESENTED, LOST PROFITS OR BUSINESS INTERRUPTION, EVEN IF RIM WAS EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Any software that is provided with this document will be governed by the terms and conditions of the RIM software license provided to you with either your RIM wireless handheld or the RIM BlackBerry Enterprise Server Software, as applicable, and, by using the software provided with this document, you agree to be bound by such terms. Warning: This document is for the use of licensed users only. Any unauthorized copying, distribution or disclosure of information is a violation of copyright laws. No reproduction in whole or in part of this document may be made without express written consent of RIM. 2003 Research In Motion Limited. All rights reserved. The BlackBerry and RIM families of related marks, images and symbols are the exclusive properties of Research In Motion Limited. RIM, Research In Motion, 'Always On, Always Connected', the envelope in motion symbol and the BlackBerry logo are registered with the U.S. Patent and Trademark Office and may be pending or registered in other countries. All other brands, product names, company names, trademarks and service marks are the properties of their respective owners. The handheld and/or associated software are protected by copyright, international treaties and various patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D,445,428; D,433,460; D,416,256. Other patents are registered or pending in various countries around the world. Please visit www.rim.net/patents.shtml for a current listing of applicable patents. Note: These files are considered pre-release because they have received only minimal software quality assurance. If you decide to use the files in this release, you should retest your entire application. Although these files are considered an interim patch, they are deployable and supported. By applying this release, you agree to upgrade and apply the next generally available public release.

BlackBerry Simulator

Version 3.6

User Guide
BlackBerry Simulator Version 3.6 User Guide Last modified: 10 April 2003 Part number: PDF-06395-001 At the time of publication, this documentation complies with simulator version 3.6. The information in this document is RIM confidential and is for internal distribution only. 2003 Research In Motion Limited. All Rights Reserved. The BlackBerry and RIM families of related marks, images and symbols are the exclusive properties of Research In Motion Limited. RIM, Research In Motion, Always On, Always Connected, the envelope in motion symbol and the BlackBerry logo are registered with the U.S. Patent and Trademark Office and may be pending or registered in other countries. All other brands, product names, company names, trademarks and service marks are the properties of their respective owners. The handheld and/or associated software are protected by copyright, international treaties and various patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D445,428; D433,460; D416,256. Other patents are registered or pending in various countries around the world. Visit www.rim.com/patents.shtml for a current listing of applicable patents. While every effort has been made to achieve technical accuracy, information in this document is subject to change without notice and does not represent a commitment on the part of Research In Motion Limited, or any of its subsidiaries, affiliates, agents, licensors, or resellers. There are no warranties, express or implied, with respect to the content of this document. Research In Motion Limited 295 Phillip Street Waterloo, ON N2L 3W8 Canada Research In Motion UK Limited Centrum House, 36 Station Road Egham, Surrey TW20 9LF United Kingdom Published in Canada

Contents

About this guide..... 5 Overview.....6 Audience.....6 Conventions.....6 Related resources.....6
1 Getting started...... 7
Installing the handheld simulator....8 Setting up the simulators....9 Starting the simulators....10
2 Using the simulator.....11
Using the simulator....12 Setting wireless coverage conditions...14 Configuring reception....15 Configuring transmission....15 Using the phone.....16 Simulating handheld operating conditions....18 Simulating flash memory....19 Simulating a desktop connection....19
3 Simulator options......21
Handheld simulator options....22 Mobile Data Service simulator options....23

About this guide

This section provides information on the following topics:
Overview Audience Conventions Related resources

1: About this guide

Overview
This guide explains how to use handheld and network simulators to perform the following tasks:
learn how to use BlackBerry handhelds test web content and third-party applications reproduce and troubleshoot problems that are found in the field demonstrate features of BlackBerry handheld software
This guide assumes that you are comfortable installing and using software on a Windows computer.

Audience

This guide is intended for web content developers, trainers, technical support representatives, and sales people who need to use simulators for testing, training, troubleshooting, and demonstrations.

Conventions

This guide uses the following conventions:
Icon Description Warning: Warnings advise you that failure to take or avoid a specific action can result in data loss or physical damage. Prerequisite: Prerequisites are required conditions for the associated topic. Note: Notes contain important information on the associated topic. Tip: Tips provide optional or time-saving information on the associated topic.

Related resources

Refer to the following resources for additional information:
Resource Description This guide provides information on creating Java applications for BlackBerry handhelds. This guide provides information on creating web content and web-based applications for BlackBerry handhelds.
BlackBerry Java Developer Guide BlackBerry Browser Developer Guide
BlackBerry Wireless Handheld User Guide This guide provides information on using BlackBerry handhelds.

Getting started

Installing the handheld simulator Setting up the simulators Starting the simulators

1: Getting started

Installing the handheld simulator
Two simulators are available to test your web pages without using a actual handheld:
handheld simulator Mobile Data Service (MDS) simulator
Install the handheld simulator
1. 2. 3. 4. Go to the BlackBerry Developer Zone web site: http://www.blackberry.com/developers. Download the handheld simulator.zip file to your computer. Right-click the.zip file. Click Extract to folder C:\.\3.6.0.x.simpackage. A folder called 3.6.0.x.simpackage is created. In the rest of this guide, this folder is referred to as the simpackage folder.
Install the Mobile Data Service simulator
Prerequisite: To use the Mobile Data Service simulator, you must install the Java runtime environment (JRE) version 1.4.0 or later. Visit the Sun web site at http://java.sun.com/j2se/1.4.1/download.html for more information.

1. 2. 3. 4.

Go to the BlackBerry Developer Zone web site: http://www.blackberry.com/developers. Download the.zip file for the Mobile Data Service simulator to your computer. Right-click the.zip file. Click Extract to folder C:\.\MDS. An MDS folder is installed in the location that you selected.
Setting up the simulators
Edit the run.bat file to specify the handheld and network type to simulate. By default, the simulator emulates the BlackBerry 6700 Series of wireless handhelds on a GPRS network.

Set the handheld type

1. 2. 3. 4. In the simpackage folder, right-click run.bat. Click Edit. The file opens in a text editor. After set rimos=, add the appropriate.dll file name:

set rimos=Os6500.dll

Save the file.
Tip: Some simulator packages provide default batch files for each handheld type, such as runOs5800.bat, runOs6700.bat, and runOs6500.bat. Use these files if they are available so you do not have to edit the run.bat file.

Set the network type

By the default, the simulator emulates a handheld on a GPRS network. To emulate a handheld running on a CDMA or iDEN network, you must set a command line option. 1. 2. 3. In the simpackage folder, right-click run.bat file. Click Edit. The file opens in a text editor. After osloader %rimos%, add the /W<n> option:
/wc - CDMA networks /wi - iDEN networks /wg - GPRS networks
For example, to emulate a handheld operating on a CDMA network, add /wc:
osloader %rimos% /wc /RegAddress=none /rsim=0x20000001. /rport=8205 jvm.dll
Tip: When you start the handheld simulator, the network type appears in the window title.

Set the resolution

Add the /GRES option to set the resolution and color depth of the simulator LCD display. 1. 2. 3. In the simpackage folder, right-click run.bat file. Click Edit. The file opens in a text editor. After osloader %rimos%, add /GRES<height>x<width>x16: For example, to emulate a BlackBerry 6200 Series handheld, add /GRES160x100x16:
osloader %rimos% /GRES160x100x16 /RegAddress=none /rsim=0x20000001. jvm.dll

Starting the simulators

Start the handheld simulator
1. In the simpackage folder, double-click run.bat. The handheld simulator appears. If a JVM error occurs, close the simulator. In the simpackage folder, delete the.dmp files and double-click run.bat again.
Start the Mobile Data Service simulator
1. In the MDS folder, double-click load.bat. A command prompt window displays information about Mobile Data Service startup. If the Mobile Data Service starts successfully, the following message appears at the bottom of the command prompt window: INFO: Starting Coyote HTTP/1.1 on port 8080
Verify that the Mobile Data Service simulator is running
1. In the handheld simulator, open the BlackBerry Browser. The browser appears.
Tip: To select the BlackBerry Browser icon, roll the wheel button on your mouse, or press the UP ARROW or DOWN ARROW key. To open the application, click the mouse wheel button or press ENTER.

2. 3. 4. 5.

Click the mouse wheel button (or press the RIGHT ARROW key). The browser menu appears. Click Go To. A dialog box appears. In the Go To field, type: http://www.blackberry.com/go/mobile/. Click OK. If the BlackBerry home page appears, the Mobile Data Service simulator is working correctly. If an error message indicates that the browser is unable to connect to the Mobile Data Service, verify that you started the Mobile Data Service simulator.

Using the simulator

Using the simulator Setting wireless coverage conditions Using the phone Simulating handheld operating conditions Simulating flash memory Simulating a desktop connection

2: Using the simulator

The handheld simulator displays a Home screen with icons for each application. When you select an icon, the name of the application appears at the bottom of the Home screen. Double-click an icon to open that application.

Phone button Trackwheel

Home screen

Escape button

Application title bar
Backspace key Alt key Left Shift key Enter key Right Shift key

BlackBerry handheld simulator for GPRS

Use the trackwheel

The simulator trackwheel simulates the trackwheel on the handheld. Using the trackwheel, you can navigate, view, and select items on each screen in the simulator. You can roll the trackwheel to scroll through menu items or text, and click the trackwheel to select applications or menu options. If your mouse has a wheel button, simulate using the trackwheel as follows:
To simulate rolling the trackwheel, roll the wheel button on your mouse. To simulate clicking the trackwheel, click the wheel button.
If your mouse does not have a wheel button, simulate using the trackwheel as follows:
To simulate rolling the trackwheel, left-click your mouse and drag the simulator trackwheel up or down, or press the UP ARROW or DOWN ARROW keys on your computer keyboard To simulate clicking the trackwheel, right-click your mouse, or press the LEFT ARROW or RIGHT ARROW key on your computer keyboard.

Start an application

1. 2. 3. 4. 5. In the simulator, roll the trackwheel to select an application icon. The title of the application appears at the bottom of the screen. Click the trackwheel. The application main screen appears. To open the application menu, click the trackwheel. To click a menu item, click the trackwheel. To return to the Home screen, click Close.

Use the keyboard

To simulate pressing keys on the handheld, press the keys on your computer keyboard or use your mouse to click the keys on the simulator keyboard. Press ESC on your computer keyboard to simulate pressing the Escape key on the handheld. Press CTRL on the computer keyboard to simulate pressing the Alt key on the handheld.

Set the keyboard mode

Your options for using the keyboard depend on the keyboard mode that is set for the simulator. 1. In the simulator, on the Keyboard menu, click one of the following options:
PC: In PC mode, you can type letters and numbers using the normal keys on your computer keyboard. Handheld: In handheld mode, you can use only the keys on your keyboard that exist on the handheld. To type a number or symbol, hold CTRL and press the appropriate key on the computer keyboard. For example, on a BlackBerry 6700 Series handheld, to type 1, press CTRL+W.

In either mode, you can use your mouse to click keys on the simulator.

Set the display size

1. In the simulator, on the Display menu, click one of the following options:
Actual Size: uses the same number of pixels as on an actual handheld LCD Large Display: uses a larger display with correct aspect ratios 13

Take screen shots

You can save a bitmap image of the handheld simulator screen. The image size is the same as the resolution set on the simulator (the default is 160 by 160 pixels). 1. 2. 3. 4. In the simulator, on the Display menu, click Snapshot LCD. The Save Snapshot window appears. In the File name field, type a file name for the image. Select a folder. Click Save. The screen is saved.
Setting wireless coverage conditions
1. In the simulator, on the Simulation menu, click Show Radio Simulation Control Panel. The Radio Simulation Control Panel appears.
Radio Simulation Control Panel

Configuring reception

In the Radio Simulation Control Panel, the Reception section enables you to simulate different wireless network coverage conditions for receiving data.
Simulate wireless network coverage
1. 2. In the Radio Simulation Control Panel, select the In coverage option. Slide the coverage bar to control the received signal strength indicator (RSSI) reported to applications. The signal strength varies from 120 dBm to 50 dBm. A signal of -120 dBm is extremely weak, and the handheld typically loses coverage before reaching this number. A signal of -50 dBm is stronger than you are likely to see on the actual network.
Simulate loss of wireless network coverage
In the Radio Simulation Control Panel, select the Out of coverage option. This option simulates the condition when a handheld is outside an area of sufficient wireless network coverage, and cannot receive or send data.

Configuring transmission

In the Radio Simulation Control Panel, the Transmission section enables you to simulate different wireless network coverage conditions for sending data.
Simulate good wireless network coverage
1. In the Radio Simulation Control Panel, select the All transmits succeed option. Selecting this option means that data is sent successfully from the handheld to the network. On an actual network, under good wireless network coverage conditions, almost all data is sent successfully.

Simulate network delays or user choice of transmission
1. In the Radio Simulation Control Panel, select the Prompt for Tx success option. Selecting this option means that every time the simulator sends data to the network, you are prompted to select whether the data is transmitted successfully. The data is pending until you select Yes or No. You can use this mode to simulate very long transmission delays.
Simulate intermittent wireless network coverage
1. 2. In the Radio Simulation Control Panel, select the Random success option. Use the slide bar to set the probability with which data is sent successfully from the handheld. The delay for successful packets is about one and a half seconds. The delay for unsuccessful packets is three seconds (unsuccessful transmission attempts typically take longer than successful transmission attempts).

Using the phone

On the BlackBerry 6700 Series handheld simulator, press the PAGE UP key on your computer keyboard to simulate pressing the Phone button on the handheld. On the BlackBerry 6500 Series handheld simulator, press the PAGE UP key on your computer keyboard to simulate pressing the PTT (Push-to-Talk) button.

Simulate voice calls

1. In the simulator, on the Simulation menu, click Show Voice Simulation Control Panel. The Voice Simulation Control Panel window appears.
Voice Simulation Control Panel
Select one of the following options:
To simulate making a voice call to the handheld, click Create. The call appears in the Current Calls list. The handheld simulator displays a message that there is an incoming call, which you can then answer, answer and hold, or ignore. To disconnect a call, click Disconnect. To simulate the failure of a call, from the drop-down list beside the Fail button, select a reason for the failure. Click Fail.
In the simulator, you can use the Phone application to simulate making a voice call. This call appears in the Current Calls list in the voice simulation control panel. Click Accept to simulate answering the call.
Simulate SIM card changes
1. In the simulator, on the Simulation menu, click Show Voice Simulation Control Panel. The Voice Simulation Control Panel appears. The SIM section displays information on the current SIM card that is simulated. 2. To simulate removing the SIM card from the handheld, click Remove. When the SIM card is removed, you can change information, such as adding voice mail phone numbers. 3. To simulate inserting a SIM card, click Insert.
Enable supplementary services
You can simulate a variety of supplementary voice services, including call barring, caller ID, and call forwarding. 1. In the simulator, on the Simulation menu, click Show Supplementary Service Control Panel. The Supplementary Services Option window appears.

Supplementary Services Option window
In the Network Option section, select one of the following check boxes:
Check box Description simulates the handheld forwarding calls to specific phone numbers simulates the handheld ignoring outgoing phone calls simulates the handheld ignoring incoming phone calls simulates the handheld preventing the caller's phone number from appearing on outgoing calls simulates the handheld outside of a wireless network coverage area simulates the handheld roaming on another wireless network
Forwarding Outgoing Barring Incoming Barring Call ID Restriction Mobile not reachable Mobile Roaming
Simulating handheld operating conditions
You can simulate various conditions that affect the operation of the handheld.
Simulate battery conditions
You can simulate the status of the handheld battery. 1. In the simulator window, on the Simulation menu, click one of the following options:
Option Good Battery Low Battery Dead Battery Charging Description battery power is sufficient for handheld and network use battery power is too low to use the network, but the handheld is on handheld is off handheld battery is charging
Simulate holster conditions
You can simulate the handheld either in or out of the holster. When the handheld is in the holster, the screen display turns off. 1. In the simulator, on the Simulation menu, click In holster or Out of holster.

Enable backlighting

1. Press the PAGE DOWN key on your computer keyboard. Backlighting remains on for 20 seconds.

Simulating flash memory

The simulator uses a.dmp file to simulate flash memory. When the simulator starts, it loads the flash memory contents from the.dmp file, or creates a.dmp file if one does not already exist. When the simulator exits, it saves flash memory contents to the.dmp file. A separate.dmp file is maintained for each handheld type. The file name is FS<number>.dmp, where <number> is the handheld series number, such as 5800, 6500, or 6700. The flash memory size is specified using the /F<n> command line option.
Simulate resetting a handheld
When the handheld is reset, flash memory is cleared. You can simulate this situation. 1. 2. In the simpackage folder, delete the FS<number>.dmp file. Restart the simulator.
Simulating a desktop connection
You can simulate a serial connection between the handheld and the BlackBerry Desktop Software.
Note: The simulator supports serial port connections only. The simulator does not support USB connections.
1. 2. 3. 4. 5. 6. 7. 8. 9.
Exit the BlackBerry Desktop Software. Connect a null modem cable between COM port 1 and COM port 2 on your computer. In the simpackage folder, right-click run.bat. Click Edit. The file appears in a text editor. Before jvm.dll, add the /S1 option:

osloader %rimos%. /F8192 /H577592 /rport=19780 /rport=8205 /S1 jvm.dll
Save the file. Start the simulator. Start the BlackBerry Desktop Software. In the BlackBerry Desktop Software, on the Options menu, click Connection Settings.
10. Click Detect. A message indicates that a handheld was found. The BlackBerry Desktop Manager is now connected to the simulator. If the BlackBerry Desktop Software does not detect the simulator, restart your computer and repeat steps 6 through 9. User Guide 19

Simulator options

Handheld simulator options Mobile Data Service simulator options

3: Simulator options

Handheld simulator options
1. 2. 3. In the simpackage folder, right click run.bat. Click Edit. The file appears in a text editor. Before jvm.dll, add options:
osloader %rimos% /RegAddress=none /rsim=0x20000001 /F8192 /H577592 /rport=19780 /rport=8205 [options] jvm.dll
The following table describes the command line options for the handheld simulator.

Option

/APP /B /D<n> /E /F<n> /GRES /L- /L+ /LN /localtime /N /RDISABLESMS /REGADDRESS /ROFF /RPHONE /RPORT /RSIM /RSMS /S<n> /SMALL /W<n>
Description Set /APP=JvmEnableSecurity to set the simulator to securemode. Disable sound card. Use <n> sectors of flash memory for file system data storage. Erase the flash memory allocation log. Simulate <n> kilobytes of flash memory. Set resolution and color depth of the simulated LCD, in the following format: /GRES=<height>x<width>x<depth>. Turn on (L+) or turn off (L-) flash memory timing simulation. Turn off flash memory protection. Specify that the simulator should return local time when applications invoke time-related methods. Delete the flash file memory system before initialization. Disable SMS support in the simulator. Enable or disable a registration server. Turn off the radio on simulator startup. Set a SIM phone number. Set the handheld socket for network communication. Set the simulator personal identification number (PIN). Specify an SMS server and simulator ports for sending and receiving SMS messages. Specify a desktop computer serial port to use. Enable the IDE to launch the simulator's LCD screen to actual size. Specify the type of network to simulate: /wc - CDMA networks /wi - iDEN networks /wg - GPRS networks
Mobile Data Service simulator options
1. 2. In the MDS\config folder, open the rimpublic.property file in a text editor. Edit parameters to configure the following features:
logging HTTP support HTTPS support push support email-to-PIN mappings
Restart the Mobile Data Service simulator for changes to take effect.

Logging

Parameter

Logging.level

Description Specify the type of information that is logged, if logging is enabled. 1: events, such as starting and stopping 2: events + errors 3: events + errors + warnings 4: events+errors + warnings + debug

Default

Logging.console.log.level
Specify the type of information that appears in the console, if logging 4 is enabled. Refer to the description for the Logging.level parameter. Set to TRUE or FALSE to enable or disable HTTP standard logging (HTTP TRUE headers only). Set to TRUE or FALSE to enable or disable HTTP debug logging (HTTP data and headers). This parameter should be set to TRUE only when necessary to debug a specific problem. Set to TRUE or FALSE to enable or disable HTTPS logging.
application.handler.http.logging application.handler.http.logging. verbose application.handler.http.logging

HTTP support

application.handler.http. CookieSupport application.handler.http. AuthenticationSupport application.handler.http. AuthenticationTimeout
Description Set to TRUE or FALSE to enable or disable cookie storage. If you select TRUE, the Mobile Data Service manages cookie storage instead of the handheld. This reduces the load on the handheld significantly.
Set to TRUE or FALSE to enable or disable storage of user authentication TRUE information. If HTTP authentication is set to TRUE, this parameter determines the 3600000 length of time (in milliseconds) before the authentication information becomes invalid. This timer resets whenever the user issues a request that invokes the authentication information for a particular domain. This parameter sets the length of time (in milliseconds) before a connection attempt to the handheld expires if the handheld is unreachable. This parameter sets the length of time (in milliseconds) before a connection attempt to a server expires if the server is unreachable.

140000

application.handler.http. device.connection.timeout

application.handler.http. server.connection.timeout

150000

HTTPS support
application.handler.https. allowUntrustedServer
Description Set to TRUE to allow the Mobile Data Service to connect to untrusted servers or FALSE to restrict access to trusted servers only. A server is trusted if its certificate is installed on the Mobile Data Service host machine.

Push support

The following parameters are related to Mobile Data Service support for push applications. You typically should not change these parameters.
WebServer.listen.host WebServer.listen.port

Description

This parameter defines the computer on which the Mobile Data Service localhost listens for HTTP POST requests from push applications. This parameter defines the port on which the Mobile Data Service listens for HTTP POST requests from push applications.

Email-to-PIN mapping

To test push applications, map the simulator PIN to the email addresses that the push application uses. 1. In the rimpublic.property file, add or change entries in the [Simulator] section. Entries have the following format:
Simulator.<PIN>=<host>:<port>, <email_address>
The following default entry maps PIN 2100000a to email address user2100000a@pushme.com:
Simulator.2100000a=localhost:81, user2100000a@pushme.com
Change the email address, if necessary, so that when a push application sends data to that email address, it is sent to the simulator.
Note: The default PIN for the simulator is 2100000a. The PIN is set using the /rsim simulator option.
2003 Research In Motion Limited Published in Canada.