Differences

This shows you the differences between two versions of the page.

--- en:docs:mvm:api:1 [2026/03/20 02:36] – prokushev
+++ en:docs:mvm:api:1 [2026/03/20 03:11] (current) – prokushev
@@ Line 1: / Line 1: @@
 ====== SVC_ERROREXIT ======
-Terminate MVM with an error message. This call displays a message and then terminates the current MVM session.
+===== Brief =====
-===== Parameters =====
+Terminate MVM with error message (far pointer to ASCIIZ message on stack)
-^ Register ^ Description ^
+===== Input =====
-| Stack (top) | Far pointer (segment:offset) to an ASCIIZ message string. The message is displayed by the host system before termination. |
-===== Return Value =====
+  * Stack (top) = far pointer (segment:offset) to an ASCIIZ message string
-This function does not return; it terminates the MVM.
+===== Return =====
-===== Description =====
+This function does not return. The MVM is terminated and control passes to the host operating system.
-**SVC_ERROREXIT** provides a way to terminate the MVM (Multiple Virtual DOS Machine) with a user‑supplied error message. It is specific to the OS/2 MVDM environment and has no direct equivalent in DOS INT 21h (the closest is AH=4Ch, which terminates without a message).
+===== Notes =====
-Before invoking the call, the far pointer (segment and offset) of a null‑terminated ASCII string must be pushed onto the stack. The host system (OS/2) will display the message and then terminate the virtual machine.
+  * The message must be a null‑terminated ASCII string.
+  * The far pointer must be pushed onto the stack (segment first, then offset) before issuing the HLT instruction.
+  * Because the call never returns, no registers are preserved and the carry flag is undefined.
-The low‑level instruction sequence generated for this SVC is:
+===== Binding =====
-  HLT
+====MASM ====
-  DB  1          ; function code
-  DB  NOT 1      ; complement of function code (for validation)
-===== Example =====
-The following example shows how to terminate with an error message using assembly language:
 <code asm>
-   push ds
+include macrolib.inc
-   push offset msg
-   hlt
+    push ds
-   db  1
+    push offset msg
-   db  not 1
+    @SvcErrorExit
 msg db "Fatal error",0
 </code>
-In a high‑level language (e.g., C with inline assembly), you could use a helper macro:
+==== C ====
 <code c>
-#define SvcErrorExit(msg) \
+#include <svc.h>
-    __asm { \
-        push ds \
+void main(void) {
-        push offset msg \
+    SvcErrorExit("Fatal error");
-        hlt \
+}
-        _emit 1 \
-        _emit ~1 \
-    }
 </code>
-===== Notes =====
+The underlying pragma is defined as:
-* The message string must be in the ASCIIZ format (zero‑terminated).
+<code c>
-* After this call, the MVM is terminated and control returns to the host operating system.
+extern void SvcErrorExit(const char far *msg);
-* Because the call never returns, no register values are preserved.
+#pragma aux SvcErrorExit = \
+    "hlt"           \
+    "db  1"         \
+    "db  NOT 1"     \
+    parm caller [] [msg] \
+    modify [ax bx cx dx];
+</code>
-===== See Also =====
+===== See also =====
-* [[en:docs:mvm:api:2|SVC_EXIT]] – terminate without a message.
+  * [[en:docs:mvm:api:2|SVC_EXIT]] – terminate without a message
-* [[en:docs:mvm:api:0|SVC_DUPHANDLE]] – duplicate handle.
+  * [[en:docs:dos:api:int21:4c|INT 21h AH=4Ch]] – DOS terminate with return code
-* [[en:docs:dos:api:int21:4c|INT 21h AH=4Ch]] – DOS terminate with return code.
 {{page>en:templates:svcapi}}