Blackberry MDS Studio Javascript Reference Guide

BlackBerry MDS Studio
version 2.0
JavaScript Reference Guide

BlackBerry MDS Studio version 2.0 JavaScript Reference Guide
Last modified: 1 October 2008
Part number: 15129096
At the time of publication, this documentation is based on BlackBerry MDS Studio version 2.0.
Send us your comments on product documentation: https://www.blackberry.com/DocsFeedback.
©2008 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, SureType® and related trademarks, names,
and logos are the property of Research In Motion Limited and are registered and/or used in the U.S. and countries around the world.
JavaScript is a trademark of Sun Microsystems. All other trademarks are the property of their respective owners.
The BlackBerry smartphone and other devices and/or associated software are protected by copyright, international treaties, and various
patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D445,428; D433,460;
D416,256. Other patents are registered or pending in the U.S. and in various countries around the world. Visit www.rim.com/patents for a list of
RIM (as hereinafter defined) patents.
This documentation including all documentation incorporated by reference herein such as documentation provided or made available at
www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition, endorsement, guarantee,
representation, or warranty of any kind by Research In Motion Limited and its affiliated companies ("RIM") and RIM assumes no responsibility
for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and
confidential information and/or trade secrets, this documentation may describe some aspects of RIM technology in generalized terms. RIM
reserves the right to periodically change information that is contained in this documentation; however, RIM makes no commitment to provide
any such changes, updates, enhancements, or other additions to this documentation to you in a timely manner or at all.
This documentation might contain references to third-party sources of information, hardware or software, products or services including
components and content such as content protected by copyright and/or third-party web sites (collectively the "Third Party Products and
Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including, without limitation the content,
accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any other aspect of Third Party Products
and Services. The inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by RIM of
the Third Party Products and Services or the third party in any way.
EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS, ENDORSEMENTS,
GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY
CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR
PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING
FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE,
OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND
SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE.
SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT
PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT
BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST
ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE FOR ANY TYPE
OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE,
HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY
OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED
DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION,
LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR
RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES,
DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES,
COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES,
WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER OBLIGATION, DUTY,
OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT
LIABILITY.
THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE OF
ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY
OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL
PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR
SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO
INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.
IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE, AGENT,
DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITY ARISING FROM OR
RELATED TO THE DOCUMENTATION.
Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that your airtime service
provider has agreed to support all of their features. Installation or use of Third Party Products and Services with RIM's products and services
may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are
solely responsible for determining whether to use Third Party Products and Services and if any third party licenses are required to do so. If
required you are responsible for acquiring them. You should not install or use Third Party Products and Services until all necessary licenses
have been acquired. Any Third Party Products and Services that are provided with RIM's products and services are provided as a convenience to
you and are provided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by
RIM and RIM assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and
subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent
expressly covered by a license or other agreement with RIM.
The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto. NOTHING IN
THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY RIM FOR
PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.
Research In Motion Limited Research In Motion UK Limited

295 Phillip Street Centrum House, 36 Station Road
Waterloo, ON N2L 3W8 Egham, Surrey TW20 9LF
Canada United Kingdom
Published in Canada
Contents
Standard environment ...................................................................................................................................... 13
Data types ........................................................................................................................................................ 13
Enumerated data types .......................................................................................................................... 14
Date data types ....................................................................................................................................... 14
Binary data types ..................................................................................................................................... 14
Data type conversion .............................................................................................................................. 14
Parameters ....................................................................................................................................................... 18
Global symbols ................................................................................................................................................19
Dialog ........................................................................................................................................................19
Screen .......................................................................................................................................................19
BlackBerry MDS data component global symbols .............................................................................19
BlackBerry MDS Studio components and script .......................................................................................... 21

Screen component access ............................................................................................................................. 21
Screen field access .................................................................................................................................. 21
Menu keyword access ............................................................................................................................ 23
Message component access ......................................................................................................................... 23
Message field access ............................................................................................................................. 24
Data component access and creation ........................................................................................................ 24
Data field access .................................................................................................................................... 24
Arrays ....................................................................................................................................................... 24
Application global variables ................................................................................................................. 25
Organizer data access .......................................................................................................................................27

Contact component ........................................................................................................................................27
Code sample: Using the Contact component .................................................................................... 28
Address component ....................................................................................................................................... 28
Code sample: Using the Address component .................................................................................... 29
Event component ........................................................................................................................................... 29
Code sample: Using the Event component ........................................................................................ 29
Code sample: Finding an event using the where clause .................................................................. 30
Attendee component ..................................................................................................................................... 30
Code sample: Using the Attendee component .................................................................................. 30
RepeatRule component ................................................................................................................................ 30
Code sample: Using the RepeatRule component ............................................................................... 31
Message component ...................................................................................................................................... 31
Task component .............................................................................................................................................. 31
Code sample: Using task component fields ....................................................................................... 32
System component ........................................................................................................................................ 32
DeviceInfo component .................................................................................................................................. 32
Error component ............................................................................................................................................ 33
Error categories ...................................................................................................................................... 34
Error codes ............................................................................................................................................... 34
Logger component ................................................................................................................................. 34
Organizer enumerated data types .............................................................................................................. 35
Application integration .....................................................................................................................................37

Organizer applications ..................................................................................................................................37
Address Book application ......................................................................................................................37
Calendar application ..............................................................................................................................37
Email application .................................................................................................................................... 38
Phone application .................................................................................................................................. 39
Maps application .................................................................................................................................... 39
Tasks application .................................................................................................................................... 40
GPS access ...................................................................................................................................................... 40
BlackBerry MDS Runtime application integration .................................................................................... 41
Parameters ............................................................................................................................................... 41
Java application integration .......................................................................................................................... 41
Parameters ............................................................................................................................................... 41
BlackBerry MDS Studio functions .................................................................................................................. 43

Screen functions ............................................................................................................................................ 43
Function: close ........................................................................................................................................ 43
Function: display .................................................................................................................................... 43
Function: refresh .................................................................................................................................... 44
Data functions ................................................................................................................................................ 44
Function: all ............................................................................................................................................. 44
Function: create (keyless data) ............................................................................................................ 45
Function: create (multiple primary keys) ............................................................................................ 45
Function: create (single primary key) ................................................................................................. 45
Function: display ....................................................................................................................................46
Function: find (multiple primary keys) ................................................................................................46
Function: find (single primary key) ...................................................................................................... 47
Function: findWhere ............................................................................................................................... 47
Function: pop .......................................................................................................................................... 48
Function: property .................................................................................................................................. 48
Function: push ........................................................................................................................................49
Function: remove ....................................................................................................................................49
Function: remove .................................................................................................................................... 50
Function: removeAll ............................................................................................................................... 50
Message functions ......................................................................................................................................... 50
Function: contains .................................................................................................................................. 50
Function: send ......................................................................................................................................... 51
Organizer functions ....................................................................................................................................... 51
Function: exit ........................................................................................................................................... 51
Function: loadURL ................................................................................................................................... 51
Function: log ........................................................................................................................................... 52
Function: send ........................................................................................................................................ 52
Function: startCall .................................................................................................................................. 53
1
Standard environment
Data types
Parameters
Global symbols
Data types
The following data types are returned to JavaScript®, based on access to the BlackBerry MDS Studio Application
symbols:
• array
• binary
• boolean
• data component
• date
• decimal
• enumerated
• integer
• long
• message component
• screen component
• string
The following data types are returned from component elements as primitive JavaScript variables:
• boolean
• decimal
• integer
• long
• string
You can use simple comparisons, such as != or ==. You do not need to call functions on objects. In BlackBerry MDS
Studio, types boolean, integer, decimal, and string can be represented as objects in JavaScript.
BlackBerry MDS Studio JavaScript Environment
Enumerated data types

Enumerated data types can be used if they are defined in the BlackBerry MDS Studio application.
var x = 0;
if(mycar.BrandName == Car.sedan) {
x = x + 1;
}
Date data types

The BlackBerry MDS Studio™ date data types are represented internally by the BlackBerry® MDS Runtime as long
data types. These dates are converted to the JavaScript date data type when dereferencing the script. This way,
you can manipulate the date through natively available functions.
Binary data types

The BlackBerry MDS Studio™ supports base64Binary and hexBinarydata fields from a WSDL, as well as field types
of BLOB, binary, varbinary, and image, from a database data source. These types are represented internally by the
BlackBerry® MDS Runtime as binary data types. You can map these types to image and button controls.
The BlackBerry MDS Runtime supports the following MIME types:
• image/gif
• image/png
• image/vnd.wap.wbmp
• image/jpeg (on color devices)
• image/jpg (on color devices)
• image/pjpeg (on color devices)
• image/bmp
• image/tiff
Example: Converting a binary field to a numeric array

// Convert the previously defined binary variable g_bin
myVar = g_bin.toArray();
Example: Converting to a binary field from a numeric array

// Convert the array to a binary
g_bin = myNumArray;
Data type conversion

The BlackBerry MDS Runtime converts data when an assignment or relational expression is processed. The
conversion occurs when BlackBerry MDS Studio application symbols or subfields, such as components, globals,
messages, and screens, are referenced. The BlackBerry MDS Studio™ component reference implies that the data
typing system of the component definition must be observed. Otherwise, the standard JavaScript type conversion
rules apply.
10
1: Standard environment
Data type conversion rules constrain the conversion results to avoid questionable or invalid results. Semantic
operators describe the valid conversions between different data types.
11
Conversion rules for boolean values

Input value Result
BlackBerry MDS Studio component true
boolean not applicable
date true
decimal false if 0; otherwise true
enumeration true
integer false if 0; otherwise true
long false if 0; otherwise true
null false
string (case-insensitive) false if the length of the string is 0; otherwise true
undefined false
Conversion rules for integer values

Input value Result
BlackBerry MDS Studio component 0
boolean 1 if true, 0 if false
date the number of milliseconds past January 1st, 1970
decimal if the decimal has no fraction and is in the range between -2^31 and +2^31 - 1, the conversion
succeeds; otherwise, it wraps around
enumeration 0
integer not applicable
long if the long data type is in the range between -2^31 and +2^31 - 1, the conversion succeeds; otherwise,
it wraps around
null 0
string converts a string representation of an integer; otherwise, 0
undefined 0
Conversion rules for decimal values

Input value Result
BlackBerry MDS Studio component NaN
decimal not applicable
enumeration NaN (not a number)
integer converted, but there might be a loss in precision
long converted, since the range of the long is smaller than that of the decimal
null 0
string (case-insensitive) convert a string representation of a long; otherwise, NaN
undefined NaN
12
Conversion rules for long values

Input value Result
BlackBerry MDS Studio component 0
decimal if the decimal has no fraction and is in the range between -2^31 and +2^31 - 1, the conversion
succeeds; otherwise, it wraps around
enumeration 0
integer converted, since the range of the integer is smaller than that of the long
long not applicable
null 0
string (case-insensitive) converts to a number if in a valid format; otherwise, 0
undefined 0
Conversion rules for string values

Input value Result
BlackBerry MDS Studio component data type error
boolean string representation of a boolean value
date simple date format of a date value
decimal string representation of a decimal value
enumeration string representation of an enumeration value; for example, STATUS.NOT_STARTED converts to
“NOT_STARTED”
integer string representation of an integer value
long string representation of a long value
null null
string (case-insensitive) not applicable
undefined “UNDEFINED”
Conversion rules for date values

Input value Result
boolean data type error
date not applicable
decimal data type error
enumeration data type error
integer data type error
long data type error
null data type error
string (case-insensitive) converts based on predefined time pattern, data type error if failed
undefined data type error
13
Conversion rules for enumerated values

Input value Result
date data type error
enumeration not applicable
null data type error
string (case-insensitive) convert a proper string representation of enumeration value; otherwise, a data type error is
generated
Conversion rules for BlackBerry MDS Studio component values

Input value Result
BlackBerry MDS Studio component not applicable
date ignored if assigned to a global or keyless field; otherwise, set to null
enumeration ignored if assigned to a global or keyless field; otherwise, set to null
null ignored if assigned to a global or keyless field; otherwise, set to null
string (case-insensitive) data type error
Data type conversion errors

When a data type conversion error occurs, a JavaScript exception is raised. You can catch the exception using a try
catch block.
// where gdate is of type date, and gboolean is of type boolean
try {
gdate = gboolean;
} catch (e) {
Dialog.display(“Error: “ + e);
}
If the exception is not caught, an error message is displayed and the application closes.
Parameters
You can declare parameters explicitly in either the screen or script definition in the screen editor and BlackBerry
MDS Studio Script Editor. You can define multiple parameters, only as type BlackBerry MDS data component.
14
Global symbols
Dialog
The Dialog global symbol enables script-based control of BlackBerry MDS Runtime dialog boxes.
Field Description
OK dialog type OK
YES_NO dialog type Yes/No
OK_BUTTON button type OK
YES_BUTTON button type Yes
NO_BUTTON button type No
Screen
The Screen global symbol enables you to control screen management using script.
BlackBerry MDS data component global symbols

A global symbol is defined for every BlackBerry MDS Studio data component type declared in the application.
Keyed and keyless data collection

A global symbol is introduced for both keyed and keyless BlackBerry MDS Studio data component types. A keyed
data collection has a primary key specified in its declaration, while a keyless data collection does not have a
primary key. You specify key field information using the BlackBerry MDS Studio Data Component editor.
When you create a keyed data instance, it is added to the corresponding data collection, where it remains until you
explicitly remove it. A keyless data instance remains as long as its container, another data component, or global
variable, remains. If you create a keyless data instance in a script without passing it to subsequent screens (using
screenName.display()), it is lost after the script ends.
15
16
2
BlackBerry MDS Studio components and
script
Screen component access
Message component access
Data component access and creation
You cannot create message and screen components explicitly using script, but they are available to the BlackBerry
MDS Studio environment and behave similarly to other JavaScript object types. You can create data component
instances using the create() function.
Screen component access

A symbol is registered corresponding to the screen name of each screen defined in the application. This symbol
can be referenced anywhere throughout the script in a way that is similar to how global variables are referenced.
scrLogin.display();
Screen field access

You can access controls defined on a screen using the JavaScript field notation. The return data type and value
access vary depending on the type of the control.
All screen controls share the visible field. The visible field returns a boolean value that indicates whether the
screen control is shown or hidden.
Example: Setting the visibility of a region

// Set the visibility of a region according to a global boolean preference setting
scrMain.myDetailRegion.visible = gvShowDetail;
// hide the editbox and refresh the screen

scrMain.myEditbox.visible = false;
Screen.refresh();
Check box fields

Check box fields use the properties described for single value controls. The checkbox control does not support the
selected field.
In contrast to EditBox, TextArea, and Label controls however, the value field returns a boolean rather than a string.
Example: Using the checkbox control with script

scrMyScreen.myCheckBox.value = true; // check it.
scrMyScreen.myCheckBox.value = false; //uncheck it.
Single value control fields

The EditBox, TextArea, and Label controls have a single value field that is readable and writable. The value field is
based on string or date data types.
Example: Assigning a value to an editbox

// edPlayerName is an editbox
var loginName = scrLogin.ebPlayerName.value;
loginName = "Mr. " + loginName;
scrLogin.ebPlayerName.value = loginName;
When assigning to the value field, the BlackBerry MDS Runtime attempts to make data type conversions. See
“Example: Converting a binary field to a numeric array” on page 10 for more information. If the control is defined
to use a date or time entry data type, the right side value of the assignment statement is first converted to a date
object and if successful, value is assigned as a date object. If the control is defined in BlackBerry MDS Studio to
have a duration entry data type, a long or a string representation of a long number can be assigned, but not a date
object.
Multiple value control fields

Choice and Multichoice fields may return a single string or an array of strings. Access to the choice control is
modified using the selected and value extension fields.
Field type Field extension Return data type

Choice .selected single integer-based index indicating the current selection
.selectedValue value of the output mapping of control
.value array of string or date
.mapping selected item
Multichoice .selected array of indexes
.selectedValue value of the output mapping of control
.value array of string or date
.mapping array of selected items
Example: Returning a string from selected text

// slPlaceBets is a choice control. Here we get the current selected item text.
Dialog.display("You selected " + scrHorseRacing. slPlacedBets.value[scrHorseRacing.
slPlacedBets.selected]);
// Here we iterate all the choices and combine into one string
var choicesString = "";
var choices = scrHorseRacing.slPlacedBets.value; // Returns an array
for(i=0;i < choices.length;i++)
choicesString = choicesString + choices[i]; // Adds the current string
Note that only a string array can be assigned to the value field of these controls.
Repetition control fields

Repetition is similar to Choice fields for the use of the selected field. For Repetition, the value field returns an array
of data components and can be assigned only with an array of data component.
18
2: BlackBerry MDS Studio components and script
With the exception of Label, Separator, Image, Button, Region, and Menu item controls, each control has mapping
field, which is of the type defined in the mapping attribute of the control. It is read-only in script and reflects the
mapping result of the control. The mapping field is often used to access the selected item in choice or repetition
controls.
Example: Getting the mapping field of a repetition control

// Dereference the data component field by using the mapping property
var theEmployee = ViewEmployees.repetition1.mapping;
var employeeDept = theEmployee.department;
Table control fields

You can access table properties from script to determine the contents of a particular cell.
Property Description
columns This property is an array of the column controls in the table.
selectedColumnIndex This property is the index of the selected column.
selectedRowIndex This property is the index of the selected row.
Example: Returning a string from selected text

// gets the string value of the currently selected cell
var cell = scrMain.table1.columns[scrMain.table1.selectedColumnIndex]
[scrMain.table1.selectedRowIndex];
Menu keyword access

A screen has a menu available through the MENU keyword. A menu might be defined through BlackBerry MDS
Studio to contain multiple menu items. Each menu item is available by name through JavaScript using the
intermediary MENU symbol.
The Visible property is a boolean value. If true, the menu item is visible. If the value is false, it is invisible.
Code sample: Defining menu items

if(isLogin) {
scrLogin.MENU.login.visible = false;
scrLogin.MENU.logout.visible = true;
} else {
scrLogin.MENU.login.visible = true;
scrLogin.MENU.logout.visible = false;
}
Message component access

Each message defined in the application is available to the script as a global symbol.
19
Message field access

You can access fields on a message component by name. The return type of the field is determined by the
definition of the message and may be one of boolean, integer, string, date, data component or array containing
any of these data types. Both prototypes and data mappings influence message fields.
outSubmitBet.id = bet.id;
Data component access and creation

You can access data component instances by dereferencing nested fields of enclosing data instances.
In the following example, the PersonalProfile data instance is obtained from the UserProfile data instance through
the profile field and is passed to the send function on outProfileInfo message.
// UserProfile is first found
var user = UserProfile.find("id");
// Personal Profile is de-referenced off the UserProfile "user" through the

// profile field.
// The profile is then assigned to a message and sent.
outProfileInfo.body = user.profile;
outProfileInfo.send();
You can create a data component instance using the create() function on the data component type global
symbol. The following example creates a Horse data component with the primary key set to "Bill the Horse."
var h = Horse.create("Bill the Horse");
Data field access

You can access fields on a data component by name. The definition of the data determines the return type of the
field, which can be any of the supported data types, including other data components. Additional data fields might
be available due to prototyping from other data types.
Arrays
Arrays are used throughout the BlackBerry MDS Studio application. Global variables and nested data component
fields can be declared as arrays.
Arrays returned from references to application definitions behave similarly to JavaScript arrays, with subtle
differences. Like JavaScript arrays, the BlackBerry MDS Studio arrays can be indexed using the element notation
[], but they support extended functions. Arrays returned in this way support only a subset of the standard
JavaScript array functions.
Unlike JavaScript arrays, an explicit push() must be used to increase the size of the BlackBerry MDS Studio array.
This is in contrast to JavaScript arrays where the element notation [] can be used to both reference the element
and increase the array size to store a new value.
20
2: BlackBerry MDS Studio components and script
Application global variables

A global variable is defined in the BlackBerry MDS Studio Global Variable Editor and can be referenced in a script
by name. For example, the following code assigns the player name to the gPlayerName global variable:
Code sample: assigning a name to a global variable

// Get the Player data component instance, assign the name to the
// global variable gPlayerName.
var player = Player.create(scrLogin.ebPlayerCode);
if(player.name != null && player.name == scrLogin.ebPlayerName ) {
gPlayerName = player.name;
}
21
22
3
Organizer data access
Contact component
Address component
Event component
Attendee component
RepeatRule component
Message component
Task component
System component
DeviceInfo component
Error component
Organizer enumerated data types
Organizer data is exposed to the BlackBerry MDS Studio application through a set of standard data component
definitions. These data definitions are similar to user-defined data definitions; they have fields, they support
functions, and so on. The fields provided by the standard data components are fixed and are reflective of the
organizer information they convey.
Keyed standard components do not require a primary key value to create them. Each keyed standard component
has a unique identifier (UID) primary key field that is managed by the BlackBerry MDS Runtime.
Contact component
The Contact data component updates or retrieves information from the address book application on the
BlackBerry® device. The Contact data component comes with a predefined set of fields and supports regular data
component functions such as create(), findWhere(), and removeAll(). Contact is a keyed data collection.
Field name Data type Description

dcid string direct connection ID
Email1 string first email address
Email2 string second email address
Email3 string third email address
faxTel string fax number
home2Tel string second home telephone number
homeAddress Address home address
homeTel string home telephone number
jobTitle string job title
mobileTel string mobile telephone number
nameFamily string family name

nameGiven string given name
nameTitle string title
note string note or description related to the contact
org string organization name
otherTel string telephone number
pagerTel string pager number
pin string BlackBerry device PIN
uid integer primary key that contains the unique identifier of the contact; this field is read-only
user1 string first user-defined field that contains information about the contact
user2 string second user-defined field that contains information about the contact
user3 string third user-defined field that contains information about the contact
user4 string fourth user-defined field that contains information about the contact
webpage string web page URL
work2Tel string second work telephone number
workAddress Address work address
workTel string work telephone number
Code sample: Using the Contact component

// No need to supply a key value here
var c = Contact.create();
c.nameTitle = "Mr.";
c.nameGiven = "John";
c.nameFamily = "Smith";
c.Email1 = "jsmith@abcco.com";
c.org = "ABC Co.";
var a = Address.create();
a.addrCountry = "Canada";
a.addrLocality = "Mississauga";
a.addrPostalcode = "L4W 5M4";
a.addrRegion = "Ontario";
a.addrStreet = "111 Main Street";
c.homeAddress = a;
c.workTel = "(555) 555-5555";
Address component
The Address keyless data component is part of the Contact keyed data component. Address data components have
no primary key.

addrCountry string country of a particular address
addrExtra string extra address information of a particular address
addrLocality string locality information of a particular address, for example, a city, county, town, and so on
addrPostalcode string postal code or zip code of a particular address
24
3: Organizer data access

addrRegion string region information, for example, province, state, territory, of a particular address
addrStreet string street of a particular address
Code sample: Using the Address component

var c = Contact.create();
c.nameTitle = "Mr.";
c.nameGiven = "John";
c.nameFamily = "Smith";
c.Email1 = "jsmith@abcco.net";
c.org = "RIM";
var a = Address.create();
a.addrCountry = "Canada";
a.addrLocality = "Mississauga";
a.addrPostalcode = "L4W 5M4";
a.addrRegion = "Ontario";
a.addrStreet = "111 Main Street";
c.homeAddress = a;
c.workTel = "(555) 555-4444";
Event component
The Event data component finds or creates meetings and appointments in the calendar application. Event is a
keyed data collection.

alarm date alarm date for this event
allday boolean flag to indicate that this is or is not an all day event; true if it is; otherwise set to false
attendees array of Attendee attendees for this event
end date end date for this event
free_busy FREEBUSY free or busy status for the event, FREEBUSY is a predefined enumerated data type with
enumerated values of FREE, TENTATIVE, BUSY, OUT_OF_OFFICE; the default value is BUSY
location string location information for this event
note string more complete description than the summary field
RepeatRule repeatRule string repeat rule for this event; the default value is null
start date start date for this event
summary string brief description of the event
uid integer unique ID for this event; it is the primary key; this field is read-only
Code sample: Using the Event component

var e = Event.create();
e.location = "Time Square";
e.summary = "have some fun";
e.start = new Date(2004, 12, 24, 20, 0);
e.end = new Date(2004, 12, 25, 8, 0);
e.alarm = new Date(2004, 12, 24, 19, 45);
25
e.attendees.push(Attendee.create(), Attendee.create());
e.attendees[0].address = "bill@sample.com";
e.attendees[1].address = "jsmith@abcco.net";
e.free_busy = FREEBUSY.OUT_OF_OFFICE;
e.allday = true;
Code sample: Finding an event using the where clause

e = Event.findWhere("start = 'Jan 1, 2004'");
e[0].note = "New Year's Day";
Attendee component
The Attendee keyless data component is part of the Event keyed data component. Attendee data components do
not have a primary key.

address string email address of an attendee
type ATTENDEE_TYPE type of a particular attendee; ATTENDEE_TYPE is a predefined enumerated type with
enumerated values of ORGANIZER, INVITED, ACCEPTED, DECLINED, TENTATIVE; the default
value is INVITED; this field is read-only
Code sample: Using the Attendee component

var e = Event.create();
e.location = "Time Square";
e.summary = "have some fun";
e.start = new Date(2004, 12, 24, 20, 0);
e.end = new Date(2004, 12, 25, 8, 0);
e.alarm = new Date(2004, 12, 24, 19, 45);
// This technique adds two new attendees directly

// to the array of attendees on the event
e.attendees.push(Attendee.create(), Attendee.create());
e.attendees[0].address = "bill@sample.com";
e.attendees[1].address = "jsmith@abcco.net";
e.free_busy = FREEBUSY.OUT_OF_OFFICE;
e.allday = true;
RepeatRule component
The RepeatRule keyless data component is part of the Event keyed data component. It defines the frequency or
recurrence of an event. RepeatRule data components do not have a primary key.

end date the date when the event reoccurrence ends
interval integer the number of times the event reoccurs (for example, DAILY); if the
frequency field is set to NONE, this field is ignored
26

frequency REPEATE_RULE_FREQUENCY frequency of an event; the default value is NONE, which means that the
enumerated event occurs once; REPEAT_RULE_FREQUENCY is a predefined enumerated
type with the following values: NONE, DAILY, WEEKLY, MONTHLY, YEARLY
Code sample: Using the RepeatRule component

var event = Event.create();
event.summary = "Learn martial art";
var rule = RepeatRule.create();
rule.frequency = REPEAT_RULE_FREQUENCY.DAILY;
rule.interval = 1;
rule.end = new Date(2005, 12, 31);
event.repeatRule = rule;
Message component
The Message component can be used to create a new email message that is to be sent or to retrieve an email
message that is stored on the device. Message is a keyed data collection.

bccRecipients string list of additional contact email addresses in the Bcc field of a message
ccRecipients string list of additional contact email addresses in the Cc field of a message
content string body text of the message
folder FOLDER specifies the folder in which to store the message; by default it stores messages in the
enumerated Sent folder; this field is read-only; FOLDER is a pre-defined enumerated type
from string sender email address; this field is read-only
priority PRIORITY priority of the message; PRIORITY is a predefined enumerated type with values of HIGH,
enumerated NORMAL, or LOW
replyTo string email address that the reply to this message should be sent to; if this field is not set, the
field uses the value in the from field; this field is read-only
subject string subject of the message
toRecipients string list of the recipient email addresses in the To field of a message
uid integer primary key that contains the unique identifier of the message; this field is read-only
Task component
The Task data component is used to add or search for tasks in the task list on the BlackBerry device. Task is a keyed
data collection.

note string more complete description than the summary field
27

status STATUS status of the task; the default value is NOT_STARTED
enumerated STATUS is a predefined enumerated data type with the following values:
NOT_STARTED—task is incomplete
IN_PROGRESS—task is in progress
COMPLETED—task is complete
WAITING—waiting for a task-related event
DEFERRED—task is postponed
priority PRIORITY priority of the task; PRIORITY is a predefined enumerated type with values of HIGH, NORMAL, or
enumerated LOW
summary string brief description of the task
uid integer primary key that contains the unique identifier of the task; this field is read-only
Code sample: Using task component fields

var t = Task.create();
t.summary = "Something to do";
t.note = "This is a more detailed description for what I have to do";
t.status = STATUS.IN_PROGRESS;
t.due = new Date(2004, 12, 31);
System component
The System component does not contain any fields but provides the following system functions:
• exit()
• loadURL()
• startCall()
DeviceInfo component
The DeviceInfo component enables you to inspect BlackBerry device information. This component is read-only,
and you cannot assign new values to the component.
Field name Type Description

IMSI string International Mobile Subscriber Identity (IMSI) number; wireless devices that have a SIM card use
this number
IMEI string International Mobile Equipment Identity (IMEI) number; valid for wireless devices that operate on
Global System for Mobile Communication (GSM) and iDEN networks; if called on a device on a
CDMA network, it returns the electronic serial number (ESN)
phoneNumber string telephone number of the device, if any; returns UNKNOWN if the telephone feature is unavailable
PIN string personal identification number (PIN) of the device
28
Error component
The Error data component enables you to retrieve error information when an error occurs. This component is read-
only and cannot be assigned new values. A default error handling script is generated for the application by the
BlackBerry MDS Studio. This script is run by the BlackBerry MDS Runtime when an error situation is detected. This
script can be modified or extended by the developer of the BlackBerry MDS Studio application.
Field name Type Description

category integer category the error belongs to; see the table below for a list of error categories
code integer error code or identifier; see the table below for a list of codes
description string error description
data string more detailed description of the error
name string name of the error; this field usually is used to indicate the specific type of a connector error; see the
example below
requestName string name of the corresponding request message that is related to the error; refer to the example below
29
Error categories
Category Meaning
CATEGORY_MDS_SERVICES_ERROR BlackBerry MDS Services error
CATEGORY_MDS_RE_ERROR BlackBerry MDS Runtime error
CATEGORY_CONNECTOR_ERROR type of errors that occur in the back-end connectors such as web service and database connector
Error codes
Code Meaning Category
METADATA_ERROR metadata error MDS_RE_ERROR
OUT_QUEUE_FULL queue for outgoing messages is full MDS_RE_ERROR
OUT_QUEUE_CRITICAL queue for outgoing messages is almost full MDS_RE_ERROR
JAVA_SCRIPT_ERROR runtime ECMAScript error MDS_RE_ERROR
INCOMING_MESSAGE_ERROR error occurs when receiving a message MDS_RE_ERROR
OUTGOING_MESSAGE_ERROR error occurs when sending a message MDS_RE_ERROR
SERVER_INTERNAL_ERROR BlackBerry MDS Services has an internal error MDS_SERVICES_ERROR
SERVER_MAPPING_ERROR error occurs during mapping of BlackBerry MDS Studio MDS_SERVICES_ERROR
application complex data types to data source defined
data types by BlackBerry MDS Services
SERVER_TRANSFORMATION_ERROR transformation error occurs on BlackBerry MDS Services MDS_SERVICES_ERROR
SERVER_SECURITY_ERROR security error occurs on BlackBerry MDS Services MDS_SERVICES_ERROR
BACKEND_CONNECTOR_ERROR backend connector error MDS_SERVICES_ERROR
MESSAGE_TOO_LARGE a message is too large to be processed MDS_SERVICES_ERROR
SOAP_AUTH_ERROR authorization error CONNECTOR_ERROR
SOAP_SECURITY_ERROR Simple Object Access Protocol (SOAP) security error CONNECTOR_ERROR
SOAP_ENDPOINT_UNAVAILABLE_ERROR endpoint is unavailable CONNECTOR_ERROR
SOAP_MESSAGE_INVALID_ERROR message is invalid CONNECTOR_ERROR
SOAP_CONNECTOR_ERROR SOAP connector error CONNECTOR_ERROR
SOAP_BACKEND_ERROR SOAP fault received from the web service, pool error CONNECTOR_ERROR
during web service connection, or web service request
time out
SOAP_NETWORK_ERROR occurs when proxy error codes HTTP 502 or HTTP 504 are CONNECTOR_ERROR
received
WSE_SUBSCRIBE_ERROR subscription request fails CONNECTOR_ERROR
WSE_UNSUBSCRIBE_ERROR unsubscription request fails CONNECTOR_ERROR
WSE_UNSUBSCRIBE_SUBSCRIPTION_NOT_ an unsubscribe request is received, but no corresponding CONNECTOR_ERROR
FOUND_ERROR subscription is found
Logger component
The Logger component enables you to log runtime messages. You can log three types of messages from a script:
INFORMATION, WARNING and ERROR.
30
Organizer enumerated data types

The following list provides the names of the predefined enumeration data types that you can use.
Data type Description

FREEBUSY FREEBUSY provides the status of a person involved in an event. The
definition is described by the following pseudo-code:
• FREE
• TENTATIVE
• BUSY
• OUT_OF_OFFICE
FOLDER FOLDER is used to specify the folder where the copy of an outgoing email
should be stored. The enumeration data type is defined to have the
following fields:
• INBOX
• SENT
PRIORITY PRIORITY defines three priority levels. This enumeration data type is
used by Message and ToDo data components. The enumeration carries
the following fields:
• HIGH
• NORMAL
• LOW
STATUS STATUS defines the status of a task or to-do. The definition has the
following fields:
• NOT_STARTED
• IN_PROGRESS
• COMPLETED
• WAITING
• DEFERRED
ATTENDEE_TYPE ATTENDEE defines the types of an attendee. The definition has the
following fields:
• ORGANIZER
• INVITED
• ACCEPTED
• DECLINED
• TENTATIVE
REPEAT_RULE_FREQUENCY REPEAT_RULE_FREQUENCY enumerates data types of repeat-
frequency used in a RepeatRule data component. The definition has the
following fields:
• NONE
• DAILY
• WEEKLY
• MONTHLY
• YEARLY
31
32
4
Application integration
Organizer applications
GPS access
BlackBerry MDS Runtime application integration
Java application integration
Invoke other BlackBerry applications from your BlackBerry MDS Runtime application using the System.exec() function.
Organizer applications
Address Book application
Access the Address Book application.
var contact = Contact.create()
var isNewView = true;
System.exec(APP_TYPE.ADDRESSBOOK.contact); //opens the Address Book with the specified

contact.
System.exec(APP_TYPE.ADDRESSBOOK.isNewView); //opens the Address Book application if

isNewView is false; otherwise, creates a new contact.
System.exec(APP_TYPE.ADDRESSBOOK); //opens the Address Book application.
Parameters
Parameter Description
contact Contact to view or create in the Address Book application.
Calendar application
Access the Calendar application.
var event = Event.create()
var date = newDate;
System.exec(APP_TYPE.CALENDAR.CALENDAR_VIEW.DAY); //opens the Calendar application in

DAY view (can also use WEEK, MONTH, AGENDA, DEFAULT).
System.exec(APP_TYPE.CALENDAR.CALENDAR_VIEW.DAY, date); //opens the Calendar

application in DAY view with the specified date.
System.exec(APP_TYPE.CALENDAR.CALENDAR_VIEW.DAY, event); //opens the Calendar

application in DAY view at the specified event.
System.exec(APP_TYPE.CALENDAR.event); //opens the Calendar application with the

specified event.
System.exec(APP_TYPE.CALENDAR); //opens the Calendar application with the default view.
Parameters
event Event to view or create in the Calendar application.
date Date to view in the Calendar application.
Email application
Access the Email application.
var message = Message.create();
message.subject = "Hey";
message.recipients = "jblack@bb.com";
message.content = "How are you?";
System.exec(APP_TYPE.EMAIL, message); //opens the Email compose window with the

specified message.
System.exec(APP_TYPE.EMAIL, to, subject, content); //opens the Email compose window

with specified recipients, subject, and content.
var recipients = jblack@bb.com;

var subject = "Hey";
var content = "How are you?";
var isPIN = true;
System.exec(APP_TYPE.EMAIL, recipients, subject, content, isPIN); //opens the Compose

email window if isPIN is false; otherwise, composes a PIN message).
System.exec(APP_TYPE.EMAIL, EMAIL_VIEW.NEW); //opens the Compose email window (use

