blackberry mds studio javascript reference guide

8/9/2019 Blackberry MDS Studio Javascript Reference Guide

1/52

BlackBerry MDS Studioversion 2.0

JavaScript Reference Guide


2/52

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. Visitwww.rim.com/patentsfor 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 ARISINGFROM 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 TYPEOF 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
https://www.blackberry.com/DocsFeedbackhttp://www.rim.com/patentshttp://www.blackberry.com/go/docshttps://www.blackberry.com/DocsFeedbackhttp://www.blackberry.com/go/docshttp://www.blackberry.com/go/docshttp://www.rim.com/patents


3/52

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 ORRECEIVE 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 ORRELATED 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.

Published in Canada

Research In Motion Limited295 Phillip StreetWaterloo, ON N2L 3W8Canada

Research In Motion UK LimitedCentrum House, 36 Station RoadEgham, Surrey TW20 9LFUnited Kingdom


4/52


5/52

ContentsStandard environment .................. ..................... ................... .................... ..................... ..................... .............. 13

Data types ........................................................................................................................................................ 13

Enumerated data types .......................................................................................................................... 14

Date data types ....................................................................................................................................... 14

Binary data types .....................................................................................................................................14

Data type conversion ..............................................................................................................................14Parameters .......................................................................................................................................................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 .................................................................................... 29Event 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 ............................................................................... 31Message component ...................................................................................................................................... 31


6/52

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 ....................................................................................................................................39Tasks 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) ............................................................................................................ 45Function: 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 ..........................................................................................................................................48Function: property ..................................................................................................................................48


7/52

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 ...................................................................................................................................51Function: log ........................................................................................................................................... 52

Function: send ........................................................................................................................................ 52

Function: startCall .................................................................................................................................. 53


8/52


9/52

1

Standard environment

Data typesThe 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.

Data types

Parameters

Global symbols


10/52

10

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 typesThe 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 typesThe 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_binmyVar = g_bin.toArray();

Example: Converting to a binary field from a numeric array// Convert the array to a binaryg_bin = myNumArray;

Data type conversionThe 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.


11/52

11

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.


12/52

12


Conversion rules for boolean values

Conversion rules for integer values

Conversion rules for decimal 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

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

Input value Result

BlackBerry MDS Studio component NaN

boolean 1 if true, 0 if false

date the number of milliseconds past January 1st, 1970

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, NaNundefined NaN


13/52


14/52

14


Conversion rules for enumerated values

Conversion rules for BlackBerry MDS Studio component values

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 BlackBerryMDS Studio Script Editor. You can define multiple parameters, only as type BlackBerry MDS data component.

Input value Result

BlackBerry MDS Studio component data type error

boolean data type error

date data type error

decimal data type error

enumeration not applicable

integer data type error

long data type error

null data type error

string (case-insensitive) convert a proper string representation of enumeration value; otherwise, a data type error is

generated

undefined data type error

Input value Result

BlackBerry MDS Studio component not applicable

boolean data type error

date ignored if assigned to a global or keyless field; otherwise, set to null

decimal data type error

enumeration ignored if assigned to a global or keyless field; otherwise, set to null

integer data type error

long data type error

null ignored if assigned to a global or keyless field; otherwise, set to null

string (case-insensitive) data type error

undefined data type error


15/52

15

1: Standard environment

Global symbols

DialogThe Dialog global symbol enables script-based control of BlackBerry MDS Runtime dialog boxes.

ScreenThe Screen global symbol enables you to control screen management using script.

BlackBerry MDS data component global symbolsA 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 youexplicitly 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.

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


16/52

16



17/52

2

BlackBerry MDS Studio components andscript

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 accessA 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 accessYou 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 settingscrMain.myDetailRegion.visible = gvShowDetail;

// hide the editbox and refresh the screenscrMain.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.

Screen component access

Message component access

Data component access and creation


18/52

18


Single value control fieldsThe 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 editboxvar 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 fieldsChoice 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.

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 stringvar choicesString = "";var choices = scrHorseRacing.slPlacedBets.value; // Returns an arrayfor(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.

Field type Field extension Return data type

Choice .selected

.selectedValue

.value

.mapping

single integer-based index indicating the current selection

value of the output mapping of control

array of string or date

selected item

Multichoice .selected

.selectedValue

.value

.mapping

array of indexes

value of the output mapping of controlarray of string or date

array of selected items


19/52

19

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 repetitioncontrols.

