Executes as soon as the scene is put online.

public sub OnOnline(Engine As xpEngine, Self As xpScene)

Executes before the scene is prepared to go online or to preview. A good place to fill in text and data.

public sub OnPrepare(Engine As xpEngine, Self As xpScene)

Executes before the scene is put online and before an existing item on the framebuffer is taken offline. Set AbortSetOnline = True to cancel taking it online.

public sub OnBeforeOnline(Engine As xpEngine, Self As xpScene, FramebufferIndex As Integer, Layer As Integer, ByRef AbortSetOnline As Boolean)

Executes just before the item is removed from a framebuffer. Handled lets the script take over the take-off.

public sub OnBeforeOffline(Engine As xpEngine, Self As xpScene, ByRef Handled As Boolean)

Executes after the item is removed from a framebuffer.

public sub OnOffline(Engine As xpEngine, Self As xpScene)

Executes for every frame rendered, including preview frames. Type says whether it is online, preview or NLE. Keep it very fast: it runs once per field/frame.

public sub OnRender(Engine As xpEngine, Self As xpScene, FieldNumber As Integer, Type As RenderType)

Executes each time the scene is rendered into preview.

public sub OnPreviewRender(Engine As xpEngine, Self As xpScene, FieldNumber As Integer)

Executes when the scene is being exported to video or images from the sequencer.

public sub OnExport(Engine As xpEngine, Self As xpScene)

Executes when this scene is online and another scene is put online on a different layer.

public sub OnSceneOnline(Engine As xpEngine, Self As xpScene, OnlineScene As xpScene)

Executes when this scene is online and another scene is removed from a different layer.

public sub OnSceneOffline(Engine As xpEngine, Self As xpScene, OfflineScene As xpScene)

Executes when the main scene director of the scene changes state (PlayState: stopped, paused, playing...).

public sub OnSceneDirectorState(Engine As xpEngine, Self As xpScene, State As PlayState)

CII command to load a project. FileName can be changed. Set Handled = True if the script loaded it itself.

public sub OnLoadProject(Engine As xpEngine, ByRef FileName As String, ByRef Handled As Boolean)

CII page write: creates or updates a take item (TakeItemID) from scene SceneID with the field Values(). All of these can be changed.

public sub OnPageWrite(Engine As xpEngine, ByRef SceneID As Integer, ByRef TakeItemID As Integer, ByRef Values() As String, ByRef Handled As Boolean)

CII page read/recall: brings take item TakeItemID to channel Channel.

public sub OnPageRead(Engine As xpEngine, ByRef TakeItemID As Integer, ByRef Channel As Integer, ByRef Handled As Boolean)

CII command to take take item TakeItemID offline.

public sub OnSetOffline(Engine As xpEngine, ByRef TakeItemID As Integer, ByRef Handled As Boolean)

CII command to clear channel Channel.

public sub OnClear(Engine As xpEngine, ByRef Channel As Integer, ByRef Handled As Boolean)

Runs when the mapped shortcut, GPI or P-Bus trigger is activated. Only Engine is passed: get scenes through it.

public sub OnKeyPress(Engine As xpEngine)

Runs when the text of the object is set (by a take item, Datalinq, the API...). Change Text to change what is displayed.

public sub OnSetText(Engine As xpEngine, Scene As xpScene, Self As xpTextObject, ByRef Text As String, ByRef Handled As Boolean)

Runs when text is appended to the object. Text is the text being added.

public sub OnAddText(Engine As xpEngine, Scene As xpScene, Self As xpTextObject, ByRef Text As String, ByRef Handled As Boolean)

Runs when a single line (LineIndex) of a multi-line text object is set.

public sub OnSetLine(Engine As xpEngine, Scene As xpScene, Self As xpTextObject, LineIndex As Integer, ByRef Text As String, ByRef Handled As Boolean)

Runs when the event marker is shown (reached) while the scene renders.

public sub OnShow(Engine As xpEngine, Scene As xpScene)

Runs when the event marker is hidden.

public sub OnHide(Engine As xpEngine, Scene As xpScene)

Runs when the Scene Director playhead reaches the script event.

public sub OnEvent(Engine As xpEngine, Scene As xpScene)

Transition Logic rule condition: set Result = True when the rule should apply for OtherScene.

public sub OnTransLogic(Engine As xpEngine, Scene As xpScene, OtherScene As xpScene, ByRef Result As Boolean)

' Runs every time the text is set
Text = UCase(Trim(Text))

If IsNumeric(Text) Then
    Text = Format(CDbl(Text), "#,##0.00")
End If

Dim obj As xpBaseObject = Nothing
If Self.GetObjectByName("Clock", obj) Then
    Dim txt As xpTextObject = CType(obj, xpTextObject)
    txt.Text = Format(Now, "HH:mm")
End If

Dim obj As xpBaseObject = Nothing
If Self.GetObjectByName("Name", obj) Then
    If Trim(CType(obj, xpTextObject).Text) = "" Then
        AbortSetOnline = True
        Engine.DebugMessage("Name is empty: " & Self.Name, MessageType.mt_Warning)
    End If
End If

