# Function Reference

# _Excel_BookAttach

Attaches to the first instance of a workbook where the search string matches based on the selected mode

#include <Excel.au3>
_Excel_BookAttach ( $sString [, $sMode = "FilePath" [, $oInstance = Default]] )

## Parameters

$sString | String to search for
$sMode | [optional] specifies search mode: FileName - Name of the open workbook FilePath - Full path to the open workbook (default) Title - Title of the Excel window
$oInstance | [optional] Object of the Excel instance to be searched (default = keyword Default = all instances)

## Return Value

Success: | the Excel workbook object.
Failure: | 0 and sets @error.
@error: | 1 - An error occurred or $sString can't be found in any of the open workbooks. @extended is set to the COM error code 2 - $sMode is invalid

## Related

_Excel_BookClose, _Excel_BookNew, _Excel_BookOpen, _Excel_BookOpenText

## Example

### Example 1

    #include "Extras\HelpFileInternals.au3"

    #include <Excel.au3>
    #include <MsgBoxConstants.au3>

    ; Create application object and open an example workbook
    Local $sWorkbook = _Extras_PathFull("_Excel1.xls")
    Local $oExcel = _Excel_Open()
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_BookAttach Example 1", "Error creating the Excel application object." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
    Local $oWorkbook = _Excel_BookOpen($oExcel, $sWorkbook)
    If @error Then
        MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_BookAttach Example 1", "Error opening workbook '" & $sWorkbook & "'." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
        _Excel_Close($oExcel)
        Exit
    EndIf

    ; Attach to the first Workbook where the file path matches
    $oWorkbook = _Excel_BookAttach($sWorkbook)
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_BookAttach Example 1", "Error attaching to '" & $sWorkbook & "'." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
    MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_BookAttach Example 1", "Search by 'filepath':" & @CRLF & @CRLF & "Successfully attached to Workbook '" & $sWorkbook & "'." & @CRLF & @CRLF & "Value of cell B3: " & $oWorkbook.Activesheet.Range("B3").Value)

### Example 2

    #include "Extras\HelpFileInternals.au3"

    #include <Excel.au3>
    #include <MsgBoxConstants.au3>

    ; Create application object and open an example workbook
    Local $oExcel = _Excel_Open()
    If @error <> 0 Then Exit MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_BookAttach Example 2", "Error creating the Excel application object." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
    Local $oWorkbook = _Excel_BookOpen($oExcel, _Extras_PathFull("_Excel1.xls"))
    If @error Then
        MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_BookAttach Example 2", "Error opening workbook '" & _Extras_PathFull("_Excel1.xls'.") & @CRLF & "@error = " & @error & ", @extended = " & @extended)
        _Excel_Close($oExcel)
        Exit
    EndIf

    ; Attach to the first Workbook where the file name matches
    Local $sWorkbook = "_Excel1.xls"
    $oWorkbook = _Excel_BookAttach($sWorkbook, "filename")
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_BookAttach Example 2", "Error attaching to '" & $sWorkbook & "'." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
    MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_BookAttach Example 2", "Search by 'filename':" & @CRLF & @CRLF & "Successfully attached to Workbook '" & $sWorkbook & "'." & @CRLF & @CRLF & "Value of cell A2: " & $oWorkbook.Activesheet.Range("A2").Value)