PowerScript Reference
PowerScript Functions

Description

Opens a window object of a known datatype. Open displays the window and makes all its properties and controls available to scripts.

Applies to

Window objects

Syntax

Open ( windowvar {, parent } )

Return value

Integer.

Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, Open returns null.

Usage

You must open a window before you can access the properties of the window. If you access the window's properties before you open it, an execution error will occur.

To reference an open window in scripts, use windowvar.

To open an array of windows where each window has different datatype, use Syntax 2 of Open.

Parent windows for the opened window

Generally, if you are opening a child or a pop-up window and specify parent, the window identified by parent is the parent of the opened window (windowname or windowvar). When a parent window is closed, all its child and pop-up windows are closed too.

Not all types of windows can be parent windows. Only a window whose borders are not confined within another window can be a parent. A child window or a window opened as a sheet cannot be a parent.

If you specify a confined window as a parent, PowerBuilder checks its parent, and that window's parent, until it finds a window that it can use as a parent. Therefore if you open a pop-up window and specify a sheet as its parent, PowerBuilder makes the MDI frame that contains the sheet its parent.

If you do not specify a parent for a child or pop-up window, the active window becomes the parent. Therefore, if one pop-up is active and you open another pop-up, the first pop-up is the parent, not the main window. When the first pop-up is closed, PowerBuilder closes the second pop-up too.

However, in an MDI application, the active sheet is not the active window and cannot be the parent. In Windows, it is clear that the MDI frame, not the active sheet, is the active window -- its title bar is the active color and it displays the menu.

Because a response window grabs focus, you should not open it when focus is changing, such as in a LoseFocus event.

Examples

This statement opens an instance of a window named w_employee:

Open(w_employee)

The following statements open an instance of a window of the type w_employee:

w_employee w_to_open
Open(w_to_open)

The following code opens an instance of a window of the type child named cw_data and makes w_employee the parent:

child cw_data
Open(cw_data, w_employee)

The following code opens two windows of type w_emp:

w_emp w_e1, w_e2
Open(w_e1)
Open(w_e2)

See also

Close

OpenWithParm

Show

Description

Opens a window object when you do not know its datatype until the application is running. Open displays the window and makes all its properties and controls available to scripts.

Applies to

Window objects

Syntax

Open ( windowvar, windowtype {, parent } )

Return value

Integer.

Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, Open returns null.

Usage

You must open a window before you can access the properties of the window. If you access the window's properties before you open it, an execution error will occur.

To reference an open window in scripts, use windowvar.

The window object specified in windowtype must be the same datatype as windowvar (the datatype includes datatypes inherited from it). The datatype of windowvar is usually window, from which all windows are inherited, but it can be any ancestor of windowtype. If it is not the same type, an execution error will occur.

Use this syntax to open an array of windows when each window in the array will have a different datatype. See the last example, in which the window datatypes are stored in one array and are used for the windowtype argument when each window in another array is opened.

If windowtype is a descendant window, you can only reference properties, events, functions, or structures that are part of the definition of windowvar. For example, if a user event is declared for windowtype, you cannot reference it.

The object specified in windowtype is not automatically included in your executable application. To include it, you must save it in a PBD file (PowerBuilder dynamic library) that you deliver with your application.

For information about the parent of an opened window, see Syntax 1.

Examples

This example opens a window of the type specified in the string s_w_name and stores the reference to the window in the variable w_to_open. The SELECT statement retrieves data specifying the window type from the database and stores it in s_w_name:

window w_to_open
string s_w_name
 
SELECT next_window INTO  : s_w_name FROM routing_table
WHERE...  ;
 
Open(w_to_open, s_w_name)

This example opens an array of ten windows of the type specified in the string is_w_emp1 and assigns a title to each window in the array. The string is_w_emp1 is an instance variable whose value is a window type:

integer n
window win_array[10]
 
FOR n = 1 to 10
      Open(win_array[n], is_w_emp1)
      win_array[n].title = "Window " + string(n)
NEXT

The following statements open four windows. The type of each window is stored in the array w_stock_type. The window reference from the Open function is assigned to elements in the array w_stock_win:

window w_stock_win[ ]
string w_stock_type[4]
 
