REMMS Programmers Guide

REMMS is the supported resident modem, input, output-routing, and session layer for Atari Mutineer. It is not an MMS ABI clone. BASIC code discovers REMMS dynamically and calls the published jump table.

REMMS.COM loads at $1E00, installs through INITAD, publishes a discovery record, and raises MEMLO so Atari BASIC modules can call it safely.

Discovery Record

The loader publishes this record at $03E8:

Atari BASIC therefore reads the API pointer from decimal 1004/1005, the public block from 1006/1007, and the session block from 1010/1011.

Byte +3 ($03EB) is the XL OS CARTCK location. REMMS does not own it and never writes it: the 850 R: handler, relocated just above REMMS at MEMLO, uses it as working storage and rewrites it thousands of times per call. The publish loop skips it. The remms-lifecycle case discovery_after_connect traces every write to the other discovery bytes under the Altirra debugger and watches REMMS's only store into the record (sta REMMS_DISCOVERY,x) for index 3. It fails if REMMS writes $03EB, if anything but REMMS writes another discovery byte, or if the signature, pointers or RPUB+5/+6 change after a connected call. The other discovery bytes are XL OS boot-time variables (SUPERF, CKEY, CASSBT, DERRF, ACMVAR) that nothing writes once DOS is running; the layout is inherited from the MMS memory map. Read the REMMS version from the public block (RPUB+5 major, RPUB+6 minor).

BASIC PEEK Reference

Discovery record at decimal 1000 ($03E8):

Public block offsets from RPUB:

Session block offsets from SS:

BASIC USR Reference

REMMS 1.7 keeps every older API offset stable. Each entry is three bytes:

RTEXT is the fixed page-six entry at $0601 rather than a resident jump-table slot:

R=USR(1537,ADR(PATH$),LEN(PATH$),ADR(WORK$),FLAGS)

WORK$ reserves 256 bytes. Its first 64 bytes hold the EOL-terminated path and the remaining 192 bytes are the streaming buffer. Flag bit 0 clears the display before output and bit 1 enables paging. Results are 0 success, 1 user abort, 2 invalid request, 3 open failure, 4 disk failure, and 5 output or carrier failure. The service preserves the current route, suspends the modem around each disk chunk, and resumes it before sending that chunk.

RDETACH ends resident text/pager activity, closes REMMS-owned R: state, restores the exact saved E: and R: HATABS pointers, leaves K: untouched, and returns routing to local. REMMS discovery and memory remain present; RINIT installs the handlers again.

Set the common names once after discovery:

1010 RINIT=RAPI:RMODE=RAPI+3:RROUTE=RAPI+6:ROPEN=RAPI+9:RCLOSE=RAPI+12
1020 RSTAT=RAPI+15:RGET=RAPI+18:RPUT=RAPI+21:RCON=RAPI+24:RTGET=RAPI+27
1030 PBEGIN=RAPI+30:PPUT=RAPI+33:PEND=RAPI+36:RRESET=RAPI+39
1040 REVENT=RAPI+42:TBEGIN=RAPI+45:TEND=RAPI+48:RFAIL=RAPI+51

Result And Enum Tables

Structured byte results returned by RGET, RTGET, and RPUT:

REMMS error codes:

Event kinds returned by REVENT:

Physical states:

Connection states:

Text input modes for TBEGIN:

Editor mode leaves received editing controls out of the display stream. The application redraws accepted text explicitly, so ATASCII cursor controls and ANSI cursor sequences cannot be recorded as message-body bytes.

Operation codes stored in telemetry:

RGET/RPUT return $0100 no data, $0101 carrier lost, $0102 recoverable I/O, $0103 fatal I/O, or $0104 timeout. REVENT returns event_kind*256+value. RFAIL accepts reason 4 carrier, 6 fatal I/O, 7 timeout, or 8 application failure. It preserves a more specific resident reason, ends text input, and closes through the lifecycle owner.

Modes, Routes, And HATABS

The central invariant is: local mode never polls, reads, or writes R:.

• Local mode forces local output and restores the original E:/K: HATABS entries.
• Host-open begins in local-output mode while REMMS waits for a call.
• After CONNECT, REMMS marks session +87 online, selects route both, and installs its E:/K: wrappers.
• A remote-only or mirrored route is active only while session +87 is 1.
• Carrier loss or fatal modem I/O clears online/text state, closes R: through the physical owner, restores local mode/route, and records one pending event. Cleanup CLOSE failure leaves explicit PHYSICAL_FAULT.

The wrappers chain to the saved handlers directly. A local E: get first restores the saved E: entry in HATABS, because SDX's console handler resolves E: through HATABS again and would otherwise re-enter the wrapper. Every chained return reinstalls the wrappers. HATABS entries are found by device letter each time; the saved indexes are transient session bytes that a BASIC program switch clears. REMMS preserves the zero-page working range, DVSTAT, and the SIO DCB around the relevant CIO calls.

