Blackberry RIM 950 User Manual

Developer’s Guide

RIM 950 Wireless Handheld™

Version 1.7

SDK User’s Guide

RIM 950 Wireless Handheld — SDK User's Guide, Version 1.7
Last revised 9/18/00

Part Number: PD F-03037-001

© 1997-2000, RESEARCH IN MOTION LIMITED

RIM, Research In Motion, the RIM logo, RIM 950 Wireless Handheld, RIM 957
Wireless Handheld, RIM 950, RIM 957 and RIM Wireless Handheld are trademarks
of Research In Motion Limited. Research In Motion and RIM are registered, U.S.
Patent and Trademark Office.

Complies wit h software O/S version 2.0 and applications version 1.7.
Visual C++ and Windows are trademarks of Microsoft Corporation. Intel is a

registered trademark of Intel Corporat thoion. Mobitex is a registered trademark of
Telia AB. DataTAC is a registered trademark of Motorola. All other brands, product
names, company names, trademarks, and service marks mentioned herein are
registered trademarks or trademarks of their respective holders.

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.

While every effort has been made to ensure 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.

Research In Motion Li mited

295 Phillip Street
Waterloo, Ontario
Canada N2L 3W8
Tel. [phone]
Fax [phone]
Web site: www.rim.net
Email: [e-mail]

Printed In Canada

JHM0700/sdk_uguide.doc

Contents

1. Introduction............................................................................................5

About the SDK......................................................................................5

About the network ...............................................................................6

About Research In Motion..................................................................6

About this guide...................................................................................6

2. Installing the SDK................................................................................9

To install the SDK.................................................................................9

To configure Microsoft Developer Studio.......................................11

3. Release notes........................................................................................15

Recompiling your applications.........................................................15

Message................................................................................................15

OS..........................................................................................................16

New simulator....................................................................................16

Ribbon changes...................................................................................16

Address Book changes.......................................................................17

4. Tools guide...........................................................................................19

RIM 950 Wireless Handheld simulator ...........................................19

Program loader...................................................................................37

DLLUtil................................................................................................47

Conversion utilities............................................................................47

5. An overview of the system................................................................49

RIM co-operative scheduler..............................................................50

Tasks and threads...............................................................................50

Task yielding.......................................................................................50

MESSAGE concept.............................................................................51

Memory use.........................................................................................51

User interface......................................................................................52

API overview ......................................................................................52

6. Building applications.........................................................................55

Coding an application........................................................................55

Compiling RIM Wireless Handheld applications..........................63

Installing the application...................................................................64

Appendix ..................................................................................................69

C library compatibility for RIM Wireless Ha ndheld applications69

Index..........................................................................................................75

1.Introduction

The RIM 950 Wireless Handheld Software Developer’s Kit (SDK)
includes all the tools needed to begi n application development quickly.
The SDK provides an extremely powerful development environment
that utilizes Microsoft Developer Studio 5.0 or later (Visual C++ 5.0 or
later), supporting Windows 95 and Windows NT.

The RIM Wireless Handheld™ features a 32-bit Intel386™ processor
which executes the same instruction set as a Windows 95 computer. The
operating system provided with the wireless handhel d is a multitasking
operating system with built-in messaging. You can write new
components for the wirele ss handheld wi thout needing to rewr ite entire
applications.

About the SDK

The SDK package includes:

• software

• application utilities

• PC-based simulator (herein referred to as the “RIM Wireless

Handheld simulator”)

If you have used a previous version of this SDK, you should read the
release notes section of this document (see page 15). The release notes
section describes changes required to make old applications run under
this version of the software. For example, it describes the new versioning
scheme and outlines compatibility requirements in new releases.

6 Introduction — About the network

About the network

The RIM Wireless Handheld operates over the BellSouth Intelligent
Wireless Network
wireless data network in Canada. Both networks offer broad coverage,
nationwide roaming, fast messaging, a nd reliable delivery. Even if your
RIM Wireless Handheld is turned off or temporarily out of coverage,
your messages will be stored and forwarded automatically when you
return to coverage.

SM

in the United States and the Rogers™ AT&T®

About Research In Motion

Research In Motion (RIM) manufactures high performance radio
modems for use with the Mobitex network. These modems and other
Mobitex products manufactured by RIM are used on Mobitex networks
around the world.

RIM has an internatio nal r eputa tion f or de velop in g hig h per for mance RF
technology in the narrowband PCS data communications industry.
RIM’s wireless technology has set new standards for battery life,
transceiver performance, physical size, ease-of-use, and price.

By helping companies design a broad range of wireless data products,
RIM has a detailed understanding of what end users and equipment
manufacturers need to use the Mobitex network effectively and
affordably.

The result of this close co- o per ation is a fa mily of ad vanc ed wir eles s da ta
products that are easy to use and integra te quickly, including the RIM
902M™ OEM radio modem and the RIM 950 Wireless Handheld.

About this guide

These Developer’s Guides are meant to assist you in creating your
applications. This guide includes general information on the SDK itself.

Throughout this guide, the simulator will be referred to as the ‘RIM
Wireless Handheld simulator.’

Developer’s Guide – RIM 950 Wireless Handheld™

Introduction — About this guide 7

Some information is set apart typographically in the following ways:

Note

Notes provide additional information to help complete a task.

Tips offer an alternative method of performing an action

Tip

WARNING

Warnings follow any procedure or paragraph containing
instructions that, if followed improperly, could result in
damaging the RIM Wireless Handheld or software.

The names of program groups, icons, folders, wi ndows, etc. will appear
in bold text. An example would be the Research In Motion program
group.

References to buttons have the hot key underlined where applicable. An
example would be the N

ext> button.

All programming elements such as returns, events, constants, structures,
parameters, etc. will appear in
the

COMM_RX_ERROR error code.

Courier New font. An example would be

Developer’s Guide – RIM 950 Wireless Handheld™

2. Installing the SDK

In order to run the RIM 950 Wireless Handheld Software Developer’s
Kit, you need a PC capable of running Microsof t De veloper Studio 5.0 (or
later). This chapter describes the process of installing the RIM 950
Wireless Handheld SDK an d config uring Microsof t De veloper Studi o 5.0
(or later) to work with the SDK.

You can install and run the RIM 950 Wireless Handheld SDK in both
Windows 95 and Windows NT.

To install the SDK

1. Double-click on the installer icon.

2. The RIM Wireless Handheld simulator setup desktop will appear.
Follow the instructions on your screen throughout the setup process.

Software License Agreement window

10 Installing the SDK — To install the SDK

Note

Please read the license agreement carefully. Proceeding with the
installation indicates that you agree with the conditions in the license
agreement.

3. When the Choose Destination Location window opens, a default
directory will be displayed. To change this directory, click the

Br

owse button, and the Choose Directory window will open. Select

the path, drive, and directory that you would like for your
destination. Click OK to return to the Ch oose Destination Location
window.

Choose Destination Location window

4. Once you have selected the destination directory, click N
continue. The Select Program Folder window opens.

Select Program Folder window

Developer’s Guide – RIM 950 Wireless Handheld™

ext> to

Installing the SDK — To configure Microsoft Developer Studio 11

5. Type in a folder name in which the setup items will be stored. The

default folder name is Research In Motion. Alternatively, you may
select a folder from the Existing Folders section.

6. At the end of the installation, an Installation Query window will

open to ask if you would like to view the README file.

7. A new window will open to display the Research In Motion

program group.

The RIM 950 Wireless Handheld SDK contains all of the tools and
information needed to build an application.

See page 55 for information on the process of building an applica tion for
the RIM Wireless Handheld and the structure of an application. See
Chapter 3 – Tools Guide on page 19 for information on the tools use d to
create a wireless handheld application and for a description of their
function and usage.

To configure Microsoft Developer Studio

The RIM 950 Wireless Handheld SDK is designed to make use of the
libraries and features in Microsoft Developer Studio 5.0 (or later).
Handheld applications are built as a Windows DLL target, but they are
not used as Windows applications. The final DLL is stripped of
extraneous information and then ported into the RIM Wireless Handheld
operating system.

Because Windows sees the RIM Wireless Handheld applications as
DLLs, Developer Studio allows you to use nearly all development
facilities available for Windows, including using the Integrated
Development Environment, source level debugging, and breakpoints.
However, DLLs must not make calls to the Windows API, even when
running under Wind ows.

You must be familiar with Microsoft Developer Studio to develop
applications. You must purchase and become familiar with this
application separately from the RIM 950 Wireless Handheld Software
Developer’s Kit.

Developer’s Guide – RIM 950 Wireless Handheld™

12 Installing the SDK — To configure Microsoft Developer Studio

Follow these steps to configure the Microsoft Visual C++ 5.0 (or later)
environment for building RIM 950 Wireless Handheld applications.

1. Start the Microsoft Developer Studio and select File > New > Project

to create a new project.

• Give the project a name.

• Define the project type as WIN32.DLL.

Although the target is a Windows DLL, the RIM Wireless
Handheld application is not compatible with the Windows
operating system.

2. Select Project > Settings to set up the project parameters.

• Go to the Settings For: tab.

• Select All Configurations.

3. Go to the Debug tab.

• Set the executable for the Debug Session as OSLOADER.EXE.

• In the Program arguments field put a line in the form:

OS DLL] [OS parameters] [application DLLs]