NEW_PIN to compose a PIN message).
System.exec(APP_TYPE.EMAIL, EMAIL_VIEW.NEW_SMS); //opens the Contact list to send an

SMS.
System.exec(APP_TYPE.EMAIL, EMAIL_VIEW.NEW_MMS); //opens the Contact list to send an

MMS.
System.exec(APP_TYPE.EMAIL, EMAIL_VIEW.SAVED); //opens the Saved email list window.
System.exec(APP_TYPE.EMAIL, EMAIL_VIEW.SEARCH); //opens the Search email window.
System.exec(APP_TYPE.EMAIL, EMAIL_VIEW.DEFAULT); //opens the default Email list window.
System.exec(APP_TYPE.EMAIL); //opens the Email list window.
34
4: Application integration
Parameters
message Newly drafted or created email to send.
content Content of the new message.
recipients Recipients for the message.
subject Subject for the message.
Phone application
Access the Phone application.
var isSmartDialing = false;
System.exec(APP_TYPE.PHONE, "5553214567", isSmartDialing); //dials the specified number

using smart dialing, only if isSmartDialing is true.
System.exec(APP_TYPE.PHONE, "5553214567"); //dials the specified number using smart

dialing.
System.exec(APP_TYPE.PHONE, "voicemail"); //dials the voice mail number.
System.exec(APP_TYPE.PHONE); //opens the Phone application.
Parameters
number Phone number to dial in the Phone application.
Maps application
Access the Maps application.
var contact = Contact.create();
var addressIndex = 1;
System.exec(APP_TYPE.MAPS, contact, addressIndex); //opens the Map application and

