Analyzer and GNT Analyzer

COBOL Source Information

Chapter 4: Animator

Animator is a powerful menu-driven tool for debugging your COBOL programs. It displays your source code and your application in windows on the screen, highlighting each line of the source as your program is executed. This process is referred to as animating.

16-bit:
In addition to Animator, the 16-bit COBOL system also provides a base Animator. Base Animator does not contain all of the Animator's enhanced functionality, such as windows. The base Animator has been supplied for users whose machines might not meet Animator's memory requirements, but who still require a simple but effective tool for debugging programs.

See your Release Notes if you are unsure whether base Animator has been supplied for your environment. The term Animator can be taken to mean both the Animator and base Animator unless one or the other is specifically referenced.

This chapter describes the complete set of functions in both the Animator and base Animator.

4.1 Overview

Animator uses windows to display information about your program during execution, along with the corresponding part of your source code. The base Animator does not provide windows functionality; it displays information about your program at the bottom of the screen. Both Animators provide functions to enable you to control the pace at which your program runs, interrupt execution to examine and change data items, alter the sequence of execution or enter COBOL statements for immediate execution before your program continues. These facilities enable you to debug your programs quickly and easily.

32-bit for Windows NT and OS/2 V2:
If you are using a 32-bit COBOL system for Windows NT or OS/2 V2 you can use Animator to debug .exe, .dll, .gnt and .int files. See the section Animating Generated Code later in this chapter for information on animating .exe, .dll, and .gnt files.

Windows and OS/2:
This COBOL system provides an additional tool you can use to debug your COBOL applications on Windows and OS/2 - Animator Version 2 (Animator V2). Animator V2 uses a graphical user interface to provide a fully integrated environment in which you can edit and debug your applications. If you are using a 32-bit COBOL system for Windows NT or OS/2 V2, you can also use Animator V2 to debug generated programs.

Windows and OS/2:
If you are using Windows or OS/2 we recommend that you use Animator V2 to debug your applications. For information on using Animator V2, see your Object COBOL User Guide.

Figure 4-1 summarizes the capabilities of Animator, Animator V2, and Xilerator to debug generated code on each environment supported by this COBOL system.

Table 4-1 : Generated Code Debugging Capability

16-bit:
If you are running under the 16-bit COBOL system, you can make use of Xilerator, which provides additional facilities for low-level debugging, including debugging C and at the Assembler level.

4.1.1 Executing the Program

A flexible set of execution functions enables you to execute the code at the speed to suit the problem you are examining. You can Zoom (execute at maximum speed) through code you do not want to see execute, manually Step through each statement or set a convenient automatic execution speed in a problem area.

Breakpoints can be set throughout the source code by marking each statement where you want a break to occur or by defining a condition that should give rise to a break. This lets you define exactly when to get manual control of your program when it is executing automatically.

A backtracking facility can show you the path that has been taken through your code to arrive at a specific point.

4.1.2 Querying, Monitoring and Changing Data Items

Debugging a program often involves monitoring various data values in order to detect unexpected results. As the values of the data change during program execution, the monitored items are highlighted as they are updated. You can view the various data items in a variety of shapes and sizes. For example, you can view a block of data organized in sets of seven characters as a group of seven characters in width.

A data item in a program can be queried and displayed in either text (ASCII) or hexadecimal format. The contents of the data item can be changed, and has an immediate effect in subsequent program execution. Test data items that you use during one Animator session can be saved for use in subsequent sessions.

Special watch windows enable you to see the before and after states of data values as each statement is executed. You can simply overtype the monitored data items if you want to manually set a new value in order to change the logic flow of your program. Watch windows are not available with base Animator.

4.1.3 Logic Testing

"Do" functions enable you to execute additional code without having to interrupt your testing session. These COBOL statements can be executed when you enter them, or they can be associated with a statement and executed with that statement. The latter are saved in a file so that they can be incorporated into your source code once you have decided they correct a problem.

"Reset" functions enable you to bypass code that you do not want to be executed.

4.1.4 Cooperative Animation

DOS and OS/2:
In addition to animating a program in the same session as Animator, you can animate a program in a different session on the same machine (on OS/2) or a program running on a separate machine.

4.1.5 The On-line Reference

You can access the On-line Help System directly from Animator. This enables instant access to the help in the On-line Reference and any other on-line help files supplied with this system.

To invoke the On-line Help System, press the hotkey Alt+1. The On-line Help System looks at the word under the cursor. If a text cursor exists, it looks at that. Otherwise, it looks at the mouse cursor. If no cursor exists, it starts up at the home topic of the On-line Reference.

If the cursor is on a word, that word is used as a topic-name. If it is on a space, the word immediately following it on the line is used. If there is none, the word immediately preceding it on the line is used. If the line is blank, the system displays the home topic.

Once you have entered the On-line Help System, you can use it as described in the chapter On-line Help System to look at any files that are available. To return to Animator, press Escape from the On-line Reference Main menu.

4.2 Operation

Before you can animate a program, you must first compile it for animation. When you have done so, you can invoke Animator.

The following subjects are explained in the sections below:

• Compiling your program for animation

• Invoking Animator

• Starting cooperative or cross-session animation (DOS and OS/2)

• Locating various files required by Animator

• The organization of Animator screens

• Accessing the Animator functions

4.2.1 Preparing for Animation

Before you use Animator, you must compile your source code, including all called programs, for animation. The following sections describe how you compile for animation on DOS, Windows, OS/2, and on UNIX. See your Object COBOL User Guide for complete details on compiling in your given environment.

Notes:

• You must compile your program for animation on the same environment on which it will be animated.

• 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. This facility is not available with base Animator.

• You can syntax-check your programs using the COBOL Editor. See the section Syntax-checking and Animating in the chapter Editor for information.

4.2.1.1 Preparing for Animation on the 16-bit COBOL System

16-bit:
The command line for compiling your program for animation on the 16-bit COBOL system is:

component prog-name anim;

where the parameters are:

Compiling for animation on the 16-bit COBOL system causes an information file (.idy) and an intermediate code (.int) code file to be created. You can animate .int code files directly.

Additional files are also created depending on the environment you are using. See your Object COBOL User Guide for more information on the files created when you compile.

4.2.1.2 Preparing for Animation on 32-bit COBOL Systems for Windows NT or OS/2 V2

32-bit for Windows NT and OS/2 V2:
The command line for compiling your program for animation on a 32-bit COBOL system for Windows NT or OS/2 V2 is:

component prog-name;

where the parameters are:

Compiling for animation on the 32-bit COBOL systems for Windows NT or OS/2 V2 causes information files (.idy and .gdy) and a code file to be created. The code file created depends on optional Compiler directives you specify:

• If you specify the GNT directive, the Compiler creates a generated (.gnt) code file. You can animate this directly if you have set the COBANIM_2 environment variable to ANIMATE.

• If you do not specify GNT, the Compiler creates an .int code file. You can animate this directly.

See your Object COBOL User Guide for information on the GNT directive, and the section Animating Generated Code later in this chapter for information on the COBANIM_2 environment variable.

32-bit for OS/2 V2:
If you are using the 32-bit COBOL system for OS/2 V2 and you want to use Animator to debug Presentation Manager COBOL programs, you must set the COBANIM_2 environment variable to ANIMGUI (not ANIMATE) before you invoke Animator. Do this using the following operating system command, which you can enter at the command line or include in your config.sys file:

set cobanim_2=animgui

When you animate a program after setting COBANIM_2 to ANIMGUI you cannot access any other applications you might have running on your system while Animator has the focus.

