Copyright: 'Copyright ® 1996 Progress Software Corp.
Citation: 'Copyright ® 1996 Progress Software Corp.


Crescent SaveAs Control
 The Crescent SaveAs Control

Control Files

CSAVAS16.OCX, CSAVAS32.OCX

Object Type

SaveAs

Comments

The Crescent SaveAs control can be used to transfer data in a Recordset object from one file type to another and leave the source data intact. It is invisible at run time.

There are several possible output file formats, including an Access database, an Excel spreadsheet, an HTML table, and a text file. You can use the SaveAs control to create an application that can output data in various formats to allow multiple applications to access the data. The SaveAs control saves the data one table at a time, so you can also use it to change the structure of an existing database. You could also modify the Recordset output data or exclude specific fields (columns) before the Recordset is saved using the ColumnCreate and Callback SaveAs events.

The Crescent SaveAs control can be used to:

Convert the data in a Recordset object to a different data type

Alter the data in a Recordset object

Properties

(About)*	(Custom)*	FileName*
Index	Name	Recordset*
SaveAsFormat*	Tag
Events

Callback*	CantCoerce*	ColumnCreate*
Error	TextTooLong*
Methods

Object	Parent	Save*
* A custom or modified property, method, or event.


(About) Property

Applies To

SaveAs control

Purpose

Provides access to version and copyright information for the SaveAs control at design time.

Comments

Double-click this property in the Visual Basic property sheet for the SaveAs control to display the About dialog box for the control.


(Custom) Property

Applies To

SaveAs control

Purpose

Provides access to custom property sheets for the SaveAs control at design time.

Comments

Double-click this property in the Visual Basic property sheet for the SaveAs control to display the custom property sheet for the control. The custom property sheet provides an interface to easily set the FileName and SaveAsFormat properties for the SaveAs control.


FileName Property

Applies To

SaveAs control

Purpose

The FileName property defines the path and file name of the output file that the SaveAs control uses for the data from the Recordset object.

Syntax

[Form.]SaveAs.FileName[ = string]

Data Type

String

Usage

Read/Write at design time and run time.

Comments

The SaveAs control reads the FileName property before converting data with the Save method. The Save method generates the output file using the path and file name specified by the FileName property.

The file name can use the long filename format or the 8.3 format. By default, the SaveAs control uses the standard file extension string for the format as selected in the SaveAs Format property. See the Format property for a detailed list of file extensions.

If you do not specify a file name extension for all of the formats with one exception, the SaveAs control automatically appends the standard file name extension to the file name when it creates the output file. The sole exception occurs with file names for text format on 16-bit environments. The 32-bit SaveAs control appends the extension of txt to files in text format. If the 16-bit SaveAs control is used to save a file in text format, the control does not append a file name extension.

If the file name or path specified by the FileName property are not valid, the SaveAs control generates an error message that tells the user to change the file name or path. The SaveAs control does not create directories; you must specify a path that already exists.

The SaveAs control uses the value of the FileName property as the path and file name of the output file generated when the Save method is called.


Recordset Property

Applies To

SaveAs control

Purpose

The Recordset property specifies the Recordset object that is the data source for the Save method.

Syntax

[Form.]SaveAs.Recordset[ = recordset]

Data Type

Object

Usage

Read/Write at run time.

Comments

The Recordset property can be set to the name of any Recordset object. If the name of the Recordset object specified by the Recordset property matches the name of an existing table in the target file or database, the SaveAs control generates a message box to ask the user whether or not the SaveAs control should overwrite the existing table.

The SaveAs control uses the value of the Recordset property as the name of the source Recordset when the Save method is called.

The Recordset property calls Data Access Object (DAO) errors, which are trappable. See the Visual Basic 4.0 on-line help for more information about DAO errors.


SaveAsFormat Property

Applies To

SaveAs control

Purpose

The SaveAsFormat property identifies the format of the output file used by the SaveAs control.

Syntax

[Form.]SaveAs.SaveAsFormat[ = integer]

Data Type

Integer

Usage

Read/Write at design time and run time.

Comments

The SaveAsFormat property can be set to the following values. These constants are listed in the Visual Basic Object Browser.

