ATARI MUTINEER
[H] HOMEATARI MUTINEER / DOCUMENTATION / 1.3.183

Runtime Architecture

Understand boot, dispatch, session state, storage, and communications flow.

Browse documentation

Runtime Architecture

Atari Mutineer uses standalone Atari BASIC programs connected by a REMMS-owned resident session block. A BASIC RUN discards variables and closes IOCBs; resident state and disk files carry the caller across module switches.

Boot Flow

SpartaDOS X
  -> RHND850.COM
  -> REMMS.COM
  -> BASIC /I <<D1:AUTOGO
  -> RUNBBS
  -> APPMGR
  -> WFC

REMMS installs at $1E00, publishes discovery at $03E8, initializes its 352-byte session block, and starts in local mode with its E: and K: wrappers installed. The wrappers directly chain the validated saved handlers for local operations; route or carrier changes do not rewrite HATABS.

Only RUNBBS, APPMGR, PATHREG.DAT, PATHREG.BAK, and the staged PATHREG.NEW update target have fixed bootstrap paths. Runtime menus, static assets, common config/data files, scheduler files, transfer spool files, and global network queue/config files are classified through the compact path registry. Application, door, message, and file locations remain owned by their specialized registries or metadata.

RUNBBS calls the API initializer, writes stable key $0001 (WFC) into the session block, and runs APPMGR.

Wait For Call

WFC opens REMMS host mode and keeps output local while waiting:

RING -> answer-ring counter -> ATA -> CONNECT -> online=1 -> route both

The local dashboard consumes REVENT, which owns console, keyboard, modem, remote-input, carrier, and error polling:

  • START: local level-9 sysop session in CORE.
  • SELECT: offline initialization/maintenance.
  • OPTION: shut down BASIC.

On a remote connection WFC detects ASCII versus ATASCII from the first return, performs login or registration, appends caller history, commits session state, and requests CORE through APPMGR.

Application Dispatch

RUNBBS -> APPMGR -> WFC -> APPMGR -> CORE
CORE -> APPMGR -> DOORS / MESGAREA / FILEBASE / SYSCHAT / SYSOP / XFERSEL

Modules write a requested stable key to session +90/+91 and an optional return key to +92/+93, then RUN "D1:>CORE>APPMGR". APPMGR resolves APPREG.DAT through PATHREG, validates the registered minimum access level, updates runtime handles, and runs the registered path. Loader CLOSE records RESUME_PENDING, and a BASIC destination performs exactly one non-hangup ROPEN,RESUME. Native transfer workers are the exception: APPMGR loads and validates the COM file while suspended, then performs one guarded ROPEN,RESUME immediately before calling the worker because there is no intervening BASIC destination.

APPMGR bulk-loads and checksum-validates the packed, key-sorted registry once per invocation, then resolves destination and return keys in memory. The trusted FILEBASE/FILEWORK overlay pair and bundled doors may return directly after validating the REMMS session and updating current/next/return handles; invalid sessions fall back to APPMGR.

Change Area is canonical in resident FILEBASE because it has the same configured-ID and access checks as the former FILEWORK copy without two BASIC reloads. FILEWORK contains only operations that need the worker overlay.

Session Ownership

The canonical layout is in remms/src/constants.inc and documented in the REMMS Programmers Guide. Important fields are:

  • identity strings at +2..+83;
  • terminal modes at +84..+86;
  • online state at +87;
  • app keys at +90..+93;
  • module/transfer state at +96/+97;
  • current app at +102;
  • access/user/time fields at +123..+127;
  • answer-rings state at +159/+160;
  • XFR1 transfer control block at +163..+337;
  • native message MSG1 control block at +340..+351;
  • unread count/cache validity and scheduler job state at +317..+322.

Online modules validate magic/version, restore their session fields, reopen REMMS host state, set route both, reopen caller-facing E:/K: channels, and check carrier at input boundaries. Local modules use mode/route local.