w_stock_type[1] = "w_stock_wine"
w_stock_type[2] = "w_stock_scotch"
w_stock_type[3] = "w_stock_beer"
w_stock_type[4] = "w_stock_soda"
 
FOR n = 1 to 4
      Open(w_stock_win[n], w_stock_type[n])
NEXT

See also

Close

OpenWithParm

Show

Description

Opens an OLE object in a file and loads it into an OLE control.

Applies to

OLE controls

Syntax

olecontrol.Open ( OLEsourcefile )

Return value

Integer.

Returns 0 if it succeeds and one of the following negative values if an error occurs:

-1 -- The file is not found or its data has an invalid format

-9 -- Other error

If any argument's value is null, Open returns null.

Examples

This example opens the object in the file MYSTUFF.OLE and loads it into in the control ole_1:

integer result
result = ole_1.Open("c:\ole2\mystuff.ole")

See also

InsertFile

Save

SaveAs

Description

Opens an OLE object that is in a OLE storage object in memory and loads it into an OLE control.

Applies to

OLE controls

Syntax

olecontrol.Open ( sourcestorage, substoragename )

Return value

Integer.

Returns 0 if it succeeds and one of the following negative values if an error occurs:

-2 -- The parent storage is not open

-9 -- Other error

If any argument's value is null, Open returns null.

Examples

This example opens the object in the substorage excel_obj within the storage variable stg_stuff and loads it into the control ole_1. Olest_stuff is already open:

integer result
result = ole_1.Open(stg_stuff, "excel_obj")

This example opens a substorage in the storage variable stg_stuff and loads it into the control ole_1. The substorage name is specified in the variable stuff_1. Olest_stuff is already open:

integer result
string stuff_1 = "excel_obj"
result = ole_1.Open(stg_stuff, stuff_1)

See also

InsertFile

Save

SaveAs

Description

Opens an OLE object in an OLE storage file and loads it into a storage object in memory.

Applies to

OLE storage objects

Syntax

olestorage.Open ( OLEsourcefile {, readmode {, sharemode } } )

Return value

Integer.

Returns 0 if it succeeds and one of the following negative values if an error occurs:

-1 -- The file is not an OLE storage file

-3 -- The file is not found

-9 -- Other error

If any argument's value is null, Open returns null.

Usage

An OLE storage file is structured like a directory. Each OLE object can contain other OLE objects (substorages) and other data (streams). You can open the members of an OLE storage belonging to a server application if you know the structure of the storage. However, the PowerBuilder functions for manipulating storages are provided so that you can build your own storage files for organizing the OLE objects used in your applications.

The whole file can be an OLE object and substorages within the file can also be OLE objects. More frequently, the structure for a storage file you create is a root level that is not an OLE object but contains independent OLE objects as substorages. Any level in the storage hierarchy can contain OLE objects or be simply a repository for another level of substorages.

Examples

This example opens the object in the file MYSTUFF.OLE and loads it into the OLEStorage variable stg_stuff:

integer result
OLEStorage stg_stuff
 
stg_stuff = CREATE OLEStorage
result = stg_stuff.Open("c:\ole2\mystuff.ole")

This example opens the same object for reading:

integer result
OLEStorage stg_stuff
 
stg_stuff = CREATE OLEStorage
result = stg_stuff.Open("c:\ole2\mystuff.ole", &
      stgRead!)

This example opens the object in the file MYSTUFF.OLE and loads it into the OLEStorage variable stg_stuff, as in the previous example. Then it opens the substorage drawing_1 into a second storage variable, using Syntax 6 of Open. This example does not include code to close and destroy any of the objects that were opened.

integer result
OLEStorage stg_stuff, stg_drawing
 
stg_stuff = CREATE OLEStorage
result = stg_stuff.Open("c:\ole2\mystuff.ole")
IF result >= 0 THEN
      stg_drawing = CREATE OLEStorage
      result = opest_drawing.Open("drawing_1", &
         stgRead!, stgDenyNone!, stg_stuff)
END IF

This example opens the object in the file MYSTUFF.OLE and loads it into the OLEStorage variable stg_stuff. Then it checks whether a stream called info exists in the OLE object, and if so, opens it with read access using Syntax 7 of Open. This example does not include code to close and destroy any of the objects that were opened.

