SaveAs

Saves the contents of a DataWindow, DataStore, graph, OLE control, or OLE storage in a file. The syntax you use depends on the type of object you want to save.

For DataWindow and DataStore syntax, see the SaveAs method for DataWindows in the section called “SaveAs” in DataWindow Reference.

To

To

Save the data in a graph

Syntax 1

Save the OLE object in an OLE control to a storage file

Syntax 2

Save the OLE object in an OLE control to a storage object in memory

Syntax 3

Save an OLE storage and any controls that have opened that storage in a file

Syntax 4

Save an OLE storage object in another OLE storage object

Syntax 5


Syntax 1: For graph objects

Description

Saves the data in a graph in the format you specify.

Applies to

Graph controls in windows and user objects, and graphs in DataWindow controls and DataStores

Syntax

controlname.SaveAs ( { filename, } { graphcontrol, saveastype, colheading { , encoding } } )

Argument

Description

controlname

The name of the graph control whose contents you want to save or the name of the DataWindow DataStore containing the graph.

filename (optional)

A string whose value is the name of the file in which you want to save the data in the graph. If you omit filename or specify an empty string (""), PowerBuilder prompts the user for a file name.

graphcontrol (DataWindow control only) (optional)

A string whose value is the name of the graph in the DataWindow control or DataStore whose contents you want to save.

saveastype (optional)

A value of the SaveAsType enumerated datatype specifying the format in which to save the data represented in the graph. Values are:

  • Clipboard! -- Save an image of the graph to the clipboard

  • CSV! -- Comma-separated values

  • dBASE2! -- dBASE-II format

  • dBASE3! -- dBASE-III format

  • DIF! -- Data Interchange Format

  • EMF! -- Enhanced Metafile Format

  • Excel! -- Microsoft Excel format

  • Excel5! -- Microsoft Excel version 5 format

  • Excel8! -- Microsoft Excel version 8 and higher format

  • HTMLTable! -- HTML TABLE, TR, and TD elements

  • PDF! -- Adobe Portable Document Format

  • PSReport! -- Powersoft Report (PSR) format

  • SQLInsert! -- SQL syntax

  • SYLK! -- Microsoft Multiplan format

  • Text! -- (Default) Tab-separated columns with a return at the end of each row

  • WKS! -- Lotus 1-2-3 format

  • WK1! -- Lotus 1-2-3 format

  • WMF! -- Windows Metafile Format

  • XLSB! -- Excel 2007 format for binary data

  • XLSX! -- Excel 2007 format for XML data

  • XML! -- Extensible Markup Language

  • XSLFO! -- Extensible Stylesheet Language Formatting Objects

Obsolete values

The following SaveAsType values are considered to be obsolete and will be removed in a future release: Excel!, WK1!, WKS!, SYLK!, dBase2!, WMF!. Use Excel8!, XLSB!, or XLSX! for current versions of Microsoft Excel! and EMF! in place of WMF!.

colheading (optional)

A boolean value indicating whether you want column headings with the saved data. The default value is true. Colheading is ignored for dBASE files; column headings are always saved.

encoding (optional)

Character encoding of the file to which the data is saved. This parameter applies only to the following formats: TEXT, CSV, SQL, HTML, and DIF. If you do not specify an encoding parameter, the file is saved in ANSI format. Values are:

  • EncodingANSI! (default)

  • EncodingUTF8!

  • EncodingUTF16LE!

  • EncodingUTF16BE!


Return value

Integer.

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

Usage

You must use zero or three arguments. If you do not specify any arguments for SaveAs, PowerBuilder displays the Save As dialog box, letting the user specify the format of the saved data.

Regional settings

If you use date formats in your graph, you must verify that yyyy is the Short Date Style for year in the Regional Settings of the user's Control Panel. Your program can check this with the RegistryGet function.

If the setting is not correct, you can ask the user to change it manually or to have the application change it (by calling the RegistrySet function). The user may need to reboot after the setting is changed.

Examples

This statement saves the contents of the graph gr_History. The file and format information are not specified, so PowerBuilder prompts for the file name and save the graph as tab-delimited text:

gr_History.SaveAs()

This statement saves the contents of gr_History to the file G:\HR\EMPLOYEE.HIS. The format is CSV without column headings:

gr_History.SaveAs("G:\HR\EMPLOYEE.HIS" ,CSV!, FALSE)

This statement saves the contents of gr_computers in the DataWindow control dw_equipmt to the file G:\INVENTORY\SALES.XLS. The format is Excel with column headings:

dw_equipmt.SaveAs("gr_computers", &
      "G:\INVENTORY\SALES.XLS", Excel!, TRUE)

See also

Print

Syntax 2: For saving an OLE control to a file

Description

Saves the object in an OLE control in a storage file.

Applies to

OLE controls

Syntax

olecontrol.SaveAs (OLEtargetfile )

Argument

Description

olecontrol

The name of the OLE control containing the object you want to save.

OLEtargetfile

A string specifying the name of an OLE storage file. The file can already exist. OLEtargetfile can include a path, as well as information about where to store the object in the file's internal structure.