searches the specified contact’s address.
System.exec(APP_TYPE.MAPS, contact); //opens the Map application and searches the

specified contact’s address.
var address = Address.create();

address.addrCountry = "Canada";
address.addrLocality = "Waterloo";
address.addrRegion = "Ontario";
address.addrStreet = "555 Berry Way";
System.exec(APP_TYPE.MAPS, address); //opens the Map application and searches the

specified address.
var location = "<location-document><location x=’4500000’ y=’-7500000’/></location-

document>";
35
System.exec(APP_TYPE.MAPS, location); //opens the Map application and searches the

specified coordinates.
System.exec(APP_TYPE.MAPS); //opens the Map application.
Parameters
contact Name of a contact in the address book.
addressIndex Phone book address of the contact to use, from 0 to 9.
address Address to search on the map.
location Coordinates to search on the map.
Tasks application
Access the Tasks application.
var task = Task.create()
var isNewView = true;
System.exec(APP_TYPE.TASKS.task); //opens the Task edit window with the specified task.
System.exec(APP_TYPE.TASKS.isNewView); //opens the Task application if isNewView is

false; otherwise, creates a new task.
System.exec(APP_TYPE.TASKS); //opens the Task application.
Parameters
task Task to open or create in the Tasks application.
GPS access
Access GPS-related information.
blackberry.location.refreshLocation(); //updates the BlackBerry location.
blackberry.location.onLocationUpdate(var method); //registers a callback method to be

