Opens a window, an OLE object, or a trace file.
For windows Open displays a window and makes all its properties and controls available to scripts.
To |
Use |
|---|---|
Open an instance of a particular window datatype |
|
Allow the application to select the window’s datatype when the script is executed |
For OLE objects Open loads an OLE object contained in a file or storage into an OLE control or storage object variable. The source and the target are then connected for the purposes of saving work.
To open |
Use |
|---|---|
An OLE object in a file and load it into an OLE control |
Syntax 3 For loading an OLE object from a file into a control |
An OLE object in a storage object in memory and load it into an OLE control |
|
An OLE object in an OLE storage file and load it into a storage object in memory |
Syntax 5 For opening an OLE object in a file into an OLEStorage |
An OLE object that is a member of an open OLE storage and load it into a storage object in memory |
|
A stream in an OLE storage object in memory and load it into a stream object |
For trace files Open opens the specified trace file for reading.
To |
Use |
|---|---|
Open a trace file |
Opens a window object of a known datatype. Open displays the window and makes all its properties and controls available to scripts.
Window objects
Open ( windowvar {, parent } )
Argument |
Description |
|---|---|
windowvar |
The name of the window you want to display. You can specify a window object defined in the Window painter (which is a window datatype) or a variable of the desired window datatype. Open places a reference to the opened window in windowvar. |
parent (child and pop-up windows only) (optional) |
The window you want make the parent of the child or pop-up window you are opening. If you open a child or pop-up window and omit parent, PowerBuilder associates the window being opened with the currently active window. |
Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument’s value is null, Open returns null.
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.
Calling Open twice
If you call Syntax 1 of the Open function
twice for the same window, PowerBuilder activates the window twice;
it does not open two instances of the window.
To open an array of windows where each window has different datatype, use Syntax 2 of Open.
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.
Mouse behavior and response windows
Controls capture the mouse in order to perform certain operations.
For instance, CommandButtons capture during mouse clicks, edit controls
capture for text selection, and scroll bars capture during scrolling.
If a response window is opened while the mouse is captured, unexpected
results can occur.
Because a response window grabs focus, you should not open it when focus is changing, such as in a LoseFocus event.
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)
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.
Window objects
Open ( windowvar, windowtype {, parent } )
Argument |
Description |
|---|---|
windowvar |
A window variable, usually of datatype window. Open places a reference to the opened window in windowvar. |
windowtype |
A string whose value is the datatype of the window you want to open. The datatype of windowtype must be the same or a descendant of windowvar. |
parent (child and pop-up windows only) (optional) |
The window you want to make the parent of the child or pop-up window you are opening. If you open a child or pop-up window and omit parent, PowerBuilder associates the window being opened with the currently active window. |
Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument’s value is null, Open returns null.
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.
Considerations when specifying a window type
When you use Syntax 2, PowerBuilder opens an instance of a
window of the datatype specified in windowtype and
places a reference to this instance in the variable windowvar.
If windowtype is a descendent 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 For windows of a known datatype.
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
Opens an OLE object in a file and loads it into an OLE control.
OLE controls
olecontrol.Open ( OLEsourcefile )
Argument |
Description |
|---|---|
olecontrol |
The name of the OLE control into which you want to load an OLE object. |
OLEsourcefile |
A string specifying the name of an OLE storage file containing the object. The file must already exist and contain an OLE object. OLEsourcefile can include a path for the file, as well as path information inside the OLE storage. |
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.
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")
Opens an OLE object that is in a OLE storage object in memory and loads it into an OLE control.
OLE controls
olecontrol.Open ( sourcestorage, substoragename )
Argument |
Description |
|---|---|
olecontrol |
The name of the OLE control into which you want to load an OLE object |
sourcestorage |
The name of an object variable of OLEStorage containing the object you want to load into olecontrol |
substoragename |
A string specifying the name of a substorage that contains the desired object within storagename |
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.
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)
Opens an OLE object in an OLE storage file and loads it into a storage object in memory.
OLE storage objects
olestorage.Open ( OLEsourcefile {, readmode {, sharemode } } )
Argument |
Description |
|---|---|
olestorage |
The name of an object variable of type OLEStorage into which you want to load the OLE object. |
OLEsourcefile |
A string specifying the name of an OLE storage file containing the object. The file must already exist and contain OLE objects. OLEsourcefile can include the file’s path, as well as path information within the storage. |
readmode (optional) |
A value of the enumerated datatype stgReadMode that specifies the type of access you want for OLEsourcefile. Values are:
|
sharemode (optional) |
A value of the enumerated datatype stgShareMode that specifies how other attempts, by your own or other applications, to open OLEsourcefile will fare. Values are:
|
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.
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.
Opening nested objects
Because you can specify path information within an OLE storage
with a backslash as the separator, you can open a deeply nested
object with a single call to Open. However, there
is no error checking for the path you specify and if the Open fails,
you wo not know why. It is strongly recommended that you open each
object in the path until you get to the one you want.
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
Opens a member of an open OLE storage and loads it into another OLE storage object in memory.
OLE storage objects
olestorage.Open ( substoragename, readmode, sharemode, sourcestorage )
Argument |
Description |
|---|---|
olestorage |
The name of a object variable of type OLEStorage into which you want to load the OLE object. |
substoragename |
A string specifying the name of the storage member within sourcestorage that you want to open. Note the reversed order of the sourcestorage and substoragename arguments from Syntax 4. |
readmode |
A value of the enumerated datatype stgReadMode that specifies the type of access you want for substoragename. Values are:
|
sharemode |
A value of the enumerated datatype stgShareMode that specifies how other attempts, by your own or other applications, to open substoragename will fare. Values are:
|
sourcestorage |
An open OLEStorage object containing 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
-3 The member is not found (when opened for reading)
-9 Other error
If any argument’s value is null, Open returns null.
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.
Opening nested objects
Because you can specify path information within an OLE storage
with a backslash as the separator, you can open a deeply nested
object with a single call to Open. However, there
is no error checking for the path you specify and if the Open fails,
you will not know why. It is strongly recommended that you open
each object in the path until you get to the one you want.
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
Opens a stream in an open OLE storage object and loads it into an OLE stream object.
OLE stream objects
olestream.Open ( sourcestorage, streamname {, readmode {, sharemode } } )
Argument |
Description |
|---|---|
olestream |
The name of a object variable of type OLEStream into which you want to load the OLE object. |
sourcestorage |
An OLE storage that contains the stream to be opened. |
streamname |
A string specifying the name of the stream within sourcestorage that you want to open. |
readmode (optional) |
A value of the enumerated datatype stgReadMode that specifies the type of access you want for streamname. Values are:
|
sharemode (optional) |
A value of the enumerated datatype stgShareMode that specifies how other attempts, by your own or other applications, to open streamname will fare. Values are:
|
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.
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
Opens the specified trace file for reading.
TraceFile object
instancename.Open ( filename )
Argument |
Description |
|---|---|
instancename |
Instancename of the TraceFile object |
filename |
A string identifying the name of the trace file you want to read |
ErrorReturn. Returns one of the following values:
Success! – The function succeeded
FileAlreadyOpenError! – The specified trace file has already been opened
FileOpenError! – The trace file can not be opened for reading
FileInvalidFormatError! – The file does not have the correct format
EnterpriseOnlyFeature! – This function is supported only in the Enterprise edition of PowerBuilder
SourcePBLError! – The source libraries cannot be found
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.
This example opens a trace file:
TraceFile ltf_file
String ls_filename
ltf_file = CREATE TraceFile
ltf_file.Open(ls_filename)
...
