forge Documentation

differences

FORGE Features and Capabilities

Overview

FORGE (Fast Optimizing Runtime Generation Environment) is a fast BASIC interpreter for the Atari 8-bit computers with modern features and enhanced capabilities. This document describes the key statements, functions, and capabilities available in FORGE.

New Statements

FUNC ... ENDFUNC (Replaces PROC/ENDPROC)

User-Defined Functions and Procedures

FORGE uses FUNC/ENDFUNC for both procedures and functions, providing a unified approach to user-defined code.

Syntax for Procedures (no return value):

FUNC name param1 param2 ...
  ' procedure body
ENDFUNC

Syntax for Functions (with return value):

FUNC name param1 param2 ...
  ' function body
  RETURN expression
ENDFUNC

Key Features:

  • FUNC without a return type behaves like the old PROC (procedure)
  • FUNC with RETURN returns a value and can be used in expressions
  • String-returning functions use a $ suffix (e.g., FUNC greet$)
  • Parameters work the same way (integer variables)
  • Can be called with @ prefix, EXEC, or by name in expressions
  • ENDFUNC automatically emits TOK_RET or TOK_RET_VAL based on whether the function has a return type

Example - Procedure:

FUNC greet name
  ? "Hello, "; name
ENDFUNC

@greet "World"

Example - Function:

FUNC add x y
  RETURN x + y
ENDFUNC

result = add(10, 20)  ' Returns 30

STATUS #iochn, statusVar

Get Device Status

The STATUS statement queries device status information from an I/O channel.

Syntax:

STATUS #iochn, statusVar

Key Features:

  • Calls CIO STATUS operation (command 13) on the specified channel
  • Stores CIO status code in statusVar (1 = success, >127 = error)
  • After successful STATUS call, device-specific information is placed in DVSTAT buffer (memory locations 746-749)
  • Essential for R: device operations (Atari 850, R:Verter, BOB-Verter) to check carrier status, error bits, and buffer counts

Example:

OPEN #1, 12, 0, "R1:"
STATUS #1, ST
IF ST = 1 THEN
  ERR_BITS = DVSTAT(0)
  SENSE = DVSTAT(1)
ENDIF

NOTE #iochn, sectVar, byteVar

Get Current File Position

The NOTE statement retrieves the current file position for random-access file operations.

Syntax:

NOTE #iochn, sectVar, byteVar

Key Features:

  • Gets current logical file position (sector + byte offset)
  • Stores 16-bit sector number (0-65535) into sectVar
  • Stores 8-bit byte offset (0-255) into byteVar
  • Automatically preserves AUX1 mode from when file was opened
  • Essential for building indexes for random-access file operations
  • Works with disk files (D:) and other devices supporting random access

Example:

OPEN #1, 8, 0, "D:USERS.DAT"
NOTE #1, SEC, BYT  ' Save position before writing
PRINT #1, "Record data"

POINT #iochn, sectExpr, byteExpr

Set File Position

The POINT statement sets the file position for random-access file operations.

Syntax:

POINT #iochn, sectExpr, byteExpr

Key Features:

  • Sets file position to specified sector and byte offset
  • Enables indexed/random-access reads by jumping to previously saved positions
  • Automatically preserves AUX1 mode from when file was opened
  • Works with disk files (D:) and other devices supporting random access
  • Used together with NOTE for building indexed file systems

Example:

OPEN #1, 4, 0, "D:USERS.DAT"
POINT #1, SEC, BYT  ' Jump to saved position
INPUT #1, A$

INCLUDE "filename"

Include Source Files

The INCLUDE directive allows modular code organization by including other source files at compile time.

Syntax:

INCLUDE "filename"
INCLUDE ONCE "filename"
#include "filename"  ' C-style syntax also supported

Key Features:

  • Inserts contents of another source file at compile time
  • Supports INCLUDE ONCE to prevent multiple inclusions
  • Automatic .bas extension if no extension specified
  • Path resolution: current file directory → include search paths → working directory
  • Cross-platform path support (both / and \ separators)
  • Circular include detection (max 32 levels)
  • Only works with command-line compiler, not IDE interpreter

Example:

INCLUDE "lib/math.bas"
INCLUDE "lib/graphics.bas"

FUNC main
  ? add(5, 3)
ENDFUNC

@main

New Functions

DVSTAT(index)

Read DVSTAT Buffer

The DVSTAT() function provides easy access to the device status buffer (memory locations 746-749).

Syntax:

DVSTAT(index)  ' index: 0, 1, 2, or 3

Key Features:

  • Reads a byte from the DVSTAT buffer
  • index must be 0, 1, 2, or 3 (corresponding to DVSTAT[0] through DVSTAT[3])
  • Used after STATUS statement to read device-specific information
  • Meaning of each byte depends on device handler:
    • DVSTAT(0) - Error bits (bitfield)
    • DVSTAT(1) - Sense byte or buffer count low byte
    • DVSTAT(2) - Buffer count high byte (usually 0)
    • DVSTAT(3) - Output buffer count
  • Particularly useful with R: devices for checking carrier status, error bits, and buffer counts

Example:

STATUS #1, ST
IF ST = 1 THEN
  ERR_BITS = DVSTAT(0)
  SENSE = DVSTAT(1)
  INPUT_COUNT = DVSTAT(1) + 256 * DVSTAT(2)
  OUTPUT_COUNT = DVSTAT(3)
ENDIF

Functional Enhancements

Random-Access File Operations

FORGE adds native support for random-access file operations through NOTE and POINT statements:

  • Automatic AUX1 preservation - No need to manually track and pass AUX1 values
  • Safer than XIO - Built-in error handling and proper mode management
  • Indexed file support - Enables building databases, message bases, and indexed record systems
  • Simplified syntax - No need to remember XIO command codes (37/38)

Modular Code Organization

FORGE adds INCLUDE directives for better code organization:

  • Multi-file projects - Split large programs into logical modules
  • Code reuse - Build libraries of reusable procedures and functions
  • Better organization - Separate concerns into different files
  • Include guards - INCLUDE ONCE prevents duplicate inclusions

Unified Function/Procedure Syntax

FORGE uses FUNC/ENDFUNC for both procedures and functions:

  • Unified syntax - One keyword for both procedures and functions
  • Return values - Functions with RETURN can be used in expressions
  • Automatic return handling - ENDFUNC automatically emits the correct return token
  • Cleaner code - More natural expression of mathematical and logical operations

Device Status Queries

FORGE adds STATUS statement and DVSTAT() function:

  • Standardized status checking - Consistent way to query device status
  • R: device support - Essential for serial device operations (Atari 850, modems)
  • Error detection - Easy access to device error bits and status information
  • Buffer management - Check input/output buffer counts for concurrent mode

Summary

FORGE provides the following key functional capabilities:

  1. FUNC/ENDFUNC - Unified syntax for procedures and functions (replaces PROC/ENDPROC)
  2. STATUS - Device status querying statement
  3. NOTE - Get current file position for random-access files
  4. POINT - Set file position for random-access files
  5. INCLUDE - Source file inclusion for modular code organization
  6. DVSTAT() - Function to read device status buffer

These additions enable:

  • Better code organization (INCLUDE)
  • Unified function/procedure syntax (FUNC replaces PROC)
  • Native random-access file operations (NOTE/POINT)
  • Easier device status checking (STATUS/DVSTAT)

Note: FORGE uses FUNC/ENDFUNC for both procedures and functions. If you're migrating code that uses PROC/ENDPROC, update it to use FUNC/ENDFUNC instead.