' _Global (xpGlobal) is a dictionary shared by every script
Dim n As Integer = 0
If _Global.KeyExists("takes") Then n = CInt(_Global.Value("takes"))
n += 1
_Global.Value("takes") = n
Engine.WriteToLog("Scene " & Self.Name & " taken " & CStr(n) & " times")

Dim path As String = "C:\data\headline.txt"
If System.IO.File.Exists(path) Then
    Text = System.IO.File.ReadAllText(path, System.Text.Encoding.UTF8)
End If

Try
    Dim doc As New XmlDocument()
    doc.Load("C:\data\score.xml")
    Dim node As XmlNode = doc.SelectSingleNode("/score/home")
    If node IsNot Nothing Then Text = node.InnerText
Catch ex As Exception
    Engine.DebugMessage("XML error: " & ex.Message, MessageType.mt_Error)
End Try

Dim dir As xpSceneDirector = Nothing
If Self.GetSceneDirectorByName("Loop", dir) Then
    dir.Play()
End If

Dim sc As xpScene = Nothing
If Engine.GetSceneByName("Bug", sc) Then
    sc.SetOnline(0, 10)
Else
    Engine.DebugMessage("Scene 'Bug' not found", MessageType.mt_Error)
End If

Result = (OtherScene.Name = "Lower Third")

' OnRender runs every frame: do as little work as possible
If Type <> RenderType.rt_Online Then Exit Sub
Dim s As String = Format(Now, "HH:mm:ss")
If CStr(_Global.Value("lastClock")) <> s Then
    _Global.Value("lastClock") = s
    Dim obj As xpBaseObject = Nothing
    If Self.GetObjectByName("Clock", obj) Then CType(obj, xpTextObject).Text = s
End If

' Option Strict is Off, so late binding on Object works
Dim fso As Object = CreateObject("Scripting.FileSystemObject")
If fso.FolderExists("C:\data") Then
    Text = CStr(fso.GetFolder("C:\data").Files.Count) & " files"
End If

' Collapse repeated spaces and remove anything inside [brackets]
Text = System.Text.RegularExpressions.Regex.Replace(Text, "\[[^\]]*\]", "")
Text = System.Text.RegularExpressions.Regex.Replace(Text, "\s{2,}", " ").Trim()

Engine.WriteToLog("CII write: scene " & CStr(SceneID) & " item " & CStr(TakeItemID) & " fields " & CStr(UBound(Values) + 1))
For i As Integer = 0 To UBound(Values)
    Values(i) = Trim(Values(i))
Next
' Leave Handled = False so XPression still creates the take item

' Scripting > Global Methods: these become members of class xp.xpc
Public Shared Function IsLong(ByVal s As String) As Boolean
    Return Len(s) > 20
End Function

Public Shared Function LongNames(ByVal names As System.Collections.Generic.List(Of String)) As System.Collections.Generic.List(Of String)
    ' VB 8 has no lambdas: pass a named function with AddressOf
    Return names.FindAll(AddressOf IsLong)
End Function

Returns the character code (Integer) of the first character of a string or of a Char, using the current ANSI code page. Throws an ArgumentException for an empty string; use AscW for the Unicode code point.

Asc("A")  ' 65

Returns the Unicode code point (Integer) of the first character of a string or of a Char, independent of the system code page. Throws an ArgumentException for an empty string.

AscW("é")  ' 233

Returns the Char for a character code; codes 0-255 are interpreted using the current ANSI code page. Prefer ChrW for Unicode values or the constants vbCr, vbLf and vbCrLf for line breaks.

Chr(65)  ' "A"c

Returns the Char for a Unicode code point (-32768 to 65535), without depending on the system code page. Useful for symbols such as arrows, bullets or accented letters in text fields.

ChrW(8226)  ' "•"c (bullet)

Returns a zero-based String array with the elements of Source that contain the Match substring (or that do not contain it when Include is False). Compare selects binary (case-sensitive) or text (case-insensitive) matching.

Filter(New String() {"CAM1", "CAM2", "VT1"}, "CAM")  ' {"CAM1", "CAM2"}

Formats a number or date as a string using a named format ("Currency", "Percent", "Short Date", "Long Time"...) or a custom .NET/VB format string such as "0.00" or "dd/MM/yyyy HH:mm". The result follows the current regional settings (decimal and date separators), so the same code can render differently on machines with different cultures.

Format(Now, "HH:mm:ss")  ' e.g. "14:05:09"

Formats a numeric value as currency using the system's currency symbol and regional settings; NumDigitsAfterDecimal sets the decimals (-1 = regional default) and the TriState arguments control the leading zero, parentheses for negatives and digit grouping.

FormatCurrency(1234.5)  ' "R$ 1.234,50" (pt-BR) / "$1,234.50" (en-US)

Formats a Date using one of the DateFormat values: GeneralDate (default), LongDate, ShortDate, LongTime or ShortTime, according to the regional settings. Use Format for custom patterns.

FormatDateTime(Now, DateFormat.ShortTime)  ' e.g. "14:05"

Formats a numeric value with the given number of decimal places (-1 = regional default) and optional digit grouping, using the regional decimal and thousands separators. The value is rounded, not truncated.

FormatNumber(1234.567, 2)  ' "1,234.57" (en-US) / "1.234,57" (pt-BR)