4.2.1.3 Preparing for Animation on UNIX

UNIX:
On UNIX, the command to compile your program for animation is:

cob prog-name

By default, the COBOL system uses the -a cob flag to compile your source files ready for animation. 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, you must set up the COBCPY, COBIDY and COBAIF environment variables. See the appendix Micro Focus Environment Variables in your Object COBOL 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.

4.2.2 Invoking Animator

To invoke Animator, enter the command line:

component [switchparams] program-name [directives]

where the parameters are:

Note: You can invoke Animator using the COBOL Editor. See the section Syntax-checking and Animating in the chapter Editor for information.

UNIX:
If you try to run Animator on UNIX using a run-time system built using the "-m sqfile" option, you receive undefined results.

4.2.3 Cooperative and Cross-session Animation (16-bit)

16-bit:
The following sections describe cooperative and cross-session animation, and apply only to the 16-bit COBOL system.

When you use Animator to test a program, the program is started and run (animated) under control of Animator. The program is normally animated in the same session as Animator, effectively as a subprogram of Animator. However, it can also be animated in a different session on Windows and OS/2, or even on a different machine. For this purpose, the program being animated is described as the user program and runs in the user session. If it is being animated on a different machine, this is the user machine. Animator always runs in the animator session on the animator machine.

Animating the user program in a different OS/2 session to Animator is referred to as cross-session animation. Only one cross-session animation can take place at a time on one machine.

Animating the user program on a different machine from Animator is referred to as cooperative animation. The two machines must be connected by a network.

F2=view on the Animator main menu would normally swap the screen to view the screen output your program is producing. However viewing the user screen is different under cross-session and cooperative animation. You cannot view the user screen on the animation machine during cooperative animation, so the F2=view function has no effect.

Under cross-session animation, the keystroke required to return to Animator after viewing the user screen is read from the user session. If you want to preserve any stored keystrokes in your application, use the HOLDVIEW"n" Animator directive when starting Animator. Then after you select the View function, the Animator screen returns automatically after n seconds.

You should be aware that there is a performance overhead when doing cooperative or cross-session animation, particularly when using OS/2 Presentation Manager. You might notice, even when zooming, that it can take some time before any results are seen on the screen.

Note: When animating in a different session or on a different machine, the number of breakpoints available is restricted to four and the Application View facility is disabled.

4.2.3.1 Starting Cooperative Animation

In cooperative animation, the user program is on a different machine than Animator. When starting cooperative animation, in addition to invoking Animator on the animator machine, you must start the cooperative program, Animuser, on the user machine. You use the command line:

animuser user-machine "netname"

Cooperative animation communicates by setting up netname; that is, a network-name. Animator and the cooperative program, Animuser, both use the same name. Each cooperative animation running at the same time on the same network must have a different network-name. The default is COOPANIM, but you can specify your own by using the USER-MACHINE directive to Animator and to Animuser. If you do not control the entire network, you should always specify a unique network-name.

The Animator machine must have access to the source files and the .idy files for your application, and the user machine must have access to the files needed to run the program. One way of doing this is to have both machines logged on to the same drive on a network server, so all the files associated with your application are together.

4.2.3.2 Starting Cross-session Animation

16-bit for OS/2:
If the user machine is running OS/2, you can cause the animated program to run in a session or window other than the one in which Animator is invoked by specifying the appropriate USER-SESSION directive when invoking Animator.

The user machine must be set up to run COBOL applications, and the files animuser.exe and the appropriate coblib file must be available to the current session:

4.2.4 Cross-session Animation (32-bit)

32-bit for Windows NT and OS/2 V2:
The following sections describe cross-session animation, and apply only to the 32-bit COBOL systems for Windows NT and OS/2 V2. It is cross-session animation that you use when animating generated code.

When you use Animator to test a program, the program is started and run (animated) under control of Animator. The program is normally animated in the same session as Animator, effectively as a subprogram of Animator. However, it can also be animated in a different session. For this purpose, the program being animated is described as the user program and runs in the user session. Animator always runs in the animator session on the animator machine.

Animating the user program in a different session from Animator is referred to as cross-session animation. Only one cross-session animation can take place at a time on one machine.

F2=view on the Animator main menu would normally swap the screen to view the screen output your program is producing. However viewing the user screen is different under cross-session animation - to view the session that is showing the user screen you must select that session from the Task List (on Windows NT) or the Window List (on OS/2 V2).

4.2.4.1 Starting Cross-session Animation

You can cause the animated program to run in a session or window other than the one in which Animator is invoked by setting the environment variable COBANIM_2 to ANIMATE. Enter the following command to set the COBANIM_2 environment variable to enable cross-session animation:

set cobanim_2=animate

OS/2:
If you are animating a native Presentation Manager program use the following command instead:

set cobanim_2=animgui

4.2.5 Cross-session and Intra-session Animation (UNIX)

UNIX:
The following sections describe the cross-session and intra-session animation facilities available with Advanced Animator on UNIX.

Cross-session animation enables you to view your application screen and the Animator screen at the same time. This is useful when developing and testing an interactive COBOL software system as it enables you to reference screen data while viewing the internal state of the COBOL application.

During the development and testing of a mixed language COBOL software system, it is often necessary to use both the Animator and another debugging tool oriented to the other language being used in the application. This involves looking at three distinct screens in the debugging process, which can easily lead to confusion. Additionally, this process is very prone to system level conflicts between the Animator and the other language debugger being used. Cross-session animation completely separates Animator from the animated process, thus allowing another language debugger to be used on the mixed language animated program, eliminating the possibility of system conflicts and reducing the possibility of confusion.

Intra-session animation enables you to completely separate the execution of the Animator and the animated program while using an interface with the same look and feel as the original Animator.

During the development of a sophisticated COBOL software system, it is possible that some of the tools used by this system will conflict with the use of the tools within the Animator. This is because Animator and the animated program execute in the same address space with the same run-time system. Both cross-session animation and intra-session animation eliminate all possibility of run-time system conflicts.

4.2.5.1 Starting Cross-session Animation

In order to run cross-session animation, you must have two login sessions active under the same userid on the same UNIX system. The program being animated is called the user program and runs in the user session. Animator runs in the Animator session .

To start cross-session animation, set the COBANIM_2 environment variable in the Animator session as follows:

COBANIM_2=ANIMATOR 
export COBANIM_2

Start Animator as you would normally:

anim [switchparams] program-name [directives]

Animator then initializes itself, locates the program to be animated, and displays the following message:

Waiting for cross-session animated program to start . . .

In the user session, set the COBANIM_2 environment variable as follows:

COBANIM_2=ANIMATED 
export COBANIM_2

Start your program as you would normally. The screen then clears and the application's source code is displayed in the Animator session.

If the application program starts executing without the Animator, it is due to one of the following reasons:

• No animatable .int code has been executed yet

• The program run is not the same as that specified on the Animator command line in the Animator session

• Another login of the user's ID on the same UNIX system is animating exactly the same program file.

4.2.5.2 Starting Intra-session Animation

Only one login session is required to run intra-session animation.

To start intra-session animation, set the COBANIM_2 environment variable as follows:

COBANIM_2=ANIMATE 
export COBANIM_2

Start Animator as you would normally:

anim [switchparams] program-name [directives]

Note that any switch parameters to your animated program must be set using the COBSW environment variable . This is because the switch parameters supplied on the anim command line are seen only by Animator while those supplied via COBSW are seen by both Animator and the animated program.