[
[

OS DLL] should be OSPGRMB.DLL if you are simulating a

RIM 950 and OSHHMB.DLL if you are simulating a RIM
957™. (If you’re using OSLOADER.EXE, you don’t need to
specify a complete path because the program looks first in its
current directory.) [
switches you need to pass to the simulator.

• Fina lly, list all of the applic ation DLLs at the end of the line,
making sure your application is the last one listed.

In order for the OSLOADER.EXE to find the DLLS, you must
either place the DLLs in your
directory and use that directory as your working directory.

4. Go to the C/C++ tab.

• Set the Category to Preprocessor.

• Enter the paths for the SDK include files in the Additional

Include Directories field. These paths are to the

OS parameters] are any command line

PATH or place them in the same

Developer’s Guide – RIM 950 Wireless Handheld™

Installing the SDK — To configure Microsoft Developer Studio 13

subdirectories \include and \include\internal of the RIM 950
Wireless Handheld SDK installation directory.

5. Change the Category to Code Generation.

• Set the Struct Member Alignment to 2 bytes. This will

minimize memory usage.

• Set the Processor to 80386.

6. Change the Category to C/C++ Language.

• Make sure that all check boxes are unchecked.

• The Enable Exception Handling checkbox should always be

unchecked.

7. Switch to the Link tab.

• Set the Category to General.

• At the end of the Object/Library Modules field, include the

files RIMOS.LIB, OSENTRY.OBJ, at the beginnin g, followed
by any .LIB files that are required (e.g. UI32.LIB,
ADDRESS.LIB, etc.). Place LIBC.LIB at the end.

• Check the checkbox Ignore all default libraries. Set the

Category to Input.

• Place the path to the subdirectory

\lib of the RIM 950

Wireless Handheld SDK installation directory in the
Additional librar y path.

8. Save these settings.

9. Your setup is complete. Now you are ready to create your
application.

Developer’s Guide – RIM 950 Wireless Handheld™

3.Release notes

This section describes some of the cha nges between versions 1.6 and 1.7
of the RIM 950 Wireless Handheld SDK. It describes changes you must
make to your existing code base before attempti ng to build applications
for RIM 950 Wireless Handheld 1.7.

WARNING

RIM 950 Wireless Handheld 1.7 comes with a new operating system, a
new simulation environme nt and some new methods and classes. This
section lists the methods and functions that have changed for 1.7 . You
should pay close attention to this list and modify your cod e if you used
the old forms.

The 1.7 environment is not binary compatible with 1.6. You
must recompile your code before running it on a 1.7 system.

Recompiling your applications

There is a new OS library, named RIMOS.LIB. Change the linker
settings for your development environment and replace the old OS
library (PAGER950.LIB) with RIMOS.LIB.

There are also a number of new methods and classes for 1.7. Check the
sections below for any code changes you might require. Be sure to
modify your code appr opriately to match the ne w method signatures.

Message

The create_message() call has been modified. It was:

bool create_message (NetworkMessage * message = NULL)

It is now:

bool create_message ( void )

16 Release notes — OS

See the Message API Developer’s Guide for more information.

OS

Version 2.0 of the OS removes certain constants. The constants

LCD_WIDTH, LCD_HEIGHT, LCD_HEIGHT_BYTE, LCD_DISPLAY_SIZE, and
LCD_DISPLAY_SIZE_BYTE that were available but deprecated in

previous releases of the SDK are no longer available. The information
they provided should be obtained using the
<LCD_API.H>). For quick recompiling, the header PRE20.H can be
included, which defines those values as function calls. This solution
should be avoided, ho wever, since the overhead of the functions makes
the use of the values very inefficient.

New simulator

For RIM 950 Wireless Handheld 1.7, a new simulator replaces the
existing PAGER950 executable. To debug applications using the new
simulator, replace PAGER950.EXE in the
field of the
OS DLL (for example, OSPGRMB.DLL) to the
the first argument. For more information on how to use the new
simulator, see the section titled “Device Simulator” in this guide.

Debug tab in the project settings with OSLOADER.EXE. Use an

