Using Message Tokens
The remaining parameters passed to the RPErrorProc or RPLogProc functions are variables which represent token-data pairs used to define the content of the message.
In this example, there are two pairs of token-data.
RPErrorProc(pRPS, (WORD)EMIT_WARNING, (DWORD)10012,
"OutBuff", pRPS->OutBuff,
"Image", IMAGENAME(pRPS->CurrentFapImageH),
LASTERRORTOKEN);
Token |
Description |
Represents a token name. The data for that token is defined in pRPS->OutBuff. |
|
A second token name, with appropriate data text following. Token and data must be character text. Therefore, if the data to be represented is anything other than text, it must be converted before you call the message function. |
|
Not really a single token, but rather is a macro that contains several token-data pairs. These pairs identify the source module name and the line number of the statement being compiled. The last component of LASTERRORTOKEN is a NULL pointer used by the internal message formatter to recognize the end of the Token-Data pairs. LASTERRORTOKEN must be the last variable passed to both the RPErrorProc and RPLogProc functions. |
There are several points to remember about tokens which will become apparent as you examine the TRANSLAT.INI file—the file that contains the rest of the message text.
The message text from the TRANSLAT.INI file does not have to use all, or for that matter any, of the tokens output from a particular function. This means you can output more information (in token-data format) than would normally be required in the message. This information, however, might prove useful to a programmer during closer examination of the message file.
Token names live forever. This means that a token logged earlier in the session can be referenced by messages that occur later. For instance, if an early message outputs a token (with a value) named ID, any message text translated after that point may refer to ID and receive that same value.
Token names are reusable. You should reuse token names whenever it makes sense. For instance, each time a function is required to emit the section (image) name, use the same token name. This conserves space in the token list (because a new entry does not have to be created) and if subsequent messages rely upon the last known value of a given token, it is more likely to be correct.
Tokens are not case sensitive. A token named Image can be referred to as IMAGE, Image, image, ImageE, and so on.
Also note, that the example refers to one-word tokens. Although, this is the most efficient use of space, tokens can be longer and include spaces. The only character you cannot use in a token is the ampersand (&)—ampersands are used in defining the static message text. For instance, you can define a token such as One A Day, but you cannot define a token such as Will Not&Work.
Note | Legacy systems expected the fourth parameter to be a string representing a format. This format string might be the complete message or contain flags indicating where subsequent variables will be substituted—such as %d, %s, %X, and so on. The RPErrorProc or RPLogProc functions distinguish how these remaining parameters are handled (legacy or new) by first determining if the Message Type and Message Number parameters are values expected by the new functionality. The new use of the functions does not require a format string. Instead, the variables represent token-data pairs until the LASTERRORTOKEN is encountered. |