Who Should Read This Guide

This guide is written primarily for use by those persons who will be responsible for developing and maintaining online applications.

Copies of this guide should be distributed to:

  • Application developers
  • Analysts
  • Prerequisite Reading

    Since this is a detailed discussion of the facilities provided by the manual screen painting function in MAGEC, and since manual screen painting is only a portion of the overall activities of an application developer, we recommend that the reader first read the "Application Developer" Tutorial. That tutorial should help to position manual screen painting within the overall scheme of developing and maintaining online applications. It is important to note that rarely would a developer begin his/her project by using the manual processes; though that is quite possible to do. It is more usual to expect that he/she would first utilize the automatic screen painter, then use the manual processes to add finishing touches to the generated screen.

    The "Edit Types" chapter gives a detailed explanation of each MAGEC edit type. Edit types play a significant role in screen painting; therefore, it would be wise to review that manual.

    The "Color 3270" chapter offers a detailed discussion of the color and extended highlighting attributes usage as well as the Cobol definitions which appear in the generated mask copybook. You should review it or have it handy to help answer questions you might have while learning screen painting.

    The appendices of the "Application Developer" and "Customization" tutorials contain very useful, concise information about several topics relevent to screen painting.

    Standard Screen Fields

    All MAGEC screens, including both MAGEC's "system" screens and all generated applications' screens, abide by certain standards. They all contain four standard screen fields which have uniform usage and definition. These four standard fields occupy the first line of the screen and the last three lines of the screen.

    When you are defining screen masks, your screen fields must not occupy the lines where those standard fields are. All other areas of the screen are available for your use.

    The standard screen fields enable MAGEC to provide many extra features for your applications without any extra effort by you. They also give all your applications a standard user interface which makes it easier for your end users to learn and remember how to use new applications. The figure on the opposite page diagrams the four standard screen fields.

    SFUNCT is a 6-character field, the first field on every screen, in which you can enter any function code. Some examples of function codes are: VACSEE, MSKDEF, CUSADD, and so forth.

    SKEY is a 31-character field in which you can enter a key argument which qualifies the function code. For example, entering a command (SFUNCT plus SKEY) of:

    VACSEE 18  

    means that you wish to see the vacation data for employee 18.

    SCOMPL is a 40-byte message area where "completion messages" are displayed. An example of a completion message is: "Data ADDED to Database". You can, in your program, move your own messages here if you like. SCOMPL is never an enterable field on the screen, it is display-only.

    SERRMSG is a 240-character screen field which occupies the last three lines of the screen. It is where MAGEC's automatic editing services will display error messages to the operator. You can move your own display-only data to this screen field, but it is not an enterable area to the operator.

      ______ _______________________________ ........................




    Figure 01 --  Standard Screen Fields

    Sequence of Tasks

    Screen painting is actually an integral part of the overall online application development process and not ordinarily looked upon as a separate task. Nonetheless, you can create a screen without creating a complete application. That screen could then be used by other applications.

    In most cases you will use the automated screen painting facilities of MAGEC to do most of the work of painting a screen, then use the manual screen painter as needed to improve upon what was automatically painted. You can also bypass the automated paint facility and manually paint your screen from scratch. If you do that you will be responsible for doing all of the many things which would have been done for you automatically, but you have complete flexibility.

    Once you have completed painting the screen to your satisfaction, you must use either the online or the batch "create" facility to actually create the two components which are needed by any program which is to use that screen. The two components are:

  • mask initialization record
  • Cobol copybook
  • The online function, MSKCRE, or the batch jobstream, MSKCREAT, accomplish the same task. They both read the MAGEC repository to extract the specifications for your mask and create the two necessary outputs described above.

    The mask initialization record is a record on the MAGEC MSK file which contains the entire screen format, including all data fields, attributes, literal values, editing rules, and control fields. The Cobol copybook is a complete definition of that record. The user program includes the Cobol copybook in a prescribed area in its data division and, when it wishes to initialize the screen with this mask, reads the mask initialization record into that area. The program references any of the screen fields using the datanames in that copybook.

    The most usual sequence of tasks that you would do when defining or modifying a screen mask is:

    MSKDEF is a "graphically-oriented" online screen painter which is capable of doing any type of modification to a mask, including moving fields, adding fields, deleting fields, and similar operations to entire lines of fields. There is also another facility which enables you to make "mass" changes based upon selection criteria; it is the SCDGBL function described later in this chapter.

    Screen Header Definition

    SHDxxx Functions

    The definition of an online screen (known as a "mask") consists of two types of entities: the screen header and the screen detail (screen fields). Before MAGEC will allow screen detail definitions to be added to the dictionary (the terms "dictionary" and "repository" are used interchangeably), there must be a header defined. There may be many screen fields associated with one screen header.

    A screen header (SHD) is defined using the SHDxxx functions. Inquiry, browse, query, and limited update functions are provided. The screen header contains high-level information about the screen. It is used not only by the processes which generate a screen mask, but also by the processes which generate the program (MMP) accessing that mask.

    When MAGEC generates a mask it posts the date-generated in the screen header record and also in the mask record and the mask copybook which are generated. When you modify or add screen fields the date-updated is automatically posted in the screen header record. These dates help you to see at a glance whether you are using an out-of-date version of a mask and whether you need to recreate the mask (using either the online MSKCRE function or the batch MSKCREAT jobstream). The online version verification (VERZUN) references the screen header and other dictionary data in order to compare version information for all components of an application.

    Figure 02 --  Screen Header / Detail

    SHDxxx Screen

    The screen header definition parameters control the automatic generation of both the screen mask and the program.

    The mmm value in SKEY (Screen Key) on line one is the 3-character screen identifier. It is called a "Mask Number" or "Screen Header Number". Its format is nxx, where x is any alphanumeric character and n is any digit (0 thru 9).

    Msk (in the heading) is the three-character identifier. This is not an enterable field on the screen; it will be filled in by MAGEC using the data from the Screen Key field on line one.

    Description: is a 25-character title for the screen. If you use the automatic screen painter it will use this description as the heading on the generated mask.

    MMP#: is the three-character MMP number of the generated program which processes the screen defined by this SHD record and its associated screen detail records.

    Function Code Prefix is the 3-character prefix to be used in generating the online function codes. The default is the DCL name.

    Use Model specifies the model to be used when defining the MMP. Valid entries are MODELMMP or MODELWIN or other model names defined on MAGEC Lookup Table #205 and starting with "MOD". MODELMMP is the default. (For more information on MODELWIN refer to the Tutorials "Application Developer" chapter, Appendix I.)

    Verify Opt: tells the program generator (MMPCREAT jobstream) whether or not to generate code to verify that numeric data items in the database records are truly numeric before trying to access them. This is useful in preventing data exception errors when there is the possibliity of bad data being read by the MAGEC-generated program.

    Extd. Color system fields: is a yes or no specification as to whether there is to be extended color support generated for the four standard screen fields: SFUNCT, SKEY, SCOMPL, and SERRMSG. If this parameter is set to Y when the mask is created, then the MMP can dynamically alter the color and extended highlighting attributes for those four screen fields just as for any other extended color fields.

    Color protected fields: is the specification for a valid color code (0 thru 7) to be used for all protected fields as the mask is auto-painted. The MMP can alter the color at execution time, if desired. A value of 0 indicates no extended color support is to be generated for protected fields (it can be specified later using the manual screen painter).

    Color unprotected fields: is for specifying a valid color code (0 thru 7) to be used for all unprotected fields as the mask is auto-painted. The MMP can alter the color at execution time, if desired. A value of 0 indicates no extended color support is to be generated for unprotected fields (it can be specified later using the manual screen painter, however).

    DCL is the three-character data class name of the primary data class accessed by this application. MAGEC will automatically generate all necessary accesses for this data class. Any number of other data classes can be joined to it, as well. The logical join process is described in the "Application Developer" tutorial.

    Element 1 thru 9 are the names of up to nine elements of the primary data class. These describe which data from the primary data class will be accessed.

    Programmer: is the name of the person is responsible for this screen mask. It is recommended that you avoid embedded blanks, use dots (.) instead: i.e. JOE.DOE.

    Last Generated and Last Updated are dates which will be posted by MAGEC when the mask is generated or altered.

      SHDxxx  mmm 
    M A G E C Data Dictionary
    Screen Header Definition for MSK mmm

    Description: ______________________________
    MMP#: ___  Function Code Prefix: ___   Use Model:  MODELMMP  Verify Opt: __ ______ 'VERIFY' or 'NO'

      Extd. Color system fields: _ Y OR N 
       Color protected fields: _ (no color)  Color unprotected fields: _ (no color)

    P R I M A R Y  D A T A 
     DCL: ___
     ELTs: ..1.. ..2.. ..3.. ..4.. ..5.. ..6.. ..7.. ..8.. ..9..
    _____  ____  ____  ____  ____  ____  ____  ____  ____
    Press PF6 to select a Data Class and Elements 

    Programmer: ______________  Last Generated:  Last Updated: 


    Figure 03 --  Screen Header Definition

    Various Screen Definition Functions

    Online Functions

    The following online function codes are used by application developers to define, modify, copy, and delete screen detail definitions.

    PAINTx PAINT1 thru PAINT6 are used to auto-paint the screen from
    data definitions in the MAGEC repository

    MSKDEF online screen painter

    MSKDEL delete all detail definitions for a mask

    MSKDUP duplicate an entire mask's detail to another mask number

    MSKCRE create the mask initialization record and Cobol copybook for a
    mask from the detail definitions in the repository

    SCDxxx list, browse, or display screen detail records from repository
    allowing updating of Locate Heading specification for a field

    SCDGBL global (mass) change to detail records for a mask based
    upon selection criteria

    SHDxxx list, browse, display, update, add, or delete screen headers

    MSKPOP pop-up window of help text for screen painting

    MSKSEE display generated screen from the mask initialization record
    created by MSKCRE (or batch MSKCREAT)

    Batch Jobstreams

    The actual creation of the mask initialization record and Cobol copybook used by the MMP can be done either online, using the MSKCRE function, or in a batch jobstream named MSKCREAT. You should refer to the "Offline Utilities" chapter for details of the JCL and control cards for MSKCREAT and other batch jobstreams. Batch jobstreams also exist for producing hardcopy pictures and documentation for a mask.

    MSKCREAT (obsolete) generate screen and copybook

    MSKDOC print documentation for mask and applications

    MSKPRT print an image of the generated screen

    Screen Detail

    MSKDEF Screen Painter

    The principle method for adding, modifying, or deleting screen detail field definitions is via the online screen painter, MSKDEF. All work is done using an image of the screen mask as it will appear when generated, with the addition of special display characters to indicate where field attribute codes will be. This enables you to continuously observe the results of changes as you make them.

    Mode of Operation

    The image of a mask is made up of a collection of one or more screen fields. Each screen field has an individual record defining it in the MAGEC repository, enabling you to manipulate it with the maximum of flexibility.

    There are two types of screen fields: variables and constants. A variable is a field which has a name and which can be referenced by the generated program. A constant is named FILLER and cannot be referenced. Constants are used for headings, prompts, and the like. It is perfectly acceptable for a heading or prompt to be a variable, as well. This enables you to have headings or labels on the screen which you can alter from your program. Every field, whether variable or constant, has its own discreet definition in the repository and can be modified via the MSKDEF facility.

    A common structure for screens is to have pairs of fields, one constant and one variable. For example:

    @ _________>


    In the above example the at-signs (@) show where the field attribute bytes will reside. There are two screen fields, one is a constant which contains the value "Emp#" and the other is a variable which contains a value of all underscores. The variable field is where the program would move the actual employee number to be displayed, it is also optionally an enterable field where the operator can key in an employee number. The greater-than symbol (>) indicates a "stopper", a dummy field having an attribute but not data, which is used to terminate the preceeding field. There is not a stopper after the first field (the constant) because another field immediately follows it, serving as a stopper for it.

    The MSKDEF facility allows you to select a field by pointing the cursor to it and pressing a PF key. The choice of which PF key was hit determines what is to be done to the selected field. For example, pressing PF18 would indicate that you wished to change the specifications for that field, pressing PF19 would indicate that you wished to delete that field from the mask, and so on.

    There are also line manipulation functions which enable you to operate upon all fields on the selected line at one time. For instance, you could move an entire line to another line on the screen, or you could delete all fields on a line. To use the line manipulation functions you simply position the cursor anywhere on the line you wish to operate upon and press the appropriate PF key.

    A legend of the PF keys and their meanings is displayed on the last three rows of the MSKDEF screen along with statistics about the mask. The PF keys are divided into "field manipulation" and "line manipulation" keys in the legend.

     MSKDEF xxx
      M A G E C  Development Process Selection

      Press PF7  -  for the semi-automated development process which allows you to
      provide Cobol code to construct the key(s) to use to join
      additional Data Classes to the primary Data Class.

      Press PF8  -  for the fully-automated development process which generates the
      join logic completely based upon your selections and using the
      Domain definitions for Data Items.

      Press PF3  -  to return to the manual screen painter which provides complete
      flexibility to manually draw a screen, define attributes, and
      code join logic.

    Choose the level of automated development you desire.  The fully-automated
    process is preferred.  The semi-automated process is necessary only if your
    data has not been defined using MAGEC's Domain facility.

    Figure 04 --  MSKDEF Screen


    Detail Field Specifications

    When you select a screen field for "change", a pop-up window shows you all of the specificatons for that field. You can overtype them to make your changes. They are:

    Scrn Fld Nm: is the name to be used for this screen field in the generated mask copybook. This name may be up to seven characters long. In the copybook you will find the actual screen field defined using this exact name, plus various other related fields named using this name with a suffix added. For example: the attribute byte for the field named "SFIELD" would be named "SFIELDA", the edit picture for it would be named "SFIELD-ED" (if it were a numeric item).

    The occurrence [( ... )] is the Cobol subscript value used to access this field, if it is part of an array. A value of 000 indicates that the field is not part of an array and that no subscript is needed. A value of 001 thru 099 is the actual occurrence number or subscript value to be used. A value of "*nn" indicates that this field is a repeating field it is occurrence 01 of an array and MAGEC is to automatically generate occurrences 02 thru nn aligned vertically below. A value of "#nn" is similar to "*nn" except that the array is repeated horizontally, rather than vertically. When you use either of these automatic repeating field specifications, MAGEC displays the generated occurrences on the MSKDEF screen exactly where they will appear on the generated mask. It uses a ditto (") to indicate where the attribute for each field will be, rather than the usual at-sign (@).

    Database Source/Target: is the Cobol name of the database field which is both the source (for displays) for this screen field, and the target (for updates) from this screen field. This may be the name of a database field or of a work field in your MMP's data division. If you leave this blank, MAGEC will simply not generate any moves to or from this screen field you can code your own moves through customization, though. The name given in this parameter may contain a subscript enclosed in parentheses, just as you would spell it in Cobol coding. If the screen field is part of an array (that is, if the occurrence number is non-zero), then the subscript for the source/target may be a relative subscript. For example: a subscript of [(*)] means that the source/target subscript is the same as the occurrence number of the screen field, a subscript of [(*+12)] means that the subscript for the source/target is the occurrence number of the screen field plus twelve (negative offsets are also possible, but not much used). Certain datanames are recognized by MAGEC as being "read-only. In those cases MAGEC generates the move to the screen for displays but does not generate a move from the screen to the source/target field for updates. Examples of such names are: CURRENT-DATE, TWA-IPL-DATE, TWA-TIME, and others.

    Row: is the screen row number on which this field begins. Screen fields may extend for multiple rows by "wrapping around" beyond the end of the line. Since MAGEC automatically defines rows 001, 022, 023, and 024, you are restricted to rows 002 thru 021. The row(and column) is initially set by MAGEC when you draw a new field onto the mask or when the automatic painter generates the initial mask. You can change it, though.

    Col: is the screen column number in which this field begins.Valid columns are 001 thru 080.

    Lgth: is the length in characters (bytes) of this screen field, not including the leading attribute or trailing stopper, if any. If you change the length you should be careful to also change the value in the screen field shown in the screen image. MAGEC edits to be sure that the field is large enough to contain the value shown.

    MSKDEF  nnn                             ................  ............. ...

    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 05 --  MSKDEF with Window Displayed

    Attr: is the six-character symbolic attribute name which specifies the field attribute code. Each position of the six-character name represents a unique attribute, only certain combinations are allowed. For example: UADRNF means Unprotected, Alphanumeric, Displayable, Regular-intensity, Non-selector-pen-detectable, modify-data-tag-ofF. When you are using MSKDEF you can press PF24 (Alt-F4, on a PC) any time to request a pop-up window of special help text which, among other things, gives the meanings and codes for each character of the attribute name.

    Clr: is the 3270 color code for this screen field. A value of 0 (or "D")indicates that you do not want extended color support for this screen field. A value of 1 thru 7 (or their letter code equivalents) indicates that you want extended color support and the initial color desired. You can press PF24 for the pop-up help which lists all the valid color codes and their meanings.

    Type: is the one-character edit type code which controls the automatic field-level editing done by MAGEC, and the Cobol definitions generated for the screen field in the mask copybook. The PF24 pop-up help text lists all the valid type codes. Refer to the "Edit Types" chapter for more detail.

    Sig: is the number of significant digits left of the decimal point. This has no meaning for alphanumeric type fields. The maximum value is 13. For date type fields this parameter is used to indicate the number of digits in the year, either 2 or 4.

    Dec: is the number of digits right of the decimal point (max. is 09). It has no meaning for alphanumeric type fields. For dates this parameter is used to control the maximum number of years old that a date may be, i.e. if you set this parameter to 03, and this is 1989, then a date of 1985 would be rejected by the automatic editing as being too old.

    Edit Table: has meaning only for edit type "T" fields. It is the three-digit (001 thru 999) lookup table number against which this field is to be edited by the automatic editing. The number used must be a valid, defined table number in MAGEC

    W-Fld: has meaning only if the edit type for this screen field is "T". It is the seven-character name of the screen field into which MAGEC is to set the description (from the lookup table entry) corresponding to the value entered into this field. For example: if this field is a type T field using table 003 (State & Province Code Table), and the operator has entered "TX" into it, the description "TEXAS" would be displayed in the field named as this field's W-Field. The name you enter into this parameter must be a valid, defined screen field name in this same mask; further, the field having that name must be specified as an edit type "W" (hence, the term W-field). The only exception is that MAGEC will accept a specification of the type "T" field as the W-field for itself. This would result in an automatic code translation, i.e the operator enters TX into a field and it is automatically converted into TEXAS in the same field on the screen.

    The W-field occurrence [( ... )] is a modifier for the W-field name. It is the occurrence number, or subscript. A value of 000 means that this W-field is not an arrayed field.

    Req: is a parameter specifying that this field is (R) required, or (O) optional. Optional fields may be left blank by the operator and will default to spaces or zero, depending on edit type.

    Loc: is the designator for the position of this field on the generated browses. A value of 0 indicates that this field does not appear on the browses. A value of 1 thru 9 indicates the relative position, left to right, of this field on the browses.

    MSKDEF  nnn                             ................  ............. ...

    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 06 --  MSKDEF with Window Displayed

    MSKDEF Functions

    Getting Help

    There are several types of online help available to you while you are using the MSKDEF function. You should take advantage of them to ease your task and reduce the need to remember codes.

    For hardcopy tables of code values, copy the appendices from your tutorials.

    For general explanation for the MSKDEF function and field specifications:

    For a pop-up window listing color codes, attribute codes, and other useful screen definition information:

    Using a Mouse

    On a PC or LAN, MAGEC supports most Mouses (or Mice, as you prefer). You do not need a Mouse to use MAGEC, the Mouse merely is a convenient way to do many commonly used functions. MAGEC can be used in Text (character) mode or in GUI (Graphical User Interface) mode and the usage of a mouse differs. In GUI mode, there is a menu bar, pull-down menus, pushbuttons, and icons to mouse-select all of the MSKDEF functions. In Text mode, there are PF key instructions on the screen. Pointing to the PF key instruction and clicking the left mouse button causes that PF key to be depressed (logically). This works much like pushbuttons and icons in GUI mode.

    Changing a Field

    The PF18 (Shift-F8, on a PC) key is used to change specifications for a screen field. To change any of the parameters for a screen field:

    Changing a Field (continued)

    To change the literal value for any field:

    To change the length of a field:

    To change the position of a screen field:

    Changing a Field (continued)

    To cause a field to be validated against a MAGEC lookup table:

    To change a field's specifications so that it appears, or does not appear, on the generated browse screens (LOC, SCN, and FND):



    Creating Arrays

    You may often have the need to create an array (repeating field) on the screen.There are several ways you can do this. The best method depends upon how much flexibility you have regarding the positioning of the fields making up the array. The simplest, and handiest, way to create an array is to define the first occurrence of the repeating fields, then specify to MSKDEF that this field repeats either vertically or horizontally on the screen. To do this:

    MSKDEF will automatically generate occurrence 2 through nn as "shadow fields" which will appear on your MSKDEF display with the "double-quote" (") character indicating the attribute positions, rather than the usual at-sign (@). Arrays created this way can be moved and altered by making changes to the first occurrence (in fact, you cannot even select other occurences to make changes to them). If you move the first occurrence of an array, all other occurrences move accordingly. This enables you to move the array as one block of fields.


    Source/Target Array

    If your screen fields making up an array (defined using the repeating field method, not the more flexible dupliated field method) are to have a database source/target specified, the source/target fields must also occur as an array using either a subscript or an index. Since you can specify the name of the source/target field only in the first occurrence of the screen fields (the other occurrences are merely shadow fields), it must include a "relative subscript" indicating that occurrence x of the database array corresponds to occurrence x of the screen array, and so forth.

    To specify a relative subscript for a database source/target field, code the dataname with a subscript of an asterisk (*) behind it. For example:

    VAC01-COMMENT (*)

    This translates into generated MOVE''s from occurrence 1 of the database to occurrence 1 of the screen, and so forth. If you wish, you can also code an offset with your relative subscript, as:

    VAC01-COMMENT (*+5)

    This would move occurrence 6 from the database to occurrence 1 on the screen, etc. You can code a negative offset (i.e. *-10) also, but we recommend that you use caution, since this would result in subscript values of zero, or even negative values.

    Moving a Field

    One way to move a field on the screen is, as described above, to simply change the row and column specifications for it. That is handy when you know the coordinates of the position where you would like the field to be moved to; however, you might often what to move a field to a spot on the screen without having to determine the coordinates first. That can be easily done using the field move key, PF21 (Alt-F1 on a PC).

    To move a field:


    Deleting a Field

    The PF19 (Shift-F9, on a PC) key is used to delete a field from a mask.

    To delete a field from a mask:

    Duplicating a Field

    The PF20 (Shift-F10, on a PC) key is used to duplicate a field.

    To duplicate (copy) one field


    Duplicating a Line

    Sometimes you will want to duplicate all the fields on one line to another line. This is an easy way of creating a repeating group of fields on the mask. When you do this, the target line must not have any fields on it before you begin, it must be blank. You use the PF4 (F4, on a PC) key to duplicate a line.

    To duplicate one line to another:


    Erasing a Line

    You may occasionally have the need to delete all fields on a given line. You can do that using the PF5 (F5, on a PC) key.

    To erase a line:


    Moving a Line

    Moving a line is equivalent to first duplicating it to another line, then erasing the original line. You can do that in one operation using the PF6 (F6, on a PC) key.

    To move a line:


    Deleting a Blank Line

    You can delete a blank line (one on which there are no detail fields) from your mask using PF13 (Shift-F3, on a PC) key. Actually, deleting a blank line consists of moving all screen fields below that line up one line on the mask. You cannot delete a line which has fields on it. If you wish to do so you must first erase the line (using PF5), then delete it.

    To delete a blank a line:

    Inserting a Blank Line

    You can insert a blank line into your mask using the PF14 (Shift-F4, on a PC) key. Actually, inserting a blank line consists of moving all screen fields which are below that line down one line on the mask.

    To insert a blank a line:

    Adding a New Field

    Adding new fields to a mask is done by drawing them directly onto the image displayed. MSKDEF scans the screen image looking for new fields you have drawn. When it finds one (or more) it automatically adds a detail field definition record (for each one) to the MAGEC repository. Then you can modify it just as you can any other field on the screen.

    There are two basic types of screen fields: variables and constants, as discussed earlier. Drawing new constants is the simpler task, so we will discuss it first.

    New constants can be drawn by simply typing their value (contents) onto the screen in the exact position where you want the new field(s) to be, preceeding each new field with a less-than symbol (<) to indicate where the field attribute is to be, and following each with either another field's attribute or a stopper (>). For example:

    would add a new field. The field length is determined by the number of characters between the attribute and the next field on the screen, or stopper. If another field, either new or pre-existing, already immediately follows the new field being drawn, there is no need to draw the stopper. The at-sign (@) or less-than symbol (<) for the following field will serve as a stopper.

    You can draw one field at a time, pressing ENTER after each one; or you can draw many fields and then press ENTER.

    To add a new variable field you do essentially the same process; however, you use either all X's or all 9's as the field's contents, as:


    The above would add two new variable fields. They would be identical to one another except that MAGEC would use a default field attribute which specified numeric-shift for the one drawn using all 9's.

    Once you have added the new variable fields you would most likely want to enter some field specifications for them. The default specifications which MAGEC will have applied are merely enough to define the fields and to prevent compiler errors. You can position the cursor to them and press PF18 to change them, just like any other field.

    In the normal mask display MSKDEF uses the at-sign (@) to denote where a field attribute will be. When you add a new constant field, the less-than symbol (<) is immediately changed to an at-sign; however, when you add a new variable field it is changed to a vertical bar (|) to distinguish it from the older fields. This helps MSKDEF to simplify your work. It will automatically home the cursor to the first vertical-bar character on the screen display. This positions the cursor ready for you to press PF18 to select that field for changes. A variable field which has never been updated is called a "virgin variable", and is not of much use until you have provided additional specifications. Once you have updated these new fields the vertical-bar will be converted into the normal at-sign.

    There is also another way you can draw new variables onto the mask. It allows MSKDEF to know a bit more about the new field so that it can apply better default specifications, further reducing your work and opportunity for errors. You can use the inclusive brackets, ({) and (}), instead of the less-than and greater-than symbols to delimit your new fields. In that case you can key a Cobol-like picture into the field, rather than just the X's or 9's. Then MSKDEF can determine such parameters as the edit type, number of significant digits left and right of the decimal point, and so forth.

    Some examples of how you might use this feature are:





    and so forth. You can mix both methods at the same time when drawing several fields onto a mask. Even when you use the more powerful method ({...}) for defining variables, you will still need to enter additional specifications for the new fields but there will be a bit less for you to do and a bit more done automatically by MAGEC. The maximum length of a numeric edit-type screen field is eighteen characters. That allows room for inserted commas, decimal point, dollar sign, and/or minus sign.

    Duplicating all Fields for a Mask

    You can copy all of the screen fields from one mask (the source mask) to another (the target mask). In order to do this, the target mask must not contain any fields before the operation is done. You can delete all fields for the target mask using the MSKDEL function described below, if necessary. To copy all fields of a mask to another mask:

    Deleting all Fields for a Mask

    You can delete all fields for a given mask using the MSKDEL function. This is especially handy when you are prototyping your screen design and using the auto-paint facility to generate a mask definition in different formats to see which comes closest to what you ultimately want. Remember, when you delete all fields for a mask, any modifications you have made are lost. It is wisest to first find the general format which you will settle upon, then make the manual screen painting changes to customize it.

    To delete all fields for a mask:

    Controlling Color

    You can control color on a field-by-field basis. You might wish to refer to the "Color 3270" chapter for more details about color codes. There are also some shortcuts you can take to control color which do not require you to update each field individually (a tedious task, somtimes).

    You can use the global change facility (SCDGBL function) to select fields within a mask which match certain criteria and to set their color attributes.

    If you use the auto-paint facility (PAINTx functions) you can have it automatically default fields to specified colors based upon whether they are protected or unprotected (attribute setting). You do this by specifying parameters on the Screen Header (SHD) before using the auto-paint facility. The parameters "Color Unprotected Fields" and "Color Protected Fields" are referenced by the auto-paint facility. You can modify the color settings using the manual screen painter, MSKDEF, after auto-paint has set them.

    Creating the Mask & Copybook

    The MSKCRE function reads all the specifications for every screen field of your mask and generates the mask initialization record and Cobol copybook needed by application programs. Its format is:

    MSKCRE mmm (mmm = desired mask number)

    You can invoke the MSKCRE function online from the MSKDEF screen. To do so:



    Restrictions & Limitations

    Number of Fields

    There is no set limit on the number of screen fields which can appear on a given mask; however, other limitations will dictate the maximum number for any particular mask.

    First, physical screen size obviously restricts the number of fields. The size of the fields is another factor. You must remember that line one and the last three lines of each mask are reserved for MAGEC's standard fields, this leaves twenty lines for your screen fields.

    Each screen field, whether it is a constant or a variable field, takes up a predictable number of bytes in the mask initialization record. To compute the number of bytes for any given field, use the formula:

    FL + 5  

    where FL = the screen field's length in bytes. The 5 is to account for space taken up by the standard order codes (SBA + address + SF + attribute). If you have specified extended color support for that screen field, then use the formula:

    FL + 11  

    This is because MAGEC requires more space to contain the extended color attributes.

    In addition, because of the way that a 3270 works, MAGEC may need to generate a "stopper" field to terminate each screen field. A stopper field is simply a dummy field (having a skip-protected attribute) which immediately follows the last byte of the screen field. These stoppers are shown as greater-than symbols (>) on the MSKDEF display. MAGEC is able to save some space by not generating a stopper behind any field which is protected and unnamed (such as a heading or prompt), nor behind any unprotected field which already has another field immediately following it A stopper takes up 5 bytes (room for its order codes).

    Finally, the MAGEC standard fields take up 337 bytes, including their order codes. If you have specified extended color support for these "system fields", then you must also add 44 bytes for additional attributes and order sequences.

    The Mask Initialization record has a 3,460-byte area in which to hold all the screen fields plus their associated 3270 order codes. A running depletion counter at the bottom of the MSKDEF display indicates the number of bytes used and remaining.

    One way of reducing the space required is to simply delete some fields. While this may seem radical, it actually is quite practical in many cases; remember, the constants are fields just like the variables. You might be able to eliminate some of the prompts. For example, by replacing individual prompts for "City Name:", "State Code:", and "ZIP Code:", with a single prompt saying: "City/State/ZIP:" (or even just "C/S/Z:". Of course, just shortening the field lengths of prompts will also save space.

    If you are running low on (or are out of) remaining space, you can often recover some space by eliminating the need for some stoppers. To do this you would move screen fields so that each unprotected field is immediately followed by another field, usually the constant prompt for the next unprotected field on the screen. For example:

    < Name:<__________> < Address:<__________>  

    could be altered to look like this to save space:

    < Name:<__________< Address:<__________>  

    For the sake of appearance, you might prefer to lengthen the prompt for the address field and to add some leading spaces in front of the literal "Address:". Remember, eliminating a stopper saves 5 bytes; you can add 2 or 3 spaces and still come out ahead. For example:

    < Name:<__________<      Address:<__________>  

    Don't bother trying to remove stoppers from behind constants. Fields which are protected, have no source/target, and are unnamed will not get a stopper generated for them at all. The greater-than symbol appears on the MSKDEF display to indicate the end of the field, but no stopper is needed.

    One last way to reduce the space requirement for your mask is to remove 7-color support for some or all of your fields.

    Field Edits

    There is a 2400-byte area provided in the Mask Initialization record to contain the edit "words" for those screen fields which are to have automatic editing done for them. These are the numeric, date, and alphanumeric editing provided in conjunction with the field Edit Type specifications. There are two sizes of edit words, 6 bytes and 15 bytes. The 6-byte edit words are for simple alphanumeric, pattern, or uppercase, with required or optional specifications. the 15-byte edit words are for table lookups, dates, and numeric edit type fields.

    The first 2 bytes of the 2400-byte area will contain the aggregate length of all the edit words for this mask. That will be followed by the edit words themselves. The first byte of each indicates the length of that edit word, either X'06' or X'0F'.

    Headings and prompts and other constants do not need any edit words.

    It is possible for you to define a screen having too many variables. That means that the edit words for all the screen variable fields will not fit in the 2400-byte area.. If that happens, MSKDEF will display an error message telling you so, as:


    To reduce the number or size of the edit words required you could delete some of the variables from the screen. You could also change some from numeric or date edit types to alphanumeric. If you fail to correct this error and persist in trying to create the mask (via the MSKCRE function) by pressing PF10 from the MSKDEF screen, you will receive the error message:


    SCD Functions

    Locate Headings

    The Screen Detail (SCD) list and change functions allow you to browse, display, and update screen field specifications. Actually, you can only update certain parameters. One of the most important of those parameters is the Locate Heading specification. This is important because this parameter cannot be updated from the MSKDEF function, only from the SCDCHG function.

    The Locate Heading specification has meaning only for those screen fields which have been selected to appear on the browse (LOC, SCN, and FND) displays as well. When you use the auto-paint facility to initially create a mask, it selects up to nine fields (limited by the 80-character display width) to appear on the browses. You can alter that selection by setting the LOC parameter for any screen fields you wish to add to or remove from the browse displays.

    The Locate Heading is the column heading which will be displayed above that field on the browse lists. If the Locate Heading is left blank the default column heading will be built using the Cobol dataname. The auto-paint facility sets the Locate Headings for the fields it selects to appear on the browses; it uses the Prompt specified in the source/target field's DIT (data item) definition in MAGEC's repository. You can alter those Locate Headings, if you wish, using the SCDCHG function.

    The 10-character key to the SCD file consists of:

    MSK number (4-characters)
    Row (3-digits)
    Column (3-digits)

    You could enter a command to update the Locate Heading for a field by keying:

    SCDCHG mmm/rrr/ccc

    where mmm = the mask number, rrr = the row, and ccc = the column. Of course, that would require you to know all that information beforehand. There is a much easier way to accomplish the same thing.

    The function SCDLST is provided to simplify finding and updating Locate Headings for screen fields. It lists the screen fields for a mask which are specified to appear on the browses, bypassing all others. SCDLST is invoked via the command:

    SCDLST mmm

    where mmm = mask number. You can then cursor-select any of the displayed items by moving the cursor down to the line on which it is listed and pressing PF4. You will be immediately presented the SCDCHG screen for the selected item.

    The Figure on the opposite page shows what the SCDLST display looks like for a hypothetical mask (mmm). This example is taken from the tutorial project's Vacation screen.

     SCDLST 600                             END OF LIST - PF5=Restart/PF7=Backward

    Msk# Row Col Name Occur Browse Heading & Position # Lgth Source/Target

    600  004 020 SEMPNUM (000) Emp# 1 0011 VAC01-EMPNUM
    600  005 020 SFIRST (000) First Name 2 0015 SIF01-FIRST-NAME
    600  006 020 SLAST-N (000) Last Name 3 0025 SIF01-LAST-NAME
    600  007 020 SDATE-H (000) Hire Date 4 0008 VAC01-DATE-HIRED
    600  008 020 STOTDUE (000) Earned Vacation  5 0010 VAC01-EARNED-VACATIO
      ++++ 30 Records Scanned, 05 Displayed so far - page 1 ++++

    Key 1 = Mask Number Press PF13 for Hardcopy
     You may position the CURSOR to an item and Press ENTER to SEE it
    (Browsing Forward) or Press PF4 to CHG it

    Figure 07 --  SCDLST Screen

    Locate Heading Screen

    The Locate Heading can be entered or modified using the SCDCHG function. The normal way of accessing the SCDCHG function is via the SCDLST function as described earlier.

    On the SCDCHG screen several of the screen field's specifications are displayed; however, only the Locate Heading can be modified since the others are all non-enterable fields. They are there merely to assist you in identifying exactly which screen field you are looking at.

    The Locate Heading is a 25-character field into which you can type a meaningful column heading for the browse screens.

    The figure on the opposite page shows a sample of the SCDCHG screen. The key (in SKEY) consists of:

    mmm = mask number

    rrr = row number

    ccc = column number

    The screen's description from the SHD definition is displayed beside the mask number in the body of the display.

    SCD Scans & Finds

    There are standard SCN and FND functions provided for the SCD data which allow you to search for screen fields (whether or not they are specifed to appear on the browses). These functions are:



    They operate just like any other MAGEC SCN and FND functions do.

    SCDCHG mmm/rrr/ccc

    M A G E C
    Locate Heading Definition

      Msk# mmm  .........................

    Row rrr

    Col ccc Length ....

    Screen Name S...... (000)

    Database Source/Target ..............................

    Locate Posn n

    Locate Heading _____________________

    Figure 08 --  Locate Heading, SCDCHG Screen

    Global Screen Detail Changes

    Certain of the parameters associated with screen field definition can be set via a global change function provided with MAGEC. The SCDGBL function allows you to specify selection criteria and replacement parameters to apply to all screen fields within a given mask which meet the selection criteria. For example, you might select all fields which have an unprotect attribute specified and set them all to the extended color Pink. Or you might select all fields on rows 015 thru 019 and set their attributes to Protected. There are numerous other scenarios you could envision using the selection and replacement parameters of SCDGBL.

    To invoke it you enter the command:

    SCDGBL mmm

    where mmm = the mask number desired. Then you enter the selection criteria and replacement parameters onto the screen and press ENTER. All of your entries are thoroughly edited and a message tells you how many screen fields matched the selection criteria and how many will be updated. There could be a difference between the two counts since the built-in validations will prevent changes which would create conflicting specifications. For example: if you told it to set all fields on row 012 to Skip-Protected attribute and some of the fields on row 012 were specified with a Numeric attribute, that would create an invalid combination (Skip-Protect and Numeric are mutually exclusive). To correct your request so that it will actually apply to all fields on row 012 you might also specify to set them to Alphanumeric, eliminating the conflict.

    You can select based upon:

    row or range of rows
    individual attributes
    required/optional flag
    edit type
    edit table number
    screen field dataname

    Your selections are connected with an and relationship. That means that if you specify to select on Color=2 (red) and edit table=003 (state code table), only those fields which are both red and validated against table 003 will match. If you specify a selection on column, only fields starting in that column will match.

    The screen automatically converts any blank entries to underscores. Selection parameters and replacement parameters which are blank (or underscore) will be ignored.

    As you can see from the figure on the opposite page, the screen field specifications you can globally (mass) change are:

    individual attributes
    edit table number

    The SCDGBL function will validate your request to be certain that you do not alter any specifications such that you create illogical combinations. Then, as it updates the records, it verifies that no conflicting specifications exist and bypasses any update which would result in a conflict.

     SCDGBL mmm
      Date MM/DD/YY  M A G E C Global Mask Field Change  Time HH:MM:SS

      S E L E C T I O N C R I T E R I A 

      Mask No. mmm
      Row 002 thru Row 021 in Col. ___  Screen Field Name _______
    Attributes: _ <===P, S, or U  _ <===A or N  _ <===D or N
      _ <===R or H  _ <===N  _ <===M or F
      Req./Opt. _  <===R or O
      Edit Type _  <===VALID EDIT TYPE
     Edit Table ___  <===001 to 255
      Color _  <===0 to 7

      R E P L A C E M E N T V A L U E S
    Attributes: _ <===P, S, or U  _ <===A or N  _ <===D or N
      _ <===R or H  _ <===N  _ <===M or F
     Edit Table ___  <===001 to 255
      Color _  <===0 to 7

    Figure 09 --  Screen Detail Global Change

    When you are using the SCDGBL function you should pay attention to the messages which are displayed on the screen. They will help you to see the effect of your requested change so that you can avoid accidents. The sequence of events when using SCDGBL is:

    If you do not press PF10 when told to do so (i.e. if you press ENTER), the update will be aborted harmlessly. Your parameters will not be overlaid on the screen so that you can modify them (if you wish) and press ENTER again to have another stab at it. It is recommended that you look at the counts of screen fields in the mask and screen fields which will match the selection criteria before pressing PF10. Then you should also look at the counts of fields updated and bypassed to be sure you did what you thought you were going to do.






    You could immediately follow the above process with the creation of the mask initialization record and copybook by entering the command:

    MSKCRE mmm

     SCDGBL mmm
      Date MM/DD/YY  M A G E C Global Mask Field Change  Time HH:MM:SS

      S E L E C T I O N C R I T E R I A 

      Mask No. mmm
      Row 002 thru Row 021 in Col. ___  Screen Field Name _______
    Attributes: _ <===P, S, or U  _ <===A or N  _ <===D or N
      _ <===R or H  _ <===N  _ <===M or F
      Req./Opt. _  <===R or O
      Edit Type _  <===VALID EDIT TYPE
     Edit Table 003  State Code Table
      Color 1  Blue
      nn User fields in MSKmmm  nn Fields match Selection Criteria

      R E P L A C E M E N T V A L U E S
    Attributes: _ <===P, S, or U  _ <===A or N  _ <===D or N
      _ <===R or H  _ <===N  _ <===M or F
     Edit Table ___  <===001 to 255
      Color 2  Red
      nn Fields were UPDATED
      nn Fields were BYPASSED due to Potential Errors caused by REPLACEMENT Values

    Figure 10 --  SCDGBL Screen Messages

    Using Auto-Paint

    As we have said earlier, you wil most often initially develop your screen masks using the automated facility, then use the manual screen painter (MSKDEF) to modify it as needed. This eliminates much effort and reduces the opportunity for errors. The best source of information on using the Auto-Paint facility is found in the Tutorials manual, in the first chapter, titled "Application Developer". We will not repeat that lesson in this chapter since you can easily review it in the Tutorial.

    Here we wish to discuss the implications of using Auto-Paint to modify a screen format after it has been initially developed. The Auto-Paint facility will not permit you to generate a screen format for a mask which already has a format defined. In other words, if there are any screen field definitions for a given mask number, you will not be allowed to Auto-Paint that mask. This is obviously designed to prevent your accidentally overlaying an existing screen format:

    In order to re-generate a mask using Auto-Paint, you must first delete all the screen field definitions for that mask. This is done using the MSKDEL function (a variation of the MSKDEF function), as:

    MSKDEL mmm

    where mmm = the mask number desired.

    MSKDEL will first display the screen format to you, press ENTER again to confirm the delete. Once the mask has been deleted (all screen field definitions, that is), you will be presented the Development Process Selection (see Figure 04) screen from which you can press PF8, PF7, or PF3 to choose the method you wish to employ to re-create the mask: Pressing PF8 or PF7 will take you back to the semi-automated or fully-automated processes.


    All of your specifications and selections from your original, or last prior, execution of the Auto-Paint sequence have been saved and will be presented to you. This eliminates the need for you to re-do all your work. You can, however, modify any of these specifications and selections, if you wish. This includes the list of joined elements, list of selected data items (fields), screen format option, and logical join coding.

    You should recognize that doing the above procedure replaces the entire old mask format with a new one. Any modifications you have made to the old format will be lost. Sometimes this is desirable, sometimes it is inconsequential, and sometimes it is undesirable.

    If losing all your modifications is not desirable, you should consider using MSKDEF to alter the mask format, rather than deleting and re-creating it. Another option you might find handy is the procedure of copying part or all of the screen field definitions from the old mask to a "dummy" temporary mask number to save them so that you can copy them back after re-generating a new mask format. You can use the MSKDUP function to copy all screen fields, or the line duplicate or field duplicate facilities of MSKDEF to copy portions of the mask.

    Graphical User Interface


    As of version 3.0 of MAGEC, you can dynamically add graphical objects to your screen from your Cobol MMP. Doing so does not preclude you from migrating that MMP to another environment in which GUI is not supported (i.e.: 3270 mainframe system) since MAGEC automatically tests whether you are executing in a graphical environment or not and simply ignores the GUI requests. To better explain the use of GUI objects we will divide this discussion into three parts: 1) a description of the GUI objects and operations involved, 2) a detailed description of the GUITOOL request area which is included into the MMP automatically, and 3) examples of the coding to create or modify each of the objects. There are three basic types of GUI objects:

    The nomenclature used by MAGEC to define GUI objects is consistent with industry standards; however, since the standard names vary slightly from one environment to another, we have taken the liberty of coining a few new names which we believe better describe the objects in question and which avoid cross-platform ambiguities.

    Text Field

    Text fields are created using the standard screen painting processes, not by calling GUITOOL. GUITOOL can, however, be used to move a text field to a different position on the screen, or to convert it into another type of field, such as Radio Buttons, etc.


    A Toggle is a binary (on / off) field which will toggle its value each time it is clicked with a mouse. For example, you could take a (text) screen field in which the operator would normally type either a Y or N and convert it into a single Radio Button icon or Checkbox icon which the operator can set on and off. Your program will receive either a Y or N in the text screen field as if that had been typed into the screen. A Toggle is different from the Radio Button or Checkbox objects discussed below in that a Toggle has two values associated with it, one for the "on" state, and one for the "off" state; and also because there is only one button displayed on the screen as opposed to an array of buttons.

    Radio Buttons

    Radio Buttons are an array (vertical or horizontal) of round buttons on the screen each of which has one value associated with its "on" state, but no value associated with its "off" state. All of the buttons are associated with the same one text screen field and only one button can be "on" at any time. For example, a text field into which the operator is to type a code indicating "married", "single", "divorced", or "unknown" could be converted into an array of four buttons. When any one of the buttons is clicked with the mouse it will be set "on" and all others will be set "off". For each button you would have provided the caption (i.e.: "married") plus the value your program is expecting (i.e.: "M"). The screen field will have the selected value filled into it as if the operator had typed it into the screen. Radio Buttons are one type of Selection Boxes, Checkboxes are the other type. MAGEC provides a proforma for creating Selection Boxes (either variation) named: GUITOOL/SELECTBX.


    Checkboxes are exactly the same as Radio Buttons except for the appearance of the screen icons. Rather than being round buttons, they are square boxes which show an "X" or a check mark within them when they are "on" and are empty when they are "off". Checkboxes are one type of Selection Boxes, Radio Buttons are the other. MAGEC provides a proforma for creating Selection Boxes (either variation) named: GUITOOL/SELECTBX.

    Selection Boxes

    Thiis is a generic term used to describe either Radio Buttons or Checkboxes described above. MAGEC provides a proforma for creating Selection Boxes (either variation) named: GUITOOL/SELECTBX.


    A Listbox is a field on the screen which contains a list of values from which the operator can select one. The selected one will be highlighted. The list may be longer than the dimensions of the field on the screen and will then be automatically made scrollable. Scrolling is accomplished using the up and down arrows on the slide bar which is affixed to the right edge of the Listbox. For example: you could convert a text screen field into which the operator is to type a title ("Mr.", Ms.", "Mrs.", "Dr.", etc.) into a Listbox which lists all the valid titles. When the operator selects one, it will be filled into the text screen field as if it had been typed into the screen. MAGEC provides a proforma for creating Listboxes named: GUITOOL/LISTBOX.

    Combo Box

    A Combo Box is like a combination of a text field and a Listbox. The field initially appears on the screen as an ordinary text field into which the operator can type, if desired. It also has a square button containing a down arrow immediately to the right of the text field. If the operator mouse clicks this down arrow button, a list of values appears extending either down or up from the text field, depending on how close to the bottom edge of the screen the field is. The operator can then select an item from the list and it will be filled into the text field as if it had been typed. MAGEC provides a proforma for creating Combo Boxes named: GUITOOL/COMBOBOX.

    API Call

    An API (Application Program Interface) Call is a request to invoke another application asynchronously. For example, you could have your MMP invoke your word processor to print, edit, or create a letter. You could have had your MMP create the base letter, write it to a sequential file, then pass it to the word processor for further massaging and printing. MAGEC provides a proforma for issuing API Calls named: GUITOOL/APICALL.


    A Pushbutton is a rectangular, three dimensional (in appearance) button on the screen which is associated with a PF key. Mouse clicking on the pushbutton is exactly equivalent to pressing that PF key and the two are indistinguishable to your program. A Pushbutton has a text caption displayed on it. If your program requests that the Pushbutton ignore the mouse, the caption will be displayed in grey, rather than black letters, this is called "greying out" the Pushbutton. You can dynamically alter the Pushbutton from your MMP, greying and re-activating it at will. MAGEC provides a proforma for creating Pushbuttons named: GUITOOL/PUTPB.


    A Bitmap is a graphical picture , in the form of a .BMP file, which you can display on your screen. A Bitmap may be made mouse sensitive or not, as you desire. If you make a Bitmap mouse sensitive, you can specify a second .BMP file to be displayed while the Bitmap is being "pushed". You also specify a PF key which will be sent to your program when this Bitmap is mouse clicked. This enables you to create icons which behave like Pushbuttons, but which contain a picture, rather than just text. MAGEC provides a proforma for creating Bitmaps named: GUITOOL/PUTBMP.

    Field ID

    The Field ID is a numeric value which uniquely identifies any text field or GUI object on your screen. If you know a field's (or object's) position on the screen, either as a row/column or an absolute screen position (as in the -POSN value from the MAGEC Mask copybook) you can get the Field ID. MAGEC provides a proforma for getting the Field ID named: GUITOOL/GETID

    Modifying Objects

    You can modify many of the attributes of a screen field or object if you know its Field ID. Among the things you can modify are: the colors, mouse sensitivity, PF key association, position on screen, caption for Pushbutton, .BMP file names for Bitmaps, and so forth. You might find it useful to get the fields specifications reported back to your program before modifying it. If you precede the MODIFY with a GETID or GETSPECS request, they will be filled into the GUITOOL request area for you. MAGEC provides a proforma for modifying an object named: GUITOOL/MODIFY.

    Deleting Objects

    If you know an object's Field ID you can delete it from the screen. MAGEC provides a proforma for deleting objects named: GUITOOL/DELETE

    Field Specs

    If you know the Field ID you can have GUITOOL report back all of the field specifications. MAGEC provides a proforma for getting field specifications named: GUITOOL/GETSPECS.

    GUITOOL Request Area

    Below is the definition of the GUITOOL-REQUEST area which is included into your MMP. Within the listing of the request area is a discussion of the fields within the request area and how you use them to create and modify GUI objects dynamically.

           01  GUITOOL-REQUEST                 PIC X(256) VALUE SPACE.


              03 GUITOOL-ID                PIC X(1).

             88 GUITOOL-BMP-CMD                VALUE X'10'.

              88 GUITOOL-PB-CMD                 VALUE X'11'.

             88 GUITOOL-MODIFY-CMD        VALUE X'12'.

             88 GUITOOL-ANIMATE-CMD        VALUE X'13'.

             88 GUITOOL-DELETE-CMD        VALUE X'20'.

             88 GUITOOL-GET-ID-CMD                VALUE X'21'.

             88 GUITOOL-SPECS-CMD                VALUE X'22'.

             88 GUITOOL-API-CMD                VALUE X'23'.

             88 GUITOOL-COMBOBOX-CMD        VALUE X'24'.

             88 GUITOOL-LISTBOX-CMD        VALUE X'25'.

             88 GUITOOL-SELECTION-BOX-CMD         VALUE X'26'.

             88 GUITOOL-TOGGLE-CMD        VALUE X'27'.

             03 GUITOOL-RET-CODE                PIC X(02).

             88 GUITOOL-OK                VALUE ' '.

             88 GUITOOL-PANEL-NOT-FOUND        VALUE '14'.

             88 GUITOOL-FIELD-NOT-FOUND        VALUE '15'.

             88 GUITOOL-INVALID-FIELD        VALUE '16'.

             88 GUITOOL-INVALID-ENTRIES        VALUE '17'.

             03 GUITOOL-ERROR-MSG                 PIC X(30).

             03 GUITOOL-FIELD-TYPE                PIC X.

             88 GUITOOL-PUSHBUTTON        VALUE 'P'.

             88 GUITOOL-ICON                VALUE 'I'.

             88 GUITOOL-LISTBOX                VALUE 'L'.

             88 GUITOOL-COMBOBOX                VALUE 'O'.

             88 GUITOOL-SCROLLBAR                VALUE 'S'.

             88 GUITOOL-RADIOBUTTON        VALUE 'R'.

             88 GUITOOL-CHECKBOX                VALUE 'C'.

              88 GUITOOL-TEXT                VALUE 'T'.

             03 GUITOOL-MOUSE-ENABLE        PIC X(1).

             88 GUITOOL-MOUSE-SENSITIVE        VALUE 'Y' ' '.

             88 GUITOOL-MOUSE-IGNORE        VALUE 'N'.

             03 GUITOOL-AID-CODE                PIC X(1).

             88 GUITOOL-ENTER                VALUE QUOTE.

             88 GUITOOL-PF1                VALUE '1'.

             88 GUITOOL-PF2                VALUE '2'.

             88 GUITOOL-PF3                VALUE '3'.

             88 GUITOOL-PF4                VALUE '4'.

             88 GUITOOL-PF5                VALUE '5'.

             88 GUITOOL-PF6                VALUE '6'.

             88 GUITOOL-PF7                VALUE '7'.

             88 GUITOOL-PF8                VALUE '8'.

             88 GUITOOL-PF9                VALUE '9'.

             88 GUITOOL-PF10                VALUE ':'.

             88 GUITOOL-PF11                VALUE '#'.

             88 GUITOOL-PF12                VALUE '@'.

             88 GUITOOL-PF13                VALUE 'A'.

             88 GUITOOL-PF14                VALUE 'B'.

             88 GUITOOL-PF15                VALUE 'C'.

             88 GUITOOL-PF16                VALUE 'D'.

             88 GUITOOL-PF17                VALUE 'E'.

             88 GUITOOL-PF18                VALUE 'F'.

             88 GUITOOL-PF19                VALUE 'G'.

             88 GUITOOL-PF20                VALUE 'H'.

             88 GUITOOL-PF21                VALUE 'I'.

             88 GUITOOL-PF22                VALUE 'á›á'.

             88 GUITOOL-PF23                VALUE '.'.

             88 GUITOOL-PF24                VALUE ''.

             88 GUITOOL-PA1                VALUE '%'.

             88 GUITOOL-PA2                VALUE ''.

             88 GUITOOL-PA3                VALUE ','.

             88 GUITOOL-CLR                VALUE '_'.

             88 GUITOOL-SEL-PEN                VALUE '='.

             88 GUITOOL-TST-REQ                VALUE '0'.

             03 GUITOOL-UOM                 PIC X(1).

             88 GUITOOL-CHARACTER-SCALE        VALUE 'C' ' '.

             88 GUITOOL-PIXEL-SCALE        VALUE 'P'.

             88 GUITOOL-POSN-SCALE        VALUE 'S'.

             03 GUITOOL-FIELD-ID                PIC S9(4) COMP.

             03 GUITOOL-WIDTH                PIC S9(4) COMP.

             03 GUITOOL-HEIGHT                PIC S9(4) COMP.

             03 GUITOOL-TOP-LEFT-ROW        PIC S9(4) COMP.


                                    PIC S9(4) COMP.

             03 GUITOOL-TOP-LEFT-COL        PIC S9(4) COMP.

             03 GUITOOL-NR-ENTRIES                PIC S9(4) COMP.

             03 GUITOOL-TBL-ITEM-WIDTH        PIC S9(4) COMP.

             03 GUITOOL-FG-COLOR                PIC X.

             88 GUITOOL-FG-BLACK                VALUE '0'.

             88 GUITOOL-FG-BLUE                VALUE '1'.

             88 GUITOOL-FG-GREEN                VALUE '2'.

             88 GUITOOL-FG-CYAN                VALUE '3'.

             88 GUITOOL-FG-RED                 VALUE '4'.

             88 GUITOOL-FG-MAGENTA        VALUE '5'.

             88 GUITOOL-FG-BROWN                VALUE '6'.

             88 GUITOOL-FG-WHITE                VALUE '7'.

             88 GUITOOL-FG-BRT-BLACK        VALUE '8'.

             88 GUITOOL-FG-BRT-BLUE        VALUE '9'.

             88 GUITOOL-FG-BRT-GREEN        VALUE 'A'.

             88 GUITOOL-FG-BRT-CYAN        VALUE 'B'.

             88 GUITOOL-FG-BRT-RED        VALUE 'C'.

             88 GUITOOL-FG-BRT-MAGENTA        VALUE 'D'.

             88 GUITOOL-FG-BRT-YELLOW        VALUE 'E'.

             88 GUITOOL-FG-BRT-WHITE        VALUE 'F'.

             03 GUITOOL-BG-COLOR                 PIC X.

             88 GUITOOL-BG-BLACK                VALUE '0'.

             88 GUITOOL-BG-BLUE                VALUE '1'.

             88 GUITOOL-BG-GREEN                VALUE '2'.

             88 GUITOOL-BG-CYAN                VALUE '3'.

             88 GUITOOL-BG-RED                 VALUE '4'.

             88 GUITOOL-BG-MAGENTA        VALUE '5'.

             88 GUITOOL-BG-BROWN                VALUE '6'.

             88 GUITOOL-BG-WHITE                VALUE '7'.

             88 GUITOOL-BG-BRT-BLACK        VALUE '8'.

             88 GUITOOL-BG-BRT-BLUE        VALUE '9'.

             88 GUITOOL-BG-BRT-GREEN        VALUE 'A'.

             88 GUITOOL-BG-BRT-CYAN        VALUE 'B'.

             88 GUITOOL-BG-BRT-RED        VALUE 'C'.

             88 GUITOOL-BG-BRT-MAGENTA        VALUE 'D'.

             88 GUITOOL-BG-BRT-YELLOW        VALUE 'E'.

             88 GUITOOL-BG-BRT-WHITE        VALUE 'F'.

             03 GUITOOL-BOR-TYPE                PIC X.

             88 GUITOOL-3D-BOR                 VALUE '3'.

             88 GUITOOL-LINE                VALUE 'L'.

             03 GUITOOL-CAPTION-DELIM        PIC X.

             88 GUITOOL-CAP-DEFAULT        VALUE '@'.

             03 GUITOOL-VALUE-DELIM                PIC X.

             88 GUITOOL-VAL-DEFAULT        VALUE '='.

             03 GUITOOL-TBL-ADDR                PIC X(4).

             03 GUITOOL-BMP-AREA.

             05 GUITOOL-FILE-1                PIC X(12).

             05 GUITOOL-FILE-2                PIC X(12).

             05 FILLER                PIC X(58).


             05 GUITOOL-PB-LITERAL                PIC X(40).


             05 GUITOOL-API-LITERAL.

                    07 GUITOOL-API-BYTE OCCURS 82 TIMES PIC X.


                    07 GUITOOL-API-PROGRAM        PIC X(9).

                    07 GUITOOL-API-PARM        PIC X(73).


             05 GUITOOL-SB-ORIENTATION        PIC X.

              88 GUITOOL-SB-HORIZONTAL        VALUE 'H'.

              88 GUITOOL-SB-VERTICAL        VALUE 'V'.


             05 GUITOOL-ANIM-FILE OCCURS 10 TIMES PIC X(12).

             05 GUITOOL-FROM-ROW        PIC S9(04) COMP.

             05 GUITOOL-FROM-COL                PIC S9(04) COMP.

             05 GUITOOL-TO-ROW                PIC S9(04) COMP.

             05 GUITOOL-TO-COL                PIC S9(04) COMP.

             05 GUITOOL-REMOVE-AT-END        PIC X(01).


    GUI Proformas

    Below are the proformas provided with MAGEC to help you to easily add GUITOOL requests to your MMP's. You can access these proformas just as you do any other MAGEC proforma in the normal develoment process.


    * *** note: field-id must be set to indicate which text field

    * ***        is to be converted into a toggle switch

             CALL 'MAGECSET' USING GUITOOL-TOG-TBL-ADDR cap-val1-val2

    *         i.e.: " Q Approved=Y=N"



    *         SET GUITOOL-FG-white                 TO TRUE

    *         SET GUITOOL-BG-black                 TO TRUE

    *         SET GUITOOL-3d-bor -or- GUITOOL-line         TO TRUE

    *         SET GUITOOL-radiobutton -or- GUITOOL-checkbox TO TRUE



    * *** Note: field-id must be set to indicate which text field

    * ***        is to be converted into a selection box

    *         CALL 'MAGECSET' USING GUITOOL-SB-TBL-ADDR tbl-of-values

    * *** i.e.: " Q Texas=TX Q New York=NY Q Wyoming=WY..."



    *         SET GUITOOL-FG-white                 TO TRUE

    *         SET GUITOOL-BG-black                 TO TRUE

    *         SET GUITOOL-3d-bor -or- GUITOOL-line TO TRUE

    *         MOVE nn                TO GUITOOL-SB-ENTRIES

    *         SET GUITOOL-SB-horizontal -or- GUITOOL-SB-vertical TO TRUE

    *         SET GUITOOL-radiobutton -or- GUITOOL-checkbox TO TRUE



    * *** note: field-id must be set to indicate which text field

    * ***        is to be converted into list box

    *         MOVE ww                TO GUITOOL-LISTBOX-WIDTH

    *         MOVE nn                TO GUITOOL-LISTBOX-ENTRIES



    *         SET GUITOOL-FG-white                 TO TRUE

    *         SET GUITOOL-BG-black                 TO TRUE

    *         SET GUITOOL-3d-bor -or- GUITOOL-line TO TRUE

    *         MOVE nn        TO GUITOOL-TBL-ITEM-WIDTH.


    *         i.e.: "Doctor Lawyer Indian Chief"



    * *** note: field-id must be set to indicate which text field

    * ***        is to be converted into combo box

    *         MOVE ww                TO GUITOOL-COMBOBOX-WIDTH

    *         MOVE nn                TO GUITOOL-COMBOBOX-ENTRIES



    *         SET GUITOOL-FG-white                 TO TRUE

    *         SET GUITOOL-BG-black                 TO TRUE

    *         SET GUITOOL-3d-bor -or- GUITOOL-line TO TRUE

    *         MOVE nn                TO GUITOOL-TBL-ITEM-WIDTH.


    *                 table-of-values in working storage

    *         i.e.: "Doctor Lawyer Indian Chief"



             MOVE field-id                TO GUITOOL-FIELD-ID.





    *         MOVE quote                TO GUITOOL-AID-CODE



    * *** set any parameters you wish to alter, leave others 0 or blank

    *         MOVE 00                TO GUITOOL-TOP-LEFT-ROW

    *         MOVE 00                TO GUITOOL-TOP-LEFT-COL

    *         MOVE 00                TO GUITOOL-WIDTH

    *         MOVE 00                TO GUITOOL-HEIGHT

    *         MOVE space                TO GUITOOL-PB-LITERAL

    * or ***** MOVE space                        TO GUITOOL-FILE-1

    * or ***** MOVE space                        TO GUITOOL-FILE-2





    *         MOVE rr                        TO GUITOOL-TOP-LEFT-ROW

    *         MOVE cc                TO GUITOOL-TOP-LEFT-COL

    * or         SET GUITOOL-POSN-SCALE        TO TRUE

    *         MOVE Sfield-POSN                TO GUITOOL-POSN

             PERFORM GTA400-GET-FIELD-ID        THRU GTA499-EXIT.




    *         MOVE quote                TO GUITOOL-AID-CODE



    *         MOVE rr                        TO GUITOOL-TOP-LEFT-ROW

    *         MOVE cc                TO GUITOOL-TOP-LEFT-COL

    *         MOVE 'xxxxxxxxxxxx'                TO GUITOOL-PB-LITERAL

    * *** width and height will default if left 00

    *         MOVE 00                TO GUITOOL-WIDTH

    *         MOVE 00                TO GUITOOL-HEIGHT





    *         MOVE quote                TO GUITOOL-AID-CODE



    *         MOVE rr                        TO GUITOOL-TOP-LEFT-ROW

    *         MOVE cc                TO GUITOOL-TOP-LEFT-COL

    *         MOVE 'xxxxxxxx.BMP'                TO GUITOOL-FILE-1

    *         MOVE 'xxxxxxxx.BMP'                TO GUITOOL-FILE-2

    *         MOVE ww                TO GUITOOL-WIDTH

    *         MOVE hh                TO GUITOOL-HEIGHT



    * *** note: field-id must be set to indicate which object

    * ***        is to be deleted



    * *** note: one, two, or three push buttons can be added to a panel

    * ***        GUITOOL-RET-CODE will contain '01' for button-1

    * ***        '02' for button-2, or '03' for button-3 when a pushbutton is

    * ***        clicked with the mouse. The default panel colors are bright-blue

    * ***        on white

    *         MOVE Title of Dialog Box                TO GUITOOL-DIALOG-TITLE

    *         MOVE first line of dialog                TO GUITOOL-DIALOG-LINE (1)

    *         MOVE second line of dialog                TO GUITOOL-DIALOG-LINE (2)

    * ***** note: up to 5 lines are allowed

    *         MOVE caption-1                TO GUITOOL-PUSH-BUTTON-1

    *         MOVE caption-2                TO GUITOOL-PUSH-BUTTON-2

    *         MOVE caption-3                TO GUITOOL-PUSH-BUTTON-3



    *         MOVE programname                 TO GUITOOL-API-PROGRAM

    *         MOVE parameters                 TO GUITOOL-API-PARM



    * *** note: Spawn-and-Wait is like a simple API call except that your task is placed into

    * *** a wait state until the spawned task completes

    *         MOVE programname                 TO GUITOOL-API-PROGRAM

    *         MOVE parameters                 TO GUITOOL-API-PARM


    * *** note: parm-area is the dataname of an area of storage in which you can place

    * *** data to be passed to the spawned task, and which it can place data into to

    * *** return to you. It is ignored by GUITOOL unless GUITOOL-API-PARM is blank.


    Using GUITOOL

    In order to successfully use the GUITOOL subroutine you should first understand a few of the concepts on which it is based.

    First, for each time it is called GUITOOL returns as much information as possible, including any default values it has assumed. For example, you can identify a field on the screen using its row/column coordinates or its absolute position (-POSN). In either case GUITOOL returns the row, column, and position values to you. A simple calculation is used to convert from one to the other, but since GUITOOL always returns both, you do not need to do the calculation. The field ID (an internally-generated unique identification number) is also a way to identify any field or object--it is also returned to you .When you PERFORM the GET-FIELD-ID routine you receive all of the field's specifications along with the field ID. When you PERFORM the PUT-PUSHBUTTON routine the field ID and width and height (even if they were defaulted) are returned. This is done to enable you to do as few steps as possible to accomplish any task.

    Second, MAGEC endeavors to preserve the portability of your applications across all supported platforms; therefore, it does not permit adding new data entry fields to a GUI panel which are not present on the text screen to which it corresponds.

    When you develop an online application with MAGEC, it first creates the text screen mask (on the MSK file), then it automatically generates the GUI panel from the text screen. You are offered choices from several options which will affect the appearance of the GUI panel at the time it is generated; but none of the choices can modify the text data input. This is because all of the data input into a GUI panel is mapped into the text screen mask to be passed into your MMP. If you added a new text entry field into a panel there would be no field on the screen mask in which to map it.

    You can, however, modify the appearance of a text field. You can convert it into a list box, combo box, selection box of either checkboxes or radio buttons, or a toggle consisting of either a radio button or a checkbox. All of these GUI objects are merely alternate ways of entering a text value which will be mapped into the original text field on the screen mask and passed to your MMP. This way your MMP works exactly the same ragardless whether you are executing in GUI mode or text mode.

    It is possible to delete a text field from the GUI panel. In that case the effect would be the same as if, in the text screen mask, you had altered the field's attribute to non-display and protected. The operator can neither see nor modify the field, but it still exists to your MMP and to the text screen mask.

    You can create non-text fields or objects on your GUI panel, and you can make them mouse-sensitive. Non-text objects include bitmaps and pushbuttons. If you make them mouse-sensitive you must tell GUITOOL which PF key you want to transmit into your MMP when that object is clicked. You can turn the mouse sensing on and off at will. For a pushbutton, when mouse sensing is off it will be "greyed out" on the panel. If you wish to create the same effect for a bitmap you will have to change the .BMP file used when it is mouse-sensitive and not mouse-sensitive.

    Third, GUITOOL is a dynamic facility which makes temporary changes to the panel. When your GUI panel is created it is stored on a file. When your MMP initially uses the panel it is read from the file into memory. GUITOOL modifies the image in memory, but not the image on the file. If your application switches screens, you will also switch GUI panels automatically. This will flush the image of the old panel from memory and all your temporary changes along with it. There is a GUI "screen painter" which allows you to make permanent changes to your panels. It abides by the same rules since it also uses the GUITOOL subroutine, but it also gives you the option of saving your changes to the panel file.

    You should give some thought as to when and where (in you program logic) you wish to do certain GUI operations. Some types of operations should be done only once when the panel is first sent, others should be done every transaction. For instance, If you wished to convert a text field to a combo box you only need to do that one time. Subsequent transactions using this same panel should bypass that operation. If you wanted to display a bitmap picture of an inventory item determined by the item number on the screen, you would need to do that every transaction since the item number could change at any time.

    If you do your GUITOOL calls from %SNDSCRN the same rule applies as when referencing fields on your text screen in %SNDSCRN: you must first verify that the Mask Number is THIS-PGMS-MSK, since %SNDSCRN is executed for both maintenance and browse functions. It is both possible and legal to add bitmaps or pushbuttons to the browse screens, but you should determine which screen is active before modifying it. Note that the GUI panel ID is the same as the text screen Mask ID. Mask 600 corresponds to GUI Panel 600.

    If you wish to do a GUI operation only once when the panel is initially invoked and bypass the operation thereafter, you could establish a switch in %DATADEF and set it when you have successfully done the operation, thereafter the switch would indicate that you should bypass it. Be sure to reset the switch any time you are in a browse transaction since that uses a different Mask and panel flushing the changes from memory. Possible coding for this logic in %SNDSCRN would be:







    ...make alterations to panel...




    To protect against random data in memory from accidentally containing a Y in your switch, you should also put code into %PREINIT as:



    For changes you want to make to the maintenance panel every transaction, such as displaying the item bitmap we discussed above, from %SNDSCRN you should code:


    ...send the bitmap to the panel....

    Fourth, you should check the return code from GUITOOL to determine whether your operation worked successfully. Because of the nature of these operations it is usually not a fatal error for them to fail since your MMP will still work correctly. Only the panel appearance and behavior will be changed. You could, however, make chages to a panel which result in more restrictive limits on data entry than were in effect on the text screen. For example, a state/province code field might permit the entry of any of the U.S. state codes plus any Canadian province code. Your MMP could convert that text field into a list box or selection box which presents only the Canadian province codes to choose from. That would, in effect, restrict the entry into that field more tightly than the text screen would have. If the operation to convert the screen field into a GUI object were to fail, the original restriction would still apply allowing U.S. state codes to be entered.

    As a convenience to you, GUITOOL returns a description of the reason for a failure along with the 2-digit error code. You might find it useful to display the error description by moving it into SERRMSG to aid you in debugging. For example:





    Fifth, API calls are subject to the rules set forth by Windows. You can call a Windows executable program (.EXE), or you can execute a DOS program or batch process (.BAT) via a Windows .PIF file. In any case, the .EXE or .PIF file must be in the search path to be found. As a rule, you should place any .PIF's in your %LANDRV%\MAGMF directory, or in the \WINDOWS directory to be sure they are found by Windows. When you are doing an API call to a Windows .EXE file, it is not necessary (but is allowable) to specify the .EXE extension, i.e.: WRITE.EXE. When calling a .PIF, you must specify the .PIF extension. i.e. MMPCREAT.PIF.

    GUI Screen Painter

    If you do your development using the GUI version or MAGEC, you can customize your GUI panels using the online GUI Screen Painter, which enables you to add bitmaps and pushbuttons, convert text fields into combo boxes or list boxes or radio buttons, and to alter the appearance and location of text fields. Essentially, you can do most of the same things using the GUI Screen Painter as you can do using the GUITOOL subroutine. You should give some thought to when to use one facility versus the other.

    The GUI Screen Painter should be used to make static changes to your panel. Any changes made this way will be stored with the actual panel definition and are therefore more efficient at execution time for your application. Suppose that you wished to present your company logo on your screen at a fixed position, say in the bottom right corner. This could be done using GUITOOL, but it would be better done using the GUI Screen Painter since it would require no coding in your program and would create less run-time overhead. Suppose again, that you wish to display a diagram of the part based upon the part number entered, or displayed, on the screen. This must be done using GUITOOL since it is a dynamic object, the picture (bitmap) must change as the part number changes.

    For another comparison, imagine that you have a screen on which there is a 2-character state/province code (i.e TX=Texas, BC=British Colombia, etc.). Now imagine that, for this particular screen, you wish to limit the entries into this field to only those states and provinces bordering one of the Great Lakes. You could accomplish this by converting the text field into a combo box, list box, or radio buttons with only the acceptable codes represented. This could be done either using GUITOOL or the GUI Screen Painter. Again, the static changes made using the GUI Screen Painter would be less overhead and less work for you, the developer. Now suppose that the list of valid codes changes based upon, say a salesman's territory number. This must be done using the GUITOOL subroutine since it must be dynamically set based upon the data being presented.

    Online interactive help tutorials are available in MAGEC for the GUI Screen Painter by simply selecting Help, Tutorials from the menu bar, or by clicking the Help button an any developer screen.