Progress
Language Reference


CREATE Automation Object Statement

Interfaces
OS
SpeedScript
All
Windows only
Yes

Creates (instantiates) an ActiveX Automation object based on a specified Automation Server connection.

SYNTAX

CREATE expression1 COM-hdl-var 
  [ CONNECT [ TO expression2 ] ]
  [ NO-ERROR ] 

expression1

A character-string expression that evaluates to 1) a unique name of a valid Automation object stored in the system registry or 2) the null string ("").

COM-hdl-var

A COM-HANDLE variable that receives the COM handle to the instantiated Automation object.

[CONNECT [ TO expression2 ] ]

Specifies the connection option, together with expression1. The behavior of each connection option depends on the execution status of the Automation Server.

Table 16 describes this behavior.

Table 16: Automation Object Connection Options

Connection
Option
Server
Execution
Status


Connection Behavior
1.
Option omitted
Running
Creates a new instance of the Automation object identified by expression1. Launches a new instance of the Server for top-level Automation objects (like Excel.Application) start a new instance of the Server.
Not running
Launches a new instance of the Server, then creates a new instance of the Automation object identified by expression1. Often, both the new Server and the new Automation object instance are invisibly created.
2.
CONNECT
Running
Connects to an active (instantiated) Automation object identified by expression1. Works for top-level Automation objects only. For example, this works for Excel.Application but fails for Excel.Sheet and Excel.Chart, which are both lower-level Automation objects.
Not running
Invalid. Always returns an error.
3.
CONNECT TO
expression2
Running
Creates or connects to an Automation object specified by expression1 that is associated with the file specified by the pathname in expression2. If more than one instance of the Server is running, this option randomly selects one (generally, the first one started). If the specified file is already open within the selected Server, this option connects to the Automation object that is instantiated for that file. If the file is not already open in the selected Server, this option opens the file and instantiates the specified Automation object for it.

If the specified file is already open in a different instance of the Server, this option fails with a “File in Use” error. This option also fails if the expression2 does not specify a valid file.
Not running
Creates a new instance of an Automation object specified by expression1 that is associated with the file specified by the pathname in expression2. This option starts a new instance of the Server and instantiates the Automation object for the class that is initialized from the contents of the file. Often, the new Server, as well as the new Automation object, are invisibly created.

This option fails if expression2 does not specify a valid file.
4.
CONNECT TO expression2
WHERE
expression1 = ""
Running
Creates or connects to an Automation object that is associated with the file specified by the pathname in expression2. This option determines the identity of the Server (and hence the Automation object) from the file extension given in expression2. If more than one instance of the Server is running, this option randomly selects one (generally, the first one started). If the specified file is already open within the selected Server, this option connects to the Automation object that is instantiated for that file. If the file is not already open in the selected Server, this option opens the file and instantiates the specified Automation object for it.

If the specified file is already open in a different instance of the Server, this option fails with a “File in Use” error. This option also fails if the expression2 does not specify a valid file.
Not running
Creates a new instance of an Automation object that is associated with the file specified by the pathname in expression2. This option determines the identity of the Server (and hence the Automation object) from the file extension given in expression2. This option starts a new instance of the Server and instantiates the Automation object for the class that is initialized from the contents of the file. Often, the new Server, as well as the new Automation object, are invisibly created.

This option fails if expression2 does not specify a valid file.

NO-ERROR

Suppresses error messages for the instantiation of an Automation object. You can then test for the ERROR condition to verify that the Automation object is instantiated.

EXAMPLE

The following procedure demonstrates several Automation object instantiations using the four basic connection options. It tries all of the options with the Microsoft Excel Automation Server. Note that not all Automation Servers support all options. For example in Office 95, there is no Automation object for PowerPoint presentations. Thus, the file connection option (Option 3 in Table 16) does not work.

r-crea.p
/* 
 * Demonstration of connecting to an Automation Object in Excel 
 * using the different connection options.
 */