LcdGetConfig call (from

Executable for debug session

Program arguments field as

Ribbon changes

The call RibbonSetApplicationString() now has an extra
parameter. If your application calls this function, you will get a lin k error
and will need to make a small code change.

The previous version of the call in the 1.5 S DK was d efined in RIBBON.H
as:

void RibbonSetApplicationString(

const char * const appName,
const char * const string,
int priority );

Developer’s Guide – RIM 950 Wireless Handheld™

Release notes — Address Book changes 17

The new version of the call is defined as:

void RibbonSetApplicationString(

const char * const appName,
const char * const string,
int priority,
const BitMap * const bitMapPtr );

The

bitMapPtr parameter is new, and refers to an optional image that

can be displayed instea d of one of the c harac ters of
has a normal maximum of five characters; if
the maximum is four characters, because one character position is used
by the bitmap.

string. The string

bitMapPtr is not NULL,

Address Book changes

Two functions have been added to notify the application of changes t o
the Address Book’s data:
an application, and
number of changes since the last reset.

register_address_book_update() registers

get_address_book_change_count() returns the

The Address Boo k API n o w has a set of f unct io ns f or de aling wit h group
addresses. A group address is an add ress name that represents a list of
other addresses. The new group addressing functions provide the
following features for dealing with group addresses:

• Determine if an address is a group address

• Get number of members

• Get information about members

• Get UIN from address handle

Developer’s Guide – RIM 950 Wireless Handheld™

4.Tools guide

This section provides information on how to make use of the tools
provided in the SDK. These tools are provided:

• RIM Wireless Handheld simulator program
(SIMULATOR.EXE/OSLOADER.EXE), used to test programs on a
PC without loading them onto a wireless handheld

• Program Loader program (PROGRAMMER.EXE), used to load
programs onto the RIM Wireless Handheld

• Conversion utilities for creating fonts and bitmaps
(BMP2DEF.EXE, BITMAP.EXE, and LCDFONT.EXE)

• A utility (DLLUTIL.EXE) to display information about a RIM
Wireless Handheld application

This chapter describes configuration and use for each of these tools. We
assume you have a basic familiarity with Microsoft Developer Studio.

RIM 950 Wireless Handheld simulator

The simulator allows you to test applications on the RIM Wireless
Handheld operating system without having to download the DLLs to the
wireless handheld itself. T he simulator supports t he full functionality of
the RIM Wireless Handheld itself, and can even be connected to a RAP
modem via the PC’s serial port, allowing the radio API to communicate
with the live Mobitex network.

Note

There are some differences between the RIM Wireless Handheld
device and the simulator. The simulator responds to certain
debugging calls, sending the output to the Visual Studio output pane;
those calls have no effect on the RIM Wireless Handheld.

20 Tools guide — RIM 950 Wireless Handheld simulator

Running the simulator

There are two RIM Wireless Handheld simulator programs:
SIMULATOR.EXE AND OSLOADER.EXE.

They are launched in different ways

SIMULATOR.EXE provides a Windows interface to the

•

OSLOADER.EXE program and is normally launched using
shortcuts.

OSLOADER.EXE provides a command-line interface and is

•

normally launched using the command line.

For both simulators, you must load applications. Each DLL loa ded into
the simulator environment is a separate application; which DLLs you
load depends upon which RIM 950 Wireless Handheld application you
want to simulate.

Run the simulator using shortcuts

The install process creates two icons in the RIM 950 Wireless Handheld

1.7 SDK program group – an SDK readme.txt icon and a Simulator icon.

Double-click the Simulator icon to start the simulator. The Simulator
window appears:

The Simulator Window

Developer’s Guide – RIM 950 Wireless Handheld™

Tools guide — RIM 950 Wireless Handheld simulator 21

1. First, select a simulation platform from the Options menu. The
Configure… item in the Options menu allows you to add new

simulation platforms or ve rsions if you have them available a s RIM
OS DLLs. The Configure… item also allows you to specify the path to
OSLOADER.EXE. Other than selecting a simulation platform, the
defaults should be appropriate.

2. When you are ready to start the simu lation, choose Start Simulation
from the Control menu. You will be prompted for command line
switches for the OSLOADER.EXE program; see below for descriptions
of the possible switches.

3. After specifying the switch es (if any), you will be prompted to load
Application DLLs via a file selector w indow. You can load more tha n
one file at a time by clicking Open after each file or by selecting more
than one file in the window and clicking Open.

4. Once all files have been loaded, click Cancel in this window; the
RIM Wireless Handheld simula tor will start.

Running the simulator from the command line

You can also start the RIM Wire less Handheld simula tor by running the
executable OSLOADER.EXE. (This executable is located in the SD K install
directory that you selected during the setup process.) The first parameter
to OSLOADER.EXE must be an

OS DLL, such as OSPGRMB.DLL.

You can optionally load applications automatically by naming them after
the OS DLL on the command line, if the directory (or directories)
containing the DLLs is specified in the Windows

PATH. For example:

OSLOADER.EXE [Switches] OsPgrMb.dll [applications]

If you don’t specify applications, you will be prompted with a file
selector window. You can load more than one file a t a time by clicking
Open after each file or by selecting more than one file in the wind ow a nd
clicking Open.

Once all files are loaded, click Cancel in thi s window; the simulator will
start.

Place the DLLs in your

PATH or place them in the same directory and use

that directory as the current directory when you execute the command.

Developer’s Guide – RIM 950 Wireless Handheld™

22 Tools guide — RIM 950 Wireless Handheld simulator

The following table summarizes the command line switches and
arguments, in alphabetical order; these are explained in greater detail
later in this section.

Switches Description

/An

Use

n sectors of flash me mory for OS and

application storage.

/Dn

Use

n sectors of flash memory for file

system data storage.

/E
/Fn
/Pf
/Ps

Erase flash allocation log.
Simulate

n kilobytes of flash memory.

Force prompt for more applications.
Always suppress prompt for more

applications.

/Rn

/RDIR=directory
/RSIM=addr

/Sn

Use serial port

Store messages in
Use

addr as the simulator's address.

n for RAP modem.

directory.

Use Windows serial port n in place of the
wireless handheld's physic al serial port.

/T[flags]

Set or suppress traps

Any argument that does not begin with / is taken as a file name, the
name of an application to be loaded.

Loading applications

Each DLL is a different application. The DLLs you load depend on which
RIM Wireless Handheld applications you want to simulate.

For example, a simple application t hat uses only the functiona lity of the
base API functions wi ll not de pend on other DLLs a nd can be l oaded by
itself. However, applications built with the User Inter face Engine require
loading the UI32.DLL file along with the UI-enabled applic ation.

There is a restriction: Each DLL loaded in a group mu st require only the
DLLs selected before or listed in the current set. Therefore, the
application with the most dependencies should be added last. This

Developer’s Guide – RIM 950 Wireless Handheld™

Tools guide — RIM 950 Wireless Handheld simulator 23

restriction does not hold if the required DLLs are in your PATH or the
working directory that was used to star t the simulator.

To simulate an application running wit h the fu ll R IM Wireless Hand held
messaging application, load a ll of the DLLs in the directory. This should
be the following DLLs:

• ADDRESS.DLL

• AUTOTEXT.DLL

• COREAPI.DLL

• CRYPTOBLOCK.DLL

• DATABASE.DLL

• MESSAGE.DLL

• RIBBON.DLL

• TRANSPORT_MDP.DLL

• UI32.DLL

Please refer to the specific API documentation for each of these DLLs for
more information.

Note

Note that SDKRADIO.DLL is not a standard application DLL for the
simulator; it is used when you want to use your RIM Wireless
Handheld as a modem (see Using the RIM Wireless Handheld as the
modem on page 30). Normally you will not load SDKRADIO.DLL into
the simulator.

Using the simulator

When you run the simulator, a window featuring a picture of the
wireless handheld appe ars on your screen. This main windo w contains
pictures of a keypad, a trackwheel, and a LCD. You can operate the
keypad and trackwheel from Windows, and the LCD will show you
what would be displayed on the actual wireless handheld.

Developer’s Guide – RIM 950 Wireless Handheld™

24 Tools guide — RIM 950 Wireless Handheld simulator

LCD Trackwheel

Keypad

The RIM Wireless Handheld simulator

Keypad

You can operate all keys on the simulator window’s keypad by clicking
them with the mouse. In addition, you can operate the keys on the RIM
Wireless Handheld keypad by using the corre sponding keys on the PC
keyboard.

ALT key

TheRIM Wireless Handheld simulator

ALT key

Alternate symbols for the keys (in red) can be accessed using the
However, due to the special function assigned to the

Developer’s Guide – RIM 950 Wireless Handheld™

BACKSPACE

key

SHIFT key

ALT key.

ALT key by

Tools guide — RIM 950 Wireless Handheld simulator 25

Windows, activate the wireless handheld 's ALT key by pushing the CTRL
key on your PC.

The current state of the Alt key is displayed on the up per right corner of
the simulator. A reverse-video ‘A’ will be d isplayed when the

ALT key is

in effect.

SHIFT key

Press and release the

CAP or SHIFT key to capitalize the next key you

press. When this key is pressed, a n up arro w will a pp ea r on the top r ight
corner of the screen.

PC mode and Pager mode

The keyboard can be toggled between two modes: PC mode and Pager
mode. In PC mode (the default), all symbols can be entered, and the
simulator internally generates the keystrokes required to produce each
symbol. In Pager mode, however, only the keys present on the wireless
handheld can be used.

The Keyboard menu

Enabling backlighting

To switch on the backlighting, press the

ALT key three times successively;

the background of the LCD turns blue. The backlighting will stay on
until an idle period of about 10 seconds has been de te cted.

Trackwheel

The trackwheel has two functions: to be rolled, and to be used as a
pushbutton. You can operate the trackwheel using either the mouse or
the arrow keys on the keyboard

Developer’s Guide – RIM 950 Wireless Handheld™

26 Tools guide — RIM 950 Wireless Handheld simulator

Using the keyboard

The left and right arrow buttons on the PC keyboard simulate the
clicking of the trackwheel while the up and down arrow buttons
simulate the rolling.

Using the mouse

To perform the roller action using the mouse, click the trackwheel with
the left mouse button and drag vertically.

To click the trackwheel, depress the right mouse button. This action
allows the trackwheel to be rolled and clicked independently. In
addition, the simulator provides full support for the Microsoft
Intellimouse. You must first ensure that the correct Microsoft
Intellimouse drivers are installed. Using t he Microsoft Intellimouse, the
mouse’s roller can be used to operate the wireless handheld’s
trackwheel. However, the Intellimouse roller only works when the
mouse pointer is over the RIM Wireless Handheld simulator.

Due to Windows filtering of events, sometimes trackwheel and right
mouse button clicks are not handled during, and immediately after
rotating the Intellimouse mou se wheel. This anomaly only occurs whe n
using the trackwheel on the Intellimouse.

LCD

The LCD size can be toggled between full size (with correct aspect
ratios), and actual size (how readable a display screen will be on the
actual hardware). To change the size of the LCD on your simulator,
select Display > Change size.

Simulation menu

The RIM Wireless Handheld simulator allows you to simulate the holster
environment as well as various battery conditions of the Wireless
Handheld. Under this menu, select the cond itions you want to simulate.

Developer’s Guide – RIM 950 Wireless Handheld™

Tools guide — RIM 950 Wireless Handheld simulator 27

The Simulation menu

In the Radio Simulator Control panel dialog box, you can simulate
various coverage conditions.

Simulating serial I/O

The simulator has the ability to use one of the PC’s serial ports as the
RIM Wireless Handheld’s serial port. This option must be enabled via

/S command line option when you start the simulator. If no /S

the
option is specified or the serial port is not available at startup, you
cannot open or use the serial port fr om the applications ru nning on the
simulator.

When opening a seria l port on the PC, the orientat ion of the serial port
on the PC is as it would normally be. Thus, if you wish to simulate a
connection between the RIM Wireless Handheld and the PC via the
provided serial port, you must connect the PC’s serial port to another
PC’s serial port via a null modem cable to communicate. If both your
simulator and your application connected to the RIM Wireless Handhe ld
are running on the same physical PC, they must be connected to
different physical serial ports on your PC and the serial ports must be
linked using a null modem cable.

Flash simulation files

In order to simulate the non-volatile nature of flash memory, the RIM
Wireless Handheld simulator loads the flash contents from a file on
startup and saves them bac k to t he file on exit. The sta te of t he simula ted
flash is preserved in a file in the working directory named
OSXXXYY.DMP, where XXX is one of PGR (pager), HH (handheld), or OEM,
and YY is one of MB (Mobitex) or DT (DataTAC).

Developer’s Guide – RIM 950 Wireless Handheld™

28 Tools guide — RIM 950 Wireless Handheld simulator

When the RIM Wireless Handheld simulator starts, it determines the
simulated flash size. The size can be specified using the /F command
line option and the default size is 2048 KB. The simulator now checks to
see if there is a file named OSXXXYY.DMP (where XXXYY corresponds to
the current simulation platform) in the working directory. If the file
exists, its size must be less than or equal to the simulated flash size,
otherwise the simulator will report an error and abort. If the file does not
exist, the RIM Wireless Handheld simulator will create it, and its size
will be equal to the simula ted flash size. Regardless of whether the DMP
file existed at startup, the RIM Wireless Handheld si mulator will always
save the simulated flash contents on exit.

If the DMP file is smaller than the flash size, it will be extended with
0xFF’s up to the flash size. This will invalidate any flash allocation
information present in the file. This facility is provided for use with old
DMP files only and should be avoided in normal oper ation.

You must be careful in the design of your algorithms so as to minimiz e
the impact of the flash file system on their performance. The
performance of your algorithms will depend on the file system.
Therefore, you may have to alter your design so that it is compatible
with the RIM Wireless Handheld file system. More information is
available elsewhere in this guide.

Notes on older simulator versions

With older simulator versi ons, the flash file was named FILESYS.DMP.
If you wish to use an old flash file in the new version of the si mulator,
simply rename it to the form

OsXxxYy.dmp, a nd place it in the working

directory. Note that this is only guara nteed to work if the fla sh file is the
same size as the flash size for the simulator. If the file is larger tha n the
flash memory of the device, the simulator will warn yo u and not load the
file. If the file is smaller than the flash memory of the device, the
simulation may work correctly. If in doub t, erase the DMP file.

Also note that older versions of the simulator will create a
FILESYS.DMP that is the size of the file system, while newer versions of
the simulator will create a DMP file that is the same size as the flash
memory of the device that is being simulated. Newer versions of the
simulator default to a 2048 KB flash size, while older versions default to
a 1024 KB flash size.

Developer’s Guide – RIM 950 Wireless Handheld™

Tools guide — RIM 950 Wireless Handheld simulator 29

Flash allocation

The available flash memory (either simula ted or real) is divided int o four
areas:

• File system data area

• Unused area

• OS and application code area

• Fixed use area

Areas are allocated by writing an entry to a Flash a lloca tion log, whic h is
a special data structure stored within the fixed use area. The log may be
completely erased using the /E command line option. Flash allocation
information will no longer exist and a default allocation will be used
until a new allocation is performed.

A new entry is added to the log whenever one or bo th of the /D or /A
command line options are specified. Whe n all of the a vailable lo g entries
have been used, the RIM Wireless Handheld simulator will not allow
any more entries to be written and the log is erased.

If the simulator finds no valid log entry in the DMP file, a default flash
allocation is used.

Modem simulation us ing a physical modem

When simulating the radio network using a RAP modem or the RIM
Wireless Handheld, the RAP modem or w ireless handheld bec omes the
simulator’s radio modem. When data packet is sent by an application,
the packet is sent to the physical modem via the serial port. Packets
received by the physical modem, as well as status information, are sent
through the serial port to the simulator running on t he PC, and passed
on to the applications.

When using the SDK with a physical modem, the applications are
essentially dealing with a live radio network. Dealing with a live
network requires that you have a RAP modem or the RIM Wireless
Handheld with a valid subscription and that you are operating in an area
that has radio coverage.

Developer’s Guide – RIM 950 Wireless Handheld™

30 Tools guide — RIM 950 Wireless Handheld simulator

When using a physica l modem with the simu lator, you cannot simula te
different coverage situations in software; you are limited by what the
modem is actually experiencing. To simulate different coverage
situations, change the position of the antenna or obstruct the antenna's
coverage. The dialog box for manually controlling radio coverage
situations is unavailable when running the simulator with a RAP
modem, as its behaviour is determined by what the actual modem
experiences on the live network.

Command line options for modem simulation using a RAP modem

/R1 /R2 /R2...

This option sets the radio serial port number. With this command
line option, the simulator simulates network traffic by
communicating to a real modem.

The simulator is able to communicate with the Allpoints wireless modem
from Megahertz and all RIM modem products for your network,
including the RIM 957, the RIM 902M OEMs, and the RIM 950 Wireless
Handheld.

Using the RIM Wireless Handheld as the modem

The RIM Wireless Handheld is an integrated embedded system and
radio modem. Although radio functionality is available to applications
running on the Wireless Handheld, this functionality is normally not
available through a serial connection. To allow the SDK’s Windows
simulator to communicate with the RIM Wireless Handheld, a special
program, SDKRADIO.DLL, must be loaded onto the RIM Wireless
Handheld to enable it to communicate radio inf ormation over the serial
port. You can load SDKRADIO.DLL with the PROGRAMMER.EXE utility
by typing:

PROGRAMMER LOAD SDKRADIO.DLL

When SDKRADIO.DLL is loaded, it automatically detects when the
simulator is attempting to contact the RIM Wireless Handheld, and
opens the COM port for communication. When not connected to the
Windows simulator, the SDKRADIO.DLL does nothing. It can coexist
with your regular applications on the RIM Wireless Handheld without
harmful effects.

When using the wireless handheld as your modem, remember that the
RIM Wireless Handheld was not designed as a high-capacity modem.

Developer’s Guide – RIM 950 Wireless Handheld™

Tools guide — RIM 950 Wireless Handheld simulator 31

Battery capacity, as well as other factors cause the rate of packet delivery
to be cut back after sending large amounts of data. In addition, when
sending large amounts of traffic with the RIM Wireless Handheld, its
battery life may be conside rably shortened. During tra nsmission of data
packets, for example, the RIM Wireless Handheld requires three times
more power than normal average power consumption.

Modem simulation using the file system

Unless you follow the inst ructions given in Modem simulation u sing a
physical modem, the simulator uses the file system to simulate the
modem. This allows you to test the c ommunications functionality of a n
application without actually connecting to a radio network. This
simulator offers the follow advantages over using the real network:

• No external hardware is required

• No network account is r equired

• Coverage situations can easily be created

• It is possible to monitor what is sent without the need for extra

tools

• It is easy to write programs to send and receive data packets as a

host side

When simulating the network using the file system instead of
communicating data packets across a live network, the modem
communicates packets across the fi le system. To send a d ata packet, the
simulator creates a file whose name indicates the destination address.
Conversely, the simulator checks for the presence of files whose name
indicate that they contain data addressed to it.

A separate control panel window, the
box, is available which allows the user to set coverage conditions.

For information specific to your network, such as the default simulation
environment, see the Radio API Developer's Guide.

Command line options for modem simulation using the file system

The simulation envir onme nt, wit h no co mma nd l ine o ptio ns, wi ll de fa ult
to simulating in the current directory, with the

dialog box not visible upon sta r tup.

panel

Developer’s Guide – RIM 950 Wireless Handheld™

Radio simulation control panel dialog

Radio simulation control

32 Tools guide — RIM 950 Wireless Handheld simulator

/RSIM=<address>

This option sets the address to simulate.

/RDIR=<directory>

This option sets the directory to use for the simulation. The default
directory is the curre nt director y. Radio sim ulators m ust point at the
same directory in orde r to be able to communicate with each other.

Simulating email

Sending and receiving email through the MESSAGE.DLL requires a
service book entry; the only way to get a service book entry onto the
simulated RIM Wireless Handheld is to register with RIM server
software. In turn, this requires a RIM Wireless Handheld with an active
account.

The easiest way to register your simulated RIM Wireless Handheld
device is to use your RIM Wireless Handheld as a modem; you can then
register the simulated RIM Wireless Handheld with the RIM server
software.

If your application uses the Radio API calls directly, you do n't need to
register the simulated RIM Wireless Handheld; registration with the
server is only required if your application uses the calls from the
Messaging API.

Radio simulation c

When the

/RDIR=<ADDRESS> or /RSIM=<directory> options are used,

ontrol panel dialog box

the dialog box for controlling network traffic is automatically made
visible. This dialog box can also be invoked, or brought to the
foreground, by selecting

Radio simulator control panel from the Simulation

menu.
The specifics of the radio simulation control panel dialog box depend

upon the wireless network you are using. See the Ra dio API Developer's
Guide for information such as:

• Simulation file protocol

• Format of the files simulating data packets

• Limitations of the simulatio n

• Specific behaviors of the simulation

Developer’s Guide – RIM 950 Wireless Handheld™

Tools guide — RIM 950 Wireless Handheld simulator 33

• Guid eli nes for writi ng a ho st-sid e applica tion to s imul a te the
network

This section describes the network sim ulation in general terms.
The control panel c onsists of two pa rts: reception and transmissio n. The

Reception section of the dialog box al lows you to set whe ther or not the
modem is in coverage. The Transmission sectio n allows you to set the
success rate for packet transmission.

Reception section

In the Reception section; you may choose to have the modem out of
coverage or in coverage; if you have the modem in coverage, you can
control the Received Signal Strength Indicator (RSSI) by sliding the
control bar back and forth. Note that the signal strength varies from -120
dBm to -50 dBm (dBm is d B with respect to milliwatt s). A signal of -120
dBm is extremely weak, and the modem typically los es coverage before
reaching this number. A signal of -50 dBm is stronger than you a re likely
to see on the actual network.

You may check for data packets immediately; many networks implement
a power save mode, where the network periodically indicates which
modem to send to. To conserve power, modems only turn on their
receivers during the periods they are being sent data . To simulate this,
the program only checks for packets every 10 seconds. You can force a
check for packets by selecting the button.

This window also indicates the current status and the number of data
packets received.

The following statuses are possible in the Active Status field:

State Description

Radio Off The radio is turned off.
Turning Off The radio is in the proce ss of turning off.
Stop Reception Radio reception is stopped

RadioStopReception has been called).

