About this chapter
This chapter describes how to build and use structures.
A structure is a collection of one or more related variables of the same or different datatypes grouped under a single name. In some languages, such as Pascal and COBOL, structures are called records.
Structures allow you to refer to related entities as a unit rather than individually. For example, if you define the user's ID, address, access level, and a picture (bitmap) of the employee as a structure called s_employee, you can then refer to this collection of variables as s_employee.
Two kinds
There are two kinds of structures:
-
Global structures, which are not associated with any object in your application. You can declare an instance of the structure and reference the instance in any script in your application.
-
Object-level structures, which are associated with a particular type of window, menu, or user object, or with the Application object. These structures can always be used in scripts for the object itself. You can also choose to make the structures accessible from other scripts.
When you design your application, think about how the structures you are defining will be used:
-
If the structure is general-purpose and applies throughout the application, make it a global structure.
-
If the structure applies only to a particular type of object, make it an object-level structure.
Although you define object-level structures in the painter for a specific object and global structures in the Structure painter, in both cases you define the structure in a Structure view. The following sections describe each of the steps you take to define a new structure:
-
Open a Structure view.
-
For object-level structures, name the structure.
-
Define the variables that make up the structure.
-
Save the structure.
Opening a Structure view
How you open the Structure view depends on whether you are defining an object-level structure or a global structure.
To define an object-level structure:
-
Open the object for which you want to declare the structure.
You can declare structures for windows, menus, user objects, or applications.
-
Select Insert>Structure from the menu bar.
A Structure view opens.
To define a global structure:
-
Select Structure from the Objects tab in the New dialog box.
The Structure painter opens. It has one view, the Structure view. In the Structure painter, there is no Structure Name text box in the Structure view.
If you are defining an object-level structure, you name it in the Structure Name box in the Structure view. If you are defining a global structure, you name it when you save the structure.
Structure names can have up to 40 characters. For information about valid characters, see the the section called “Identifier names” in PowerScript Reference.
You might want to adopt a naming convention for structures so that you can recognize them easily. A common convention is to preface all global structure names with s_ and all object-level structure names with str_.
Defining the variables
To define the variables that compose the structure:
-
Enter the datatype of a variable that you want to include in the structure.
The default for the first variable is string; the default for subsequent variables is the datatype of the previous variable. You can specify any PowerBuilder datatype, including the standard datatypes such as integer and string, as well as objects and controls such as Window or MultiLineEdit.
You can also specify any object types that you have defined. For example, if you are using a window named w_calculator that you have defined and you want the structure to include the window, type w_calculator as the datatype. (You cannot select w_calculator from the list, since the list shows only built-in datatypes.)
A structure as a variable
A variable in a structure can itself be a structure. Specify the structure's name as the variable's datatype.
Specifying decimal places
If you select decimal as the datatype, the default number of decimal places is 2. You can also select decimal{2} or decimal{4} to specify 2 or 4 decimal places explicitly.
-
Enter the name of the variable.
-
Repeat until you have entered all the variables.
Saving the structure
How you save the structure depends on whether it is an object-level structure or a global structure.
The names of object-level structures are added to the Structure List view and display in the title bar of the Structure view as soon as you tab off the Structure Name box. As you add variables to the structure, the changes are saved automatically. When you save the object that contains the structure, the structure is saved as part of the object in the library where the object resides.
Comments and object-level structures
You cannot enter comments for an object-level structure, because it is not a PowerBuilder object.
To name and save a global structure:
-
Select File>Save from the menu bar, or close the Structure painter.
The Save Structure dialog box displays.
-
Name the structure.
See Naming the structure.
-
(Optional) Add comments to describe your structure.
-
Choose the library in which to save the structure.
-
Click OK.
PowerBuilder stores the structure in the specified library. You can view the structure as an independent entry in the Library painter.
To modify a structure:
-
Do one of the following:
-
In the Open dialog box, select the global structure you want to modify.
-
Open the painter for the object that contains the object-level structure and select the structure from the Structure List view.
-
-
If the Structure List view is not open, select it from the View menu.
-
Review the variable information displayed in the Structure view and modify the structure as necessary.
To insert a variable before an existing variable, highlight it and select Insert>Row from the menu bar or Insert Row from the pop-up menu.
To delete a variable, select Delete Row from the pop-up menu.
-
Save the modified structure.
Building a similar structure
If you want to create a structure that is similar to one that already exists, you can use the existing structure as a starting point and modify it.
After you define the structure, you can:
-
Reference an instance of the structure in scripts and functions
-
Pass the structure to functions
-
Display and paste information about structures by using the Browser
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
-
Declare a variable of the structure type.
-
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.
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
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.
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
-
Select the Structure tab and select a structure.
-
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
-
Select the tab for the type of object for which the structure is defined.
-
Select the object that contains the structure.
-
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
-
Scroll to the structure variable you want to paste.
-
Select Copy from the variable's pop-up menu.
-
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.
