| Introduction | Working With Animator | |
This chapter describes how to start Animator.
Before you use Animator, you must compile your source code,
including all called programs. See your Server
Express User Guide for complete details on compiling in your
given environment. You an syntax-check your programs using the COBOL
Editor. See the section Syntax-checking
and Animating in the chapter Editor of your Utilities
Handbook 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, by-passing the COBOL screen handling syntax and routines, you can only debug the program using. 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 Server Express User 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
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 Handbook 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. See the appendix Micro Focus Environment Variables in your Server Express User 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 chapter Run-time Switches in your Server Express User Guide 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 window or process to the program being debugged. This is most useful for debugging using unsolicited dynamic attachment. To run Animator in this way, use the cobanim command:
cobanim [switchparams] [directives]
or:
cobanim_t [switchparams] [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 chapter Run-time Switches in your Server Express User Guide for details on the switches available. |
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 of 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.
If you specify an Animator directive in a $SET statement or in a
DIRECTIVES file, |
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 chapter Run-time Configuration in your Server Express User Guide.
Core file debugging enables you to see what went wrong during the execution of a program. When an error occurs, the operating-system generates a core file. The core file is a snapshot of the process's memory when program execution failed.
To generate a core file 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 chapter Run-time Configuration in your Server Express User Guide.
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 file, 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 chapter 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 Micro Focus Environment Variables in your Server Express User 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 that Animator is to save and load .aif files by setting the COBAIF Animator directive. For information on the COBAIF Animator directive, see the chapter Directives for Animator.
You can specify the directory in which Animator searches for or creates the .aif file using the $COBAIF environment variable; see the appendix Micro Focus Environment Variables in your User Guide for details..aif files are only loaded or saved by Animator if Animator is started using the anim or anim_t command. A session information file is not loaded or saved if you:
If you need to debug a preprocessor you must start Animator using the CBL_DEBUGBREAK 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 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/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:
For more information on debugging CGI programs, see the section Debugging the Application in the chapter Building Internet Programs in your Internet Applications book.
Cross-session debugging enables you to use Animator on a different console to that on which the program to be debugged is running. Although this is similar to unsolicited dynamic attachment, cross-session debugging is different in that Animator is started first and left in a waiting state; it then attaches to the first COBOL program to start. Animator will attach to a running program if:
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 console session type:
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 console session you start a program in the same directory:
cobrun /home/user/program/debug/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.
You can also 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 console session:
export COBANIMSRV=myid
myid is now a unique identifier you can use to match
Animator to a program. Type the command to start Animator:
cobanimsrv
The Animator waits for a COBOL program to start that has a matching identifier. In another console session:
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 console
session 1, the Animator main screen is displayed and the cursor placed on
the first line of prog1.int.
The user id of the Animator process and the running program need to be the same, otherwise this method will not work.
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. See your Net Express documentation for information on 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. Two versions of the debug server are provided, enabling you to debug non-threaded and threaded applications. The debug server is started using the animserv command for non-threaded applications, or animserv_t for threaded applications. Both versions of the debug server provide the same level of functionality, although the threaded version provides a better response time for asynchronous event handling such as acknowledgment of the Break button, or the setting of breakpoints while the application is executing.
The version of the debug server used does not affect the type of application that can be debugged. animserv can be used to debug a multi-threaded application, while animserv_t can be used to debug a non-threaded application. However, assuming that response time for asynchronous events is not important, we recommend you use animserv for non-threaded applications and animserv_t for multi-threaded applications, as this provides the most efficient use of system resources.
You start the animserv debug server using the command:
animserv [port(nnn)]
or:
animserv [port=nnn]
where port(nnn) specifies that port number nnn
should be used rather than a dynamically allocated port. You should only
specify a port if other people are also using the remote machine 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 into the Net Express Animate Settings dialog box.
See your Net Express documentation for details.
You start the animserv_t debug server using the command:
animserv_t [port(nnn)] [{multi|single}]
or:
animserv_t [port=nnn] [{multi|single}]
where the parameters are:
port(nnn) |
Specifies that port number nnn
should be used rather than a dynamically allocated port. You should only
specify a port if other people are also using the remote machine 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. |
single |
Use the single-threaded run-time system; this is equivalent to using the animserv debug server. |
multi |
Use the multi-threaded run-time system. |
You will need to enter the port number into the Net Express Animate Settings dialog box. See your Net Express documentation for details.
HP-UX:
In order to debug shared libraries on HP-UX, the HP-UX dynamic linker
needs to be instructed to load any shared libraries into private memory
instead of shared memory. If the libraries are not loaded privately,
Animator cannot set any breakpoints within the shared library.
When you use Animator to debug shared libraries or a program containing shared libraries (that is, files that have an .sl file extgension), Animator dynamically modifies the start-up sequence of the program being debugged so that shared libraries are loaded privately.
However, if you attempt to dynamically debug an process that is already running (for example, by using unsolicited dynamic attachment as described in the section Unsolicited Dynamic Attachment Debugging), then, by default, shared libraries are not privately mapped and Animator cannot set any breakpoints in any shared libraries.
Note: This is a general HP-UX limitation which also affects dde and gdb.
To dynamically attach to a running process and debug any shared libraries it contains, you need to run the pxdb command on the executable before the process is started.
To enable debugging of executables that are or contain shared libraries:
/opt/langtools/bin/pxdb -s on executable
To disable debugging of executables that are or contain shared libraries:
/opt/langtools/bin/pxdb -s off executable
where executable is an executable program that is or contains an .sl file.
Warning: If you enable debugging of executables that are or contain shared libraries, then all shared libraries loaded by an executable are mapped privately for each instance for the executable. If the executable is invoked multiple times on a multi-user system, this can result in a greatly increased memory requirement.
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 © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Introduction | Working With Animator | |