isc_install_execute()

Go Up to API Function Reference

Performs the actual install, including file copying, registry entries, saving uninstall options, and modifying the services file if necessary.

Syntax

 MSG_NO isc_install_execute(OPTIONS_HANDLE handle, TEXT *source_path, 
 TEXT *dest_path, FP_STATUS *fp_status, void *status_arg, 
 FP_ERROR *fp_error, void *error_arg, TEXT *uninst_file_name)

Parameter	Type	Description
handle	OPTIONS_HANDLE	The handle to the list of options created by isc_install_set_option(); returns an error if the value of handle is NULL or zero
<source_path>	TEXT*	The path where the files to be installed are located, typically on a CDROM; the function returns an error if source_path is NULL or an empty string
<dest_path>	TEXT*	The path to the desired install location; the function returns an error if dest_path is NULL or an empty string
<fp_status>	FP_STATUS*	A pointer to a callback function that accepts an integer from 0 to 100; may be NULL if no status information is required by the user
<status_arg>	void*	User-defined data to be passed to fp_status(); value is often NULL
<fp_error>	FP_ERROR*	A pointer to a callback function that accepts an error number and returns a mnemonic specifying whether isc_install_execute() should abort, continue, or retry
error_arg	void*	User-defined data to be passed to fp_error(); value is often NULL
<uninst_file_name>	TEXT*	A pointer to a buffer containing the name of the uninstall file; can be set to NULL

Description

isc_install_execute() performs the actual install, including the following operations:

• Calls isc_install_precheck() to ensure that the install can be performed; if isc_install_precheck() returns an error the install aborts
• Logs all actions to a temporary file called ib_install.log
• Creates the destination directory if it does not already exist
• Copies the files using all the correct version checks and delayed copying methods if necessary
• Creates the required registry entries
• Increments UseCount entries in the registry for shared files
• Installs the Guardian and Server as services on Windows server platforms, or adds the Guardian to the Run section of the Registry on Windows non-server platforms
• If necessary, add gds_db to the Services file
• Streams the selected options into ib_uninst.nnn (where nnn is a sequence number) for use at uninstall
• Frees the options list from memory
• Upon completion, moves ib_install.log to the install directory
• Calls fp_status() at regular intervals to pass information on the install progress (percent complete)
• Attempts to clean up if at any point the install is canceled by the user or by an error

If you choose to write functions for displaying status and handling errors, you pass in pointers to these functions as the fp_status and fp_error parameters. In addition, you can pass context information or data to these functions by passing in values for status_arg and error_arg, although these last two parameters are more commonly NULL.

Return value

Returns zero if the function executes successfully, a positive number if an error occurs, and a negative number if the function completes with warnings.

Call isc_install_get_message() to obtain the error message when the result is nonzero.

Advance To:

• isc_install_get_info()