Example: Getting the mapping field of a repetition control// Dereference the data component field by using the mapping propertyvar 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.

Example: Returning a string from selected text

// gets the string value of the currently selected cellvar cell = scrMain.table1.columns[scrMain.table1.selectedColumnIndex][scrMain.table1.selectedRowIndex];

Menu keyword accessA 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 itemsif(isLogin) {

scrLogin.MENU.login.visible = false;scrLogin.MENU.logout.visible = true;

} else {scrLogin.MENU.login.visible = true;scrLogin.MENU.logout.visible = false;

}

Message component accessEach message defined in the application is available to the script as a global symbol.

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.


20/52

20


Message field accessYou 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 creationYou 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 throughthe profile field and is passed to the send function on outProfileInfo message.

// UserProfile is first foundvar 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 thefield, 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.

ArraysArrays 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 subtledifferences. 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 explicitpush() 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.


21/52

21

2: BlackBerry MDS Studio components and script

Application global variablesA 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;}


22/52


23/52

3

Organizer data access

Organizer data is exposed to the BlackBerry MDS Studio application through a set of standard data componentdefinitions. 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 componentThe 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.

Contact component

Address component

Event component

Attendee component

RepeatRule component

Message component

Task component

System component

DeviceInfo component

Error component

Organizer enumerated data types

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

l k S S di S i i


24/52

24


Code sample: Using the Contact component// No need to supply a key value herevar c = Contact.create();c.nameTitle = "Mr.";c.nameGiven = "John";c.nameFamily = "Smith";c.Email1 = "[email protected]";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 componentThe Address keyless data component is part of the Contact keyed data component. Address data components have

no primary key.

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


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


3 O gani e data access


25/52

25

3: Organizer data access

Code sample: Using the Address componentvar c = Contact.create();c.nameTitle = "Mr.";c.nameGiven = "John";c.nameFamily = "Smith";c.Email1 = "[email protected]";

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 componentThe Event data component finds or creates meetings and appointments in the calendar application. Event is a

keyed data collection.

Code sample: Using the Event componentvar 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);

addrRegion string region information, for example, province, state, territory, of a particular address

addrStreet string street of a particular address


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 enumerated

free or busy status for the event, FREEBUSY is a predefined enumerated data type with

values ofFREE, 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




26/52

26


e.attendees.push(Attendee.create(), Attendee.create());e.attendees[0].address = "[email protected]";e.attendees[1].address = "[email protected]";

e.free_busy = FREEBUSY.OUT_OF_OFFICE;e.allday = true;

Code sample: Finding an event using the where clausee = Event.findWhere("start = 'Jan 1, 2004'");e[0].note = "New Year's Day";

Attendee componentThe Attendee keyless data component is part of the Event keyed data component. Attendee data components donot have a primary key.

Code sample: Using the Attendee componentvar 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 evente.attendees.push(Attendee.create(), Attendee.create());e.attendees[0].address = "[email protected]";e.attendees[1].address = "[email protected]";e.free_busy = FREEBUSY.OUT_OF_OFFICE;e.allday = true;

RepeatRule componentThe 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.


address string email address of an attendee

type ATTENDEE_TYPEenumerated

type of a particular attendee; ATTENDEE_TYPE is a predefined enumerated type with

values ofORGANIZER, INVITED, ACCEPTED, DECLINED, TENTATIVE; the default

value is INVITED; this field is read-only


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



27/52

27


Code sample: Using the RepeatRule componentvar 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 componentThe 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.

Task componentThe Task data component is used to add or search for tasks in the task list on the BlackBerry device. Task is a keyeddata collection.

frequency REPEATE_RULE_FREQUENCY enumerated

frequency of an event; the default value is NONE, which means that the

event occurs once; REPEAT_RULE_FREQUENCY is a predefined enumeratedtype with the following values: NONE, DAILY, WEEKLY, MONTHLY, YEARLY

Field name Data type DescriptionbccRecipients 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 FOLDERenumerated

specifies the folder in which to store the message; by default it stores messages in the

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 enumerated

priority of the message; PRIORITY is a predefined enumerated type with values ofHIGH,

NORMAL, or LOWreplyTo 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


note string more complete description than the summary field




28/52

28

y p

Code sample: Using task component fieldsvar 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 componentThe System component does not contain any fields but provides the following system functions:

exit()

loadURL()

startCall()

DeviceInfo componentThe DeviceInfo component enables you to inspect BlackBerry device information. This component is read-only,

