This function inserts the graphic tag specified by tagname at the cursor and sets the appropriate file or entity reference attribute to the file name specified by path. If tagname is not specified, a prompt dialog is displayed listing all the graphic tags (as declared in the .dcf file) that are valid at the current location. If only one graphic element is valid, then that is used without prompting. If no graphic elements are valid (or are declared in the .dcf file), the function returns 0 (False). The function returns 1 (True) if the graphic reference was successfully inserted.

If doc is zero or omitted, the current document is used.

The path parameter is set using the oid_set_graphic_pathname function and stored as a relative path name if possible, as determined by the graphic_relative_path function.