---
title: "msk_main"
original_file: "msk_main"
generated: "2026-09-11 00:50:40"
---

**
← Back
Chapter 07
# Screen Mask Definition Manual
## 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 chapter.
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.
**SCOMP**L 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.
```
** ______ _______________________________ ........................................
SFUNCT  SKEY  SCOMPL 
 
SERRMSG
................................................................................
................................................................................
................................................................................**
```
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:
use auto-paint to generate the basic screen mask
use the online function MSKDEF to customize the generated screen mask, if desired
use the online function MSKCRE (or MSKCREAT, in batch) to create the mask and copybook
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](/DOC/app_main.htm).)
**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 who 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"](/DOC/util_main.htm) 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:
@Emp#@ _________> 
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
**Note:** If there are currently no screen fields defined for the mask number specified, MSKDEF presents a selection screen asking you to choose which level of automated assistance you desire. In this Screen Painting section of the "Programmer's Reference" manual we will concern ourselves primarily with the "manual" screen painting operations which you can select by pressing PF3 when the above selection screen appears.
## 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/Targe****t:** 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  ................ ............. ...
@
MAGEC SCREEN PAINTER  (PFKEYS) --FIELD: 18=CHG 19=DEL 20=DUP 21=MOVE
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.
**Typ****e:** 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"](/DOC/magref_main.htm#MAGREF002001) reference table for a complete list.
**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  ................ ............. ...
@
MAGEC SCREEN PAINTER  (PFKEYS) --FIELD: 18=CHG 19=DEL 20=DUP 21=MOVE
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:
press PF1 (F1, on a PC)
For a pop-up window listing color codes, attribute codes, and other useful screen definition information:
press PF24 (Alt-F4, on a PC)
## 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:
position the cursor onto the desired field (anywhere in the field, but not on the "stopper")
press PF18 (window appears with all of that field's specifications)
overtype any of the specifications you wish to change
press ENTER (message in SCOMPL tells you either that your change was completed or gives you an error message)
## Changing a Field (continued)
To change the literal value for any field:
overtype the literal value directly onto the screen image (if you move the stopper, you should also change the field's length specification accordingly see below)
position the cursor onto the desired field (anywhere in the field, but not on the "stopper")
press PF18 (window appears with all of that field's specifications)
change any specifications, if desired
press ENTER (message in SCOMPL tells you either that your change was completed or gives you an error message)
To change the length of a field:
overtype the literal value, be sure to type a greater-than symbol (>) to indicate the new position where a "stopper" should be--remove the old stopper by typing a space or other character over the old greater-than symbol.
position the cursor onto the desired field (anywhere in the field, but not on the "stopper")
press PF18 (window appears with all of that field's specifications)
alter the length specification in the window
press ENTER (message in SCOMPL tells you either that your change was completed or gives you an error message, screen image is updated to show current status of field)
To change the position of a screen field:
position the cursor onto the desired field (anywhere in the field, but not on the "stopper")
press PF18 (window appears with all of that field's specifications)
overtype the row and/or column
press ENTER (message in SCOMPL tells you either that your change was completed or gives you an error message, screen image is updated showing field in its current position)
## Changing a Field (continued)
To cause a field to be validated against a MAGEC lookup table:
position the cursor onto the desired field (anywhere in the field, but not on the "stopper")
press PF18 (window appears with that field's specifications)
change the Type specification to "T"
change the Edit Table specification to the desired table number (must be a valid number use TOCLOC 1 for list of valid table numbers)
press ENTER (message in SCOMPL tells you either that your change was completed or gives you an error message)
To change a field's specifications so that it appears, or does not appear, on the generated browse screens (LOC, SCN, and FND):
position the cursor onto the desired field (anywhere in the field, but not on the "stopper")
press PF18 (window appears with all of that field's specifications)
overtype the LOC parameter (in bottom-right corner of window)
press ENTER (message in SCOMPL tells you either that your change was completed or gives you an error message)
**Note:** If you wish to alter the heading for a field which will be displayed on the browse screens you must use the SCDCHG function to do so. It is discussed later.
**Note:** You can do all of the above operations at one time, if you wish. They are discussed individually merely to simplify explanation.
## 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:
select the field for change using PF18
in the pop-up window of field specifications, type either "*nn" or #nn" into the occurrence (3-character parameter within parentheses immediately following SCRN FLD NM. The "nn" indicates how many times this field is to repeat, the asterisk (*) indicates vertical, the pound sign (#) indicates horizontal.
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.
**Note:** Also read the topic [Duplicating a Field](#msk007010) later in this chapter. It describes a less handy, but more flexible, way to define an array on the screen. The repeating field method described above requires that your array consist of fields which align in a single vertical column, or horizontal row (which may continue across more than one line of the screen). If your array must be irregularly positioned around the screen, the repeating field method will not work.
## 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:
position the cursor onto the desired field (anywhere in the field, but not on the "stopper")
press PF21 (window appears with that field's coordinates)
press ENTER to remove pop-up window
position the cursor to the first character position you wish the field to be moved to
press 17 (or press PF3 to abandon the move) (message in SCOMPL tells you either that your move was completed or gives you an error message)
**Note:** It is okay to point the cursor to a position immediately after the stopper for another field; the moved field's attribute will simply replace the stopper. It is okay to point the cursor to a position which is within the field to be moved; for example, to move the field right one or two positions. You should not position the cursor within another field as that would result in an overlap of the two fields, which you would have to correct by either moving or deleting or shortening one or the other. Overlapping fields are not legal. You can also overtype the row and/or column parameters in the pop-up window instead of using the cursor to point to where you wish the field moved. If you alter the row and/or column parameters then MSKDEF will use the numerical parameters, move the field, and not require you to point with the cursor. When the coordinates are displayed, the mask number is also displayed with them. You can actually move a field to another mask by typing the target mask number over the one displayed.
## 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:
position the cursor onto the desired field (anywhere in the field, but not on the "stopper")
press PF19 (window appears with that field's specifications)
press ENTER (message in SCOMPL tells you either that your delete was completed or gives you an error message, screen image is updated reflecting the removal of that field)
## Duplicating a Field
The PF20 (Shift-F10, on a PC) key is used to duplicate a field.
To duplicate (copy) one field
position the cursor onto the desired field (anywhere in the field, but not on the "stopper")
press PF20 (window appears with that field's specifications)
alter any of the specifications if you wish different specs for the new field to be created
press ENTER to remove the pop-up window
position the cursor to where you would like the new field to begin
press PF17 (PF3 to abandon the field duplicate) (message in SCOMPL tells you that your duplication was successful or gives an error message)
**Note:** You can alter the row and/or column parameters in the specifications window, rather than position the cursor, to indicate where you wish the new field to begin. If you are duplicating a field which is part of an array (occurrence number is greater than zero and is numeric), then MSKDEF will automatically increment the occurrence number by one. This makes it easier for you to create an array on the screen. You can define the first occurrence, giving all necessary specifications, with an occurrence number of 001 and with a source/target dataname which includes a relative subscript [(*)]. Then you can use PF20 to duplicate it to wherever you wish occurrence 002 to be. Then you can duplicate occurrence 002 to occurrence 003, and so on. Occurrences of a screen field must follow certain rules in order to be compatible with the rules of Cobol. They must appear in ascending order as the screen is read from left to right, top to bottom. They must begin with occurrence 001 and increment by one, with no gaps and no duplicate occurrence numbers within an array. All fields within the array must be the same size and have compatible (alphanumeric, or numeric, etc.) edit types. If any field in the array uses extended color, all fields must use it. You may legally have more than one array on one mask. Also read [Creating Arrays](#msk007006) earlier in this chapter. If there are errors, you will be told about them when you do the MSKCRE function (or the batch MSKCREAT jobstream), even if MSKDEF does not catch them and warn you about them. This is because, in MSKDEF, some types of errors may be transient; the result of a set of changes you are in the process of making which is not yet complete. When you have completed all your changes those errors will, presumably, disappear. If you attempt to do MSKCRE before completing the set of changes, then those errors will be shown.
## 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:
position the cursor onto the desired line to be duplicated (anywhere in the line, whether on a field or not)
press PF4 (window appears showing the mask number and row number of the selected line)
press ENTER to remove the pop-up window
position the cursor to the blank line where you would like the new fields to be added
press PF17 (or, PF3 to abandon the duplicate operation) (message in SCOMPL tells you that your duplication was successful or gives an error message)
**Note:** You can, rather than point with the cursor to indicate where to create the new line, type in the target row number overkeying the displayed row number. Since the mask number is displayed along with the row number, it is possible to duplicate the line to another mask, as well. In any case the target row must be blank.
## 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:
position the cursor onto the desired line to be erased (anywhere in the line, whether on a field or not)
press PF5
pop-up window appears to confirm row to be erased
press ENTER (message in SCOMPL tells you that the line was erased, or gives an error message)
**Note:** Erasing a line (PF5) is not the same as deleting a line (PF13). Erasing a line simply removes any screen fields which were on that line, leaving a blank line. Deleting the line removes that blank line from the screen, squeezing all lower lines up one space. You cannot delete a line which has any fields on it, thus, you may sometines wish to erase a line, then delete it.
## 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:
position the cursor onto the desired line to be moved (anywhere in the line, whether on a field or not)
press PF6
press ENTER to remove pop-up window (or see note below)
position the cursor to a blank line to which you wish the fields moved
press PF17 (or, PF3 to abandon move operation)
**Note:** You can also move a line by typing the target line number into the pop-up window, rather than by pointing with the cursor. This method also allows you to move a line from one Mask to another by typing a target Mask number, as well. If you type into either the Mask number or the Row number in the pop-up window, the line will be moved immediately and you will not be required to point with the cursor and press PF17.
## 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:
position the cursor onto the desired line to be erased (anywhere in the line)
press PF13 (message in SCOMPL tells you that the line was deleted, or gives an error message)
## 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:
position the cursor onto the line after which you would like a line inserted (anywhere in the line, whether on a field or not)
press PF14 (message in SCOMPL tells you that the line was inserted, or gives an error message)
## 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 ( *