Print Page as PDF
MESSAGE EDIT API ICR (2730)

MESSAGE EDIT API    ICR (2730)

Name Value
NUMBER 2730
IA # 2730
DATE CREATED 1999/01/27
CUSTODIAL PACKAGE MAILMAN
CUSTODIAL ISC San Francisco
USAGE Supported
TYPE Routine
DBIC APPROVAL STATUS APPROVED
ROUTINE XMXEDIT
NAME MESSAGE EDIT API
GENERAL DESCRIPTION 
These APIs are intended for use by MailMan front ends.
They edit different parts of a message.  They may only be used by the message
sender, and, with the exception of INFO^XMXEDIT, may only be used before the
message has been sent to anyone besides the sender.  The APIs do not contain
any checks to ensure that it was appropriate to call them.  That is the
responsibility of the calling routine.

For these APIs, it is expected that:

INIT^XMVVITAE   has been called to set up the user's XMV array, with vital
user information, user preferences, and, if the user is a surrogate, determine
level of authorization.  See DBIA 2728 for information on INIT^XMVVITAE.

The calling routine has determined that the user is authorized to see the
message.  If the message is in the user's mailbox, then that's enough.
Otherwise, $$ACCESS^XMXSEC should be used to determine authorization.  See
DBIA 2731 for information on $$ACCESS^XMXSEC.

OPTMSG^XMXSEC2  has been called and has given its permission to edit the
message or to toggle information only.  (Note:  $$EDIT^XMXSEC2 will also let
you know whether the user may edit the message.) See DBIA 2733 for information
on OPTMSG^XMXSEC2A and $$EDIT^XMXSEC2.

OPTEDIT^XMXSEC2 has been called and has given its permission to edit the
particular thing we are editing here.  See DBIA 2733 for information on
OPTEDIT^XMXSEC2.

INMSG2^XMXUTIL2 has been called to set XMINSTR.  These routines expect that
XMINSTR has been correctly set.  They will change XMINSTR according to the
item being edited.  See DBIA 2736 for information on INMSG2^XMXUTIL2.
STATUS Active
ID XMXEDIT
COMPONENT/ENTRY POINT
COMPONENT/ENTRY POINT COMPONENT DESCRIPTION VARIABLES
CLOSED 
Toggle a message's 'closed' flag.  The flag is
toggled in field 1.95 of the message in the Message file, as well as in the
parameter XMINSTR("FLAGS").  See the general description for important
information.

When a message is closed, it may not be forwarded by anyone, except the person
who sent it.

Note that messages addressed to SHARED,MAIL may not be closed.  If a message
is in the process of being addressed to SHARED, MAIL, and this API is called,
XMERR and ^TMP("XMERR",$J) will be set.  The calling routine should always
check for $D(XMERR) after calling this API.

