6.1-Built-In Functions

ON THIS PAGE

Firmware Version 6.1

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 IntegerRnd(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 DynamicRun(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`.