%M_SIGNAL

Signal a menu entry

status = %M_SIGNAL(entry_name, [operation], {reserved})

xcall M_SIGNAL(entry_name, [operation], {reserved})

Return value

status

If you pass D_SIGNAL (or if you omit operation), %M_SIGNAL returns true (1) if entry_name is non-blank or false (0) if it is blank. If you specify D_REMOVE, %M_SIGNAL returns true if an entry is returned or false if there is no menu entry to cancel. (^VAL)

Arguments

entry_name

The menu entry name to signal or the returned name of the canceled menu entry. (a)

operation

(optional) One of the following: (n)

D_REMOVE

Cancel the previously signaled menu entry.

D_SIGNAL

Signal a menu entry for future processing. (default)

{reserved}

Reserved for internal use. (n)

Discussion

%M_SIGNAL provides a standardized way of signaling or canceling a signaled menu entry. See Simulating a menu entry or canceling a signaled menu entry for recommendations on when to use %M_SIGNAL, and note the following:

For D_SIGNAL, %M_SIGNAL sets g_select and g_entnam. If you specify D_REMOVE, %M_SIGNAL clears g_select and sets g_entnam to the name of the canceled entry.
The D_SIGNAL operation does not call the routine that handles the signaled menu entry. It merely sets up the event to be “seen” by subsequent processing. Think of the D_SIGNAL operation as simply setting g_select and g_entnam. No other routine is called. Thus, code that follows the call to %M_SIGNAL will be executed before the code that responds to the event signaled. In the Synergy debugger, set the breakpoint in the code that responds to the event. If you break before the %M_SIGNAL call and then step over, the action signaled by the event will not have occurred yet. (If you have Windows API programming experience, the D_SIGNAL operation is more like a PostMessage than a SendMessage.)
The D_SIGNAL operation does not look at the current menu, so entry_name does not have to be on a placed menu column, and it doesn’t have to be enabled. Thus, disabling the menu entry does not prevent %M_SIGNAL from generating the associated event. The application must avoid signaling or processing the event if it is not appropriate.
As with all menu entry handling in Toolkit, the menu entry name is converted to uppercase to simplify subsequent conditional tests. However, the name passed to %M_SIGNAL is not validated as an identifier, so you can include characters that would not be legal for a menu entry, such as “@” and “#”. The usefulness of these non-menu characters is left to the creativity of the developer.
We don’t recommend calling %M_SIGNAL in list load methods. Because of the way Toolkit synchronizes menu entry signaling, Toolkit may not execute such calls.
If you signal a menu entry from and process the menu entry in a callback routine, use the D_REMOVE operation to cancel the menu entry after you’ve processed it. If you don’t, the menu entry will be resignaled when processing returns from the callback routine.
The menu entries E_CLEAR, E_COPY, E_CUT, E_MARK, and E_PASTE immediately perform their associated actions. %M_SIGNAL honors and dispatches these entries and sets g_select to 0, though status is returned as true.
We recommend that you do not pass g_entnam as entry_name. G_entnam may be modified within this routine.
As of version 8.3.1a, the Synergy DBL ACCEPT statement and the WD_ACCEPT subfunction to W_DISP no longer drop characters that are rapidly typed ahead by the user. If you create a custom ActiveX control, be sure not to call %M_SIGNAL in an event triggered by a “key down” (WM_KEYDOWN) message for a key that will be translated into a character. Instead, do this in response to a “key press” (WM_CHAR) message, to avoid duplicating the keystroke in type-ahead.

See also

Signaling a menu entry from a method

Examples

The following example, which is a change method, uses the “CUST_OK” menu entry to indicate whether a customer account could be found. The first call to %M_SIGNAL, which is in the read_customer subroutine, signals “CUST_OK” if it can read the account. The next call attempts to cancel the last signaled menu entry. If there’s no menu entry to cancel, the method informs the user that the record cannot be found (“Invalid customer code”). If the call is able to cancel a menu entry, the method then checks the value returned in g_entnam. If this is “CUST_OK”, the method proceeds to determine if there’s a credit hold on the account or if the account is closed. If g_entnam is set to any other value, the method informs the user that the record cannot be found and then resignals the canceled entry.

; Customer Change Method
function cust_change ,^val ,reentrant
    a_data_entered      ,a      ; A buffer containing the field data as entered by user.
    a_data_stored       ,a      ; A buffer for the final storage of the data.
    a_pending_status    ,n      ; The result of Toolkit's field validations.
.include "WND:inpinf.def"       ; Group argument of input info
.include 'INPUT_DATA' REPOSITORY , group='input'
                                ; The data_area argument passed to the calling input routine.
    ; a_method_data     ,a      ; Optional method data argument.
.include "WND:tools.def"
.include 'CUSTOMER_MASTER' REPOSITORY ,record='cusmas'
proc
    clear cusmas
    cusmas.customer = input.customer
    xcall read_customer(cusmas)
    clear g_entnam
    ;Is there a menu signal waiting to be processed?
    if (%m_signal(g_entnam, D_REMOVE)) then
        begin
        ;Is the menu signal a "customer record read OK"?
        if(g_entnam.eq.'CUST_OK') then
            begin
            using cusmas.status select
            ('CH '),
                begin ; CREDIT HOLD status
                xcall u_message("Customer on credit hold")
                a_pending_status = D_EMITTEDERR
                end
            ('C '),
                begin ; CLOSED status
                xcall u_message("Customer account has been closed")
                a_pending_status = D_EMITTEDERR
                end
            endusing
            end
        else
            begin
            xcall u_message("Invalid customer code")
            a_pending_status = D_EMITTEDERR
            ;Resignal the menu entry canceled above
            xcall m_signal(g_entnam, D_SIGNAL)
            end
        end
    else
        begin
        xcall u_message("Invalid customer code")
        a_pending_status = D_EMITTEDERR
        end
    freturn a_pending_status
endfunction
subroutine read_customer
    .include 'CUSTOMER_MASTER' REPOSITORY ,group='a_cusmas'
proc
    read(chan, a_cusmas, a_cusmas.customer, LOCK=Q_NO_LOCK) [ERR=nocust]
    ;Signal that customer record was read OK.
    xcall m_signal('CUST_OK', D_SIGNAL)
nocust,
    xreturn
endsubroutine