UpdateLinksDialog

Description

Attempts to find a file linked to an OLE container. If the linked file is not found, a dialog box tells the user and lets them bring up a second dialog box for find the file or changing the link.

Applies to

OLE controls and OLE DWObjects (objects within a DataWindow object that is within a DataWindow control)

Syntax

objectref.UpdateLinksDialog ( )

Argument

Description

objectref

The name of the OLE control or the fully qualified name of a OLE DWObject within a DataWindow control that contains the object for which you want to establish a link.

The fully qualified name for a DWObject has this syntax:

dwcontrol.Object.dwobjectname

Return value

Integer.

Returns 0 if it succeeds and -1 if an error occurs.

Usage

If a container's LinkUpdateOptions property is set for automatic update, PowerBuilder tries to update the link when the OLE container is created and the object is loaded (for example, when the window is opened). If the linked file is not found, a message informs the user and he or she can choose to edit the link (for example, break the link or browse for the correct file).

UpdateLinksDialog and LinkTo are useful when a linked file has been moved and the container's LinkUpdateOptions property is set for manual update.

UpdateLinksDialog

Calling this function triggers the same process that occurs for automatic update. PowerBuilder tries to find the file and if it fails it gives the user the opportunity to edit the link.

LinkTo

If you want to establish a link without involving the user, call the LinkTo function. Its arguments specify the file and item you want to link. If you want to display your own dialog for selecting the linked file, you can take the information the user specifies and call the LinkTo function.

If the OLE container holds an embedded object, calling UpdateLinksDialog has no effect. It returns zero because no link is broken.

For more information about updating links, see the section called “Linking versus embedding” in Application Techniques.

Examples

This example looks for the linked file for an OLE control ole_report. If the file is missing, it prompts the user to display the Links dialog and edit the link:

ole_report.UpdateLinksDialog()

This example looks for the linked file for an OLE DWObject ole_word in the DataWindow control dw_customer_data. If the file is missing, the user can choose to edit the link using the Links dialog:

dw_customer_data.Object.ole_word.UpdateLinksDialog()

See also

InsertObject

LinkTo