Caller I/O

  • USR(REVENT) performs the foreground event-pump pass.
  • USR(RGET) returns one exact raw remote byte, $0100 no data, $0101 carrier loss, $0103 fatal I/O, or $0104 timeout.
  • USR(RTGET) returns one canonical text byte or the same structured result.
  • USR(RPUT,byte) transmits one raw byte.
  • Wrapped E: output is local, remote, or mirrored according to route.
  • Wrapped E:/K: input uses remote bytes only while session +87 is online and shares the RTGET translation path; otherwise calls chain to the saved local handlers.
  • Text modules use canonical ATASCII (9B EOL, 7E backspace, 7F tab).
  • Native protocol binaries use the REMMS transfer service table so terminal newline translation does not corrupt binary blocks.

REMMS preserves the SIO DCB around CIO operations and keeps its validated E:/K: wrappers installed. Reinstall safely refreshes or chains a changed HATABS entry instead of switching handlers according to route.

Disk And Modem Ownership

REMMS reserves IOCB 5 for R:. Caller-facing BASIC modules never perform disk I/O while that physical modem owner is active: they request a non-hangup suspend with RCLOSE,1, read or write a bounded disk chunk, close the disk channel, and resume with ROPEN,0. Long caller lists, menus, message/file lists, and text downloads buffer data between those boundaries before sending it through the resident pager. Text uploads close the modem only for the brief append and never hold a disk file open while waiting for caller input.

External transfers use the same ownership boundary for disk blocks. FILEBASE builds an XFR1 request, XFERSEL selects the protocol, and APPMGR binary-loads the native protocol from D1:>PROTO>. Protocol binaries call REMMS native transfer services and never own R: directly.

Runtime Path Ownership

Direct D1: literals in BASIC must be one of:

  • fixed bootstrap/app-dispatch paths;
  • paths resolved through PATHREG;
  • APPREG/DOORCAT registered targets;
  • message-base paths derived from MSGBASE.CFG and MESG?.MET;
  • file-area paths derived from FILE?.MET;
  • native worker handoff, lock, journal, swap, or queue paths documented in the relevant data-format section.

tools/runtime_path_check.py enforces this classification for BASIC sources.

Permission Model

The runtime permission model is compact:

  • app access comes from APPREG minimum level;
  • door access comes from DOORCAT minimum level;
  • message access comes from MESG?.MET read/post levels plus command gates;
  • file access comes from FILE?.MET view/download/upload levels and protocol policy;
  • profile/user-edit authority comes from LOGIN and USERS.DAT.

The deferred full per-level matrix design is not parsed by caller modules. tools/permission_model_check.py enforces the compact model.

Carrier And Cleanup

REMMS 1.7 distinguishes confirmed carrier loss, negative modem CIO status, timeout, recoverable FIFO conditions, and BASIC/application failure. Fatal paths call RFAIL, preserve the first operation and CIO status, end text input, reconcile the physical owner, and record one exit/event transition. BASIC enters WFC only after the device is closed or explicitly faulted; deliberate APPMGR transitions retain the tracked-resume policy.

Before offline tools or shutdown, WFC calls RDETACH. This closes owned modem state and restores the exact saved E: and R: handlers while leaving K: alone. A later RUNBBS entry calls RINIT to reinstall REMMS.

Normal logoff closes REMMS, which performs the guarded modem hangup sequence, closes the IOCB, clears call parser state, and restores local operation.

Module Responsibilities

  • RUNBBS: initialize REMMS and request WFC.
  • APPMGR: registry lookup, access check, route preparation, and RUN.
  • WFC: dashboard, answer/login/register, local controls, caller persistence.
  • CORE: main commands, text, feedback, callers, dispatch, and logoff.
  • MESGAREA: multi-base scan/read/enter/kill and message-service dispatch.
  • MSGEDIT, MSGMAIL, MSGMOD: compose, private-mail, and moderation UIs; they stage requests but do not write live message storage.
  • MSGSTORE.COM: transient lock-guarded writer and storage authority.
  • MSGRCV.COM, MSGCMP.COM: transient recovery and compaction workers.
  • SCHED: idle WFC job dispatcher for verification, networking, and conditional compaction.
  • FILEBASE: multi-area list/download/upload/info and XFERSEL dispatch.
  • DOORS: access-filtered catalog and external door launch.
  • SYSOP: remote caller/sysop chat fallback.
  • XFERSEL: transfer protocol selection and native protocol dispatch.
  • INIT, FILEMGR, MSGMGR: initialization and fenced maintenance launchers.

The supported login/registration path remains in WFC.