Chapter 1. General PSYX information
After a PSYX is loaded into memory, the first message it receives is thepInitialize(== 'INIT')
pInitialize message. A PSYX receiving this message should perform all one-time initializations. The pInitialize message will be sent to a PSYX only once, even if the PSYX is called by multiple names.
The pInitialize message is sent a version number, in the short second parameter of main(). This parameter tells the PSYX what version of the PSYX initialize routine is being used. For version 1, implented with PsyScope 1.1b4, the msgData parameter points to a structure as defined below.
typedef struct {
long *tables;
long a4;
} InitializeStruct;
The tables field should be passed to the InitAllTables() function (defined in "StdJumpTable.c"; see "1.5.1 .h and .c Files"). This will set up dynamic function links so that the PSYX can call routines defined in the main application.
The a4 field should be filled in with the PSYXs A4 value, which can be retrieved using the function GetRegisterA4(). This will allow the PSYX Manager to properly create glue code to set up the A4 register for future PSYX messages.
Note: At the time of this writing, it is recommended, but not necessary, to fill in theWith versions of Psyscope before 1.1b4, the version number passed fora4parameter when compiling PSYXs using MPW or THINK C. If left nil, PsyScope will properly assume that the A4 value is the starting address of the code resource. This won't work with Metrowerks Codewarrior, however.
pInitialize was 0. For these versions, the msgData parameter does not point to an InitializeStruct parameter block, and should be passed directly to InitAllTables(). No method for passing back the A4 value is provided with intialize version 0.
Acceptance of the pInitialize message is required for a PSYX to be loaded.
When a PSYX is called for the first time (by a particular name), it receives is thepGetFuncTable(== 'FUNC')
pGetFuncTable message. The msgData parameter is the address of a CodeFuncPair pointer; this pointer should be changed to point to the PSYX's message table, an array of CodeFuncPair records (see "1.3.3 Message tables"). The message table array should be terminated with a record containing 0 for the message code.
typedef struct {
long msgCode;
void *Func; /* (function pointer) */
} CodeFuncPair;
This message can be ignored by a PSYX if it does not have a message table. (Note that certain classes, however, require message tables.)
The Toolbox Utility CreateFunctionTable() may be useful for defining a message table. See "11.1.2 Message Handling".
Before the PSYX is unloaded (which may happen for various reasons), it is sent thepDeinitialize(== 'DINI')
pDeinitialize message. All data structures still allocated by the PSYX should be freed at this time, and non-main segments of a multi-segment PSYX should be purged. A PSYX will be sent only one pDeinitialize message, even if it was called by multiple names.
The PSYX code resource (and thus its globals) will be purged from memory on return from this message, unless the message is not accepted (i.e. the PSYX returns 0 from main()).
ThepGetMsgCode(== 'SMSG')
pGetMsgCode message is used to transform a string message ID into a standard four-character message ID. The string form of a particular message ID -- and even whether one exists or not -- is determined completely by a receiving PSYX; a PSYX is allowed to convert a string message ID into any four-character ID, as long as the PSYX is consistent and it accepts any four-character ID that it generates.
The msgData parameter is the address of a GetMsgCodeStruct record, which contains a string pointer and a message type; the PSYX should read the string and set the message type. If the PSYX does not recognize the message string, it should set msgCode to 0 and/or return FALSE.
typedef struct {
char *string;
long msgCode;
} GetMsgCodeStruct;
When a PSYX receives a pGetMsgCode message, it is not being asked to perform the message designated by the string, only convert it to a message type which can then be passed back to the PSYX (with its parameters) for execution of the message.
The pGetMsgCode message is used most often with DCODs and XRESs, to convert messages as they appear in the script to four-character message IDs. With DCODs, string messages are often used as a way to accept modifier flags; it might be difficult, in such a case, to define a message type for every acceptable permutation of the flags. A pair of message utilities that help overcome this problem are described in "2.1.1 Message Utility".
Generated with CERN WebMaker