Back to Basic (BTB) Script User Manual

Welcome to the Back to Basic (BTB) scripting language manual. BTB is a loosely typed scripting engine built for fast automation, lightweight application development, UI creation, and system integration. Its syntax is inspired by BASIC, making it approachable for beginners while still being practical for experienced developers building internal tools and workflow automation.

BTB is best suited for:

• Task and file automation
• Desktop workflows that need mouse or keyboard simulation
• Simple internal applications
• Scripts with built-in dialogs or wizard interfaces
• Deployments that benefit from a small runtime footprint

BTB is less suited for large-scale, highly sophisticated application development where a broader framework or full software stack is a better fit.

---

1. Language Fundamentals

Core Rules

• Case Insensitivity: Commands, functions, and variables are not case-sensitive (PRINT is the same as print).
• No Declaration Needed: Variables do not need to be declared before use.
• Loose Typing: Variables can change types dynamically (e.g., a variable holding a string can later hold a number).
• File Extension: BTB script files use the .bbs extension (e.g., myscript.bbs).
• Execution Flow: The main script starts at the beginning of the file and ends when it hits END or the first SUB/FUNC definition.

Commenting

Comments can be written on their own line or at the end of a code line.

' This is a standalone comment
GLOBAL x = 10
FOR x = 1 TO 10 ' This is a valid inline comment
  PRINT x ' You can also comment after statements inside blocks
NEXT

Variable Naming

• Must start with an alphabet character.
• Can be followed by numbers or more letters.
• Supports arrays using square brackets: array[1] = "value".

---

2. Program Structure

Including Libraries

Include external .bbs files at the very beginning of your script to share functions and global variables.

INCLUDE "..\Library\FileUtils.bbs"
INCLUDE "utils.bbs"

Global Variables

Variables are local to their scope unless declared as GLOBAL.

GLOBAL gTotal = 0
GLOBAL gStartTime = NOW()

Functions and Subroutines

Functions return values via the reserved RESULT variable. Subroutines (SUB) do not return values. To use the FUNC or SUB, simply include the name followed by parentheses, regardless of parameter requirements.

Greet()
PRINT AddNumber(45, 345)

' Function Example
FUNC AddNumbers(a, b)
  RESULT = a + b
ENDFUNC

' Subroutine Example
SUB Greet()
  PRINT "Hello, World!"
ENDSUB

Parameter Passing

• Pass-by-Value (Default): A copy of the argument is passed.
• Pass-by-Reference: Prefix the argument with & to allow the subroutine to modify the original variable.

MySub(&lName, lAge)

SUB MySub(mName, mAge)
  mName = "John"   ' Updates lName in the caller's scope
  mAge = 30        ' Does NOT update lAge
ENDSUB

Optional Parameters

Parameters can be optional by specifying a default value next to the parameter.

' Output: Suri NA
PRINT MyFunc("Suri")

FUNC MyFunc(mName, mLastName="")
  IF mLastName <> "" THEN
    RESULT = mName + " " + mLastName
  ELSE
    RESULT = mName + " NA"
  ENDIF
ENDFUNC

---

3. Control Flow

Conditionals

BTB supports IF...THEN...ELSE and CASEOF blocks.

Important: BTB script does not support grouped conditions. Do not wrap full conditions or condition groups in parentheses.

' IF Statement
IF x > 10 AND y < 3 THEN
  PRINT "Condition met"
ELSE
  PRINT "Condition not met"
ENDIF

' CASE Statement
CASEOF
  CASE x = 1
    PRINT "One"
  CASE x = 2
    PRINT "Two"
  OTHERWISE
    PRINT "Other"
ENDCASE

This is not valid BTB syntax:

IF ((x + 10) - 5 > 6) OR (y = 40 AND z > 20) THEN
ENDIF

Write the condition without grouped boolean clauses:

IF x + 10 - 5 > 6 OR y = 40 AND z > 20 THEN
ENDIF

Loops

' FOR Loop
FOR i = 1 TO 10
  IF i = 5 THEN 
    EXITFOR
  ENDIF
ENDFOR

' WHILE Loop (Common for service monitoring)
WHILE 1=1
  ' Perform check
  PAUSE 5 ' Wait 5 seconds
ENDWHILE

---

4. Strings and Templates

String Literals

Use double quotes. To include a double quote inside a string, use two double quotes.

s = "He said, ""Hello!""" ' Result: He said, "Hello!"

Multi-line String Blocks

Use STRING...ENDSTRING or TEXT...ENDTEXT. These blocks support Variable Templates using |variable|.

name = "John"
STRING myEmail
  Hello, |name|
  How are you today?
ENDSTRING

---

5. User Interface Blocks

BTB allows you to define complex UI directly in your script using DIALOG or WIZARD blocks.

Dialogs

A standard popup window with various controls. BTB provides a visual editor to generate these blocks. See the dedicated Dialog Guide for layout properties and control references.