Return value

Integer.

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

-1 -- The control is empty

-2 -- The storage is not open

-3 -- The storage name is invalid

-9 -- Other error

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

Usage

The Open function establishes a connection between a storage file and a storage object, or a storage file or object and an OLE control. The Save function uses this connection to save the OLE data.

When you call SaveAs for an OLE control, it closes the current connection between the OLE object and its storage, either file or storage object. It establishes a new connection with the new storage, which will be the target of subsequent calls to the Save function.

Examples

This example saves the object in the control ole_1:

integer result
result = ole_1.SaveAs("c:\ole\expense.ole")

See also

Open

Save

Syntax 3: For saving an OLE control to an OLE storage

Description

Saves the object in an OLE control to an OLE storage object in memory.

Applies to

OLE controls

Syntax

olecontrol.SaveAs ( targetstorage, substoragename )

Argument

Description

olecontrol

The name of the OLE control containing the object you want to save.

targetstorage

The name of an object variable of OLEStorage in which to store the object in olecontrol.

substoragename

A string whose value is the name of a substorage within targetstorage. If substorage does not exist, SaveAs creates it.


Return value

Integer.

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

-1 -- The control is empty

-2 -- The storage is not open

-3 -- The storage name is invalid

-9 -- Other error

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

Usage

The Open function establishes a connection between a storage file and a storage object, or a storage file or object and an OLE control. The Save function uses this connection to save the OLE data.

When you call SaveAs for an OLE control, it closes the current connection between the OLE object and its storage, either file or storage object. It establishes a new connection with the new storage, which will be the target of subsequent calls to the Save function.

Examples

This example saves the object in the control ole_1 in the storage variable stg_stuff:

integer result
result = ole_1.SaveAs(stg_stuff)

See also

Open

Save

Syntax 4: For saving an OLE storage object to a file

Description

Saves an OLE storage object to a file. If OLE controls have opened the OLE storage object, this syntax of SaveAs puts them in a saved state too.

Applies to

OLE storage objects

Syntax

olestorage.SaveAs (OLEtargetfile )

Argument

Description

olestorage

The name of an object variable of type OLEStorage containing the OLE object you want to save.

OLEtargetfile

A string specifying the name of a new OLE storage file.  OLEtargetfile can include a path.


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

-2 -- The storage name is invalid

-3 -- The parent storage is not open

-4 -- The file already exists

-5 -- Insufficient memory

-6 -- Too many files open

-7 -- Access denied

-9 -- Other error

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

Usage

The Open function establishes a connection between a storage file and a storage object, or a storage file or object and an OLE control. The Save function uses this connection to save the OLE data.

When you call SaveAs for a storage object, it closes the current connection between the storage object and a file and creates a new file for the storage object's data.

For information about the structure of storage files, see the Open function.

Examples

This example saves the storage object stg_stuff to the file MYSTUFF.OLE. Olest_stuff is an instance variable:

integer result
result = stg_stuff.SaveAs("c:\ole\mystuff.ole")

This example opens a substorage in one file and saves it in another file. An OLE storage file called MYROOT.OLE contains several substorages; one is called sub1. To open sub1 and save it in another file, the example defines two storage objects: stg1 and stg2. First MYROOT.OLE is opened into stg1. Next, sub1 is opened into stg2. Finally, stg2 is saved to the new file MYSUB.OLE. Just as when you open a word processing document and save it to a new name, the open object in stg2 is no longer associated with MYROOT.OLE; it is now connected to MYSUB.OLE:

olestorage stg1, stg2
stg1 = CREATE OLEStorage
stg2 = CREATE OLEStorage
stg1.Open("myroot.ole")
stg2.Open("sub1", stg1)
 
stg2.SaveAs("mysub.ole")

See also

Close

Open

Save

Syntax 5: For saving an OLE storage object in another OLE storage

Description

Saves an OLE storage object to another OLE storage object variable in memory.

Applies to

OLE storage objects

Syntax

olestorage.SaveAs ( substoragename, targetstorage )

Argument

Description

olestorage

The name of an object variable of type OLEStorage containing the OLE object you want to save.

substoragename

A string whose value is the name of a substorage within targetstorage. If substorage does not exist, SaveAs creates it.

targetstorage

The name of an object variable of OLEStorage in which to store the object in olestorage. Note the reversed order of the substoragename and targetstorage arguments from Syntax 4.


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

-2 -- The storage name is invalid

-3 -- The parent storage is not open

-4 -- The file already exists

-5 -- Insufficient memory

-6 -- Too many files open

-7 -- Access denied

-9 -- Other error

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

Usage

The Open function establishes a connection between a storage file and a storage object, or a storage file or object and an OLE control. The Save function uses this connection to save the OLE data.

When you call SaveAs for a storage object, it closes the current connection between the storage object and a file and creates a new file for the storage object's data.

For information about the structure of storage files, see the Open function.

Examples

This example saves the object in the OLEStorage variable stg_stuff in a second storage variable stg_clone as the substorage copy1:

integer result
result = stg_stuff.SaveAs("copy1", stg_clone)

See also

Close

Open

Save