Start the wsadmin scripting client

Use the wsadmin tool to administer application servers, application deployment, and server runtime operations.

The wsadmin tool provides the ability to automate configuration tasks for the environment by running scripts. However, there are some limitations for using the wsadmin tool, including:

• The wsadmin tool only supports the Jython and Jacl scripting languages.

  The v6.1 release of WAS represented the start of the deprecation process for the Jacl syntax associated with the wsadmin tool. The Jacl syntax for the wsadmin tool continues to remain in the product and is supported for at least two major product releases. After that time, the Jacl language support might be removed from the wsadmin tool. The Jython syntax for the wsadmin tool is the strategic direction for WAS administrative automation. The application server provides significantly enhanced administrative functions and tooling that support product automation and the use of the Jython syntax.

  Deprecated feature: Jacl is deprecated and Jython is the default scripting language.depfeat

  Not all of the WebSphere Application Server component classes are packaged in the same .jar file. If we are going to be using the wsadmin tool to run Jython scripts, include the jython.package.path system property on your wsadmin command to ensure that all of the required JAR files are set to the jython package path during wsadmin startup.

  ./wsadmin.sh -lang jython -javaoption
  "-Djython.package.path=/usr/WebSphere70/AppServer/plugins/com.ibm.ws.wlm.jar"   
  

  To invoke WAS functions from different WAS classes that are packaged in .jar files other than runtime.jar and admin.jar, we can include multiple jar files in the path specified for the jython.package.path system property, and separate them with a semicolon (;).

  ./wsadmin.sh -lang jython -javaoption
  "-Djython.package.path=/usr/WebSphere70/AppServer/plugins/com.ibm.ws.wlm.jar;com.ibm.ws.wccm.jar"  
  

  To invoke WAS functions in a jython script using ws_ant, we can create a .prop text file, and include the following line in this file:

  jython.package.path=/usr/WebSphere70/AppServer/plugins/com.ibm.ws.wlm.jar  
  

  Then include the property file in the ant script xml file. For example:

  <taskdef name="wsadmin" classname="com.ibm.websphere.ant.tasks.WsAdmin"/>
  <target name="main" >  
      <wsadmin conntype="NONE" lang="jython" failonerror="true" properties="/tmp/jython.prop"
               script="/home/fsgapp/MSTWasBuild/project/scripts/socr/socr/jython/configure.py"> 
      </wsadmin>
  </target>  
  

• The wsadmin tool manages the installation, configuration, deployment, and runtime operations for application servers, deployment managers, administrative agents, and job managers that run the same version or a higher version of the product. The wsadmin tool cannot connect to an application server, deployment manager, administrative agent, or job manager that runs a product version which is older than the version of the wsadmin tool. For example, a v7.x wsadmin client cannot connect to a v6.x application server. However, a v6.x wsadmin client can connect to a v7.x application server. This limitation exists because new functionality is added to the wsadmin tool in each product release. We cannot use new command functionality on application servers running previous product versions.

• The wsadmin tool operates at the deployment manager node level in a mixed-cell environment. Do not run wsadmin at the application server node level to ensure that all command functionality is available.

The wsadmin launcher supports several scripting objects, including the AdminConfig, AdminControl, AdminApp, AdminTask, and Help objects. Scripts use these objects for application management, configuration, operational control, and for communication with MBeans that run in product processes. We must start the wsadmin scripting client before performing any other task using scripting.

(ZOS) Before starting the wsadmin tool with security enabled, review the topic SSL considerations for WAS administrators and the topic Defining SSL security for clients and servers.

In a flexible management environment, we can connect the wsadmin tool to a base application server, deployment manager, administrative agent, or job manager process. If we do not specify the port of the base application server or the profile name assigned to the job manager, the wsadmin tool automatically connects to the administrative agent.

The application management design does not allow us to install an EE specification level EAR or module that is at a higher level than the client. Client code that runs in wsadmin reads the EAR file and uses introspection of the content to generate the deployment configuration options that are applicable to that application. The client side code cannot process a specification level that is higher than what that client supports..

Tasks

1. Locate the command that starts the wsadmin scripting client.

   (ZOS) The command for invoking a scripting process is located in the app_server_root/bin directory. Use the wsadmin.sh file.

   Choose one of the following:

   • Invoke the scripting process using a specific profile. The QShell command for invoking a scripting process is located in the profile_root/bin directory. The name of the QShell script is wsadmin. If we use this option, we do not need to specify the -profileName profile parameter.

   • Invoke the scripting process using the default profile. The wsadmin Qshell command is located in the app_server_root/bin directory. If we do not want to connect to the default profile, specify the -profileName profile parameter to indicate the profile to use.