Constant	Value	File Format	Default File Extension
saAccess_20	0	Access 2.0	.MDB
saAccess_70	1	Access 7.0	.MDB
saDBase_IV	3	dBASE IV	.DBF/.INF/.MDX/.DBT1
saDBase_50	4	dBASE 5.0	.DBF/.DBT/.INF
saExcel_40	6	Excel 4.0	.XLS
saExcel_50	7	Excel 5.0	.XLS
saExcel_70	8	Excel 7.0	.XLS
saFoxPro_25	10	FoxPro 2.5	.DBF/.CDX/.INF
saFoxPro_26	11	FoxPro 2.6	.DBF/.FPT/.CDX/.INF
saFoxPro_30	12	FoxPro 3.0	.DBF/.FPT
saHTML	13	HTML	.HTM
saLotus_WK3	15	Lotus WK3	.WK3/.INI
saParadox_4x	18	Paradox 4.x	.DB/.MB
saParadox_5x	19	Paradox 5.x	.DB/.MB
saText	20	Text	.TXT
NOTE  	Some of the formats are supported by the 32-bit SaveAs control only. These formats include Access 7.0, DBase 5.0, Excel 7.0, FoxPro 3.0, Lotus WK3, and Paradox 5.x.

The default value for the SaveAsFormat property is Text (saText).

The SaveAs control reads the SaveAsFormat property before converting data with the Save method. When the Save method is called, it saves the input data to an output file of the format specified by the SaveAsFormat property. If the file format specified by the SaveAsFormat property is not valid (for example, it is missing the version number), the SaveAs control generates an error message that tells the user that the specified output file format is not valid.

When you set the SaveAsFormat property, the SaveAs control passes an integer value to Visual Basic. This value corresponds to the specified file format.


Save Method

Applies To

SaveAs control

Purpose

The Save method saves the data from the Recordset object specified in the Recordset property to the file specified in the FileName property. The format of the output file is specified by the SaveAsFormat property.

Syntax

[Form.]CSaveAs1.Save

Comments

The SaveAs control fires the ColumnCreate event before it transfers each column of data to the output file.

See Chapter 6, Getting Started with the SaveAs Control for information about how to use the Save method in an application.

The Save method calls Data Access Object (DAO) errors, which are trappable. See the Visual Basic 4.0 on-line help for more information about DAO errors.


Callback Event

Applies To

SaveAs control

Purpose

The Callback event lets you change data, remove data, or stops execution of the Save method.

Syntax

Private Sub CSaveAs1_Callback(Value As Variant, ByVal OldType As Integer, ByVal NewType As Integer, ByVal OldSize As Integer, ByVal NewSize As Integer, ByVal ColumnName As String, ByVal ColumnNumber As Integer, Action As Integer)

Comments

The Callback event takes the following arguments.

Argument	Description
Value	Value of the input data.
OldType	Database type of the source data.
NewType	Database type of the output data.
OldSize	Length of the text field input column.
NewSize	Length of the text field output column.
ColumnName	Name of the output column.
ColumnNumber	Number of the output column (0-based).
Action	Action to be taken by the SaveAs control. You can set this argument to one of the following values:
	saActionIgnore	Leave this field blank and continue processing.
	saActionStop	Stop processing the table and generate an error message.
	saActionContinue	Use the value from the Value argument in the output field and continue processing. (default)
The Callback event is fired before the SaveAs control writes the data for each row of a column if the Action parameter of the ColumnCreate event is set to saColumnCallback.

The Action and Value arguments are the only arguments that you can change for the Callback event. All other arguments are passed by value (ByVal).

When all four SaveAs events are fired, the Callback event is fired after the ColumnCreate event.

The Callback event calls Data Access Object (DAO) errors, which are trappable. See the Visual Basic 4.0 on-line help for more information about DAO errors.


CantCoerce Event

Applies To

SaveAs control

Purpose

The CantCoerce event lets you manually convert data that the SaveAs control cannot automatically convert to the output data type.

Syntax

Private Sub CSaveAs1_CantCoerce(Value As Variant, ByVal NewType As Integer, ByVal ColumnName As String, ByVal ColumnNumber As Integer, Action As Integer)

Comments

The CantCoerce event takes the following arguments.

Argument	Description
Value	Data that must be manually converted to the output data type.
NewType	Output data type.
ColumnName	Name of the output column.
ColumnNumber	Number of the output column (0-based).
Action	Action to be taken by the SaveAs control. You can set this argument to one of the following values:
	saActionIgnore	Leave this field blank and continue processing. (default)
	saActionStop	Stop processing the table and generate an error message.
	saActionContinue	Continue processing. Execution halts and Visual Basic generates an error message if you did not convert the data to the correct data type.
The CantCoerce event is fired if the input data cannot automatically be converted to the output data type. You can use the Action argument to instruct the control how to handle this data.

The Action and Value arguments are the only arguments that you can change for the CantCoerce event. All other arguments are passed by value (ByVal).

When all four SaveAs events are fired, the CantCoerce event is fired after the Callback event.

The CantCoerce event calls Data Access Object (DAO) errors, which are trappable. See the Visual Basic 4.0 on-line help for more information about DAO errors.


ColumnCreate Event

Applies To

SaveAs control

Purpose

The ColumnCreate event lets you eliminate, rename, or change the type of a column in the Recordset output.

