Using structures

After you define the structure, you can:

  1. Reference an instance of the structure in scripts and functions

  2. Pass the structure to functions

  3. Display and paste information about structures by using the Browser

Referencing structures

When you define a structure, you are defining a new datatype. You can use this new datatype in scripts and user-defined functions as long as the structure definition is stored in a library in the application's library search path.

To use a structure in a script or user-defined function

  1. Declare a variable of the structure type.

  2. Reference the variable in the structure.

Referencing global structures

The variables in a structure are similar to the properties of a PowerBuilder object. To reference a global structure's variable, use dot notation:

structure.variable

Example. Assume that s_empdata is a global structure with the variables emp_id, emp_dept, emp_fname, emp_lname, and emp_salary. To use this structure definition, declare a variable of type s_empdata and use dot notation to reference the structure's variables, as shown in the following script:

s_empdata   lstr_emp1, lstr_emp2 // Declare 2 variables
                             // of type emp_data.

lstr_emp1.emp_id = 100       // Assign values to the
lstr_emp1.emp_dept = 200     // structure variables.
lstr_emp1.emp_fname = "John"
lstr_emp1.emp_lname = "Paul-Jones"
lstr_emp1.emp_salary = 99908.23

// Retrieve the value of a structure variable.
lstr_emp2.emp_salary = lstr_emp1.emp_salary * 1.05

// Use a structure variable in a
// PowerScript function.
MessageBox ("New Salary", &
   String(lstr_emp2.emp_salary,"$###,##0.00"))

Referencing object-level structures

You reference object-level structures in scripts for the object itself exactly as you do global structures: declare a variable of the structure type, then use dot notation:

structure.variable

Example. Assume that the structure str_custdata is defined for the window w_history and you are writing a script for a CommandButton in the window. To use the structure definition in the script, you write:

str_custdata lstr_cust1
lstr_cust1.name = "Joe"

No access to object-level structures outside the object

You cannot make object-level structures accessible outside the object because object-level structures are implicitly private.

Copying structures

To copy the values of a structure to another structure of the same type

  • Assign the structure to be copied to the other structure using this syntax:

    struct1 = struct2

PowerBuilder copies all the variable values from struct2 to struct1.

Example. These statements copy the values in lstr_emp2 to lstr_emp1:

str_empdata lstr_emp1, lstr_emp2
...
lstr_emp1 = lstr_emp2

Using structures with functions

You can pass structures as arguments in user-defined functions. Simply name the structure as the datatype when defining the argument.Similarly, user-defined functions can return structures. Name the structure as the return type for the function.

You can also define external functions that take structures as arguments.

Example. Assume the following:

  • Revise is an external function that expects a structure as its argument.

  • lstr_empdata is a declared variable of a structure datatype.

You can call the function as follows:

Revise(lstr_empdata)

Declare the function first

The external function must be declared before you can reference it in a script.

For more about passing arguments to external functions, see the section called “Passing arguments” in Application Techniques.

Displaying and pasting structure information

You can display the names and variables of defined structures in the Browser. You can also paste these entries into a script.

To display information about a global structure in the Browser

  1. Select the Structure tab and select a structure.

  2. Double-click the properties folder in the right pane.

    The properties folder expands to show the structure variables as properties of the structure.

To display information about an object-level structure in the Browser

  1. Select the tab for the type of object for which the structure is defined.

  2. Select the object that contains the structure.

  3. Double-click the structure folder in the right pane.

    The structure folder expands to display the structure variables using dot notation.

To paste the information into a script

  1. Scroll to the structure variable you want to paste.

  2. Select Copy from the variable's pop-up menu.

  3. Insert the cursor in the script where you want to paste the variable and select Paste from the pop-up menu.

    The variable name displays at the insertion point in the script.