Introduction

The Integrated Solutions Console is a single platform for consolidating all administrative console functions (setup, configuration, monitoring, and control) for server, software, and storage products. This article shows you how to embed the Integrated Solutions Console installer into your product. It details the dependencies required to successfully generate and validate a response file, and how to invoke the installer using the generated response file. Finally, it provides some common install problems and what to look for when debugging a failed installation.

Back to top

Embed the installation

Each product that uses the Integrated Solutions Console for its administration interface must embed the Integrated Solutions Console. Such a product is called a deploying product.

As illustrated in Figure 1, the deploying product embeds the Integrated Solutions Console run time, the console installation program, and the console uninstall program. In addition to the Integrated Solutions Console, the deploying product includes its own installation program, one or more components that were developed to administer the product from the console, and the other product code.

During the product installation, a function in the Integrated Solutions Console installation program checks to determine whether the run time is already installed on the system. If the Integrated Solutions Console is already installed, the installation program does not install the run time. Instead, the components for the deploying product are deployed to the selected application server.

Create a response file

The Integrated Solutions Console run time installation program receives configuration information through a response file that is specified in the command invocation. Your product installation program must collect the required data from the user and update the base response file that is included with your product package.

Sample response files are shipped with the Integrated Solutions Console. You can use these as examples or you can start from scratch. Use one of the following methods to create the base response file:

• Collect the user input and dynamically generate a response file.
• Use an AIX®, Linux, Solaris, or Windows™ system to run the Integrated Solutions Console Toolkit installation program and generate a response file for the options you specified during the installation. This method does not apply to i5/OS installations.
1. Run the Integrated Solutions Console Toolkit installation.
2. Make a copy of the sample response file, temp/ISCRuntime.rsp, where temp is the value of the operating system variable %TEMP% on Windows systems and /tmp on the other systems. Depending on the operating system, these files might not be saved after the system is shut down.
3. Save the copy with a different name. There are no restrictions on the file name and extension.
• Use the sample installation response files from the Integrated Solutions Console download image or installation CD. The files are in the subdirectory named extras. Save a copy with a different name. There are no restrictions on the file name and extension. For AIX, Linux, Solaris, and Windows installations, the sample file is Unified_Sample_Response_File.rsp. For i5/OS installations, the sample file is i5OS_Unified_Sample_Response_file.rsp.

After you create the base response file, you must then add response file parameters based on the configuration and the platform that you plan to install on. You need to include all the common parameters listed in the next section. If you choose to install on the i5/OS platform, you need to add another set of parameters, which are described in i5/OS response file properties. Finally, depending on the security mechanism the deploying product has chosen (for example, LDAP, DB2®, or no security), you might need to add the response file properties from the parameter tables included in the remaining sections of this article. After the base response file is complete and you have added all the appropriate parameters, it will have all the properties necessary for an Integrated Solutions Console install.

Common response file properties

Table 1 lists the parameters that must be specified for all embedded installations.

i5/OS response file properties

The parameters in Table 2 apply only to installations on i5/OS systems where the DB2 server and the console run time are on separate i5/OS systems. That is, the DB2 server is on a remote system. If the DB2 server is on the local system, no response file parameters are required.

For a local or a remote DB2 server on an i5/OS system, the console run time installation program creates the DB2 database using a generated library name of the form QISCxxyy, where:

• xx is EX for run time installations that use WebSphere Application Server - Express. An example is QISCEX51.
• xx is BA for run time installations that use WebSphere Application Server Base. An example is QISCBA51.
• yy is unique number in the range 51 to 5199.

WebSphere Application Server response file properties

For installations on AIX, Linux, Solaris, and Windows systems, you must specify the parameters in Table 3 if you are installing the console for the first time on the system and you specified the parameter and value -W appServerInstance.rootDir="" . That setting indicates that the installation will use the application server that is embedded in the run time for Integrated Solutions Console.