called when the location changes.
blackberry.location.setAidMode(var aidMode); //sets the aid mode to be used.
blackberry.location.GPSSupported; //determines whether GPS is supported on the

BlackBerry Smartphone.
blackberry.location.longitude; //determines the current longitude.
blackberry.location.latitude; //determines the current latitude.
36
4: Application integration
Parameters
method Method to call when the location changes.
aidMode The aid mode to use: 0 for cellsite, 1 for assisted, and 2 for autonomous.
BlackBerry MDS Runtime application integration

Start a BlackBerry MDS Runtime application.
System.exec(APP_TYPE.MDS, "rim.net/lookup"); //runs the BlackBerry MDS Runtime
application using the specified URI.
System.exec(APP_TYPE.MDS, "rim.net/lookup?what=coffee&where=M4M"); //opens the

application using the specified parameters.
var parameters = ["what=coffee","where=M4M"];
System.exec(APP_TYPE.MDS, "rim.net/lookup", parameters); //opens the application using

the specified parameters.
Parameters
parameters A string array of parameters for the application.
Java application integration

Start a Java application.
System.exec(APP_TYPE.JAVA, "lookup"); //opens a Java application named "lookup."
System.exec(APP_TYPE.JAVA, "lookup.findBusiness?"); //opens the application at the

