Creates an object instance for a specified object type. After a CREATE statement, properties of the created object instance can be referenced using dot notation.
The CREATE statement returns an object instance that can be stored in a variable of the same type.
Syntax 1 specifies the object type at compilation. Syntax 2 allows the application to choose the object type dynamically.
Syntax 1 (specifies the object type at compilation):
objectvariable = CREATE objecttype
Parameter |
Description |
|---|---|
objectvariable |
A global, instance, or local variable whose datatype is objecttype |
objecttype |
The object datatype |
Syntax 2 (allows the application to choose the object type dynamically):
objectvariable = CREATE USING objecttypestring
Parameter |
Description |
|---|---|
objectvariable |
A global, instance, or local variable whose datatype is the same class as the object being created or an ancestor of that class |
objecttypestring |
A string whose value is the name of the class datatype to be created |
Use CREATE as the first reference to any class user object. This includes standard class user objects such as mailSession or Transaction.
The system provides one instance of several standard class user objects: Message, Error, Transaction, DynamicDescriptionArea, and DynamicStagingArea. You only need to use CREATE if you declare additional instances of these objects.
If you need a menu that is not part of an open window definition, use CREATE to create an instance of the menu. (See the function PopMenu.)
To create an instance of a visual user object or window, use the appropriate Open function (instead of CREATE).
You do not need to use CREATE to allocate memory for:
A standard datatype, such as integer or string
Any structure, such as the Environment object
Any object whose AutoInstantiate setting is true
Any object that has been instantiated using a function, such as Open
CREATE USING allows your application to choose the object type dynamically. It is usually used to instantiate an ancestor variable with an instance of one of its descendants. The particular descendant is chosen at execution time.
For example, if uo_a has two descendants, uo_a_desc1 and uo_a_desc2, then the application can select the object to be created based on current conditions:
uo_a uo_a_var
string ls_objectname
IF ... THEN
ls_objectname = "uo_a_desc1"
ELSE
ls_objectname = "uo_a_desc2"
END IF
uo_a_var = CREATE USING ls_objectname
When you have finished with an object you created, you can call DESTROY to release its memory. However, you should call DESTROY only if you are sure that the object is not referenced by any other object. PowerBuilder’s garbage collection mechanism maintains a count of references to each object and destroys unreferenced objects automatically.
For more information about garbage collection, see “Garbage collection”.
Example 1 These statements create a new transaction object and stores the object in the variable DBTrans:
transaction DBTrans
DBTrans = CREATE transaction
DBTrans.DBMS = 'ODBC'
Example 2 These statements create a user object when the application has need of the services it provides. Because the user object might or might not exist, the code that accesses it checks whether it exists before calling its functions.
The object that creates the service object declares invo_service as an instance variable:
n_service invo_service
The Open event for the object creates the service object:
//Open event of some object
IF (some condition) THEN
invo_service = CREATE n_service
END IF
When another script wants to call a function that belongs to the n_service class, it verifies that invo_service is instantiated:
IF IsValid(invo_service) THEN
invo_service.of_perform_some_work( )
END IF
If the service object was created, then it also needs to be destroyed:
IF isvalid(invo_service) THEN DESTROY invo_service
Example 3 When you create a DataStore object, you also have to give it a DataObject and call SetTransObject before you can use it:
l_ds_delete = CREATE u_ds
l_ds_delete.DataObject = 'd_user_delete'
l_ds_delete.SetTransObject(SQLCA)
li_cnt = l_ds_delete.Retrieve(lstr_data.name)
Example 4 In this example, n_file_service_class is an ancestor object, and n_file_service_class_ansi and n_file_service_class_dbcs are its descendants. They hold functions and variables that provide services for the application. The code chooses which object to create based on whether the user is running in a DBCS environment:
n_file_service_class lnv_fileservice
string ls_objectname
environment luo_env
GetEnvironment ( luo_env )
IF luo_env.charset = charsetdbcs! THEN
ls_objectname = "n_file_service_class_dbcs"
ELSE
ls_objectname = "n_file_service_class_ansi"
END IF
lnv_fileservice = CREATE USING ls_objectname
