IBPhoenix Development

The return value is isc_install_success if the function executed successfully, larger than isc_install_success if an error occurred, and less than isc_install_success if the function completed with warnings.  In the case of a non isc_install_success result, The VAR may call the function isc_install_get_message to obtain the error message.   An exhaustive list of the error codes and messages will be generated once the high level design has been completed.  Note:  These will be available to the user in the header file as well as in the documentation.

The address for the handle.  The handle will need to be set to 0L be the user before calling this function the first time.  Once the functions completes succesfully, it will point to an options list managed by the install engine.

For the InterBase product, this can be any one of the following values: 
 

Option's marked with * are not available in the current install.  They are included for maximum flexibility, however it should be recognized that they represent more work.  If it is determined that this level of flexibility in not needed, then they may be omitted. 

Note 1: The install engine itself, will always be installed, whenever any option is installed. Whereas the install engine import libraries, and header files will be installed as part of the IB_DEVoption. 

Note 2: These constants will be pre-defines in a C header file made available to all who will use the API.  The user will be free to translate this header to any other language.  It is possible that we may choose to also provide a Delphi unit, this is yet to be determined. 

Note 3: All the options begin with IB_ since they are subsets of options for INTERBASE, in this way we could have options named IC_ as subsets of options for INTERCLIENT.  In the first release of this product we will not include the IC_ options.

This function will evaluate the option specified and add all necessary nodes to the linked list of options represented by handle.  Each node can represent a file being copied, or a registry entry to be created. 

This function will need to be called once for every option the user wishes to add.

The return value is isc_install_success if the function executed successfully, larger than isc_install_success if an error occurred, and less than isc_install_success if the function completed with warnings.  In the case of a non isc_install_success result, The developer may call the function isc_install_get_message to obtain the error message.   An exhaustive list of the error codes and messages will be generated once the high level design has been completed.  Note:  These will be available to the user in the header file as well as in the documentation.

The address for the handle.  The handle represents  the list of options requested using isc_install_set_option.  If this is set to zero an error message will be returned.

This can be any one of the values listed above in isc_install_set_option.  If option is the only member of the list then handle will be set to zero to indicate an empty options list.

This function will access the options list pointed to by handle and remove the option specified by option.  This function will need to be called once for every option the users wishes to remove. If the option to be removed is the only option currently set then the call is equivalent to isc_install_clear_options.

The return value is isc_install_success if the function executed successfully, larger than isc_install_success if an error occurred, and less than isc_install_success if the function completed with warnings.  In the case of a non isc_install_success result, the function isc_install_get_message may be called to obtain the error message.   An exhaustive list of the error codes and messages will be generated once the high level design has been completed.  Note:  These will be available to the user in the header file as well as in the documentation.

The address for the handle representing  the list of options requested using isc_install_set_option.  If this is set to zero an error message will be returned.

This function will clear all the options stored in handle.  This needs to be called anytime the options need to be rebuilt, and may be called at the end of the install process.  Upon succesful completion handle is set to 0L.

The return value is isc_install_success if the function executed successfully, larger than isc_install_success if an error occurred, and less than isc_install_success if the function completed with warnings.  In the case of a non isc_install_success result, the function isc_install_get_message may be called to obtain the error message.   An exhaustive list of the error codes and messages will be generated once the high level design has been completed.  Note:  These will be available to the user in the header file as well as in the documentation.

The handle to the list of options requested using isc_install_set_option.  If this is set to NULL an error message will be returned.

The path where the files to be installed are located. In most cases this will be a path on the CD-ROM, since this will most-likely be our source media.  If this is set to NULL then this check is skipped, otherwise the existence and readability of this path is checked.  This parameter is needed so that the pre-check can verify that InterBase is actually located in the source directory. The function will return n error if it could not read the path attributes.

The path to which we wish to install.  If this is set to NULL then the disk space check is skipped.  This path is checked for existance, and if it does not exist  the rest of checks is skipped.  If the path does exist, then we will check it for writability. 

This function will perform all the pre install checking needed, such as: 

• Not allow a SuperServer to be installed if a ClassicServer is present.
• The function will check source_path.  The source_path will be checked for existence, that is actually a directory and for readability. The path shall be a valid directory path. To determine whether a particular path is valid check your OS manauls. The check is omitted if source_path is NULL.
• The dest_path is checked whether it is a directory, if it is writeable and whether it has enough space to install the selected components. The path shall be a valid directory path. To determine whether a particular path is valid check your OS manauls. The check is omitted if dest_path is NULL or it does not exist.
• Check if the destination drive/volume has enough disk space to install selected options.
• Check for pre-existing, newer or older, versions of the product already running.
• Check the dependencies of the options required.  For example, generate a  warning if the tools are being installed without the client. 
• Check for a valid operating system.
• Check for the correct user permissions needed to install. When installing on NT the user needs an administrative priviliges.

