- Syntax 1: For windows of a known datatype
- Syntax 2: For windows of unknown datatype
- Syntax 3: For loading an OLE object from a file into a control
- Syntax 4: For opening an OLE object in memory into a control
- Syntax 5: For opening an OLE object in a file into an OLEStorage
- Syntax 6: For opening an OLE storage member into a storage
- Syntax 7: For opening OLE streams
- Syntax 8: For opening trace files
- Syntax 9: For opening a PDF file
Opens a window, an OLE object, or a trace file, or a PDF document.
For windows
Displays a window and makes all its properties and controls available to scripts.
For OLE objects
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 |
|
|
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 |
|
|
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
Opens the specified trace file for reading.
For PDFDocExtractor object
Open the specified PDF file.
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 } )
|
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. |
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.
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.
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.
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.
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
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 } )
|
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. |
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.
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 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)
NEXTThe 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])
NEXTSee also
Description
Opens an OLE object in a file and loads it into an OLE control.
Applies to
OLE controls
Syntax
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. |
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
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 )
|
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 |
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
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 } } )
|
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:
|
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.
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.
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 IFThis 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 IFSee also
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 )
|
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
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.
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.
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 IFSee also
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 } } )
|
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:
|
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 IFSee also
Description
Opens the specified trace file for reading.
Applies to
TraceFile object
Syntax
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 |
Return value
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! -- (Obsolete) This function is supported only in the Enterprise edition of PowerBuilder 12.6 and earlier versions.
-
SourcePBLError! -- The source libraries cannot be found
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
Description
Opens a PDF file.
Applies to
Syntax
long Open(string filePath)
long Open(string filePath, string password)
|
Argument |
Description |
|---|---|
|
filePath |
The path and file name of the file to be opened. The path must be an absolute path. |
|
password |
If required, the password of the PDF file. |
Return value
Long. Returns 1 if it succeeds and -1 if it fails. For more errors, see the Error Codes.
Usage
You use this syntax to access the contents of a PDF file.
Examples
This example opens the PDF file "D:\extract.pdf":
long ll_open
PDFDocExtractor lpdf_docExt
lpdf_docExt = create PDFDocExtractor
ll_open = lpdf_docExt.open("D:\extract.pdf" )
See also
