Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-FileDbmsg()                                                               XBIOS

Syntax

VOID Dbmsg( rsrvd, msg_num, msg_arg )
WORD rsrvd, msg_num;
LONG msg_arg;

Function      Dbmsg() allows special debugging messages to be sent to
              a resident debugger application.

Opcode        11 (0x0B)

Availability  The only debugger that currently supports this call is the
              Atari Debugger.

Parameters    rsrvd is currently reserved and should always be 5.
              msg_num is the message number which you want to send to the
              debugging host. Values of 0x0000 to 0xEFFF are reserved for
              applications to define. Values of 0xF000 to 0xFFFF are
              reserved for special debugging messages. If msg_num is in
              the application defined range, it and the LONG contained in
              msg_arg will be displayed by the debugger and the
              application will be halted. If msg_num is between 0xF001 and
              0xF0FF inclusive then msg_arg is interpreted as a character
              pointer pointing to a string to be output by the debugger
              and debugging to halt. The string length is determined by
              the low byte of msg_num. If msg_num is DB_NULLSTRING
              (0xF000), the string will be output until a NULL is
              reached. If msg_num is DB_COMMAND (0xF100), msg_arg is
              interpreted as a character pointer to a string containing
              a debugger command. The command format is specific to the
              debugger which you are running. A useful example of this
              format when running under the Atari debugger allows a string
              to be output to the debugger without terminating debugging
              as shown in the following example:

              Dbmsg( 5, DB_COMMAND, "echo 'Debugging Message';g" );

Binding       move.l   msg_arg,-(sp)
              move.w   msg_num,-(sp)
              move.w   #$5,-(sp)
              move.w   #$0B,-(sp)
              trap     #14
              lea      10(sp),sp

Comments      The Atari Debugger only understands the value DB_COMMAND
              (0xF100) for msg_num as of version 3. Though it is normally
              harmless to run an application with embedded debugging
              messages when no debugger is present in the system,
              distribution versions of applications should have these
              instructions removed.