findBusiness entry point.
System.exec(APP_TYPE.JAVA, "lookup.findBusiness?what=coffee&where=M4M"); //opens the

application at the findBusiness entry point, using the specified parameters.
var parameters = ["what=coffee","where=M4M"];
System.exec(APP_TYPE.JAVA, "lookup.findBusiness", parameters); //opens the application

at the findBusiness entry point, using the specified parameters.
Parameters
parameters A string array of parameters for the application.
37
38
5
BlackBerry MDS Studio functions
Screen functions
Data functions
Message functions
Organizer functions
You cannot create message and screen components explicitly using script, but they are available to the BlackBerry
MDS Studio environment and behave similarly to other JavaScript object types. You can create data component
instances using the create() function.
Screen functions
Function: close
This function closes the current screen. If the screen is not the only one on the stack, the previous screen is
displayed. If it is the only screen, the BlackBerry MDS Runtime Application would exit.
void close([boolean keepOnScreenData])
Code sample: Using the close function

Screen.close(); // close without keeping the on-screen data.
Screen.close(true); // close but keep the on-screen data.
Parameters
keepOnScreenData True to keep the data entered on the screen that is about to close, otherwise, discard the data;
default value is false
Returns
This function returns nothing.
Function: display
This function displays a dialog of the type specified, presenting the message string provided.
int display(string:msg [, int:dialog_type])
Code sample: Using the display function

