SaveAs

Description

Saves the contents of a DataWindow or DataStore in the format you specify.

For syntax to save the contents of graphs in DataWindows and DataStores, see SaveAs. For syntax to save objects in OLE controls and OLE storage, see SaveAs in PowerScript Reference.

Applies to

DataWindow type

Method applies to

PowerBuilder

DataWindow control, DataWindowChild object, DataStore object


Syntax

PowerBuilder

integer dwcontrol.SaveAs ( { string filename, saveastype saveastype, boolean colheading { , encoding encoding } } )

Argument

Description

dwcontrol

A reference to a DataWindow control, DataStore, or child DataWindow.

filename (optional for PowerBuilder)

A string whose value is the name of the file in which to save the contents. If you omit this argument, or specify an empty string ("") for filename but include valid values for the saveastype and colheading arguments, the DataWindow prompts end users for a file name.

Working with DataStore objects

If you are working with a DataStore, you must supply the filename argument.

saveastype (optional for PowerBuilder)

A value of the SaveAsType enumerated datatype specifying the format in which to save the contents of the DataWindow object.

For a list of values, see SaveAsType.

colheading (optional for PowerBuilder)

A boolean value indicating whether you want to include the DataWindow's column headings at the beginning of the file. The default value is true. This argument is used for the following formats: Clipboard, CSV, Excel, and Text. For most other formats, column headings are always saved.

encoding (optional for PowerBuilder)

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

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

Usage

If you do not specify any arguments for SaveAs, PowerBuilder displays the Save As dialog box. A drop-down list lets the user specify the format of the saved data.

Report format (PSReport! value of SaveAsType) is the best choice if the DataWindow is a composite report. Choosing PSReport! has no effect if the DataWindow object has the RichText presentation style.

For XML!, the XML logical structure used is based on the current XML export template for the DataWindow object. You can change the export template by setting the value of the Export.XML.UseTemplate property. If no export template is specified, the default template is used.

If you use date formats in your report, 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 might need to reboot after the setting is changed.

When you save the contents of a DataWindow to a text file, double quotes are handled in a way that enables the ImportFile method to produce the same DataWindow when the text file is imported back into PowerBuilder. Any field that is enclosed in a pair of double quotes is wrapped with three pairs of double quotes in the saved text file. Double quotes at the beginning of a text field that have no matching double quotes at the end of the field are also replaced by three double quotes in the saved text file. However, a double quote elsewhere in the field is saved as one double quote.

The behavior of the SaveAs method with the EncodingANSI! parameter or with no encoding parameter is platform dependent. On the Windows and Solaris platforms, the file is always saved with ANSI encoding whether you are connected to an ANSI or Unicode database. On the Linux platform with an ANSI database connection, SaveAs saves the file with ANSI encoding. On the Linux platform with a Unicode database connection, if the data contains multilanguage characters, SaveAs converts the characters to UTF-8 and saves the file with UTF-8 encoding.

Examples

This statement saves the contents of dw_History to the file G:\INVENTORY\EMPLOYEE.HIS. The saved file is in CSV format without column headings:

dw_History.SaveAs("G:\INVENTORY\EMPLOYEE.HIS", &
   CSV!, false)

The following statements set the template used by the DataWindow dw_1 to t_report, specify that metadata in the XMLSchema! format should be generated in a separate file, and generate the files c:\myxml.xml containing the DataWindow row data in XML format, and c:\myxml.xsd containing the XML schema used in c:\myxml.xml:

dw_1.Modify("DataWindow.Export.XML.UseTemplate = 't_report'")
dw_1.Modify("DataWindow.Export.XML.MetaDataType = XMLSchema!")
dw_1.Modify("DataWindow.Export.XML.SaveMetaData = MetaDataExternal!")
dw_1.SaveAs("c:\myxml.xml", XML!, false)

The following statements generate the files c:\dw_one.fo containing the DataWindow presentation and data in XSL-FO format, and c:\dw_one.pdf containing the DataWindow presentation and data in PDF format:

dw_1.SaveAs("c:\dw_one.fo", XSLFO!, false)
dw_1.SaveAs("c:\dw_one.pdf", PDF!, false)

See also

ImportFile

Print

SaveAsFormattedText

Update