and you cannot assign new values to the component.

status STATUSenumerated

status of the task; the default value is NOT_STARTED

STATUS is a predefined enumerated data type with the following values:

NOT_STARTEDtask is incomplete

IN_PROGRESStask is in progress

COMPLETEDtask is complete

WAITINGwaiting for a task-related event

DEFERREDtask is postponed

priority PRIORITY enumerated

priority of the task; PRIORITY is a predefined enumerated type with values ofHIGH, NORMAL, or

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

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




29/52

29

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


30/52



31/52

31

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 emailshould 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


32/52

4


33/52

4

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 specifiedcontact.

System.exec(APP_TYPE.ADDRESSBOOK.isNewView); //opens the Address Book application ifisNewView is false; otherwise, creates a new contact.

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

Parameters

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 inDAY view (can also use WEEK, MONTH, AGENDA, DEFAULT).

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

System.exec(APP_TYPE.CALENDAR.CALENDAR_VIEW.DAY, event); //opens the Calendarapplication in DAY view at the specified event.

Organizer applications

GPS access

BlackBerry MDS Runtime application integration

Java application integration

Parameter Description

contact Contact to view or create in the Address Book application.



34/52

34

System.exec(APP_TYPE.CALENDAR.event); //opens the Calendar application with thespecified event.

System.exec(APP_TYPE.CALENDAR); //opens the Calendar application with the default view.

Parameters

Email applicationAccess the Email application.

var message = Message.create();message.subject = "Hey";message.recipients = "[email protected]";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 windowwith specified recipients, subject, and content.

var recipients = [email protected];var subject = "Hey";var content = "How are you?";var isPIN = true;

System.exec(APP_TYPE.EMAIL, recipients, subject, content, isPIN); //opens the Composeemail window if isPIN is false; otherwise, composes a PIN message).

System.exec(APP_TYPE.EMAIL, EMAIL_VIEW.NEW); //opens the Compose email window (useNEW_PIN to compose a PIN message).

System.exec(APP_TYPE.EMAIL, EMAIL_VIEW.NEW_SMS); //opens the Contact list to send anSMS.

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

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.


event Event to view or create in the Calendar application.

date Date to view in the Calendar application.

4: Application integration


35/52

35

Parameters

Phone application

Access the Phone application.var isSmartDialing = false;

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

System.exec(APP_TYPE.PHONE, "5553214567"); //dials the specified number using smartdialing.

System.exec(APP_TYPE.PHONE, "voicemail"); //dials the voice mail number.

System.exec(APP_TYPE.PHONE); //opens the Phone application.

Parameters

Maps applicationAccess the Maps application.var contact = Contact.create();var addressIndex = 1;

System.exec(APP_TYPE.MAPS, contact, addressIndex); //opens the Map application andsearches the specified contacts address.

System.exec(APP_TYPE.MAPS, contact); //opens the Map application and searches thespecified contacts 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 thespecified address.

var location = "";

Parameter Descriptionmessage Newly drafted or created email to send.

content Content of the new message.

recipients Recipients for the message.

subject Subject for the message.


number Phone number to dial in the Phone application.



36/52

36

System.exec(APP_TYPE.MAPS, location); //opens the Map application and searches thespecified coordinates.

System.exec(APP_TYPE.MAPS); //opens the Map application.

Parameters

Tasks applicationAccess 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 isfalse; otherwise, creates a new task.

System.exec(APP_TYPE.TASKS); //opens the Task application.

Parameters

GPS accessAccess 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 theBlackBerry Smartphone.

blackberry.location.longitude; //determines the current longitude.blackberry.location.latitude; //determines the current latitude.


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.


task Task to open or create in the Tasks application.

4: Application integration


37/52

37

Parameters

BlackBerry MDS Runtime application integrationStart 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 theapplication using the specified parameters.

var parameters = ["what=coffee","where=M4M"];

System.exec(APP_TYPE.MDS, "rim.net/lookup", parameters); //opens the application usingthe specified parameters.

Parameters

Java application integrationStart 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 thefindBusiness entry point.

System.exec(APP_TYPE.JAVA, "lookup.findBusiness?what=coffee&where=M4M"); //opens theapplication 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 applicationat the findBusiness entry point, using the specified parameters.

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.


parameters A string array of parameters for the application.


parameters A string array of parameters for the application.



38/52

38

5


39/52

5