Multiplies the value by 100 and formats it with a trailing % sign, using the given number of decimals (-1 = regional default). Pass the fraction (0.25), not the percentage (25).

FormatPercent(0.256, 1)  ' "25.6%"

Returns the Char at the 1-based position Index of the string. Throws an ArgumentException if Index is less than 1 or greater than the length.

GetChar("XPression", 2)  ' "P"c

Returns the 1-based position of the first occurrence of String2 inside String1, or 0 if it is not found; the optional Start argument (also 1-based) sets where the search begins. Note it is 1-based, unlike String.IndexOf, which is 0-based and returns -1.

InStr("XPression", "ss")  ' 5

Searches StringMatch from the end of StringCheck backwards and returns its 1-based position counted from the start, or 0 if not found. Start = -1 (default) begins at the last character.

InStrRev("C:\Clips\intro.mov", "\")  ' 9

Concatenates the elements of a one-dimensional array into a single string, separated by Delimiter (a single space by default). Pass "" as Delimiter to join with no separator.

Join(New String() {"A", "B", "C"}, ", ")  ' "A, B, C"

Returns the string or Char converted to lowercase using the current culture. Nothing is returned as an empty string.

LCase("XPression")  ' "xpression"

Returns the leftmost Length characters of a string; if Length exceeds the string length, the whole string is returned (no error). Inside a class that has its own Left property, call it as Microsoft.VisualBasic.Left.

Left("XPression", 2)  ' "XP"

For a String, returns the number of characters (0 for Nothing); for other types, returns the number of bytes needed to store the value (e.g. 4 for Integer, 8 for Double). For text, this is equivalent to the String.Length property but safe against Nothing.

Len("XPression")  ' 9

Returns Source left-aligned in a string of exactly Length characters, padded with trailing spaces or truncated if longer. Useful for fixed-width columns.

LSet("AB", 5) & "|"  ' "AB   |"

Returns the string with leading space characters removed. Only spaces are removed (not tabs or line breaks); use String.TrimStart() for other whitespace.

LTrim("   Hello")  ' "Hello"

Returns a substring starting at the 1-based position Start, with Length characters or up to the end if Length is omitted; returns "" if Start is beyond the end. Remember it is 1-based (String.Substring is 0-based).

Mid("XPression", 3, 5)  ' "ressi"

Returns a copy of Expression with occurrences of Find replaced by Replacement; Count limits the number of replacements (-1 = all) and Compare sets case sensitivity. Gotcha: when Start is greater than 1, the returned string begins at position Start (the characters before it are dropped).

Replace("1-2-3", "-", "/")  ' "1/2/3"

Returns the rightmost Length characters of a string; if Length exceeds the string length, the whole string is returned. Inside a class that has its own Right property, call it as Microsoft.VisualBasic.Right.

Right("Clip_0042", 4)  ' "0042"

Returns Source right-aligned in a string of exactly Length characters, padded with leading spaces or truncated if longer. Useful for aligning numbers in fixed-width text.

RSet("42", 5)  ' "   42"

Returns the string with trailing space characters removed. Only spaces are removed; use String.TrimEnd() for tabs or line breaks.

RTrim("Hello   ")  ' "Hello"

Returns a string consisting of the specified number of space characters. Handy for padding or aligning text.

"[" & Space(3) & "]"  ' "[   ]"

Splits Expression into a zero-based String array using Delimiter (a space by default; the whole delimiter string is used, not individual characters); Limit caps the number of elements (-1 = all). An empty input returns a one-element array containing "".

Split("Ana;Bia;Caio", ";")(1)  ' "Bia"

Compares two strings and returns -1 if String1 sorts before String2, 0 if they are equal, or 1 if it sorts after. Use CompareMethod.Text for a case-insensitive comparison.

StrComp("abc", "ABC", CompareMethod.Text)  ' 0

Converts a string as specified by a VbStrConv value, such as UpperCase, LowerCase, ProperCase (capitalizes each word), Wide/Narrow or Katakana/Hiragana. LocaleID optionally sets the culture used for the conversion.

StrConv("joão da silva", VbStrConv.ProperCase)  ' "João Da Silva"

Returns a string made of the first character of Character repeated Number times. Only the first character is used even if a longer string is passed.

StrDup(5, "-")  ' "-----"

Returns the string with its characters in reverse order. Returns "" for Nothing or an empty string.

StrReverse("ABC")  ' "CBA"

Returns the string with both leading and trailing spaces removed. Only spaces are removed; use String.Trim() to also strip tabs and line breaks (e.g. from data read from files).

Trim("  Score  ")  ' "Score"

Returns the string or Char converted to uppercase using the current culture. Nothing is returned as an empty string.

UCase("breaking news")  ' "BREAKING NEWS"

Returns the error message for a given VB run-time error number; without arguments, returns the message of the most recent error (Err.Number). Returns "" when the number is 0.

ErrorToString(11)  ' "Division by zero."

Removes the fractional part of a number, truncating toward zero, and returns the same numeric type. Differs from Int for negatives: Fix(-8.4) = -8, while Int(-8.4) = -9.

Fix(-8.4)  ' -8

Returns a string with the hexadecimal representation of an integer value (no "&H" prefix). Negative numbers are shown in two's complement, e.g. Hex(-1) = "FFFFFFFF".

Hex(255)  ' "FF"

Returns the integer part of a number, rounding down toward negative infinity (floor), keeping the same numeric type (a Double stays Double). Wrap it in CInt if you need an Integer.

Int(-8.4)  ' -9

Returns a string with the octal representation of an integer value (no "&O" prefix). Negative numbers are shown in two's complement.

Oct(8)  ' "10"

Converts a number to a string using the invariant culture (period as decimal separator). Gotcha: positive numbers get a leading space reserved for the sign, so use Trim(Str(x)), CStr or ToString when you do not want it.

Str(42)  ' " 42"

Parses the numbers at the start of a string and returns a Double, ignoring spaces and stopping at the first character it cannot interpret; it is culture-invariant (only "." is a decimal separator) and accepts &H/&O prefixes. Returns 0 if nothing numeric is found, never throwing for bad text.

Val("12.5 km")  ' 12.5

Returns a Date to which a number of intervals has been added (use a negative Number to subtract). The interval is a DateInterval value or a string: "yyyy" year, "q" quarter, "m" month, "ww" week, "d" day, "h" hour, "n" minute (not "m"!), "s" second.

DateAdd(DateInterval.Minute, 90, Now)  ' now + 1h30

Returns a Long with the number of interval boundaries between Date1 and Date2 (positive when Date2 is later). Interval uses the DateInterval enum or the same strings as DateAdd ("d", "h", "n", "s"...); note it counts boundaries crossed, so DateDiff("yyyy") between Dec 31 and Jan 1 is 1.

DateDiff(DateInterval.Second, startTime, Now)  ' elapsed seconds

Returns an Integer with the requested component of a Date (year, quarter, month, week of year, weekday, hour...), chosen by a DateInterval value or interval string. The optional arguments define the first day of the week and the first week of the year.

DatePart(DateInterval.Quarter, #8/15/2007#)  ' 3

Builds a Date (time 00:00:00) from year, month and day numbers. Out-of-range values roll over, so month 13 is January of the next year and day 0 is the last day of the previous month.

DateSerial(2024, 3, 0)  ' #2/29/2024#

Returns the current date as a string, always in "MM-dd-yyyy" format (month first) regardless of regional settings. Assigning to it changes the system date; use Format(Today, ...) for display.

DateString  ' e.g. "12-31-2024"

Converts a string to a Date containing only the date part (any time information is discarded). The string is parsed with the current regional settings, so "01/02/2024" may mean January 2 or February 1.

DateValue("2024-12-31")  ' #12/31/2024#

Returns the day of the month (1 to 31) of a Date as an Integer.

Day(#12/25/2024#)  ' 25

Returns the hour (0 to 23) of a Date as an Integer.

Hour(#2:30:00 PM#)  ' 14

Returns the minute (0 to 59) of a Date as an Integer.

Minute(#2:30:00 PM#)  ' 30

Returns the month (1 to 12) of a Date as an Integer.

Month(#12/25/2024#)  ' 12

Returns the name of a month (1 to 12) in the current culture's language, optionally abbreviated. On a pt-BR system the names come out in Portuguese ("janeiro").

MonthName(1, True)  ' "Jan" (en-US)

Returns a Date with the current system date and time (local time). Typical source for clocks and timestamps in graphics.

Format(Now, "HH:mm")  ' e.g. "14:05"

Returns the second (0 to 59) of a Date as an Integer.

Second(#2:30:15 PM#)  ' 15

Returns a Date containing the current time of day (date part January 1 of year 1). Assigning to it changes the system clock, which you should not do from a script.

Hour(TimeOfDay)  ' current hour

Returns a Double with the number of seconds (with fractions) elapsed since midnight. Useful for simple elapsed-time measurements, but it resets to 0 at midnight.

Dim elapsed As Double = Timer - t0  ' seconds since t0 = Timer

Builds a Date holding only a time of day from hour, minute and second numbers (the date part is January 1 of year 1). Out-of-range values roll over, e.g. 90 minutes becomes 1 h 30 min.

TimeSerial(14, 30, 0)  ' 2:30:00 PM

Returns the current time as a string, always in 24-hour "HH:mm:ss" format regardless of regional settings. Assigning to it changes the system clock.

TimeString  ' e.g. "14:05:09"

Converts a string to a Date containing only the time part (the date part is January 1 of year 1). Accepts formats such as "14:30" or "2:30 PM".

TimeValue("14:30:15")  ' 2:30:15 PM

Returns the current system date with the time set to 00:00:00. It is also a writable property that changes the system date, which you should never do from a script.

Format(Today, "dd/MM/yyyy")

Returns the day of the week as an Integer from 1 to 7, where 1 is the day given by DayOfWeek (Sunday by default). Pass FirstDayOfWeek.Monday to make Monday = 1.

Weekday(#12/25/2024#)  ' 4 (Wednesday)

Returns the name of a weekday (1 to 7) in the current culture's language, optionally abbreviated. The numbering depends on FirstDayOfWeekValue, which defaults to the system setting, so pass FirstDayOfWeek.Sunday for predictable results.

WeekdayName(Weekday(Today), False, FirstDayOfWeek.Sunday)  ' e.g. "Monday"

Returns the year (1 to 9999) of a Date as an Integer.

Year(Today)  ' e.g. 2024

Brings an already running application window to the foreground, identified by its window title or process ID (e.g. the value returned by Shell). Throws an ArgumentException if no matching window is found.

AppActivate("Untitled - Notepad")

Plays the default system beep through the computer's sound device. On a playout machine this may be audible on an audio output, so use it only while debugging.

Beep()

Gets or sets a property, or calls a method, on an object using its name as a string at run time; UseCallType is CallType.Get, Let, Set or Method, and Args holds the arguments. Useful when the member name comes from data, at the cost of speed and compile-time checking.

CallByName(obj, "Text", CallType.Let, "Hello")

Returns the element of the Choice list at the 1-based position Index (fractions are truncated), or Nothing if Index is out of range. All choices are evaluated, and the result is an Object that may need CStr/CInt.

CStr(Choose(2, "Red", "Green", "Blue"))  ' "Green"

Returns the command-line arguments of the current process as a single string (without the program name). Inside XPression this is the command line used to start XPression itself.

Dim args As String = Command()

Creates and returns a new instance of a COM (ActiveX) object by its ProgID, optionally on a remote server; the result is late-bound (Object), so member calls require Option Strict Off. The COM component must be registered on the XPression machine.

Dim fso As Object = CreateObject("Scripting.FileSystemObject")

Deletes a section or a key from the application's settings in the Windows registry (HKEY_CURRENT_USER\Software\VB and VBA Program Settings\AppName). Omitting Key deletes the whole section, and omitting Section deletes all settings for AppName.

DeleteSetting("MyXPScripts", "Scores", "Home")

Returns the value of an operating-system environment variable by name, or "" if it does not exist; with a numeric index (1-based), returns the "NAME=value" string of that entry.

Environ("COMPUTERNAME")  ' e.g. "XPN-PLAYOUT1"

Returns all keys and values of a registry section saved with SaveSetting as a two-dimensional String array, where (i, 0) is the key and (i, 1) the value. Returns Nothing if the section does not exist.

Dim s(,) As String = GetAllSettings("MyXPScripts", "Scores")

Returns a reference to a COM object, either loaded from a file (PathName) or an already running instance of the given Class. Like CreateObject, the result is late-bound.

Dim xl As Object = GetObject(, "Excel.Application")

Reads a value saved with SaveSetting from the registry for the current Windows user, returning Default ("" if omitted) when the key does not exist. Handy for persisting small values between XPression sessions.

GetSetting("MyXPScripts", "Scores", "Home", "0")

Returns TruePart if Expression is True, otherwise FalsePart, as an Object. Gotcha: both parts are always evaluated (no short-circuit), so IIf(x Is Nothing, "", x.Name) still fails when x is Nothing; use an If...Else block in that case (the If() operator does not exist in VB 8).

CStr(IIf(score >= 10, "WIN", "LOSE"))

Shows a modal dialog asking the user to type text and returns it (or "" if the user cancels); Title, DefaultResponse and position are optional. It blocks the XPression render thread until closed, so never use it in scripts that run on air.

Dim name As String = InputBox("Guest name:", "Lower third", "John Doe")

Shows a modal message box and returns a MsgBoxResult indicating which button was clicked; Buttons combines MsgBoxStyle flags (buttons, icon, default button) and Title sets the caption. It blocks the XPression render thread until dismissed, so use it only for testing, never on air.

If MsgBox("Clear all?", MsgBoxStyle.YesNo, "Confirm") = MsgBoxResult.Yes Then Reset()

Returns a string "lower:upper" describing which range of size Interval, between Start and Stop, contains Number; values are padded with leading spaces to the width of Stop plus one. Mostly used to build frequency tables or histograms.

Partition(25, 0, 99, 10)  ' " 20: 29"

Saves a string value in the Windows registry under HKEY_CURRENT_USER\Software\VB and VBA Program Settings\AppName\Section\Key. The value is per Windows user, so it is not shared between machines or accounts.

SaveSetting("MyXPScripts", "Scores", "Home", "3")

Starts an external program and returns its process ID; Style sets the window style and Wait = True blocks until the program exits (or Timeout ms elapse). Inside XPression, avoid Wait = True and long-running programs, since the script blocks the render thread.

Shell("notepad.exe C:\temp\log.txt", AppWinStyle.NormalFocus)

Takes pairs of (condition, value) and returns the value of the first pair whose condition is True, or Nothing if none is. All arguments are evaluated, and the result is an Object.

CStr(Switch(x < 0, "neg", x = 0, "zero", True, "pos"))

Returns the line number where the last error occurred, which only works when the code uses numbered lines; otherwise it returns 0.

Dim line As Integer = Erl()

Returns the ErrObject with information about the most recent run-time error (Number, Description, Source...). It is filled by On Error handling and also when an exception is caught in a Try...Catch block.

If Err.Number <> 0 Then Engine.WriteToLog(Err.Description)

Returns True if the variable refers to an array. Returns False for Nothing and for strings.

IsArray(New Integer() {1, 2})  ' True

Returns True if the expression is a Date or a string that can be converted to a Date using the current regional settings. Use it before CDate to avoid conversion exceptions.

IsDate("31/12/2024")  ' True on pt-BR, False on en-US

Returns True if the expression is DBNull.Value, the value that represents a database NULL (e.g. from a DataRow or DataReader). Check it before converting database fields.

If IsDBNull(row("Score")) Then score = 0

Returns True if the expression is an Exception object. Kept mainly for compatibility with VB6 code that used error values.

IsError(New Exception("x"))  ' True

Returns True if the expression is Nothing (has no object assigned). Equivalent to the test x Is Nothing.

If IsNothing(scene) Then Exit Sub

Returns True if the expression is a number or a string that can be converted to a number (using the current regional settings, and also accepting &H/&O prefixes). Use it to validate text before calling CDbl or CInt.

IsNumeric("12abc")  ' False

Returns True if the expression holds a reference type (String, arrays, class instances) and False for value types such as Integer, Date or structures.

IsReference("abc")  ' True

Returns the lowest available index of the given dimension (Rank, 1-based) of an array. In VB.NET arrays always start at 0, so it is normally 0.

LBound(arr)  ' 0

Returns the RGB color value (Integer, &H00BBGGRR) of one of the 16 classic QuickBASIC colors (0 to 15). The value uses the COM/OLE byte order, not System.Drawing.Color's ARGB; convert with ColorTranslator.FromOle if needed.

QBColor(12)  ' &HFF (light red)

Returns an Integer color value built from red, green and blue components (0 to 255), in the COM/OLE order &H00BBGGRR (red in the low byte). It is not the same as Color.FromArgb(...).ToArgb(); use ColorTranslator.FromOle to get a System.Drawing.Color.

RGB(255, 0, 0)  ' 255

Converts a VB type name to the corresponding .NET (CLR) type name, or returns Nothing if the name is not a VB elementary type.

SystemTypeName("Integer")  ' "System.Int32"

Returns a string with the VB name of the variable's data type, such as "Integer", "String", "Double", "Integer()" for arrays or "Nothing". Useful for debugging late-bound objects.

TypeName(42)  ' "Integer"

Returns the highest index of the given dimension (Rank, 1-based) of an array; for Dim a(5) it returns 5 (six elements). Returns -1 for an empty array and throws for Nothing.

UBound(New String() {"A", "B", "C"})  ' 2

Returns a VariantType value identifying the data type of the variable (e.g. VariantType.Integer, VariantType.String, VariantType.Date). Arrays combine VariantType.Array with the element type.

VarType(3.5) = VariantType.Double  ' True

Converts a .NET (CLR) type name to the corresponding VB type name, or returns Nothing if there is no VB equivalent. Accepts names with or without the "System." prefix.

VbTypeName("System.Int32")  ' "Integer"

Changes the current working directory. This affects the whole XPression process (and relative paths everywhere), so prefer working with absolute paths instead.

ChDir("D:\Graphics")

Changes the current drive, using the first letter of the given string or Char. Like ChDir, it changes process-wide state.

ChDrive("D")

Returns the current working directory path, or the current directory of the given drive letter.

CurDir()  ' e.g. "C:\Program Files\XPression"

Returns the first file or folder name matching a path pattern (wildcards * and ?) and Attributes; calling Dir() again with no arguments returns the next match, and "" when there are no more. Returns only the name (not the full path), and the shared search state is not thread-safe.

Dim f As String = Dir("D:\Logos\*.png")

Returns True when the end of a file opened for Input, Random or Binary has been reached. Use it as the loop condition when reading files.

If EOF(fn) Then FileClose(fn)

Returns the OpenMode (Input, Output, Append, Binary or Random) with which a file number was opened by FileOpen.

FileAttr(fn) = OpenMode.Append  ' True

Closes the files opened with FileOpen for the given file numbers; with no arguments, closes all of them. Unclosed files stay locked by the XPression process.

FileClose(fn)

Copies a file from Source to Destination, overwriting the destination if it exists. Fails if the source file is open for writing.

FileCopy("D:\data.xml", "D:\backup\data.xml")

Returns the date and time when the file was created or last modified. Useful to detect whether a data file has changed since the last read.

FileDateTime("D:\scores.txt")

Reads data from a file opened in Random or Binary mode into the given variable (passed ByRef), at RecordNumber (1-based record in Random mode, byte position in Binary mode) or at the current position. Counterpart of FilePut.

Dim n As Integer : FileGet(fn, n, 1)

Reads a value from a file opened in Random or Binary mode into an Object variable, at RecordNumber (1-based) or the current position. Use it instead of FileGet when the variable is declared As Object.

FileGetObject(fn, value, 1)

Returns the size of a file in bytes as a Long. For a file currently open with FileOpen, use LOF to get the up-to-date size.

FileLen("D:\scores.txt")  ' e.g. 1024

Opens a file for VB-style I/O, associating it with a file number (get one from FreeFile); Mode is OpenMode.Input, Output, Append, Binary or Random, and Access, Share and RecordLength are optional. Always close it with FileClose, preferably in a Finally block.

Dim fn As Integer = FreeFile() : FileOpen(fn, "D:\log.txt", OpenMode.Append)

Writes the value of a variable to a file opened in Random or Binary mode, at RecordNumber (1-based) or the current position. Data is written in binary form, to be read back with FileGet.

FilePut(fn, 42, 1)

Writes an Object value to a file opened in Random or Binary mode, at RecordNumber or the current position. Counterpart of FileGetObject.

FilePutObject(fn, CObj(42), 1)

Sets the maximum line width for output to a file opened with FileOpen; Print/Write wrap to a new line when it is reached. A width of 0 means unlimited.

FileWidth(fn, 80)

Returns the next available file number for use with FileOpen. Always use it instead of hard-coding numbers, since other scripts may have files open.

Dim fn As Integer = FreeFile()

Returns the FileAttribute flags of a file or folder (ReadOnly, Hidden, System, Directory, Archive...). Test a flag with And, e.g. (GetAttr(p) And FileAttribute.Directory) <> 0.

(GetAttr("D:\Logos") And FileAttribute.Directory) <> 0  ' True

Reads one comma-delimited value from a file opened in Input mode into the given variable (ByRef). Intended for data written with Write/WriteLine, which quote strings and delimit fields.

Dim s As String : Input(fn, s)

Reads CharCount characters from a file opened in Input or Binary mode and returns them as a string, including commas, quotes and line breaks.

Dim all As String = InputString(fn, CInt(LOF(fn)))

Deletes one or more files from disk; wildcards (* and ?) are accepted, so double-check the pattern. Deleted files do not go to the Recycle Bin.

Kill("D:\Temp\*.tmp")

Reads a whole line from a file opened in Input mode and returns it without the trailing line break. Combine with EOF in a loop to read text files line by line.

Dim s As String = ""
Do Until EOF(fn)
    s = LineInput(fn)
Loop

Returns the current position in an open file: last record read/written for Random, last byte for Binary, and the byte position divided by 128 for sequential files.

Loc(fn)

Prevents other processes from accessing all of an open file, a single record, or a range of records (Random) / bytes (Binary). Every Lock must be matched by an Unlock with the same arguments.

Lock(fn, 1, 10)

Returns the size, in bytes, of a file opened with FileOpen. Reflects data already written in the current session, unlike FileLen.

LOF(fn)  ' e.g. 2048

Creates a new directory. Throws an IOException if the directory already exists.

MkDir("D:\Export\Today")

Writes display-formatted values to a file opened for Output or Append, without adding a line break. Use TAB and SPC to position output.

Print(fn, "Score: ", 10)

Writes display-formatted values to a file opened for Output or Append, followed by a line break. The simplest way to write a text log line.

PrintLine(fn, Format(Now, "HH:mm:ss") & " take OK")

Renames a file or directory; if the new path is in another folder on the same drive, the file is moved. Throws if NewPath already exists.

Rename("D:\data.txt", "D:\data_old.txt")

Closes all files opened with FileOpen and flushes their buffers. Equivalent to calling FileClose with no arguments.

Reset()

Removes an existing directory, which must be empty. Delete the files first with Kill.

RmDir("D:\Export\Old")

Without Position, returns the current read/write position of an open file; with Position, sets it. Positions are 1-based: byte position in Binary/sequential modes, record number in Random mode.

Seek(fn, 1)  ' rewind

Sets the FileAttribute flags of a file, such as ReadOnly or Hidden; combine flags with Or. Use FileAttribute.Normal to clear them.

SetAttr("D:\data.xml", FileAttribute.ReadOnly)

Used inside Print/PrintLine to insert Count spaces in the output. Handy for simple text alignment.

PrintLine(fn, "A", SPC(5), "B")

Used inside Print/PrintLine to move the output to a given column (1-based); with no argument, moves to the next print zone (every 14 columns).

PrintLine(fn, "Name", TAB(20), "Score")

Releases a lock previously applied with Lock on a whole file, a record, or a range of records. Arguments must match the original Lock call.

Unlock(fn, 1, 10)

Writes values to a sequential file as comma-separated fields, with strings in quotes and dates as #yyyy-MM-dd#, without a line break. The output is meant to be read back with Input.

Write(fn, "Home", 3)

Like Write, writes comma-separated, quoted values to a sequential file, but ends with a line break. Produces simple CSV-like records readable with Input.

WriteLine(fn, "Home", 3)  ' "Home",3

Returns the depreciation of an asset for a given period using the double-declining balance method (or another rate via Factor). Cost, Salvage, Life and Period must use consistent units.

DDB(10000, 1000, 5, 1)  ' 4000

Returns the future value of an investment with constant periodic payments and a constant interest Rate per period. Money paid out is negative and money received is positive; Due sets payments at the end or beginning of each period.

FV(0.01, 12, -100)  ' ≈ 1268.25

Returns the interest portion of the payment for period Per of a loan or annuity with constant payments and rate. Uses the same sign convention as Pmt.

IPmt(0.01, 1, 12, 1000)  ' -10

Returns the internal rate of return for a series of periodic cash flows in a Double array, which must contain at least one negative (payment) and one positive (receipt) value. Guess is the starting estimate for the iterative calculation.

Dim cf() As Double = {-1000, 300, 400, 500} : IRR(cf)  ' ≈ 0.089

Returns the modified internal rate of return of a series of cash flows, using FinanceRate for the cost of payments and ReinvestRate for reinvested receipts. The array needs both negative and positive values.

MIRR(cf, 0.1, 0.12)

Returns the number of periods needed for an investment or loan with constant payments Pmt and rate Rate to reach the given future value. Uses the usual sign convention (payments negative).

NPer(0.01, -100, 1000)  ' ≈ 10.59

Returns the net present value of a series of future cash flows (Double array) discounted at Rate. The first value is discounted one full period, so add an initial investment separately.

Dim f() As Double = {300, 400, 500} : NPV(0.1, f)  ' ≈ 978.96

Returns the constant payment per period for a loan or annuity, given the rate per period, number of periods and present value. The result is negative for money paid; divide an annual rate by 12 for monthly payments.

Pmt(0.01, 12, 1000)  ' ≈ -88.85

Returns the principal portion of the payment for period Per of a loan or annuity with constant payments and rate. IPmt + PPmt equals Pmt for each period.

PPmt(0.01, 1, 12, 1000)  ' ≈ -78.85

Returns the present value of a series of constant future payments at a constant rate per period. Uses the usual sign convention (payments negative).

PV(0.01, 12, -100)  ' ≈ 1125.51

Returns the interest rate per period of an annuity, calculated iteratively from the number of periods, payment and present value. Throws if the calculation does not converge; try a different Guess.

Rate(12, -88.85, 1000)  ' ≈ 0.01

Returns the straight-line depreciation of an asset for one period: (Cost - Salvage) / Life.

SLN(10000, 1000, 5)  ' 1800

Returns the sum-of-years'-digits depreciation of an asset for the given Period. Depreciation is higher in the first periods.

SYD(10000, 1000, 5, 1)  ' 3000

Initializes the random-number generator used by Rnd, seeding it from the system timer or from the given Number. Call it once (e.g. at script start), not before every Rnd call.

Randomize()

Returns a random Single greater than or equal to 0 and less than 1. Call Randomize once first, or the same sequence repeats every time the script engine starts; a negative argument returns the same number for the same seed and 0 repeats the last number.

CInt(Int(Rnd() * 10)) + 1  ' 1 to 10

Returns the name of the scripting language in use, which is always "VB" for Visual Basic .NET.

ScriptEngine()  ' "VB"

Returns the build number of the Visual Basic runtime. Mainly useful for diagnostics.

ScriptEngineBuildVersion()

Returns the major version number of the Visual Basic runtime (8 for Visual Basic 2005).

ScriptEngineMajorVersion()  ' 8

Returns the minor version number of the Visual Basic runtime.

ScriptEngineMinorVersion()  ' e.g. 0

Adds an item to the Collection, optionally with a unique string Key (case-insensitive) and a position given by Before or After (index or key). Adding a duplicate key throws an ArgumentException.

col.Add("Ana Souza", "guest1")

Removes all items from the Collection, leaving Count at 0.

col.Clear()

Returns True if the Collection has an item with the given key. Use it before Item(key) to avoid an exception for missing keys.

If col.Contains("guest1") Then col.Remove("guest1")

Returns the number of items in the Collection. Valid indexes go from 1 to Count.

Dim last As Object = col(col.Count)

Returns an enumerator over the items of the Collection; it is what makes For Each work. You rarely call it directly.

For Each o As Object In col : Engine.WriteToLog(CStr(o)) : Next

Default property that returns an item by 1-based index or by string key (col(1) or col("key")). Note that a Collection starts at 1, unlike arrays and List(Of T), and an Integer argument is always treated as an index.

CStr(col("guest1"))  ' "Ana Souza"

Removes an item from the Collection by key or by 1-based index. Throws if the key or index does not exist.

col.Remove("guest1")

Resets all properties of the Err object (Number = 0, Description = ""...). It is called automatically by Resume, Exit Sub/Function and On Error statements.

Err.Clear()

Gets or sets the descriptive text of the current error. This is the message you usually log or display.

Engine.WriteToLog(Err.Description)

Returns the line number where the error occurred, only when the code uses numbered lines; otherwise 0.

Err.Erl

Returns the Exception object that corresponds to the current error in Err. Useful to access the .NET details (type, stack trace, InnerException).

Dim ex As Exception = Err.GetException()

Gets or sets the context ID of a topic in the help file associated with the error. Rarely used in scripts.

Err.HelpContext

Gets or sets the full path of a help file associated with the error. Rarely used in scripts.

Err.HelpFile

Returns the system error code from the last call to an unmanaged DLL function made through a Declare statement. Only meaningful right after such a call.

Err.LastDllError

Gets or sets the numeric code of the current error; 0 means no error. Commonly checked after On Error Resume Next.

If Err.Number <> 0 Then Engine.WriteToLog(Err.Description)

Generates a run-time error with the given Number and optional Source, Description and help information. For your own errors, add a value to vbObjectError so it does not clash with system error numbers.

Err.Raise(vbObjectError + 1, "MyScript", "Data file not found")

Gets or sets the name of the object or application that generated the error. Helpful to identify which script or component failed.

Err.Source