The launchClient script

Use the launchClient script to start your J2EE client application. Although it is valid to run application clients with nodes in a Network Deployment environment, do not use the launchClient script in the Network Deployment installation. Instead, use the launchClient script shipped in the bin directory of the Base installation.

Product

The launchClient script is available in WAS.

Authority

To run this script, your user profile must have the following authorities:

• /QIBM/UserData/WebAS5/Base/instance/                           *X

• /QIBM/UserData/WebAS5/Base/instance/bin                            *X

• /QIBM/UserData/WebAS5/Base/instance/bin/setupCmdLine                      *RX

• /QIBM/UserData/WebAS5/Base/instance/properties                            *X

• /QIBM/UserData/WebAS5/Base/instance/properties/client.policy              *R

• /QIBM/UserData/WebAS5/Base/instance/properties/implfactory.properties     *R

• /QIBM/UserData/WebAS5/Base/instance/properties/java.security              *R

• /QIBM/UserData/WebAS5/Base/instance/properties/sas.client.props           *R

• /QIBM/UserData/WebAS5/Base/instance/properties/wsjaas_client.conf         *R

• /QIBM/UserData/WebAS5/Base/instance/etc                                   *X

• /QIBM/UserData/WebAS5/Base/instance/etc/DummyClientKeyFile.jks            *R

• /QIBM/UserData/WebAS5/Base/instance/etc/DummyClientTrustFile.jks          *R

For example, to grant all users execute (*X) authority to the /QIBM/UserData/WebAS5/Base/instance directory, run the following command from Qshell:

chmod a+x /QIBM/UserData/WebAS5/Base/instance

For details on how to assign authorities, see chmod - Change file modes in the iSeries information center.

These authorities are required for secure Web services clients:

• /QIBM/UserData/WebAS5/Base/instance/properties/ws-security.xml       *R

• /QIBM/UserData/WebAS5/Base/instance/etc/samples                             *X

• /QIBM/UserData/WebAS5/Base/instance/etc/samples/enc-sender.jceks     *R

• /QIBM/UserData/WebAS5/Base/instance/etc/samples/dsig-sender.ks       *R

• /QIBM/UserData/WebAS5/Base/instance/etc/samples/intca2.cer       *R

Syntax and parameters

This is command line invocation syntax for the launchClient tool:

launchClient [-instance instance_name] [userapp.ear |-help|-?]
 [-CCname=value] [app args]

where instance_name is the name of your instance, userapp.ear is the fully-qualified path name to the EAR file that contains the application client, name is the name of the parameter, value is the value to which the parameter is set, and app args are arguments that pass to the application client.

The launchClient script requires that the first parameter is one of the following:

• The fully-qualified path name of the enterprise archive (EAR) file that represents the J2EE application client to launch
• A request for launchClient usage information (the -help parameter)

All other parameters are optional and can appear in any order. The application client run time ignores any optional parameters that do not begin with a -CC prefix, and passes them to the application client.

You can specify the directory for an expanded EAR file if you want to avoid extracting the EAR file (and removing the temporary directory) each time launchClient is called.

You can pass parameters to the launchClient script in these ways:

1. From a command line
2. From a properties file
3. With System properties
4. With JVM system properties

The parameters are resolved in the order listed. This prioritization allows you to set and override default values.

Supported arguments for the -CC parameter include:

• -CCsoapConnectorPort
  The soap connector port. If you do not specify this argument, the WAS default value is used. This default is 8880.

• -CCverbose
  This option displays additional information messages. The default is false.

• -CCclasspath
  A class path value. When you launch an application, the system class path is not used. If you want to access classes that are not in the EAR file or part of the resource class paths, specify the appropriate class path here. Use the platform-specific classpath entry separator character to separate multiple classpath entries. For Windows platforms, the separator is a semicolon (;). On iSeries and Unix platforms, the separator is a colon (:).

• -CCjar
  The name of the client JAR file that resides within the EAR file for the application you want to launch. Use this argument when you have multiple client JAR files in the EAR file.

• -CCadminConnectorHost
  Specifies the host name of the server from which configuration information is retrieved. The default is the value of the -CCBootstrapHost parameter or the value of the local host if the -CCBootstrapHost parameter is not specified.

• -CCadminConnectorPort
  Indicates the port number that the administrative client function should use. The default value is 8880 for SOAP connections and 2809 for RMI connections.