Animator then initializes itself, locates the program to be animated and displays the following message:

Waiting for intra-session animated program to start . . .

The program being animated then initializes itself and Animator displays its source view screen.

4.2.5.3 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 complete description of possible run-time errors and their format.

4.2.6 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. 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.

DOS, Windows and OS/2:
On DOS, Windows and OS/2, to set the COBCPY environment variable enter:

set cobcpy=e:\myapp\cpyfiles;d:\common\cpyfiles

UNIX:
On UNIX, 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:

DOS, Windows and OS/2:
On DOS, Windows and OS/2, to set the COBIDY environment variable enter:

set cobidy=e:\myapp\idyfiles;d:\common\idyfiles

UNIX:
On UNIX, to set the COBIDY environment variable enter:

COBIDY=:/usr/myapp/idyfiles:/usr/common/idyfiles
export COBIDY

4.2.7 Screen Description and Operation

The Animator screen appears after Animator has been invoked. Your program source code appears on this screen. The cursor is positioned under the first executable statement in the Procedure Division, and this statement is highlighted. The bottom of the screen displays the information line and the Animator Main menu.

The main menu for Animator is shown in Figure 4-1.

Figure 4-1: Main Menu - Animator

The main menu for the base Animator is shown in Figure 4-2.

Figure 4-2: Main Menu - Base Animator

The Animator Main menu contains functions that you select to control the way your program is executed. A full description of these functions is presented later in this chapter.

When you use an option that causes statements to be executed, the cursor and highlighting follow the execution path, so they are always on the statement to be executed next. At other times, the highlighting remains on the statement that is to be executed next, but you can move the cursor around the screen to access different places in the source. The statement to be executed next, or currently being executed, is always highlighted, and is known as the current statement.

4.2.7.1 The Information Line

The information line displays the name of your program. It also shows the current level (Level=01) of nested PERFORM statements in the program, and the speed at which you have selected to animate your program. The Ins, Caps, Num and Scroll indicators, which appear on the right side of the information line, are highlighted when Insert, Caps Lock, Num Lock, or Scroll Lock respectively are active.

4.2.7.2 Moving the Cursor and Text During Animation

You can use several keys to move the cursor through the displayed code. You can also change the portion of text displayed on the screen.

DOS, Windows and OS/2:
You can also use a mouse to move the cursor position. Simply move the mouse pointer to the required position and click the left mouse button. This mouse support is not available for UNIX or for base Animator.

The following table lists the name of the cursor control keys, their function and the keystrokes required to obtain them.

UNIX:
Some of these keys are symbolic key-names which might not be present on your keyboard. For details of the actual keystrokes for your environment, see the appendix UNIX Key Usage Chart in the UNIX version of this manual.

Warning: The Animator interrupt key is the Escape key on UNIX and Ctrl+Break on DOS, Windows and OS/2. Therefore, animating an Adis ACCEPT disables the interrupt for the duration of the ACCEPT as the Escape key is a valid keystroke in this context (for instance, to terminate the ACCEPT). This means that if your program spends a lot of execution time performing Adis ACCEPTs, you might experience difficulty interrupting the program if you are using the Animator Zoom function.

An example of this is the demonstration program Tictac, which spends most of its execution time requesting user input and very little time acting on that input.

You might want to set a breakpoint in your program after such an ACCEPT statement to ensure that your program can break out of Zoom mode and return to the Animator screen. Alternatively, you can use Ctrl+K to interrupt an Adis ACCEPT.

4.2.7.3 Entering Text on Menus

Several of the Animator menus require you to enter text. In all cases, on entry to the menu, the previous contents of the field are present. This can be cleared using F2=clear. This key acts as a delete-to-end-field, deleting all characters from the current cursor position to the end of the field. When entering or editing text, the keys <left-arrow>, <right-arrow>, Home, End and Backspace all operate as normal. Insert or overtype mode can also be selected using the Ins key.

Once you have completed a field, pressing the Enter key confirms your update. If you want to cancel the update, press the Escape key. Both keys cause exit to a higher level menu if appropriate.

Where a selection of fields is presented, the cursor keys can be used to move up and down the list, and the Enter key selects the item you want and places it in the input field if appropriate.

4.2.7.4 Using the Animator Windows

Animator places information in windows which you can manipulate. This facility is not available with the base Animator.

You view your COBOL source code as a backdrop to the windowing system displaying the monitored data items. You can fill the screen as required with the contents of data items. The system is capable of covering the entire source code area with data windows. Simple keystrokes enable the monitored items to be hidden, reappearing automatically whenever they change in value.

4.2.7.4.1 Viewing Data

You can view a maximum of 200 characters in COBOL format in one window. You can scroll through the contents of this window to view other parts of the data item. You use multiple windows to monitor the same data item so that more than 200 characters can be monitored at one time. You also have the option of displaying a maximum of 128 bytes of the monitored item in hexadecimal format.

Note: Numeric values are viewed as equivalent edited PICTURE strings.

The contents of data items that you can change appear in reverse video in the monitoring windows. Keyboard keys and special keystrokes enable efficient editing of the item's contents. See the section Key Functions for Updating Queried Data Items below.

4.2.7.4.2 Creating and Adjusting Windows

You can create and position windows in the following ways:

• change the number of characters displayed by defining a new shape and size for the window

• change the position of the window on the screen

• move the window almost entirely off the screen, leaving one character displayed for easy access to the window.

4.2.7.4.3 Key Functions for Updating Queried Data Items

The following keys and key combinations have special effects when updating the contents of data items.

UNIX:
Some of these keys are symbolic key names which might not be present on your keyboard. For details of the actual keystrokes for your environment, see the appendix UNIX Key Usage Chart in the UNIX version of this manual.

4.3 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 before pressing Enter to begin animation or in the cobol.dir file.

The format for specifying directives is given here. If you are running UNIX, see the appendix Directives for Animator in this book for details on the directives available. If you are running DOS, Windows or OS/2, see the chapter Directives for Animator in your Object COBOL User Guide.

DOS, Windows and OS/2:
On DOS, Windows and OS/2, use the following format for Animator directives:

[ / ] [no] keyword parameter

where the parameters are:

UNIX:
On UNIX, use the following format for Animator directives:

[no] keyword parameter

where the parameters are:

4.4 Menus

Animator menus are organized to provide rapid access to the most commonly used functions.

You can access help menus from any Animator menu by pressing F1=help. This calls the help screen for the option from which it is called.

The menus described in this section appear in alphabetical order according to their menu-name, which is displayed on the left-hand side of the information line.

4.4.1 Alter-window Menu

The Alter-window menu is accessed by pressing Alt+F10 from the Query Data-name menu in Animator. It is shown in Figure 4-3:

Figure 4-3: Alter-window Menu

It enables you to move and resize monitors using either the mouse or cursor keys.

Not available in base Animator.

4.4.2 Alternate Menu

Advanced Animator, which is supplied with add-on products, also provides an Alternate menu (see Figure 4-4) which gives access to the facilities of Analyzer and Structure Animator. See the documentation for your add-on product for details of these facilities.

Figure 4-4: Advanced Animator Alternate Menu

To access the Alternate menu, hold down the Alt key when viewing the Animator Main menu.

UNIX:
UNIX users should see the appendix UNIX Key Usage Chart in their version of this manual for details of the actual keystrokes required.

Not available with base Animator or Animator.

4.4.3 Animator Main Menu

The Animator Main menu is displayed when Animator is started (unless the ZOOM Animator directive has been set, in which case the program executes immediately).

