.. highlightlang:: us

.. index:: GetObject

.. _getobject:

GetObject
=========

.. us.tag  GetObject NOTREADYENGLISH Programming.ActiveX New300

:ref:`GetObject` returns a reference to an embedded OLE object or a reference to
an application instance.

.. function::  o = GetObject(hOleObject)
    o = GetObject(ssServer)

.. us.return

**Return Value**

*o* is a reference to an embedded COM object it the function was called with a
UniScript handle as the first parameter. If the parameter is an application name,
the function returns a reference to an existing instance of the application. If
the application is not running already, it will be started.

.. us.params

**Parameters**

.. uparam:: hOleObject

   *hOleObject* is the UniScript handle of an embedded object.

.. uparam:: ssServer

   is the application name, e.g. ``Word.Application`` or ``Excel.Application``.

.. us.comment

**Comment**

If the server application is not responding a MessageBox is displayed after the
default time out. The default timeout value is 30 seconds. It can be set
with ``OLESetTimeout(nSeconds)``. 

.. us.example

**Example**

The following example expects that Excel 2000 or Excel 97 is installed.

::

   def _GetObjectByName(ssName)
   {
       hObj = ObjGetFirst()
       if (ObjGetName(hObj) == ssName) {
           return hObj;
       }
       while ((hObj = ObjGetNext()) != 0) {
           if (ObjGetName(hObj) == ssName) {
               return hObj;
           }
       }
       return 0;
   }
   def test()
   {
       hDoc = DocCreate(GetRootDirectory() + "Samples\Ole\Simple.ipw")
   //  hDoc = DocCreate("d:\uniplotr\Samples\Ole\Simple.ipw");
       if (hDoc == 0) error("can't open document");
       hOleObject = _GetObjectByName("magic0101");
       if (hOleObject == 0) error("can't find Excel table");
       excel = GetObject(hOleObject);
       if (excel == 0) error("can't execute Excel");
       excel.ActiveSheet.Cells(1,1).Value = "x";
       excel.ActiveSheet.Cells(1,2).Value = "y";
       excel.ActiveSheet.Range("a2:a31").Value = [2:31]';
       excel.ActiveSheet.Range("b2:b31").Value = rand(31, 1);
       DocReplot(hDoc);
   }

The following example shows a function that sends all doument pages to
MS-Word.

::

   def SendToMSWord(hDoc)
   {
       ShowWaitCursor(TRUE);
       obj = GetObject("Word.Application")
   //  obj = CreateObject("Word.Application")
       if (obj == 0) {
           error(sprintf(_s("Cannot start %s"), "Word"));
       }
       obj.Documents.Add();
       ad = obj.ActiveDocument;
       j = 1;
       hPageAct = DocGetActivePage(hDoc);
       nPageSel = DocGetPageNumber(hDoc, hPageAct);
       nPage = DocGetPageCount(hDoc);
       AppProgressCreate(0, nPage, 1, FALSE);
       for (i in nPage:1) {
           hPage = DocGetPageHandle(hDoc, i);
           ssFile = GetTempFileName();
           PageSaveAsMetafile(hPage, ssFile);
           ad.Shapes.AddPicture(ssFile, 0, 1).ConvertToInlineShape();
           DeleteFile(ssFile);
           AppProgressStepIt();
       }
       AppProgressDestroy();
       ShowWaitCursor(FALSE);
       DocSelectPage(hDoc, nPageSel);
       obj.Visible = 1;
       return TRUE;
   }

The following example is a small interface for Excel files. The interface can 
be used to read cell values and write cell values into a sheet. See function
Test().

