Apple IIgs #89
MessageByName -- Catchy Messages

Written by Dan Strnad & Dave Lyons (September 1990)

This note clarifies MessageByName and provides examples of creating and retrieving a named message.


Did You Say You Want To Get A Message?

All you have to do is ask. Apple IIgs Toolbox Reference, Volume 3 already tells you how. Here's what the fine print says: with the createItFlag set to FALSE and the name of the message you are after in the nameString, you call MessageByName. What's unclear in the manual is that if the message was found, no error is returned, the createFlag is returned as FALSE, and messageID contains the ID you can pass to MessageCenter to retrieve the contents of the message. Here's an example of MessageByName in use.

The following code creates a named message.


CreateNamedMessage
            pha
            pha
            pea 1                                     ;create it
            pushlong #MsgBlock
            _MessageByName                            ;function $1701
            pla
            sta myMsgID                               ;keep the ID if you want
            pla                                       ;check the createFlag if 
;                                                      you want
            ...

MsgBlock    dc.w MsgBlockEnd-MsgBlock
            dc.b 28,'XYZ Software:My Cool Product'    ;Pascal-style string
            ... more data goes here
MsgBlockEnd

The following code retrieves the message.


            pha
            pha
            pea 0                                     ;don't create message
            pushlong #MsgBlock
            _MessageByName                            ;function $1701
            ply                                       ;keep id of existing 
;                                                      message
            pla                                       ;createFlag (ignore)
            bcs noMessage                             ;carry set if an error 
;                                                      occurred


            pea 2                                     ;MessageCenter action:GET
            phy                                       ;message ID for 
;                                                      MessageCenter, below
            pha
            pha                                       ;space for NewHandle 
;                                                      result
            lda #0                                    ;size of handle (0)
            pha
            pha
            ldx MyID                                  ;ID for empty
            phx
            pha                                       ;handle attributes (0)
            pha
            pha                                       ;no special location
            _NewHandle
            lda 3,s
            sta mcHandle+2
            lda 1,s
            sta mcHandle                              ;keep a copy of the 
;                                                      handle for later
            _MessageCenter                            ;takes Action, Msg ID, 
;                                                      and Handle

            lda mcHandle+2
            pha
            lda mcHandle
            pha
            phd
            tsc
            tcd
            ldy #2
            lda [3],y
            tax
            lda [3]
            sta 3
            stx 5

* now read data from the message at [3]
            ldy #$xxxx                                ;index past the name 
;                                                      string
            lda [3],y
            ...
            pld
            pla
            pla
            
            lda mcHandle+2
            pha
            lda mcHandle
            pha
            _DisposeHandle

noMessage   ...

mcHandle    dc.l 0
myMsgID     dc.w 0

MessageByName is available in Tool Locator versions 3.0 and later (System Software 5.0 and later).

Further Reference


This and all of the other Apple II Technical Notes have been converted to HTML by Aaron Heiss as a public service to the Apple II community, with permission by Apple Computer, Inc. Any and all trademarks, registered and otherwise, are properties of their owners.