[Next] [Previous] [Up] [Top] [Contents] [Index]

Chapter 3. XRESs

3.1 How an XRES is Called

The mere existence of an XRES is not sufficient for the XRES to be called as a function from the scripting language; one or more glue entries must be included in the script.

When a script-defined function is called, if the function entry has an "ExtResult" attribute instead of a "Result" attribute, an XRES is invoked to perform the function computation. (See PsyScope User Manual "12.9.6 Function Definitions", p344 for information on script-defined functions.) The XRES to be invoked is named in the "ExtResult" attribute. Optionally, a "Msg" sub-attribute may be defined to specify a string message for the XRES; otherwise, the 'XRES' message is sent.

A message ID for an XRES message must start with a capital "X". Thus, 'Xabc' is a valid XRES message ID, but 'xabc' or 'abcd' is not. There is no constraint on the string form of the message ID.

For example, here is how FactorAttrib() is defined:

	FactorAttrib::
		ExtResult: Factor
			Msg:> FactorAttribute
The "Factor" PSYX accepts a pGetMsgCode message to change "FactorAttribute" to 'Xfac'. When the "Factor" PSYX receives an 'Xfac' message, it knows to handle it as an XRES message and computes a value from the current factor information.

XRES message handlers must be defined in a message table. The prototype of an XRES message-handling function is:

 int Func(TokenValue **toks, int *count, int *disp, EntryRef *source);
On entry, *toks is an array containing the parameters that are being passed to the XRES, and *count is size of this array. These parameters are the tokens from the content of the script function entry which invoked the XRES (which are usually, in turn, the parameters passed into the script function call). If *disp contains a TRUE value, the input token array should be freed by the XRES. The source parameter is a reference to the script function entry which invoked the XRES.

On exit, the *toks and *count values should be the results of the XRES computation. These tokens will be passed back out as the result of calling the script function. *disp should be TRUE if the result token array should be freed by the XRES manager.

The return value of an XRES function should be TRUE for a successful computation. If there is a parameter error or some other problem, FALSE should be returned and the original parameter token list should not be freed (even if *disp is TRUE).

PSYX Programmer's Manual - 24 AUG 95
[Next] [Previous] [Up] [Top] [Contents] [Index]

Generated with CERN WebMaker