Closes a window, an OLE storage or stream, or a trace file.
To close |
Use |
|---|---|
A window |
|
An OLEStorage object variable, saving the object and clearing connections between it and a storage file or object |
|
A stream associated with the specified OLEStream object variable |
|
A trace file |
Closes a window and releases the storage occupied by the window and all the controls in the window.
Window objects
Close ( windowname )
Argument |
Description |
|---|---|
windowname |
The name of the window you want to close |
Integer. Returns 1 if it succeeds and -1 if an error occurs. If windowname is null, Close returns null. The return value is usually not used.
Use Syntax 1 to close a window and release the storage occupied by the window and all the controls in the window.
When you call Close, PowerBuilder removes the window from view, closes it, executes the scripts for the CloseQuery and Close events (if any), and then executes the rest of the statements in the script that called the Close function. Do not call Close from the CloseQuery or Close events, since this produces an endless loop.
After a window is closed, its properties, instance variables, and controls can no longer be referenced in scripts. If a statement in the script references the closed window or its properties or instance variables, an execution error will result.
Closing a window by calling the Close function in any of the window's events or in an event of any control on the window can cause PowerBuilder to crash if the Close function is not the last statement in the event script. You can avoid this issue by calling the Close function in the last statement of the event script, or in a user-defined event that is posted from the event script. For example, the following code in the Open event script for a window called w_1 can cause a crash:
// w_1 Open event script close(this) open(w_2) // causes crash
This code does not cause a crash:
// w_1 ue_postopen event script close(this)
// w_1 Open event script open(w_2) this.Post Event ue_postopen()
Preventing a window from closing
You can prevent a window from being closed with a return code
of 1 in the script for the CloseQuery event. Use the RETURN statement.
These statements close the window w_employee and then open the window w_departments:
Close(w_employee)
Open(w_departments)
After you call Close, the following statements in the script for the CloseQuery event prompt the user for confirmation and prevent the window from closing:
IF MessageBox('ExitApplication', &
'Exit?', Question!, YesNo!) = 2 THEN
// If no, stop window from closing
RETURN 1
END IF
Closes an OLEStorage object, saving the object in the associated storage file or object and clearing the connection between them. Close also severs connections with any OLE controls that have opened the object. Calling Close is the same as calling Save and then Clear.
OLEStorage objects
olestorage.Close ( )
Argument |
Description |
|---|---|
olestorage |
The OLEStorage object variable that you want to save and close |
Integer. Returns 0 if it succeeds and one of the following negative values if an error occurs:
-1 The storage is not open
-9 Other error
If olestorage is null, Close returns null.
This example saves and clears the object in the OLEStorage object variable olest_stuff. It also leaves any OLE controls that have opened the object in olest_stuff empty:
integer result
result = olest_stuff.Close()
Closes an OLEStream object.
OLEStream objects
olestream.Close ( )
Argument |
Description |
|---|---|
olestream |
The OLEStream object variable that you want to close |
Integer. Returns 0 if it succeeds and one of the following negative values if an error occurs:
-1 The storage is not open
-9 Other error
If olestream is null, Close returns null.
This example closes the OLEStream object stm_pic_label and releases the variable’s memory:
integer result
result = stm_pic_label.Close()
DESTROY stm_pic_label
Closes an open trace file.
TraceFile objects
instancename.Close ( )
Argument |
Description |
|---|---|
instancename |
Instance name of the TraceFile object |
ErrorReturn. Returns one of the following values:
Success! – The function succeeded
FileNotOpenError! – A trace file has not been opened
You use the Close function to close a trace file you previously opened with the Open function. You use the Close and Open functions as well as the properties and functions of the TraceFile object to access the contents of a trace file directly. You use these functions if you want to perform your own analysis of the tracing data instead of building a model with the Profiling or TraceTree object and the BuildModel function.
This example closes a trace file:
ift_file.Close()
DESTROY ift_file
