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 |
|
&hBE | 190 | ERR_MISSING_ENDWHILE |
|
&hBC | 188 | ERR_MISSING_ENDIF | End of script reached without finding an |
&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 |
|
&hB7 | 183 | ERR_UNEXPECTED_EOF | Unexpected end of string encountered during string compilation. |
&hB6 | 182 | ERR_FOR_NEXT_MISMATCH | Variable on |
&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 |
|
&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 |
|
&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 ( |
&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 |
|