PreviousIntroduction Working With AnimatorNext

Chapter 2: Starting Animator

This chapter describes how to start Animator.

2.1 Preparing for Animation

Before you use Animator, you must compile your source code, including all called programs. See your Server Express 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 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, 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 Server Express User's Guide.

To create an .int file:
cob prog-name.cbl

By default, the COBOL system uses the -a cob flag to compile your source files ready for animation.

To create a .gnt file:
cob -ug prog-name.cbl
To create a callable shared object file:
cob -zg prog-name.cbl
To create a system executable file:
cob -xg prog-name.cbl

2.2 Starting Animator

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's Guide for details.

2.2.1 Starting Animator From the Command Line

You can start Animator from the command line:

2.2.1.1 Starting Animator at Your Terminal

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 Descriptions of Run-time Switches in your Server Express User's 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.

2.2.1.2 Starting Animator in a Different Window or Process

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 Descriptions of Run-time Switches in your Server Express User's 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.

2.2.1.3 Starting Animator In Sleep Mode

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.

2.2.1.4 Specifying Animator Directives

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 ( ).

2.2.2 Just-in-time Debugging

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's Guide.

2.2.3 Core File Debugging

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's 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

2.2.4 Unsolicited Dynamic Attachment Debugging

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

2.2.5 The CBL_DEBUGBREAK Routine

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.

2.2.6 Specifying Screen Size for Screen-swapping

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's Guide.

2.2.7 Screen Borders on aixterm

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

2.2.8 The .aif File and Animator

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's 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:

2.3 Debugging a Preprocessor

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.

2.4 Mixed-language Debugging

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.


2.4.1 Mixed-language Debugging of Callable Shared Objects

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.

2.5 Debugging Multi-threaded Programs

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.

2.5.1 Multi-threading and Animator

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

2.6 Debugging CGI Programs

You can use Animator to debug CGI programs using any of the following:

For more information on debugging CGI programs, see the section Debugging the Application in the chapter Building Internet Programs in your Internet Applications book.

2.7 Cross-session Debugging

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.

2.8 Remote Debugging

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:

All versions of the debug server provide the same level of functionality, although the threaded versions 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. 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, assuming that response time for asynchronous events is not important, we recommend you use animserv32 or animserv64 for non-threaded applications and animserv32_t or animserv64_t for multi-threaded applications, as this provides the most efficient use of system resources.

2.8.1 Using animserv32 and animserv64

You start the animserv32 and animserv64 debug server using the command:

animservxx [port(nnn)]

or:

animservxx [port=nnn]

where the parameters are:

xx 32 or 64. Specifies the version of the debug server for the 32-bit or 64-bit environments.
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.

2.8.2 Using animserv32_t and animserv64_t

You start the animserv32_t and animserv64_t debug server using the command:

animservxx_t [port(nnn)] [{multi|single}]

or:

animservxx_t [port=nnn] [{multi|single}]

where the parameters are:

xx 32 or 64. Specifies the version of the debug server for the 32-bit or 64-bit environments.
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 animserv32 or animserv64 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.

2.9 Debugging Shared Libraries on HP-UX

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.


2.10 Error Messages

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.

2.11 Copyfile and Information File Location

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.

PreviousIntroduction Working With AnimatorNext