if(Dialog.display("Do you wish to continue?", Dialog.YES_NO) == Dialog.YES_BUTTON) {
// continue …
}
Parameters
msg string to display
dialog_type either Dialog.OK or Dialog.YES_NO. The default is OK.
Returns
This function returns the result of your selection, indicating the specified button type.
Function: refresh
This function refreshes the current screen.
void refresh()
Code sample: Using the refresh function

Screen.refresh();
Returns
Data functions
Function: all
This function returns all instances of the collection identified by the BlackBerry MDS Studio data component
name.
Array all()
Code sample: Using the all function

var everyHorse = Horse.all();
i = 0;
while(i < everyHorse.length) {
Dialog.display("Found horse: " + everyHorse[i].name);
i++;
}
Returns
This function returns the entire collection. This might result in an empty array.
40
5: BlackBerry MDS Studio functions
Function: create (keyless data)

This function creates a new instance of the keyless data component.
Object create()
Code sample: Using the create function with keyless data components
var aAddress = Address.create();
Returns
This function returns the new keyless data instance.
Function: create (multiple primary keys)

This function creates new instances of data components using the primary keys supplied. If the data matching a
primary key already exists, that instance is returned.
Object create({Object:pkey1, Object:pkey2 ...})
Code sample: Using the create function

var aHorse = Horse.create({Name:"Tigrina",Age:7});
Parameters
pkey primary key values used to create the data component instance; the data type of pkey can be string, integer, decimal, date,
enumeration, or keyed data component
In the BlackBerry MDS Studio, you cannot specify a boolean value for a primary key.
If another instance with this primary key is found, that instance is returned. The create() function never returns a null
value.
Returns
This function returns the new or found keyed data instances.
Function: create (single primary key)