integer result
boolean str_found
OLEStorage stg_stuff
OLEStream mystream
 
stg_stuff = CREATE OLEStorage
result = stg_stuff.Open("c:\ole2\mystuff.ole")
IF result < 0 THEN RETURN
 
result = stg_stuff.MemberExists("info", str_found)
IF result < 0 THEN RETURN
 
IF str_found THEN
      mystream = CREATE OLEStream
      result = mystream.Open(stg_stuff, "info", &
         stgRead!, stgDenyNone!)
      IF result < 0 THEN RETURN
END IF

See also

Close

Save

SaveAs

Description

Opens a member of an open OLE storage and loads it into another OLE storage object in memory.

Applies to

OLE storage objects

Syntax

olestorage.Open ( substoragename, readmode, sharemode, sourcestorage )

Return value

Return value

Integer.

Returns 0 if it succeeds and one of the following negative values if an error occurs:

-2 -- The parent storage is not open

-3 -- The member is not found (when opened for reading)

-9 -- Other error

If any argument's value is null, Open returns null.

Usage

An OLE storage file is structured like a directory. Each OLE object can contain other OLE objects (substorages) and other data (streams). You can open the members of an OLE storage belonging to a server application if you know the structure of the storage. However, PowerBuilder's functions for manipulating storages are provided so that you can build your own storage files for organizing the OLE objects used in your applications.

The whole file can be an OLE object and substorages within the file can also be OLE objects. More frequently, the structure for a storage file you create is a root level that is not an OLE object but contains independent OLE objects as substorages. Any level in the storage hierarchy can contain OLE objects or be simply a repository for another level of substorages.

Examples

This example opens the object in the file MYSTUFF.OLE and loads it into the OLEStorage variable stg_stuff, as in the previous example. Then it opens the substorage drawing_1 into a second storage variable. This example does not include code to close and destroy any of the objects that were opened.

integer result
OLEStorage stg_stuff, stg_drawing
 
stg_stuff = CREATE OLEStorage
result = stg_stuff.Open("c:\ole2\mystuff.ole")
IF result >= 0 THEN
      stg_drawing = CREATE OLEStorage
      result = opest_drawing.Open("drawing_1", &
         stgRead!, stgDenyNone!, stg_stuff)
END IF

See also

Close

Save

SaveAs

Description

Opens a stream in an open OLE storage object and loads it into an OLE stream object.

Applies to

OLE stream objects

Syntax

olestream.Open ( sourcestorage, streamname {, readmode {, sharemode } } )

Return value

Integer.

Returns 0 if it succeeds and one of the following negative values if an error occurs:

-1 -- Stream not found

-2 -- Stream already exists

-3 -- Stream is already open

-4 -- Storage not open

-5 -- Access denied

-6 -- Invalid name

-9 -- Other error

If any argument's value is null, Open returns null.

Examples

This example opens the object in the file MYSTUFF.OLE and loads it into the OLEStorage variable stg_stuff. Then it checks whether a stream called info exists in the OLE object, and if so, opens it with read access. This example does not include code to close and destroy any of the objects that were opened.

integer result
boolean str_found
OLEStorage stg_stuff
OLEStream mystream
 
stg_stuff = CREATE OLEStorage
result = stg_stuff.Open("c:\ole2\mystuff.ole")
IF result < 0 THEN RETURN
 
result = stg_stuff.MemberExists("info", str_found)
IF result < 0 THEN RETURN
 
IF str_found THEN
      mystream = CREATE OLEStream
      result = mystream.Open(stg_stuff, "info", &
         stgRead!, stgDenyNone!)
      IF result < 0 THEN RETURN
END IF

See also

Close

Description

Opens the specified trace file for reading.

Applies to

TraceFile object

Syntax

instancename.Open ( filename )

Return value

ErrorReturn. Returns one of the following values:

Usage

You use this syntax to access the contents of a specified trace file created from a running PowerBuilder application. You can then use the properties and functions provided by the TraceFile object to perform your own analysis of tracing data instead of using the available modeling objects.

Examples

This example opens a trace file:

TraceFile ltf_file
String ls_filename
 
ltf_file = CREATE TraceFile
ltf_file.Open(ls_filename)
...

See also

Close

Reset

NextActivity