CREATE Statement

The CREATE statement creates a new instance of a non-graphical object such as a COM object or .NET assembly. Use it specifically for objects or assemblies that are not visual in nature. Use the Screen Section or DISPLAY statement to create an instance of a graphical .NET assembly or an ActiveX control.

Note: CREATE can be used with thin client applications to create instances of an object on the client or on remote Windows servers. CREATE cannot be used to create an object on a non-Windows server; however, non-Windows servers running AcuConnect can provide connectivity to Windows servers in a multi-tiered configuration.

Format 1

CREATE object-name creates a COM object.

CREATE object-name
 
HANDLE { IN } object-handle
       { IS }

Remaining phrases are optional.

SERVER-NAME { IS } server-name
            { =  }
LICENSE-KEY { IS } license-key
            { =  }
EVENT PROCEDURE IS { proc-1 [ {THROUGH} proc-2 ] }
                              {THRU } 
                   { NULL } 

Format 2

CREATE assembly-name creates a non-graphical .NET object.

CREATE "assembly-name" 

NAMESPACE { IS } "namespace"

CLASS-NAME { IS } "class-name"
 
HANDLE { IN } object-handle
       { IS }

EVENT PROCEDURE { IS } "event-proc"

Remaining phrases are optional.

VERSION { IS } "version"

CULTURE { IS } "culture"

STRONG-NAME { IS } "strong-name"

CONSTRUCTOR { IS } CONSTRUCTOR[n] parameters...

MODULE { IS } "module"

FILE-PATH { IS } "file-path"

SERVER-NAME { IS } server-name

Syntax Rules

  1. object-name is an optionally qualified name of a COM object defined in the special-names paragraph.
  2. server-name is an alphanumeric literal or data item.
  3. license-key is an alphanumeric literal or data item.
  4. object-name is a USAGE HANDLE data item.
  5. proc-1 and proc-2 are procedure names relating to COM events. See ActiveX and COM Events for more information.
  6. Any value surrounded by quotation marks is an alphanumeric literal and is case-sensitive.

Format 1 (CREATE object-name) General Rules

  1. In a non-Thin Client environment the COM object is registered and instantiated on the same machine the runtime is executing on. In a Thin Client scenario the COM object is registered and instantiated on the client machine rather than the server where the runtime is executing.
  2. server-name identifies a remote machine on which to create and execute the COM object or .NET assembly. It can be specified as a UNC, DNS name, or IP address. Server-name must be the name of a Windows machine. CREATE cannot create objects on non-Windows servers. When a server-name is provided - the COM object's interface is instantiated on the machine where the application is executing and the back-end is instantiated on the specified server where the work is done and resources can be accessed. In this case the COM object must be registered on both machines.
    Note: In a non-distributed environment, the server-name property has no effect, meaning you can use this format with server-name for compiling both distributed and non-distributed environments with no change in code required.
  3. When executing in a distributed environment, the value of server-name, when specified for a .NET object, must start with the prefix Local: to signify that the object should be created on the application host (server runtime) rather than on the client (display host, or thin client, or web browser). For example:
    CREATE .NET_object SERVER-NAME "Local:the_server_name"
  4. In a Thin Client environment the customer may also specify the server-name with the prefix, Local: e.g. CREATE COM_object SERVER-NAME "Local:the_server_name". In this case the COM object is wholly instantiated on the specified server where the COM object is registered, all the work is done and all resources must reside.
  5. Some COM objects are licensed for run time using a license key that is provided to you by the object vendor. This license key is a text string usually located in a .lic file. By setting the value of the LICENSE-KEY property to this license key, you embed this license key in your COBOL program. Then when you run your COBOL program, the license key is passed to the COM object for verification. You do not send the .lic file or license key to the end-user. Set LICENSE-KEY when you create the object (i.e., in the CREATE statement). The default value is " ". When LICENSE-KEY is " " (i.e., the default) and the COM object supports the licensing mechanism, the control performs its own license verification. Some objects require a .lic file to do this. Others may check the system registry or hard disk for other properly installed and licensed software.

Format 2 (CREATE assembly-name) General Rules

  1. Literal values for assembly parameters are located in the COPY file generated by the NETDEFGEN utility. The same COPY file must be included in the SPECIAL-NAMES paragraph of your program.
  2. assembly-name is the name of a .NET assembly defined in the NETDEFGEN COPY file. This must be the DLL name of a non-graphical control, not an executable file. Non-graphical controls are generated by Visual Studio when a developer selects a "Class Library" project type.
  3. Namespace is a NameSpace in the assembly.
  4. Ccass-name is a class in the NameSpace.
  5. Version is the version number of the assembly.
  6. culture is cultural information related to the assembly.
  7. strong-name is the cryptographic key required to access the assembly, if any. If the assembly requires such a key, as all assemblies in the Global Assembly Cache (GAC) do, it is shown in the COPY file under the keyword STRONG.
  8. All classes that result in an object have a CONSTRUCTOR, which is a sort of method. If you see a CONSTRUCTOR identifier in the COPY file without a parameter list, the field may be omitted from your COBOL program. If all listed CONSTRUCTORs have parameters, then you must choose which CONSTRUCTOR and parameters to use. constructor(n) is the constructor that you want to use followed by its parameter data.
  9. module identifies a file where a combination of NameSpaces and Classes resides. It is used when the assembly is constructed of other assemblies.
  10. file-path is the path of an XML file, and that XML file contains the path where the .NET assembly is located. Use FILE-PATH when the assembly that you want to access does not reside in the GAC or in the same directory as wrun32.exe. Assemblies that reside in the GAC have the STRONG keyword in the NETDEFGEN COPY file.
    When using a C# assembly and Thin client, where the C# assembly is on the client, file-path points to an XML-FILE. The xml file needs to reside in the run time bin directory. Here is a sample XML file:
    <?xml version="1.0"?>
    <FILE_PATH>@[DISPLAY]:C:\path-on-client-where dll-resides</FILE_PATH>
    This allows a C# assembly to be executed on the client when running Thin client.