This function creates a new instance of the data component using the primary key supplied. If the data matching
the primary key already exists, that instance is returned.
Object create(Object:pkey)
Code sample: Using the create function

var aHorse = Horse.create("Tigrina");
41
Parameters
pkey primary key value used to create the data component instance; the data type of pkey can be string, integer, decimal, date,
enumeration, or keyed data component
In the BlackBerry MDS Studio, you cannot specify a boolean value for a primary key.
If another instance with this primary key is found, that instance is returned. The create() function never returns a null
value.
Returns
This function returns the new or found keyed data instance.
Function: display
This function displays the named screen using the specified arguments.
void display(Data:parm1, Data:parm2 …)
Code sample: Using the display function

scrNextRegisterNewPlayer.display(playerDetails);
Parameters
parm data component objects passed to the screen for display; the number required is dependent upon the screen definition
Returns
Function: find (multiple primary keys)

This function is available only for keyed data collections. It finds the data component instance resolved by the
primary keys. If the instance is not found, it is not created (unlike the create() function).
Object find({Object:pkey1, Object:pkey2 ...})
Code sample: Using the find function

var AnotherHorse = Horse.find({Name="Tigrina",Age=6});
Parameters
pkey primary keys used to resolve the keyed data component; it can be one of the primitive data types (except boolean) or a keyed
data component that is one of the primary keys
Returns
This function returns the found instance or null if an instance is not found.
42
Function: find (single primary key)

This function is available only for keyed data collections. It finds the data component instance resolved by the
primary key. If the instance is not found, it is not created (unlike the create() function).
Object find(Object:pkey)
Code sample: Using the find function

var aHorse = Horse.create("Tigrina");
if(aHorse == null) {
// Would never get here…
Dialog.display("Cannot happen");
}
var someOtherHorse = Horse.find("Awesome American");
if(someOtherHorse == null) {
newHorse = Horse.create("Awesome American");
}
Parameters
pkey primary key used to resolve the keyed data component; it can be one of the primitive data types (except boolean) or a keyed
data component that is the primary key
Returns
This function returns the found instance or null if an instance is not found.
Function: findWhere
This function is available only for keyed data components.
Array findWhere(string:clause)
Code sample: Using the findWhere function

// findWhere based on comparison to simple literal. Returns
// an array.
var horses = Horse.findWhere("rank ='101'");
if(horses.length == 0) {
Dialog.display("No horses found.");
} else {
Dialog.display(horses.length + " horse(s) is(are) found.");
}
// findWhere based on comparison to dynamic value

var selectedH = Horse.findWhere("rank ='" +
scrTrackInfo.chRaces.value[scrTrackInfo.chRaces.selected] + "'");
Parameters
clause - "[fieldname operator value][ORDERBY fieldname_orderby ASC/DESC]"
43
One, or the other, or both parts can be provided.
Parameter Explanation
fieldname field name; arrays are not supported, but if the field is a data component, the equal (=) and not equal (<>) operators
are supported
operator = (equal)
<> (not equal)
!= (not equal)
< (less than)
<= (less or equal)
> (greater than)
>= (greater or equal)
Only = and <> are supported for data components.
value value for comparison; when a literal value is specified it must be enclosed in single or double quotation marks
fieldname_orderBy field used for sorting the results; it can only be a nonarray primitive field
Returns
This function returns an array. The array is empty if nothing is found.
Function: pop
This function removes the last element from the array.
void pop()
Code sample: Using the pop function

