Built-In Functions

 

BrightScript features a set of built-in, module-scope, intrinsic functions. A number of file I/O, string, mathematics, and system functions are also available via the roGlobal object.

Type()

Type(a As Variable) As String 

This function returns the type of the passed variable and/or object.

GetGlobalAA()

GetGlobalAA() As Object

This function fetches the global associative array for the current script.

Rnd()

Rnd(range As Integer) As Integer
Rnd(0) As Float

If passed a positive, non-zero integer, this function returns a pseudo-random integer between 1 and the argument value. The range includes the argument value: For example, calling Rnd(55) will return a pseudo-random integer greater than 0 and less than 56.

If the argument is 0, this function returns a pseudo-random Float value between 0 and 1.

Note

The Rnd() functions utilize a pseudo-random seed number that is generated internally and not accessible to the user.

Box()

Box(type As Dynamic) As Object

This function returns an object version of the specified intrinsic type. Objects will be passed through.

Example
b = box("string") b = box(b) ' b does not change

Run()

Run(file_name As String, [optional_arg As Dynamic, …]) As Dynamic
Run(file_names As roArray, [optional_arg As Dynamic, …]) As Dynamic

This function runs one or more scripts from the current script. You may append optional arguments, which will be passed to the Main() function of the script(s). The called script may also return arguments to the caller script.

If a string file name is passed, the function will compile and run the corresponding file. If an array of files is passed, the function will compile each file, link them together, and run them.

Example
Sub Main() Run("test.brs") BreakIfRunError(LINE_NUM) Print Run("test2.brs", "arg 1", "arg 2") if Run(["file1.brs","file2.brs"])<>4 then stop BreakIfRunError(LINE_NUM) stop End Sub Sub BreakIfRunError(ln) el=GetLastRunCompileError() if el=invalid then el=GetLastRunRuntimeError() if el=&hFC or el=&hE2 then return 'FC==ERR_NORMAL_END, E2=ERR_VALUE_RETURN print "Runtime Error (line ";ln;"): ";el stop else print "compile error (line ";ln;")" for each e in el for each i in e print i;": ";e[i] end for end for stop end if End Sub

Eval()

Eval(code_snippet As String) As Dynamic

This function runs the passed code snippet in the context of the current function. The function compiles the snippet, then executes the byte-code. If the code compiles and runs successfully, it will return zero. If the code compiles successfully, but encounters a runtime error, it will return an integer indicating the error code (using the same codes as the GetLastRunRuntimeError() function). If compilation fails, it will return an roList object; the roList structure is identical to that of the GetLastRunCompileError() function.

The Eval() function can be useful in two cases:

  • When you need to dynamically generate code at runtime.

  • When you need to execute a statement that could result in a runtime error, but you don’t want code execution to stop.

Example
PRINT Eval("1/0") 'Returns a divide by zero error.

GetLastRunCompileError()

GetLastRunCompileError() As roList

This function returns an roList object containing compile errors (or Invalid if no errors occurred). Each roList entry is an roAssociativeArray object containing the following keys:

  • ERRSTR: The compile error type (as String)

  • FILESPEC: The file URI of the script containing the error (as String)

  • ERRNO: The error number (as Integer)

  • LINENO: The line number where the error occurs (as Integer)

The following are possible ERRNO values:

Error Code

Description

Expanded Description

&hBF

191

ERR_NW

ENDWHILE statement occurs without statement.

&hBE

190

ERR_MISSING_ENDWHILE

WHILE statement occurs without ENDWHILE statement.

&hBC

188

ERR_MISSING_ENDIF

End of script reached without finding an ENDIF statement.

&hBB

187

ERR_NOLN

No line number found.

&hBA

186

ERR_LNSEQ

Line number sequence error.

&hB9

185

ERR_LOADFILE

Error loading file.

&hB8

184

ERR_NOMATCH

MATCH statement does not match.

&hB7

183

ERR_UNEXPECTED_EOF

Unexpected end of string encountered during string compilation.

&hB6

182

ERR_FOR_NEXT_MISMATCH

Variable on NEXT does not match FOR.

&hB5

181

ERR_NO_BLOCK_END



&hB4

180

ERR_LABELTWICE

Label defined more than once.

&hB3

179

ERR_UNTERMED_STRING

Literal string does not have end quote.

&hB2

178

ERR_FUN_NOT_EXPECTED



&hB1

177

ERR_TOO_MANY_CONST



&hB0

176

ERR_TOO_MANY_VAR



&hAF

175

ERR_EXIT_WHILE_NOT_IN_WHILE



&hAE

174

ERR_INTERNAL_LIMIT_EXCEDED



&hAD

173

ERR_SUB_DEFINED_TWICE



&hAC

172

ERR_NOMAIN



&hAB

171