For installations that use a separate WebSphere Application Server installation and security is already enabled on that installation, specify the parameters in Table 4.

DB2 response file properties

If the parameter -W dbChoice.dbChoice is set to db2, a remote or local DB2 installation is used to store the console data. The database must already exist before the run time installation starts. Specify the parameters in the following table to provide the information that the run time needs to access the database.

Note: The parameters in this topic do not apply to console run time installations on i5/OS systems.

LDAP user registry response file properties

If you are installing the console for the first time on the system, the parameters listed in Table 6 enable WebSphere Application Server security and specify information about the LDAP user registry. The application server can be the one that is embedded in the Integrated Solutions Console or a separate WebSphere Application Server installation.

DB2 user registry response file properties

If you are installing the console for the first time on the system, the parameters listed in Table 7 enable WebSphere Application Server security and specify the DB2 information for the user registry. The application server can be the one that is embedded in the Integrated Solutions Console or a separate WebSphere Application Server installation.

To this point all I've done is build a response file. This response file contains all the parameters necessary for the Integrated Solutions Console installation program to run. All that remains is learning how to start the install and pass it the response file you just generated.

Starting the Install

Figure 2 illustrates the process for invoking the Integrated Solutions Console installation and deploying your components.

As Figure 2 shows, your product installation program must perform the following steps to install the Integrated Solutions Console run time and deploy your components:

1. Check for an existing Integrated Solutions Console installation on this machine.
• For AIX, Linux, Solaris, and Windows installations, issue the following command (on a single line) to invoke ISCAction:

     java -cp
                fully-qualified_path/ISCAction.jar run -silent    -W
                available.version="available_version"    -W
                appServer.location="location" 

• For i5/OS installations, issue the following command (on a single line) to invoke ISCAction:

     java -cp
                fully-qualified_path/ISCAction.jar run -silent    -W
                available.version="available_version"     -W
                appServer.location="location"     -W
                appServer.instance="instance"   

where:

• fully-qualified_path is the fully-qualified path for the ISCAction.jar file.
• available_version is the version number of the Integrated Solutions Console run time that your installation program embeds. For Version 5.1, the only valid value is 5.1.
• location has one of the following values:
• For AIX, Linux, Solaris, and Windows installations that use the application server that is embedded in the run time for Integrated Solutions Console, the value is "" (empty string).
• For AIX, Linux, Solaris, and Windows installations that use a separate WebSphere Application Server installation, the value is the fully-qualified path to that installation. An example is "C:\Program Files\WebSphere\AppServer".
• For i5/OS installations that use WebSphere Application Server Express, the value is /QIBM/ProdData/WebASE51/ASE.
• For i5/OS installations that use WebSphere Application Server Base, the value is /QIBM/ProdData/WebAS51/Base.
• instance is the name of the WebSphere Application Server instance that the console uses on the i5/OS system.

The ISCAction.jar file is in the root directory of the Integrated Solutions Console download image.

2. Prompt the user for the Integrated Solutions Console configuration information. Use that information to update the base response file.
3. For AIX, Linux, Solaris, and Windows installations, if the user specifies the option to use an existing DB2 installation for the console data store (dbChoice.dbChoice="db2"), the console database must already exist before you run ISCCheck to validate the user input. Your product installation program should create the console database for the user or your product documentation should instruct the user to create the database before the user starts the installation program.
4. Verify that the system meets the Integrated Solutions Console software and hardware prerequisites and that the information in the response file is correct. Issue the following command (on a single line) to invoke ISCCheck:

   java -cp
                fully-qualified_path/ISCCheck.jar run -silent    -W
                response.file="response_file" 

where:

• fully-qualified_path is the fully-qualified path for the ISCCheck.jar file.
• response_file is the fully-qualified path for the response file that contains the user input.

See Return codes for a description of the ISCCheck return codes. ISCCheck logs error and warning messages to the standard output. Display the error and warning messages to the user. If ISCCheck detects errors in the response file, your program can prompt the user to correct the errors in the user input.

