This chapter describes different ways of debugging your applications and how to start Animator.
Before you use Animator, you must compile your source code, including all called programs. See your User's Guide for complete details on compiling in your given environment. You can syntax-check your programs using the COBOL Editor. See the section Syntax-checking and Animating in the chapter Editor of your Utilities Guide for information. You can animate source files containing lines longer than 80 characters, provided that you compiled your program with the SOURCEFORMAT"FREE" directive. However, you should be aware that while Animator does tolerate free-format source code, it does not scroll beyond the normal COBOL margins, so results can be unpredictable.
Note: Programs that output escape sequences to the screen (for example, for cursor and color handling) required the setting of the COBCTRLCHAR environment variable in previous products and debugging of such programs was not supported. The COBCTRLCHAR support, and therefore the ability to output escape sequences, has been removed from this product.
If a program writes directly to the screen, bypassing the COBOL screen handling syntax and routines, you can only debug the program using cross-session debugging. For details on cross-session debugging, see the section Cross-session Debugging.
Animator can be used to debug files in any executable format. The following sections show you how to use the Cob utility to create an executable file ready for use by Animator; in each case, an Animator information file is produced. This file contains additional information required by Animator; it has the file extension .idy. The .idy file created by Server Express is portable to Net Express and Mainframe Express, enabling you to debug your application using these development environments. If you port the .idy file, you must port its associated .int file. You cannot port an .idy file with any other type of executable file for debugging in another environment.
If the system is unable to write to an .idy file, you could receive the following error:
I-O Error: IDY file (fatal)
You should ensure that sufficient disk space is available, and remove any LOCK or READ ONLY attributes that your file contains, and recompile your program.
See the chapters:
Both chapters are in your User's Guide.
cob prog-name.cbl
By default, the COBOL system uses the -a cob flag to compile your source files ready for animation.
cob -ug prog-name.cbl
cob -zg prog-name.cbl
cob -xg prog-name.cbl
Note: The code optimizations that occur when .gnt files are produced create the following restrictions on Animator behavior:
You can start Animator in various ways:
This section describes how to start Animator, and how to set up applications to start Animator. In all cases, if you want to use Animator to debug a program, that program must first be compiled for debugging.
Note: You can invoke Animator using the COBOL Editor. See the section Syntax-checking and Animating in the chapter Editor of your Utilities Guide for information.
Before you invoke Animator, set the environment variable TERM to the appropriate value for your terminal. To enable Animator to search for the required source files and information files in directories other than the current working directory you must set up the COBPATH, COBCPY, COBIDY and COBAIF environment variables. If you have set the COBDATA environment variable, make sure that the path to the file check.lbr is included in the list of paths. See the appendix Environment Variables in your User's Guide for details.
You can start Animator from the command line:
To invoke Animator in the current window use the anim command.
anim [switchparams] program-name [directives]
or:
anim_t [switchparams] program-name [directives]
Use anim_t if your program is multi-threaded. The parameters are:
| switchparams | A set of switches. Each switch must be preceded by a plus sign
(+) to turn it on, or a minus sign (-) to turn it off. Switches can be set in
any order. The last setting of the switch is the one that is accepted.
See the topic Descriptions of Run-time Switches for details on the switches available. |
| program-name | The name of the file you want to animate. If you do not specify
a path, the current directory is assumed.
If you do not specify an extension, a callable shared object is first searched for, followed by .gnt , .int, then .lbr files. |
| directives | An optional sequence of one or more Animator directives. Each
directive must be separated by at least one space and must not be broken across
lines.
See the chapter Directives for Animator for details on the directives available. |
You can start Animator in a different terminal window, if the machine you're debugging on has X windows. This is especially useful for debugging threaded applications.
To get Animator to start in a different terminal window, first ensure that the DISPLAY operating system environment variable is set:
export DISPLAY=local_machine_name:0.0
Then, f you're debugging on a different machine, ensure that the remote machine is allowed to start X clients on the local machine (using the xhost command). Then use the cobanim command:
cobanim [switchparams] program-name [directives]
or:
cobanim_t [switchparams] program-name [directives]
Use cobanim_t if your program is multi-threaded.
The parameters are:
| switchparams | A set of switches. Each switch must be preceded by a plus sign
(+) to turn it on, or a minus sign (-) to turn it off. Switches can be set in
any order. The last setting of the switch is the one that is accepted.
See the topic Descriptions of Run-time Switches for details on the switches available. |
| program-name | The name of the file you want to animate. If you do not specify
a path, the current directory is assumed.
If you do not specify an extension, a callable shared object is first searched for, followed by .gnt , .int, then .lbr files. |
| directives | An optional sequence of one or more Animator directives. Each
directive must be separated by at least one space and must not be broken across
lines.
See the chapter Directives for Animator for details on the directives available. |
You can start Animator in sleep mode. Animator sleeps until a process attaches to it, and then starts in a different window or process to the program you are debugging. This is most useful for cross-session debugging. To run Animator in this way, use the cobanimsrv command:
cobanimsrv [directives]
or:
cobanimsrv_t [directives]
Use cobanimsrv_t if your program is multi-threaded.
The parameters are:
| directives | An optional sequence of one or more Animator directives. Each
directive must be separated by at least one space and must not be broken across
lines.
See the chapter Directives for Animator for details on the directives available. |
You can use directives when Animator is invoked to modify its behavior. You specify directives after the program-name on the command line.
The format for specifying directives is given here. See the chapter Directives for Animator for details on the directives available.
Use the following format for Animator directives:
[no] keyword=parameter
where the parameters are:
| no | Turns keyword off. no can either adjoin the keyword or be separated from it by one or more spaces. no applies only to certain directives as indicated in the directive's description. |
| keyword | One or more Animator directives described in the
chapter
Directives for
Animator.
If you do specify more than one directive, they must all be enclosed in quotation marks. This is necessary to inform UNIX that all the directives in them are grouped together. If you omit the quotation marks, second and subsequent directives are ignored although no warning to this effect is given. |
| parameter | A qualifier to keyword
and applies only to certain directives as indicated in the directive's
description.
=parameter must adjoin keyword. You must not include any spaces in an Animator parameter because UNIX treats the space character as a delimiter. If parameter is a filename, it can be a fully specified filename, including path, unless otherwise stated. If you specify an Animator directive in a $SET statement or in a DIRECTIVES file, parameter cannot be preceded by an equals sign (=). It must be enclosed either in double quotation marks (" ") or parentheses ( ). |
Just-in-time debugging enables you to start Animator and debug a running program if it terminates with a run-time error. This enables you to see what was happening when the program failed.
To start just-in-time debugging you need to add the run-time tunable debug_on_error to the configuration file. To specify which debugger to start, add the run-time tunable debugger_command to the configuration file.
For details on the run-time configuration file and run-time tunables, see the topic Run-time Configuration.
Core dump debugging enables you to see what went wrong during the execution of a program. When an error occurs, the operating system generates a file containing a core dump. The core dump is a snapshot of the process's memory when program execution failed.
To generate a core dump you need to add the run-time tunable core_on_error to the run-time configuration file.
For details on the run-time configuration file and run-time tunables, see the topic Run-time Configuration.
Note: If the tunable debug_on_error is set, the core_on_error tunable is overridden. You must therefore delete any reference to debug_on_error.
To view a core dump, start Animator:
anim core
Unsolicited dynamic attachment enables you to start Animator at any point in a program. To start an unsolicited dynamic attachment you tell Animator which process it needs to attach to.
Use system commands, such as ps, to ascertain the process id of the program to which you want to attach Animator. Then start Animator using the process id:
anim process_id
CBL_DEBUGBREAK is a run-time library routine. It enables you to attach Animator at any point during COBOL code execution. If you have this routine in your program, then Animator starts debugging your program at the line that calls this routine.
For details on using this routine, see the Library Routines.
CBL_DEBUG_START and CBL_DEBUG_STOP are run-time library routines. They enable you to attach and detach Animator at various points during COBOL code execution. They are intended for use in remote and cross-session debugging, but they can also be used to control local animation
The CBL_DEBUG_START and CBL_DEBUG_STOP routines are documented in full in the Library Routines.
When Animator executes a program, the program might need to use the terminal for input and output. If you only have access to a single terminal, and both Animator and the executing program need access to it, Animator keeps a virtual image of the program's output in the background. This image is displayed, and Animator swapped to the background, if you press F2=View, or if Animator itself displays the program's output (during Step or Zoom operations, for example).
By default, the size of this virtual screen is set to 24 lines. You can change this by setting the environment variable LINES before starting Animator; for example:
export LINES=40 anim program.int
You should not set LINES to a size greater than the actual depth of the screen.
For detailed information on environment variables, see the appendix Environment Variables in your User's Guide.
On AIX systems, aixterm terminals have an inner border between the window border and the text. The color of the inner border is always the same as the current background color. When you are using Animator, the background color can change depending on the current function, such as querying a data item; in this case, the color of the terminal border also changes. If you find this distracting, and want to prevent it happening, you are advised to remove the inner border. You can do this by setting the border's size to zero in your .Xdefaults file:
aixterm*internalBorder:0
Animator can keep a record of the breakpoints and monitors you set, so that when you next load the program into Animator, breakpoints and monitors remain in the same state as when you set them in the previous Animator session. This information is kept in the session information file, which has the file extension .aif. Session information files are usually referred to as .aif files. Breakpoints and monitors are described in the chapter Working With Animator
You specify whether or not Animator is to save and load .aif files using the COBAIF Animator directive; by default COBAIF is set on. For information on the COBAIF Animator directive, see the chapter Directives for Animator.
.aif files are loaded or saved by Animator if you:
You can also specify $COBAIFNAME if you are starting Animator using the command anim; in this case the basename you specify overrides the application name as the basename of the .aif file. You must still specify the COBAIF Animator directive.
For details of these environment variables see the appendix Environment Variables in your User's Guide for details.
If you use remote animation with Net Express, breakpoints are saved in Net Express, not Server Express. If you detach from the Net Express animation process and let it continue to run, the breakpoints are lost.
If you need to debug a preprocessor you must start Animator using the CBL_DEBUGBREAK or CBL_DEBUG_START routine. Insert this routine at a suitable point in the preprocessor source code. When the program calls this routine, Animator starts and attaches to the preprocessor.
To enable mixed-language programming, you use Animator and any relevant system debugger. You use Animator to debug the COBOL program - running as one process - and the system debugger to debug the non-COBOL program - running as a separate process.
After compiling both the COBOL and other-language program for debugging, start Animator using the COBOL program, specifying the MIXEDLANGDEBUG Animator directive:
anim prog mixedlangdebug
Note: If you specify MIXEDLANGDEBUG you can only debug using .int files.
You can step through the program as you would normally. When the program calls the other-language program, switch to a different terminal or X window. Ascertain the process id of the running program, using system commands such as grep.
Start the system debugger using the process id. Use the commands in the system debugger to stop when the program enters the called subprogram. From the terminal or X window where Animator is running, step into the call to the sub-program.
Switch back to the terminal or X window in which the system debugger is running. The debugger should have stopped in the called program. You can now debug this function as you like by, for example, setting more breakpoints or querying values, and so on.
Note: For information on using the system debugger, see your system documentation. No information on using system debuggers is given in this manual.
If you are developing a mixed-language application and need to debug a non-COBOL shared object that dynamically loads another non-COBOL shared object, you might find that the system debugger will not allow you to set any breakpoints in the callable shared object until it has been loaded.
To debug your program in this circumstance, you must set a breakpoint on a function called mF_cso_loaded(); this enables you to see when the run-time system loads and unloads shared objects from memory. When you see that your callable shared object has been loaded, you can then set your own breakpoints.
The function mF_cso_loaded() is called whenever a callable shared object is loaded or unloaded. It has two arguments; the first is the name of the callable shared object being loaded or unloaded, while the second is set to zero for a load, non-zero for an unload.
This section assumes that you are familiar with multi-threaded programming. If you are not, see your Multi-threaded Programming book.
When you compile your application, you use the Cob -t flag to specify that the program is multi-threaded. You can then run the program using the trigger for the multi-threaded run-time system, cobrun_t, setting the +A run-time switch to start Animator:
cobrun_t +A program
or start Animator:
anim_t program
Each of the triggers cobrun, anim and cobanim have a corresponding multi-threaded version cobrun_t, anim_t and cobanim_t.
When Animator starts, you can use its View-threads function to view multiple threads. See the chapter Working With Animator for functions that you can use to debug multi-threaded applications.
You can use core file debugging, just-in-time debugging and unsolicited dynamic attachment with multi-threaded programs as described in the previous sections; the difference is that you use the _t suffix with any triggers.
You can use Animator with multi-threading programs in two ways:
If you start Animator with the MULTITHREAD directive specified, Animator runs in the non-threaded run-time system, but creates a multi-threading environment for the animated program. This means that Animator does not incur the processing overheads of a multi-threading run-time system, and Animator performance (speed) is therefore not degraded. However, as two different run-time systems (that is, one threaded, the other non-threaded) are loaded into system memory space, using the MULTITHREAD directive might result in a decrease in the overall performance of the operating system.
If you use the _t version of the commands that start Animator, both Animator and the animated program run in the multi-threaded run-time system. This can affect the speed at which Animator and the animated programs run because both use whatever system resources are necessary to maintain thread state information. However, using _t commands has the advantage over the MULTITHREAD directive that the operating system can share the code spaces of the two executing run-time system shared libraries, so memory use might not be adversely affected.
No hard and fast rules can be given as to whether you should use the _t commands, or the MULTITHREAD directive. Generally, if speed is an issue, use Animator with the MULTITHREAD directive; if memory use is an issue, use the _t commands.
For information on Animator directives, see the chapter Directives for Animator
You can use Animator to debug CGI programs using any of the following:
For more information on debugging CGI programs, see the chapter Building and Debugging CGI Programs in your CGI-based Applications book.
Cross-session debugging enables you to use Animator in a different terminal window to that in which the program to be debugged is running. With cross-session debugging, Animator is started first in one session and left in a waiting state; it then attaches to a program started in another session, as long as certain conditions are met. These are:
You associate the Animator process and the program using one of the following methods:
You can specify a unique identifier using the COBANIMSRV environment variable to the processes for Animator and a program you want to debug. Animator will then only debug a program that has a matching identifier. For example, in one session enter:
export COBANIMSRV=myid
myid is now a unique identifier you can use to match Animator to a program. Enter the command to start Animator:
cobanimsrv
Animator waits for a COBOL program to start that has a matching identifier. In another session enter:
export COBANIMSRV=myid cobrun prog1.int
When prog1.int starts, the unique identifier myid matches that of Animator, so Animator attaches to this process. In the first session, the Animator main screen is displayed and the cursor placed on the first line of prog1.int.
If you start Animator in the same directory as that in which you run the program that is to be debugged, the program will attach to the waiting Animator process.
For example, in one session enter:
cd /home/user/program/debug cobanimsrv
Animator is now waiting for a program to start in the /home/user/program/debug directory. Therefore, if in another session you change to the same directory and start a program by entering:
cd /home/user/program/debug cobrun prog1.int
prog1.int attaches to the waiting Animator process; the Animator main screen is displayed and the cursor is placed on the first line of prog1.int.
With these routines you can switch debugging on and off as you wish and debug more than one program without having to stop and restart the Animator process. You start up Animator in one session, using the cobanimsrv command. In a second session you run a program that has a different COBANIMSRV environment variable value, or if it is not set, is running in a different directory. This program starts running as normal, not animated.
When a call to CBL_DEBUG_START is encountered with an identifier parameter that matches the value of the COBANIMSRV environment variable for the Animator process, or if the identifier parameter is unset, is running in the same directory, then Animator attaches to the program.
For example, in one session enter:
export COBANIMSRV=myid
myid is now a unique identifier you can use to match Animator to a program. Enter the command to start Animator:
cobanimsrv
Animator waits for a COBOL program to start that has a matching identifier. In another session enter:
cobrun prog1.int
The prog1.int program starts running without animation. A call to CBL_DEBUG_START is encountered:
call CBL_DEBUG_START using by value flags, timeout, by reference "myid", returning status-code
The unique identifier myid matches that of Animator, so Animator attaches to this process. In the first session, the Animator main screen is displayed and the cursor placed on the line of prog1.int containing the CBL_DEBUG_START call.
You can stop or suspend debugging by issuing a call to CBL_DEBUG_STOP.
CBL_DEBUG_START and CBL_DEBUG_STOP calls can also be used to switch remote and local animation on and off. The calls are documented in full in the Library Routines.
Note: To control cross-session animation using CBL_DEBUG_START and CBL_DEBUG_STOP, you must either:
If the COBANIMSRV environment variable values for the Animator process and the program match, Animator will start animating the program immediately, instead of when the first call to CBL_DEBUG_START is encountered.
You can use Net Express to debug programs on your UNIX system. This enables you to debug programs that you have developed on a UNIX system using Server Express, or published on a UNIX system using the Net Express UNIX Option. The remote debugging capability is provided in Net Express Version 3.0 and later. In remote debugging, the local machine is the Net Express PC, while the remote machine is the UNIX workstation. Of course, you could run both sessions on the same PC, using a Telnet window to conduct the UNIX session.
There are two ways you can do remote debugging:
To debug a program on your UNIX system using Net Express remote debugging, you need to start the debug server on your UNIX system using the animserv command. Versions of the animserv command are provided that enable you to debug non-threaded and threaded applications, on 32-bit and 64-bit systems. We recommend that you use:
The version of the debug server used does not affect the type of application that can be debugged. animserv32 or animserv64 can be used to debug a multi-threaded application, while animserv32_t or animserv64_t can be used to debug a non-threaded application, However, the threaded versions provide a better response time for asynchronous event handling such as acknowledgment of the Break button, and the setting of breakpoints while the application is executing.
You start the debug server using the command:
animservxx[_t] [auto] [port(nnnn)]
or:
animservxx[_t] [auto] [port=nnnn]
where the parameters are:
| _t | Requests the multi-threaded version of animserv |
| xx | 32 or 64. Specifies the version of the debug server for the 32-bit or 64-bit environments. |
| auto | Specifies that animserv should operate in advanced mode, providing animation of multiple programs running in sequence in one session. |
| nnnn | Specifies that port number nnnn should be used rather than a dynamically allocated port. You should only specify a port if other people are also using the remote workstation for remote debugging. The port number should be a unique number greater than 1024. If you do not specify a port number, a port number is allocated; this allocated number is displayed on your terminal. You will need to enter the port number when you initiate debugging in Net Express. See your Net Express online help for details. |
Note: If you use any of the variants of the animserv command with the AUTO option, you must not run it in background.
The sequence of events with standard remote debugging is as follows:
The sequence of events with advanced remote debugging is as follows:
You repeat steps 3 through 5 or 4 through 5, debugging a sequence of programs or parts of programs. When you want to stop, you issue a final CBL_DEBUG_STOP call with a flag that indicates that the Animator process should terminate. You must exit from Net Express at this point; if you leave it open and try to do some more debugging, the results are unpredictable.
At no point should you attempt to start or stop debugging using Net Express menu options; you must allow the UNIX Animator process to control the Net Express IDE.
To use advanced remote animation, you need to insert CBL_DEBUG_START and CBL_DEBUG_STOP calls in your code. These calls can also be used to switch cross-session and local animation on and off. The calls are documented in full in the Library Routines.
There are several methods that you can use to debug services and applications that run on an enterprise server. The most flexible of these, and the one that we recommend, is the use of the Enterprise Server Dynamic Debugging facility.
The Enterprise Server Dynamic Debugging option enables you to attach to, and debug, any application or service running on an enterprise server. It requires no changes to the code of your program. It does however require that you turn on Dynamic Debugging for your enterprise server, that the enterprise server is running on the same machine and under the same user ID as Server Express, that you compile for debug, and that you deploy the dictionary (.idy) files for your application.
Using the cobesdebug utility, you can tell an enterprise server configured for Dynamic Debugging that you want to debug any service or application instance that matches criteria that you supply. For example, you can specify that you want to debug instances of a given web service that are started from a particular client machine.
Each time an application or service is started the enterprise server checks to see if it matches the criteria that you supplied. If it does, the enterprise server attaches it to the debug session started by cobesdebug. You can then step through the application in the normal way.
Your match criteria can be specific or general. However, we recommend that you be as specific as possible to avoid conflicts with other users. If more than one user specifies details that match a particular service or application instance, the most specific match (that is, the session that provided the most specific information) will be attached to the instance.
Note: You can view the active dynamic debug sessions and the associated debug criteria on your enterprise server by using the Dyn-Dbg button in ESMAC. You can also use the screen to remove debug criteria that are no longer required. To access ESMAC, see To start ESMAC for a server.
USERA specifies Web Services started from a particular client IP address. USERB specifies Web Services started from the same client IP address, but also specifies the service name. When a matching web service is started, the enterprise server will attach USERB's debug session to the service.
When you specify the match criteria, you will be warned if they are similar to those provided by another user. If you specify identical match criteria to those provided by another user, you will receive an error message and the criteria will be rejected.
| Argument | Description | Usage | Applies to |
|---|---|---|---|
| type | Specify either CICS | JCL | WS | J2EE, depending on the type of application or service you want to debug. | Mandatory | All |
| tranid | Specify the CICS transaction id that you want to debug | Optional | CICS only |
| termid | Specify the CICS terminal id used to launch the
application. Note: For non-facility tasks (i.e. those which are not running on a terminal or printer) specify '....' for the value of the terminal ID. |
Optional | CICS only |
| userid | Specify the CICS user id used to start the application that you want to debug | Optional | CICS only |
| progid | Specify the program id of the program that you want to debug | Optional | CICS only |
| jobname | Specify the name of the job you want to debug. | Optional | JCL only |
| stepname | Specify the JCL step that you want to debug. | Optional | JCL only |
| jobnumber | Specify the number of a job in the help queue that you want to debug | Optional | JCL only |
| program | Specify the name of the JCL program that you want to debug | Optional | JCL only |
| ipaddress | Specify the IP address of the client that will be used to request the web service you want to debug. Enter the address in the form xxx.xxx.xxx.xxx | Optional | Web service only |
| servicename | Specify the fully qualified name of the service. This is formed by taking the name of the service and appending a hash(#) character, for Web Services, or a dot(.), for J2EE, followed by the name of the operation that you want to debug. For example, if the service name for the web service that you deployed is http://tempuri.org/wmapserv, and the operation to be debugged is Read, the fully qualified service name is http://tempuri.org/wmapserv#Read | Optional | Web service and J2EE |
| server | Specify the enterprise server region that you are using to run the services you want to debug | Mandatory | All |
For example:cobesdebug type=WS server=ESDEMO servicename=http://tempuri.org/wmapserv#Read
cobesdebug now passes the service details to the enterprise server region specified by the server parameter and starts the animator. The animator waits for the service to begin.
Each time a service is started, the enterprise server will check to see if it matches the details that you provided. If it does, the enterprise server attaches the character animator to the service.
Note:
You can use the following alternative methods for debugging services and applications running on an enterprise server. As with Enterprise Server Dynamic Debugging, Server Express and Enterprise Server must be running on the same machine.
To debug a service using CBL_DEBUGBREAK using the default enterprise server ESDEMO, follow these steps:
call "CBL_DEBUGBREAK"
cob -ia myprog.cbl
Remember to remove the line that calls CBL_DEBUGBREAK when you have finshed debugging the service.
As an alternative to inserting the call statement, you can compile the program with the Compiler directive INITCALL"CBL_DEBUGBREAK", before you deploy it.
To debug a service using the cassi command using the default enterprise server ESDEMO, follow these steps:
cassi -a -rESDEMO
cob -ia myprog.cbl
You must also either deploy the .cbl and .cpy files or set the COBCPY environment variable in ESDEMO's configuration to point to the location of the files. For more information about setting environment variables for enterprise servers see the section Environment Variables in the chapter Configuration in your Enterprise Server Configuration and Administration Guide.
Any service that runs in the debug service execution process is debugged, that is, the Server Express Animator starts up as soon as the service is entered.
A run-time system error message is returned on a program that is syntactically correct but which encounters problems during the actual running of the intermediate code. When animating a program, run-time errors are displayed on the bottom line of the screen. See your Error Messages for a complete description of possible run-time errors and their format.
You can direct the COBOL Compiler to look for copyfiles in a particular location if they are not found in the same directory as the main source file. You do this by setting the environment variable COBCPY. When you are using Animator, a copyfile is searched for in the path where it was found during compilation. If it is not found there, the directories specified by the COBCPY environment variable are searched.
To set the COBCPY environment variable enter:
COBCPY=/usr/group/sharedcopy:/usr/mydir/mcpy export COBCPY
You can direct Animator to look for its information (.idy) files in a particular location if they are not found in the same directory as the program being animated. To do this, you set the COBIDY environment variable. For example:
COBIDY=:/usr/myapp/idyfiles:/usr/common/idyfiles export COBIDY
Copyright © 2007 Micro Focus (IP) Ltd. All rights reserved.