isCOBOL Evolve : SDK User's Guide : Debugger : Remote Debugging
Remote Debugging
isCOBOL allows remote debugging of programs.
Remote debugging is often used in the following scenarios:
• to debug a servlet or a web service running under Tomcat or other servlet container,
• to debug a COBOL program running via webclient,
• to debug a COBOL program that is called by foreign languages like C or Java,
• to debug a program with character-based interface managed by CHARVA,
• to debug a remote program running in the isCOBOL Server.
The program must have be compiled with either -d option or -dx option.
At run time, the only requirement is that the iscobol.rundebug * property is set to 1 or 2 in the isCOBOL configuration. The program runs normally, listening on the TCP/IP port 9999. A different port number can be set via the iscobol.debug.port configuration property.
To start a remote debugging session, the isCOBOL Debugger needs to know the host name of the machine running the program to be debugged and the port number dedicated to the debugger connection. Use the following command:
iscrun [ -J-Discobol.debug.code_prefix=sourcePaths ] [ -d ] -r [ [ HostName ] Port ]
When running on Windows, the following command can also be used:
isrun [ -J-Discobol.debug.code_prefix=sourcePaths ] [ -d ] -r [ [ HostName ] Port ]
The -d option can be omitted when -r is used.
If HostName is omitted, then localhost is assumed.
If Port is omitted, then 9999 is assumed.
If sourcePaths includes multiple paths, they must be separated by the system path separator.
When the Debugger attaches to a program, it looks for the program source and copy files in the following paths:
• Paths stored in the class file, looking for relative paths in the current working directory.
• Paths stored in the class file, looking for relative paths in the paths of the iscobol.debug.code_prefix property.
• Basename of paths stored in the class file, looking in the paths listed in the iscobol.debug.code_prefix property.
• Paths stored in the class file, looking for relative paths in the paths of the CLASSPATH environment variable.
• Basename of paths stored in the class file, looking in the paths listed in the CLASSPATH environment variable.
In thin client environment you can debug the isCOBOL Server activity by running the isCOBOL Client with the -d option as explained in Usage of isCOBOL Client, Format 6.
Automatic download of source files
If the source files are not available on the local PC where you run the Debugger, but they’re on the remote machine instead, you can ask the remote runtime to send the source files through TCP/IP. In order to activate this feature, set iscobol.debug.remote_source (boolean) to true on the local PC and iscobol.debug.remote_source_enabled (boolean) to true on the remote machine. The remote runtime will look for source files in its Classpath and iscobol.debug.code_prefix setting.
Examples
• Example of remote debugging in thin client with automatic download of source files.
1. Start the server as follows:
iscserver -c server.properties
2. Launch the Client as follows:
iscclient -J-Discobol.debug.remote_source=1 -hostname <server-ip> -d MAIN_PROGRAM
Content of server.properties:
iscobol.rundebug=2
iscobol.debug.remote_source_enabled=1
iscobol.debug.code_prefix=/path/to/cbl_files\n/path/to/copy_files
• Example of remote debugging of a character-based application (CHARVA) with automatic download of source files.
1. Start the application as follows on the server:
iscrun -c runtime.properties -t MAIN_PROG
2. Run the following command on the local PC:
iscrun -J-Discobol.debug.remote_source=1 -r <server-ip>
Content of runtime.properties:
iscobol.rundebug=2
iscobol.debug.remote_source_enabled=1
iscobol.debug.code_prefix=/path/to/cbl_files\n/path/to/copy_files
• Example of remote debugging of an EIS servlet with automatic download of source files.
1. Add the following entries to WEB-INF/classes/iscobol.properties:
iscobol.rundebug=2
iscobol.debug.remote_source_enabled=1
iscobol.debug.code_prefix=/path/to/cbl_files\n/path/to/copy_files
2. Navigate to the servlet’s URL with your favorite browser in order to trigger the execution of the underlying COBOL program,
3. Run the following command:
iscrun -J-Discobol.debug.remote_source=1 -r <servlet-container-ip>