Close

Closes a window, an OLE storage or stream, or a trace file.

To close

Use

A window

Syntax 1

An OLEStorage object variable, saving the object and clearing connections between it and a storage file or object

Syntax 2

A stream associated with the specified OLEStream object variable

Syntax 3

A trace file

Syntax 4


Syntax 1: For windows

Description

Closes a window and releases the storage occupied by the window and all the controls in the window.

Applies to

Window objects

Syntax

Close ( windowname )

Argument

Description

windowname

The name of the window you want to close


Return value

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.

Usage

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.

Examples

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

See also

Hide

Open

Syntax 2: For OLEStorage objects

Description

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.

Applies to

OLEStorage objects

Syntax

olestorage.Close ( )

Argument

Description

olestorage

The OLEStorage object variable that you want to save and close


Return value

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.

Examples

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()

See also

Open

Save

SaveAs

Syntax 3: For OLEStream objects

Description

Closes an OLEStream object.

Applies to

OLEStream objects

Syntax

olestream.Close ( )

Argument

Description

olestream

The OLEStream object variable that you want to close


Return value

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.

Examples

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

See also

Open

Syntax 4: For trace files

Description

Closes an open trace file.

Applies to

TraceFile objects

Syntax

instancename.Close ( )

Argument

Description

instancename

Instance name of the TraceFile object


Return value

ErrorReturn. Returns one of the following values:

  • Success! -- The function succeeded

  • FileNotOpenError! -- A trace file has not been opened

Usage

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.

Examples

This example closes a trace file:

ift_file.Close()
DESTROY ift_file

See also

Reset

Open

NextActivity