The Main menu (shown earlier in this chapter in Figure 4-1 for Animator and in Figure 4-2 for the base Animator) provides access both to direct functions and to submenus. The direct functions enable you, with a single keystroke, to execute the program and to reposition the program text on your screen.

To select a submenu or a function, use the appropriate function key or highlighted key required.

4.4.4 Breakpoints Menu

The Breakpoints menu (see Figure 4-5) is accessed by pressing B on the Animator Main menu.

Figure 4-5: Breakpoints Menu

You can set breakpoints in your program to halt execution when you are using Go or Zoom mode (Break Zoom is not available in base Animator). They are useful for debugging programs quickly when you have some idea of where a problem lies.

This menu displays options that enable you to perform the following functions:

• Set a breakpoint at the statement at the current cursor location

• Set a breakpoint at the statement at the current cursor location and zoom execution. This breakpoint is then automatically unset.
  Not available with base Animator.

• Cancel either a single breakpoint at the current cursor location or all breakpoints throughout the program

• Set a conditional breakpoint

• Examine the set breakpoints

• Automatically execute a specified COBOL statement at a breakpoint

• Set the frequency with which a breakpoint is activated

When a breakpoint is reached, you see the message:

Breakpoint encountered

at the bottom of your screen.

You can set up to 100 breakpoints in each program.

Note: By default, whenever you check a program, Animator saves details of the breakpoints in an .aif file. This means that breakpoints you set are not lost when you recheck a program or exit Animator.

The location of a breakpoint is stored in an .aif file as an offset from the start of the relevant section or paragraph. As a result, when you insert or delete lines before a breakpoint in a section or paragraph, rechecking the program could cause the breakpoint to be set on a line other than the line on which you set it.

You can prevent breakpoints moving in this way by specifying the CHECK-CLEAR-BREAKS Animator directive. If you are running UNIX, see the appendix Directives for Animator in this book for details on the directives available. If you are running DOS, Windows or OS/2, see the chapter Directives for Animator in your Object COBOL User Guide.

4.4.5 Control Menu

Advanced Animator, which is supplied with add-on products, also provides a Control menu, which gives access to some additional facilities such as scrolling functions, which enable rapid movement of the program text, and a text string search function. See the documentation for your add-on product for details of these facilities.

To access the Control menu (see Figure 4-6), hold down the Ctrl key when viewing the Animator Main menu.

UNIX:
UNIX users should see the appendix UNIX Key Usage Chart in their version of this manual for details of the actual keystrokes required.

Figure 4-6: Advanced Animator Control Menu

DOS, Windows and OS/2:
The Application-view function, available ion DOS, Windows and OS/2, can be accessed from here; this provides information about other programs in your application. See the description of Application-view for more details.

Not available in base Animator or Animator.

4.4.6 Environment Menu

The Environment menu (see Figure 4-7) is accessed by pressing E on the Animator Main menu.

Figure 4-7: Environment Menu

The Environment menu provides functions which enable you to set parameters to control some general execution aspects of the program you are executing. These include:

• Specifying the name of a program at which to interrupt execution

• Setting a level below which PERFORMs and CALLs are executed as single steps (Threshold)

• Setting a conditional program break which causes execution in Go or Zoom mode to halt when the condition is encountered (Until).

Note: The functions Flash(step/zoom) and Mon-slide(on/off) are not available in base Animator and do not appear on the menu.

4.4.7 Go Menu

The Go menu (see Figure 4-8) is accessed by pressing G on the Animator Main menu.

Figure 4-8: Go Menu

The Go function automatically executes each statement in the program one by one, displaying the source code on the screen as it is executed. Go mode is an automatic Step mode; you do not have to press a key to execute each statement as you do in Step mode.

You can set the Go execution speed by pressing a key from 0 to 9, where 0 is the slowest. You can also set the speed of execution from the Animator Main menu by pressing a number from 0 to 9 before selecting the Go function. The current speed is shown on the information line. The default speed is 5.

4.4.8 Locate-declaration Menu

The Locate-declaration menu, shown in Figure 4-9, is accessed by pressing L on the Animator Main menu.

The Locate-declaration function finds the location in the source code where a data item, filename, or procedure is declared.

From the Locate-declaration menu you can locate an item either by using the cursor as a pointer or keying in the name of the item you want to locate. The cursor control keys can be used to position the cursor in the program text or monitor window. Data items and filenames can be located from either their monitor windows or name in the text. Procedure-names can be located from their names in the program text.

4.4.9 Perform-level Menu

The Perform-level menu, shown in Figure 4-10 is accessed by pressing P on the Animator Main menu.

Figure 4-10: Perform-Level Menu

The Perform-level function enables you to Zoom through performed paragraphs, in-line PERFORM statements and called subprograms. This is useful if you are looking for a bug and are sure it isn't in a particular PERFORM range or subprogram.

The perform functions enable you to Zoom through the code specified by a PERFORM or CALL statement, or the code that completes such a statement if you have already begun to execute it.

You can animate programs with up to a maximum of 254 levels of PERFORM nesting. If your program exceeds this level, Animator will only Step, even if you specify Zoom mode.

4.4.10 Query Menu

The Query menu is accessed by pressing Q on the Animator Main menu. This menu as it appears in Animator is shown in Figure 4-11 and in the base Animator in Figure 4-12.

Figure 4-11: Query Menu - Animator

Figure 4-12: Query Menu - Base Animator

The Query menu functions enable you to look at and change the contents of data items. From this menu and its submenus, you can query data items, create a file containing a list of data values, and monitor data items.

Following a successful query, the Query Data-name menu appears on the screen with the queried data-name on the information line and the value of the data item in a window or at the bottom of the screen.

If you are using Animator, you should be aware that recompiling a program causes the monitor to be lost. If you leave Animator without unsetting the monitor, the monitor is set the next time you animate the program, unless you have recompiled it.

Warning: When animating an .exe, .dlw or .dll program that contains a PROCEDURE DIVISION USING statement with a USING item that has not been passed from another program, if you try to query the item, a protection violation occurs under Windows or OS/2, and memory can be corrupted under DOS. To prevent this, compile the program for animation with the PARAMCOUNTCHECK Compiler directive.

This does not apply to the UNIX operating system.

4.4.10.1 Query Data-name Menu

The Query Data-name menu, shown in Figure 4-13, appears after you have selected the item to be queried. The data-name appears on the information line; the value of the data item appears in a window (for Animator) or at the bottom of the screen (base Animator).

Figure 4-13: Query Data-name Menu

This menu provides functions which enable you to display the contents of the queried data item; if the data item exceeds 200 bytes on Animator or 80 bytes on base Animator, only the first 200 bytes and 80 bytes are displayed for Animator and base Animator respectively. From this menu, you can also view the data item in both hexadecimal and text (ASCII) format together and clear or alter the contents of the data item.

The Query Data-name menu is actually a set of two menus: an ASCII (text) menu and a Hex menu. You switch between them using a toggle key.

The ASCII menu is the menu which first appears after selecting the data item to be queried. Selecting the Hex function invokes the Hex menu. On this menu, the Hex function is replaced by a Text function which switches back to the Text menu.

On the Hex menu, the content of the queried data item appears on the left of the display area in hexadecimal form. The corresponding ASCII representation appears on the right.

There are Alternate and Control menus available from the Query Data-name menu. The Alternate menu enables you to create and save lists of test data, and set up and change a list of values for the queried data item to be used for successive runs of the program. You can also define a list for one or more data items in the program; change the size and shape of the queried data item or change its position on the screen.and to monitor queried data items

