Daylight v4.9
Release Date: 1 February 2008

Name

dt_setmessage - notify users of a Thor or Merlin database

Generic Prototype

dt_setmessage(dt_Handle, dt_String, dt_Integer, dt_String) => dt_Boolean

C Prototype

#include "dt_thor.h"

dt_Boolean dt_setmessage(dt_Handle object, dt_Integer alen, dt_String auth_pw, dt_Integer when, dt_Handle message)

FORTRAN Prototype

include 'dt_f_thor.inc'

logical dt_f_setmessage(object, auth_pw, when, message)

integer*4 object
character*() auth_pw
integer*4 when
character*() message

Description

"Broadcasts" a message to all users of 'object', where 'object' is a Thor or Merlin server or database. The message is sent to all users of the server or database as one or more "NOTE" entries in the client's error queue (see dt_errors(3)).

The string 'auth_pw' is a password to authorize the message. If the object is a Thor or Merlin server, then the password must match that of the user "thor". If the object is a database, then the password must match the executive password for the database.

The parameter 'when' indicates when the message is to be broadcast. For a Merlin database, only DX_MESSAGE_NOW is allowed. For Thor servers, Merlin servers and Thor databases, 'when' can be one of:

DX_MESSAGE_NOW

Send the message immediately to all users. The message is a "one time" message, and is not recorded anywhere.
DX_MESSAGE_RECORD
Record the message (attach it to the database or server), then send the message to each client that uses the object. For server objects, the message is sent when a user connects to the server. For database objects, the message is sent when the database is opened. The message remains in effect until another message replaces it.
DX_MESSAGE_FILE
Like DX_MESSAGE_RECORD, but the object 'message' specifies a file on the Thor or Merlin server host's file system; the file's contents become the message. This allows a particular message to be shared among several servers or databases.
DX_MESSAGE_NONE
Erases any message associated with the object. This is the same as setting a message whose length is zero. The object 'message' is ignored.
The object 'message' contains a message. It can be any object that responds to dt_stringvalue(3), or a sequence or stream of such objects. If the object is not a stream or sequence, then its stringvalue is the message that is sent as a single "NOTE:" in the error queue. If it is a sequence or stream, each object it contains will be a separate "NOTE:" in the error queue. If an object returns the 'invalid string', it is replaced by a string of length zero (""). If 'message' is a sequence or stream, it is reset (see dt_reset(3)). If 'message' is NULL_OB, then no message is sent.

Return Value

Returns TRUE if the operation was successful, or FALSE if an error was encountered (for example if the password is incorrect).

Related Topics

dt_alloc_seq(3) dt_errorclear(3) dt_errors(3) dt_errorworst(3) dt_mer_server(3) dt_open(3) dt_stream(3) dt_stringvalue(3) dt_thor_server(3)

thorserver(1) (THOR_SERVER_MESSAGE, MERLIN_SERVER_MESSAGE) option also sets the message on startup.

Bugs

It is up to the Thor/Merlin client programs to report the messages. Clients use different strategies to report errors, so there is no guarantee that the message will be delivered promptly, if at all.

The Toolkit's error queue is limited to approximately 20 messages, each of which is limited to approximately 500 bytes. Generally speaking, messages messages should be limited to a few lines, and lines should be fairly short. Because the 10-character string " NOTE:" is prepended to each line of the message, lines should normally be limited to about 70 characters so that they will fit in a typical 80-character display device.