// Horse is a data definition…
// Create first new horse Tigrina
var newHorse1 = Horse.create("Tigrina");
// Create second new horse Awesome American
var newHorse2 = Horse.create("Awesome American");
// Horse collection is backed by MDS array, store that in myHorses
var myHorses = Horse.all();
// Remove the last index; Awesome American
myHorses.pop();
Returns
Function: property
This function returns the number of elements in the array.
property: length
Code sample: Using the property function

// Get the number of horses in a race, Race component
44
// is keyed by the race number

var raceNo = 1;
var theRace = Race.find(raceNo);
var numberOfHorses = theRace.horses.length;
Dialog.display("There are " + numberOfHorses + " running today");
Returns
This function returns the number of elements in the array.
Function: push
This function adds the provided objects, in order, to the end of the array.
void push(Object:parm1, Object:parm2 …)
Code sample: Using the push function

var raceNo = 1;
var race = Race.find(raceNo);
var horse1 = Horse.create("Tigrina");
var horse2 = Horse.create("Awesome American");
if(race != null){
}race.horses.push(horse1, horse2);
else{
race = Race.create(raceNo);
race.horses.push(horse1,horse2);
}
Parameters
parm objects to be pushed into the array
Returns
Function: remove
This function removes the data instance.
void remove()
Code sample: Using the remove function

var oldHorse = Horse.find("Tigrina");
oldHorse.remove();
Returns
45
Function: remove
This function removes the object instances.
void remove(Object:parm1, Object:parm2 …)
Code sample: Removing object instances

// Race data component definition contains
// nested array field of Horse data components.
var horse1 = Horse.find("Tigrina");
var horse2 = Horse.find("Awesome American");
race.horses.remove(horse1, horse2);
Parameters
parm objects to be removed from the array
Returns
Function: removeAll
This function is available only for keyed data collections. It removes all instances of the collection identified by the
BlackBerry MDS Studio data component name.
void removeAll()
Code sample: Using the removeAll function

// removes all horses from the environment
Horse.removeAll();
// horses is an array on the track data component (resolved elsewhere

// via .create() or .find(), or passed as a parameter). Horses field
// contains instances of Horse data components. The following
// empties the horses array.
track.horses.removeAll(); //empties horses array from track component
Returns
Message functions
Function: contains
This function confirms whether or not this instance is contained.
boolean contains(Object:parm)
46
Code sample: Finding the contained instance of an object

var raceNo = 1;
var race = Race.find(raceNo);
var oldHorse = Horse.find("Tigrina");
if(race.horses.contains(oldHorse)){
Dialog.display(oldHorse.name + " is available");
}
Parameters
parm object to find
Returns
This function returns true if contained, false is returned otherwise.
Function: send
This function sends the named message.
outSubmitBet.send();
Returns
Organizer functions
Function: exit
This function exits the current running BlackBerry MDS Studio application.
System.exit();
Returns
Function: loadURL
This function loads the URL specified and brings the browser to the foreground.
System.loadURL("www.rim.com")
47
Parameters
URL string of the URL to be loaded by the browser, for example, “http://www.rim.com”
Returns
Function: log
This function logs the message specified.
void log(string source, string message[, int type])
Code sample: Using the log function

Logger.log("myScript", "the script started", Logger.INFORMATION);
// do sth.
Logger.log("myScript", "An error", Logger.ERROR);
Logger.log("myScript", "A warning", Logger.WARNING);
// last parameter is optional, information will be assumed.

Logger.log("myScript","The script is finished");
Parameters
source source of the message, for example, "myScript"; this parameter is optional
message message to log
type type of message; it can be any of the following:
• Logger.INFORMATION
• Logger.WARNING
• Logger.ERROR
Logger.INFORMATION is the default
Returns
Function: send
This function sends an email message to the addresses specified in the To, cc, and bcc fields.
Code sample: Using the send function

var mail = Message.create();
mail.toRecipients = "bill@sample.com; smith@sample.com";
mail.subject = "Hello";
mail.content = "This is the body text";
var status = mail.send();
if(status == Message.SENT) {
48
Dialog.display("The email is sent successfully.");

}
Returns
This function returns the status of the message being sent. The status will be one of the following:
• Message.SENT - Sent successfully.
• Message.ERROR_OCCURRED - An error occurs and the message is not sent.
• Message.SAVED_DRAFT - The message is saved as draft and is not sent.
Function: startCall
This function makes a phone call using the specified telephone number.
System.startCall("4165554444");
Parameters
number telephone number to call
Returns
49
50
©2008 Research In Motion Limited
Published in Canada.

Blackberry MDS Studio Javascript Reference Guide

Загружено:

Сведения о документе

Исходное описание:

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Blackberry MDS Studio Javascript Reference Guide

Загружено:

Авторское право:

Доступные форматы

BlackBerry MDS Studio

JavaScript Reference Guide

Last modified: 1 October 2008

Part number: 15129096

Send us your comments on product documentation: https://www.blackberry.com/DocsFeedback.

Research In Motion Limited Research In Motion UK Limited

BlackBerry MDS Studio components and script .......................................................................................... 21

Organizer data access .......................................................................................................................................27

Application integration .....................................................................................................................................37

BlackBerry MDS Studio functions .................................................................................................................. 43

Enumerated data types

Date data types

Binary data types

Example: Converting a binary field to a numeric array

Example: Converting to a binary field from a numeric array

Data type conversion

Conversion rules for boolean values

Conversion rules for integer values

Conversion rules for decimal values

Conversion rules for long values

Conversion rules for string values

Conversion rules for date values

Conversion rules for enumerated values

Conversion rules for BlackBerry MDS Studio component values

Data type conversion errors

BlackBerry MDS data component global symbols

Keyed and keyless data collection

Screen component access

Screen field access

Example: Setting the visibility of a region

// hide the editbox and refresh the screen

Check box fields

Example: Using the checkbox control with script

Single value control fields

Example: Assigning a value to an editbox

Multiple value control fields

Field type Field extension Return data type

Example: Returning a string from selected text

Repetition control fields

Example: Getting the mapping field of a repetition control

Table control fields

Example: Returning a string from selected text

Menu keyword access

Code sample: Defining menu items

Message component access

Message field access

Data component access and creation

// Personal Profile is de-referenced off the UserProfile "user" through the

Data field access

Application global variables

Code sample: assigning a name to a global variable

Field name Data type Description

Field name Data type Description

Code sample: Using the Contact component

Field name Data type Description

Field name Data type Description

Code sample: Using the Address component

Field name Data type Description

Code sample: Using the Event component

Code sample: Finding an event using the where clause

Field name Data type Description

Code sample: Using the Attendee component

// This technique adds two new attendees directly