@DDEExecute (Formula Language)

Syntax

@DDEExecute( conversationID ; command )

Parameters

conversationID

The conversationID is returned by the @DDEInitiate function, which must precede the use of @DDEExecute. Use your own variable name; that's how you pass the conversation ID between Domino® and the other application. If the conversation ID is invalid, Domino® returns an error. See @IsError.

command

Text. The command must be a text string that adheres to the syntax rules of the receiving application (see that application's documentation). Enclose the command in quotation marks so it can be passed intact to the DDE application; that application will then interpret it as a DDE command.

Return value

acknowledgment

Number.

• Returns @True (1) if the DDE command is successfully executed
• Returns @False(0) if not
• Returns an error if the conversation ID is invalid

Usage

This function is intended for use primarily in field formulas, agents, and toolbar buttons. It does not work in column or selection formulas, and is not intended for use in window title or form formulas. Since the Macintosh does not support DDE, these commands will not work on Macintosh workstations. In addition, the format of the DDE commands may vary somewhat with each platform or application.

If the user's NOTES.INI file includes the statement:

NoExternalApps=1

then any formula involving @DDE functions is disabled. The user doesn't see an error message; the formula fails to execute.

You can have up to 10 DDE conversations running concurrently, although under normal circumstances you should only have one conversation running at a time. Be sure to terminate all DDE conversations once they're completed, or you may run out of sessions and be unable to initiate more conversations when needed.

You cannot use this function in Web applications.

Examples

Conv_ID := @DDEInitiate("123W";"Budget95.wk3");
@If (@IsError(Conv_ID); @Do(@Prompt([Ok];"Error"; 
"Unable to initiate conversation");@Return(""));
@Do(@DDEPoke(Conv_ID;"A:B6"@Text(Amount));
@DDEExecute(Conv_ID;"[RUN(\"{Goto}A:B6~\")]");
@DDEExecute(Conv_ID;"[RUN(\"/rfc~~\")]");
@DDEExecute(Conv_ID;"[RUN(\"{Goto}A:B10~{Edit-Copy}\")]");
@DDETerminate(Conv_ID);
@Command([EditNextField]);
@Command([EditPaste])))

The line-by-line explanations:

Conv_ID := @DDEInitiate("123W";"Budget95.wk3");

Initiates a conversation between Domino® and 1-2-3®. This statement specifies which worksheet to use (BUDGET95.WK3) and stores the conversation ID in the variable Conv_ID. Note that the specified file must be open before the @DDEInitiate is executed.

@If (@IsError(Conv_ID); @Do(@Prompt([Ok];"Error";   
"Unable to initiate conversation"); @Return(""));

Determines whether the DDE conversation was successfully initiated. If it was, the formula continues; if it wasn't, a message appears, and the formula stops executing.

@Do(@DDEPoke(Conv_ID;"A:B6";@Text(Amount));

Converts the contents of the numeric Amount field to text, and then passes that value to cell A:B6 in the 1-2-3® worksheet. The value must be converted to text because only text can be passed via DDEPoke.

@DDEExecute(Conv_ID;"[RUN(\"{Goto}A:B6~\")]");

Makes cell A:B6 the current location in the worksheet.

@DDEExecute(Conv_ID;"[RUN(\"/rfc~~\")]");

Passes the Range, Format, Currency command to 1-2-3®; cell A:B6 is now formatted for currency values.

@DDEExecute(Conv_ID;"[RUN(\"{Goto}A:B10~{Edit-Copy}\")]");

Passes the Goto and Edit Copy commands to 1-2-3®; cursor is moved to cell A:B10 within the worksheet and the value stored in that cell is copied to the Windows™ Clipboard.

@DDETerminate(Conv_ID);

Terminates the DDE conversation.

@Command([EditNextField]); 

Navigates to the next field within the current Domino® document.

@Command([EditPaste])))

The contents of the Clipboard (the value from cell A:B10) are pasted into that field.