Note: Handle should be a valid handle obtained by calling  isc_set_option.  Handle cannot be NULL.  If this is the case, an error will be returned.

The return value is isc_install_success if the function executed successfully, larger than isc_install_success if an error occurred, and less than isc_install_success if the function completed with warnings.  In the case of a non isc_install_success result, the function isc_get_install_message may be called to obtain the error message.   An exhaustive list of the error codes and messages will be generated once the high level design has been completed.  Note:  These will be available to the user in the header file as well as in the documentation.

The handle of  the options requested using isc_install_set_option.

The path where the files to be installed are located. In most cases this will be a path on the CD-ROM, since this will most-likely be our source media.  This may NOT be set to NULL.

The path to which we wish to install. If  dest_path does not exists it will be created. This can not be NULL nor it can be an empty string. If you wish to get a suggested destination use  isc_install_get_info function.

A call-back function which accepts an integer from 0 to 100 indicating % completion. If this function is supplied by the user, it will be called as progress is made within the engine to allow the user to display a status bar, bill-boards, or what ever other form of progress they wish.  This may be NULL, in which case no status information will be supplied to the user. The 'func' type will be pre-defined in the header.

User defined data to be passed to fp_status.  This helps the user establish the context of the function.

A call-back function which accepts an error number.  This function will process the error (such as the file is in use) and return isc_install_fp_retry for retry, isc_install_fp_continue for continue, and isc_install_fp_abort for abort.  If abort is specified, the function will fail and the original error is returned.  This allows the user to handle errors and inform us of the action we need to take.  This may be NULL, in which case if an error occurs the function will fail and return the error.

User defined data to be passed to fp_error.  This helps the user establish the context of the function.

A pointer to a buffer in which the name of the uninstall file will be returned.  This file name will be of the type ib_uninst.xxx where xxx is a sequence number.  This information is to be used to create the uninstall icon. If this is set to NULL the file name will not be returned.

This function will perform the actual install, that is: 

• Call isc_install_precheck to ensure that the install may be performed.
• Log all actions to a file called ib_install.log. This file is initially created at the temporary directory and it is moved to the destination directory upon successful completion.
• Create the destination directory if it does not already exist.
• Copy the files using all the correct version checks, and delayed copying methods necessary.
• Increase the reference count of shared files.
• Create the registry entries needed.
• Install the guardian in the Services Manager on Win NT, or add the guardian to the Run section of the registry on Win 95.
• Modify the TCP/IP services file (if necessary).
• Write the options installed into the uninstall file for later use.
• Return the name of the uninstall file.

Note: If any of the call-back functions attempt to call the Install API functions, other then isc_install_get_message, the result will be undetermined.  Thus, these functions should not be calling back into the Install Engine.

The return value is isc_install_success  if the function executed successfully, larger than  isc_install_success  if an error occurred, and less than  isc_install_success if the function completed with warnings.  In the case of a non  isc_install_success result, the function isc_install_get_message may be called to obtain the error message.   An exhaustive list of the error codes and messages will be generated once the high level design has been completed.  Note:  These will be available to the user in the header file as well as in the documentation.

The name and path to the uninstall file.  This will allow us to determine if InterBase has been instlled, and which options were installed.  This may not be left NULL.

This function will perform all pre uninstall checking needed, such as: 

• Check that the uninstall file is valid.
• Check that the server is not running if the server was installed.
• Check for the correct user permission needed to uninstall.

The return value is isc_install_success if the function executed successfully, larger than  isc_install_success  if an error occurred, and less than  isc_install_success if the function completed with warnings.  In the case of a non  isc_install_success result, the function isc_install_get_message may be called to obtain the error message.   An exhaustive list of the error codes and messages will be generated once the high level design has been completed.  Note:  These will be available to the user in the header file as well as in the documentation.

The name of the file containing the options which were installed.  This information will be used to decide what we will uninstall. This can not be NULL

A call-back function which accepts an integer from 0 to 100 indicating % completion. If this function is supplied by the user, is will be called as progress is made within the engine to allow the user to display a status bar, bill-boards, or what ever other form of progress they wish.  This may be NULL, in which case no status information will be supplied to the user. The 'func' type will be pre-defined in the header.

User dafined data to be passed to fp_status.  This helps the user establish the context of the function.

A call-back function which accepts an error number.  This function will process the error (such as the file is in use) and return -1 for retry,  0 for continue, and 1 for abort.  If abort is specified, the function will fail and the original error is returned. This allows the user to handle errors and inform us of the action we need to take.  This may be NULL, in which case if an error occurs the fp_status is not called and the function will return the error.

User defined data to be passed to fp_error.  This helps the user establish the context of the function.

This function will perform the actual uninstall, that is: 

