Message.mesa
Copyright (C) 1982, 1983, 1984, 1985, 1986 by Xerox Corporation. All rights reserved.
Revised by: McManis 29-Apr-85 15:49:30
Revised by: Balcon  9-Apr-85 9:49:31
Tim Diebert: October 28, 1986 12:19:56 pm PST
<< Overview:
This interface allows Services existing before Services 10.0 to access messages stored in a message file. The messages are stored as string bodies. The NSStrings that are returned by the Get and GetList operations use the actual pointers to these messages and should not be deallocated.
Some of the messages stored in the message file are actually message "templates" which have fields called "diamonds" that need to be replaced with the appropriate arguments. An example of a message containing diamonds is "This <1> cannot be <2>." Possible arguments for <1> would be "file drawer" and "folder". The Expand operation is used to form the desired message, given the message template and an array containing the required number of arguments. The array of string arguments should be arranged in an order corresponding to the diamonds they replace, i.e. <1> will be replaced with array[0], <2> with array[1], etc.
The NSStrings that are returned by the GetTime and Expand operations should be deallocated by the client when they are no longer needed. NSString.FreeString should be used to free the strings with the client zone as the zone parameter, or Heap.systemZone if the client used the default zone.
Clients are responsible for providing the message data via the SetMessages operation. Calls to SetMessages will be ignored if a message file is available, but clients should ALWAYS include their call to SetMessages in their respective start-up routines. There should be only one SetMessages invocation for each Service.
Services which have called SetMessages should call UnloadMessages when they are unloaded to deallocate all space allocated by the message facilities. >>
DIRECTORY
NSString USING [String],
Rope USING [ROPE],
XMessage USING [MsgID, MsgType];
Message: CEDAR DEFINITIONS = BEGIN
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
TYPES:
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
Services: TYPE = -- One for each range of messages, used by Message/XMessage layering implementation
{
scs, -- Services Common Software
chs, -- Clearinghouse Service
ecs, -- External Commmunication Service
fs, -- File Service
gws, -- Gateway Service
irs, -- Internetwork Router Service
its, -- Interactive Terminal Service
ps, -- Print Service
ms, -- Mail Service
mch, -- MCH common
rbs, -- Remote Batch Service
svm, -- Server Monitor
grtr, -- TTY Greeter
cmsv, -- Communication Services Area
distr, -- Distributed Services area
basic, --Basic Services area
rxdev}; -- Rank Xerox development
Msgkey: TYPE = CARDINAL;
MsgkeyList: TYPE = RECORD [ data: SEQUENCE length: CARDINAL OF Msgkey];
StringArray: TYPE = RECORD [ data: SEQUENCE length: CARDINAL OF NSString.String];
Messages: TYPE = RECORD [ data: SEQUENCE length: CARDINAL OF MsgEntry];
The following is derived from XMessage.MsgEntry
MsgEntry: TYPE = RECORD [
msgKey: Msgkey, -- runtime mesage access handle
msg: NSString.String, -- message body
translationNote: NSString.String ← NIL, -- special instructions to the translators
translatable: BOOLEAN ← TRUE, -- IF FALSE do not translate
type: XMessage.MsgType ← userMsg, -- assertion as to who the client is
id: XMessage.MsgID]; -- unique handle for the life time of message];
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
SIGNALS, ERRORS:
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
Error: ERROR [type: ErrorType];
ErrorType: TYPE = {arrayMismatch, invalidMsgkeyList, invalidStringArray, invalidString,
notEnoughArguments};
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
OPERATIONS:
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
Operations for obtaining messages:
Get: PROCEDURE [msgkey: Msgkey] RETURNS [msg: NSString.String];
Returns message corresponding to the given msgkey.
GetList: PROCEDURE [msgkeys: REF MsgkeyList, msgs: REF StringArray];
Fills the client-supplied array with the requested messages.
GetTime: PROCEDURE [] RETURNS [msg: NSString.String];
Returns time of day message. Storage for msg is allocated from z. The client is responsible for deallocating the string with NSString.FreeString.
Inserts arguments into a message template:
Expand: PROCEDURE [source: NSString.String, args: REF StringArray]
RETURNS [msg: NSString.String];
Returns a message consisting of the given template and inserted arguments. Allocates necessary storage from z. The client is responsible for deallocating the string with NSString.FreeString.
Start-up Operations:
SetMsgfile: PROCEDURE [file: Rope.ROPE, offset: CARDINAL ← 0];
Tells the implementation where to look for the message file. A page offset parameter is provided in case the client wants to use an NSFile.
NOTE: SetMsgfile is now obsolete. Clients who need to use a message file should use XMessage.
SetMessages: PROCEDURE [messages: REF Messages];
Initializes a set of messages. If a message file is available, then the messages are taken from that file and "messages" are ignored. Otherwise "messages" becomes the client's runtime messages.
Unload operations
UnloadMessages: PROCEDURE [service: Services];
Unload the messages when the Service who are clients of this interface are unloaded.
END. -- of Message
LOG ( time - person - action )
21-Jan-82 12:11:36 - CKabcenell - Created.
1-Feb-82 10:32:28 - CKabcenell - Redefined Messages TYPE.
12-Feb-82 17:25:51 - CKabcenell - Redefined SetMsgfile.
9-Jun-82 10:08:07 - CKabcenell - Converted to Filing 5.0.
- - - - Services 8.0 - - - -
2-Aug-83 10:07:06 - Ciccone - Replaced File.Capability with File.File for Klamath.
27-Oct-83 15:59:49 - McManis - Added zone parameter to Expand and GetTime
- - - - Services 10.0 - - - -
9-Apr-85 9:37:04 - Balcon - Added XMessage required changes, redefined MsgEntry, redefined SetMsgfile, added UnloadMessages
29-Apr-85 15:49:27 - McManis - Changed SetMsgfile back to previous definition. Fixed up comments.