::

   def excel_com_open(ssFileName)
   {
      obj = [.];
      ox = GetObject("Excel.Application");
      if (ox == 0) {
         MessageBox(sprintf(_s("Cannot start %s"), "MS-Excel"), ["ICONHAND"]);
   		 ShowWaitCursor(FALSE);
   		 return FALSE;
   	  }
      if (strtod(ox.Application.Version()) < 8.0) {
         ox=0;
         MessageBoxError(_s("Only MS-Excel 97, MS-Excel 2000 or newer is supported"));
         ShowWaitCursor(FALSE);
         return FALSE;
      }
      ssXLSTemplateFileName = MakeFullPath(ssFileName);
      ssXLSTemplateFileName = strfindreplace(ssXLSTemplateFileName, "\\\\", "\\");
      if (ox.Workbooks.Open(ssXLSTemplateFileName) == 0) {
         MessageBoxError(_s("Cannot open file:") + " " + ssXLSTemplateFileName);
         ShowWaitCursor(FALSE);
         return FALSE;
      }
      obj.ox = ox;
      return obj;
   }

   def excel_com_select_worksheet(obj, ssSheetName)
   {
      nTable = obj.ox.ActiveWorkbook.Worksheets.count();
      for (i in 1:nTable) {
         ssName = obj.ox.ActiveWorkbook.Worksheets(i).Name;
         if (ssName == ssSheetName) {
            obj.oSheet = obj.ox.ActiveWorkbook.Worksheets(i);
            return TRUE;
         }
      }
      obj.oSheet = 0;
      return FALSE;
   }

   def excel_com_write(obj, pValue, iRow, iCol)
   {
      obj.oSheet.Cells(iRow, iCol).Value = pValue;
   }

   def excel_com_read(obj, iRow, iCol)
   {
      return obj.oSheet.Cells(iRow, iCol).Value;
   }

   def excel_com_close(obj)
   {
      obj.ox.ActiveWorkbook.Save();
      obj.ox.ActiveWorkbook.Close();
      obj.ox = 0;
   }

   /*
   The given sheet name must exist in the Excel file.
   */ 
   def Test()
   {
      obj = excel_com_open("d:/test_excel.xls");
      if (obj == 0) {
         error();
      }
      excel_com_select_worksheet(obj, "Sheet1"); // Select sheet
      excel_com_write(obj, "Hello", 2,3);  // Write "Hello" in cell C2
      excel_com_write(obj, 123.543, 2,4);  // Write the number´123.543 in cell D2
      ssVal = excel_com_read(obj, 2,3);  // Read cell
      ssVal = excel_com_read(obj, 2,4);
      excel_com_close(obj);  // Save modified file and close it.
   }

The following example is a small interface for Excel files. The interface can 
be used to read cell values and write cell values into a sheet. See function
Test().

::

   def excel_com_open(ssFileName)
   {
      obj = [.];
      ox = GetObject("Excel.Application");
      if (ox == 0) {
         MessageBox(sprintf(_s("Cannot start %s"), "MS-Excel"), ["ICONHAND"]);
   		 ShowWaitCursor(FALSE);
   		 return FALSE;
   	  }
      if (strtod(ox.Application.Version()) < 8.0) {
         ox=0;
         MessageBoxError(_s("Only MS-Excel 97, MS-Excel 2000 or newer is supported"));
         ShowWaitCursor(FALSE);
         return FALSE;
      }
      ssXLSTemplateFileName = MakeFullPath(ssFileName);
      ssXLSTemplateFileName = strfindreplace(ssXLSTemplateFileName, "\\\\", "\\");
      if (ox.Workbooks.Open(ssXLSTemplateFileName) == 0) {
         MessageBoxError(_s("Cannot open file:") + " " + ssXLSTemplateFileName);
         ShowWaitCursor(FALSE);
         return FALSE;
      }
      obj.ox = ox;
      return obj;
   }

   def excel_com_select_worksheet(obj, ssSheetName)
   {
      nTable = obj.ox.ActiveWorkbook.Worksheets.count();
      for (i in 1:nTable) {
         ssName = obj.ox.ActiveWorkbook.Worksheets(i).Name;
         if (ssName == ssSheetName) {
            obj.oSheet = obj.ox.ActiveWorkbook.Worksheets(i);
            return TRUE;
         }
      }
      obj.oSheet = 0;
      return FALSE;
   }

   def excel_com_write(obj, pValue, iRow, iCol)
   {
      obj.oSheet.Cells(iRow, iCol).Value = pValue;
   }

   def excel_com_read(obj, iRow, iCol)
   {
      return obj.oSheet.Cells(iRow, iCol).Value;
   }

   def excel_com_close(obj)
   {
      obj.ox.ActiveWorkbook.Save();
      obj.ox.ActiveWorkbook.Close();
      obj.ox = 0;
   }

   /*
   The given sheet name must exist in the Excel file.
   */ 
   def Test()
   {
      obj = excel_com_open("d:/test_excel.xls");
      if (obj == 0) {
         error();
      }
      excel_com_select_worksheet(obj, "Sheet1"); // Select sheet
      excel_com_write(obj, "Hello", 2,3);  // Write "Hello" in cell C2
      excel_com_write(obj, 123.543, 2,4);  // Write the number´123.543 in cell D2
      ssVal = excel_com_read(obj, 2,3);  // Read cell
      ssVal = excel_com_read(obj, 2,4);
      excel_com_close(obj);  // Save modified file and close it.
   }

.. seealso::
   :ref:`overview-programming`,
   :ref:`CreateObject`,
   :ref:`CreateObjectEmbedded`

:sub:`id-69498`