Syntax

Private Sub CSaveAs1_ColumnCreate(ByVal ColumnNumber As Integer, ColumnName As String, ColumnType As Integer, ColumnSize As Integer, ByVal UnsupportedType As Boolean, Action As Integer)

Comments

The ColumnCreate event takes the following arguments.

Argument	Description
ColumnNumber	Number of the output column (0-based).
ColumnName	Name of the output column.
ColumnType	Value representing the input data type.
ColumnSize	Length of the text field input column.
UnsupportedType	Set to True if the data type specified by the ColumnType argument is not supported by the output format.
Action	Action to be taken by the SaveAs control. You can set this argument to one of the following values:
	saColumnSave	Transfer the column to the output table. (default)
	saColumnSkip	Do not transfer the column to the output table.
	saColumnCallback	Execute the Callback event before transferring the column to the output table.
The ColumnCreate event is fired once per column during the creation of the output table, before the first row of data is converted. It is always the first event fired by the SaveAs control.

The Action, Column Name, Column Type, and Column Size arguments are the only arguments that you can change for the ColumnCreate event. All other arguments are passed by value (ByVal).

The SaveAs control sets the ColumnSize argument of the ColumnCreate event to 254 when the output file type is dBASE or FoxPro. dBASE and FoxPro databases do not support text fields longer than 254 characters.

The ColumnType argument can be set to the following values.

Value	Actual Value	Description
dbBoolean	1	Yes/No
dbByte	2	Byte
dbCurrency	5	Currency
dbDate	8	Date/Time
dbDouble	7	Double
dbInteger	3	Integer
dbLong	4	Long
dbLongBinary	11	Long Binary (OLE object)
dbMemo	12	Memo
dbSingle	6	Single
dbText	10	Text
The ColumnCreate event calls Data Access Object (DAO) errors, which are trappable. See the Visual Basic 4.0 on-line help for more information about DAO errors.


Error Event

Applies To

SaveAs control

Purpose

This event is fired whenever an error occurs in the SaveAscontrol when the control cannot determine what action to take.

Syntax

CSaveAs1_Error(Number As Integer, Description As String, Scode As Error, Source As String, HelpFile As String, HelpContext As Long, CancelDisplay As Boolean)

Constants

This event has the following parameters:

Number As Integer - The native error number.

Description As String - A short description of the error.

Scode As Error - The actual numeric value for the error.

Source as String - The name of the application in which the error occurred.

HelpFile As String - The filename of the help file if known. If the filename is not known or if a help file does not exist, the value is NULL.

HelpContext As Long - The context ID passed to get the help file.

CancelDisplay As Boolean - Setting the CancelDisplay parameter to True tells the control not to report the error. Use this value if you will handle the error in your program. Setting the CancelDisplay parameter to False tells the control to report the error. This is the default behavior.


TextTooLong Event

Applies To

SaveAs control

Purpose

The TextTooLong event lets you eliminate or ignore input fields that are too long to fit into the output fields.

Syntax

Private Sub CSaveAs1_TextTooLong(Value As String, ByVal NewSize As Integer, ByVal ColumnName As String, ByVal ColumnNumber As Integer, Action As Integer)

Comments

The TextTooLong event takes the following arguments.

Argument	Description
Value	Value of the input data.
NewSize	Length of the text field output column.
ColumnName	Name of the output column.
ColumnNumber	Number of the output column (0-based).
Action	Action to be taken by the SaveAs control. You can set this argument to one of the following values:
	saActionIgnore	Leave this field blank and continue processing.
	saActionStop	Stop processing the table and generate an error message.
	saActionContinue	Truncate the text, transfer it to the output field, and continue processing. (default)
The TextTooLong event is fired when the input text is too long to fit into the output field.

The Action and Value arguments are the only arguments that you can change for the TextTooLong event. All other arguments are passed by value (ByVal).

When all four SaveAs events are fired, the TextTooLong event is fired after the CantCoerce event.

The TextTooLong event calls Data Access Object (DAO) errors, which are trappable. See the Visual Basic 4.0 on-line help for more information about DAO errors.


General Tab
General Tab - Crescent SaveAs Control

Use this tab to set the FileName and SaveAsFormat properties for the SaveAs control. The General tab allows you to set these properties at design time, instead of at run time.

FileName

Sets the FileName property, which defines the path and file name of the output file that the SaveAs control uses for the data from the Recordset object.

SaveAsFormat

Sets the SaveAsFormat property, which identifies the format of the output file used by the SaveAs control.

OK

Apply changes to the General tab for the SaveAs control and exit the property sheet.

Cancel

Exit the property sheet without saving unapplied changes to the General tab for the SaveAs control.

Apply

Apply changes to the General tab.