Who Should Read This Guide

This guide is written primarily for use by those who will be using the MAGEC Application Development facilties to develop online applications using 3270 terminals with the Extended Color feature.

Copies of this guide should be distributed to:

  • Application Developers
  • System Programmers
  • Prerequisite Reading

    This guide is written assuming that the reader is familiar with the online development processes of MAGEC. If you have not yet read the following chapters in the Tutorials manual then we recommend that you do so:

    "Application Developer"


    You might also find it handy to have "Analysis of the Generated MMP" from the Programmer's Reference manual nearby for reference.

    Color 3270 Feature

    MAGEC's Color 3270 Feature is necessary only to enable you to take advantage of the extended color and highlighting capabilities which are available on the newer terminal hardware.

    If your site does not have color terminals, then you will be able to develop applications which will operate correctly on your non-color terminals and will also work correctly (and more impressively) when you do install the color terminals, without any program changes or re-compiles.

    The MAGEC Color 3270 feature enables you to take advantage of the 7-color and Extended Highlighting features of your CRT terminals. If your terminals are not equipped with these features then you may ignore this section. If some or all of your terminals are 7-color then you will find this MAGEC feature extremely beneficial.

    You can specify screen field color at the time you "paint" your screens and you can programmatically alter the color and set extended highlighting in your MMP's. MAGEC provides complete transparency for your applications and your Masks. If you specify color and extended highlighting for fields in your Mask and then execute the application from a non-7-color (either monochrome or 4-color) terminal, then MAGEC will automatically adjust the control character sequences accordingly. This means that your applications will still be usable from all your terminals, without any special programming by you. Applications which are developed without specifying color controls will, of course, still operate at both color and non-color terminals as well.

    MAGEC determines whether your terminal, or monitor, can support Extended Color attributes by looking at the DVC-file definition for your terminal. If the terminal is not defined, MAGEC defaults safely to non-Extended color support.

    How to Specify Color

    Field Color in MSKDEF

    If you wish to specify color control for a screen field you must do so via the online screen painting function MSKDEF. Using MSKDEF you set the initial value for the color attribute for a screen field. This tells MAGEC:

  • Initially set that field to the color specified.
  • Generate color and extended highlighting control fields in the Mask copybook for that screen field.
  • The color and extended highlighting support costs 6 bytes of space per screen field in the Mask Initialization Record (on the MSK file). This may reduce the number of screen fields you can fit on a Mask. The six byte area is only generated, however, for those screen fields for which you have specified color. The Mask copybook will include definitions for the special color and extended highlighting controls along with the usual screen field definitions. This enables you to alter the values of them just as you are able to set the value for the ordinary field attributes.

    MSKDEF Specifications

    When you select a screen field using the PF18 key (in MSKDEF), the selected field's specifications appear in a pop-up window display. You can modify any of them, as you learned in the tutorials for Application Development and Customization.

    One of the specifications is "CLR", which is short for "color". You can specify the initial color for a screen field here. Either the numeric value code or the letter code may be used. The possible values are:

    Value               Meaning---Letter Code

    0               No color control---Default

    1               Blue---Blue

    2               Red---Red

    3               Pink---Pink

    4               Green---Green

    5               Turquoise---Turquoise or Cyan

    6               Yellow---Yellow

    7               White (or Black)---White

    If you specify a letter code, rather than its numeric equivalent, MAGEC will translate the letter code into its numeric equivalent for you. This is done merely to simplify your entry and to eliminate the need for you to memorize the numeric codes.

    If you specify "0"(or "D"), MAGEC generates no color or extended highlighting controls for that field. If you specify any other value then MAGEC will generate the color and extended highlighting controls.

    If you wish to alter the color of a screen field in your MMP, then you must specify a value other than "0" for that field, in order to have color support generated for it.

    If you specify color support for any field(s) in a Mask, then that Mask is considered to be a color Mask. If you execute your MMP from a mainframe terminal which has the 4-color (Base Color) option and you are using a color Mask, then the terminal hardware will automatically revert to the "monochrome" state (all green, usually), except for those fields for which you have specified a color. This means that the 4-color option is set off and the 7-color option (if present) is set on. This is a function of the 3270 control unit, not of MAGEC.

    MSKDEF, Pop-Up Specifications

    Figure 01 is an example of how the pop-up window on MSKDEF's display appear when you have selected a screen field for "change" using PF18.

    The specification for color is shown with a prompt of "CLR". It defauts to "0" (no color support), you can alter it to any valid value to specify color support for that screen field.

    If you specify any valid (1 - 7, or their letter equivalents) color code here, then MAGEC will generate the 6 bytes of color and extended highlighting control codes in your Mask for that screen field and the initial color will be what you specified. The extended highlighting code will be initialized to NO-HILITE unless the 3270 attribute (ATTR:) is set to a high-intensity attribute (as: SADHNF, UNDHNF, etc.), in which case the extended highlighting will be set initially to BLINK.

    The ordinary attribute highlighting (which controls high-intensity) and the extended highlighting are mutually exclusive, the hardware can only do one or the other for a given screen field. MAGEC automatically highlights error fields by either setting the high-intensity attribute or by setting the extended highlighting to BLINK, depending on what type of terminal you are at (7-color or not). MAGEC makes the determination at execution-time and adjusts accordingly.

    Pop-Up HELP

    The MSKDEF function has a special built-in HELP feature (in addition to the normal PF1 HELP key) which uses a pop-up window. You can press PF24 at any time to see the pop-up screen. When you press PF24 again, the pop-up window will disappear and your MSKDEF screen will be back to normal. The pop-up help display shows you the color codes as well as 3270 attribute codes and other useful data to help you in using MSKDEF effectively.

    While you are looking at the pop-up display you can press ENTER to scroll forward through the complete text you can press PF24 to quit at any time.

      MSKDEF mmm                             -- HIT  ENTER TO CHANGE --

    LAST GEN=93 08 05 --LINE: 4=DUP 5=ERASE 6=MOVE 13=DEL 15=INS
    LAST UPD=93 06 22 2494 BYTES MAX, nnnn USED, nnnn LEFT  PF24=POP-UP HELP

    Figure 01 --  Screen Field Specifications - MSKDEF in "Change mode"

    Controlling Color in an MMP

    Mask Copybook

    As you will recall, the Mask copybook which MAGEC generates for your Mask includes definitions for all your screen fields plus definitions for all the necessary control fields associated with them. For each field (assuming a screen field named "Sfield") it includes:

    Sfield               the actual screen field

    SfieldA               the 3270 attribute byte

    SfieldE               the field's error flag

    Sfield-POSN               the field's position on the screen

    For numeric edit-type fields:

    Sfield-N               numeric value of contents of Sfield

    Sfield-ED               Cobol edit pattern for Sfield

    For date edit-type fields:

    Sfield-DAY-OF-WEEK               Sunday=1, Saturday=7, etc.

    Sfield-JULIAN-DATE               Julian equivalent of entered date

    For color-controlled fields:

    Sfield-COLOR               color code

    SfieldH               extended highlighting code

    You can reference any of these control fields in your MMP. Your MMP's automatically have symbolic names defined for all the valid colors and extended highlighting options. They are:
















    If you wanted to set Sfield to be yellow, you would code:

    MOVE YELLOW TO Sfield-COLOR.                

    If you wanted Sfield to blink, you would code:

    MOVE BLINK TO SfieldH.                

    Your MMP's initialization process includes the initialization of the color and extended highlighting settings back to the color you specified in MSKDEF and to NO-HILITE each time the MMP is entered.

    Symbolic Screen Field References

    When you are coding customization logic for your MMP's, you will usually be more familiar with the database field (DIT) datanames than with the screen field (MSK) datanames. For that reason, you may prefer to utilize MAGEC's Symbolic Screen Field Referencing feature which is described in detail in the "Database Administration" chapter of the Programmer's Reference manual.

    Briefly, it enables you to use the database name to indirectly access screen fields. The mapping of database names to screen field names is controlled by the associations defined in the screen's Mask definition. The associations are defined using the "Source/Target" specifications for screen fields.

    Assuming that you had a screen field named SAMOUNT with a source/target named CUS01-AMOUNT, you could code:

    MOVE +10.00 TO @CUS01-AMOUNT@-N  @CUS01-AMOUNT@-ED


    rather than having to look up the screen field name (SAMOUNT) in order to access it.

    MAGEC will, as the program is being generated, translate the symbolic references into the proper Cobol datanames.


    Defining Color Terminals

    DVC Definition

    In order to tell MAGEC that a given terminal (Device) is equipped for Extended Color & Highlighting you must define it to the MAGEC Device (DVC) file.

    The DVC file is where you define a profile for your terminals for the MAGEC Security System, the MAGEC TP Spooler, and for Color 3270 support.

    To specify that a terminal has Extended Color and Highlighting enter "Y" into the field titled "7-COLOR".

    Defining your terminals to the DVC file is not a basic requirement to use MAGEC, it is only required if you desire one or more of the following:

  • Security by Terminal
  • TP Spooling capabilities from this terminal
  • 7-Color support for this terminal
  • If you would like to see whether your terminal is defined as a 7-color device, enter the command:

    DVCSEE *

    The asterisk (*) will automatically be replaced by the terminal ID of the terminal you are at. This also works for DVCADD or DVCCHG. This makes it easy for you to define or modify the definition of your terminal without having to key in the cryptic terminal ID.

    The DVC file profiles are used for the Security system and the TP Spooler also. There may be security restrictions as to who may see or alter DVC file profiles. If you are unauthorized for these functions and you feel you should be authorized, see your Security Officer.


     DVC... tttt
     ID= tttt
     Location: ___  ( ) Buf Size: ______
     Type: ____  L/R: _______  7-Color(Y/N): _  --TEST--  --PROD--
     Desc: _____________________________________  87654321 87654321
     Status __________  Form: ____  User Views: ________  ________
     Active Report Time Out: ___ min.
     Print Classes: ____________________________________  SMTWTFSH
    Authorized Hours: __ __ to __ __  Days: ________
     ...............MAXIMUM AUTHORIZATION LEVELS BY APPLICATION.....................
    G/L (01): _  A/P (02): _

    Press PF4 for browse (LOC) screen  Press PF13 for Hardcopy
    Press PF16 to Copy field to buffer  Press PF17 to Paste data from buffer
    Press PF2 for field-level HELP

    Figure 02 --  Device Profile Screen