To open the built-in Dialog Editor, place the cursor on the DIALOG keyword, right-click, and choose Dialog Editor. The editor highlights the full DIALOG...ENDDIALOG block, opens the visual designer, and writes the updated dialog code back into that block when you save.

DIALOG "Options", "Segoe UI", 400, 300
*FORM
  Dimension=100, 100, 400, 300
  Caption=My Dialog
*LABEL
  Caption=Enter your name:
*EDIT
  Name=entName
*BUTTON
  Name=btnOk
  Caption=OK
ENDDIALOG

' Retrieve values
name = DIALOGVAR("entName")

Wizards

Multi-step interfaces with "Next" and "Back" navigation. See the dedicated Wizard Guide for full details.

To open the built-in Wizard Editor, place the cursor on the WIZARD keyword, right-click, and choose Wizard Editor. The editor highlights the full WIZARD...ENDWIZARD block, opens the visual designer, and writes the updated wizard code back into that block when you save.

WIZARD "Setup Wizard", 500, 400
*Form
  Name=page1
  Caption=Welcome
  Desc=This is step 1
*EDIT
  Name=entName
  Caption=Enter Name
*Form
  Name=page2
  Caption=Finish
  Desc=You are done!
ENDWIZARD

' Retrieve values
username = WIZARDVAR("entName")

---

6. Service Mode & Automation

BTB scripts can run as Windows Services. Special comments at the top of the script define service properties:

'DISPLAYNAME=MyAutomator
'ACCOUNTNAME=LocalSystem
'STARTTYPE=3
'DELAYSTART=1000
'VERBOSE=1

Monitoring Patterns

A common pattern for BTB is monitoring a folder:

WHILE 1=1
  lCount = FINDFILES("C:\Monitor\*.pdf")
  FOR i = 1 TO lCount
    lFile = FINDGET(i)
    IF WAITFILELOCK(lFile, 10) THEN
      ' Process file...
    ENDIF
  ENDFOR
  PAUSE 5
ENDWHILE

---

7. Function Reference (Categorized)

AI & OCR

• AIOPEN(apiKey, attachInline, systemPrompt, [endpoint]): Open an AI channel.
• AIEXEC(handle, prompt, [attachments]): Execute an AI prompt.
• AICLOSE(handle): Close the AI handle.
• AITOKENCOUNT(handle): Get tokens used in last request.

File & Directory Operations

• FILEEXISTS(path), DIREXISTS(path): Check existence.
• FILECOPY(src, dest), FILEDELETE(path), FILERENAME(old, new): File management.
• MKDIR(path): Create directory.
• FOPEN(path, mode): Open file (1=Read, 2=Create/Write, 3=Append).
• FGETS(handle), FPUTS(handle, text): Read/Write lines.
• LOADFROMFILE(path): Load entire file.
• SAVETOFILE(var, path): Save variable to file.
• FINDFILES(spec, [sortByDate]): Search for files.
• FINDGET(index): Retrieve file name from search result.

String Manipulation

• LEFT(text, count), RIGHT(text, count), MID(text, start, count): Substring extraction.
• LENGTH(text): String length.
• UPPER(text), LOWER(text): Case conversion.
• TRIM(text): Remove spaces.
• STRREPLACE(src, find, replace): Search and replace.
• PARSE(text, delimiter): Get left side of delimiter.
• RPARSE(text, delimiter): Get right side (reverse parse).
• STR(number), VAL(string): Conversion between types.

Network & Communication

• HTTPEXEC(method, url, [content], [headers]): Web requests (GET, POST, etc.).
• FTPCONNECT(host, user, pwd): FTP connection.
• SMTPSETUP, SMTPCONNECT, SMTPSEND: Email sending.
• POP3RETRIEVE, IMAPSEARCH, IMAPGET: Email retrieval.
• SNMPGET(handle, mib): SNMP management.

System & Process

• EXEC(app, params), ENHEXECUTE(app, params): Run applications.
• GETPROCESSLIST(): List running processes.
• PROCKILL(pid): Terminate process.
• SYSDIR(type): Get system paths ("home", "temp", "resource").
• EXPANDENV(envVar): Expand environment variables (e.g., %TEMP%).
• TICKCOUNT(): Milliseconds since system start.

Database Operations

• DBOPEN(connectionString): Open database.
• DBEXECUTE(handle, sql): Execute SQL.
• DBGET(handle, field): Retrieve field value.
• DBCLOSE(handle): Close database.

UI Interaction

• PRINT message: Display message.
• PROMPT message, seconds: Transient message.
• INPUT prompt, var: User input.
• MSGBOX(message, type, buttons): Standard Windows message box.
• GETFILE(), GETDIR(): File/folder pickers.
• SHOWPROGRESS(text) / UPDATEPROGRESS(pct): Progress bars.

---

For the complete alphabetical list of 200+ functions, consult the Command Reference.