Introduction

---

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:

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:

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

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.

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:

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.

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:

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.

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.

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.

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:

For numeric edit-type fields:

For date edit-type fields:

For color-controlled fields:

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:

Colors:

Highlighting:

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

If you wanted Sfield to blink, you would code:

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.

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

MOVE RED TO @CUS01-AMOUNT@-COLOR

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.

NOTE:

• You should read the topic Symbolic Screen Field References in the Database Administration chapter before coding symbolic references. This feature was provided primarily for the coding of Business Rules and Referential Integrity Rules, however, it is also available to Application Developers.

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:

If you would like to see whether your terminal is defined as a 7-color device, enter the command:

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.

NOTE:

• tttt = Device ID (terminal ID)

• The DVCADD, DVCCHG, DVCSEE, etc. functions use this screen format.

• If your terminal is not defined on the DVC file, MAGEC assumes that it is not a 7-color terminal.

• A value of "Y" in 7-COLOR indicates that this terminal is an Extended Color & Highlighting device; a value of "N" (or blanks) indicates that it is not.