• Call isc_uninstall_precheck to ensure that the uninstall may be performed.
• Remove all InterBase files that are installed. ODBC Core Files, msvcrt.dll, setupapi.dll, cfgmgr32.dll, isc4.gdb, isc4.gbk and ib_license.dat will not be removed.
• Remove registry entries.
• Decrease reference counts of shared files.
• Remove shared files which have a reference count less than 1 except for those files which Microsoft has pre assigned to 0, such as MSVCRT.DLL.
• Uninstall the InterBase Guardian and InterBase Server services on NT. Remove ibguradian.exe at Run registry key on 95/98 systems.

Note: If any of the call-back functions attempt to call the Install API functions, other then isc_install_get_message, the result will be undetermined.  Thus, these functions should not be calling back into the Install Engine.

The function actually returns MSG_NO which can be checked. It may return error codes when something goes wrong. The best practice is to check the error code to ensure that the message returned is credible.

The error/warning value to be translated.  This is the same value that is returned from the functions above.

A buffer in which to place the message.

The length of the buffer sipplied in bytes.  If the error/warning message does not fit in the space provided, as much of the message that will fit will be placed in msg.

This function converts the error/warning value stored in msg_no and returns the corresponding error/warning message for use by the programmer. The message returned will always be  zero terminated.

The function returns a MSG_NO which can be later used in isc_install_get_message to obtain a human readable error information. When the option parameter is used the option is validated. If  the option specified is invalid, info_type specified is not valid or the buffer pointer is not valid the function will return an error . The caller should always check the return value. The contents if the info buffer is undetermined when the function returns something other than isc_install_success

This can be one of the constants defined at ibinstall.h The function will return an error of the info_type specified is not known to the install API.

The option we would like to receive information about. The function will return an error when the option specified is not valid. The option value is ignored when a destination suggestion is requested.

A pointer to a buffer where the infomation requested will be returned. The buffer can not not NULL. The function will return an error if the buffer is NULL.

This specifies a size of the buffer in bytes.  The buffer length of 0 is unacceptable. It is the responsibility of the user to ensure that the actual buffer size is passed to the function. It is also the responsibility of the calller to ensure that the buffer is large enough to hold the requested information. If text information is requested then the buffer is recommended to be at least ISC_INSTALL_MAX_MESSAGE_LEN bytes. If the destination suggestion is requested then the recommended buffer size should be ISC_INSTALL_MAX_PATH. For diskspace information the result will be of unsigned long size.

The function will return the information requested by info_type. If the info_type is not option specific then the option argument is ignored. The information is returned at info_buf  location. This parameter can not be NULL. A proper buf_ size in bytes should be specified. If either info_buf or buf_size are NULL(0) an error will be generated. Currently 4 types of the information can be expected from the function but it is possible to add additional ones as necessary. The types of information are:

1. Suggested destination directory. This functionality is taken over from isc_install_precheck (5.5 undocumented functionality). isc_install_precheck will no longer suggest a destination path (Option parameter is ignored in this case).
2. Disk space required to install a particular option (Requires a valid option)
3. A human readable option name (Requires a valid option)
4. A human readable option description. (Requires a valid option)

The function returns a MSG_NO which can be later used in isc_install_get_message to obtain a human readable error information. When the option parameter is used the option is validated. IF the file can not be loaded a warning is returned. This is because this functionality is not essential for the rest fo the install.

This is full path to where the .msg file can be found. Most of the time this is the source_path form where the customer installs the product. A developer  may choose to place the file or several .msg files into a separate sub directory and load it from there.

The function addresses the internationalization issues. It attempts to load the external .msg file from external_path location. Normally the developer would supply one .msg file. It is, however, possible to write the setup program in such a way that it can switch the languages on demand. In this case the developer should provide several .msg files.

This essentially means that we are providing a feature that will enable customers easily replace english language messages that our API issues with their own messages in a different language. For this we provide an API call isc_install_load_external_text  to load a customer defined text strings stored in a disk file.
The messages  that we have to store in the .msg are
 

• error messages
• options names and options descriptions
• actions text. It will contain actions descriptions and actions status messages that will be logged to a text ibinstall.log file.

This might possibly end up in 3 or more different sets of messages that we have to handle. Since we know better how the messages file will look like we have to supply s necessary tool to create such a file. The proposed scenario is:
 

• The proposed name for the tool is MAKEMSG.
• The customer using our tool extracts the set of predefined text messages out to a text file that is readable and can be edited. The text file is created in such a form that it could be fed back to our tool.
• The customer edits the file and runs our tool against it. The tool parses the file and creates ibinstall.msg.
• It is the responsibility of the customer to copy the ibinstall.msg file to a proper location during the installation process. This is if the customer wants that the uninstall program use his messages file.
• It is also the responsibility of the customer to remove the file upon uninstall.
• To make use of the customized ibinstall.msg file the customer has to call isc_install_laod_external_file function.

It is possible to create several msg files. The setup program might ask the user which language he prefers to receive the install messages and switch the language momentarily. The program may switch the language as many times as it wishes. The default english messages becomes unavailable as soon as the user switches to another language unless the user also creates an external english language msg file.