4.4.11 Reset-execution Menu

The Reset-execution menu, shown in Figure 4-14 is accessed by pressing R on the Animator Main menu.

Figure 4-14: Reset Execution Menu

The Reset function enables you to alter the sequence of program execution by changing the current statement, which is the statement that is to be executed next. You can simply skip one statement, reset to the current cursor position, reset at the next (higher) Perform level, or reset at the start of the program. Reset does not change the values of any data.

4.4.12 Text Menu

The Text menu, shown in Figure 4-15, is accessed by pressing T on the Animator Main menu.

Figure 4-15: Text Menu

The Text function enables you to split, join, and redisplay the screen.

4.5 Functions

Animator functions are accessed from menus. The function-names are sometimes abbreviated on the menus; however, the descriptions in the following sections use the full names.

The following section contains a quick reference listing all of the functions available in Animator. This listing is followed by detailed descriptions of these functions.

4.5.1 Function Access

The following table lists the functions in alphabetical order and indicates the keys you must press to access them. Thus, to determine the path to access a given function, follow the sequence of keystrokes. For example, to reach the Set Breakpoint function, from the Animator Main menu, you press the Breakpoints key (B) followed by the Set Breakpoint key (S).

UNIX:
Some of these keys are symbolic key-names which might not be present on your keyboard. For details of the actual keystrokes for your environment, see the appendix UNIX Key Usage Chart in the UNIX version of this manual.

For the purposes of this table, it is assumed that you are using the cursor to identify data-names rather than keying them in; therefore, a C on the menu access path indicates the selection of a data- name using the cursor. If, however, you are not using cursor, simply substitute Enter and the name of your data item for the key C to identify fields.

4.5.2 Function Descriptions

This section describes the functions available with Animator. Any not available in base Animator are marked accordingly.

Note: Mouse support is not provided for UNIX or for the base Animator. UNIX and base Animator users should ignore any references in the following sections to using a mouse.

-9

Enable you to vary the speed at which execution progresses in Go mode, where 0 is the slowest and 9 is the fastest.

Add List

Adds the value you have keyed in to the end of the list of values for the queried data item.

Align

Repositions the program text so that the line on which the cursor is currently positioned becomes the third line on the display screen.

Alter Monitor Window

Displays the Alter-window menu which enables you to change the size and position of the data monitor. For a description of the functions on this menu, see Move-window, Window-size-left/right/up/down and Redraw. You can use the mouse to access your windows for these functions.

Not available in base Animator.

Alter Path

Searches for a file on a different path from the one you originally specified. You can enter any valid path specification, but you must terminate it with a directory separator (backslash (\) on DOS, Windows and OS/2 or slash ( /) on UNIX).

This function is offered as appropriate. There is no explicit access.

Alternate

Displays the main Alternate menu for Advanced Animator (available with add-on products), which is described in the section Menus. For a description of the functions on this menu, see the documentation provided with your add-on product.

Not available in Animator or base Animator.

Animate

Displays the contents of all variables for the current statement as monitors, in effect combining the features of Watch windows with Go. The statement is then executed, and the contents of the monitors updated. These monitors are then removed. This process continues for successive statements until the end of the program is reached or you press Escape. A menu is displayed enabling the speed of execution to be changed and enabling Zoom mode to be entered.

Not available in base Animator.

Application-view

16-bit:
On the 16-bit COBOL system, Application-view enables you to view programs in your application while animating the current program using Advanced Animator (available with an add-on product). When the function is selected, a window appears which displays a list of available programs. For a program to appear on the list, it must already have been called by the application. Only .int programs that were compiled for Animation are listed.

You can select a program from this list by positioning the cursor on the program-name, and pressing Enter. When a program is selected, it is displayed in the normal way by Animator. If the program is not the current program (that is, the program that has the execution point in it), all functions that cause execution are disabled. All other Animator functions are enabled, giving you the opportunity to perform queries and set breakpoints. To continue with the Animator session, select the current program from the program list.

Breakpoints

This function displays the Breakpoints menu which is described in the section Menus. For a description of the functions on this menu, see Cancel All Breakpoints, Do At Breakpoint, Examine Breakpoint, If Breakpoint, On Count Breakpoint, Set Breakpoint, and Un-set Breakpoint.

Cancel All Breakpoints

Resets all active breakpoints.

Cancel Program Break

Cancels the currently set program break; that is, a breakpoint that is activated when execution reaches the specified program. See also Select Program Break.

Clear

Clears the current input field.

Contained Data

Displays the contents of the first sub-level of the item that is being queried. This query function is active when a group item is being queried.

Containing Data

Displays the contents of the data item in which the selected item occurs. This query function is active when a member of a group item is being queried.

Control

Displays the main Control menu for Advanced Animator (available with add-on products), which is described in the section Menus. For a description of the functions on this menu, see Application-view, Scroll Up/Down (1 line) and Scroll Up/Down (continuously).

Not available in Animator or base Animator.

Cursor-name Locate

Finds the location in the source code where a data item, filename or procedure is declared.

You can use the cursor control keys or the mouse to position the cursor in the program text; you can use the cursor control keys to position the cursor in a structure diagram, or monitor window. Data items and filenames can be located either from their monitor windows or name in the text. Procedure-names can be located from their names in the program text.

Cursor-name Query

Displays the contents of the data item at either the current cursor position or the position of the mouse pointer (use a double-click to activate this function). It gives you access to other functions which enable you to modify and monitor the item. To alter the contents of the queried data simply type in a new value. The new value replaces the item's previous value. If the data item is a dynamic stream, you can update it by using the Do function.

You can place the cursor, or select with the mouse, anywhere in the data item or in the data item window. If you do not select the name of a data item, the message:

Not data item

appears at the bottom of the screen.

Following a successful query, the Query Data-name menu appears on the screen with the queried data-name on the information line and the value of the data item at the bottom of the screen.

Cursor-position Reset

Enables you to alter the sequence of program execution. The statement at the cursor position becomes the current statement. Execution continues from this statement. This function does not change the value of any data.

Delete List

Deletes the current value displayed from the list of values for the data item being queried.

Do

Enables you to enter a COBOL statement to be executed immediately. This command enables you to insert a statement in the sequence of execution but does not add it to your program code. To add it, you must key it in using a text editor then recompile your source code file. Alternatively, you can enter it as a Do At Breakpoint, in which case it is saved in a file.

The COBOL statement cannot exceed 71 characters.

Entering an invalid COBOL statement gives an error message.

Note: Although most COBOL statements are supported by the Do command, Animator cannot handle some complex statements. An appropriate error message is issued in these cases.

Do At Breakpoint

Prompts you for a valid COBOL statement which is to be executed along with the current line. Execution is not interrupted. The line containing the breakpoint is highlighted (highlighting is not available in base Animator).

When Animator encounters a breakpoint set with the Do option, the COBOL statement is executed immediately before the statement containing the breakpoint. In Zoom or Go mode, execution continues without a break. In Step mode, the Do-statement is executed when the statement containing the breakpoint is stepped onto. A message indicating that the statement has been executed appears at the bottom of the screen. You can repeatedly execute the COBOL statement without retyping it.

Entering an invalid COBOL statement gives an error message.

On exit from Animator, all the COBOL statements that are currently set using this function are written to a file called progname.edo, where progname is the name of your main program, in the same directory as the source of that program . You can then paste the contents of the .edo file into the program source file. You can do this using the F4=load-DO-statement-file option on the COBOL Editor's Command File menu.

