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:
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.
Prerequisite Reading
______ _______________________________ ........................................ |
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:
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.
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 01 -- Standard Screen Fields
Sequence of Tasks
if desired
Screen Header Definition
SHDxxx Functions
Figure 02 -- Screen Header / Detail
SHDxxx mmm |
The following online function codes are used by application developers to define, modify, copy, and delete screen detail definitions.
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.
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.
Figure 03 -- Screen Header Definition
Various Screen Definition Functions
Online Functions
Batch Jobstreams
Screen Detail
MSKDEF Screen Painter
MSKDEF xxx |
NOTE:
Figure 04 -- MSKDEF Screen
MSKDEF nnn ................ ............. ... |
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.
Figure 05 -- MSKDEF with Window Displayed
MSKDEF nnn ................ ............. ... |
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:
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.
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:
To change the literal value for any field:
To change the length of a field:
To change the position of a screen field:
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):
NOTE:
NOTE:
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.
NOTE:
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:
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:
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.
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:
NOTE:
The PF19 (Shift-F9, on a PC) key is used to delete a field from a mask.
To delete a field from a mask:
The PF20 (Shift-F10, on a PC) key is used to duplicate a field.
To duplicate (copy) one field
NOTE:
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:
NOTE:
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:
NOTE:
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:
NOTE:
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:
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 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.
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:
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:
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.
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:
You can invoke the MSKCRE function online from the MSKDEF screen. To do so:
NOTE:
NOTE:
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:
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:
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:
could be altered to look like this to save space:
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:
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.
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:
Figure 06 -- MSKDEF with Window Displayed
MSKDEF Functions
Getting Help
Using a Mouse
Changing a Field
(anywhere in the field, but not on the "stopper")
(window appears with all of that field's specifications)
(message in SCOMPL tells you either that your change was completed or gives you an error message)
Changing a Field (continued)
(if you move the stopper, you should also change the field's length specification accordingly
see below)
(anywhere in the field, but not on the "stopper")
(window appears with all of that field's specifications)
(message in SCOMPL tells you either that your change was completed or gives you an error message)
(anywhere in the field, but not on the "stopper")
(window appears with all of that field's specifications)
(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)
(anywhere in the field, but not on the "stopper")
(window appears with all of that field's specifications)
(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)
(anywhere in the field, but not on the "stopper")
(window appears with that field's specifications)
(must be a valid number
use TOCLOC 1 for list of valid table numbers)
(message in SCOMPL tells you either that your change was completed or gives you an error message)
(anywhere in the field, but not on the "stopper")
(window appears with all of that field's specifications)
(message in SCOMPL tells you either that your change was completed or gives you an error message)
Creating Arrays
Source/Target Array
Moving a Field
(anywhere in the field, but not on the "stopper")
(window appears with that field's coordinates)
(message in SCOMPL tells you either that your move was completed or gives you an error message)
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
(anywhere in the field, but not on the "stopper")
(window appears with that field's specifications)
(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
(anywhere in the field, but not on the "stopper")
(window appears with that field's specifications)
(message in SCOMPL tells you that your duplication was successful or gives an error message)
Duplicating a Line
(anywhere in the line, whether on a field or not)
(window appears showing the mask number and row number of the selected line)
(message in SCOMPL tells you that your duplication was successful or gives an error message)
Erasing a Line
(anywhere in the line, whether on a field or not)
(message in SCOMPL tells you that the line was erased, or gives an error message)
Moving a Line
(anywhere in the line, whether on a field or not)
Deleting a Blank Line
(anywhere in the line)
(message in SCOMPL tells you that the line was deleted, or gives an error message)
Inserting a Blank Line
(anywhere in the line, whether on a field or not)
(message in SCOMPL tells you that the line was inserted, or gives an error message)
Adding a New Field
Duplicating all Fields for a Mask
(where mmm = the source mask number)
(the source mask is displayed with a prompt to enter the target mask number)
(either an error message tells you that the target mask is not blank, or the fields are all copied and the new mask, the target, is displayed)
Deleting all Fields for a Mask
(where mmm is the desired mask number to be erased)
(the mask will be displayed for verification)
(a message in SCOMPL will tell you that the mask has been deleted and you can press PF10 to return to the auto-paint functions)
Controlling Color
Creating the Mask & Copybook
(this must be done from the MSKDEF screen for a mask which has at least one screen field defined
if there are no screen fields defined for the mask then PF10 will go to the auto-paint functions instead)
Restrictions & Limitations
Number of Fields
Field Edits
SCD Functions
SCDLST 600 END OF LIST - PF5=Restart/PF7=Backward |
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:
The screen's description from the SHD definition is displayed beside the mask number in the body of the display.
Figure 07 -- SCDLST Screen
Locate Heading Screen
SCDCHG mmm/rrr/ccc |
Figure 08 -- Locate Heading, SCDCHG Screen
SCDGBL mmm |
SCDGBL mmm |
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 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.
NOTE:
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.
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.
Toggle
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
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.
Listbox
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.
Pushbutton
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.
Bitmap
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.
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.
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.
GUITOOL /TOGGLE
GUITOOL /SELECTBX
GUITOOL /LISTBOX
GUITOOL /GETSPECS
GUITOOL /MODIFY
GUITOOL /GETID
GUITOOL /PUTPB
GUITOOL /PUTBMP
GUITOOL /DELETE
GUITOOL/DIALOG
GUITOOL /APICALL
GUITOOL/SPWNWAIT
Figure 10 -- SCDGBL Screen Messages
Using Auto-Paint
Graphical User Interface
GUITOOL
GUITOOL Request Area
01 GUITOOL-REQUEST PIC X(256) VALUE SPACE.
01 FILLER REDEFINES GUITOOL-REQUEST.
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.
03 GUITOOL-POSN REDEFINES GUITOOL-TOP-LEFT-ROW
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).
03 GUITOOL-PB-AREA REDEFINES GUITOOL-BMP-AREA.
05 GUITOOL-PB-LITERAL PIC X(40).
03 GUITOOL-API-AREA REDEFINES GUITOOL-BMP-AREA.
05 GUITOOL-API-LITERAL.
07 GUITOOL-API-BYTE OCCURS 82 TIMES PIC X.
05 FILLER REDEFINES GUITOOL-API-LITERAL.
07 GUITOOL-API-PROGRAM PIC X(9).
07 GUITOOL-API-PARM PIC X(73).
03 GUITOOL-SB-AREA REDEFINES GUITOOL-BMP-AREA.
05 GUITOOL-SB-ORIENTATION PIC X.
88 GUITOOL-SB-HORIZONTAL VALUE 'H'.
88 GUITOOL-SB-VERTICAL VALUE 'V'.
03 GUITOOL-ANIM-AREA REDEFINES GUITOOL-BMP-AREA.
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).
88 GUITOOL-REMOVE-FROM-PANEL VALUE 'Y'.
GUI Proformas
* *** 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-CAP-DEFAULT TO TRUE
SET GUITOOL-VAL-DEFAULT TO TRUE
* 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
PERFORM GTB300-MAKE-TOGGLE THRU GTB399-EXIT.
* *** 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-CAP-DEFAULT TO TRUE
SET GUITOOL-VAL-DEFAULT TO TRUE
* 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
PERFORM GTB200-MAKE-SELECTION-BOX THRU GTB299-EXIT.
* *** 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-CAP-DEFAULT TO TRUE
SET GUITOOL-VAL-DEFAULT TO TRUE
* 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.
CALL 'MAGECSET' USING GUITOOL-LISTBOX-TBL-ADDR tbl-of-values
* i.e.: "Doctor Lawyer Indian Chief"
PERFORM GTB100-MAKE-LISTBOX THRU GTB199-EXIT.
GUITOOL /COMBOBOX
* *** 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-CAP-DEFAULT TO TRUE
SET GUITOOL-VAL-DEFAULT TO TRUE
* 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.
CALL 'MAGECSET' USING GUITOOL-COMBOBOX-TBL-ADDR
* table-of-values in working storage
* i.e.: "Doctor Lawyer Indian Chief"
PERFORM GTA900-MAKE-COMBOBOX THRU GTA999-EXIT.
MOVE field-id TO GUITOOL-FIELD-ID.
PERFORM GTA600-GET-FIELD-SPECS THRU GTA699-EXIT.
SET GUITOOL-MOUSE-IGNORE TO TRUE
* or SET GUITOOL-MOUSE-SENSITIVE TO TRUE
* MOVE quote TO GUITOOL-AID-CODE
SET GUITOOL-PIXEL-SCALE TO TRUE
* or SET GUITOOL-CHARACTER-SCALE TO TRUE
* *** 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
PERFORM GTA500-MODIFY-FIELD THRU GTA599-EXIT.
SET GUITOOL-PIXEL-SCALE TO TRUE
* or SET GUITOOL-CHARACTER-SCALE TO TRUE
* 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.
SET GUITOOL-MOUSE-IGNORE TO TRUE
* or SET GUITOOL-MOUSE-SENSITIVE TO TRUE
* MOVE quote TO GUITOOL-AID-CODE
SET GUITOOL-PIXEL-SCALE TO TRUE
* or SET GUITOOL-CHARACTER-SCALE TO TRUE
* 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
PERFORM GTA200-PUT-PUSHBUTTON THRU GTA299-EXIT.
SET GUITOOL-MOUSE-IGNORE TO TRUE
* or SET GUITOOL-MOUSE-SENSITIVE TO TRUE
* MOVE quote TO GUITOOL-AID-CODE
SET GUITOOL-PIXEL-SCALE TO TRUE
* or SET GUITOOL-CHARACTER-SCALE TO TRUE
* 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
PERFORM GTA100-PUT-BITMAP THRU GTA199-EXIT.
* *** note: field-id must be set to indicate which object
* *** is to be deleted
PERFORM GTA300-DELETE THRU GTA399-EXIT.
* *** 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
PERFORM GTB400-MAKE-DIALOG-BOX THRU GTB499-EXIT.
* MOVE programname TO GUITOOL-API-PROGRAM
* MOVE parameters TO GUITOOL-API-PARM
PERFORM GTA700-API-CALL THRU GTA799-EXIT.
* *** 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
*-or- CALL 'MAGECSET' USING GUITOOL-TBL-ADDR parm-area
* *** 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.
PERFORM GTB500-SPAWN-AND-WAIT THRU GTB599-EXIT.