DDEAdvise( ) Function

Creates a notify link or an automatic link used in a dynamic data exchange (DDE).

DDEAdvise(nChannelNumber, cItemName, cUDFName, nLinkType)

Return Values

Logical

Parameters

• nChannelNumber
  Specifies the channel number.

• cItemName
  Specifies the item name. For example, Microsoft Excel uses row and column notation to refer to cells in a worksheet. The item name R1C1 designates the cell in the first row and first column of the worksheet.

• cUDFName
  Specifies the user-defined function that is executed when a notify link or an automatic link is established and the item cItemName is modified. When the user-defined function is executed, it is passed the following six parameters in the order given below:

  Parameter	Contents
  Channel Number	The channel number of the server application.
  Action	ADVISE or TERMINATE.
  Item	The item name; for example, R1C1 for a Microsoft Excel worksheet cell.
  Data	The new data (automatic link) or the empty string (notify link).
  Format	The data format; for example, CF_TEXT.
  Advise Status	The link type (0 = manual, 1 = notify, 2 = automatic).

  The user-defined function should have six parameters in its LPARAMETER or PARAMETER statement to accept the values passed from the server application. If a notify link is established, the user-defined function is executed and the empty string is passed in the Data parameter. You can issue DDERequest( ) later to retrieve the data. If an automatic link is established, the user-defined function is executed and the data is passed in the Data parameter.

  The Action parameter contains ADVISE when the link is being updated by the server. The user-defined function is called, and the Action parameter contains TERMINATE when the link is closed by the client or server.

  Any value returned by the user-defined function is ignored.

• nLinkType
  Specifies the link type in the following way:

  nLinkType	Link type
  0	Manual
  1	Notify
  2	Automatic

  You can turn off notification from the server application by specifying 0 for nLinkType. If the item changes, the user-defined function isn't executed.

Remarks

DDEAdvise( ) is used to create a notify link or an automatic link to an item name in a server application. When a notify link is created with DDEAdvise( ), the server application notifies Visual FoxPro that the item name has been modified. If an automatic link is created, the server application notifies Visual FoxPro that the item name has been modified and passes the new data to Visual FoxPro.

Before you can create a link, you must establish a channel to the server application with DDEInitiate( ).

You can also use DDEAdvise( ) to turn off notification from the server.

DDEAdvise( ) returns a true value (.T.) if it executes successfully; otherwise, it returns false (.F.).

Example

The following example demonstrates how you can establish a DDE channel to a Microsoft Excel worksheet named Sheet1. DDEAdvise( ) is used to establish two links to data in two worksheet cells (R1C1 and R1C2). The user-defined function NEWDATA is executed when data in either of the cells changes. The user-defined function tests the item and advise parameters to determine which item changed and what kind of link has been established.

PUBLIC mchannum
mchannum = DDEInitiate('Excel', 'Sheet1')
IF mchannum != -1
   = DDEAdvise(mchannum, 'R1C1', 'newdata', 1)     && Notify link
   = DDEAdvise(mchannum, 'R1C2', 'newdata', 2)     && Automatic link
   WAIT WINDOW 'Enter data in first two cells in Excel.'
ENDIF
PROCEDURE newdata
PARAMETERS channel, action, item, data, format, advise
IF action = 'ADVISE'
   DO CASE
      CASE item = 'R1C1'   && Notify link
         newvalue = DDERequest(channel, item)
         ? 'R1C1 notify link: ' + newvalue
      CASE item = 'R1C2'   && Automatic link
         newvalue = data
         ? 'R1C2 automatic link: ' + newvalue
   ENDCASE
ELSE
   IF action != "TERMINATE"
      = DDETerminate(mchannum)
 ENDIF
ENDIF

See Also

DDEInitiate( ) | DDELastError( ) | DDESetOption( ) | DDETerminate( )