create Instruction

The create instruction creates an instance of a class, and assigns it to a variable or a property.

Syntax

The syntax of the create instruction is:

create entity [as expression] [transient | persistent | sharedTransient];

The entity value can be a property expression, a local variable, or a formal parameter.

The syntax of the extended create instruction, which applies to version 2018.0.01 and higher, retrieves the object reference using an assignment instruction, is as follows.

reference := create class‑name(parameters) lifetime;

From Jade 2020.0.02, an assignment statement is no longer required to use the extended create instruction. It can now be used as an expression in any of the following situations.

Right‑hand side expression of an assignment statement
An input or constant parameter in a method call
The expression of a return instruction
As a parameter to a superclass parameterized constructor within a create method

Exception 6801 (Cannot assign to create expression) is raised if you attempt to assign an extended create expression as the value of an io or output parameter.

Description

You can optionally specify a class expression in the as clause of the create instruction but you cannot specify a class expression in the as clause of the extended create instruction. The class does not need to be an explicit class name; it can be a variable or any valid expression that yields a class. However, the class name must be explicit in the extended create instruction.

The as clause in the extended create instruction from version 2018.0.01 and higher is not supported, because the class name must be specified so that the compiler can validate the signature of the create method call.

You cannot use the create instruction without parameters if the class of the object being created has a constructor that has parameters.

The extended create instruction syntax is allowed for any class, with or without an explicit constructor with or without parameters.

The transient, persistent, and sharedTransient modifiers specify whether the instance of the class being created is transient, shared transient, or persistent. If the modifier is omitted, the default lifetime for the class is used.

For details about:

Constructor create methods, see "Using Constructors and Destructors", in Chapter 4 of the Development Environment User's Guide.
Shared transient transactions, see "beginTransientTransaction", earlier in this chapter. See also "Sharing Uncommitted Persistent Objects".
For details about the RootSchema classes for which you can create persistent instances, see "Instructions for Creating and Deleting Objects".

The create instruction on a Form subclass creates a GUI form. If you want to create a print form at run time that simulates the entire GUI process, use the GUIClass class createPrintForm method. (For details, see Chapter 1 of the Encyclopaedia of Classes.)

create Instruction Examples

The following example shows the use of the create instruction without parameters.

createEmployee(newName, newAddress, newPhone: String;
               newBirthDate: Date): Employee;
vars
    newEmployee : Employee;
begin
    create newEmployee;
    newEmployee.name      := newName;
    newEmployee.address   := newAddress;
    newEmployee.phone     := newPhone;
    newEmployee.birthDate := newBirthDate;
    return newEmployee;
end;

The following example shows the use of the as clause in the create instruction.

createFault(faultType: Character): Fault;
vars
    fault : Fault;
begin
    if faultType = "N" then
        create fault as NewFeatureSuggestion;
    elseif faultType = "D" then
        create fault as DocumentationFault;
    else
        create fault as NormalFault;
    endif;
    ...                        // Do other initialization
    return fault;
end;

The following example shows the use of the create instruction without parameters when the class is not an explicit class name.

createFault(faultClass: Class): Fault;
vars
    fault : Fault;
begin
    create fault as faultClass;
    ...                        // Do other initialization
    return fault;
end;

Extended create Instruction Examples

The following example is an Employee class create method with parameters.

create(newName, newAddress, newPhone: String; newBirthDate: Date) updating;
begin
    name := newName;
    address := newAddress;
    phone := newPhone;
    birthDate := newBirthDate;
end;

The following is an example of an extended create instruction based on the above Employee class create method with parameters being used in an assignment statement.

createEmployee(newName, newAddress, newPhone: String; 
               newBirthDate: Date): Employee;
vars
    newEmployee : Employee;
begin
    newEmployee := create Employee(newName, newAddress, newPhone, newBirthDate);
    return newEmployee;
end;

The following is an example of an extended create instruction based on the above Employee class create method with parameters being used as a method call parameter.

addToCollection(employees: EmployeeDict; name, address, phone: String; 
                birthdate: Date);
begin
    employees.add(create Employee(name, address, phone, birthdate));
end;

The following is an example of an extended create instruction based on the above Employee class create method with parameters being used as a return instruction expression.

createEmployeeIfValid(name, address, phone: String; birthdate: Date): 
                      Employee typeMethod;
begin
    if not validateEmployeeParams(name, address, phone, birthdate) then
        return null;
    endif;
    return create Employee(name, address, phone, birthdate);
end;