317B ExecuteCommand¶
Validated MON 317B (207 decimal) · Mnemonic UECOM · Group: Commonly-Used Monitor Calls (manual section 2.3)
Available from: Background programs (manual compatibility box)
Emulation source: src/handlers/mon_317B_ExecuteCommand.c
Description¶
Executes a SINTRAN III command. Specify the command name and the parameters as a text string.
- An error message is output if an error occurs. The program does not terminate.
- Some commands may destroy your program. Commands which affect your program’s memory area should be used with care.
- Some commands have output, e.g. @LIST-FILES. This is displayed on the terminal.
- Use SuspendProgram to wait a second between two ExecuteCommands which depend on each other, e.g. CreateFile and OpenFile.
- It may be advisable to use @enable-escape before this call, to avoid having problems terminating some commands.
Notes¶
- Version history: M-version increased the maximum length of the command buffer from 104 characters to 150 characters (ND-860230-7A-EN SINTRAN III - Release Information - M-Version.md:1093).
Parameters¶
| Name | Type | Direction | Description |
|---|---|---|---|
Command |
STRING | In | SINTRAN III command string to execute (up to 35 chars). |
Direction: In = the program supplies the value, Out = the call returns it, In/Out = both.
See also¶
CallCommand, SetCommandBuffer. CallCommand terminates the program if an error occurs
Compatibility¶
| Machines | Users | Programs |
|---|---|---|
| ND-100 and ND-500 | All users | Background programs |
The manual's compatibility box for this call, word for word.
Yes/no fields from the YAML extraction (not in the manual's words):
| ND-100 | ND-500 | User programs | RT programs | System programs |
|---|---|---|---|---|
| Yes | Yes | No | No | No |
Examples¶
From the manual (OCR text, not corrected).
BYTES : Command(0:35)
...
Monitor_Call('ExecuteCommand', Command)
CHARACTER Command*35
...
Monitor_Call('ExecuteCommand', Command(1:35))
Command : PACKED ARRAY [0..34] OF CHAR;
...
ExecuteCommand(Command);
01 Command PIC X(35).
...
MONITOR-CALL "ExecuteCommand" USING Command.
Command : STRING 35
ExecuteCommand : EQU 37B9 + 317B
...
CALLG ExecuteCommand, 1, Command
| | |
|--------|-------------------------|
| LDA | (CMND | %Address of string with SINTRAN command. |
| MON | 317 | %Monitor call ExecuteCommand. |
| ... | | |
| CMND, | 'CLOSE-FILE 102' | %Execute CLOSE-FILE 102. |
ndmonlib implementation¶
Validated Registered MON_STATUS_VALIDATED in src/core/mon_registry.c: implemented, tested and working.
| Handler | mon_317B_ExecuteCommand |
| Code lines | 61 (non-blank, non-comment lines in the file) |
Notes from the handler source¶
src/handlers/mon_317B_ExecuteCommand.c line 27
Frontend-registered nested-command runner (loads+runs a DOM re-entrantly).
NULL until the --monitor shell registers one; then UECOM actually executes
the named program (e.g. NC's CAT-CAT5-B06 code-generator back-end).
src/handlers/mon_317B_ExecuteCommand.c line 45
TEMP probe: dump the raw command descriptor and the memory it points at,
to map NC's UECOM argument layout (the CAT-500 invocation).
src/handlers/mon_317B_ExecuteCommand.c line 75
Read command string. NC passes the command as a [Length:4][Pointer:4]
descriptor (arg0 = {maxlen, cmd_ptr, ...}; the command text lives at the
pointer and is 0x27-terminated), e.g. "NC-A", "CAT-CAT5-B". Try that
descriptor form first; fall back to a direct read for callers that pass
the string inline.
src/handlers/mon_317B_ExecuteCommand.c line 87
Nested subsystem invocation (e.g. NC's CAT-500 back-end "CAT-CAT5-B"):
if the frontend registered a runner, let it resolve+run the named program
re-entrantly (sharing this file table) so the back-end actually produces
its output. Contract: 0=ran ok, <0=not a known program (fall back to the
benign stub), >0=program ran but failed.
Emulation research¶
Source
This section comes from the emulation: block of the call's YAML file in the NDInsight repo. It records what was learned while implementing the call in nd500x; its status is nd500x's, not ndmonlib's.
| Status (nd500x) | stub |
| nd500x handler | nd500x/src/libmon/handlers/mon_317B_ExecuteCommand.c |
| Last updated | 2026-07-17 |
Note¶
STUB - SAY SO. nd500x DECODES the command string correctly and then DOES NOTHING WITH IT: it logs the name and returns success. No SINTRAN command is executed, no subsystem is invoked. Callers therefore believe their command ran when it did not.
Parameter notes¶
1. Command
| Field | Value |
|---|---|
| Note | THE DESCRIPTOR - the hard-won fact. NC and the other VDM front-ends pass the command as a [Length:4][Pointer:4] DESCRIPTOR, not inline text: arg0 points at {maxlen, cmd_ptr, ...} and the command text lives AT cmd_ptr, terminated by 0x27 ("'"). mon_read_sintran_string read the descriptor struct directly, saw first byte 0x00, and returned "". nd500x now tries mon_read_descriptor_string() first and falls back to the inline read. 12B SETCM uses the SAME layout. |
| Verified | Yes |
2. Command
| Field | Value |
|---|---|
| Note | An argument-layout probe is left in the handler, gated on the environment variable ND500X_UECOM_DUMP: it dumps the raw descriptor words, 64 bytes at the descriptor address, and 64 bytes at each of the first three words it points to. |
| Verified | Yes |
Observed calls¶
1. NC C front-end (nc-a06.dom) - three invocations per compile
| Field | Value |
|---|---|
| Params | Command: 'NC-A', then 'CAT-CAT5-B', then 'NC-A' |
| Expectation | NC is a VDM front-end: it parses C, writes machine-independent "CAT code" into the always-open scratch file (SINTRAN file number 0100 octal = 64 decimal, SCRATCHnn:DATA), and then invokes the shared BACK-END CODE GENERATOR as a SINTRAN command through this call. By SINTRAN command abbreviation (Users Guide ND-60.050.06 line 1563: "-" separates parts, each abbreviated if unambiguous), 'NC-A' resolves to NC-A06 (the driver itself, nc-a06.dom) and 'CAT-CAT5-B' to the CAT-500 code generator (ND-archive/500/CAT5-CAT/cat-cat5-b06.dom, "CAT-500 - Version B06 - 1988-01-05", 280957 bytes). |
| Note | THIS STUB IS WHY BOUT.NRF WAS ALWAYS 0 BYTES. It was never an emulator or MON-contract bug - it was a MISSING BACK-END. Both emulators stub 317B, so the code generator never runs and the scratch file is never turned into an object. On an older code path the same gap surfaced as the 0x080241FC "T1-B" crash (NC walking a stale pass-record because the pass never ran). Commit 15ca5e9; docs/CAT500_UECOM_CSHARP_HANDOFF.md Part A. |
Return contract¶
- Success: K flag cleared - UNCONDITIONALLY, whether or not anything ran. The manual says an error message is output on error and the program does NOT terminate, so the caller has no reliable way to notice the stub.
-
Errors
Code Octal Meaning 111 157B Missing parameter (fewer than 1 argument supplied)
Verified¶
1. MON 317B dispatches via MCTAB to the L07 worker UECOM.
| Field | Value |
|---|---|
| Evidence | Carve L-VSX-500 317B-ExecuteCommand/README.md - the whole chain (GOTAB slot, MFELL level switch, MCTAB slot, UECOM worker body) is byte-verified. MCTAB slot (segment 044-S3IDPIT, byte offset 2238) = 050701B = UECOM; UECOM worker body 050701B-050725B in 003-S3CP (byte offset 17282). Reproduced: dd if=044-S3IDPIT.bin bs=1 skip=2238 count=2 -> 51 c1. This folder is the reference that established the MCTAB dispatch model for ALL MON calls. |
2. The command arrives as a [len][ptr] descriptor, 0x27-terminated.
| Field | Value |
|---|---|
| Evidence | Live capture from NC: the three commands decode as 'NC-A', 'CAT-CAT5-B', 'NC-A' only via the descriptor read; the direct read gave "". Commit 15ca5e9. NC unchanged by the fix: clean MON 0B LEAVE at instr 1902382. |
3. CAT-CAT5-B is the code generator, and it runs under nd500x.
| Field | Value |
|---|---|
| Evidence | cat-cat5-b06.dom validated under nd500x (harness nd500x/test/diag_domload.c): loads, entry 0x08000004, issues TIME/TUSED/RSIO/GSWSP/ROBJE/SETBS/RMAX/SMAX, prints its banner and "Cat-500:" prompt, then reads commands via 503B DVINST. Its strings confirm the role: "code generation : ok", "can't open CAT file", "can't map scratch file into memmory", "can't write to object file", "inline-assembler not implemented for NRF output". |
Unverified¶
- NESTED EXECUTION IS NOT IMPLEMENTED on either emulator. The handler comment states it plainly: "Command execution (nested subsystem invocation, e.g. the CAT-500 back-end "CAT-CAT5-B") is not yet performed here".
- The nd500x registry marks this call MON_STATUS_VALIDATED. That status is about DISPATCH REGISTRATION, not about the call doing its work - it is a stub. Do not read the registry status as a correctness claim.
- The UECOM worker body IS carved (050701B-050725B) but was not decoded for this note, so what SINTRAN actually does with the command - and what it returns - is unread.
- The manual's 35-character command limit (per the nd500x registry parameter text) is not enforced; the handler reads up to 256 bytes.
- The manual warnings "some commands may destroy your program" and "some commands have output ... displayed on the terminal" have no emulator analogue.
Sources¶
1. NDInsight/tools/sintran-segment-carver/versions/L-VSX-500/re/mon-analysis/317B-ExecuteCommand/README.md
| Field | Value |
|---|---|
| Note | MCTAB[317B] = UECOM = 050701B. This folder is the canonical reference for the corrected MCTAB dispatch model (cross-referenced by every other call''s CORRECTED header). |
2. nd500x/docs/CAT500_UECOM_CSHARP_HANDOFF.md
| Field | Value |
|---|---|
| Note | Part A - why BOUT.NRF was 0 bytes; the VDM front-end/back-end architecture. |
3. ND-60.050.06 SINTRAN III Users Guide
| Field | Value |
|---|---|
| Note | Line 1563 - command abbreviation: "-" separates parts, each abbreviated if unambiguous. |
Source¶
SINTRAN III Monitor Calls (ND-860228.2 EN), page 181.