Note: Although most COBOL statements are supported by the Do command, Animator cannot handle some complex statements. An appropriate error message is issued in these cases.

Down List

Displays the next item in the list of values for the data item being queried.

Down Perform Level

Cancels the result of Up Perform Level, which enables the current execution path to be examined at the PERFORM level. This function is not available in base Animator.

Down-table

Displays the contents of the next table entry. The display of the variable used as the table subscript (shown with the data-name) reflects the current value and is changed by this function. This query function is only active when a table data item is being queried.

Dump List

Saves test data that you have created using the Query List functions. The list is written to disk in the current directory using the program- name plus an .ils extension. If the specified filename already exists, the file is overwritten with the new values. This list is loaded when you re-enter Animator and execute the program for which you have created the list. The file must be in the current directory.

Enter

Confirms any selections you have made or data you have keyed in. It might return you to a higher level menu. Where both Escape and Enter options are available, Escape exits without making the update you have keyed in, whereas Enter makes the update and then exits.

Enter-name Locate

Displays a menu where you can type in the name of the item to be located in the source code.

Moves the cursor to one of the following locations:

• The line in which the data item is declared

• The first occurrence of the filename in your program

• The paragraph or section-name at the head of a procedure

depending upon what you enter at the prompt. If you are working with nested programs, you must be positioned in the program in which that data item is defined for this function to work successfully.

Enter-name Query

Prompts you for a data item name, which can be entered in upper or lower case. Following a successful query, the Query Data-name menu appears on the screen with the queried data-name on the information line and the value of the data item in a window or at the bottom of the screen. To alter the contents of the queried data, simply type in a new value. The new value replaces the item's previous value.

If you are working with nested programs, you must be positioned in the program in which that data item is defined for this function to work successfully.

Environment

Displays the Environment menu which is described in the section Menus. For a description of the functions on this menu see This Program Break, Select Program Break, Cancel Program Break, Set Threshold Level,Un-set Threshold Level, Set Until Condition, Un-set Until Condition,Examine Until Condition, Set Backtrack, Un-set Backtrack,Examine Backtrack, Flash, and Monitor-slide.

Escape

Returns to the higher level menu or exits from Animator altogether if you are at the top menu. Where both Escape and Enter are available options, Escape exits without making the update you have keyed in, whereas Enter makes the update and then exits.

Examine Backtrack

Enables you to traverse the recorded execution path. The Set Backtrack function must have been used before the execution of at least one line of source code in order for this function to operate.

You use the <up-arrow> key to backtrack through the execution path starting from the current statement. At any stage you can move forward through the execution path by using the <down-arrow> key.

Note: Execution does not occur during backtracking; backtracking is purely a viewing facility. During backtracking, statements are stepped in accordance with the current Threshold Level. See Set Threshold Level.

Examine Breakpoints

Enables you to review your breakpoints. Each time you execute this function, the cursor is placed on the COBOL statement that has the next breakpoint set on it. After displaying the last breakpoint, the function displays the first breakpoint.

In addition, if the Breakpoint menu is active, whenever the cursor is positioned on a statement containing a breakpoint, a message appears on the bottom line of the screen.

Examine Until Condition

This function enables you to see the contents of the current Until Condition. See Set Until Condition.

Exchange

Toggles to move the cursor, and therefore the display of execution, between screens in split-screen mode. You can split the screen in two using the Split Text function.

Exit Perform

Executes the remainder of outstanding code in the PERFORM range which includes the current statement. Execution stops on the statement following the end of the PERFORM range.

This function operates only if the current statement is in a PERFORM range. If you select this function when you are not in the range of a PERFORM (PERFORM LEVEL = 01) and you are currently in a subprogram, you are asked if you want to leave the program. If you reply "Yes", the program execution continues in Zoom mode until the calling program is reached. If you are not in a subprogram, you are reminded that the PERFORM LEVEL = 01 by an error message.

Find String

Finds the next occurrence of a text string in the source program file. You can find a text string in both the main program and copyfiles or in just the main program. By default, the Find function searches all files in the program. Once the find is completed, the cursor is positioned at the beginning of the text string located.

The string can be up to 32 characters long and must be entered exactly as written in the source code, using upper- and lower-case letters as appropriate.