2. In a flexible management environment, determine whether to connect to a base application server, administrative agent, or job manager process.
   • Connect to the administrative agent process.

     Connect the wsadmin tool to the administrative agent to configure, manage, and administer servers. If we do not specify connection options, the wsadmin tool automatically connects to the administrative agent process. To connect to the administrative agent:

     wsadmin -lang jython
     

   • Connect to a base application server process.

     Connect the wsadmin tool to a base application server to manage settings for a specific server of interest. Use this connection type when connecting to a node containing one server and is registered with the administrative agent. Use a command such as the following to connect to a base application server:

     wsadmin -conntype SOAP [-port 4213] -lang jython
     

   • Connect to the job manager process.

     Connect the wsadmin tool to the job manager to submit, monitor, and manage administrative jobs. Use a command such as the following to connect to the job manager:

     wsadmin -profileName JobMgr01 -lang jython
     

3. Review additional connection options for the wsadmin tool.

   We can start the wsadmin scripting client in several different ways. To specify the method for running scripts, perform one of the following wsadmin tool options:

   Run scripting commands interactively

   Run wsadmin with an option other than -f or -c or without an option. The wsadmin tool starts and displays an interactive shell with a wsadmin prompt. From the wsadmin prompt, enter any Jacl or Jython command. We can also invoke commands using the AdminControl, AdminApp, AdminConfig, AdminTask, or Help wsadmin objects. To leave an interactive scripting session, use the quit or exit commands. These commands do not take any arguments.

   The following examples launch the wsadmin tool:

   • Launch the wsadmin tool using Jython:

     (UNIX) (ZOS)

     wsadmin.sh -lang jython
     

     (iSeries)

     wsadmin -lang jython
     

     (Windows)

     wsadmin.bat -lang jython
     

   • Launch the wsadmin tool using Jython when security is enabled:

     (UNIX) (ZOS)

     wsadmin.sh -lang jython -user user_name -password password
     

     (iSeries)

     wsadmin -lang jython -user user_name -password password
     

     (Windows)

     wsadmin.bat -lang jython -user user_name -password password
     

   • Launch the wsadmin tool using Jacl with no options:

     (UNIX) (ZOS)

     wsadmin.sh -lang jacl
     

     (iSeries)

     wsadmin -lang jacl
     

     (Windows)

     wsadmin.bat -lang jacl
     

   Run scripting commands as individual commands

   Run the wsadmin tool with the -c option.

   (UNIX) (ZOS) If we invoke a command that includes a dollar sign character ($) using the wsadmin -c option, the command line attempts to substitute a variable. To avoid this problem, escape the dollar sign character with a backslash character (\). For example: wsadmin -c "\$AdminApp install ...".

   The following examples run commands individually:

   • Run the list command for the AdminApp object using Jython:

     (UNIX) (ZOS)

     wsadmin.sh -lang jython -c 'AdminApp.list()'
     

     (iSeries)

     wsadmin -lang jython -c "AdminApp.list()"
     

     (Windows)

     wsadmin -lang jython -c "AdminApp.list()"
     

   • Run the list command for the AdminApp object using Jacl:

     (UNIX) (ZOS)

     wsadmin.sh -c "\$AdminApp list"
     

     or

     wsadmin.sh -c '$AdminApp list'
     

     (iSeries)

     wsadmin -c "$AdminApp list"
     

     (Windows)

     wsadmin -c "$AdminApp list"
     

   Run scripting commands in a script

   Run the wsadmin tool with the -f option, and place the commands to run into the file.

   (ZOS) WAS for z/OS supports multiple encoding for the Jacl and Jython command files. The default encoding for the command files is ASCII. To run an EBCDIC encoded file, add the following JVM argument to the wsadmin.sh file through the -javaoption flag:

   -Dscript.encoding=Cp1047
   

   For example:

   wsadmin.sh -javaoption -Dprofile.encoding=Cp1047
   

   We can alternatively have two versions of the wsadmin.sh file, one that references the ASCII version of the file and another that references the EBCDIC version of the file. For example, copy the wsadmin.sh file to the wsadminE.sh file. Then add -Dscript.encoding=Cp1047 to the wsadminE.sh file.

   The following examples run scripts:

   • Run the a1.py script using Jython:

     (UNIX) (ZOS)

     wsadmin.sh -lang jython -f  al.py
     

     (iSeries)

     wsadmin -lang jython -f  al.py
     

     (Windows)

     wsadmin -lang jython -f  al.py
     

     where the a1.py file contains the following commands:

     apps = AdminApp.list()
     print apps
     

   Run scripting commands in a profile script

   A profile script is a script that runs before the main script, or before entering interactive mode. Use profile scripts to set up a scripting environment that is customized for the user or the installation.

   (ZOS) WAS for z/OS supports multiple encoding for Jacl and Jython profile scripts. The default encoding for the profile file is ASCII. To run an EBCDIC encoded profile script file, add the following JVM argument to the wsadmin.sh file:

   -Dprofile.encoding=Cp1047
   

   For example:

   wsadmin.sh -javaoption -Dprofile.encoding=Cp1047
   

   We can alternatively have two versions of the wsadmin.sh file, one that references the ASCII version of the file and another that references the EBCDIC version of the file. For example, copy the wsadmin.sh file to the wsadminE.sh file. Then add -Dprofile.encoding=Cp1047 to the wsadminE.sh file.

   By default, the following profile script files might be configured for the com.ibm.ws.scripting.profiles profiles property in the app_server_root/properties/wsadmin.properties file:

   • app_server_root/bin/securityProcs.jacl
   • app_server_root/bin/LTPA_LDAPSecurityProcs.jacl

   By default, these files are in ASCII. If we use the profile.encoding option to run EBCDIC encoded profile script files, change the encoding of the files to EBCDIC.

   To run scripting commands in a profile script, run the wsadmin tool with the -profile option, and include the commands to run into the profile script.

   To customize the script environment, specify one or more profile scripts to run.

   Do not use parenthesis in node names when creating profiles.

   The following examples run profile scripts:

   • Run the a1prof.py script using Jython:

     (UNIX) (ZOS)

     wsadmin.sh -lang jython -profile alprof.py
     

     (iSeries)

     wsadmin -lang jython -profile alprof.py
     

     (Windows)

     wsadmin.bat -lang jython -profile alprof.py
     

     where the a1prof.py file contains the following commands:

     apps = AdminApp.list()
     print "Applications currently installed:\n " + apps
     

   • Run the a1prof.py script using Jacl:

     (UNIX) (ZOS)

     wsadmin.sh -profile alprof.jacl
     

     (iSeries)

     wsadmin -profile alprof.jacl
     

     (Windows)

     wsadmin.bat -profile alprof.jacl
     

     where the a1prof.py file contains the following commands:

     set apps [$AdminApp list]
     puts "Applications currently installed:\n$apps"
     