BlackBerry MDS Studio 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: closeThis 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 functionScreen.close(); // close without keeping the on-screen data.Screen.close(true); // close but keep the on-screen data.

Parameters

Returns

This function returns nothing.

Function: displayThis function displays a dialog of the type specified, presenting the message string provided.

int display(string:msg [, int:dialog_type])

Screen functions

Data functions

Message functions

Organizer functions


keepOnScreenData True to keep the data entered on the screen that is about to close, otherwise, discard the data;

default value is false



40/52

40

Code sample: Using the display functionif(Dialog.display("Do you wish to continue?", Dialog.YES_NO) == Dialog.YES_BUTTON) {

// continue }

Parameters

ReturnsThis function returns the result of your selection, indicating the specified button type.

Function: refreshThis function refreshes the current screen.

void refresh()

Code sample: Using the refresh functionScreen.refresh();

ReturnsThis function returns nothing.

Data functions

Function: allThis 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.


msg string to display

dialog_type either Dialog.OK or Dialog.YES_NO. The default is OK.

5: BlackBerry MDS Studio functions


41/52

41

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 componentsvar aAddress = Address.create();

ReturnsThis 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 functionvar aHorse = Horse.create({Name:"Tigrina",Age:7});

Parameters

ReturnsThis 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 functionvar aHorse = Horse.create("Tigrina");


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.



42/52

42

Parameters

ReturnsThis function returns the new or found keyed data instance.

Function: displayThis function displays the named screen using the specified arguments.

void display(Data:parm1, Data:parm2 )

Code sample: Using the display functionscrNextRegisterNewPlayer.display(playerDetails);

Parameters


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

Returns

This function returns the found instance or null if an instance is not found.


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.


parm data component objects passed to the screen for display; the number required is dependent upon the screen definition


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



43/52

43

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 functionvar aHorse = Horse.create("Tigrina");if(aHorse == null) {// Would never get hereDialog.display("Cannot happen");}

var someOtherHorse = Horse.find("Awesome American");if(someOtherHorse == null) {newHorse = Horse.create("Awesome American");}

Parameters

ReturnsThis function returns the found instance or null if an instance is not found.

Function: findWhereThis 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 valuevar selectedH = Horse.findWhere("rank ='" +

scrTrackInfo.chRaces.value[scrTrackInfo.chRaces.selected] + "'");

Parametersclause - "[fieldname operator value][ORDERBY fieldname_orderby ASC/DESC]"


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



44/52

44

One, or the other, or both parts can be provided.

ReturnsThis function returns an array. The array is empty if nothing is found.

Function: popThis 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 Tigrinavar newHorse1 = Horse.create("Tigrina");// Create second new horse Awesome Americanvar newHorse2 = Horse.create("Awesome American");// Horse collection is backed by MDS array, store that in myHorsesvar myHorses = Horse.all();// Remove the last index; Awesome AmericanmyHorses.pop();

Returns


Function: propertyThis 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

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)

(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



45/52

45

// is keyed by the race numbervar 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: pushThis 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// Get the number of horses in a race, Race component// is keyed by the race numbervar 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

Returns


Function: removeThis function removes the data instance.

void remove()

Code sample: Using the remove functionvar oldHorse = Horse.find("Tigrina");oldHorse.remove();



parm objects to be pushed into the array


F i


46/52

46

Function: removeThis 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

Returns


Function: removeAllThis 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 environmentHorse.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


Message functions

Function: containsThis function confirms whether or not this instance is contained.

boolean contains(Object:parm)


parm objects to be removed from the array


C d l Fi di th t i d i t f bj t


47/52

47

Code sample: Finding the contained instance of an object// Get the number of horses in a race, Race component// is keyed by the race number

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

ReturnsThis function returns true if contained, false is returned otherwise.

Function: sendThis function sends the named message.

outSubmitBet.send();


Organizer functions

Function: exitThis function exits the current running BlackBerry MDS Studio application.

System.exit();


Function: loadURLThis function loads the URL specified and brings the browser to the foreground.

System.loadURL("www.rim.com")


parm object to find


48/52


Dialog.display("The email is sent successfully.");


49/52

49

Dialog.display( The email is sent successfully. );}

ReturnsThis 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: startCallThis function makes a phone call using the specified telephone number.

System.startCall("4165554444");

Parameters



number telephone number to call



50/52

50


51/52


52/52

2008 Research In Motion Limited

Published in Canada.

blackberry mds studio javascript reference guide

Documents