CreateObject function

Syntax

CreateObject(str_class_name, create_par,  ...)

Where str_class_name either identifies:

  • A class by class name

  • A class of OLE Automation object in the form:

    app_name.object_name

Description

Use the CreateObject function to return an instance of a class. You can use this function to access an application class, a PeopleCode built-in object (like a chart), or an OLE Automation object.

If the class you are creating requires values to be passed, use the create_par parameters to supply them, or use the CreateObjectArray function.

Parameters

Parameter Description

str_class_name

Specify the name of the class that you want to instantiate an object from.

create_par

Specify the parameters required by the class for instantiating the object.

Example

This example instantiates an Excel worksheet object, makes it visible, names it, saves it, and displays its name. Note the use of ObjectGetProperty in the example to return the Excel.Sheet.Application object. 

&WORKAPP = CreateObject("COM", "Excel.Application"); 
&WORKBOOKS = ObjectGetProperty(&WORKAPP, "Workbooks"); 
/* This associates the INVOICE template w/the workbook */
ObjectDoMethod(&WORKBOOKS, "Add", "C:\TEMP\INVOICE.XLT"); 
ObjectDoMethod(&WORKAPP, "Save", "C:\TEMP\TEST1.XLS"); 
ObjectSetProperty(&WORKAPP, "Visible", True);

This following example illustrates the creation of an application class object. This code assumes that MyBaseClass is the superclass of both MySubclass1 and MySubclass2 classes.

local MyBaseClass &mbobj; 
local String &ClassName = "MySubclass1"; 
if &test then 
&ClassName = "MySubclass2"; 
end-if; 
&mbobj = CreateObject(&ClassName);

The following example creates a chart in an iScript, using the CreateObject function to generate a reference to a chart object.

Function IScript_GetChartURL() 
   Local Chart &oChart; 
   Local Rowset &oRowset; 
   Local string &sMap; 
   Local string &sURL; 
   &oChart = CreateObject("Chart"); 
    
   &oRowset = CreateRowset(Record.QE_CHART_RECORD); 
   &oRowset.Fill("where QE_CHART_REGION= :1", "MIDWEST"); 
   &oChart.SetData(&oRowset); 
   &oChart.Width = 400; 
   &oChart.Height = 300; 
   &oChart.SetDataYAxis(QE_CHART_RECORD.QE_CHART_SALES); 
   &oChart.SetDataXAxis(QE_CHART_RECORD.QE_CHART_PRODUCT); 
   &oChart.SetDataSeries(QE_CHART_RECORD.QE_CHART_REGION); 
   &oChart.HasLegend = True; 
   &oChart.LegendPosition = %ChartLegend_Right; 
   &sURL = %Response.GetChartURL(&oChart); 
   &sMap = &oChart.ImageMap; 
   %Response.Write("<HTML><IMG SRC="); 
   %Response.Write(&sURL); 
   %Response.Write("  USEMAP=#THEMAP></IMG><MAP NAME=THEMAP>"); 
   %Response.Write(&sMap); 
   %Response.Write("</MAP></HTML>"); 
End-Function;

Considerations for Instantiating Application Classes

You can use the CreateObject function to access an application class. You would want to do this when you were programming at a high-level, when you might not know the name of the class you wanted to access until runtime. You must specify a fully-qualified class name. In addition, the class name is case-sensitive.

The returned object has the type of class you specified.

Alternatively, when the application class name and path is known at design time, use the create function instead. See create function for more information.

Considerations for Instantiating PeopleCode Built-in Objects

For example, to instantiate a Chart object without using a chart control (that is, without using the GetChart function) you could use:

&MyChart = CreateObject("Chart");

The returned object has the type of class you specified.

Note:

The only way to instantiate a Crypt object is using the CreateObject function.

Considerations Using OLE Automation Objects

CreateObject returns an instance of an OLE Automation object as a variable of type Object.

The str_class_name argument uses the syntax app_name.object_type, which consists of: app_name (the name of the application providing the object) and object_type (the class or type of the object to create), separated by a period (dot).

Any application that supports OLE Automation exposes at least one type of object. For example, a spreadsheet application may provide an application object, a worksheet object, and a toolbar object.

To create an OLE Automation object, you assign the object returned by CreateObject to a variable of type Object:

local object &WORKSHEET;

&WORKSHEET = CreateObject("Excel.Sheet");

After an object is created, you can reference it using the object variable. In the previous example, you access properties and methods of the new object using the ObjectGetProperty, ObjectSetProperty, and ObjectDoMethod functions.

Note:

If an object has registered itself as a single-instance object, only one instance of the object can be created, even if CreateObject is executed more than once. Note also that an object assigned to a global variable is not valid across processes: that is, the scope and lifetime of the global is the same as the scope and lifetime of the instance of PeopleTools in which the object was created.

Related Topics