Debugging Jython script files on WebSphere Application Server

The debugger enables you to detect and diagnose errors in your Jython script. It allows you to control the execution of your script by setting breakpoints, suspending threads, stepping through the code, and examining the contents of the variables. To debug Jython scripts, you will use the WebSphere® Administrative Script Launcher to set up the runtime environment to interpret your script, and the security settings; if your script is running against a secured server.
Prerequisite: Restriction:

To debug Jython scripts:

  1. Open a Jython script file in the Jython editor:
    1. In Navigator view, expand the Jython project that contains the Jython script file you want to debug your Jython script file.
    2. Right-click the Jython script file.
    3. In the pop-up menu, select Open With > Jython Editor.
  2. Set breakpoints in the Jython script. To set one or more breakpoints in the Jython editor, double-click in the margin beside the line of code that you want to set as a breakpoint.
  3. In the Jython editor, right-click and in the pop-up menu select Debug As > Administrative script. The WebSphere Administrative Script Launcher opens. Use the WebSphere Administrative Script Launcher to debug administrative script files on WebSphere Application Server from within the development environment.
  4. The Script page, is the main page of the WebSphere Administrative Script Launcher.
  5. The Administrative Script field is automatically pre-filled with the path to your script file.
  6. In the Scripting runtime list, select a name of an installed WebSphere Application Server runtime environment as defined in the Preferences page (Window > Preferences > Server > Installed Runtimes). You need to specify a runtime environment that is on your local file system to interpret your script file. If the runtime environment you want to interpret your script file is not available in the drop-down list, click the New button to define a new WebSphere Application Server runtime environment. The New Server Runtime wizard opens. Although the New Server Runtime wizard allows you to create any runtime environments, when using the WebSphere Administrative Script Launcher for debugging Jython script, only the local WebSphere Application Server v6.1 runtime environment is supported for debugging.
    Note: If you defined WebSphere Application Server v6.0.x1 or v5.11 as installed runtime environments, you may see these runtimes listed under the WebSphere Runtime drop-down list. But these runtime environments are not supported for debugging, as a result, the Debug button is not available and the following error message is displayed:
    Running a debug configuration is not supported for this type of
    scripting runtime.
    However, the Apply button is available, which allows you to save the configuration from the WebSphere Administrative Script Launcher for running the Jython script in non-debug mode. See Running administrative script files on WebSphere Application Server for details on running Jython scripts.
  7. In the WebSphere Profile list, select a profile that belongs to the previously selected runtime environment. A profile is the set of files that define the runtime environment. If you select the [Unspecified] option, the tooling will choose the profile who is assigned the default role.
  8. (Optional) In the wsadmin arguments field, specify advanced command-line invocation syntax for the wsadmin scripting client. This WebSphere Administrative Script Launcher already handles the following information passed to the wsadmin scripting client:
    • the file name and path of the script file
    • the language of the script file
    • the name of the WebSphere profile used to run your script file
    • the user ID and password to authenticate to the targeted secured server
    Do not specify the information again in the wsadmin arguments field.
    Tip: If you want to pass arguments to your Jython script, do not specify them in this wsadmin arguments field, as this field is target for the wsadmin scripting client. Instead, select the Arguments page and in the Program arguments text box specify your program arguments.
    Note: If you need to specify the program arguments for issuing your Jython scripts, keep in mind that the first program parameter is used for different purposes when debugging versus running the Jython scripts. For details, see the Jython debugger inserts the filename of the script for the sys.argv[0] topic.
  9. In the Security section, specify if your script is running against a server that is secured by selecting one of the following options.
    Option Description
    No security on target server Specifies your script is running against a server that is not secured.
    As defined in soap.client.props or sas.client.props file

    Specifies that your script is running against a secured WebSphere Application Server, and you have supplied authentication information in the sas.client.props or the soap.client.props files to communicate with this secured server.

    The sas.client.props and the soap.client.props files are located in the properties directory for each WebSphere Application Server profile, for example x:/profilePath/properties.

    If you use a Remote Method Invocation (RMI) connector, set values for the following properties in the sas.client.props file with the appropriate values:

    com.ibm.CORBA.loginUserid=
    com.ibm.CORBA.loginPassword=
    Also, set the following property:
    com.ibm.CORBA.loginSource=properties
    The default value for this property is prompt in the sas.client.props file. If you leave the default value, a dialog box appears with a password prompt. If the script is running unattended, it appears to hang.
    If you use a Simple Object Access Protocol (SOAP) connector, set values for the following properties in the soap.client.props file with the appropriate values:
    com.ibm.SOAP.securityEnabled=true
    com.ibm.SOAP.loginUserid=
    com.ibm.SOAP.loginPassword=
    Optionally, set the following property:
    com.ibm.SOAP.loginSource=none
    You can find the default value for this property in the soap.client.props file. If you accept the default value and do not provide loginUserid and loginPassword values, a dialog box appears with a password prompt. If the script is running unattended, it appears to hang.
    Note: If you specify user and password in the Specify section and in the sas.client.props file or the soap.client.props file, the WebSphere Administrative Script Launcher overrides the information in the .props file.
    Specify Specifies that your script is running against a server that is secured.

    In the User ID and Password field, type the user ID and password to authenticate to this targeted secured server.

    If you specify user ID and password information in this section and in the sas.client.props file or the soap.client.props file, the WebSphere Administrative Script Launcher overrides the information in the .props file.

    Attention: The use of the password option may result in security exposure as the password information becomes visible to the system status program such as ps command which can be invoked by other user to display all the running processes. Do not use this option if security exposure is a concern. Instead, select the As defined in soap.client.props or sas.client props file radio button; and specify the user ID and password information in the soap.client.props file for SOAP connector or sas.client.props file for RMI connector. The soap.client.props and sas.client.props files are located in the properties directory of your WebSphere Application Server profile.
  10. Click the Apply button to save your configuration. Using the Apply button will automatically populate the appropriate VM arguments and classpaths for your selected WebSphere Application Server runtime environment.
    Tip: If you change your selection for the Scripting runtime list, be sure to click the Apply button for each change to automatically populate the correct VM arguments and classpaths for your newly selected WebSphere Application Server runtime environment.
  11. Remember: Verify that you have breakpoints set in the Jython editor (specified in the earlier steps). Otherwise your debug sessions simply runs to completion.
  12. Click the Debug button to debug your script. The Debug perspective opens.
The debugger suspends on the set breakpoint on your Jython script, and you can further debug the script in the Debug perspective.
Related concepts
Working with a WebSphere Application Server Network Deployment environment
Related reference
Scripting: Resources for learning
Jython debugger demo and test program (DebugTest.py)
Jython debugger inserts the filename of the script for the sys.argv[0]
1 WebSphere Application Server v6.0.x is not available in WebSphere Application Server Toolkit V6.1.x, but available in products such as Rational® Application Developer V7.0.x or Rational Software Architect V7.0.x

Feedback