HP 3000 Manuals HP 3000 Manuals
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. 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 animation on DOS, Windows and OS/2, and on UNIX. See the chapter Compiler for complete details on compiling in your given environment.
NOTE 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 will not scroll beyond the normal COBOL margins, so results can be unpredictable. This facility is not available with base Animator.
On DOS, Windows and OS/2, you must compile your program with the ANIM directive set. For details on this directive, see the appendix Directives for Compiler. (DOS, Windows and OS/2) The command line for compiling your program for animation is: component prog-name anim; where: component is the program-name for the system component to be invoked, in this case the Compiler: DOS and OS/2 Windows cobol cobolw prog-name is the name of your application program.
NOTE Where you specify the command line depends upon the operating system you are running in. For example, in Windows and OS/2, if you have created a group for COBOL, then you double click on the appropriate program icon to invoke the component. Full details on the alternative methods of invoking system tools in your environment are provided in the chapter Introduction.
Compiling for animation causes information files (.idy), which are required by Animator, and an executable file to be created: DOS OS/2 Windows -------------------------------------------------------- prog-name.EXE prog-name.DLL prog-name.DLW The executable files contain intermediate code rather than the native code produced by a normal compilation. The automatic link step uses the link library COBLIB.LIB, together with other libraries depending on the operating system on which the Compiler is running. See the chapter Linking and Library Management for details. A dynamic link library file, with extension .DLL on OS/2 and .DLW on Windows, is created using the .DEF file with the root name the same as the source file-name. The DEFFILE Compiler directiveis on by default causing the Compiler to create a suitable.DEF file. If you need to use your own .DEF file, you must specify the NODEFFILE directive. See the appendix Directives for Compiler for further details on the effect of this directive. You may wish to perform the link step yourself. You can do this immediately following the compile since the .OBJ file remains present after the automatic link. However, you can prevent the automatic link altogether by specifying the directive OPT"0" when compiling. When you do link, in order to create an executable file suitable for animation, you must link with COBLIB.LIB (not LCOBOL.LIB). If you are running on OS/2 or Windows, you also must create a .DLL or .DLW file. See the chapter Linking and Library Management for details. On UNIX, the command to compile your program for animation is:(UNIX) cob prog-name By default, the COBOL system uses the -a cob flag to compile your source files ready for animation. See the chapter COBOL System Interface (cob) for details. 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 $COBPATH environment variable. See the appendix Micro Focus Environment Variables for details. If the system is unable to write to a .idy file, you may 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. Invoking Animator To invoke Animator, enter the command line: component [switchparams] program-name [directives] where: component is the program-name for the system component to be invoked, in this case Animator: DOS and OS/2 Windows UNIX animate animatew anim switchparams is 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 appendix Descriptions of Run-time Switches for details on the switches available. program-name is the name of the file you wish to animate. The file-name should be of the form described in the chapter Compiler. If you do not specify a path, the current directory is assumed. On DOS, Windows and OS/2, do not specify an extension. For details on the search sequence followed, see the chapter Compiler. On UNIX, if you do not specify an extension, the extension .gnt will be searched for first, followed by .int. Any .gnt file will be zoomed. directives is 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. For details on the directives available, see the appendix Directives for Animator.
NOTE Where you specify the command line depends upon the operating system you are running in. For example, in Windows and OS/2, if you have created a group for COBOL, then you double click on the appropriate program icon to invoke the component. Full details on the alternative methods of invoking system tools in your environment are provided in the chapter Introduction.
If you attempt to run Animator on UNIX using a run-time system built using the "-m sqfile" option, you will receive undefined results.(UNIX) Cooperative and Cross-session Animation The following sections describing cooperative and cross-session animation apply only to DOS and OS/2; these facilities are not available on Micro Focus COBOL for UNIX environments. (DOS and OS/2) 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 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, then 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 within the user session. If you wish to preserve any stored keystrokes in your application, use the HOLDVIEW"n" Animator directivewhen starting Animator. Then after you select the View function, the Animator screen will return automatically after n seconds. See the appendix Directives for Animator for further details.
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.
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, then you should always specify a unique network name.See the appendix Directives for Animator for details on setting USER-MACHINE. 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. Starting Cross-session Animation. 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: DOS OS.2 ------------------------------------------------- COBLIB.DLE COBLIB.DLL COPY-file and Information File Location You can direct the COBOL Compiler to look for COPY-files 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 COPY-file 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 will be searched. See the chapter Compiler for details. On DOS, Windows and OS/2, to set the COBCPY environment variable: (DOS, Windows and OS/2) set cobcpy=e:\myapp\cpyfiles;d:\common\cpyfiles On UNIX, to set the COBCPY environment variable:(UNIX) COBCPY="/usr/group/sharedcopy:/usr/mydir/mcpy" Animator can be directed to look for its information files (.idy) 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: On DOS, Windows and OS/2, to set the COBIDY environment variable: (DOS, Windows and OS/2) set cobidy=e:\myapp\idyfiles;d:\common\idyfiles On UNIX, to set the COBIDY environment variable:(UNIX) COBIDY=":/usr/lib/cobol/" 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. 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. 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. 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 the base Animator. (DOS, Windows and OS/2) The following table lists the name of the cursor control keys, their function and the keystrokes required to obtain them. Some of these keys are symbolic key names which may not be present on your keyboard. For details of the actual keystrokes for your environment, see the appendix UNIX Key Usage Chart.(UNIX) ----------------------------------------------------------------- | | | | | Key | Function | Default Key/Keystroke | | Number | | | | | | | ----------------------------------------------------------------- | | | | | | | | DOS, Windows | UNIX | | | | and OS/2 | | | | | | | ----------------------------------------------------------------- | | | | | | cursor-| moves the cursor | <- | cursor-left | | left | left one character | | | | | position | | | | | | | | ----------------------------------------------------------------- | | | | | | cursor-| moves the cursor | -> | cursor-right | | right | right one | | | | | character position | | | | | | | | ----------------------------------------------------------------- | | | | | | cursor-| moves the cursor | ^ | cursor-up | | up | up one line; with | | | | | Scroll Lock on | | | | | moves the text | | | | | down one line | | | | | | | | ----------------------------------------------------------------- | | | | | | cursor-| moves the cursor | v | cursor-down | | down | down one line; | | | | | with Scroll Lock | | | | | on moves the text | | | | | up one line | | | | | | | | ----------------------------------------------------------------- | | | | | | Tab | moves the cursor | Tab | Tab | | | to the next tab | | | | | position to the | | | | | right; tabs are | | | | | set every four | | | | | positions in | | | | | columns 1 through | | | | | 76 in Animator and | | | | | in columns 8 | | | | | through 72 in the | | | | | base Animator | | | | | | | | ----------------------------------------------------------------- | | | | | | Backtab| moves the cursor | Backtab | Backtab | | | to the next tab | | | | | position to the | | | | | left | | | | | | | | ----------------------------------------------------------------- | | | | | | Enter | moves the cursor | Enter | Enter | | | to column 1 on the | | | | | next line in | | | | | Animator and in | | | | | column 8 on the | | | | | next line in the | | | | | base Animator; | | | | | with Scroll Lock | | | | | on, moves the text | | | | | up one line | | | | | | | | ----------------------------------------------------------------- | | | | | | Home | moves the cursor | Home | Home | | | to column 1 of the | | | | | current line in | | | | | Animator and to | | | | | column 8 of the | | | | | current line in | | | | | the base Animator; | | | | | pressing Home a | | | | | second time moves | | | | | the cursor to | | | | | column 1 of the | | | | | top line in | | | | | Animator and to | | | | | column 8 of the | | | | | top line in the | | | | | base Animator; | | | | | pressing Home a | | | | | third time moves | | | | | the cursor to the | | | | | beginning of the | | | | | file | | | | | | | | ----------------------------------------------------------------- | | | | | | End | moves the cursor | End | End | | | to the end of the | | | | | current line; | | | | | pressing End a | | | | | second time moves | | | | | the cursor to the | | | | | bottom of the | | | | | screen; pressing | | | | | End a third time | | | | | moves the cursor | | | | | to the end of the | | | | | file | | | | | | | | ----------------------------------------------------------------- | | | | | | Page- | displays the | Page-Up | KEY_PPAGE or | | Up | screen of program | | Ctrl+U | | | text preceding | | | | | this screen | | | | | | | | ----------------------------------------------------------------- | | | | | | Page- | displays the | Page-Down | KEY_NPAGE or | | Down | screen of program | | Ctrl+D | | | text following | | | | | this screen | | | | | | | | ----------------------------------------------------------------- | | | | | | Top- | moves immediately | Ctrl+Home | Ctrl+T | | of- | to the top of the | | | | text | program | | | | | | | | ----------------------------------------------------------------- | | | | | | Bottom-| moves immediately | Ctrl+End | Ctrl+V | | of- | to the end of the | | | | text | program | | | | | | | | ----------------------------------------------------------------- | | | | | | Up-10- | moves (10 x source | Ctrl+Page-Up | KEY_SR or | | screens| screen size) lines | | Ctrl+B | | | up the program | | | | | | | | ----------------------------------------------------------------- | | | | | | Down- | moves (10 x source | Ctrl+ | KEY_SF or | | 10- | screen size) lines | Page-Down | Ctrl+F | | screens| down the program | | | | | | | | ----------------------------------------------------------------- | | | | | | F1 | Function key 1 | F1-F10 | KEY_F(0-10) | | thru | thru Function key | | | | =F10 | 10 | | | | | | | | ----------------------------------------------------------------- | | | | | | Escape | Escape | Esc | Esc | | | | | | -----------------------------------------------------------------
WARNING The Animator interrupt keyis 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 may 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 may wish 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 the Ctrl+K keys to interrupt an Adis ACCEPT.
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 will be present. This can be cleared using F2=clear key. 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 <-, ->, 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 wish to cancel the update, press the Escape key. Both keys will 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 will select the item you want and place it in the input field if appropriate. Using the Animator Windows. Animator places information within 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. 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. 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. Key Functions for Updating Queried Data Items. The following keys and key combinations have special effects when updating the contents of data items. Some of these keys are symbolic key names which may not be present on your keyboard. For details of the actual keystrokes for your environment, see the appendix UNIX Key Usage Chart.(UNIX) ------------------------------------------------------------------ | | | | | Key | Function | Default Key/Keystroke | | Number | | | | | | | ------------------------------------------------------------------ | | | | | | | | DOS, Windows | UNIX | | | | and OS/2 | | | | | | | ------------------------------------------------------------------ | | | | | | Home | moves the cursor | Home | Home | | | to the beginning | | | | | of window | | | | | | | | ------------------------------------------------------------------ | | | | | | Top-of- | moves the cursor | Ctrl+Home | Ctrl+T | | Text | to beginning of | | | | | the data item; | | | | | causes the | | | | | contents of the | | | | | window to change | | | | | if not currently | | | | | displaying the | | | | | beginning of the | | | | | item | | | | | | | | ------------------------------------------------------------------ | | | | | | End | moves the cursor | End | End | | | to the end of the | | | | | window | | | | | | | | ------------------------------------------------------------------ | | | | | | Bottom- | moves the cursor | Ctrl+End | Ctrl+V | | of-Text | to the end of the | | | | | data item; causes | | | | | the contents of | | | | | the window to | | | | | change if not | | | | | currently | | | | | displaying the end | | | | | of the item | | | | | | | | ------------------------------------------------------------------ | | | | | | cursor-up | moves the cursor | ^ | cursor-up | | | up one line; if at | | | | | the top of the | | | | | window, updates | | | | | the window to show | | | | | the previous | | | | | window of the | | | | | item's contents | | | | | | | | ------------------------------------------------------------------ | | | | | | cursor- | moves the cursor | v | cursor-down | | down | down one line; if | | | | | at the bottom of | | | | | the window, | | | | | updates the window | | | | | to show the next | | | | | window of the | | | | | item's contents | | | | | | | | ------------------------------------------------------------------ | | | | | | cursor- | moves the cursor | <- | cursor-left | | left | left one character | | | | | position; if at | | | | | the beginning of | | | | | window, shifts | | | | | data in the window | | | | | one character to | | | | | the right | | | | | | | | ------------------------------------------------------------------ | | | | | | cursor- | moves the cursor | -> | cursor-right | | right | right one | | | | | character | | | | | position; if at | | | | | the end of the | | | | | window shifts data | | | | | in the window one | | | | | character to the | | | | | left | | | | | | | | ------------------------------------------------------------------ | | | | | | F2 | clears the | F2 | KEY_F2 | | | contents of the | | | | | data item | | | | | | | | ------------------------------------------------------------------ | | | | | | Ins | toggles between | Ins | Ins | | | insert and replace | | | | | modes; in insert | | | | | mode, Ins is | | | | | highlighted on the | | | | | information line; | | | | | the cursor changes | | | | | shape | | | | | | | | ------------------------------------------------------------------ | | | | | | Del | deletes the | Del | Del | | | character at the | | | | | current cursor | | | | | position; if | | | | | insert mode is on, | | | | | causes all other | | | | | characters to the | | | | | right of cursor in | | | | | the window to | | | | | shift left one | | | | | position | | | | | | | | ------------------------------------------------------------------ | | | | | | Backspace | deletes the | Backspace | Backspace | | | character before | | | | | the cursor | | | | | position; if | | | | | insert mode is on, | | | | | causes all | | | | | characters to the | | | | | right of cursor in | | | | | the window to | | | | | shift left one | | | | | position | | | | | | | | ------------------------------------------------------------------
![[]](../../pic3k/M015145/FFN233c50.gif)
![[]](../../pic3k/M015145/FFN243c50.gif)