5. Start the run time installation. Issue the following command (on a single line) to invoke ISCRuntime:

   java -cp
                fully-qualified_path/ISCRuntime.jar run -options
                response_file 

where:

• fully-qualified_path is the fully-qualified path for the ISCRuntime.jar file. The ISCRuntime.jar file is in the root directory of the Integrated Solutions Console download image.
• response_file is the fully-qualified path for response file that contains the user input.

Note:

• ISCRuntime calls ISCCheck to verify the system configuration again. If the check is successful, ISCRuntime installs the run time (if necessary) and adds your product information to the product registry.
• ISCRuntime logs messages to ISCRuntimeInstall.log. See Return codes for a description of the ISCRuntime return codes. Your program must respond to error codes.
• For i5/OS systems, your program must determine the cause of ISCRuntime errors, perform the manual uninstall steps to clean up the failed installation, and then restart the installation.
• In addition to using the ISCRuntime return codes, you can also monitor the overall progress of the console installation and errors that cause the installation to fail. See the Installation progress indicator file for instructions.
• In certain configurations on Windows machines with multiple network interface cards, the installation program can fail due to the system returning a different host name than is expected. See Systems with multiple network adapters for more information.
• The run time installation automatically starts the Integrated Solutions Console if the installation is successful. If you need to stop or start the server after the initial installation, see Stopping and starting the servers.

6. Deploy the components for your product. Those components provide the pages for administering your product and resources through the Integrated Solutions Console. See Embedding component deployment for a detailed description of the Java™ commands for using the deployment tool and the return codes for those classes.

When developing this portion of your installation program, remember the following points:

• Verify that your components have been tested and that any errors have been fixed.
• Deploy your components after the installation of the Integrated Solutions Console run time has completed successfully.
• Your product package must also include the code for removing deployed components.

Note: Some operating systems restrict access to directories. Be sure to arrange your directories so that your product installation program can access the Integrated Solutions Console installation program, the installation files, and the response file.

Back to top

Monitoring the installation

After your product installation program invokes the Integrated Solutions Console installation program, it must monitor the installation. This section discusses the various ways to monitor the return codes and log files produced by the install program.

Return codes

ISCAction returns a two-digit return code. Table 8 lists the meaning of each digit in the code. The following scenarios are examples of scenarios for ISCAction:

• If you run ISCAction and specify an existing WebSphere Application Server installation, the return code is 55 if Integrated Solutions Console is not already installed on that WebSphere Application Server and security is not enabled on the server.
• Return code 78 indicates that the current version of Integrated Solutions Console is already installed on the specified WebSphere Application Server and LDAP security is enabled for that server.
• Return 9x and x9 indicate an error that should be debugged.
• Return codes that are outside of the values listed in Table 8 indicate that the ISCAction command was not invoked correctly. Examples of such codes are 51, 1, and even 0 (which frequently indicates normal operation in other programs). For example, if you try to run /usr/bin/notjava -cp /usr/ISC/ISCAction.jar run -W available.version="5.1" -W appServer.location="", the return code might be 127, which is the UNIX code for "not found" because notjava is not the name of a program on the system.

Table 9 lists the codes returned by ISCCheck and ISCRuntime.

If your installation program is Java-based, you can use the exitValue method as illustrated in Listing 5 (which does not apply to i5/OS systems):

           Process p;
                if(SystemServices.isWindows()) {              String[]
                winCmdArray = {"cmd.exe","/C",temp};
                p = Runtime.getRuntime().exec(winCmdArray,
                envVars == null ? null : (String[])envVars.toArray(new
                String[0]));           }            else {
                String[] unixCmdArray =
                {"/bin/sh","-xc",temp};
                p = Runtime.getRuntime().exec(unixCmdArray,
                envVars == null ? null : (String[])envVars.toArray(new
                String[0]));           }           try {
                p.waitFor();           }
                catch(InterruptedException e) {}
                return(p.exitValue());           

