Contents Previous Next Subchapters

Setting a COM object
Syntax cowith(object name)
cowith(object name, ObjectArg1)
cowith(object name, ObjectArg1, ObjectArg2)
cowith
See Also cocreate , coendwith

Description
Sets the current object to be used by the coinvoke, copropget, and copropput functions. The character row vector object name specifies the object to be referenced. If present, the arguments ObjectArg1 and ObjectArg2 may be an integer, real, or double-precision matrix, a logical scalar, or a character row vector. The ObjectArg values are passed to object name when the object is retrieved.

If cowith is called without arguments the function returns an integer scalar which is the current depth in the object hierarchy. (That is the number of times that cowith has been called for which there is not a corresponding coendwith call.)

Some automation servers expose their functionality in a hierarchy of objects. The property or method functionality you wish to access might be part of a child object. In Visual Basic this hierarchy navigation is typically provided with the "dot" notation as in <parent object>.<child object> For example, in Visual Basic you access the FileSystemObject through the parent Scripting object,
     Set fileSystemObject = CreateObject("Scripting.FileSystemObject")
 O-Matrix does not store handles to child objects but allows you to perform property and method operations relative to the current object. The O-Matrix cowith and coendwith functions push and pop child objects of a hierarchy to enable navigation of automation objects models that are designed with a nested hierarchy.

Examples

Referencing an Excel Object Without Arguments
The Excel Automation server defines an object hierarchy where Workbook and Worksheet objects are children of the Excel Application object. If at the O-Matrix prompt you enter
     clear
     cocreate("Excel.Application")  # Create connection to the Excel Automation server
     copropput("Visible", 1)  # Set the Visible property of .Application to make Excel visible
 O-Matrix will start Excel and make it visible on the desktop. After the call to cocreate, Application is the current object, and Visible is a property of the Application object. If you continue the example by entering
     cowith("Workbooks")    # Make the Excel.Application.Workbooks active
     coinvoke("Add")        # call Add method of workbooks to create new Excel workbook
 The call to cowith makes Workbooks, which is a child object of Application the current object.

Referencing an Excel Object That Requires Arguments
Child objects are often defined in automation servers as a property or method that requires an argument. (Often referred to as collections in Visual Basic.) The cowith function can reference one of these objects by specifying up to two arguments.

Individual cells in Excel are accessed by referencing a Range object with the desired cell or cells as an argument to the Range reference. If at the O-Matrix prompt you enter
     clear
     cocreate("Excel.Application")
     copropput("Visible", 1)
     cowith("Workbooks")
     coinvoke("Add")
     coendwith
 O-Matrix will start Excel, make it visible, and add a new workbook to the Workbooks child object of the Application object. If you continue the example by entering
     cowith("Range", "A1")
 O-Matrix will access the A1 cell of Workbooks child object, Range. You can verify that O-Matrix is now referencing the specified Range object by entering
     copropput("Value", 3)
 which will display 3 in the first cell of Excel. If you wish to terminate Excel you need to navigate back up the Excel object hierarchy to the Excel Application object. If you continue the previous example by entering
     coendwith     # navigate up to Worksheet parent object
     coendwith     # navigate up to Application object
     coinvoke("Quit")  # exit Excel
 O-Matrix will navigate back to the root object of the Excel object hierarchy and exit the application.