If you want to include spaces at the end of the string, enter the spaces and terminate them with a hash mark (#). If you want to find a string in the main program only, enter the string, terminated by a # and an M. The M tells Animator to search just the main file.

If you have previously used the Find function during the current session, the last specified string appears in the prompt field. You can use the Clear function to clear the string or Enter to search for the same string again.

The Find function searches forward only from the current cursor position. You cannot find a string that you have already passed.

Flash

Enables you to toggle between Step and Zoom mode to change the conditions which cause Animator to display the user screen.

Not available in base Animator.

When you alter this setting, Animator confirms the change which affects only the current program.

Flash (step) is of particular use if your COBOL program calls a subprogram which is written in another language (for example, Assembler) which could otherwise produce output on the Animator screen.

The default setting Flash (zoom) is created at compilation time and can be altered using the FLASH Animator directive at compilation time.

Go

Executes automatically each statement in the program one by one, displaying the source code on the screen as it is executed. Go mode is an automatic Step mode; you do not have to press a key to execute each statement as you do in Step mode.

You can set the Go execution speed by pressing a key in the range 0 to 9, where 0 is the slowest. You can also set the speed of execution from the Animator Main menu by pressing a number in the range 0 to 9 without selecting the Go function. The current speed is shown on the information line. The default speed is 5.

To stop execution in Go mode and return to the Animator Main menu, press Escape.

To change to Zoom mode from Go mode, press Z. The program then executes at full speed without animation. You can break out of Zoom mode by pressing the Break key combination.

Hex

Toggles to change the display of a queried data item to hexadecimal format and to change the menu displayed. You can type over the data using either text or hexadecimal code.

Hex/ASCII

Toggles to move the cursor between the hex and ASCII data representations. It is available when you are displaying a queried data item in hex format. You can type over the data using either text or hexadecimal code.

Hide Monitors

Hides all monitors. They only reappear on the screen if their value changes or if a Refresh function is performed.

Not available in base Animator.

If Breakpoint

Enables you to set a conditional breakpoint. A conditional breakpoint is a breakpoint that takes effect only if the specified condition is true when the breakpoint is reached. The line containing the breakpoint is highlighted (highlighting is not available in base Animator).

The submenu prompts you to enter a condition in COBOL format. Once you have entered a valid statement, pressing the Enter key sets a conditional breakpoint at the current cursor position. Execution stops at this breakpoint only when the condition is true.

If the condition you specify is false or does not become true, Animator ignores the breakpoint and continues executing the program. You can enter any condition enabled by COBOL syntax, including combinations of conditions. You cannot set a conditional breakpoint on a statement that already has an ordinary breakpoint, and vice versa.

If you want to set a conditional breakpoint that is not tied to a particular statement, you should use the Until function.

Insert List Left

Inserts a new data value entered into the input field into the list immediately before the currently displayed list value. This function is one of the Query Data list functions.

Insert List Right

Inserts a new data value entered into the input field into the list immediately after the currently displayed list value. This function is one of the Query Data list functions.

Join Text

Cancels the effect of the Split Text function and returns you to a single screen display of source code. You can use the Refresh Text function to repaint the screen after using the Join Text function.

Locate-declaration

Displays the Locate-declaration menu if accessed from the Animator Main menu. For a description of the functions on this menu see Cursor-name Locate, Enter-name Locate, Up Perform Level and Down Perform Level.

Note: The Up Perform Level and Down Perform Level functions are not available in base Animator.

Alternatively, if accessed from the Query Alternate menu, the Locate-declaration function finds the location in the source code of the current query item.

Look-up

Repositions the program text so that the line number specified at the prompt becomes the third line on the screen. This provides a quick and easy means of locating a line in your code without having to scroll through it line by line.

Monitor

Enables you to display the content of a queried data item as it changes during program execution.

See also Monitor-off, Hide Monitors and Alter Monitor Window.

Monitor+Break+Change

Monitors the queried data item and performs a breakpoint when the data item changes. Only one of these is enabled at a time.

Not available in base Animator.

Monitor+Fixed

Causes the monitor to operate on the subscript that was current when the function was selected rather than to follow the subscript. By default, Animator monitors the queried data item and the subscript of the data item. As the subscript changes, the monitor is adjusted to display the relevant data element.

Monitor-off

Switches off the monitor display of a queried data item. See also Hide Monitors.

Monitor-slide

Toggles to enable you to change the way the monitor windows move on the screen. With this toggle set to on (the default) the monitor window appears at the current cursor position and slides to its final position, towards the right-hand side of the screen. With this toggle set to off, the monitor positions itself immediately in the final position, towards the right-hand side of the screen.

Not available in base Animator.

Move-window

Defines a new window position. You can either use the cursor keys to move the window in the appropriate direction, or you can click the mouse on the top border of the window containing the data-name and drag the window to a new position.

Not available in base Animator.

Next Reset

Causes the next statement to become the current statement without executing any code. This function does not change the value of any data.

Next-if

Zooms through all statements until the next IF statement is encountered. Program execution then stops, and the source code is returned to the screen.

Nx-If

An abbreviation of the Next-if function. See Next-if.

On Count Breakpoint

Enables you to set periodic breakpoints that halt execution immediately before the specified statement has been executed the specified number of times. For example, if you specify a frequency of 3, set the breakpoint and then Zoom, execution breaks the third time that the breakpoint is encountered, and every third time subsequently. The line containing the breakpoint is highlighted (highlighting is not available in base Animator).

The frequency must be in the range 2 to 255 inclusive. Once the frequency has been entered, the normal Breakpoint menu appears, enabling you to set the breakpoint or to specify a breakpoint with the Do function. The number selected for the desired frequency appears on the information line.

Organize Monitors

Reorganizes the monitors on your screen to their default positions.

Not available in base Animator.

Perform-level

Displays the Perform-level menu which is described in the section Menus. For a description of the functions on this menu see Step Perform and Exit Perform.

Query

Displays the Query menu, which is described in the section Menus. For a description of the functions on this menu, see Cursor-name Query, Enter-name Query, Repeat Query, Monitor-off, Dump-list, Hide Monitors, Organize Monitors and Watch-off.

Query Data-name

Displays the Query Data-name menu, which is described in the section Menus. For a description of the functions on this menu, see Contained Data, Containing Data, Down-table, Hex, Hex/ASCII, Monitor Same Level and Up-table.

Query Data-name Alternate

Displays the Query Data-name Alternate menu, which is described in the section Menus. For a description of the functions on this menu, see Add List, Delete List, Down List, Insert List Left, Insert List Right, Locate-declaration, Redraw, Up List and Update List.

Query Data-name Control

Displays the Query Data-name Control menu, which is described in the section Menus. For a description of the functions on this menu, see Monitor+Break+Change and Monitor+Fixed.

Quit-perform

Exits from the current PERFORM range without executing the remaining statements. The next executable statement after the PERFORM statement becomes the current statement. You can select this function only when inside the range of a PERFORM.

This function does not change the value of any data.

Redraw

Redraws the monitor, using the cursor position as the new corner, after you have defined a new corner for your monitor using the Window-size-left/right/up/down function.

Not available in base Animator.

Refresh

Refreshes the display of all source text and the monitor.

Repeat Query

Displays the content of the item which was last queried and displays the Query Data-name submenu.

Reset-execution

Displays the Reset-execution menu which is described in the section Menus. For a description of the functions on this menu, see Start, Next, Quit-perform and Cursor-position Reset.

Same Level

Displays the content of the next data item that has the same level as the queried data item. The data-name appears on the information line.

Scroll Up/Down (continuously)

Scrolls the text rapidly toward the beginning (Up) or end (Down) of the file. Press any key to stop scrolling in either direction.

Scroll Up/Down (one line)(Ctrl+<left-arrow>/<right-arrow>)

Enables you to scroll up or down, line by line, by using the <left-arrow> or the <right-arrow> key respectively.

Select Program Break

Prompts you for the name of the program at which you want execution to halt; that is, a program break. A program break is a breakpoint that is activated when execution reaches the specified program.

Set Backtrack

Causes the execution path to be recorded from the set point onwards. See the Examine Backtrack function for details of how to view the recorded details.

Set Breakpoint

Enables you to set a breakpoint at the current cursor position. When Animator encounters the breakpoint, execution halts before executing the statement. The statement containing the breakpoint becomes the current statement. The line containing the breakpoint is highlighted (not available in base Animator).

Program breakpoints remain set, so if you leave animation without un-setting (canceling) a breakpoint, the breakpoint is set the next time you animate the program. You can set up to 100 breakpoints in each program.

When a breakpoint is reached, you see the message:

Breakpoint encountered

at the bottom of your screen.

Set Threshold Level

Enables you to specify a nesting level of subroutines and called subprograms below which PERFORMs and CALLs are executed in Zoom mode rather than being animated.

The level is set according to the level of the current line. The set level then appears on the information line and can be un-set by using the Un-set Threshold Level function.

Set Until Condition

Enables you to set a conditional program breakpoint that causes execution to halt when the condition becomes true.

This function is similar to a conditional breakpoint except that it is not tied to a particular COBOL statement but to the entire program. With a conditional program breakpoint, the Animator tests the condition before executing each statement and halts if it is true.

The condition must conform to the syntax rules for COBOL conditions.

You can set only one Until breakpoint in a program.

Split Text

Enables you to split a screen horizontally in two at the current cursor position. You must have a minimum of four lines in a split screen.

When you have split the screen, you can execute in either half. The Exchange function moves the cursor between the halves.

Split-screen mode is particularly useful if you want to query data declarations or a set of variables in one screen while executing in the other.

Start

Makes the first executable statement in the program the current statement. No code is executed.

This function does not change the value of any data, so if you use this function to test your program as though you had not executed any code, make sure you reinitialize all of your variables before continuing.

Step

Executes the current statement and places the cursor on the next executable statement, which it also highlights.

Step Perform

Causes execution of the entire PERFORM range or subprogram in Zoom mode if the current statement is a PERFORM or CALL statement. Execution stops on the statement following the end of the PERFORM range or subprogram.

Text

Changes the display of a queried data item to text format and changes the menu displayed if accessed from the Query Data-name menu. You can type over the data using either text or hexadecimal code.

Alternatively, if accessed from the Animator Main menu, this function displays the Text menu which is described in the section Menus. For a description of the functions on this menu see Split Text, Join Text, Refresh and Edit Text.

This Program Break

Sets a program break; that is, a breakpoint that occurs when the selected program is re-entered. For example, if This Program Break specifies a program break for the current program, a breakpoint occurs when the program is re-entered after a subprogram call.

Un-set Backtrack

Stops the recording of the execution path.

Un-set Breakpoint

Cancels a breakpoint at the current cursor position.

Un-set Threshold Level

Cancels the current Threshold Level. See Set Threshold Level.

If no level is set, the information line displays the message:

Threshold-level = un-set

Un-set Until Condition

Cancels the Until Condition if one is active. See the Set Until Condition function.

Up List

Displays the previous item in the list of values for the queried data item.

Up Perform Level

Enables the current execution path to be examined at the PERFORM level. This shows where execution returns when the current PERFORM range is exited. This function is not available in base Animator.

The related function, Down Perform Level, cancels the result of Up Perform Level.

Up Table

Displays the contents of the previous table entry. The display of the variable used as the table subscript (shown with the data-name) reflects the current value and is changed by this function. This query function is active only when a table data item is being queried.

If you select an entry that is before the first table entry, a warning beep is sounded.

Update List

Changes the value of the displayed item in a list of Query data to a new value which you key in.

View

Enables you to view the user screen during animation. The screen changes whenever you execute a statement that echoes a character to the screen. Press any key to return to the source code, unless you are using cross-session animation and you have specified the HOLDVIEW"n" directive, in which case the Animator screen returns automatically after n seconds.

View has no effect if you are using cooperative animation.

Watch Monitors

Causes the contents of all variables on the current line to be displayed as monitors in the bottom right-hand part of the screen. Using the Watch command a second time causes a single step (see the Step function), updating the contents of the monitors. Using the Watch command a third time removes the Watch monitors created for the previous statement and creates a new set for the current line.

Thus, this function enables you to examine the before and after states of variables for any given statement with the minimum of keystrokes.

Watch monitors are treated differently than normal monitors: they overlay any normal monitors in the bottom right-hand portion of the screen. The Organize Monitors function makes the watch windows revert to normal monitor windows. A Watch monitor is not created for a field which is already being monitored in some way.

Other Query commands treat Watch monitors as normal monitors.

Not available in base Animator.

Note: If the Watch monitors are turned into normal monitors, any subscripted items are monitored with the value of the subscript at the time of conversion.

Watch-off

Removes all watch monitors.

Not available in base Animator.

Wch

An abbreviation of the Watch Monitors function. See Watch Monitors.

Where

Moves the cursor to the start of the current statement, and repositions the program text so that the current statement becomes the third line on the screen.

Window-size-left/right/up/down

Enables you to define a new corner for your monitor at the cursor position. Once you have placed the cursor where you want your new corner, use the Redraw function to have your monitor updated.

Not available in base Animator.

Word Left

Moves the cursor to the previous word in the program text. If the cursor is positioned on the first word on a line, this function moves the cursor to the last word on the previous line and scrolls the text if necessary.

Word Right

Moves the cursor to the next word in the program text. If the cursor is positioned on the last word on a line, this function moves the cursor to the first word on the next line and scrolls the text if necessary.

Zoom

Executes the program at full speed, displaying the user screen rather than the Animator screen containing the source code.

You can break out of Zoom mode by pressing the Break key combination (on DOS, Windows and OS/2) or by pressing Escape (on UNIX), unless your program is executing an Enhanced ACCEPT, in which case the Break or Escape terminates the ACCEPT, and animation continues.

If you do not break out of Zoom mode, execution continues until a STOP RUN statement is encountered. At this point the Animator screen is restored and Step mode resumed.

Zoom Breakpoint

Sets a temporary breakpoint at the current cursor position and enters Zoom mode. When this breakpoint is encountered (or execution is interrupted for any other reason) the breakpoint is un-set.

Not available in base Animator.

4.6 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. You could receive such an error if you try to access a file in the wrong mode or if you use a corrupt file. Refer to your Error Messages for complete descriptions of possible run-time errors.

When animating a program, run-time errors are displayed on the bottom line of the screen in the format described in your Error Messages.

4.6.1 Communication Errors

DOS and OS/2:
Additional error messages can be produced during cooperative animation, due to a failure in the communications link between Animator and the user program (for example, if the network goes down). These take the form:

Communications error nnnnh

where nnnn is a four digit hexadecimal number.

The more common errors are:

4.7 Animating Generated Code

4.7.1 Overview

Using Animator to debug generated code has the following advantages over debugging intermediate code:

• You can debug the applications that you have shipped to your users. Making your applications debuggable does not affect their performance.

• It is possible to debug programs that use the Windows and Presentation Manager application program interfaces.

• You can investigate any problems that occur when the result of executing an .int code program differs from that of executing the same program compiled to generated code.

• Debugging processor-intensive programs is much faster when using generated code.

4.7.2 Operation

The following sections describe the steps you need to take before you can use Animator to animate generated code, how to invoke and use it and any restrictions you might need to be aware of when using it.

4.7.2.1 Preparing to Animate Generated Code

In order to animate generated code programs, Animator requires the following files to be available:

4.7.3 Starting Animator to Debug Generated Code

Before you start Animator, set the COBANIM_2 environment variable as follows:

Start Animator as you would normally:

animate [switchparams] program-name [directives]

See the section Invoking Animator earlier in this chapter for full details on invoking Animator. Any switch parameters to your animated program must be provided by the COBSW environment variable.

Animator then initializes itself, locates the program to be animated.

32-bit for Windows NT and OS/2 V2:
On the 32-bit COBOL system for Windows NT and OS/2 V2, the following message is then displayed:

Waiting for cross-session animated program to start...

SCO OpenServer:
On the COBOL system for SCO UNIX, the following message is then displayed:

Waiting for intra-session animated program to start...

If the application program starts executing without the Animator, it is due to one of the following reasons:

• No animatable .int file or .gnt or linked object file has been executed yet
  
  
• The .gdy file cannot be located in the current directory or in the path specified by the environment variable COBIDY.
  
  
• The COBANIM_2 environment variable is not set to ANIMATE.
  
  
• SCO OpenServer:
  Another login of the user's ID on the same UNIX system is animating the same program file

4.7.3.1 Animating .gnt Code Modules

Assume you have two programs, where:

cobcaller.cbl calls cobsub.cbl

Example:

Compile the programs:

anim cobcaller.gnt

4.7.3.2 Animating Object Code Modules

cobol cobcaller anim;
cobol cobsub anim;

cbllink -d cobsub

cbllink cobcaller

set cobanim_2=animate

animate cobcaller.exe

cob -xG cobcaller.cbl cobsub.cbl -ICOBANIM_STATIC

COBANIM_2=animate
export COBANIM_2

anim cobcaller

4.7.4 Error Messages

The following error messages might be issued by Animator when errors occur using generated code animation. Each message is explained here, and a corrective measure is suggested.

Error in animation communications channel

• Animator has encountered system limits or conflicts resulting in communications errors.
  
  
• Animate the program when the load on the system has reduced.

Animated program has terminated unexpectedly

• A program you are animating has terminated without following the standard run-time system shut-down process. This error is usually encountered when you initiate the termination, or when a severe run-time error occurs.
  
  
• Run the program without animation to determine if it runs successfully. If it does, animate the program without generated code animation.

Unable to initialize animated process

• Animator has encountered system limits in starting your program. The animated program cannot start because of insufficient memory or too many running processes. It is also possible the animated program could not initialize itself.
  
  
• Animate the program when the load on the system has reduced. Run the program without animation to determine if it successfully runs if it does, animate the program without generated code animation.

STOP RUN encountered during GNT animation

• Animator V2 has encountered a STOP RUN statement while animating your .gnt code program.
  
  
• Step or Run the animated program, and Animator V2 will terminate the program and its current session.

Analyzer and GNT Analyzer

COBOL Source Information