isCOBOL Evolve : Appendices : Library Routines : A$SEND_MESSAGE
A$SEND_MESSAGE
In an Application Server environment, A$SEND_MESSAGE allows you to send a notification message to another connected thin client.
By default, the message will appear as a standard graphical message box, but this layout can be customized as described below, in Customizing the message layout.
Note - It’s not possible to send a message to another client if the current thin client session is running in a separate task due to the iscobol.as.multitasking setting. It’s also not possible to send messages to those clients that are not thin clients (i.e. FileServer sessions, remote calls and TurboRun sessions).
Syntax:
 CALL "A$SEND_MESSAGE" USING  threadID,
                              msgText,
                             [msgTitle]
                       GIVING returnCode
Parameters:
threadID
PIC 9(n)
Specifies the thread ID of the client that will receive the message
msgText
PIC X(n)
Specifies the text of the message.
msgTitle
PIC X(n)
Optional parameter.
Specifies the title of the message box. If omitted, the title is set to "A$SEND_MESSAGE".
Return code:
returnCode can be any numeric data item and provides additional information:
0
Operation successul.
-1
Invalid arguments.
-2
Recipient client not found.
-3
Communication error.
 
Examples:
Example - Inform client number 2 that the invoice has been printed
...
call "A$SEND_MESSAGE" using 2, "Invoice number #1312 has been printed",
                               "Message from Tom".
...
Customizing the message layout
isCOBOL offers the ability to create a custom window to display the message generated by A$SEND_MESSAGE. Before showing the default message box, the Application Server calls A$CUSTOM_MESSAGE on the client machine. If this program is found, it is used instead of the default.
This program must be called A$CUSTOM_MESSAGE and must be in a location specified in the CLASSPATH or iscobol.code_prefix set on the client machine. It must also use the following Linkage code:
 LINKAGE SECTION.
 77 msgText  pic x any length.
 77 msgTitle pic x any length.
Where msgText and msgTitle will receive the content of the corresponding parameter passed to A$SEND_MESSAGE.
The following example shows how to display a notification window instead of a message box though the A$CUSTOM_MESSAGE program:
 program-id. "a$custom_message".
 
 working-storage section.
 77 n-win handle of window.
 
 linkage section.
 77 msgText pic x any length.
 77 msgTitle pic x any length.
 
 screen section.
 01 n-screen.
   03 entry-field line 1, col 1
      lines 10 cells, size 40 cells
      no-box, multiline, read-only, value msgText.
 
 procedure division using msgText, msgTitle.
 main.
    display notification window
            bottom right
            lines 10, size 40
            before time 500
            visible 0
            handle n-win.
    display n-screen upon n-win.
    modify n-win visible 1.