(

Active The modem is in coverage on the network.

Developer’s Guide – RIM 950 Wireless Handheld™

34 Tools guide — RIM 950 Wireless Handheld simulator

State Description

Checking... The radio is checking for data on a 10 second

interval, or the
pressed.

Checking for 10 sec. The radio is checking continuously because

of a recent data packe t sent or received.

Out of coverage The modem is out of cover age.

Transmission section

In the Transmission section, you may choose how frequently data
packets are transmitted successfully. You may choose to have all
transmits succeed, to be prompted f or each data packet’s success ( useful
for simulating very long transmit delays), or have a percentage of
packets transmit successfully, packets ch osen randomly.

This section of the dialog box also contains the Transmit status field,
which indicates the status of the last or current packet that was
submitted for transmission. It can be one of the following states:

Check now button was

State Description

Pending The modem is currently attempting to send a

submitted packet.
Transmit Done The last packet was successfully sent to the network
Transmit Failed The last packet failed to reach the network.

Simulator command line options

The SDK environment can be configured using the following command
line arguments:

/Sn

Use Windows serial port n in place of the wireless handheld’s
physical serial port. Without this argument, no serial port will be
used, and applications will be prevented from opening a serial port.

Examples:

/S1 /S2 /S3 /S4

Developer’s Guide – RIM 950 Wireless Handheld™

Tools guide — RIM 950 Wireless Handheld simulator 35

/Rn

Tell the RIM Wireless Hand held simulator to use serial port n for a
RAP modem. The RAP modem is used in place of the physical RF
hardware in the simulation environment. If this argum e nt is omitted,
no serial port is used, and simulated rad io communications will not
be possible.

Examples:

/R1 /R2 /R3 /R4

/Pf

Force prompting for more applications By default, t he RIM Wireless
Handheld simulator prom pts for applications on startup only if no
applications are specified on the command line. Canno t be used with

/Ps.

/Ps

Suppress prompting for more applications. By default, the RIM
Wireless Handheld simulator prompts for applications on startup
only if no applications a re specif ied on t he command line. Cannot be
used with

/Pf.

/Fn

Simulate n kilobytes of flash memory. If this argument is omitted,
the default size of 2048 KB is used. Note that older versions of the
simulator will have a default flash size of 1024 KB.

Examples:

/F1024 /F2048

/E

Completely erase the flash allocation log. Flash allocation
information will no longer exist a nd a d efault all ocation w ill be used
until a new allocation is specified. This option has to be used when
all Flash allocation log entries have been used .

/Dn

Simulate n sect ors of 64 KB each for file system data storage. If this
option is omitted, the previous amount is preserved, unless /E is
simultaneously specified. If /E is specified, a default amount is used.
This can simulate the result of a PROGRAMMER ALLOC command.

Example:

Developer’s Guide – RIM 950 Wireless Handheld™

36 Tools guide — RIM 950 Wireless Handheld simulator

/D15

/An

Simulate n sectors simulat ed flash memory (in 64 K B sectors) to be
used for OS and applicatio n code storage. If this option is omitted,
the previous amount is preserved, unless
specified. If

/E is specified, a default amount is used. This can

simulate the result of a PROGRAMMER ALLOC command.
Example:

/A16

/T[flags]

Modify the stale pointer trapping behaviour of the RIM Wireless
Handheld simulator.

By default, the RIM Wireless Handheld simulator will, at various
intervals, move the location of the si mulated f ile sys tem o n yield an d
on file writes. The simulator then maps the old location as invalid
memory. Used pointers to the file system that should have been
reloaded from the handle table result in page faults. The /T option
can be followed by these symbols:

/E is simultaneously

+ Turn subsequent options on

- Turn subsequent options off

W Trap on flash write

Y Trap on yield

By default, both options are turned on.
Example:
This enables a trap on flash write and disables the trap on yield:

/TW-Y

<Filename>

Any argument that does not begin with a slash is assumed to be an
application filename. Multiple application filenames may be
specified on the command line. File names conta ini ng spaces must be
surrounded by quotes.

Example:

Developer’s Guide – RIM 950 Wireless Handheld™

Tools guide — Program loader 37

In this example, APP2.DLL is assumed to reside in the working
directory

C:\dev\app1.dll app2.dll.

Debugging hints

Some tips for debugging a pplications using the simul ator (and the RIM
Wireless Handheld itself).

• When the machine fails and requests a reset, yo u can often
get additional informati on by typing
contents of different registers.

• You may be able to get additional information on a reset
request by typing
unresolved OS call, this co mmand displays the name of the
call.

• For some reset requests, pressing the R key will cause a
reset.

• You can force a reset request with Alt-Shift-Backspace.

info. If the failure was caused by an

dbug. This displays the

Program loader

The RIM 950 Wireless Handheld SDK includes a command line utility
(PROGRAMMER.EXE) to load the compiled Windows DLLs onto the
physical wireless handheld . This utility will take the s ame DLL that was
debugged under Windows, and perform a ll necessary steps to load it on
to the Wireless Handheld. The utility can also be used to manipulate
applications that are already installed on the wireless handheld.

The PROGRAMMER.EXE utility perf orms many of the application loader
functions of the Desktop Manager utility shipped with every RIM
Wireless Handheld; it also performs tasks more suite d to programmers’
needs.

Developer’s Guide – RIM 950 Wireless Handheld™

38 Tools guide — Program loader

Program loader command line options

The PROGRAMMER.EXE uti lity requires a set of command line options to
denote serial port configuration, the action required, and what files are
to be manipulated. The command line templa te is:

PROGRAMMER [[-Pport] [-Sspeed] [-Wpassword][command]

If no command action is given, PROGRAMMER.EXE displays help
information.

Universal command line options

The -P, -S and –W options may be given with any action.

-Pn

Use serial port n. The default is COM1.

-Sspeed

Set baud rate for the conne ction to the RIM Wire less Handheld. The
default is 115200 baud.

-Wpassword

Use given password, if password protec tion has been enabled on the
RIM Wireless Handheld.

Program loader commands

The following command actions are supported:

Command Description

LOAD [-S] [-G] [-V]
[-M] [-D] apps or
( groups )

ERASE [-A|-E] apps

DIR [-S]

HELP [command]

Load applications or groups of
applications on the RIM Wireless
Handheld

Erase applications and optionally OS
both from Wireless Handheld

List applications currently on the
Wireless Handheld

Display help information, possibly
about command

Developer’s Guide – RIM 950 Wireless Handheld™

Tools guide — Program loader 39

Command Description

BATCH filename

Run PROGRAMMER.EXE commands
stored in a file

VER

MAP [-F] [-R]

LOADFS

SAVEFS

WIPE [-F | -A]

NUKE

ALLOC [-E]
[-D sectors]
[-A sectors]

LOAD command

List applications currently on the
Wireless Handheld, including version
information

Display detailed flash and RAM maps

Load file system data from a .DMP file
onto RIM Wireless Handheld

Save file system data from RIM
Wireless Handheld into a .DMP file

Irreversibly erase applications or file
system or both from RIM Wireless
Handheld

Erase all flash on RIM Wireless
Handheld, including file system,
applications, and password

Moves breakpoint between
application memory and file system
memory.

LOAD [-S] [-G] [-V] [-M] [-D]<apps or groups>

Where

-S specifies tha t symbol informa tion for all new applica tions should be

appended to a DEBUG.DAT file in the current directory.

-G specifies that the first applic ation or group of applica tions should be

grouped with the last group found on the RIM Wireless Handheld.

-V specifies checking file versions. Normally PROGRAMMER only checks

API versions and dependencies, since developers are unlikely to
update the file information for every build.

-M specifies mappings of unresolved OS calls should be displayed. As

of version 1.7, the loader maps unresolved OS calls to an internal

Developer’s Guide – RIM 950 Wireless Handheld™

40 Tools guide — Program loader

API,

RimCatastrophicAPIFailure(). In all cases, other

unresolved links fail; only unresolved OS calls can be mapped.

-D specifies that unresolved OS calls should not be mapped to

RimCatastrophicAPIFailure().

<files or groups> are one or more files or groups of files to be

loaded onto the RIM Wireless Handheld. Individual files are specified
alone. Groups of files are enclosed in parentheses, brackets, or braces.
There must be spaces surrounding the brackets, as in the example below.

Description

The

LOAD command loads new applications or the application

environment onto the RIM Wireless Ha ndheld. Any old a pplications by
the same name are erased. A pplications can and should be grouped to
reduce wasted space on the RIM Wireless Handheld. However, if an
application is to be rep la ced sepa rate from ot her appli ca tions o n t he RIM
Wireless Handheld, it should be placed in its own group.

Note

When loading or replacing the application environment
(PAGER950.BIN), it must be specified first on any Load command.

Grouping of programs

Because the flash memory can onl y be erased one 64 kilobyte sector at a
time, any application that is to be erased and have its space reclaimed
must not overlap with oth er applications in the same 64 kilobyte sector.
Grouped applications are contiguous, without regard to the 64k sector
boundaries. As such, when inval idating an application that is part of a
group, the space cannot be rec laimed without erasing other applications
as well. Applications that ar e not grouped each occupy one or more 64
kilobyte sectors, with the remainder of the last sector used being wasted.

Note

The ability to group programs is specific to the PROGRAMMER.EXE.
Although the desktop loader program will recognize groups already
on a RIM Wireless Handheld, it cannot load files in groups.

Examples

The following command will load the application environment and
applications onto the RIM Wireless Ha ndheld:

Developer’s Guide – RIM 950 Wireless Handheld™

Tools guide — Program loader 41

PROGRAMMER LOAD PAGER950.BIN UI32.dll ( Address.dll
AutoText.dll Message.dll Options.dll
Transport_RTP.dll )

The following command wi ll load a new calculator application, grouping
it with the other applications:

PROGRAMMER LOAD -G Calculator.dll

ERASE command

ERASE –A
ERASE <application names>

Where

-A specifies tha t all applicatio ns and the applicat ion environment a re to

be deleted.

<application names> are the names of specific applications to be

deleted.

Description

The

ERASE command erases applications currently loaded on a RIM

Wireless Handheld. The names are not case sensitive and can be
obtained using the

PROGRAMMER DIR command.

The space occupied by erased applications is only reclaimed when the
entire group that it resides in is erased.

Example

The following command will erase all applications on the RIM Wireless
Handheld:

PROGRAMMER ERASE -A

The following command will erase only the address book application:

PROGRAMMER ERASE ADDRESS.DLL

DIR command

DIR [-S]

Developer’s Guide – RIM 950 Wireless Handheld™

42 Tools guide — Program loader

Where

-S specifies a short listing of only the application names.

Description

The

DIR command generates a listing of the applications currently

loaded on a RIM Wireless Handheld . Unless the
this listing includes the names of the applications and the amount of
flash and RAM occupied by the applications. The applications are
grouped as they are grouped on the RIM Wireless Handheld.

Example

The following command will list the applications on the RIM Wireless
Handheld:

PROGRAMMER DIR

VER command

VER

-S option is specified,

Description

The

VER command generates a listing of the applications currently

loaded on a RIM Wireless Handheld, including version information.
"Version information" includes release tags and build times. The
applications are grouped as they are grouped on the RIM Wireless
Handheld.

Example

The following command will list the applications on the RIM Wireless
Handheld, including release tags and build times:

PROGRAMMER VER

BATCH command

BATCH <batchfile>

Where

<batchfile> is the name of a file containing commands.

Developer’s Guide – RIM 950 Wireless Handheld™

Tools guide — Program loader 43

Description

The

BATCH command allows multiple commands to be placed in a file

and executed with a single, short command. This command is useful
when repeatedly performing the same load process, and for overcoming
the fixed limit imposed on command lines.

The batch file may contain one or more of the

BATCH commands. The results are committed to the RIM Wireless

LOAD, ERASE, DIR, or

Handheld only if all comma nds are successfully completed . Each line of
a batch file can be no more than 256 characters long. Single commands
can be broken into multiple commands, if you have long file names.

WIPE command

WIPE [-F | -A]

Where

-F specifies that t he file system should be wiped.

-A specifies that t he a pplication area should be wiped.

If no option is specified, both the file system a nd application are wiped.

HELP command

HELP [<command>]

Where

<command> is the name of the c ommand f or whic h you want help, or the

word

errors.

Description

The

HELP command invokes the bu ilt-in help syste m. With no options a

generic help message is produced. Help for a specific command can be
obtained by specifying it as an option. Help ab out error messages can be
obtained by specifying the

errors command.

If the output is not redirected to a file, the help system uses a built-in
paging system. Press any key at the

Developer’s Guide – RIM 950 Wireless Handheld™

<MORE> prompts.

44 Tools guide — Program loader

Example

To get help on the

LOAD command, type:

PROGRAMMER HELP LOAD

To get help on errors, type:

PROGRAMMER HELP ERRORS

To get a main help page, type:

PROGRAMMER HELP HELP

ALLOC command

ALLOC [-E] [-D <sectors>] [-A <sectors>]

Where

-E specifies the File Allocation Sector to be erased before writing an

entry.

-D<sectors>

specifies the new size of the file (or data) area in flash sectors; the
minimum size is 1.

-A<sectors>

specifies the new size of the OS and applications area in flash
memory.

If no options are specified, the command reports on current usage.

Description

This command writes a new entry to the Flash Allocation Log and moves
the breakpoint between File area and the OS and applications area of
memory. It is possible to move onl y one, but then you would have an
unused sector.

The command will only reduce the size of an area if the sectors to be
removed are completely blank. Th is is rarely a pr oblem wit h the OS and
applications area, but may be a problem with the File area , because there
are no guarantees about placement of information.

Developer’s Guide – RIM 950 Wireless Handheld™

Tools guide — Program loader 45

When the File Area size is decreased, at least one blank sector must
remain within the area. Back up and pack your da ta before issuing the
ALLOC command.

Troubleshooting

Most error messages are self-explanatory. The following errors deserve
more discussion.

Error: Unable to connect to device

An error occurred trying to initiate communications with the RIM
Wireless Handheld. Make sure that it is connected to the computer
properly.

Error: Insufficient flash or RAM

There is not enough flash or RAM memory remaining to load a new
application. Make sure that you have erased any old applica tions. If you
have been erasing and loading often, you may have fragmented your
flash space. In this case, try erasing all applications and start again.
Loading applications as part of the same group will cause them to
occupy flash more efficiently.

Error: Relocation failed

It was not possible to rel ocate an application. T his typically occurs if the
application environment (PAGER950.BIN) is not specified first in a
command. When loading or replacing the application environment, it
must always be specified first in the

Error: Bad load

This error occurs when a
a serious error that requires the RIM Wireless Handheld to be reset and
its operating system reloaded. In order to reset the RIM Wireless
Handheld, insert a small p ointed instrument, such as a paper clip, into
the small reset hole on the back of the RIM Wireless Handheld. To reload
the operating system, follow the example instruction in the
on page 39 of this manual.

Developer’s Guide – RIM 950 Wireless Handheld™

LOAD is interrupted or done improperly. This is

LOAD command.

LOAD section

LOAD

46 Tools guide — Program loader

Error: Not all imports resolved

An application is requesting imports from another application that
cannot be exported by the other applica tion. Ensure t hat you are loa ding
all applications that provide the exports t ha t you need.

Developer’s Guide – RIM 950 Wireless Handheld™

Tools guide — DLLUtil 47

DLLUtil

The DLLUTIL.EXE utili ty provides informa tion about DL Ls as they w ill
be when loaded onto the R IM Wireless Handheld, simila r to the output
of PROGRAMMER DIR and PROGRAMMER VER. There are two forms of the
command:

DLLUTIL SIZE [-R] files
DLLUTIL VER files

files argument is a list of DLLs and/or OS files, and can contain

The
wildcards (* and ?).

In the first form (SIZE), the utility displays a dump of flash memory,
RAM, and thunk resources. With the –R switch, the utility displa ys the
size of the DLLs without the
loaded. This is how programs were loaded by versions of the
PROGRAMMER.EXE utility 16 through 18. With out –R, the utility displa ys
the sizes as loaded by PROGRAMMER.EXE versions 20 and greater.

.reloc (DLL relocation) information

In the second for m (VER), DLLUTIL displays version information. Beside
each valid file, it lists versions for both imp orted and exported APIs. It
also lists valid operating systems along with file version information.

Conversion utilities

The SDK contains three small conversion utilities intended for creating
fonts and bitmaps for the RIM Wireless Handheld.

For information about usin g these utilities, see chapter 3 of the OS API
Developer’s Guide.

BITMAP

The BITMAP.EXE executable creates bitmap header file from a definition
file (with a .DEF extension). The header file is then included in a
resource DLL or an application.

Developer’s Guide – RIM 950 Wireless Handheld™

48 Tools guide — Conversion utilities

The syntax is:

BITMAP definition header

The definition file format is described in t he OS API Developer’s Guide,
under “Creating bitmaps.”

BMP2DEF

The BMP2DEF.EXE exec utable creates a definition file from an existing
bitmap (.BMP). The definition file can be turned into a RIM Wireless
Handheld bitmap header file using BITMAP.EXE.

The syntax is:

BMP2DEF bitmap definition

LCDFONTS

The LCDFONTS.EXE executable creates a font header file from a
definition file. The header file is t hen included in a resource DLL or an
application.

The syntax is:

LCDFONTS definition header

The definition file format is described in t he OS API Developer’s Guide,
under “Creating custom fonts.”

Developer’s Guide – RIM 950 Wireless Handheld™

An overview of the system — Conversion utilities 49

5.An overview of the

system

This section describes parts of t he RIM Wireless Handheld’s system for
developers, concentrating on the operating system.

When developing for the RIM Wireless Handheld, it’s important to
realize that the RIM Wireless Handheld has its own operating system.
Some of the features of the operating system (such as the use of flash
memory rather than a traditional file system) are based on the
requirements of a portable wireless device.

When developing applications for the RIM Wireless Handheld, you
should be aware of the following:

• A co-operative scheduler in the multitasking operati ng system

• Tasks and threads are used to run applications

• Because the OS is co-operative, each task must be able to yield so

that other tasks may use the CPU

• Tasks communicate using ME SSAGEs

• The system uses t wo types of memory; this is normall y hidden b y

the file system handles

• The user interface is somewhat different from a traditional GUI
interface; users and applications communicate through the task
wheel, the keyboard, and the display; applications may be selected
through the applicatio n r i bbon

• For some (but not most) applications, you may need to know
details of the underlying wireless network; see the Radio API
Developer's Guide for information about y our network. There are
a large number of APIs provided

The rest of this chapter describes these things in slightly more detail.

Developer’s Guide – RIM 950 Wireless Handheld™

50 An overview of the system — RIM co-operative scheduler

RIM co-operative scheduler

The RIM Wireless Handheld’s operatin g system ( OS) is desig ned using a
co-operative multitasking model. For more information on the operating
system and the OS functional specifications, see the RIM 950 Wireless
Handheld Operating System API Devel oper’s Guide.

Tasks and threads

A normal application is developed as a task or thread. In order to create
a new task:

PagerMain()

• a

• an application name must be chosen

• an application stack size must be specified

PagerMain()

Each
and is used to construct and initializ e objects needed by the application.
For more information and an example, see “Cod ing an application” on
page 55. For more information on creating new tasks, see the RIM 950
Wireless Handheld OS API Developer’s Guide.

function must be defined

function is called during the initialization process

Task yielding

Since the operating system is a co-operative multitasking model, the
PAGERMAIN() function (and all other code) must include a task yield
function call to allow other tasks to make use of the CPU. The
application can be resta r ted in a number of ways:

• In response to a
the real time clock)

• In response to a

• In response to a user selection through the Ribbon (selecting an

icon on the main scr een)

MESSAGE posted by a system thread ( for example,

MESSAGE posted to the task by another task

• In response to a user selection through t he Options List

Developer’s Guide – RIM 950 Wireless Handheld™

An overview of the system — MESSAGE concept 51

For more information on the MESSAGE posting process, see “MESSAGE
concept” below as well as the RIM 950 Wireless Handheld Operating
System API Developer’s Guide.

MESSAGE concept

The Operating System allows for inter-task communication through
posting and receiving

RimPostMessage(), RimSendMessage(), and RimGetMessage()

functions described in the RIM 950 Wireless Handheld Operating System
API Developer’s Guide. The

RimSendMessage() functions allow a ta sk or system service to send a
MESSAGE to a specific task or tasks. The RimGetMessage() function

allows a task to yield control of the CPU until a

PagerMain()

The
initialize the necessary app lication objects, followed by a message loop:
an infinite loop containing a
call the appropriate application function for each expected RIM
MESSAGE.

MESSAGES. For more information, see the

RimPostMessage() and

MESSAGE is posted for it.

function should include code to construct and

RimGetMessage() function and code to

If you're using the UI, a message loop function is included.

Memory use

The RIM Wireless Handheld co ntains two types of memory: RAM and
flash. RAM memory is volatile and can be accessed directly. Flash
memory is non-volatile and can be accessed either directly or i ndirectly
through calls to a file system. File system handles can be assumed to
always point to the appropriate data. Flash memory can be accessed
directly as if it were RAM, but with the follo wing two restrictions:

• Flash memory is read only memory.

• The data may move if the application code yields c ontrol of the

CPU (by either calling

RimGetMessage()

another application that does one of these things).

For more information on file system use, see the RIM 950 Wireless
Handheld OS API Developer’s Guide.

Developer’s Guide – RIM 950 Wireless Handheld™

,

by making a file system call, or by calling

RimTaskYield()

or

52 An overview of the system — User interface

User interface

The user can acquire data from the application through the RIM Wireless
Handheld’s LCD. In or der to use the LCD, the application must ma ke a
request to become the foreground task. F or more information on making
an application a foreground task, see the RIM 950 Wireless Handheld OS
API Developer’s Guide. Once the task has bec ome the foregrou nd task, it
can use OS level calls to display data on the LCD or alternatively use
higher-level objects defined by the UI Engine.

The application can acquire data from the user through the keyboard, a
system level device that posts a
application can acquire the inf or matio n b y gett ing t hat

RimGetMessage().

A RIM Wireless Handheld user can manually act ivate an application b y
selecting that application’s icon on the main screen. You create such an
icon by registering a name and a bitmap using the

RibbonRegisterApplication() function. The DEVICE_RIBBON will

then post a
the appropriate application code. For more information, see the RIM 950
Wireless Handheld Ribbon API Developer’s Guide.

MESSAGE to the application’ s task that can be used to invoke

MESSAGE whenever a key is pressed. The

MESSAGE through

The user can also activate an application manual ly by selecting its en try
in the Options List. Y ou cre ate such a n en try b y registe ring a name a nd a
callback function using the
calls the callback function that has access to the LCD (has the
foreground) through the Optio ns thread. This approach should only be
used to make application parameter changes and other changes of a
limited nature.

OptionsEntry

API overview

This section provides an overview of the RIM Wireless Handheld
Application Programming Interfaces (APIs), how they are organized,
and some of the features that can be used in RIM Wireless Handheld
applications.

Developer’s Guide – RIM 950 Wireless Handheld™

()

function. This function

An overview of the system — API overview 53

The following APIs are provided. All but the most trivial applications
will need to make use of the APIs described in the OS API Developer’s
guide and the User Interface Developer’s Guide.

API Description Documented in

Address Book

API

access to the database used by the
Address Book application; create,

Address Book

API
edit, and retrieve contact
information

AutoText API

Database / File

system API

Database API

Keypad API

LCD API

Messaging API

Options API

access to the AutoText application;

AutoText API
customize the editing of editable
user text

access file functions; the file

OS API
system on the RIM Wireless
Handheld is non-standard, to
make better use of resources

access to the database functions;

Database API
define new record s, and to create,
edit, and retrieve information
stored in the database

customize the keypad; actual

OS API
keystrokes are passed as messages
from the application server

low-level display functions , screen

OS API
buffers, and string management;
use the UI APIs for dialogs,
menus, and edit classes

access to email and other messages Messaging API
responsible for controlling system-

Ribbon API
wide programmingof the features,
such as the date, time, and
screen/keyboard settings

Radio

communications

API

Ribbon API

simplified access to ra dio network

Radio API
and status of packet
communications

register an application on the

Ribbon API
functions list in the HOME screen

Developer’s Guide – RIM 950 Wireless Handheld™

54 An overview of the system — API overview

API Description Documented in

Serial

communications

access and configure serial port on
the RIM Wireless Handheld

API

OS API

System services

API

User Interface

API

Access to thread handling,
messaging, and task switching,
memory allocation, timers, and the
system clock

Calls for high-level display of
information and handling input,
such as creating screens, menus,
and dialogs

OS API

User Interface
API

Developer’s Guide – RIM 950 Wireless Handheld™

6. Building applications

This chapter describes the basics of wr iting an application for the RIM
Wireless Handheld.

Coding an application

This section briefly outlines the required compo nents of an application
on the wireless handheld. The basic program structure essentially
consists of an infinite l oop that receives messages fro m the OS, and c ode
to process those messages.

For every RIM Wireless Handheld application:

• Create an entry point named

• Register the application, providing a version string and a stack

size

• Set up a message loop

• Define version information

• Build the application as a Windows DLL target

PagerMain()

The PagerMain entry-point function

Each RIM Wireless Handheld application must have an entry point
function named

void PagerMain( void )

The

PagerMain() f unction has the forma t shown in the exa mple on the

following page. The following guidelines will help you create the

PagerMain() f u nc tion:

PagerMain with the following prototype:

56 Building applications — Coding an application

• Begin the

PagerMain() function with the construction of any

permanent objects required by the application. Y ou should avoid
accessing objects in other DLLs because until the

PagerMain()

functions in these DLLs have ha d a cha nce to r un, the c onstr ucti on
of these objects may not have occurred.

• After this local initializa tion phase, call
the

PagerMain() functions of other tasks to run.

• After

RimTaskYield() is called, you can expect that the other

RimTaskYield() to a llow

tasks’ permanent objects have been created. Now call those
functions that make the
other tasks (for example,

PagerMain() function itself known to

RibbonRegisterApplication()).

• The function can display any user interface elemen ts that will be
visible to the user if the task is brought to the foreground.

• Finally, if your application needs to respond to

MESSAGES posted

by other tasks or by syste m devices (such as the real time clock),
include an infinite loop containing a

RimGetMessage() task yields control of the CPU unt il a MESSAGE

RimGetMessage(). The

is posted for the task.

For more information on

MESSAGES, system devices, and task yielding,

see the RIM 950 Wireless Handheld Operating System API Developer’s
Guide.

Registering the application

RIM Wireless Handheld applications must have two variables defined
globally — the version string and the stac k size.

The version string is used to register the application with the task
switcher in the operating system. The name will appear when the task
switcher is run. The definition should look like this:

char VersionPtr[] = "My Application";

The stack size is used by the system when creating the initial thread for
the application. The value should be sized accord ing to the needs of your
application (the
definition should look like this:

int AppStackSize = 4096;

Developer’s Guide – RIM 950 Wireless Handheld™

RimStackUsage() call will help with this). The

Building applications — Coding an application 57

Here is some example PagerMain() code for an application that makes
use of the database:

#include <Pager.h>
#include <Ribbon.h>

//Definition of bitmap registered with ribbon
#include <bitSample.h>

char VersionPtr[] = "Database Sample";
int AppStackSize = 5000;
// Function which creates the main thread
void

PagerMain( void )
{

// Yield to let other applications initialize
RimTaskYield();

// Register the application with the Ribbon
// so an icon is shown on the main screen
// The & designates 'D' as the hotkey.

RibbonRegisterApplication( "&Database Sample",

NULL, 0, 0 );

// Initialization complete:
// set up LCD and enter message loop
.
.
.

};

Entering the message loop

Handheld applications spend a grea t deal of time in the message loop.
This code block should get required applicatio n messages and perform
required operations. It is n ot necessary for all applica tions to react to all
messages.

If your application makes use of the UI engine, there are several routines
for processing specific kinds of messages (such as
and

ProcessMenu()).

If you need to write a message loop, the typical structure for this loop is
a non-terminating loop with a switch statement to delegate message
processing to differ ent functions. For example:

Developer’s Guide – RIM 950 Wireless Handheld™

ProcessScreen()

58 Building applications — Coding an application

#include "Pager.h"

void PagerMain( void )
{

// initialization as in previous section
.
.
.
// Message loop
MESSAGE msg;

// perform initialization
for (;;) {

RimGetMessage( &msg );
// respond to events
switch( msg.Device ) {
case DEVICE_SYSTEM:

// handle SYSTEM messages
break;

case DEVICE_TIMER:

// handle TIMER messages
break;

case DEVICE_KEYPAD:

// handle KEYPAD messages
break;

}

}

}

Note

Applications are not required to be strict state machines.

It is possible to call RimGetMessage() from anywhere in the code. For
more complex programs, e very screen of your program should have its
own message loop. Messages tha t do not pertain to the screen, such as
radio messages, should be handled by callin g a messa ge hand ler, or even
a separate thread.

Becoming the foreground task

Only foreground tasks may displa y on the screen, so an application that
wishes to display data must first become the foregrou nd ta sk.

In this example, the applica tion should be brought to the foreground if
the user activates the appli ca tion by selec ti ng an ic on on t he main sc ree n.
When the user selects the icon, the OS sends a

Developer’s Guide – RIM 950 Wireless Handheld™

MESSAGE to the

Building applications — Coding an application 59

application from the RIBBON device, with the event set to

RIBBON_GRAB_FOREGROUND. If we get a RIBBON message, we call

RimGetCurrentTaskID()for the current task handle. We bring the

application to the foreground using

if( msg.Device == DEVICE_RIBBON ) {

if( msg.Event == RIBBON_GRAB_FOREGROUND ) {

// Bring this application to the foreground
// so it can use the LCD
RimRequestForeground( RimGetCurrentTaskID() );

}

}

RimRequestForeground().

Returning from the
switcher, but it’s more appropriate to return to the ribbon with

RibbonShowRibbon(). This also gives up the foreground.

PagerMain() call will return the user to the task

Using the Ribbon API

Instead of a system menu, the RIM Wireless HandheldRIM 950 Wireless
Handheld uses a simple ribbon interface to select applications. To add
your application to the ribbon:

1. Add

2. Select Pr oject > Settings and click on the Link tab. Add RIBBON.LIB

3. Call the

Your application can return to the ribbon by calling

RibbonShowRibbon().

#include <ribbon.h> to the beginning of your program.

to the Object/Library Modules field before LIBC.LIB.

RibbonRegisterApplication() function at the beginning

of

PagerMain(), before the program enters the message loop. See the

RIM 950 Wireless Handheld SDK Ribbon API Developer’s Guide for
more information on this function.

Handling user input

User input can be handled at the low level, but this is inefficient. We
presume you’re using the UI Engine.

Developer’s Guide – RIM 950 Wireless Handheld™

60 Building applications — Coding an application

If the user presses a key, the OS sends a
the

KEYPAD device. If we get a KEYPAD message, we p ass the MESSAGE to

the UI Engine, which returns a result code:

if( msg.Device == DEVICE_KEYPAD ) {

// Let the UI process the message
result = m_ui_engine.HandleInput( message );
//Process UI Engine result

}

MESSAGEs resulting from a key being pressed on the keyboard ar e sent

only to the foreground task.
If the UI Engine returns

menu. If the UI Engi ne returns
the

BACKSPACE key, in which case we want to return to the main screen

(

RIBBON).

if( result == CLICKED ) {

// Set up, display, and handle menu result
}
if( result == UNHANDLED ) {

//Check for the backspace key.

//If the user pressed backspace

//we want to go to the home screen

if( message.Event == KEY_DOWN &&

message.SubMsg == KEY_BACKSPACE ) {

RibbonShowRibbon();

}
}

CLICKED, the application should display a

UNHANDLED, the user may have pressed

MESSAGE to the application from

PagerMain function example

This is a more complicated example of a PagerMain() function; it
includes task yielding, and makes use of items from other DLLs.

#include <Pager.h>
#include <Ribbon.h>

char VersionPtr[] = "Example Application";
int AppStackSize = 4096;

// Function identifying task to the OS
// These values are actually the defaults for
// a PagerMain() thread; see RimCreateThread()
// for more details

Developer’s Guide – RIM 950 Wireless Handheld™

Building applications — Coding an application 61

static

void

set_task_pid( void )

{

PID pid;
pid.Name = "Example Application";
pid.EnableForeground = true;
pid.Icon = NULL;
RimSetPID( &pid );

}

// Function which creates the main thread

void

PagerMain( void )

{

MESSAGE msg;
set_task_pid();

// Yield to let other applications initialize
RimTaskYield();

// Register the application with the Ribbon so an
// icon is shown on the main screen

RibbonRegisterApplication( "Database Sample",

&bitmapSample, 0, 0 );

// Initialization complete: set up LCD and
// enter message loop
for (;;) {

RimGetMessage( &msg );
// respond to events
switch( msg.Device ) {
case DEVICE_SYSTEM:

// handle SYSTEM messages
break;

case DEVICE_TIMER:

// handle TIMER messages
break;

case DEVICE_KEYPAD:

// handle KEYPAD messages
break;

}

}

}

Developer’s Guide – RIM 950 Wireless Handheld™

62 Building applications — Coding an application

To set up a basic program structure

1. Implement a message loop:

Any application running on the device will need t o hand le messages

from the OS that will notify the application of key presses, radio

events, etc. The most efficient process is to do this is to use a message

loop.

The basic structure of the message loop is:

for(;;){

// waits until a message is given
// to the application by the OS

RimGetMessage (&message);

// processes message

}

2. An application that wishes to display data on the device’s LCD

screen must first become the foreground task.

In this example, the application should be bro ught to the foregrou nd

if the user activates the applica tion by selecting an icon on the main

screen. When the user selects the icon, the OS sends a

application from the

RIBBON_GRAB_FOREGROUND. If we get a RIBBON message, we call

RimGetCurrentTaskID() for the current task ha ndle. We bring the

application to the foreground using

RIBBON device, with the event set to

MESSAGE to the

RimRequestForeground().

if( message.Device == DEVICE_RIBBON ) {

if( message.Event == RIBBON_GRAB_FOREGROUND ) {

// Bring this application to the foreground
// so it can use the LCD
RimRequestForeground(RimGetCurrentTaskID());

}

}

3. If the user presses a key, the OS sends a

from the

MESSAGE to the UI Engine, which returns a result code:

if( message.Device == DEVICE_KEYPAD ) {

}

Developer’s Guide – RIM 950 Wireless Handheld™

KEYPAD device. If we get a KEYPAD message, we pass the

// Let the UI process the message
result = m_ui_engine.HandleInput( message );
//Process UI Engine result

MESSAGE to the application

Building applications — Compiling RIM Wireless Handheld applications 63

MESSAGEs resulting from a key being pressed on the keyboard are

sent only to the foreground task.

4. If the UI Engine returns CLICKED, the application should displa y a
menu. If the UI Engine returns
pressed the
main screen (

if( result == CLICKED ) {

// Set up, display, and handle menu result
}

if( result == UNHANDLED ) {

//Check for the backspace key. If the user
// pressed backspace we want to go to the home
// screen

}

BACKSPACE key, in which case we want to return to the

RIBBON).

if( message.Event == KEY_DOWN &&

message.SubMsg == KEY_BACKSPACE ) {

RibbonShowRibbon();

}

UNHANDLED, the user may have

Example programs

Source code for sample applications is available in the SAMPLES
directory where the SDK was installed.

You may want to read the Messenger Developer’s Guide, which
describes a sample application that makes use of the OS and database
APIs.

Compiling RIM Wireless Handheld applications

You can create a RIM Wireless Handheld applica tion by recompiling an
application created for an earlier version of the wireless handheld.

1. Set up a Microsoft Developer Studio project (version 5.0 or later) as

described above.

2. Select Project > Add to Project > Files…. Select all the source and

header files that should be included in the project.

Developer’s Guide – RIM 950 Wireless Handheld™

64 Building applications — Installing the application

pp

You should now be able to compile and deb ug your application using
the RIM 950 Wireless Handheld SDK.

Installing the application

There are two utilities available to install the application on a RIM
Wireless Handheld, the PROGRAMMER.EXE utility and the Desktop
Manager software shipped with every RIM Wireless Handheld.
Installing the application with PROGRAMMER.EXE has been covered (see
page 39 for a description of the
cannot run the Desktop Manager and PROGRAMMER.EXE at the same
time.

Normally, installation of a distributed application is done using the
Application Loader in the Desktop Manager software. To make your
application visible to the Desktop Manager software, you need to set
certain registry keys; the Desktop Manager looks for those keys and
creates an entry for your application.

LOAD command action). Note that you

Depending upon your distribution method, you can either set the key s
directly or you can create an applica tion loader information file with a
.ALI file extension.

Registry keys for installation

The registry keys are installed in the hive under

HKEY_LOCAL_MACHINE/SOFTWARE/Research In Motion/Desktop
Software/Loader/Applications/DisplayName. Note that the Display Name

is both the name of the key and a value in the key.

Value Name Value Type Meaning

Description REG_SZ The text displayed in the

description field of the Application
Loader when one of the items in
the app list is selected.
Corresponds to the

<DESCRIPTION> tag of the ALI

file.

DisplayName REG_SZ

The name of the app as displa ye d
in the A

lication Loader.

Developer’s Guide – RIM 950 Wireless Handheld™

Building applications — Installing the application 65

Value Name Value Type Meaning

Corresponds to the

<DISPLAY_NAME> tag of the ALI

file.

Flags REG_DWORD See below. Generally 0x04 is the

best value. Inferred from the
optional

<SCREEN_SIZE> tag of

the ALI files.

Path REG_SZ Fully qualified path to the ac tual

app DLL. In ALI files, it is inferred
from the pathname to the ALI file
by the Application Loader.

Version REG_DWORD Indicates version infor mation

associated with the app DLL. This
isn't used directly by the loader,
but is required. Corresponds to the

<VERSION> tag of the AL I f ile.

The Flags is a bitset indicating information about this particular
application DLL:

Name Mask Meaning

Reserved1
Reserved2
Reserved3

SMALLSCREEN

0x01 Reserved; must be zero
0x02

Reserved; must be zero

0x04 Reserved; must be one
0x08 Indicates that this app is intended for

use only on the pager-sized RIM
Wireless Handhelds

BIGSCREEN

0x10 Indicates that this app is intended for

use only on the palm-sized RIM
Wireless Handhelds

Developer’s Guide – RIM 950 Wireless Handheld™

66 Building applications — Installing the application

ALI file format

The ALI file is read by the Application Loader, which then sets
appropriate registry keys. From that point on, your a pplication is known
to the loader.

The ALI file is a text file that contains three lines. The format is:

<DESCRIPTION>Description of the application
<DISPLAY_NAME>Name to be displayed
<VERSION>Version number

<SCREEN_SIZE>Model (RIM 950™ or RIM 957™) RIM

Wireless Handheld — optional line

The angle brackets (

<DESCRIPTION>

A brief description of the application that is displayed in the
Description pane of the applicatio n loader. The value is an ar bitrary
text string.

<DISPLAY_NAME>

The name for the application, displayed with a checkbox in the
selection pane of the application loader. The list of applications is
sorted by display name. The value is an arbitrary text string. This
value will also be used for the registry key name.

<VERSION>

A version number for the application. A value is required but is
currently ignored by the application loader. The value must be in
numeric format.

<SCREEN_SIZE>

This tag is optional, and represents the model of the RIM Wireless
Handheld. Valid arguments f or this tag are
Respectively, these set the
extra bits.

The ALI file must be in the sa me directory as t he DLL it de scribes, and it
must have the same basen ame as the DLL it de scribes. For example, the
API file for MEMOPAD.DLL is named MEMOPAD.ALI.

<>) around the key names are required.

LARGE, SMALL, and ANY.

BIGSCREEN bit, SMALLSCREEN bits, or no

Developer’s Guide – RIM 950 Wireless Handheld™

Building applications — Installing the application 67

Application loader notes

You should be aware of the following when packaging a pplications for
the Application Loader for the RIM Wireless Handheld.

Each application requires an ALI file or registry settings

The ALI file contains information used by the loader to add an
application to its list of ava ilable applica tions. The A LI file must ha ve the
same basename as the DLL it describes and it must be in the same
directory as the DLL it describes. See above for the format. The
Application Loader uses the contents of the ALI file to set registry
entries. You may choose to set the registry entries directly.

Each application must have a unique name

Neither the application loader nor the RIM Wireless Handheld will allow
two applications with the same name. Each application must have a
unique name. This is not normally a problem; the int ernal DLL name is
used for comparison purposes. (The internal DLL na me is the name of
the output file passed to the linker when creating the DLL.)

The application name is compiled into the DLL

Simply renaming the DLL with W indows Expl orer will not allow y ou to
have two copies of the MemoPad (for example) on your RIM Wireless
Handheld. The check is based on the internal DLL name. If for some
reason you want to ha ve to dif ferent versio ns of the same applicati on on
your device, you will need to adjust your build process.

Developer’s Guide – RIM 950 Wireless Handheld™

Appendix

C library compatibility for RIM Wireless Handheld applications

Only some functions within the co mpiler C library are safe to call from
the RIM Wireless Handheld environment. The following table
summarizes the information. There are equivalent functions for the
groups marked “No”—see the list afterwards.

Compatible with RIM Wireless

Function

Groups

Argument access macros

Buffer access macros

Byte classification

Character classification

Data conversion

Debug

Directory control

Error and exception handling

File handling

Floating point

Input/output

Locale dependent

Memory allocation

Process and environment control

Searching and sorting

String manipulation

System calls

Time ü

Yes No Some

ü
ü

ü

Handheld?

ü
ü

ü
ü
ü
ü

ü
ü
ü
ü

ü
ü

ü

ü

70 Appendix — C library compatibility for RIM Wireless Handheld applications

Functions that are compatible

Argument access macros

This set of functions is compatible with the RIM Wireless Handheld
environment. This includes the macros

Buffer manipulation functions

This set of functions is compatible with the RIM Wireless Handheld
environment. This includes

_memicmp, memmove, memset, and _swap.

Data conversion functions

The following data conversion functions may be used in a RIM W ireless
Handheld application:

labs, _ltoa, strtol, strtoul, __toascii, tolower, _tolower,
toupper, _toupper, and _ultoa.

Searching and sorting functions

abs, atoi, _atoi64, atol, _itoa, _i64toa,

va_arg, va_start, and va_end.

memccpy, memchr, memcmp, memcpy,

The library functions
work in the RIM Wireless Handheld environment. Testing for these
functions has not been completed at this time.

bsearch, _lfind, _lsearch, and qsort should

Functions that are not compatible

Byte classification (multibyte) functions

The RIM Wireless Handheld does not support multibyte characters.

Character classification functions

Since the RIM Wireless Handheld does not support multibyte or wide
characters, multibyte or wide character functions are also not supported.
Many of the other isxxx() functions and macros are locale dependent.
Different locales have different sets of upper and lower case characters.

Debug functions

The RIM Wireless Handheld does not support the compiler library
debugging support functions. Other functions are provided to support
debugging of wireless handheld applications. For example, short

Developer’s Guide – RIM 950 Wireless Handheld™

Appendix — C library compatibility for RIM Wireless Handheld applications 71

debugging messages c an be output to the debug o utput window when
running MS Developer St udio by calling

RimDebugPrintf.

Directory control functions

The RIM Wireless Hand held file system is dif ferent from those used on
desktop systems. As a result, the directory control functions are not
supported by the RIM Wireless Handheld.

Error and exception handling functions

The RIM Wireless Handheld environment does not support exception
handling. Serious failures, such as page faults, ar e hand led by the syste m
function

RimCatastrophicFailure, which may be called by

application code when an unrecoverable error is detected.

File handling functions

The RIM Wireless Hand held file system is dif ferent from those used on
desktop systems. As a result, the file handling functions are not
supported by the RIM Wireless Handheld.

Floating-point functions

Since the RIM Wirele ss Ha ndheld has no floa ting p oint co- proc essor a nd
does not support applica tion handling of traps and exc eptions, floating
point functions may not be used on the RIM Wireless Handheld, unless
all of the floating points ar e implemented by emulation without ca lls to
the operating system. However, the following functions are incorrectly
classified as floating point functi ons, a nd may be used without dif ficu lty:

div, labs, ldiv, _lrotl, _lrotr, _max, _min, rand, _rotl, and _rotr.

Input and output functions

Any stream, file, or cons ole input/output functions are not compa tible
with the RIM Wireless Handheld environment. The RIM Wireless
Handheld environment provides different mechanisms for keyboard
input, LCD output, and file system access. Because o f the way they are
implemented in the compiler library, this category also includes

sprintf and sscanf. These may not be used in a RIM Wireless

Handheld application. Use

sprintf.

The port I/O functions, su ch as

RimSprintf or RimVSprintf instead of

inp and outp, will not cause an error

during compilation, li nking, or loading. H owever, be cause RIM Wireless

Developer’s Guide – RIM 950 Wireless Handheld™

72 Appendix — C library compatibility for RIM Wireless Handheld applications

Handheld applications run in a protected environment, calling these
functions will cause a protection fault at run time.

Locale dependent functions

The RIM Wireless Handheld environment does not support locales,
multibyte characters, or wide characters. However, it is useful to have
many of the locale dependent functions compatible. These functions
were in the C library before the

setlocale function.

Memory allocation functions

The standard C memory allocation function s may n ot be used in the RIM
Wireless Handheld environment. Use

RimFree instead.

RimMalloc, RimRealloc, and

The global C++ operators
translated into calls to

new and delete may be used. They are

RimMalloc and RimFree respectively. Operator

new differs from the standard one in that, if there is insufficient memory
to perform the allocation, it returns a

NULL pointer rather than throwing

an exception.

Process and environment control functions

Because the process model of the RIM Wireless Handheld environment
is quite different from that of desktop systems, the compiler C library
process and environment control functio ns are not applicable.

The functions

setjmp and longjmp are also in this class. They are not

available because the library implementation s make sy stem calls i n order
to perform stack unwinding. You could write a version of these
functions that would work on the RIM Wireless Handheld, if it is
acceptable not to call the distracters of C++ stack objects between the

setjmp and the longjmp.

String manipulation functions

Many of the string manipulation functions are locale dependent or
require the use of

malloc. These functions are, therefore, not supported

by the RIM Wireless Handheld environment.

System call functions

Windows system call functions may not be used in the RIM Wireless
Handheld environment. Because of the way the RIM Wireless Handheld

Developer’s Guide – RIM 950 Wireless Handheld™

Appendix — C library compatibility for RIM Wireless Handheld applications 73

operating system allocates applica tion stacks, Wi ndo ws funct io ns are not
safe to call even when running on the simulator.

Time functions

The RIM Wireless Handheld operating system represents time
differently from desktop systems. As a result, time functions are not
compatible with the RIM Wireless Handheld environment.

Developer’s Guide – RIM 950 Wireless Handheld™

Index

about this guide, 6–7
ALI file, 64
alt key, simulating, 24–25
API

generic application, See

generic application

overview, 52–54

application loader, 64

registry keys, 64

applications

compiling RIM Wireless

Handheld, 63–67

restarting, 50
backlighting, 25
BITMAP.EXE utility, 47
BMP2DEF.EXE utility, 48
building applications, 54–67
C library compatibility for RIM

Wireless Handheld

applications, 69
coding applications, 62–63
compiling RIM Wireless

Handheld applications, 63–67
configuring MS Developer

Studio, 12–13
ctrl key, 25
development environment

configuring, 12–13
DLL, 11, 55
DLLUTIL.EXE utility, 47
examples

generic application, 62–63

source code, 63
exception handling, 71
filename, 36
flash file system, 28
flash memory, 51
flash simulation file, 28
flash simulation files, 27

generic application

entering the message loop,

57–58
entry point function, 55
example programs, 63
registering the application,

55–57

header files

Pager.h, 57
Pre20.h, 16
ribbon.h, 59

HKEY_LOCAL_MACHINE/SO

FTWARE/Research In
Motion/Desktop
Software/Loader/Applicatio

ns, 64
icons, creating, 52
information sources

API Developer’s Guides, 52–

54

Operating System API

Developer’s Guide, 50

Ribbon API Guide, 52
installing the SDK, 9–13
interface, user, 52
introduction, 5
keypad, 24
launching the simulator, 20, 2 1
LCD, 26
LCDFONTS.EXE utility, 48
loading simulator applications,

22

macros

argument access, 70

LCD constants, 16

locale dependent, 70
memory

flash, 51

RAM, 51

76 Index

use, 51

message loops

and ribbon, 59
definition, 62
entering the message loop,

57–58

MESSAGEs

concept, 51

mode

pager, 25
pc, 25

modem, 35

radio simulation control

panel dialog box, 32

simulating using a physical

modem, 29

simulating using the file

system, 31

simulation with RAP m odem,

30

using file system

command line options, 31
packet transmission, 33, 34
radio simulation control

panel dialog box, 32

using the pager as a modem,

30

MS Developer Studio

configuring, 12–13

description, 11
MS Intellimouse, 26
MS Visual C++ 5.0, 12
multitasking, 5
network

description, 5–6
opening

multiple files in the simulator,

21

simulator, 20, 21
Operating System API

Developer’s Guide, 50

OS library

RIMOS.LIB, 15

OSLOADER.EXE, 21
packet transmission, 33, 34
pager mode, 25
PAGER950.LIB, 15
PagerMain function

example, 60

tasks and threads, 50
pc mode, 25
processor, 5
program loader, 69–73

batch command, 42–43, 42–43

command line options, 38–44

dir command, 41–42

erase command, 41

load command, 39–41

troubleshooting, 44–46

ver command, 42

wipe command, 43–44
prompting for applications, 3 5
radio simulation contr ol panel

dialog box, 32

packet transmission section,

33, 34
RAM, 51
RAP (radio access protocol), See

modem

release notes, 15

Message, 16
OS, 16
recompiling, 15

simulator, 16
Research In Motion, 6
restarting applications, 50
ribbon API

using, 59
Ribbon API Guide, 52
ribbon icons, See icons, creating
RIM co-operative scheduler, 50
RIM Wireless Handheld

activating applications, 52

keyboard, 52

LCD, 52

Developer’s Guide – RIM 950 Wireless Handheld™

Index 77

RIM Wireless Handheld

simulator, See simulator
running the simulator, 19–20
SDK

components, 6–7
description, 5
installing, 9–13
multitasking, 5

processor, 5
serial input/output, 27
serial port, 34
shift key

simulator, 25
shortcuts for starting t he

simulator, 20–23

simulating

battery environment, 26–27

holster environment, 26–27

serial input/output, 27
simulation menu

battery, 26–27

holster, 26–27
simulator, 16, 19–37

alt key, 24–25

backlighting, 25

command line options, 27–37

command line options for

RAP modem, 30

command line options using

the file system, 31
keypad, 24
launching, 20, 21
LCD, 26

loading applications, 22
opening, 20, 21
opening multiple files, 21
pager mode, 25
pc mode, 25
running, 19–20
shift key, 25
simulating using a physical

modem, 29
trackwheel, 25
using, 23–27
using the shortcuts, 20–23

standard C library

compatible functions, 70

system overview, 49
tasks

application development, 50
yielding, 50

threads, 50
tools guide, 19–48
trackwheel, simulating, 25
user interface, 52
using

simulator, 23–27
simulator shortcuts, 20–23
the ribbon API, 59

utilities

bitmap, 47
bmp2def, 48
conversion, 47–48
dllutil, 47
lcdfonts, 48

Developer’s Guide – RIM 950 Wireless Handheld™