Skip to content

Language Reference Collections

Jump to bottom
Andreas AFENTAKIS edited this page Oct 8, 2025 · 18 revisions

**PAGE UNDER CONSTRUCTION **

Language Reference Collections

In FBASIC, collections are fundamental data structures used to manage lists of values and result sets from data sources. While traditional single variables hold one value, collections allow a program to store and iterate over multiple related items efficiently. The two primary collection types referenced in the language are SDATA (or Static) and CURSOR (or Fetchable).

Understand the concept.

As FBASIC is an extedable computer programming language, the core interpreter offering structures that are common to all modern languages and easy to translate it, statement by statement to another languages. The static collections are collections that are having most of the times just one dimension and are stored in the memory. The fetchable collections are accessible row by row without the ability to have direct access to one row by index.

Characteristic Static Fetchable
In memory Yes No
Access row by index Yes No
Access row by fetch Yes Yes
Need reset Yes Yes
Foreach loop Yes Yes
Known number of items Yes No
Multi field support No Yes
Dynamic field naming No Yes
Need data source No Yes
Data from the program (via SDATA) Yes No
Statement SSET Yes No

1. SDATA Collections (Static Data)

An SDATA collection is a dynamic, in-memory structure primarily designed to store and manage lists of primitive values (like strings or numbers) generated or manipulated within the FBASIC program's execution flow. It serves a similar role to an array or list in other languages, allowing for flexible data aggregation.

Creation and Population

The SDATA collection is created and populated using the SDATA statement.

Statement Purpose Example
SDATA collectionName "" Initializes a new, empty collection. sdata names ""
SDATA collectionName [value] Appends a single value to the end of the collection. sdata names [nameInput]

Population Example (from code)

The following example demonstrates initializing an SDATA collection and populating it within a loop:

REM Initialize an empty SDATA collection named 'names'
sdata names ""

inputLoop:
input nameInput

If nameInput = "." Then
GoTo endInput
EndIf

REM Store the name into the SDATA collection
sdata names [nameInput]

GoTo inputLoop
endInput:

Retrieval and Iteration

The standard way to access all items in an SDATA collection is using the FOREACH...ENDFOREACH loop structure.

Statement Purpose
FOREACH collectionName Begins a loop that iterates through every item in the collection.
[collectionName.Item] A special syntax used only inside a FOREACH loop to reference the current item's value.
ENDFOREACH collectionName Closes the loop structure.

Example of Iteration:

Foreach names
print [names.Item]
EndForeach names

Explicit SDATA Manipulation Statements and Functions

FBASIC provides dedicated statements and functions for advanced management of SDATA collections, granting array-like control.

Statement/Function Syntax Type Description
SSET SSET collectionName, index, value Statement Sets/updates the value of an item at a specific, 1-based index in the SDATA collection.
SCNT() SCNT(collectionName) Function Returns the total number of elements (count) currently stored in the SDATA collection.
SCI() SCI(collectionName, index) Function Returns the value of the item at the specified 1-based index in the SDATA collection.

Example using SSET and SCNT():

sdata scores ""
sdata scores [95] REM stores 95 at index 1
sdata scores [88] REM stores 88 at index 2

let total = SCNT(scores)
print "Total items: " + total REM Prints 2

SSET scores, 2, 90 REM Change value at index 2 from 88 to 90
let newScore = SCI(scores, 2)
print "New score at index 2: " + newScore REM Prints 90

2. CURSOR Collections (Dynamic Data)

The CURSOR collection is a special type of collection that acts as a wrapper for external data sources, specifically SQL results. It is designed for efficient, record-by-record retrieval of data without loading the entire dataset into memory at once.

Creation

The CURSOR collection is created using the CURSOR statement, which typically executes a SQL query against a configured data provider.

Syntax: Cursor collectionName, "SQL Statement"

Example:

Cursor DATA1, "select top 20 id,name where type='S' from sysobjects order by name"

Retrieval and Navigation Statements and Functions

Statement/Function Syntax Type Description
FETCH FETCH collectionName Statement Reads the next record from the cursor's result set, making its fields accessible for use.
RESET RESET collectionName Statement Resets the cursor position back to the beginning of the result set, allowing the program to iterate over the data again.
EOD() EOD("collectionName") Function Returns a boolean value (true/false) indicating if the End Of Data has been reached for the specified cursor.
Field Access [collectionName.FieldName] Syntax Accesses the value of a field from the currently fetched record.

A. Standard FOREACH Loop

This is the most common and robust method for processing all records in the result set.

Foreach DATA1
sdata names [DATA1.name]
EndForeach DATA1

B. Manual FETCH Loop

This method offers fine-grained control over reading records, often used with conditional branching using EOD().

dataloop1:
fetch DATA1
If EOD("DATA1") Then
GoTo exitloop
EndIf

let msg= "ID: " + sql([DATA1.id]) + ", Name: " + sql([DATA1.name])
print msg

GoTo dataloop1

exitloop:

3. Data Provider Concept

The Data Provider is a crucial component that extends FBASIC's core functionality, serving as the bridge between the program's execution environment and external data sources, typically relational databases accessible via SQL.

Role and Function

The Data Provider is an external adapter, configured at the interpreter level, that executes the following responsibilities:

  1. Connection Management: It establishes and maintains the necessary connection to the external database (e.g., SQL Server, Oracle, or a file-based database).
  2. SQL Execution: It receives the raw SQL query string passed through the CURSOR statement. It executes this query against the configured database.
  3. Result Set Wrapping: Instead of returning the raw data, the Data Provider wraps the query results into a CURSOR collection. This design ensures that FBASIC can efficiently process large datasets record-by-record without loading the entire result into memory, facilitating data streaming.

The CURSOR collection is entirely dependent on a correctly configured Data Provider being available to the FBASIC environment. If the Data Provider is not configured or fails to execute the SQL, the CURSOR statement will result in a runtime exception.

Clone this wiki locally