Create Forward Message - OMMSCRT

Create Forward Message (OMMSCRT)

Required Parameter Group:

1	Function Code	Input	Char(1)
2	Global Message Handle	Input	Packed(9,0)
3	Destination Entity	Input	Char(11)
4	Macro Number	Input	Packed(3,0)
5	Return F-Key Pressed	Output	Char(2)
6	Return Status	Output	Char(1)

API Overview:
The Create Forward Message API (OMMSCRT) provides the means to display the appropriate forward message creation menu to the user. The user may fill in the fields within the message and send the message to its destination.

Required Parameter Group Details:
(1) Function Code
INPUT; CHAR(1)
This parameter is a function code that instructs the API what action to perform. Valid values are:

C	Create a new message
F	Forward an existing message
S	Resend an existing message
R	Reply-to an exiting message

After the successful send of a message, if the function code is 'C' then the destination field is cleared and the screen remains as-is. If the function code is not 'C', then after a successful send of a message the API exits and control returns to the calling program.

(2) Global Message Handle
INPUT; PACKED(9,0)
This parameter must contain the unique global message handle of the existing message. This must be zero if the function code is 'C'.

(3) Destination Entity
INPUT; CHAR (11)
This parameter must contain a valid QTRACS destination entity. This field may be blank. If it is not blank and the entity is valid, then the destination field is protected on the screen and the user is prohibited from modifying it.
Valid destinations are users, vehicles, address lists, or groups. The special constants '*ALLVEH' and '*ALLUSR' are valid if the sender has authority to send to all users and all vehicles. The sender is not a valid destination. Indirect addressing is indicated with a leading '@', otherwise all destinations are left-justified and right-filled with blanks.

(4) Macro Number
INPUT; PACKED(3,0)
This parameter must contain a valid forward macro number. If zero, then it's free-form.

(5) Return F-Key Pressed
OUTPUT; CHAR (2)
This parameter returns the function key that was pressed to exit the API screen.

00	Forced exit (after a successful send of message when function code is 'F', 'R', or 'S')
03	F3 (exit) was pressed
12	F12 (cancel) was pressed

(6) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:

0	Success, at least 1 message was sent
1	Success, but no messages were sent
2	Failure, invalid function code
3	Failure, invalid global message handle
4	Failure, invalid message requester
5	Failure, invalid message destination
6	Failure, invalid macro number
7	Failure, internal error occurred (opening file, etc.)
8	Failure, invalid message status for function code of 'F' or 'S'
9	Failure, cannot resend message which has an embedded forwarded message

Effect
The function code determines the logic for the validation of the input parameters.
For function code ' C ', create, validation is as follows:

If destination is non-blank, it is validated and the field is protected (it is not input-capable)
If macro number is non-zero, then it is validated. If it is zero then it is assumed to be free-form. If valid then the corresponding template is displayed.
All other input parameters are ignored.

For function code ' F ', forward, validation is as follows:

Global Message Handle must be valid and the message which it points to must be TO the sender.
Status of message pointed to by GMH must not be,

"1065" unknown macro
"1066" macro version skew
"1521" illegal macro definition

If destination is non-blank, it is validated and the field is protected
Macro number input field is ignored; all forwarded messages are freeform. The message to be forwarded will be displayed on the screen to the right of the freeform template.

For function code ' S ', resend, validation is as follows:

Global Message Handle must be valid.
Status of message pointed to by Global Message Handle must not be,

"1065" unknown macro
"1066" macro version skew
"1521" illegal macro definition

It is invalid to resend a message which contains a previously forwarded message. This validation prevents someone from modifying a message which originated from someone other than the sender.
If destination is non-blank, it is validated and the field is protected
Macro number input field is ignored; the macro number is set to the macro number of the message pointed to by the input Global Message Handle. The message which is to be resent will be displayed on the screen. The contents of the message may be altered.

For function code ' R ', reply-to, validation is as follows:

Global Message Handle must be valid and the message which it points to must be TO the sender. The source of the message must not be an application.
Status of message pointed to by Global Message Handle must not be,

"1065" unknown macro
"1066" macro version skew
"1521" illegal macro definition

The destination field is set to the sender of the message being replied-to. The destination field is protected.
Macro number input field is validated. The corresponding forward macro template is displayed.