• -CCadminConnectorType
  Specifies how the administrative client should connect to the server. Specify RMI to use the RMI connection type or specify SOAP to use the SOAP connection type. The default value is SOAP.

• -CCadminConnectorUser
  Administrative clients use this user name when a server requires authentication. If the connection type is SOAP, and security is enabled on the server, this parameter is required. The SOAP connector does not prompt for authentication.

• -CCadminConnectorPassword
  The password for the user name that the -CCadminConnectorUser parameter specifies.

• -CCaltDD
  The name of an alternate deployment descriptor. This parameter is used with the -CCjar parameter to specify the deployment descriptor to use. Use this argument when a client jar file is configured with more than one deployment descriptor. Set the value to null to use the client JAR file standard deployment descriptor.

• -CCBootstrapHost
  The name of the host server you want to connect to initially. The format is your.server.name, for example: mySystem.myCompany.com.

• -CCBootstrapPort
  The port number on which the name service for the application server is listening. If you do not specify this argument, the WAS default value is used.

• -CCproviderURL
  Provides bootstrap server information that the initial context factory can use to obtain an initial context. WAS initial context factory can use either a CORBA object URL or an IIOP URL. CORBA object URLs are more flexible than IIOP URLs and are the recommended URL format to use. This value can contain more than one bootstrap server address. This feature can be used when attempting to obtain an initial context from a server cluster. You can specify bootstrap server addresses, for all servers in the cluster, in the URL. The operation succeeds if at least one of the servers is running, eliminating a single point of failure. The address list does not process in a particular order. For naming operations, this value overrides the -CCBootstrapHost and -CCBootstrapPort parameters. An example of a CORBA object URL specifying multiple systems follows: -CCproviderURL=corbaloc:iiop:myserver.mycompany.com:9810,:mybackupserver.mycompany.com:2809 This value is mapped to the java.naming.provider.url system property.

• -CCinitonly
  Use this option to initialize application client run time for ActiveX application clients without launching the client application. The default is false.

• -CCtrace
  Use this option to obtain debug trace information. IBM Service may request this information when you report a problem. The default is false.

• -CCtracefile
  The name of the file to write trace information. The default is to output to the console.

• -CCpropfile
  Name of a properties file that contains launchClient properties.

• -CCsecurityManager
  Enables and runs the WAS with a security manager. The default is disable.

• -CCsecurityMgrClass
  The fully qualified name of a class that implements a security manager. Only use this argument if the -CCsecurityManager parameter is set to enable. The default is java.lang.SecurityManager.

• -CCsecurityMgrPolicy
  The name of a security manager policy file. Only use this argument if the -CCsecurityManager parameter is set to enable. When you enable this parameter, the java.security.policy system property is set. The default is user_install_root/properties/client.policy, where user_install_root is the directory specified for the JVM system property user.install.root. This property is set by the setupCmdLine script on the iSeries. On non-iSeries platforms, this property exists only if the multiple instance support is being used. If the property is not set, the launchClient script defaults to install_root/properties/client.policy, where install_root is the root directory of the client application runtime support installation.

• -CCD
  Use this option to have the WAS set the specified system property during initialization. Do not use the = character after the -CCD. The general format of this parameter is -CCDproperty=value, where property is the name of the property, and value is the value of the property. For example: -CCDcom.ibm.test.property=testvalue. You can specify multiple -CCD parameters.

• -CCexitVM
  Use this option to have the WAS call System.exit() after the client application completes. The default is false.

• -CCdumpJavaNameSpace
  Prints out the Java portion of the WAS Java Naming and Directory Interface (JNDI) name space. The true value uses the short format which prints out the binding name and the type of the object bound at that location. The long value uses the long format which prints out the binding name, bound object type, local object, type, and string representation of the local object, for example: IORs, and string values. The default value is false.

Examples

These examples demonstrate the syntax of the launchClient script:

On Windows: launchClient c:\earfiles\myapp.ear -CCBootstrapHost=myWASServer -CCverbose=true app_parm1 app_parm2

On AIX or Solaris: ./launchClient.sh /usr/earfiles/myapp.ear -CCBootstrapHost=myWASServer -CCverbose=true app_parm1 app_parm2

On iSeries: /QIBM/ProdData/WebAS5/Base/bin/launchClient /home/earfiles/myapp.ear -instance myinstance -CCBootstrapHost=myWASServer -CCverbose=true app_parm1 app_parm2