ERR_FOREACH_INDEX_TM



&hAA

170

ERR_RET_CANNOT_HAVE_VALUE



&hA9

169

ERR_RET_MUST_HAVE_VALUE



&hA8

168

ERR_FUN_MUST_HAVE_RET_TYPE



&hA7

167

ERR_INVALID_TYPE



&hA6

166

ERR_NOLONGER

Feature no longer supported.

&hA5

165

ERR_EXIT_FOR_NOT_IN_FOR



&hA4

164

ERR_MISSING_INITILIZER



&hA3

163

ERR_IF_TOO_LARGE



&hA2

162

ERR_RO_NOT_FOUND



&hA1

161

ERR_TOO_MANY_LABELS



&hA0

160

ERR_VAR_CANNOT_BE_SUBNAME



&h9F

159

ERR_INVALID_CONST_NAME



&h9E

158

ERR_CONST_FOLDING  



GetLastRunRuntimeError()

GetLastRunRuntimeError() As Integer

This function returns the error code that resulted from the last Run() function.

These codes indicate a normal result:

Error Code

Description

Expanded Description

&hFF

255

ERR_OKAY



&hFC

252

ERR_NORMAL_END

Execution ended normally, but with termination (e.g. END, shell "exit", window closed).

&hE2

226

ERR_VALUE_RETURN

Return executed with value returned on the stack.

&hE0

224

ERR_NO_VALUE_RETURN

Return executed without value returned on the stack.

 

The following codes indicate runtime errors:

Error Code

Description

Expanded Description

&hFE

254

ERR_INTERNAL

Unexpected condition occurred.

&hFD

253

ERR_UNDEFINED_OPCD

Opcode could not be handled.

&hFB

251

ERR_UNDEFINED_OP

Expression operator could not be handled.

&hFA

250

ERR_MISSING_PARN



&hF9

249

ERR_STACK_UNDER

No value to pop off the stack.

&hF8

248

ERR_BREAK

scriptBreak() function called.

&hF7

247

ERR_STOP

STOP statement executed.

&hF6

246

ERR_RO0

bscNewComponent failed because object class not found.

&hF5

245

ERR_R01

BrightScript member function call does not have right number of parameters.

&hF4

244

ERR_RO2

BrightScript member function not found in object or interface.

&hF3

243

ERR_RO3

BrightScript interface not a member of the object.

&hF2

242

ERR_TOO_MANY_PARAM

Too many function parameters to handle.

&hF1

241

ERR_WRONG_NUM_PARAM

Number of function parameters incorrect.

&hF0

240

ERR_RVIG

Function returns a value, but is ignored.

&hEF

239

ERR_NOTPRINTABLE

Value not printable.

&hEE

238

ERR_NOTWAITABLE

WAIT statement cannot be applied to object because object does not have an roMessagePort interface.

&hED

237

ERR_MUST_BE_STATIC

Interface calls from rotINTERFACE type must be static.

&hEC

236

ERR_RO4

"." Dot Operator used on object that does not contain legal object or interface reference.

&hEB

235

ERR_NOTYPEOP

Operation attempted on two type-less operands.

&hE9

233

ERR_USE_OF_UNINIT_VAR

Uninitialized variable used illegally.

&hE8

232

ERR_TM2

Non-numeric index applied to array.

&hE7

231

ERR_ARRAYNOTDIMMED



&hE6

230

ERR_USE_OF_UNINIT_BRSUBREF

Reference to uninitialized SUB.

&hE5

229

ERR_MUST_HAVE_RETURN



&hE4

228

ERR_INVALID_LVALUE

Left side of the expression is invalid.

&hE3

227

ERR_INVALID_NUM_ARRAY_IDX

Number of array indexes is invalid.

&hE1

225

ERR_UNICODE_NOT_SUPPORTED



&hE0

224

ERR_NOTFUNOPABLE



&hDF

223

ERR_STACK_OVERFLOW



&h20

32

ERR_CN

Continue (cont or c) not allowed.

&h1C

28

ERR_STRINGTOLONG



&h1A

26

ERR_OS

String space has run out.

&h18

24

ERR_TM

A Type Mismatch (string /number operation mismatch) has occurred.

&h14

20

ERR_DIV_ZERO



&h12

18

ERR_DD

Attempted to re-dimension array.

&h10

16

ERR_BS

Array subscript out of bounds.

&h0E

14

ERR_MISSING_LN



&h0C

12

ERR_OUTOFMEM



&h08

8

ERR_FC

Invalid parameter passed to function/array (e.g. a negative matrix dim or square root).

&h06

6

ERR_OD

Out of data (READ).

&h04

4

ERR_RG

Return without Gosub.

&h02

2

ERR_SYNTAX



&h00

0

ERR_NF

Next without For.