The wsadmin returns the following output when it establishes a connection to the server process:

Jython example output:

Applications currently installed:
 DefaultApplication
ivtApp
query
WASX70311: For help, enter: "print Help.help()"
wsadmin>

Jacl example output:

Applications currently installed:
 DefaultApplication
ivtApp
query
WASX70311: For help, enter: "$Help help"
wsadmin>

(ZOS) If we receive the message:

[ Unable to allocate an initial java heap of 268435456 bytes. ]
[ **Out of memory, aborting** ]
[ *** panic: JVMST016: Cannot allocate memory for initial java heap ]
CEE5207E The signal SIGABRT was received.

the wsadmin scripting client was unable to start because the region size on your login is not large enough to allocate the minimum heap size (-Xms ) that is specified on the JVM created when wsadmin starts. The default value for the -Xms option, as specified in the wsadmin.sh file statement PERF_JVM_OPTIONS="-Xms256m -Xmx256m, is is 256 MB. To correct this problem, log out of TSO, and then when you log back in to TSO try to increase the value of the Size parameter on your login screen. If we cannot increase the value of the Size parameter on your login screen, check to see if any IEFUSI exits that prevents you from increasing the value of this parameter.

(ZOS) If we are logging in by telnet to OMVS, the value used to determine the address space size that your login receives is specified in the BPXPRMxx parmlib member. BPXPRMxx controls the complete environment of z/OS UNIX. Therefore the value set for the MAXASSIZE parameter determines the size of the address space. However, if we are using RACF, the address size can also be set for an individual user in the respective RACF OMVS segment. In this situation the value specified for the ASSIZEMAX parameter indicates, in bytes, the address space size limit for that user. For example a setting of ASSIZEMAX=0268435456 indicates the address space allocated to that user is 256 MB.

wsadmin scripting tool