DDERequest( ) Function

  • Article

Requests data from a server application in a dynamic data exchange (DDE) conversation.

DDERequest(nChannelNumber, cItemName [, cDataFormat [, cUDFName]])

Return Values

Character

Parameters

  • nChannelNumber
    Specifies the channel number of the server application.

  • cItemName
    Specifies the item name. The item name is application-specific and must be understood by the application. 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.

  • cDataFormat
    Specifies a format for the data requested. The default format is CF_TEXT. In this format, fields are delimited with tabs and records are delimited with a carriage return and a line feed.

  • cUDFName
    Allows an asynchronous data transfer. If you omit cUDFName, Visual FoxPro waits for the data from the server for the period specified with DDESetOption( ). If you specify the name of a user-defined function with cUDFName, Visual FoxPro continues program execution immediately after the request is made.

    When the data is available from the server application, the user-defined function specified with cUDFName is executed. The user-defined function is passed six parameters in this order:

    Parameter Contents
    Channel Number The channel number of the server application.
    Action XACTCOMPLETE (successful transaction).XACTFAIL (failed transaction).
    Item The item name; for example, R1C1 for a Microsoft Excel worksheet cell.
    Data The new data (REQUEST) or data passed (POKE or EXECUTED).
    Format The data format; for example, CF_TEXT.
    Transaction Number The transaction number returned by DDERequest( ).

    Use DDEAbortTrans( ) to cancel an uncompleted transaction. If the transaction fails, you can use DDELastError( ) to determine why it failed.

    When you include cUDFName, DDERequest( ) returns a transaction number equal to or greater than 0 if successful, or –1 if an error occurs.

Remarks

Before you can request data using DDERequest( ), you must establish a channel to the server application with DDEInitiate( ).

If the request for data is successful, DDERequest( ) returns the data as a character string. If the request fails, DDERequest( ) returns an empty string and DDELastError( ) returns a nonzero value. If you include the asynchronous user-defined function cUDFName, DDERequest( ) returns a transaction number if successful, or –1 if an error occurs.

Example

The following example uses DDEInitiate( ) to establish a DDE channel between Visual FoxPro and a Microsoft Excel worksheet named Sheet1. 'Excel' is the service name, and 'Sheet1' is the topic name. The channel number is stored to the memory variable mchannum for use in subsequent DDE functions.

DDERequest( ) requests the item name R1C1, the data in the first row and column of the Sheet1 spreadsheet.

mchannum = DDEInitiate('Excel', 'Sheet1')
IF mchannum != -1
   mrequest = DDERequest(mchannum, 'R1C1')
   IF !EMPTY(mrequest) AND DDELastError( ) = 0      && Successful
      WAIT WINDOW 'R1C1 contents: ' + mrequest
   ENDIF
   = DDETerminate(mchannum)            && Close the channel
ENDIF

See Also

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