DEF BUTTON bExit 
    LABEL "Exit" SIZE 16 BY 1.25 AUTO-GO.
DEF BUTTON bStart 
    LABEL "Option 1 - Start Excel" SIZE 32 BY 1.25 .
DEF BUTTON bConnect 
    LABEL "Option 2 - Connect to Active" SIZE 32 BY 1.25.
DEF BUTTON bConPerFile 
    LABEL "Option 3 - Connect per File" SIZE 32 BY 1.25.
DEF BUTTON bConnectMon 
    LABEL "Option 4 - Connect by Extension" SIZE 32 BY 1.25.
DEF VAR e AS CHAR VIEW-AS EDITOR SIZE 63 BY 1 LABEL "Result:" FONT 2.

DEFINE VARIABLE curDir AS CHARACTER.
FILE-INFO:FILE-NAME = ".".
curDir = FILE-INFO:FULL-PATHNAME.
DEFINE VAR wordAppl AS COM-HANDLE.


FORM e SKIP(0.5) bStart  SPACE bConnect  SPACE bConPerFile 
                         SPACE bConnectMon 
       SKIP(0.5) bExit WITH FRAME a VIEW-AS DIALOG-BOX THREE-D FONT 6.
FRAME a:TITLE = "Testing CREATE Automation Object Statement".

ENABLE ALL WITH FRAME a.ON CHOOSE OF bStart IN FRAME a 
DO:

/*
 * Option 1:
 * Connect using CREATE expression1 Com-Handle-Var.
 */

  DEFINE VARIABLE excelAppl AS COM-HANDLE.
  CREATE "Excel.Application" excelAppl. 
  excelAppl:Visible=true.
  excelAppl:Workbooks:Add.
  excelAppl:Range("A1"):Value = "testing CREATE".
  ASSIGN e:SCREEN-VALUE = String(excelAppl:Range("A1"):Value).
  release object excelAppl.
END.

ON CHOOSE OF bConnect IN FRAME a
DO:

/*
 * Option 2:
 * Connect using CREATE expression1 Com-Handle-Var CONNECT.
 */

  DEFINE VARIABLE excelAppl AS COM-HANDLE.
  CREATE "Excel.Application" excelAppl connect.
  excelAppl:Range("A2"):Value = "testing CONNECT".
  MESSAGE "Click me to continue!" VIEW-AS ALERT-BOX.
  ASSIGN e:SCREEN-VALUE = String(excelAppl:Range("A2"):Value).
  excelAppl:Workbooks:Item(1):SaveAs(curDir + "\zzz.xls").
  excelAppl:Quit().
  release object excelAppl.
END. 
ON CHOOSE OF bStart IN FRAME a
DO:

/*
 * Option 1:
 * Connect using CREATE expression1 Com-Handle-Var.
 */

  DEFINE VARIABLE excelAppl AS COM-HANDLE.
  CREATE "Excel.Application" excelAppl. 
  excelAppl:Visible=true.
  excelAppl:Workbooks:Add.
  excelAppl:Range("A1"):Value = "testing CREATE".
  ASSIGN e:SCREEN-VALUE = String(excelAppl:Range("A1"):Value).
  release object excelAppl.
END.

ON CHOOSE OF bConnect IN FRAME a
DO:

/*
 * Option 2:
 * Connect using CREATE expression1 Com-Handle-Var CONNECT.
 */

  DEFINE VARIABLE excelAppl AS COM-HANDLE.
  CREATE "Excel.Application" excelAppl connect.
  excelAppl:Range("A2"):Value = "testing CONNECT".
  MESSAGE "Click me to continue!" VIEW-AS ALERT-BOX.
  ASSIGN e:SCREEN-VALUE = String(excelAppl:Range("A2"):Value).
  excelAppl:Workbooks:Item(1):SaveAs(curDir + "\zzz.xls").
  excelAppl:Quit().
  release object excelAppl.
END. 

NOTES

SEE ALSO

RELEASE OBJECT Statement


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095