Inside COBOL May 2000: Loading up function keys

Loading up function keys

By Shawn M. Gordon

This month we’ll look at function keys, those delightfully convenient buttons that allow you to program up to eight different functions at a shot. Using function keys to issue commands allows you to avoid menus inside your programs, or forcing users to memorize a bunch of commands.
Over the years I developed a series of macros, variables and procedures for easily loading up function keys. You can take this as far as you want — depending on what you want to do will control the complexity. To start, take a look at Figure 1. KEY-POINT and KEY-BUFF will come into play later when we use the macros to load the function keys.

Figure 1:


01 KEY-POINT            PIC S9(9)        COMP VALUE 0.
  01 KEY-BUFF             PIC X(300)       VALUE SPACES.
*
  01 SET-FKEY.
     03                   PIC X            VALUE %33.
     03                   PIC X(02)        VALUE '&f'.
     03 FKEY-TYPE         PIC 9            VALUE 2.
     03                   PIC X            VALUE 'a'.
     03 FKEY-NUM          PIC 9.
     03                   PIC X(04)        VALUE 'k16d'.
     03 FKEY-LEN          PIC 99           VALUE 02.
     03                   PIC X            VALUE 'L'.
     03 FKEY-LABEL        PIC X(16).
     03 FKEY-DATA         PIC X(02).
     03                   PIC X            VALUE %15.
*
  01 KEY-ON.
     03                   PIC X            VALUE %33.
     03                   PIC X(03)        VALUE "&jB".
*
  01 KEY-OFF.
     03                   PIC X            VALUE %33.
     03                   PIC X(03)        VALUE "&j@".
*
  01 KEY1.
     05                   PIC X      VALUE %33.
     05                   PIC X      VALUE 'p'.
*
  01 KEY2.
     05                   PIC X      VALUE %33.
     05                   PIC X      VALUE 'q'.
*
  01 KEY3.
     05                   PIC X      VALUE %33.
     05                   PIC X      VALUE 'r'.
*
  01 KEY4.
     05                   PIC X      VALUE %33.
     05                   PIC X      VALUE 's'.
*
  01 KEY5.
     05                   PIC X      VALUE %33.
     05                   PIC X      VALUE 't'.
*
  01 KEY6.
     05                   PIC X      VALUE %33.
     05                   PIC X      VALUE 'u'.
*
  01 KEY7.
     05                   PIC X      VALUE %33.
     05                   PIC X      VALUE 'v'.
*
  01 KEY8.
     05                   PIC X      VALUE %33.
     05                   PIC X      VALUE 'w'.
*

SET-FKEY contains the entire escape sequence to load a particular function key with a particular value. The FKEY-TYPE means we want to transmit the data with a carriage return. The FKEY-NUM is which actual function key we are loading. FKEY-LABEL is the value that will appear in the function key label, you have 16 characters that will show up in two rows of eight. The FKEY-DATA value is what will be transmitted to the computer when you press the key.

Here is an important bit. I use an FKEY-LEN of 2, and have predefined the data length to be a buffer of 2. You could make this 80 if you wanted. Many moons ago I decided to use the default value of the function keys as their actual value, this is why you will see KEY1 thru KEY8 defined as they are, it allows me to say something like IF MY-VAR = KEY4 THEN. Now you might say, “What the heck does pressing KEY4 mean?” Depending on how you code this, you would be right, it’s hard to tell. My style of coding makes it easy for me to tell.

KEY-ON and KEY-OFF will turn on or off the function key display respectively. I once used these a lot, and depending on the context, it might make sense to turn the keys on and off. I will turn them off if they aren’t applicable to remove the visual cue. Another point when using function keys, try to make sure that they only contain values that apply to the current field. There is nothing worse than having function keys on a field that don’t work, or get the wrong results.

Now let’s move on to the macros; take a look at Figures 2 and 3.

Figure 2



$DEFINE %PREPFKEY=
          MOVE SPACES       TO KEY-BUFF
          MOVE 1            TO KEY-POINT#
  *
  $DEFINE %LOADFKEY=
          MOVE !1  TO FKEY-LABEL
          MOVE !2  TO FKEY-DATA
          MOVE !3  TO FKEY-NUM
          STRING SET-FKEY DELIMITED BY SIZE INTO KEY-BUFF
                 WITH POINTER KEY-POINT#
  *
  $DEFINE %SHOWFKEY=
          STRING KEY-ON DELIMITED BY SIZE INTO KEY-BUFF
                 WITH POINTER KEY-POINT
          SUBTRACT 1 FROM KEY-POINT
          MULTIPLY KEY-POINT BY -1 GIVING KEY-POINT
          CALL INTRINSIC "PRINT" USING KEY-BUFF, KEY-POINT, %320#
  *

Figure 3



  %PREPFKEY.
  %LOADFKEY("Sessions        "#,KEY1#,1#).
  %LOADFKEY(" Active Inactive"#,KEY2#,2#).
  %LOADFKEY("                "#,KEY3#,3#).
  %LOADFKEY("  View  LogFile "#,KEY4#,4#).
  %LOADFKEY(" Change Interval"#,KEY5#,5#).
  %LOADFKEY("                "#,KEY6#,6#).
  %LOADFKEY("                "#,KEY7#,7#).
  %LOADFKEY("  Main    Menu  "#,KEY8#,8#).
  %SHOWFKEY.

I like to have a macro that initializes all of our variables and pointers, hence the PREPFKEY. Next we have LOADFKEY, this will continually append data into the function key buffer in preparation for displaying it. You will notice that I have to manually center the text that is going to display in the function key labels. You might want to enhance the macro so that it will do it for you automatically.

Finally the SHOWFKEY macro will load up the function keys for you and display them. It’s probably a good idea to put the KEY-ON variable in here to ensure that the function keys are displayed for the user, which is I have it in here. We use the PRINT intrinsic because it is more efficient than DISPLAY, and less work than FOPENing and FWRITEing to the terminal.

That pretty much covers it. As you can see, it’s tailored to my own requirements but leaves you room for enhancement and growth. Play with it and have fun.

Shawn Gordon, whose S.M. Gordon & Associates firm supplies HP 3000 utilities, has worked with 3000s since 1983.