InstallShield Internal Library Functions 22 Miscellaneous Functions The following functions provide different features such as low-level hardware interfaces, components creation, and operations and user output. DO performs the currently defined EXIT and HELP handler. DoinsTall runs another InstallShield installer. Handler specifies a label that is transferred to an exit and help event responses. ISCompareServicePack compares the number of service packages installed on the target OS and the specified number of service packages. MessageBeep produces a standard warning bee. SendMessage Sends a message to another window or application. Sprintf Returns a string that formats one or more characters, numbers, or string values. SYSTEM exits to DOS, restart Windows or restart your computer. Varrestore restores the value of the system variable Srcdir and Targetdir that saved when calling Varsave. Varsave Save the current value of system variables srcdir and targetdir. 22.1 DO Syntax: DO (NOPERATION); Description: Exit and Help handlers support only backward compatibility. In an event-based script, you have to replace the oncancelishling and onhelp event handler. The DO function performs the currently defined EXIT and HELP handler, gives you greater control of these handles, usually only when the user presses the F1 key (HELP), F3 key (EXIT), or CANCEL Button (exit) . With the DoFunction, you can perform EXIT or HELP to respond to custom dialog events or from any user from the internal dialog box. You can also use the DO function in a multi-formation of script to test your exit and help handlers. Use the DO function to register the queued self-registration file. File uses the "Batch Method" to install the registered file to wait for the registration. When you call DO (SelfRegistrationProcess), InstallShield's self-registration of all queuing files, even if they fail. If DO fails due to any reason, it will return -1. Self-registration failed files Save InstallShield system variable errorfilename, separated by semicolons. Parameters: NOPERATION Specifies the type of operation to be executed. One of the following predefined constants in this parameter location: EXIT: Start the EXIT operation. If the exit handler is not defined, the default EXIT dialog is displayed. Help: Start Help operation. If the HELP handler is not defined, the function does not have any action. SelfregistrationProcess: Register all self-registered files that have been queued. Return Value: 0: The DO function successfully launched the specified action. <0: The DO function failed to start the specified action. Note: The DO function allows the currently defined HELP and EXIT handler to execute when the user does not press the F1 or F3 key. The DO function is also more versatility than the goto statement (it can be used to call the Help and EXIT processing program). The GOTO statement cannot be used in all environments, but the DO function can be called any time. For more information on default and custom HELP and EXIT handles, see the Handle function. 22.2 DoInstall Syntax: Doinstall (Szinsfile, Szcmdline, Lwait); Description: DoinsTall function runs another installshield installer. When this function is called, the second installer is executed immediately. Parameters lwait Specifies whether the call script is done before you continue to run the installer. The installation called DoinsTall must be created with the same main version number and the secondary version of InstallShield. If you try to run a installer created by any other InstallShield version, it is impossible to succeed.
If the second installer runs another executable application, the first installer does not control the running application, and there is no way to monitor the status of running the application. Parameters: szinsfile Specifies the full qualification of the compiled script file (.inx) to run (containing a drive indicator and full path). Szcmdline specifies a line of installshield command lines. Here you can specify any effective launch installshield command line, however, note that in this environment (context) is not appropriate -f and -l option, it cannot be used. LWAIT specifies that the call script is done before you continue to wait for the run. One of the following predefined constants in this parameter location: NOWAIT: Call the installer and continue after running the second installer. WAIT: Call the installer to wait for the running installer to terminate before proceeding. Return Value: 1: The installer called DOINSTALL (in WAIT is the third parameter) is successfully terminated. The control program continues the statement under the doinstall function in the original installer. 2: The installer called DOINSTALL (with NOWAIT is the third parameter) is successfully terminated. The control program continues the statement under the doinstall function in the original installer. -1: The installer called DOINSTALL cannot be initialized. This error is often the result of losing a desired installation file, and the general error that occurs when running the second installer generates the return value. -2: The installer called by DoinsTall (in WAIT) cannot be found by the .inx script file specified by szinsfile. -3: The installer called by Doinstall (in WAIT is the third parameter) is canceled by the user. Any other negative value: an undetermined error occurred. Note: • The second installer always runs in the language specified by the current value of the system variable Selected_Language. This is true even if the -l parameter is used in the command line of the second installer. · Note that only one shared file running in the installer and the installer running it is ikernel.ex_. Therefore, all other installation files required for the second installer must be in the same folder when operating normally. If these files do not exist, the installer will not be run correctly. Therefore, it is recommended that you will copy all files created by the Media Wizard to the folder you run from it to the second installer. If you run the second installer from the installation support folder (Supportdir) of the first installer, it is recommended that you place these files in the appropriate language and operating system in the installation file pane of the first installer. In the folder, when the installation is initialized, they are automatically decompressed in the support folder of the first installer. 22.3 Handler Syntax: Handler (NOBJECT, LABEL); Description: Exit and Help handles only support backward compatibility. In an event-based script, you have to replace the oncancelishling and onhelp event handler. Handler function Create an event's custom handler, such as Help acceleration key (F1), Cancel's acceleration key, and EXIT's acceleration key (F3). If the user presses the F1 key, the currently defined HELP handler is executed. If the user presses the F3 key, the currently defined EXIT handler is executed. If you don't use the Handler function to define a custom HELP and EXIT handler, the default handler will be executed. The default EXIT handler displays an exit dialog. The default HELP handler does not work.
To perform a custom handler defined with the handler, the installshield calls the unique label specified by the INSTALLSHIELD when the NOBJECT event occurs. When INSTALLSHIELD reaches the return statement in the handler code (in the next statement of the label), the control program returns to the statement (if the handler label is not called, the statement has been executed). With Handler, you can specify an Exit or Help custom handler. You can display Messagebox, Sprintfbox, and Askyesno dialog box in the exit handler; however, you cannot display the SD dialog. Parameters: NOBJECT Specifies the transfer (trap) event. One of the following predefined constants in this parameter location: EXIT: Specifies the custom handler when the CANCEL button or the F3 accelerator is pressed. If you do not define a handler, a default EXIT dialog will appear when the Cancel button or the F3 acceleration button is pressed. Help: Specifies the custom handler when pressing the F1 acceleration button. If you do not define a handler, do not do anything when you press the F1 accelerator. Label specifies that the program must jump to the label name when the specified button or the accelerator button is pressed. Do not define that the label is a numeric value or a string value. To cancel a currently defined handler and reinstall the default handler, the parameter is delivered to this parameter. This method is useful in some scripts, and a custom handler installed in those scripts is only available to a specific process, and then go to the default handler. Return Value: 0: Handler successfully created a handler. <0: Handler failed to create a handler. Note: • Do not define the named value value or a string value. • Effective acceleration keys are F1 bonds (HELP) and F3 (Exit) (which is the same as the effect of the Cancel button in the script dialog). Help (f1) allows you to run the Help engine or provide other suitable HELPs. When the user presses the F1 key, INSTALSHIELD invokes the currently defined HELP handler. You can provide any type of HELP function feature in the HELP handler. · If you want to provide the context about Help, you must track the context in your script. For example, you can have a string value that contains the current context string. Then you can use this string value in a Switch-CASE statement of the HELP handler, specify the appropriate HELP events based on the value of the context string. You can also test global variables nsddialog in your HELP process routine. NSDDialog is set to a dialog ID of the currently executed SD dialog (described in SDRC.H in the InstallShield Include folder). (NSDDIALOG is not defined when there is no SD dialog execution.) So when an SD dialog is executed, you can let the user access the SD dialog-specific HELP. · As the HELP handler, you can also define and perform a custom and SD dialog-specific EXIT handler. • In the script, the exit and help handler labels and their related code must be placed before the program statement. 22.4 ISCompareServicePack Syntax: ISCompareServicePack; Description: The iScompareServicePack function is only compatible with scripts created with InstallShield previous versions. We recommend that you determine the number of Windows NT Service Pack by detecting the value of sysinfo.winnt.nservicePack. The iSCompareServicePack function is compared to the number of service packages on the Windows NT system and the number of service packages specified by SZServicePack.
Parameters: SZServicePack Specifies the number of service packages compared to the number of service packages on the target computer. The format of the string must be "Service Pack N", n is the number of service packages. Compare case sensitive. Return Value: LESS_THAN (1): There is no service package on the target system or the number thereof is less than the value of the parameter SSServicePack. Equals (2): The number of service packages matches. Greater_than (0): The number of service packages on the target system is greater than the value of the parameter SZServicePack. -1: ISCompareServicePack failed to compare the number of service packages. Note: This function is only working on WinNT4.0.22.4 MessageBeep syntax: MessageBeep (NRESERVED); Description: The MessageBeep function plays the default system sound. Parameters: NRESERVED passes 0 to this parameter. Other values are not allowed. Return Value: This function has no return value. Note: · You have an audio signal to provide an audio file by calling Playmmedia to play an audio file. 22.5 SendMessage Syntax: SendMessage (NHWND, NMSG, NWPARAM, NLPARAM); Description: The SendMessage function sends a message to one or more windows. SendMessage until the message has been processed to return to the installation script control program. The SendMessage function is to pass Windows API SendMessage. For more information, please contact your Windows programming document. Parameters: nhwnd Specifies the handle of the window that identifies the window that receives the message. NMSG specifies messages sent to the window. NWPARAM specifies information about the additional message. NLPARAM specifies information about the additional message. Return Value: The InstallShield SendMessage function returns to it calls the value returned by the Windows API in the same name. The return value depends on the message accepted by Windows API SendMessage. For more information on return messages for Windows API SendMessage, please contact your Windows programming document. Note: • Send a message or process return value for parameter NMSG, you must define the constant of the constant defined in the script and the constant defined in Windows.h. You can't use #include in your script to contain Windows.h. 22.7 Sprintf Syntax: Sprintf (SvResult, Szformat [, Arg] [, ...]); Description: The Sprintf function creates a string from variable data using format specifiers and match variables. The Sprintf function is working like Microsoft Windows API WSPrintf. Parameters: SvResult creates a string from the variable passing to the third parameter and the subsequent parameter, format and returns the string according to the description of the second parameter SZFormat. SZFormat specifies a string that can contain text text and must include a corresponding format specifier for each variable in the string that is embedded in the SvResult. Arg You can specify up to 9 variables that can be included in the message. Each format specifier in the message must have a corresponding variable; the type of each variable must match its respective format specifiers. Sprintf Will Generate A Compiler Error OR Fail At Run Time Under The Following Conditions: Sprintf Fails to generate a compilation error or runtime: specified more than 9 format specifiers and variables: Compile errors. The number of variables and the number of format specifiers do not match. When a certain set does not have a corresponding variable, the result string will contain unpredictable characters in the location of the descriptor. When the variable is more than the specifier, the excess variable will not be inserted into the result string. A variable does not match the corresponding format specifier. The result string will contain unpredictable characters in the location of the descriptor.
Return Value: If the Sprintf function is successful, the return value is the length of the string saved in the variable svresult, does not include end null characters. 22.8 System Formula: System (NOP); Description: Use the System function to restart the Windows or restart the system. The System function does not perform an exception abort (ie, it does not delete the installed file). However, INSTALLSHIELD deletes it to place any temporary directory and temporary files in the system for installation. The System function has an earlier version of InstallShield. When using installshield's current version, the best functions used to restart Windows or systems are RebootDialog and SDFINISHREBOOT. In these two functions, the SDFINISHREBOOT function is the best. See which one is best for you to see. Parameters: NOP Specifies what to do after the installation is installed. One of the predefined constants in this parameter location: SYS_BootMachine: Restart the system. Note: • This function calls Microsoft Windows API EXITWINDOWS. This function is highly dependent on the interaction of BIOS and systems due to the Today's system. Some systems do not restart or pending when the function is called. Many installation routines (including system software such as MS-DOS) displays a warning message to the user before they restart the system. This warning message indicates what happened and guides the user to manually restart the system when the command fails. 22.9 Varrestore Syntax: Varrestore (NTYPE); Description: The Varrestore function gives the system variable srcdir and targetdir re-assaped the value saved by previously calling Varsave. Whenever you want to temporarily modify the value of srcdir and targetdir (for example, set the source directory and target directory before calling XcopyFile), you have to call Varsave. Then then call Varrestore to set the value of these variables to their original value. Parameters: NTYPE Specifies constant srctargetdir to indicate that you want to restore the value of previously saved system variables srcdir and targetdir. Return value: 0: Indicates that the previously saved system variable srcdir and targetdir are restored. <0: Indicates that there is no saving value that can be restored. When you call Varrestore first call Varrestore, you call Varstore more than the number of times you call Varsave. Note: • Every time you call Varsave, InstallShield advances the current value of srcdir and targetdir into an inner stack (ie a storage area of a Fisrt in last out). This approach allows you to stack a range of SRCDIR and Targetdir in memory. You can then call the Varrestore to retrieve these values from the stack to retrieve these values in the order in which they are stored. For example, if you call Varsave three times (there is no Varrestore in these calls), there are three sets of srcdir and targetdir values in the stack. The first call VARRRESTORE will restore the value when the VarSave is called. The next call VARRRESTORE will restore the value of the second call VARSAVE. The third call VARRRRESTORE will recover the value when calling Varsave. At this time, the stack varies. 22.10 Varsave Syntax: Varsave (NTYPE); Description: The Varsave function saves the current value of the system variable srcdir and TargetDir (they can be used by many other installshield functions).