If your installation program is not Java-based and runs on a Windows system, you can monitor the environment variable %errorlevel% as illustrated in Listing 6.

echo %errorlevel%

If your installation program is not Java-based and runs on an AIX, Linux, i5/OS, or Solaris system, you can monitor the environment variable $? as illustrated in Listing 7.

echo $?

Note: If your base response file contains passwords that are not encrypted, your installation program should delete the file, or direct the user to secure or discard the file after the installation has completed successfully.

Progress indicator

You can monitor the overall progress of the console installation by using information in the progress indicator file. The following points are the key aspects of the properties file:

• The progress indicator is the file temp/ISCRuntimeInstallProgress.properties, where temp is the value of the operating system variable %TEMP% on Windows systems, /tmp/InstallShield on i5/OS systems, and /tmp on the other systems. Depending on the operating system, these files might not be saved after the system is shutdown.
• The progress indicator file is overwritten each time it is updated at predetermined points during the installation.
• If you attempt a subsequent installation on the same machine, an old copy of the file might still be in the system temporary directory. In such cases, remove the file before starting the subsequent installation.
• The progress indicator file contains the following properties:
• percentage=percent_progress
• status=status_code
• timestamp=date_time
• ISC_FAILURE_MESSAGE=message

where:

• percent_progress is a rough calculation of the amount of the installation that has been completed. Valid vales are 0 to 100. These values are not posted at equal intervals, such as at 5%, 10%, 15%, and so on.
• status_code is one of the following strings: RUNNING, FAILED, PAUSED, and SUCCESSFUL. The strings are not translated.
• date_time is the date and time of the last update to the ISCRuntimeInstallProgress.properties file. This string is generated by using the Java Date.toString() method. For a description of the date field format, see the Javadoc for the java.util.Date.toString() method.
• message is a message that indicates a failure in the installation. Use this field to troubleshoot the problem. The parameter value will be unique for each failure point, but each failure point might have multiple causes. This property does not have a value if the installation was successful. An example of a message is the following message: (May 25, 2004 9:38:56 PM), Setup.product.install, com.ibm.pvc.we.care.ismp.FailAndExitAction, wrn, PortalRunUpdateTask2AgainFail_Exit.
• Although the status property includes FAILED and SUCCESSFUL indications, always use the ISCRuntime return code to determine success or failure. ISCRuntime always sends a return code as its last action

Back to top

Troubleshooting an install

This section describes the log files created during installations and recommends when to check the file for information that might assist in troubleshooting problems.

Location of log files

The location of the log files varies according to the operating system:

• For AIX, Linux, Solaris, and Windows systems, the log files are written to the operating system temporary directory, which is the value of the system variable %TEMP% on Windows systems, /tmp/InstallShield on i5/OS systems, and /tmp on the other systems. Depending on the operating system, these files might not be saved after the system is shut down.
• For i5/OS systems, the log files are in the path /tmp/InstallShield. The log files are created if the console run time is installed as part of a product installation that embeds the Integrated Solutions Console.

Names of log files

Table 10 lists the names of the log files.

What to look for in the log files

The first log to look at is always the ISCRuntimeInstall.log. Look for messages that indicate that a command failed. In most cases this can be found at the bottom of the log. This will most likely point off to another log file where the error actually occurred. Notice the following:

(Sep 2, 2005 3:04:45 PM), Setup.product.install, com.ibm.pvc.we.care.ismp.FailAndExitAction, wrn, PortalAddWPSinstanceFail

This message in the ISCRuntimeInstall.log tells the installer that a failure occurred in the PortalAddWPinstance ANT task. This task has a corresponding log file located in the /tmp/InstallShield directory. If you look at the PortalAddWPinstance.log file you can find more detailed information on why the failure occurred.

Common problems

Following is a list of common install problems:

• Invalid LDAP credentials.
• An administration product like Virtualization Engine has already installed the Integrated Solutions Console, which results in the call to ISCAction failing with a return code.
• For installs on i5/OS, the WebSphere Application Server is not installed with the embedded installation. It is up to the deploying product to install the required WebSphere fixes.
• In the PortalBasicConfig.log file for installs on i5/OS, the following is seen:

  Listing 8. PortalBasicConfig.log file
  

  [wsadmin] WASX7017E: Exception received while running file "BM/UserData/WebASE/ASE5/SYSINST/PortalServer/config/work/was/createWpsEar.jacl" exception information: com.ibm.bsf.BSFException: error while eval'ing Jacl expression: com.ibm.ws.scriptingScriptingException com.ibm.websphere.management.exception.AdminException: ADMA0094E: Application Management operation installApplication is not available in your WebSphere installation.

  
  

  This is due to the correct PTF not being install to match the corresponding fix level of WebSphere Application Server. Refer to the chart below.

If the embedding product is using ISC 5.0.2, which will use WebSphere Application Server 5.0.2, and is intending on installing on i5/OS, make sure you have the correct 5722DG1 PTF that corresponds with the fix level of WebSphere Application Server V 5.0.2 that is currently on your system:

• WebSphere Application Server V 5.0.2.3 Express requires 5722DG1 SI12051
• WebSphere Application Server V 5.0.2.4 Express requires 5722DG1 SI12730
• WebSphere Application Server V 5.0.2.5 Express requires 5722DG1 SI13552
• WebSphere Application Server V 5.0.2.6 Express requires 5722DG1 SI14456
• WebSphere Application Server V 5.0.2.7 Express requires 5722IWE SI15467 (no 5722DG1 PTF required), also requires 5722IWE SI16369
• WebSphere Application Server V 5.0.2.9 Express requires 5722IWE SI17016

Here are the corresponding Group PTF numbers to order for WebSphere Application Server on i5/OS. This update the fix levels of WebSphere, Java code, DB2/400, and IBM HTTP Server:

• WebSphere Application Server V 5.0 Express Group PTF: SF99272
• WebSphere Application Server V 5.0 Base Group PTF: SF99287
• WebSphere Application Server V 5.1 Express Group PTF: SF99275
• WebSphere Application Server V 5.1 Base Group PTF: SF99285

Steps to take to ensure a successful install

If you have a problem with installing the Integrated Solutions Console, perform the following procedure:

1. Verify that:
• The correct prerequisites are installed, which include but are not limited to:
• Operating system type and fix level (including PTFs for i5/OS)
• Hardware meets minimum recommended levels
• WebSphere Application Server version and fix levels if installing into an existing WebSphere Application Server
• The settings (such as user IDs and passwords) that you specified are correct, which include but are not limited to:
• LDAP IDs and passwords
• Local operating system IDs and passwords
• Remote DB IDs and passwords
• WebSphere Application Server IDs and passwords if the server is already secure
• You have followed all of the installation instructions.
• If you attempted a previous install, make sure you have run the uninstall along with following the corresponding uninstall instructions.
2. Check the installation log files for error messages and return codes.

Back to top

Conclusion

This article discussed in depth the process involved in embedding the Integrated Solutions Console installer, which is used to administer different products using a single Web-based console. The goal of the article is to make you aware of some common problems and how to recover from those problems faster.

Resources

• For overview information about the Integrated Solutions Console, take the tutorial Create an administrative suite (developerWorks, February 2004).
  
  
• Help in the Integrated Solutions Console (developerWorks, February 2004) takes you through the features of a common help framework for Web-based applications that are deployed to the IBM Integrated Solutions Console Version 5.0.1.
  
  
• See Enable a help system within the Integrated Solutions Console (developerWorks, May 2004) to learn how the Eclipse help infocenter is integrated with the Integrated Solutions Console run time. Using a downloadable sample file, you'll step through the complete cycle of creating a help plug-in.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Embed the installation
• Monitoring the installation
• Troubleshooting an install
• Conclusion
• Resources
• About the author
• Comments