Usage: D CLOSED^XMXEDIT(XMZ,.XMINSTR,.XMMSG)
VARIABLES TYPE VARIABLES DESCRIPTION
XMZ Input 
Message IEN in the MESSAGE file.
XMINSTR Both 
If the message is closed (XMINSTR("FLAGS")["X"), then
make the message not closed:
- Delete field 1.95 of the message in the Message file.
- Remove the "X" from XMINSTR("FLAGS").

If the message is not closed (XMINSTR("FLAGS")'["X"), then make the message
closed:
- Set field 1.95 of the message in the Message file.
- Append an "X" to XMINSTR("FLAGS").
XMMSG Output 
An appropriate message, suitable for display to the
user.

Either "'Closed' flag removed" or "Message flagged 'Closed'".
CONFID 
Toggle a message's 'confidential' flag.  The flag is
toggled in field 1.96 in the Message file, as well as in the parameter
XMINSTR("FLAGS").  See the general description for important information.

When a message is confidential, it may not be read by a surrogate.

Note that messages addressed to SHARED,MAIL may not be confidential.  If a
message is in the process of being addressed to SHARED, MAIL, and this API is
called, XMERR and ^TMP("XMERR",$J) will be set.  The calling routine should
always check for $D(XMERR) after calling this API.

Usage: D CONFID^XMXEDIT(XMZ,.XMINSTR,.XMMSG)
VARIABLES TYPE VARIABLES DESCRIPTION
XMMSG Output 
An appropriate message, suitable for display to the
user.

Either "'Confidential' flag removed" or "Message flagged 'Confidential'".
XMINSTR Both 
If the message is confidential
(XMINSTR("FLAGS")["C"), then make the message not confidential:
- Delete field 1.96 of the message in the Message file.
- Remove the "C" from XMINSTR("FLAGS").

If the message is not confidential (XMINSTR("FLAGS")'["C"), then make the
message confidential:
- Set field 1.96 of the message in the Message file.
- Append a "C" to XMINSTR("FLAGS").
XMZ Input 
Message IEN in the MESSAGE file.
CONFIRM 
Toggle a message's 'confirm receipt requested' flag.
The flag is toggled in field 1.3 of the message in the Message file, as well
as in the parameter XMINSTR("FLAGS").  See the general description for
important information.

When a message is flagged 'confirm receipt requested', the first time each
recipient reads the message, a message will be sent to the sender of the
message informing the sender that the recipient has seen the message.

Usage: D CONFIRM^XMXEDIT(XMZ,.XMINSTR,.XMMSG)
VARIABLES TYPE VARIABLES DESCRIPTION
XMZ Input 
Message IEN in the MESSAGE file.
XMINSTR Both 
If the message is 'confirm receipt requested'
(XMINSTR("FLAGS")["R"), then make the message not 'confirm receipt requested':
- Delete field 1.3 of the message in the Message file.
- Remove the "R" from XMINSTR("FLAGS").

If the message is not 'confirm receipt requested' (XMINSTR("FLAGS")'["R"),
then make the message 'confirm receipt requested':
- Set field 1.3 of the message in the Message file.
- Append an "R" to XMINSTR("FLAGS").
XMMSG Output 
An appropriate message, suitable for display to the
user.

Either "'Confirm Receipt Requested' flag removed"

or "Message flagged 'Confirm Receipt Requested'".
DELIVER 
Set or delete a message's 'delivery basket' in field
21 of the message in the Message file, as well as in the parameter
XMINSTR("RCPT BSKT").  See the general description for important information.

When a message specifies a delivery basket, it will be delivered to that
basket for each recipient, as long as the recipient has allowed such targeted
delivery (by so indicating under User Preferences).  If the recipient does not
allow such targeted delivery, then the message is delivered as usual.

Usage: D DELIVER^XMXEDIT(XMZ,BASKET,.XMINSTR,.XMMSG)
VARIABLES TYPE VARIABLES DESCRIPTION
XMZ Input 
Message IEN in the MESSAGE file.
BASKET Input 
Full name of the basket to which the message should
be delivered.  It must be a valid basket name.  (Free text, 2-30 characters.)
This API does not check to ensure that the basket name is valid.  That is the
responsibility of the calling routine.

If BASKET="@", field 21 of the message in the Message file is deleted, and
XMINSTR("RCPT BSKT") is killed.

Otherwise, field 21 of the message in the Message file and XMINSTR("RCPT
BSKT") are set to BASKET.
XMINSTR Output 
If BASKET="@", field 21 of the message in the Message
file is deleted, and XMINSTR("RCPT BSKT") is killed.

Otherwise, field 21 of the message in the Message file and XMINSTR("RCPT
BSKT") are set to BASKET.
XMMSG Output 
An appropriate message, suitable for display to the
user.

Either "Delivery basket set" or "Delivery basket removed".
INFO 
Toggle a message's 'Information only' flag. The flag
is toggled in field 1.97 of the message in the Message file, as well as in the
parameter XMINSTR("FLAGS").  See the general description for important
information.

When a message is flagged 'Information only', no one may reply to the message,
except for the sender.

Note that unlike the other APIs in this DBIA, this API may be used by the
sender at any time to toggle the 'Information only' flag, even after the
message has been sent to other users.

Usage: D INFO^XMXEDIT(XMZ,.XMINSTR,.XMMSG)
VARIABLES TYPE VARIABLES DESCRIPTION
XMZ Input 
Message IEN in the MESSAGE file.
XMINSTR Both 
If the message is 'information only'
(XMINSTR("FLAGS")["I"), then make the message not 'information only':
- Delete field 1.97 of the message in the Message file.
- Remove the "I" from XMINSTR("FLAGS").

If the message is not 'information only' (XMINSTR("FLAGS")'["I"), then make
the message 'information only':
- Set field 1.97 of the message in the Message file.
- Append an "I" to XMINSTR("FLAGS").
XMMSG Output 
An appropriate message, suitable for display to the
user.

Either "'Information only' flag removed"

or "Message flagged 'Information only'".
PRIORITY 
Toggle a message's 'priority' flag.  The flag is
toggled in field 1.7 of the message in the Message file, as well as in the
parameter XMINSTR("FLAGS").  See the general description for important
information.

When a message is priority, it is delivered normally, but each recipient is
alerted to it at logon or when it is delivered, and, when reading new
messages, priority messages are displayed first.  In a message list, priority
messages are marked by an "!".

Usage: D PRIORITY^XMXEDIT(XMZ,.XMINSTR,.XMMSG)
VARIABLES TYPE VARIABLES DESCRIPTION
XMZ Input 
Message IEN in the MESSAGE file.
XMINSTR Both 
If the message is priority (XMINSTR("FLAGS")["P"),
then make the message not priority:
- Remove the priority indicator from field 1.7 of the message in the Message
file.  (The parameter XMINSTR("TYPE") is used here.)
- Remove the "P" from XMINSTR("FLAGS").

If the message is not priority (XMINSTR("FLAGS")'["P"), then make the message
priority:
- Add the priority indicator to field 1.7 of the message in the Message file.
(The parameter XMINSTR("TYPE") is used here.)
- Append a "P" to XMINSTR("FLAGS").
XMMSG Output 
An appropriate message, suitable for display to the
user.

Either "'Priority' flag removed" or "Message flagged 'Priority'".
SUBJ 
Change the message subject.  If the subject is null,
the subject is set to "* No Subject *".  If the subject is "* No Subject *",
and the message is sent to a remote site, the subject in the "SUBJECT:" header
record will be null.

The subject is set in field .01 of the message in the Message file, as well as
in the parameter XMIM("SUBJ").  See the general description for important
information.

Usage: D SUBJ^XMXEDIT(XMZ,XMSUBJ,.XMIM)
VARIABLES TYPE VARIABLES DESCRIPTION
XMZ Input 
Message IEN in the MESSAGE file.
XMSUBJ Input 
New subject of the message.  The subject must be
valid.  It must be 3-65 characters.  It may also be null.  It is the
responsibility of the calling routine to ensure that the subject is valid.
You may use the API VSUBJ^XMXAPI (DBIA 2729) to validate a subject.
XMIM Output 
XMIM("SUBJ") is set to the new message subject.
TEXT 
Replace the text in field 3 of the message in the
Message file.

Usage: D TEXT^XMXEDIT(XMZ,XMBODY)
VARIABLES TYPE VARIABLES DESCRIPTION
XMZ Input 
Message IEN in the MESSAGE file.
XMBODY Input 
The closed root of the array that contains the word
processing data to be filed.  The array itself must be in a format acceptable
to FileMan's WP^DIE API.  It is the responsibility of the calling routine to
ensure that the root is correctly passed in and that the array itself is
correctly formatted.  This API does not check it.
VAPOR 
Set or delete a message's 'vaporize date' in field
1.6 of the message in the Message file, as well as in the parameter
XMINSTR("VAPOR").  See the general description for important information.

When a message specifies a vaporize date, that date will be set in the Mailbox
file for each recipient in field 5 of the message record in the message
multiple of the basket to which the message is delivered as the message is
delivered to each recipient.  This holds true even when the message is
forwarded.  The vaporize date (from field 5 of the basket message multiple in
the Mailbox file) is displayed to the recipient every time the recipient reads
the message.  Each recipient is free to delete or change the vaporize date
(field 5...) of the message in his or her mailbox.  Messages with vaporize
dates in the user's mailbox are deleted from the user's mailbox when the
vaporize date arrives.

Usage: D VAPOR^XMXEDIT(XMZ,XMVAPOR,.XMINSTR,.XMMSG)

Note that this API does not edit the message vaporize date in a user's basket.
Use KVAPOR^XMXUTIL (DBIA 2734) to do that.
VARIABLES TYPE VARIABLES DESCRIPTION
XMZ Input 
Message IEN in the MESSAGE file.
XMVAPOR Input 
Vaporize date/time.  Must be in internal FileMan
format.  This API does not check to ensure that the date/time is valid.  That
is the responsibility of the calling routine.

If XMVAPOR="@", field 1.6 of the message in the Message file is deleted, and
XMINSTR("VAPOR") is killed.

Otherwise, field 1.6 of the message in the Message file and XMINSTR("VAPOR")
are set to XMVAPOR.
XMINSTR Output 
If XMVAPOR="@", field 1.6 of the message in the
Message file is deleted, and XMINSTR("VAPOR") is killed.

Otherwise, field 1.6 of the message in the Message file and XMINSTR("VAPOR")
are set to XMVAPOR.
XMMSG Output 
An appropriate message, suitable for display to the
user.

Either "Vaporize Date set" or "Vaporize Date removed".
NETSIG 
Add the user's network signature to a message.  See
the general description for important information.

This is not a toggle.  MailMan has no way of checking to see if the user's
network signature has already been added.  Everytime this API is called, the
network signature is added to the message, so if this API is called 3 times on
the same message, the network signature will be added 3 times.

Usage:  D NETSIG^XMXEDIT(XMDUZ,XMZ,.XMINSTR,.XMMSG)
VARIABLES TYPE VARIABLES DESCRIPTION
XMDUZ Input 
The user whose network signature is to be added to
the message.  This is, of course, the user who created the message.  The DUZ
suffices, or enough of the name for a positive ID.
XMZ Input 
Message IEN in the MESSAGE file.
XMINSTR Used 
If the message is not scrambled, then this variable
is ignored.

If the message is scrambled (locked with a key), then XMINSTR("SCR KEY") must
contain the scramble key.  If the key is not correct or is not supplied, then
XMERR AND ^TMP("XMERR",$J) will be set.  The calling routine should always
check for $D(XMERR) after calling this API.
XMMSG Output 
Upon successful completion of this API, this variable
contains an appropriate message, suitable for display to the user.

"Network Signature added."
SCRAMBLE 
Scramble or unscramble a message's text.  This API
works as a toggle.  If the text is scrambled, it will unscramble it.  If it's
not scrambled, it will scramble it.  See the general description for important
information.

Usage: D SCRAMBLE^XMXEDIT(XMZ,.XMINSTR,.XMMSG)
VARIABLES TYPE VARIABLES DESCRIPTION
XMZ Input 
Message IEN in the MESSAGE file.
XMINSTR Both 
If the message is scrambled, the XMINSTR("SCR KEY")
must contain the correct scramble key, otherwise XMERR and ^TMP("XMERR",$J)
will be set. The calling routine should always check for $D(XMERR) after
calling this API.  XMINSTR("SCR HINT") is ignored as input.  XMINSTR("SCR
KEY") and XMINSTR("SCR HINT") are both killed upon successful completion of
this API, and fields 1.8 and 1.85 of the message are deleted.

If the message is not scrambled, XMINSTR("SCR KEY") must contain the key with
which the message should be scrambled.  It must be 3-20 characters, and case
is ignored.  XMINSTR("SCR HINT") is shown to the user when s/he receives the
message, and is intended to be a hint to the user as to what the key might be.
If supplied, it may be no more than 40 characters.  The hint is optional.
Field 1.8 of the message is set with the hint, and field 1.85 is set with the
key.
XMMSG Output 
An appropriate message, suitable for display to the
user.

Either "Message text Scrambled" or "Message text UnScrambled".