Call Lifecycle

Opening R: configures concurrency and resets the host parser. USR(RSTAT) consumes modem result bytes in bounded batches and recognizes:

RING -> ATA -> CONNECT

Session +159 contains the answer-after-rings setting (1..9) and +160 contains the current ring count. REMMS sends ATA once when the configured count is reached. The parser stops on the complete CONNECT terminator and queues every already-available caller byte in order. RING, CONNECT, and pre-connect NO CARRIER parsing is disabled after connection. Connected carrier loss is sensed out of band through the 850 status/sense path; negative CIO status and timeout have distinct structured results and exit reasons.

Raw And Text Input

RGET (RAPI+18) and RPUT (RAPI+21) are byte-exact. WFC uses raw input for the first-return terminal probe. Native transfer protocols use the REMMS transfer service table published in discovery bytes +12..+15. Normal BBS and door input uses RTGET (RAPI+27). Remote E:/K: reads use the same translated path, so there is one text conversion implementation.

When session +84 is zero, the corrected MOE input table is:

Other bytes are unchanged. CRLF and CRNUL are returned as one EOL; a lone LF still maps to a space. Ctrl-C 03 and Ctrl-S 13 are discarded. When session +84 is nonzero, ATASCII bytes pass through unchanged except for those two remote flow-control bytes.

The resident pager never uses printable letters as controls. At a pager prompt, Return advances one line, Space advances one page, Ctrl-Q shows the remainder, and Ctrl-C quits the listing. During output, Ctrl-S pauses, Ctrl-Q resumes, and Ctrl-C aborts. Printable S, C, and Q are preserved as ordinary typeahead for the next text input operation.

Standard line editors consume only the canonical values: 7E performs destructive backspace, 7F inserts one space, and unsupported clear, cursor, line insert/delete, and character insert/delete controls are ignored. Strict MOE semantics mean incoming ASCII DEL 7F is indistinguishable from ATASCII tab and therefore inserts one space; it is not a backspace alias.

Translated input is bounded by a 60-byte watermark in a 64-byte FIFO. A modem status snapshot of 60 bytes or more is not partially delivered: REMMS sends XOFF, clears the FIFO, rebuilds the concurrent stream, and returns recoverable event kind 5, value 8. Every BASIC field reader restarts from an empty field. This intentionally rejects an unpaced long paste rather than accepting a rotated or truncated line.

Text Output

Wrapped E: output is raw in ATASCII mode. In ASCII mode REMMS maps:

The FD mapping intentionally fixes the duplicate-7D comparison in the MOE source. Binary output must bypass E: and use raw RPUT.

External transfer ownership

FILEBASE writes an XFR1 request into session +163..+337, XFERSEL selects a registered protocol, and APPMGR loads the native COM file from D1:>PROTO>. REMMS publishes the native transfer service table at discovery +12/+13 and the transfer block pointer at +14/+15. Protocol binaries use that table for raw bytes, binary-mode lifecycle, progress, cancellation, and result state.

Caller-facing BASIC must not overlap disk CIO with an active physical R: owner. Use RCLOSE,1, perform bounded disk I/O, close the disk channel, and then call ROPEN,0 before pager or prompt output. Buffer or chunk long displays; never leave a disk file open while waiting for caller input. RCLOSE,1 sends XOFF and keeps remote input paused across disk work. The next TBEGIN discards paused typeahead and sends XON only after the new field is ready. Callers must not substitute fixed sleeps for this handshake.

Console Commands

USR(RAPI+24) returns:

WFC maps these values to local sysop login, offline tools, and shutdown.

Console actions use only the physical console switches and XL/XE HELP latch:

REMMS clears HELPFG after consuming $11, $51, or $91. It never reads ordinary CH or K: input for console control, and there are no printable aliases.

Session Block

REMMS owns a 352-byte block with magic 77 and session version 9.

BASIC programs must preserve the fields they do not own across RUN.

BASIC Startup Pattern

1000 IF PEEK(1000)<>82 OR PEEK(1001)<>69 OR PEEK(1002)<>77 THEN RUN "D1:>CORE>WFC"
1010 RAPI=PEEK(1004)+256*PEEK(1005)
1020 RPUB=PEEK(1006)+256*PEEK(1007):SS=PEEK(1010)+256*PEEK(1011)
1030 RMODE=RAPI+3:RROUTE=RAPI+6:ROPEN=RAPI+9
1040 RSTAT=RAPI+15:RGET=RAPI+18:RPUT=RAPI+21:RTGET=RAPI+27
1050 IF PEEK(SS)<>77 OR PEEK(SS+1)<>9 THEN RUN "D1:>CORE>RUNBBS"
1060 R=USR(ROPEN,0):IF R<>0 THEN R=USR(RAPI+51,6):RUN "D1:>CORE>WFC"
1070 R=USR(RMODE,1):R=USR(RROUTE,2)

Local modules instead call USR(RMODE,0) and USR(RROUTE,0).