intersystems-community/iris-agentic-dev/objectscript-mac-routines

MAC Routine Hard Gate — Check BEFORE Writing Code

Before generating any .MAC code, verify all 8 items:

Correct MAC Structure

MYROUTINE
    ;Entry point - no parens, no braces
    Set x = $$CALC(3,4)
    Quit
    ;
CALC(a,b)   ;Extrinsic function - called with $$CALC(a,b)
    Quit a+b
    ;
HELPER  ;Subroutine - called with Do HELPER
    Write "done",!
    Quit

$ZTRAP Error Handling (legacy pattern)

MYROUTINE
    Set $ZTRAP = "ERRHAN"
    ; ... code that might error ...
    Quit
    ;
ERRHAN
    Set err = $ZE
    Set $ZTRAP = ""
    Write "Error: ",err,!
    Quit

Reading and writing .MAC via Atelier

VS Code's isfs:// provider does not always expose routines, so go at the Atelier REST API directly. The document name includes the .mac extension.

# Read
iris-agentic-dev tool iris_doc --args '{"mode":"get","name":"MYROUTINE.mac"}'
 
# Write (checks the document out of source control first when one is configured)
iris-agentic-dev tool iris_doc --args '{"mode":"put","name":"MYROUTINE.mac","content":"MYROUTINE\n Quit\n"}'
 
# List MAC routines
iris-agentic-dev tool iris_doc --args '{"mode":"list","pattern":"*.mac"}'

Without the CLI, call Atelier with curl -K -, which reads the credential from stdin so it stays out of the process list. IRIS_SCHEME is https for an HTTPS endpoint:

printf 'user = "%s:%s"\n' "${IRIS_USERNAME:-_SYSTEM}" "$IRIS_PASSWORD" \
  | curl -s -K - "${IRIS_SCHEME:-http}://${IRIS_HOST:-localhost}:${IRIS_WEB_PORT:-52773}/api/atelier/v1/${IRIS_NAMESPACE:-USER}/doc/MYROUTINE.mac"

A PUT to the same URL with ?ignoreConflict=1 overwrites regardless of the server timestamp.

A PUT does not compile — follow it with POST /action/compile and a body of ["MYROUTINE.mac"], or use the iris_compile MCP tool. Always re-read after writing; the PUT response body is not a reliable confirmation. See the compile skill.

Common Bugs in Legacy MAC Code

• result used after a For loop but never initialized → <UNDEFINED> if no rows
• #include file not found → check ^%INCLUDE global or .inc file spelling
• $$FUNC vs Do LABEL confusion: $$ for functions returning values, Do for subroutines
• Quit value in a Do-called subroutine → exits subroutine cleanly; Quit with no value for void