| 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, for debugging. See your Server Express User Guide for complete details on compiling in your given environment.
Notes:
If a program writes directly to the screen, by-passing the Cobol screen handling syntax and routines, then you can only debug the program using cross-session debugging.
If you want to create an .int file for use with the Animator, use the command:
cob prog-name.cbl
By default, the COBOL system uses the -a cob flag to compile your source files ready for animation.
If you want to create an .gnt file for use with the Animator, use the command:
cob -ug prog-name.cbl
If you want to create a callable shared object file for use with the Animator, use the command:
cob -zg prog-name.cbl
If you want to create a system executable file for use with the Animator, use the command:
cob -xg prog-name.cbl
In all these cases, the source code is compiled to an executable format, and an Animator information file (with the extension .idy) is created. The Animator information file is usually referred to as the .idy file.
See the chapters:
Both chapters are in your Server Express User Guide.
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.
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.
Animator can be invoked in various ways:
This section describes how to invoke Animator, and how to set up applications to invoke the 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.
To invoke Animator, enter one of the following command lines.
anim [switchparams] program-name [directives]
or:
anim_t [switchparams] program-name [directives]
Use anim_t if your program is multi-threading. 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. |
cobanim [switchparams] [directives]
or:
cobanim_t [switchparams] [directives]
Use cobanim where you want to start Animator in a different window or process to the program. This is most useful for debugging using unsolicited dynamic attachment.
Use cobanim_t if your program is multi-threading.
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. |
cobanimsrv [directives]
or:
cobanimsrv_t [directives]
Use cobanimsrv where you want to start Animator in a different window or process to the program, and you want the Animator to sleep until a process attaches to it. This is most useful for cross-session debugging.
Use cobanimsrv_t if your program is multi-threading.
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 the 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 start the 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 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 the 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. If you have this routine in your program, then Animator starts debugging your program at this point in your program. This call is enables you to attach Animator at any point during COBOL code execution.
Enables a COBOL program to invoke Animator.
call "CBL_DEBUGBREAK"
None
You can use this call to invoke Animator. If the program is not being debugged when it calls CBL_DEBUGBREAK, it starts Animator and then comes to a halt, as if you had been debugging it already and then pressed the Stop button on the toolbar.
If the program was already being debugged when it called CBL_DEBUGBREAK, then debugging comes to a halt in that Animator, as if you had pressed the Stop button.
The routine returns a value in RETURN-CODE of 0 if the call was successful, or non-zero if it tried to invoke Animator but failed.
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 the appendix Micro Focus Environment Variables in your Server Express User Guide.
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 other-language program - running as a separate process.
After compiling both the COBOL and other-language program for compilation, 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 a 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 breakpoint on a
function called mF_cso_loaded(); this enables you to see when the
run-time 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 assume 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 the 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 View-threads 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 are loaded into system memory space (that is, one threaded, the other non-threaded), 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 the 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 the 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 the 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 the
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; therefore, Animator attaches to this process. In
console session 1, the Animator main screen is displayed and 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 NetExpress to debug program 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 NetExpress UNIX Option. The remote debugging capability is provided in NetExpress Version 3. See your NetExpress documentation for information on remote debugging.
To debug a program on your UNIX system using NetExpress 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, it is recommended that, assuming response time for asynchronous events is not important, that 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 NetExpress Animate Settings dialog. See your NetExpress 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 NetExpress Animate Settings dialog. See your NetExpress documentation for details.
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 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. During animation, 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
Animator can be directed 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 © 1999 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 | |