# Introduction

### User Guide

## Who Should Read This Guide

This guide is written primarily for use by those persons who will be using online applications which were developed by and operate under control of MAGEC. Although all MAGEC applications are not the same, there is a high degree of standardization encouraged by MAGEC. This book will describe all the standard features of MAGEC applications from the perspective of the terminal operator.

It is strongly recommended that data processing personnel also read this to familiarize themselves with the overall philosophy of the MAGEC software and so that they will understand what the application users can and should expect from the systems developed with MAGEC. This book, if read by both the users and DP personnel, should help define common terms and references to enhance communications between the two groups.

The MAGEC "system" functions which are used by application developers, security officers, database administrators, and so forth, are actually also applications which were generated using MAGEC and therefore share most of the same attributes as are described in this guide.

Copies of this guide should be distributed to:

- Application Users

- Application Developers

- Security Officers

- Database Administrators

- System Programmers

- Auditors

As well as any other individuals in the organization who might come in contact with MAGEC or the application systems developed using MAGEC.

# Overview

## What is MAGEC?

MAGEC is a software product which helps data processing application developers to more easily create and maintain online and batch applications. Online applications are computer systems designed to be used via CRTs (screens) as opposed to paper forms and reports. Many applications may be partially online and partially off-line, or "batch". Modern applications increasingly favor online processes since they permit immediate access to data and are, if properly designed, easier for the end-user to use. This manual concerns itself with online, as opposed to batch, applications.

Although MAGEC's primary function is to aid in the development and maintenance of applications, it also includes a large number of features specifically designed to help the end-user of MAGEC-generated applications. In this guide we will discuss how to use the applications developed using MAGEC and how to take advantage of the "user-friendly" features, such as:

- Menu Facility

- HELP Keys

- Pop-Up Windows

- Window Swapping

- Online Documentation

- Pick Lists

- Error Highlighting

- Browses with Cursor Selection

- Query functions

- Copy & Paste facility

# Keyboard

## Using the Keyboard

MAGEC applications may be used from any "3270-type" terminal or from a standard IBM (or compatible) PC or PS/2. While there are many possible variations of screen sizes and display color options these variations have little or no effect on the use of the terminal for MAGEC applications. There are, however, variations in keyboards which must be recognized.

Most 3270 keyboards consist of the usual alphabetic and numeric keys arranged (more or less) as they are on a standard typewriter. A Shift key changes the meanings of the alphabetic keys from lower-case to uppercase and, often, the numeric keys to special characters. The "Shifted meanings" are usually printed above the "non-Shifted meanings" on the face of each key. So far this is still very much like a standard typewriter.

In addition to the alphabetics, numerics, and special characters the 3270 keyboard also has keys for special functions. One of these keys is the "ALT" key (usually on the bottom row of keys) on some keyboards. The ALT key is simply another kind of Shift key. It alters some of the keys on the keyboard to a third possible meaning, the "altered" meaning. The Altered meanings are shown on the front edge of those keys which are affected.

## Special Function Keys

On some keyboards the special functions are separate keys while on some keyboards the special functions are altered meanings for the alphabetic or numeric keys. Regardless, the special functions have the same meaning to the MAGEC applications from any keyboard. The keyboards on microcomputers are usually different from those on mainframe terminals. MAGEC is oriented toward the mainframe keyboards. When you are using MAGEC at a PC or PS/2 you will notice that MAGEC substitutes function keys from the microcomputer keyboard for those on the mainframe 3270 terminal keyboard. There is a template in this section titled PC-MAGEC 3270 Emulation Template which will help you to translate from one to the other.

## ENTER Key

The ENTER key (usually near lower right corner of key pattern) is used to transmit data from the screen to the computer. Data may be keyed onto any screen and then re-keyed (in case of error) as many times as necessary before transmitting it to the computer. The 3270 terminal is actually a separate machine from the computer and until data is transmitted to the computer it is simply being held on the screen waiting for the operator to transmit it. The ENTER key is not the only one which transmits the data, but it is the one which is used most often. The PC key which emulates the ENTER key is the large plus key (+) at the far right of the keyboard in the numeric key pad section.

On a PC, MAGEC will also accept the page down key (Pg Dn) as equivalent to the mainframe PF8 key and the page up key (Pg Up) as equivalent to the mainframe PF7 key. This is handy since in many cases MAGEC screens use PF8 and PF7 to page forward and page backwards, respectively.

## PF Keys

Depending on which type of keyboard is being used there may be from 5 to 24 special functions called PF keys. These are marked with the designations PF1 (or PF01) through PF24. Some keyboards have only PF1 through PF12 and some have only PF1 through PF5 (very uncommon in recent years). These PF keys also transmit the screen data as the ENTER key does. The MAGEC applications can sense which key was used to transmit and can assign different meanings to different keys in order to allow the operator to use a single keystroke to indicate a request which might otherwise require entering a long "command". It is unlikely that any given application will have all the available PF keys defined. Those which are not defined by the application are treated as being equivalent to the ENTER key. The PC keys which emulate the PF keys are F1 through F10 (emulate PF1 through PF10, respectively), Shift-F1 through Shift-F10 (emulate PF11 through PF20, respectively), Alt-F1 through Alt-F4 (emulate PF21 through PF24, respectively).

## PA Keys

There are usually two (sometimes three) special function keys on the keyboard called PA keys. These do not transmit the data from the screen, instead, they transmit a special code which simply indicates which key the operator has pressed. They are used for certain very special purposes in all MAGEC applications as defined by the MAGEC software itself. The PA keys are identified by the designations PA1 and PA2 shown on them. Since they are so special it is often (depending on keyboard) necessary to simultaneously press the ALT key and the PA key in order to prevent the operator from accidentally pressing them. On the PC keyboard the Ctrl-F1 through Ctrl-F3 emulate PA1 thru PA3, respectively.

## CLEAR Key

The CLEAR key (ESC key on the PC) is used to "clear" the screen. It does not transmit the data from the screen. Like the PA keys it transmits only a code to indicate which key was pressed. It also "wipes out" all the data on the screen. Like the PA keys, it is also often necessary to simultaneously press the ALT and CLEAR keys as an added protection. This key also has very special purposes in MAGEC applications and is defined by the MAGEC software uniformly for all applications developed using MAGEC.

## The Cursor

The cursor is a special symbol, usually having the appearance of an underscore or a rectangular "block", which is displayed on the screen to show the operator what screen position is being "keyed into" at the time. As data is keyed into the screen the cursor normally advances left to right, top to bottom. MAGEC applications use "formatted screens". This means that the screen is formatted into "screen fields", some of which are "protected" and some of which are "unprotected". Protected means that the operator may not key into that field. Unprotected means that the operator may key into that field. The cursor, in most cases, will advance as the operator keys into an unprotected field on the screen and, at the end of that field, automatically skip to the next unprotected screen field in order to expedite the work of the operator.

## Cursor Manipulation Keys

You can position the cursor anywhere on the screen using special keys which are designated by arrows printed on their faces to show in which direction the cursor will move when they are pressed ( ). These keys can move the cursor to any position on the screen regardless whether there is a protected field at that position or not.

The "Tab" keys are marked with left and right arrows pointing to a vertical line ( ). These keys will skip Protected fields and position to the next or prior unprotected field.

Another cursor manipulation key is the HOME key. It moves the cursor to the first enterable field on the screen. In MAGEC that is always the six-character function code field at the top left corner of the screen.

Another cursor manipulation key is the RETURN key ( ↩ ) it moves the cursor down and left to the first unprotected field on a lower line. This key always has the "down-left-arrow" symbol shown on it. On a mainframe 3270 keyboard it is also labeled RETURN. On a PC keyboard it is sometimes labeled RETURN and sometimes ENTER, do not confuse that with the PC MAGEC simulation of the mainframe ENTER key (large + key). On a PC keyboard there are two plus keys, one is normally in the typewriter-like portion of the keyboard, in the numbers row at the top. To enter a plus character (+) with that key you must also hold down the Shift key. The other plus key is at the far-right, in the numeric pad portion of the keyboard. You do not need to depress the Shift key to enter a plus character with that key. That plus key at the far right is the "large plus key" which MAGEC accepts as meaning ENTER from a PC keyboard.

These keys do not enter any data as they move the cursor.

MAGEC applications can sense the position of the cursor at the time the operator pressed a transmit key (ENTER or any PF key) and can interpret it as the operator's selection of an item displayed in that position on the screen. An example might be a menu screen where a list of options is displayed and the operator selects the one desired by positioning the cursor to it and pressing ENTER. Cursor manipulation keys work essentially the same on the PC as they do on the mainframe.

# Screen Standards

The most popular 3270 screen size is 1,920 characters, 24 rows by 80 columns (columns are vertical as in Roman architecture). Other sizes are available, some larger some smaller, but for purposes of this discussion the 24 by 80 screen size will be assumed. MAGEC imposes some standards upon the applications as to screen format. These standards are intended to provide a uniformity in the way all applications work in order to simplify training of operators and also so that MAGEC can automatically provide some other "user friendly" features.

## Top Row of Screen

The top row (line) of every screen for every MAGEC application will consist of the same three standard fields. This is where the operator enters the "commands" to be executed and where the applications place "completion messages" to the operator. A completion message is one which notifies the operator that the operation specified has been done successfully, such as "Data UPDATED on Data Base" or that the operation cannot be done and why, such as "No Data Found for key", etc. A wide variety of possible messages might appear in this area of the screen and operators should pay attention to them carefully.

Data processing personnel have adopted standard names for these three fields. While it is certainly not necessary for operators to speak in the jargon of data processors, it might be helpful to know the standard names when talking to DP persons. The standard names for the fields on Row 1 of the screen are:

SFUNCT Screen function code

SKEY Screen key

SCOMPL Screen completion message

The first two fields, SFUNCT and SKEY together might be considered the "command", they are both unprotected (may be keyed into) while the last field, SCOMPL, is protected.

Function codes are keyed into SFUNCT, they are six-character mnemonics which specify what type of operation is to be done to what type of data. For instance: to add a customer one might use a function code of CUSADD. To change a customer's data one might use CUSCHG, etc. Of course, we are assuming that these are the function codes specified by the application developer.

Lower-case alphabetics are not allowed in function codes. MAGEC will automatically convert any lower-case alphabetic characters that you key in SFUNCT into their uppercase equivalents.

Key-values are keyed into SKEY. The longest key-value that can be entered is 31-characters since that is the length of SKEY. The key value specifies which record(s) are to be operated upon. For instance: entering CUSADD 37 (SFUNCT and SKEY) would indicate that the operator desires to add Customer number 37 to the database.

Lower-case alphabetics are usually not allowed in key values for most applications. MAGEC will normally translate any lower-case alphabetic characters into their uppercase equivalents. There is a provision made for the rare instance when an operator must enter a key value containing lower-case alphabetics. Refer to Key Value Entry topic in this manual.

     FFFFFF KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC

     SFUNCT     SKEY                          SCOMPL

                  SERRMSG

    EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE
    EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE
    EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE

Figure 01 -- SFUNCT, SKEY, SCOMPL, and SERRMSG

In Figure 01 the four standard screen fields are indicated by the letter they are shown filled with:

`F SFUNCT (function code)`

`K SKEY (key)`

`C SCOMPL (completion message)`

`E SERRMSG (error message)`

NOTE:

- SFUNCT and SKEY are enterable fields.
  SCOMPL and SERRMSG are display-only fields

Operator advisory and "positive feedback" messages are displayed in SCOMPL. Assuming that the operator entered: CUSADD 37, and that there already was a customer number 37 on file then SCOMPL might contain the message "Duplicate Already on File". The operator is never able to key into the SCOMPL screen field.

## Bottom 3 Rows of Screen

The last three Rows of the screen are also defined in a standard way in all MAGEC applications. They are defined as one large screen field known to the data processing personnel as SERRMSG. The operator can never key into the SERRMSG field on the screen.

SERRMSG stands for: "Screen Error Messages". Messages which appear here indicate entry errors in the screen data. MAGEC applications do not add or update the bad data to the database, they present it back to the operator with appropriate messages in the SERRMSG screen field.

The error messages are each up-to 40 characters long, there is room for up-to 6 such messages in SERRMSG at any one time. If the operator mis-enters a zip code on the screen (invalid format, non-numeric) then the error message might say "ERR123-Invalid ZIP code".

Every error message is assigned an error number (123, in the example above) which identifies it. If the operator mis-enters three zip codes on the same screen then the error message will only appear once since it would be pointless to repeat it. All three of the fields would be "highlighted" though to make the mis-entries stand out to the operator. Error numbers are not necessarily numeric, they may be alphanumeric -- they may contain the digits 0 through 9 and the letters A through Z.

# Error Messages

## Error Messages on Screen

All data which is keyed by the operator is edited and validated before it is used to update the database. A well-designed application should spare no effort in attempting to prevent wrong or bad data from ever getting onto the database. MAGEC applications pass the keyed data through three stages of editing:

1. MAGEC automatic editing

2. The developer's Custom editing

3. Business Rule editing

The automatic editing verifies that the keyed data is in the proper format, for instance: amount fields must be numeric, date fields must be a valid date, etc. It is also capable of verifying codes using a "table lookup feature", for instance: state abbreviations, product codes, etc. Automatic editing is associated with one screen field at a time, more complex cross-field compatibility editing (e.g. if Zipcode starts with "75" then Statecode must be "TX") is handled by Custom editing and Business Rules.

Custom editing is capable of verifying virtually anything that the automatic editing cannot, for instance: if the sales price entered is less than the suggested price on the product file then the salesman must be the owner of the company or this order is to be rejected. Custom editing is added to the application by the developer.

Business Rules are very much like Custom editing except that they are specified by the database administrator and are automatically added to the program without the developer having had to do anything. This is how the database administrator can ensure that only good data gets onto the files.

Regardless which type of editing issues an error message the message will be presented in the SERRMSG field and will have its error "number" (may be alphanumeric) prefixing it, as: "ERR7B5-Salesman is not the owner".

All Error messages are defined to MAGEC on its error message file. Error numbers starting with "9" (9AA thru 999) are standard MAGEC automatic editing messages, others are added by application developers and database administrators as needed. For every error message there are three items recorded:

Error Number three-character "number"

Message Text 33-character message

Description up-to four lines of explanation describing why
this message was issued and what to do to correct

The error number and text are what appears in SERRMSG. Whenever any error messages are displaying in SERRMSG then the operator may press the universal MAGEC "HELP" key (PF1) to request a display of the long descriptions for the error messages shown. The data which has been keyed onto the screen will not be lost or destroyed. MAGEC will display the Descriptions, which may continue for more than one screenful, and when done will return the operator's screen exactly as it was before. The error messages will still be there, the screen fields in error will still be highlighted, and the cursor will still be where it was. This may be done over and over without harming the operator's screen.

The SERRMSG field on the screen may never be entered into by the operator but is sometimes used to display messages other than error messages. In some functions it is not possible to receive an error message since the operator does not key any data and no database updating is involved. An example would be an inquiry or browse function which only displays data, but does not update any files. In some such cases the application might place instructions as to what may be done from here or what PF keys are defined in this application and their meanings. These messages are easily distinguishable from error messages.

## Highlighting

When error messages appear on the screen in SERRMSG the screen fields which are in error will usually also be highlighted. This means that they will appear brighter (or blinking, or in a different color, depending upon which type of terminal) to make them stand out from other screen fields. Though there is a limit of six error messages on the screen at one time there is no limit to the number of screen fields which might be highlighted.

NOTE:

- MAGEC will not display the same error message multiple times on one screen. If you have entered non-numeric data into three numeric screen fields then MAGEC will highlight all three fields, but will issue the message indicating "non-numeric data in numeric field" only one time. This is to avoid wasting valuable space which might be more useful for displaying other error messages, and so forth.

NOTE:

- Version 2.4 of MAGEC added the capability for your company to dynamically set a parameter controlling which of three "extended highlighting" options is to be used to denote screen fields in error. The options apply only to 7-color terminals; they are Blink, Reverse-Video, and Underline. The parameter is set in MAGEC Lookup Table #243, which can be altered by certain authorized persons in your company. If you are using a 4-color terminal, or a monochrome terminal, this parameter will be ignored and have no effect.

MAGEC will automatically position the cursor onto the first screen field which is in error in order to assist the operator to quickly correct the errors.

The operator need not re-key data which was correctly entered, only what is incorrect. The entire screenful of data is re-edited every time it is transmitted so that if, in correcting one error, the operator creates a new one it will be detected and an error message for it will be presented. This scheme automatically catches all combinations of errors involving cross-field validations. For example, the State Abbreviation (i.e. TX, NY, etc.) may be perfectly valid in itself, but may not be valid in combination with the Zip Code (which itself may be valid, but not within that State).

# HELP Key

## The HELP Key PF1

The PF1 key is universally defined by MAGEC as the HELP key. You may press it at any time to request appropriate documentation or explanation for whatever function you are currently doing. Some of the "help" features provided via the PF1 key are automatically produced by MAGEC, others require that the application developers enter concise and meaningful explanations and documentation as the application is being developed (or afterwards). The most satisfactory results occur when data processing and end-user personnel cooperate in the development of the applications and documentation.

The HELP key has one of four possible meanings depending upon the prevailing circumstances. It might:

- Display error analysis (error description)

- Display key entry analysis

- Display online documentation for a function

- Display the broadcast message

ERROR ANALYSIS If you are attempting to do an updating function and have error messages displaying on the screen (in SERRMSG) then pressing the PF1 key will result in a display of the error analysis, explanations for the error messages being shown. If the error analysis is longer than one screenful then the operator will be instructed (in SCOMPL) "Press PF8 to page forward". PF3 will quit immediately and return to your application screen.

Pressing PF8 will "page forward" to the next screenful of error analysis. After the last of the error analysis has been displayed pressing PF3 will return to the application screen intact as it was before the HELP key was pressed. PF7 (F7, on a PC) will page backwards while in the help display.

KEY ANALYSIS If there are not error messages on the screen but you have mis-entered the key value (in SKEY) for this function, then pressing the HELP key will result in a key analysis display. The key analysis is a single screenful of description and key format information with a sample shown to assist you in correctly entering the key. After the key analysis is displayed, pressing PF3 will return to the application screen intact as it was before the HELP key was pressed.

FUNCTION-LEVEL HELP If there are not error messages and the key-value has not been mis-entered (or if it has not been entered at all), pressing the HELP key will result in a display of the function-level documentation which has been entered for this function code. If there is no documentation then the message "NO DOCUMENTATION ON FILE" will be displayed. The documentation for a given function often will continue for more than one screenful. The SCOMPL field at the top of the screen will instruct the operator "Press PF8 to page forward" until the end of the documentation has been reached. A key analysis is also presented at the end of the documentation. Pressing PF3 after the key analysis will return to the application screen intact as it was before the documentation display began.

Since some functions might have rather lengthy documentation on file and it is likely that the operator will have found what information was needed before reaching the end, provision has been made to take a "shortcut" back to the application screen. At any time during the documentation display pressing PF3 (F3, on a PC) will immediately return to the application screen.

Re-pressing the HELP (PF1) key while viewing the documentation or error analysis will restart the display from the beginning.

BROADCAST MESSAGE If there is a Broadcast message which MAGEC "thinks" this operator has not yet seen, then pressing the HELP key will display the broadcast message regardless of what other circumstances prevail. Once the message has been shown to this operator the meaning of the HELP key reverts to the standard described above.

Broadcast messages are used by the central computer facility to notify all users of some scheduled event, such as "the computer will be shut down at noon", etc.

## Field-Level HELP Key PF2

Another type of HELP key is also built into MAGEC applications. It is the field-level HELP key. It will let you call up documentation for a specific screen field by positioning the cursor to it (anywhere within the field is OK) and pressing PF2.

When you invoke field-level HELP as described above, MAGEC builds a screen of textual description for the selected screen field. The description is built from a combination of 1) the technical specifications for that field, and 2) the textual narrative explanation from the MAGEC dictionary for the database field associated with this screen field. If the database administrator has not entered any explanation then only the automatically-generated portion of the text can be displayed.

Pressing PF3 (F3, on a PC) will return to the application screen intact as it was before the field-level HELP key was pressed.

This field-level HELP facility was added to MAGEC in version 2.0 (September, 1988). If you attempt to use the Field-Level HELP key on a screen which was created prior to then you will probably receive a message saying: "No documentation found in the dictionary". You should notify your application developers and database administrators. Upgrading older screens so that they include this valuable feature is not overly difficult and worth the effort.

# Menus

## Menu Screens

A built-in automatic menu facility will produce, on demand, a three-level menu for any operator. Operators are never required to use menus to access any application screen or function, but they may use the menus to access any screen or function for which they are authorized.

You can bypass all menus by simply keying the function code and key value (into SFUNCT and SKEY) to go directly to any application for which you are authorized. The more experienced operators are inclined to use this technique most of the time since it is faster. Less experienced opererators often prefer using menus to get to the applications until they become more familiar with the system. Either method produces the same results, they are just alternate ways of getting to an application screen.

The menu facility produces three levels of menu screens. The first, higher level, menu lists the logical applications for which the operator has access authorization. An example of logical applications is:

01 General Ledger

02 Accounts Payable

et cetera

Different operators might see a different list because their authorizations are not the same. By positioning the cursor to the line (row) on which a logical application appears and pressing ENTER the operator can select the one desired. The result will be an intermediate (group) menu for the selected logical application for the requesting operator. It will show a list of function codes which are in the selected logical application and which this operator is authorized to do, for example:

CUS... Customer Maintenance (9 functions)

VENCHG Change a Vendor

INC... Vendor Maintenance (9 functions)

etc.

Since these menus are dynamically built at the time they are requested, and since they are driven by the central dictionary's security parameters, they are always accurate based upon the current security authorizations. When new applications are added, or operators' authorizations are changed, the menus immediately reflect the new parameters. There is no waiting for technical support personnel to update the menu screens.

## How to Request a Menu

To get the main menu at any time you may key the function code **MENU into the SFUNCT screen field (top-left corner of screen). If you have set the Special Keys Option appropriately, you may also use the CLEAR (Esc key, on a PC) key or PA1 key (Ctrl-F1, on a PC) to get the same result. This session option is simply a way of equating a special function key to an often-used command in order to save the operator keystrokes.

## Group Menu

The intermediate menu lists functions and groups of functions which are available to you and which belong to the selected Logical Application. Since MAGEC applications usually contain a set of functions, all having the same three-character prefix, this menu shows such sets of functions as a single line item. If you cursor-select one of these sets you will receive the third-level menu which will show each individual function within that set. If the group-level menu detects that there is only one function available to you (for a given three-character prefix) then it will display that function on a line. If you select such a single function you will be given the actual application screen for it without having to go to the third-level menu.

## Application Menu

The third-level (lowest level) menu is called the "application menu". To get an application menu you may cursor-select the desired function set from the group menu or you may key into SFUNCT and SKEY (SKEY immediately follows SFUNCT on the screen) the command:

`$$MENU nn`

where:

nn = the logical application number desired.

Logical application numbers may be any number from 01 through 50 which are assigned by the security officers or data processing development staff. If you will be using the menus often then you may set a session option to equate the PA1 (Ctrl-F1) key to the $$MENU function to reduce keystrokes needed to return to the application menu from any other screen.

## Using the Application Menu

The low-level application menu display lists functions which belong to the logical application selected and which the operator logged on to the terminal is authorized to do. In some cases the list will continue for more than one "page" (screenful). Just pressing PF8 will "page forward" through the menu list. When the end of the menu list is reached pressing PF3 will return to the main menu.

To select a function from the application menu you may position the cursor to the line on which it is shown and press ENTER. If you position the cursor to a function's line and press HELP (PF2) instead of ENTER, the online documentation for the selected function will be presented instead of the application screen.

Since most functions require a key value in order to make up a complete command, you may key in the desired key value beside the selected function right onto the application menu screen. If the key value is not entered onto the menu screen and one is required then the application screen will be presented with a message in SCOMPL "Enter key Info -or- Press PF1 for Help".

You may then key in the desired key value or use the HELP key to obtain a key analysis display showing the proper format for entering the key value for this function.

CUSADD Add a Customer

CUSCHG Change a Customer

etc.

# Documentation

## Viewing Documentation

An online facility is built into MAGEC to enable you to view documentation at your screen. It includes a three-level "menu" to help you to choose among all the many topics stored in the documentation file (the DOC file).

To begin, you enter the function code: **HELP. You will be presented a list of Entity Types defined to the MAGEC dictionary. You can choose one by positioning the cursor to the line it is displayed on and pressing ENTER. The list may be more than one page (screenful) long. If you wish to page forward, just press ENTER without cursor-selecting an Entity Type.

When you select an Entity Type you will be presented a list of Key Words (or Key Phrases). They will be the ones associated with the selected Entity Type. For example, if you chose an Entity Type of FUNC (online function codes), you would receive a list of key words which were online function codes; if you selected an Entity Type of BPGM (batch programs), you would receive a list of key words which were batch program names, and so forth. Your list could continue for multiple pages, to page forward just press ENTER. When you see the Key Word or Phrase you are interested in, point to it with the cursor and press ENTER.

When you cursor-select a Key Word or Phrase, as described above, you will then be presented a list of Topics from the MAGEC documentation file. They will be those topics which are referenced by (associated with) the Key Word or Phrase you have selected. This list may also continue for multiple pages, you can just press ENTER to page forward. When you see the Topic you are interested in you can cursor-select it and press ENTER, you will be displayed the first page (screenful) of text for that Topic.

As you browse through the selected Topic you can page forward by pressing PF8, or page backward by pressing PF7 (F7, on a PC). When you are through reading it, you can press PF12 (Shift-F2, on a PC) to return to the Topics list.

At each level of the selection menus the PF12 key will take you back up to the prior menu. If your security authorization permits you to modify documentation, you can do so while you are browsing through the Topic. To do that you would alter the function code (SFUNCT) to DOCCHG, key in your changes, and press ENTER.

Another way you can look for a Topic in the DOC file is by simply browsing through it using the DOCLOC function. The DOCLOC screen is merely a list of Topics, in alphanumeric order, which are on the file. They are not organized by Key Word references. This method is handy when you know the Topic (and how it is spelled, approximately) that you want to view. You do not need to enter the complete Topic Name as a key value in SKEY (though you could), you could enter only the first few characters of it or just enter a "1" to start browsing at the beginning of the file.

As with all lists in MAGEC, you can cursor-select the item you are looking for by positioning the cursor to it, when it is shown in the list on the screen, then you can press ENTER and be immediately presented the DOCSEE display of the first page (screenful) of text for the Topic you chose. You also can produce hardcopy manuals from the DOC file. Your online applications have function-level and field-level online HELP which will be discussed later.

NOTE:

- **HELP menus help find Documentation. DOCLOC lists Topics.

## **HELP and DOCLOC

Figure 02 -- Reviewing Documentation Online

# Key Value Entry

## Keying into SKEY

A complete "command" might be considered to be a combination of the function code (entered into SFUNCT) and the key value (entered into SKEY). SFUNCT and SKEY are the first two screen fields on any MAGEC application screen. Some functions might not require any key value to be entered, but most do. Though the formats for entering key values for various applications may differ greatly, certain rules are common to all MAGEC applications. Understanding them will save much time and make it easier for an operator to quickly learn to use any MAGEC-generated applications.

## Padding

There are only two types of data which may be entered into the Skey field, they are: numeric data and non-numeric data. In either case the operator may key in the desired "value" and MAGEC will pad it as appropriate to produce the proper internal key. For instance: if a Customer number is six digits long the operator may key in a value of "37" and MAGEC will "pad" it to 000037 internally, if a Customer Name is 20 characters long the operator may key in "JONES" and MAGEC will append the appropriate number of blanks to the end of it.

Numeric key data is "right justified" and padded with leading zeros and non-numeric key data is left-justified and padded with trailing blanks. The application developers specify whether each item of key data is numeric or non-numeric. They also specify the minimum number of characters which the operator is to be allowed to enter for each item (component field) of key data. For instance: a minimum of two digits might be specified for Customer number, requiring an entry of "03" for Customer 3. Requiring a minimum number of characters (or digits) for an item of key data is often done to reduce the chance of mis-keyed data.

## Compound Keys

In many cases the key value will consist of more than one "key component". An example of such a compound key value might be: a key of Customer number plus Invoice number for accessing the invoice information screen. If the Customer number is six digits long and the Invoice number is seven digits long, then to access Customer 37's Invoice number 125 the operator may enter a key value of 37/125 instead of the cumbersome 0000370000125, which is the actual database key value. As in the example given, the slash character ( / ) is used as the delimiter between key Components. Each of the components may have a minimum number of characters specified for it. In some applications the key value may be compound with some numeric and some non-numeric key components, the slash separates the components and each will be properly padded and may have its own minimum specified. Up to five key components might be used in any given key value depending on the needs of the application.

## Key Delimiter

As mentioned above, the normal delimiter for key components is the slash ( / ). In most cases that is very acceptable; however, there might be some instances where a slash is a valid character within a key value. For example, an automobile's Vehicle Identification Number might look like: AB3/12XV45. In that example the Slashes are not delimiters separating different component fields of the key, they are actually part of the key value. Obviously, if the Slash were both a valid character within a key value and the delimiter separating component fields, a great deal of confusion would result. To solve this problem, MAGEC allows the developer to specify a different delimiter character to be used instead of the Slash. Therefore, in some of your screens you may use some other delimiter character to separate component key fields. Hopefully, the developer was thoughtful enough to advise you with either written documentation, online HELP text, messages displayed on the screen, or all of the above, in those cases.

## Lowercase in Key Value

It is a standard feature of all MAGEC applications that the function code and key value entered into the top row of the screen will be converted from any lowercase alphabetics to uppercase automatically. This eliminates the need for operators to concern themselves with the type of terminal being used and whether the terminal is converting alphabetic characters to uppercase or not. In almost all cases this uppercase translation is desirable. In very few rare cases it may be necessary to key lowercase alphabetics into the key value and not have them translated into uppercase. There is a way to do that.

MAGEC will not uppercase characters in the SKEY field if they are enclosed in quotes ( " ). Thus, to enter a key value of: ABC Corporation of OHIO

"ABC Corporation of OHIO"
- or
"ABC Corporation of OHIO
- or
abc c"orporation of" ohio

would all be equivalent. The quote characters will be "squeezed out" of the key value and do not count in the calculation of the length (number of characters) of data entered. The first quote encountered (left to right) will stop the uppercasing at that point and the next one will restart it at the point where it is encountered. If the entire key value is not to be uppercased then simply prefixing it with a quote will suffice since it is not necessary to restart uppercasing.

If the uppercasing is stopped by using the quote but the operator keys the data, or part of it, in uppercase alphabetics then those characters will remain uppercase as entered.

## HELP for Entering Key Values

If you require assistance in properly entering the key value for any given application you may use the HELP key to request a key analysis at any time. If the HELP key is pressed while any invalid key format is entered in SKEY, then the key analysis will be displayed. If the HELP key is pressed with a blank key value in SKEY, then the full online documentation will display. The last "page" (screenful) of the online documentation is the key analysis. The Documentation may also be requested by selecting the desired function from the application Menu and using the PF1 key as described in the Menus section of this book.

The key analysis screen displays a "key format", a mock-up of the complete key value with X's representing non-numeric data and 9's representing numeric data. For example:

`XXXXXXXXXX/999`

would indicate that the key value consists of a 10-character non-numeric item plus a 3-character numeric item. A description is also shown to help in understanding what this key value actually is. For example: City Name/ZIP code Prefix.

Below that is an "analysis" of the components showing the minimum number of characters for each and the maximum and the type of data, numeric or non-numeric.

If the key analysis is not enough to clarify the proper key format then you should review the full online documentation for more information. Just blank out the entire SKEY field and press the HELP key to request full online documentation.

# Standard Functions

## Standard Function Codes

MAGEC applications are always accessed using the six-character function codes entered into SFUNCT. There is no restriction regarding what characters may be used to make up function codes except that they be six characters long and that they be unique. The application developers could produce an application in which "XYZABC" is a valid function code - or "ADD$$$" or " @#$%^" or virtually any sequence of six characters which can be keyed into a CRT keyboard. However, it is more likely that they would use mnemonic, easy to remember, codes with some consistency of format.

The kinds of things that online applications do can be grouped into several categories. With very few exceptions they:

- Add data to the database

- Change data on the database

- Delete data from the database

- Duplicate data on the database

- Display (Inquire into) data on the database

- Browse through data on the database (with variations)

MAGEC very strongly encourages the developers to use a standard set of nine function codes to accomplish these operations. The standard set consists of function codes with a prefix (first three characters) which describes the "Data Class". Customer data might, for instance, be called "CUS". The last three characters describe which operation is to be done. The standard set of functions for CUS data would be:

CUSADD Add a Customer

CUSCHG Change a Customer

CUSDEL Delete a Customer

CUSSEE See (Display) a Customer

CUSNXT See the Next Customer (from the one shown on the CUSSEE screen)

CUSDUP Duplicate a Customer

CUSLOC Locate a Customer (Browse)

CUSSCN Scan for selected Customer(s)

CUSFND Find Customers meeting certain criteria

MAGEC makes it particularly easy and automatic to produce applications using the standard function codes, thus it is very likely that an operator will encounter these frequently. The online documentation should include detailed explanations for each of the functions, especially the SCN and FND functions, which are extremely versatile. In this Guide we will briefly describe what each type of function does and how each might be used.

## ADD Function

Functions ending in "ADD" are used to add data to the database. Using an ADD function actually involves two transactions (entries). In the first transaction, only the function code and key value are entered. The screen is returned to the operator formatted into the proper format for the function being done and with underscore characters (_) filling all the enterable (Unprotected) screen fields to show where the operator is to key data into. The operator then keys in the appropriate data to be added. In the case of adding a Customer this might consist of Name, Address, etc. After entering all the data the operator presses the ENTER key. This is the second transaction, or "continuation transaction". This time MAGEC passes all the screen fields through the Automatic Editing which verifies that numeric fields contain numeric data, etc., and the application might also pass the screen data through additional Business Rule and Custom Editing. If all the edits and validations are passed without detecting errors, then the new Customer is added to the database and the screen is returned to the operator with a message in SCOMPL : "Data ADDED to Database".

This message gives a "positive response" to the operator to assure that the ADD function has successfully completed. Sometimes the developer might override this standard message with one more suitable for the particular application or may eliminate it altogether by having the application immediately transfer to another screen and function after the data has been added. For example; after adding a Customer, the screen might come back formatted for adding an Invoice for that Customer with the function code automatically set to IVCADD to save operator keystrokes and time.

If errors are found in the screen data then the data is not added to the database. Instead, the screen is returned to the operator with Error Messages on the bottom (in SERRMSG) and the fields in error highlighted. If the operator corrects the errors and re-presses ENTER then the data will be added as above.

## CHG Function

The CHG functions are used to update data on the database. Using the CHG functions actually involves two transactions (entries) as with the ADD functions. On the first transaction, only the function code and key value are entered, the screen is returned to the operator in the proper format for the function being done and displaying the data for the key value entered. For example: if CUSCHG 37 was entered then the data for Customer 37 will be displayed. If there is no data found for the key value then a message in SCOMPL will say "No Data Found for key". Of course, the operator cannot update a record which is not there.

With the data displayed on the screen for the record(s) to be updated the operator may alter any field by simply keying over what is displayed. Pressing ENTER again initiates the second, continuation transaction. This time MAGEC passes all the screen data through the Automatic Editing (as for ADD function) and the application passes it through the Business Rule (if applicable) and its Custom Editing. If no errors are found, then the new data is updated to the appropriate database record(s) and SCOMPL will say: "Data Updated on Database".

If errors are found, then no updating takes place. Instead, the screen is returned to the operator with Error Messages and fields in error highlighted. If the operator corrects the errors and re-presses ENTER then the update will be done as above.

## SEE Function

Database data may be displayed on the screen using the SEE functions. Using them is a one transaction process in which the operator enters only the function code and key value. The screen is returned in the proper format for the function and with the data for the key value displayed.

Special provision is made for transferring from a SEE function to the CHG function for that same "Data Class". If the operator wishes to update the record(s) being displayed he/she may alter the function code to the CHG function, key over the data to be altered and press the ENTER key. In this case the SEE function is serving as the first transaction for the CHG function and the update will take place immediately (if all edits are passed, of course). When doing this the operator must not alter the key value or the screen will merely be returned displaying the data for the new key value (first transaction of a CHG function).

Special provision is also made for transferring to the DUP function to add a new record for a different key value but using the data from this SEE screen. This saves operator keystrokes and time when new data is to be added which is essentially the same as some existing data. To accomplish this the operator alters the function code to the DUP function, alters the key value to the new one desired, and (if needed) overkeys any data on the screen with changes, then presses ENTER. If all edits are passed the new data will be added immediately just as in the ADD function.

## DUP Function

The DUP functions are used to duplicate data on the database. They allow the operator to save keystrokes by copying existing data and making alterations to it as needed instead of re-keying from scratch. The DUP function may only be done immediately following a SEE function for the same Data Class. A valid sequence of events is:

`CUSSEE 37`

`CUSDUP 985`

This would add a new Customer (number 985) using the data from the SEE screen for Customer 37 with whatever changes the operator made by over-keying before pressing ENTER on the DUP function. The editing done for a DUP function is the same as for an ADD function.

## DEL Function

The DEL functions may be used to delete data from the database. Using the DEL functions is actually a two transaction process. In the first transaction the operator only enters the function code and key value, the screen is returned in the appropriate format and displaying the data for the key value given. If no data was found for that key value then SCOMPL will say: "NO DATA FOUND for key".

With the data displayed on the screen the message in SCOMPL will say: "Press ENTER to Delete" unless the developer of the application has overridden this standard message with a message more appropriate to that application. By simply pressing the ENTER key the data will be deleted unless the application has been provided with an "Edit for Delete" Custom Edit to protect against deletions in certain circumstances. For example: it might be illegal to delete a Customer if there are Invoices on file for that Customer.

The SEE function will also serve as the first transaction for a delete for the same key value. In the sequence of events:

`CUSSEE 37`

`CUSDEL 37`

Customer 37 will be deleted immediately when the ENTER key is pressed on the DEL function (if no edit errors are found).

## NXT Function

The NXT function may only be done following a SEE function for the same Data Class. It is used to display the next, or prior, record to the one being displayed. Successive NXT functions may be done until the end of the data is reached. The NXT function is considered equivalent to the SEE function. In cases where the SEE function serves as the initial transaction for another function (CHG, DUP, DEL) the NXT function will also serve.

As each successive record is displayed the key value for it is placed into the SKEY screen field.

You can page forward or backward using the NXT function. To page forward, press PF8. To page backward, press PF7 instead.

## LOC Function

The LOC functions are used to browse through the database to locate a particular record, etc. They allow the operator to enter a partial or "generic" key value, or to simply begin at the start of the database data and proceed from there. The operator enters the function code and key value (as appropriate) and presses ENTER. The application will access the database and start at the first record having a key value equal to, or greater than, the key value entered. It will list, one line per "record", on the screen selected fields of the records' data. In the case of a Customer Locate (CUSLOC) it might show Customer number, Name, City, etc. If the LOC function reaches the end of the data, then SCOMPL will say: "END of Data Reached" -- otherwise, SCOMPL will say: "Press ENTER to Continue".

Pressing the PF8 key will "page forward", browsing through the data until the end is reached. PF7 will "page backward". If the operator sees an item for which more information is desired he/she may position the cursor to the line on which that item is displayed and press ENTER. The screen will immediately transfer to the SEE function for the selected item. If the PF4 key is used instead of the ENTER key with cursor selection, the screen will transfer immediately to the CHG function for it. Refer to the topic "Attach / Detach" for more information about these screen transfers.

The LOC functions are ideal when the operator does not know the exact key value for an item he/she is looking for but will recognize it from a brief display of identifying data (Name, etc.). All LOC functions have the common feature that a key value of "1" means to start at the very beginning of the data (file) and begin listing from there.

## Attach / Detach

The cursor-select feature, which allows the operator to select an item from any browse screen to see or change its detail, utilizes the MAGEC Attach/Detach facility. That gives the operator the ability to return from the selected item's screen to the browse screen as it was left. When the operator cursor-selects an item, MAGEC does an "Attach" to the SEE or CHG function screen for the chosen item. To return to the browse list, the operator simply presses PF3. This works from the LOC functions, SCN functions, and FND functions, automatically.

The Attach / Detach facility supports up to three (3) levels of screen nesting by saving the browse screen from which the cursor-selection was made. If the operator exceeds three levels, MAGEC will present a pop-up window with a message indicating so. The window message will offer four options for handling the situation:

1) Push oldest Screen off of STACK -- this simply drops the highest level screen from the stack and adds the current screen as the third-level screen in the stack and proceeds to the display of the selected item. The operator then has the ability to Detach (via PF3) back three levels, but no longer to the screen which used to be at the highest level, since all lower level screens have been bumped up one level.

2) Clear STACK of Screens -- this option clears the entire stack, dropping all three of the saved screens and then saves the current screen as the highest level. The selected item's detail screen will be displayed.

3) Transfer without STACKing this Screen -- this option leaves the saved stack as it was, transferring to the chosen item's display screen without saving the current screen. The operator can Detach back to the three saved screens in the stack, but the current browse screen is not one of them.

4) Return to Screen with no change -- this option does not transfer to the chosen item's display screen, and it does not alter the stack of saved screens. The operator will be returned to the browse screen as if he/she had not done a cursor-selection at all.

## SCN Function

The SCN function is a variation of the LOC function. It also accepts a generic key value, and lists the same data on the screen. The difference is that it has a "Selection Mask" line added to the screen in which the operator enters selection criteria. The Selection Mask is formatted the same as the data display lines but with the Dot character (.) in every data position.

The SCN function is a type of Query-by-Example. The operator overkeys the Dots in the positions desired with the selection character for that position.

For example: if the operator wishes to see only Customers who live in cities whose names begin with "dal" and whose Customer Names begin with "W" he would key a "w" into the first position of the Name field, and "dal" the first three positions of the City field in the Selection Mask. When the operator presses the ENTER key data will begin being listed on the screen just as in the LOC function, except that only items having the same character as in the Selection Mask will appear.

The DOT character indicates that the SCN function is to ignore comparisons in that position it is a "wild card" character.

NOTE:

- On the sample screen (Figure 03) dots indicate the data display positions.

     CUSSCN 1

    Cus #    Name                         City

    ......   ........................     ........................

                                                 Selection Mask Line

NOTE: The dots indicate the data display columns. You overtype the dots for matching entries in those columns.

Figure 03 -- Selection Mask Line on SCN Screen

The example screen shown in FIgure 04 depicts a SCN function being done on the CUS Data Class using the function code CUSSCN. Notice that the operator keyed match characters into the display positions in which a comparison was to be made and left the Dots in all other positions in the Selection Mask.

Using a key value (in SKEY) of "1" in any LOC, SCN, or FND function will cause the operation to start at the beginning of the file, accessing in the file's primary key sequence, regardless of what the first actual key value on file is.

Notice that the SCN function treats lowercase alphabetics as equal to their uppercase equivalents. This enables the operator to scan for a name based upon its spelling without being concerned as to whether it is on file in all uppercase, all lowercase, or mixed cases. Treating lower and uppercase alphabetics as equal is the standard rule for the SCN functions (and also for the FND functions below). It is possible in some cases that the application developer decided that this standard was not appropriate. The developer has the option to override this standard, thereby causing the operator to have to enter the exact alphabetic characters in upper and lowercase in order for the SCN function to find a "match", it is very rare though.

The display of all items meeting the selection criteria might well continue for more than one "page" (screenful). The message in SCOMPL indicates either "Press ENTER to Continue" or "END OF DATA Reached".

The SCN function is extremely easy to use and can satisfy many ad hoc requirements for special inquiries. It includes the same cursor-selection features as the LOC function does. Positioning the cursor onto the line on which an item is shown and pressing ENTER will transfer immediately to the SEE function for that item. Pressing the PF4 key instead of ENTER will transfer immediately to the CHG function for it.

Pressing PF8 will page forward through the display. Pressing PF7 will page backwards. The last line of each "page" will show the "page number" (relative to the start of this display) and how many records have been scanned and how many of those were selected and displayed so far. Pressing the PF5 key will restart the display at "page 1".

## Scan Limit

In order to prevent the SCN function from using up too much of the computer's resources, a limit is placed on the number of records it may scan before sending the screen back to the operator
asking him/her to "Press ENTER to Continue". The normal setting of the Scan Limit is 1000 records. The developer might, in some applications, override this standard by setting a higher or lower Scan Limit. It is even possible that the developer might vary the Scan Limit based upon the time-of-day, location of the terminal, or operator ID. As the SCN function is scanning through the database trying to find enough records to display to fill the screen it may sometimes reach the Scan Limit before finding a screenful of records to display. In that case it will display as many as it has found so far and, if the operator presses ENTER (to Continue), it will then resume its scan.

     CUSSCN 1                             END OF LIST - PF5 Key=Restart/PF7=Backward

    Cus #   Name                     City

    ......  w...................     dal..............

    000135  Wilson, James            Dallas

    001056  Wellington, Fred         Dal-Worth

    305670  womack, dan              Dalesville

           ++++ 37 Records Scanned, 03 Displayed so far -   Page  1 ++++

    KEY 1 = Customer #                      Press PF13 for Hardcopy

    You may Position the CURSOR on an item and Press ENTER to "SEE" it

    (Browsing Forward)                      or Press PF4 to "CHG" it

Figure 04 -- Sample SCN function

## FND Functions

In selecting the records to display, the SCN function checks that they meet all the selection criteria. For instance: it will check that the first character of the Name is "W" and the first two characters of the City are "DAL" and show only items meeting both criteria. This is known as an AND connection between the criteria. To select items using an OR connection between the criteria (or other connections) the FND function would be used. For instance: the FND function could select items in which either the Name begins with "W" or the City begins with "DAL", etc.

The FND function is used to search for records on the database using more elaborate search arguments than the SCN function can handle. FND functions permit searches for "character strings", or sequences of characters anywhere in the displayed data, for example: a FND function might be used to search for all Customers whose Names contain the character sequence "CORP" regardless where in the Name it appears. The list which results might include:

Jones Corporation

Fleming Incorporated

Corporate Leasing Company

Scorpion Enterprises

This application of the FND function is similar to what may be done with the SCN function except that the search is not limited to only the exact positions in which the "Search Argument" was keyed, in fact the Search Argument is not keyed into the Selection Mask line at all. The FND functions' screens include an additional screen field called "Search Argument" in which the operator enters the character sequence to be searched for.

As with the SCN functions it is the standard rule that uppercase and lowercase alphabetics are considered equal in the search comparison unless the application developer has overridden the standard for some reason.

The Dot (.) character is also a wild card character in the Search Argument of the FND function. If you were looking for someone named either Dan or Don you could search for "d.n".

The same rules for "Scan Limit" apply to FND functions as to SCN functions in order to prevent their "hogging" the computer resources. Any item displayed on the screen list may be cursor-selected using the ENTER or PF4 keys to transfer to the SEE or CHG functions, respectively, just as for the LOC function. Any key value may be entered into SKEY to start the search at some position into the file other than the beginning, or a key value of "1" may be used to start at the beginning.

     CUSFND 1

     Search Arg:  ..................................................................

    Cus #       Name                         City

    .......     ..........................   ..............................

                 Enter the character sequence you wish to search for on

                 the 2nd line of the screen beside "SEARCH ARG:"

                 Then, you may use PARENTHESES to bracket the portion of

                 the display line in which you wish the search to be done.

                 Enter the PARENTHESES on the 4th line, below the heading.

                 Use ONLY ONE LEFT and/or ONE RIGHT parenthesis, NO OTHER

                 CHARACTERS on that line.  Omitting them results in a

                 search of the entire line.

                 You may Press PF1 for complete instructions.

Figure 05 -- Search Argument Line on FND function

In the sample FND function screen shown, the Search Argument was entered as "CORP" and parentheses were used to delimit the "Search Zone" causing the FND function to look only in the Name portion of the screen data for the character string: "CORP". If the parentheses were omitted then the entire display area would have been searched.

The FND function permits two Search Arguments to be used in any one search, for example: to search for Customers whose Names contain either the sequence "CORP or "INC" a Search Argument might be entered as follows: "CORP|OR|INC". The vertical bar character ( ) or (broken bar character) can be used to "bracket" the logical connector . The FND functions support one or two argument searches with a logical connection between the two arguments of:

AND AND connection
(both A and B)

OR OR connection
(either A or B)

NOR NOR connection
(neither A nor B)

NOT NOT connection
(not A)
(A but not B)

XOR Exclusive or connection
(either A or B but not both)

Every FND function should have complete explanations for using all options included in the online documentation. If the developer has produced the application using the recommended standard set of function codes, then MAGEC will have automatically added a full explanation of the FND function to whatever other Custom Documentation might have been provided.

The FND functions can be used to do complex searches of the database as needs arise. In many cases these functions will allow the operator to satisfy ad hoc requirements without calling on data processing personnel for assistance and without waiting for custom programming to be done. Since the same information is displayed on the LOC, SCN, and FND screens the value of these functions will be greatly enhanced if Data Processing and User personnel collaborate on their design.

NOTE:

- When you do a selection from any of the browse or query screens (LOC, SCN, or FND) MAGEC saves the list of keys of the items which were displayed to you (the items which matched your selection criteria if you were doing a SCN or FND). This saved list is called the "Short List". Cursor-selecting an item takes you to a display or update screen for that item; you can then select another item from the Short List by pressing PF24, requesting a pop-up window listing the Short List, and cursor selecting from it. When you cursor select from the Short List you must press PF24; that selects the item and returns to your full-screen display or update for the selected item. See the topic Short Lists, later in this manual.

     CUSFND 1                                 END OF LIST - PF5=Restart/PF7=Backward

     Search Arg: corp...............................................................

    Cus#      Name                        City

    ......   (.....................)      ......................

    001024    Jones Corporation           San Francisco

    002305    Fleming Incorporated        Los Angeles

    022167    Scorpion Enterprises        New York

           ++++ 37 Records Scanned, 03 Displayed so far -   Page 1 ++++

    KEY 1 = Customer #                      Press PF13 for Hardcopy

    You may Position the CURSOR on an item and Press ENTER to "SEE" it

    (Browsing Forward)                      or Press PF4 to "CHG" it

Figure 06 -- Sample FND function

# Changing Browse Direction

## The PF8 and PF7 Keys

In all browse functions (LOC, SCN, and FND) the PF8 key causes your screen to page forward one screenful; the PF7 key causes your screen to page backward one screenful. A display at the bottom left corner of your screen will tell you whether you are going forward or backward.

If you are doing a query (SCN or FND) you can cause the program to search forward or backward using these same keys.

In inquiry functions (SEE and NXT) PF8 will read forward and display the next item and PF7 will read backward and display the prior item from the one which had been displayed.

# Simulating PF/PA Keys

## **PFnn and **PAnn Function Codes

There might be some instances when you wish to use a particular PF key or PA key but cannot because of any of several reasons. Your terminal keyboard might not have that key (some older models do not have every possible key). Your mainframe system might have designated that particular key for some special purpose, in which case the key is "intercepted" before it can reach the MAGEC applications. Your keyboard might be faulty.

Regardless why you cannot use the desired key, there is an alternate method for simulating any valid key. You move the cursor to the SFUNCT screen field (the simplest way to do that is to press HOME), then you type in one of the special function codes:

function codes keys simulated

**PF01 thru **PF24 PF1 thru PF24

**PA01 thru **PA03 PA1 thru PA3

Then just press ENTER.

You can even use cursor-selection in conjunction with this key simulation. Just type in the special function code, position the cursor where you want it, then press ENTER.

# Broadcast Message

## MSGSEE Function

Sometimes it is necessary for the Central Computer Site personnel, such as security officers, mainframe operators, etc., to issue a message to all system users informing them of some event or situation affecting them. A good example of this is: the computer is scheduled to be "down" from noon to 1:00 today.

A Broadcast Message Facility is built into MAGEC and all applications developed using MAGEC. Any operator may see the current Message by using the function code MSGSEE. entered into SFUNCT. There is no key value required and if one is keyed into SKEY it will be ignored. The current Broadcast Message will be displayed on the operator's screen with the function code altered to MSGSAW.

Pressing ENTER with the MSGSAW function will indicate to MAGEC that you have seen the message.

If MAGEC "thinks" that an operator has not seen the current message then there will be a Notification message displayed on the last line of the screen saying: "THERE IS A MESSAGE FOR YOU - USE MSGSEE, OR PRESS PF1 TO SEE IT".

Whenever this Notification is shown on the last line of the screen the PF1 (or F1 on a PC) key, usually designated as the HELP key, is automatically equated to the MSGSEE function. Pressing it at that time will simulate the operator's having keyed MSGSEE into SFUNCT and will display the Broadcast Message with the MSGSAW function code set. Pressing ENTER after reading the message indicates to MAGEC that this operator has seen the message, so the Notification disappears and PF1 reverts to its normal HELP key function.

# Getting Into MAGEC

## In a CICS Environment

One of the most common environments in which MAGEC applications are used is called "CICS". CICS is a product of IBM. If the operator does not know whether the environment is CICS or not he/she should contact the Data Processing department. This section describes how to get into MAGEC in a CICS environment, for other environments see below.

MAGEC is sub-divided into sixteen (16) "user views". When an operator wishes to "get into" MAGEC he/she does so via one of these user views. The user views are named:

Test User-Views Production User-Views

TS01 PR01

TS02 PR02

TS03 PR03

TS04 PR04

TS05 PR05

TS06 PR06

TS07 PR07

TS08 PR08

The MAGEC security system might specify that some operators are allowed to use some user views and not others, and that some terminals are allowed into some user views and not others. Another security system which is built into CICS might also impose some limits on operators and terminals with regard to accessing these user views.

The MAGEC security system might also specify that some function codes are allowed in some user views and not others. User views are an important part of security control in MAGEC.

An operator can always determine whether he/she is already in MAGEC by pressing the CLEAR key. If in MAGEC, the CLEAR key will result in either the MAGEC "logo" screen, the MAGEC log on screen, or a MAGEC Menu screen depending on the setting of the operator's Special Keys session option. In any case it will be obvious to the operator that he/she is or is not already in MAGEC when the CLEAR key is pressed. If not already in MAGEC, the operator should "home" the cursor (move it to top-left corner of screen) and key one of the four-character user-views and press ENTER.

Once "into" MAGEC the operator will probably be required to log on (identify him/herself) before being allowed to do any other function. Logging on is initiated by entering "SYSLOG" in SFUNCT and "ON" in SKEY. There are also automatic logon facilities built into MAGEC which can log the operator on vased upon his/her having logged onto a higher-level security system, such as RACF, TopSecret, or ACF2.

After getting into MAGEC all procedures are identical regardless of which environment is installed (CICS or other). Refer to the section of this manual titled Logging On/Off for log on procedures.

## In a Westi Environment

One of the common environments in which MAGEC applications are used is called "Westi". Westi is a product of Westinghouse Corporation. If you do not know if your environment is Westi or not you should contact the Data Processing department. This section describes how to get into MAGEC in a Westi environment, for other environments see below.

MAGEC is sub-divided into sixteen (16) "user views". When an operator wishes to "get into" MAGEC he/she does so via one of these user views. The user views are named:

Test User-Views Production User-Views

TS01 PR01

TS02 PR02

TS03 PR03

TS04 PR04

TS05 PR05

TS06 PR06

TS07 PR07

TS08 PR08

The MAGEC security system might specify that some operators are allowed to use some user views and not others and that some terminals are allowed into some user views and not others. Another security system which is part of Westi might also impose some limits on operators and terminals with regard to accessing these user views.

The MAGEC security system might also specify that some function codes are allowed in some user views and not others. User views are an important part of security control in MAGEC.

An operator can always determine whether he/she is already in MAGEC by pressing the CLEAR key. If in MAGEC, the CLEAR key will result in either the MAGEC "logo" screen, the MAGEC log on screen, or a MAGEC Menu screen depending on the setting of the operator's session option. In any case it will be obvious to the operator that he/she is or is not already in MAGEC when the CLEAR key is pressed. If not already in MAGEC then the operator should press the CLEAR key to obtain the Westi Main Menu screen and key one of the four-character user views and press ENTER.

Once "into" MAGEC the operator will probably be required to log on (identify him/herself) before being allowed to do any other function. Logging on is initiated by entering "SYSLOG" in SFUNCTand "ON" in SKEY.

After getting into MAGEC all procedures are identical regardless of which environment is installed (Westi or other). Refer to the section of this manual titled Logging On/Off for log on procedures.

## In a PC Environment

MAGEC may also be run in a PC environment, either standalone, or as a PC workstation on a network. In text mode, the PC environment essentially emulates the CICS environment.

In a Windows or OS/2 environment, simply mouse-seelct the appropriate icon from your Windows group or OS/2 folder--MAGEC will startup automatically.

NOTE:

- Please refer to Appendix A of this manual for the MAGEC keyboard emulation template which will equate 3270 PF and PA keys to PC keys.

MAGEC is sub-divided into sixteen (16) "user views". When an operator wishes to "get into" MAGEC he/she does so via one of these user views. The user views are named:

Test User-Views Production User-Views

TS01 PR01

TS02 PR02

TS03 PR03

TS04 PR04

TS05 PR05

TS06 PR06

TS07 PR07

TS08 PR08

The MAGEC security system might specify that some operators are allowed to use some user views and not others, and that some terminals are allowed into some user views and not others.

The MAGEC security system might also specify that some function codes are allowed in some user views and not others. User views are an important part of security control in MAGEC.

An operator can always determine whether he/she is already in MAGEC by pressing the CLEAR (Esc, on a PC) key. If in MAGEC, the CLEAR key will result in either the MAGEC "logo" screen, the MAGEC log on screen, or a MAGEC Menu screen depending on the setting of the operator's session option. In any case it will be obvious to the operator that he/she is or is not already in MAGEC when the CLEAR key is pressed. If not already in MAGEC, the operator should key one of the four-character user-views at the DOS prompt and press ENTER.

Once "into" MAGEC the operator will probably be required to log on (identify him/herself) before being allowed to do any other function. Logging on is initiated by entering "SYSLOG" in SFUNCT and "ON" in SKEY. There is a facility built into MAGEC which can automatically log the operator onto MAGEC based upon his/her having logged onto the network's security system. This eliminates the need for the operator to see or use the SYSLOG ON screen.

After getting into MAGEC all procedures are identical regardless of which environment is installed (PC or other). Refer to the section of this manual titled Logging On/Off for log on procedures.

# Getting Out of MAGEC

## PF15 Key

Regardless what environment is installed (CICS, IBM-PC, Westi, etc.) and regardless what function or screen is presently being used by the operator, MAGEC may always be exited by pressing the PF15 (Shift-F5 on PC) key. If you are at a mainframe terminal, a MAGEC option was specified by the data processing personnel as to what non-MAGEC application is to be transferred to when PF15 is hit.

In a GUI environment there is an EXIT button in your toolbar which will automatically press PF15.

On the mainframe, pressing PF15 does not log the operator off - it simply exits MAGEC.

NOTE:

- Via the global system parameters contained in Table #243 you can establish a routine which is to be invoked immediately after exiting MAGEC via PF15. This routine may execute any other online transaction desired; therefore, it is up to your Systems department to determine what is executed when you press PF15.

# Logging On and Off

In order to log on to MAGEC the operator must have been defined to the MAGEC security system by a security officer. When the officer defines the operator, an employee number and an initial password will be assigned. Thereafter, that operator can log on and off using the commands SYSLOG ON or SYSLOG OFF as appropriate. Logging off may be done from any MAGEC application screen at any time by simply keying the command and pressing ENTER. When logging on, the command must be keyed into SFUNCT and SKEY and when ENTER is pressed the screen returns to the operator in the format shown in figure 07.

The operator must correctly enter his/her employee number (operator ID) and four-character password. If these are correctly entered and no other situation exists to preclude MAGEC's accepting the log on, the message "Log On Firstname Lastname" will appear below the password. Lastname and Firstname in the sample message are the operator's names. The operator may now proceed to do any MAGEC application functions for which he/she has been authorized by the security officers.

If any portion of the entry is incorrect then the operator will have to retry logging on by rekeying the password and, if it is wrong, the employee number. The password must be rekeyed on every attempt to log on even if it was correctly keyed before, since MAGEC "wipes out" the passwords on the screen for security reasons.

## Changing the Password

If you wish to change the password at any time it may be changed as you log on. To change the password, enter the employee number and password, as usual, then skip the cursor down to the NEW PASSWORD screen field and key the new password into it. In order to be sure that you have not accidentally miskeyed the new password it must be repeated again below exactly as it was entered into the NEW PASSWORD field.

NOTE:

- All three password entry fields on the screen are "dark" fields; they are invisible to the operator and anyone overseeing the entry. All three are "wiped out" by MAGEC every time the operator presses ENTER (or any other transmit key) for security reasons. If the operator has to retry the log on because of any error all three will have to be re-keyed.

Certain verifications are made to guard against changing the password to one which is easy to guess by unauthorized persons. If the "guessing routine" built into MAGEC is able to guess the new password then you will receive the error message "New Password is TOO EASY" and will have to choose a better password.

It is possible for the security officers to suspend an operator for any reason, it is also possible for MAGEC to automatically suspend an operator for a variety of reasons. Some examples are: exceeding the maximum number of failed logon attempts, attempting to log on after the operator's termination date, etc. A message on the screen will tell the operator that he/she is suspended when this occurs. The operator must contact a security officer in order to be reinstated.

The security officers may also require that an operator change his/her password at some minimum frequency by specifying that each new password is only good for some number of days from the time it is set. If the number of days elapses and the operator has not yet changed the password

    SYSLOG ON                              MAGEC User-View TS01, Term-ID PC01

                                      M A G E C

                                   SYSTEM LOG ON/OFF

     EMPLOYEE NUMBER: _________                    DATE: MM/DD/YY

                                                        THURSDAY

            PASSWORD: ____

       NOTE - To change your password: (1) enter OLD password above - DO NOT HIT

              ENTER,  (2) enter NEW password below, (3) repeat it for verification,

              (4) hit enter.

               NEW PASSWORD:

           REPEAT TO VERIFY:

Figure 07 -- Log On / Log Off Screen

then he/she will be required to do so in order to log on. A message will appear saying "Time to Change Your Password". Operators may be restricted to logging on only via certain user views or only at certain locations or certain days of the week or times of the day or holidays. If an operator attempts to log on where or when not authorized, the log on will be rejected with an error message. If the operator repeatedly attempts to log on and is repeatedly rejected, he/she may be automatically suspended by MAGEC, requiring a security officer's help in order to be reinstated.

## Time-Out

In order to protect operators who sometimes forget to log off of the system before leaving for lunch or for the night, the security officers can specify a time-out parameter for each operator and for each terminal. This specifies the number of minutes that may elapse since the last entry at the terminal before MAGEC assumes that the operator has left the area and automatically logs him/her off. The next time an entry is attempted, the log on screen will be presented with the message shown below the password field saying: TIME OUT. The operator may re-enter the employee number and password to log back on to the system.

# Windows

## Swapping Windows

The window swapping feature of MAGEC works for any function. You can press PF9 (F9 on a PC) or key the function code **SWAP any time to swap windows. The transaction on the screen at that time will be moved into the "hold window" and the transaction from the hold window will be moved to the screen. Pressing PF9 again will swap them back again.

In a GUI environment there is a SWAP button which is equivalent to pressing PF9.

If you are in the middle of some complex transaction and suddenly realize that you need to look up something on another file or table using some other functions, pressing PF9 will "save" the current transaction allowing you to do any number of other transactions and then, later, return to exactly where you left off.

# Copy & Paste

## PF16 and PF17 Keys

There is often the need to copy data from one screen display to another. For example, suppose the operator was adding a record for a new customer which happened to be a department of a company in which other departments were already customers. It would be handy to have the ability to copy the address from a screen display of the existing customer into the address field for the new one to be added. That can be done using MAGEC's Copy & Paste facility.

There is a "holding area" (sometimes called a "cut/copy buffer", or "clipboard") which will hold up to 2,400 characters of data. There are designated PF keys to enable the operator to copy screen data into the buffer or to copy data from the buffer to the screen. They are:

PF16 -- copy data to buffer

PF17 -- paste data from buffer onto screen

In a GUI environment (replaced by LAMP Stack MAGEC) there are COPY and PASTE buttons on your toolbar which are equiivalent to the PF16 and PF17 keys.

The operator could, therefore, display the old customer's data and position the cursor to the address and press PF16 (Shift-F6, on a PC). Then, while adding the new customer's data, position the cursor to the screen area where the address is to be filled-in and press PF17 (Shift-F7, on a PC). The address data would be pasted onto the new screen, saving many keystrokes and possible errors.

When data is copied into the buffer (using the PF16 key) it remains in the buffer until the operator copies something else into the buffer (thereby replacing it). That means that the operator could do any number of other transactions before pasting that data into another screen. It also means that the data can be pasted more than once. Once data is copied to the buffer the operator is not required to ever paste it anywhere, though.

The Copy & Paste facility works on only one screen field at a time, each Copy operation overlays the data in the buffer. If data is copied from a short field and pasted to a longer one it is padded with trailing spaces. If it is copied from a long field to a shorter one, it is truncated on the right.

This feature works equally well in conjunction with the Window Swap feature or in normal single screen mode. The buffer is even retained when the operator logs off (via SYSLOG OFF) or simply exits MAGEC (via PF15) so that it is still available when he/she returns.

# Session Options

## Special Keys Option

Any operator may set a session option code to specify that the PA1 (Ctrl-F1, on a PC) key and CLEAR (Esc, on a PC) key are to be equated to certain, frequently-used functions in order to save operator keystrokes. To set the Option the operator may at any time enter (into SFUNCT) the function code OPTION . No key value is required, as it will be filled in by the OPTION function using the operator's employee number. The screen will be returned to the operator with the operator's name shown and the current session option code. The cursor will be positioned onto the current code so that the operator may change his/her Special Keys session option.

The operator may alter the Special Keys option code and press ENTER (large plus key, on a PC) to set the new code for this session and also to store the new code on his security system profile so that each time this operator logs on it will automatically be set until it is again changed. If the operator desires to set the new code for this session only, and not to store it for future sessions (log-ons) then he/she may do so by pressing the PF4 (F4 on a PC) key instead of the ENTER key.

There are five valid codes which may be set as the Special Keys option. Any other code will be rejected with an error message. The five valid codes are:

Code Key Meaning

A PA1 return to application menu
CLEAR go to Logo screen

B PA1 go to main menu
CLEAR go to Logo screen

C PA1 undefined
CLEAR go to Logo screen

D PA1 go to MSKDEF screen
CLEAR go to TSKLST screen

E PA1 return to application menu
CLEAR go to main menu

Option D is used only by application developers since the MSKDEF and TSKLST functions are not usually used by non-developer personnel. The Option E (for Easy) is appropriate for novice users since it is very menu oriented.

## Stack Option

The Stack Option is also set on the OPTION screen. It controls how MAGEC will handle a stack overflow which occurs when applications attach to other applications with the ability to return. An example of this is when a full-screen application invokes a pop-up window application. Pressing PF3 in the pop-up will return to the first application. You have several choices as to how to deal with the situation where the maximum number of returns has been saved and another attach is being attempted. The choices will be presented on the screen.

# Security

## Security Officers

There are two levels of security officers, local and central. The local officers are, likely, the departmantal managers and supervisors in the user departments. The central security officers are usually certain select individuals in the central data processing facility.

Local officers can handle all the day-to-day requirements in the user area: setting up new operators, suspending operators who are no longer in the department, disabling and enabling terminals. Their authority to do these functions is limited to their own location (or department).

Whenever operators encounter difficulties with logging on or in accessing functions for which they feel they should be authorized they should first contact the local security officer to try to remedy the problem.

Central security officers have virtually unrestricted authorization and can set up local officers or suspend them and can alter any security parameters for any location. If a problem cannot be solved at the local security officer level then a central officer may be contacted.

In some installations company policy might not allow for local officers. Then the central officers will have to be contacted for any problems first.

## Suspended Operators

Operators may become "suspended" for a number of reasons. They may be suspended by a security officer via an online transaction which takes effect immediately on being received by the system. They may be suspended automatically by MAGEC as they attempt to log on if:

- They have reached the termination date set in the Security File.

- They attempt to log on unsuccessfully too many times in a row.

- They do not use the system (log on) for too many days and MAGEC assumes they are no longer active employees

A security officer will have to be notified to reinstate an operator who is suspended. The automatic suspensions are to protect against unauthorized accesses which might occur if a would-be intruder had an unlimited number of tries to guess a correct password or to find one for an ex-employee.

When the officer looks at the suspended operator's profile in the security system a message on the screen will indicate to the officer why this operator was suspended. The officer may immediately reinstate the operator if appropriate.

## Restricted Access

Each operator has a security profile recorded in the system. In this profile are authorization level codes which designate how high an authorization this operator has in each logical application. Logical applications are defined by the security and development staff. Some possible logical applications are:

`01 General Ledger`

`02 Accounts Payable`

`- et cetera`

The number preceeding each name above indicates a logical application number as it might be assigned by persons who define the logical applications for this organization. As new applications are developed new logical applications might possibly be added. These logical applications are what appear on the main menu screen. When an operator uses the **MENU function (or a special function key equated to it) to request the main menu, MAGEC lists on the screen each logical application which is defined and for which this operator has any authorization at all.

Every function code is defined as "belonging to" one logical application and as requiring some level of authorization within that logical application in order to be accessed. The operator posesses some level of authorization (it might be zero in some cases) in each of the logical applications. Before allowing the operator to access any function, MAGEC checks that the operator's authorization for the proper logical application is sufficient for the function attempted. If it is not, the operator will receive a message in SCOMPL saying "UNAUTHORIZED for "xxxxxx" function".

Whenever an operator requests an application menu, whether it was from the main menu or by keying the $$MENU function code, MAGEC lists functions belonging to the designated logical application. It shows only those for which the operator has sufficient authorization.

In addition to restricting access by operator, MAGEC can also limit accesses made from any given terminal. At the time that an operator logs on at a terminal, MAGEC reduces the operator's authorization levels for any logical application in which the terminal has a lower (lower than the operator's) authorization level specified. This reduction is not a permanent one, it applies only to this session and does not alter the operator's security profile. If such a temporary reduction is made, a message saying so will display on the bottom line of the screen when the operator logs on.

Both operators and terminals may be restricted to use the system only on certain days of the week or times of the day or holidays. An operator will be unable to successfully log on to a terminal if either the operator's or the terminal's security profile does not permit it. The exception to this is in the case of central security officers whose ultra-high authorization levels override many of the restrictions imposed upon ordinary operators and even local security officers.

# Printed Documentation

## The DOC File

The online documentation which is displayed when the operator uses the HELP key (PF1) is stored on a system file which data processing personnel know as the "DOC file". The DOC file can also store other kinds of documentation.

If User personnel desire hardcopy printouts of any documentation from the DOC file, whether it be online documentation or other, a printout can be produced in minutes. The name of the utility program which is used to print documentation is MAGECLBR . It may be run by data processing personnel on request. Full explanation on the use of MAGECLBR is included in the "Offline Utilities" chapter of the MAGEC Programmer's Reference Guide, which the data processing department has copies of. The control card format to print a hardcopy of any topic from the DOC file is:

`-MAGECPRT DOC tttt`

where :

tttt = any valid 30-character topic name

You can view the documentation on the DOC file via the **HELP function discussed under the heading Viewing Documentation earlier in this section.

# Short-Lists

## PF24

When you do any of the browse functions (i.e. LOC, SCN, FND) the program automatically saves a list of the keys to the items found. For example, if you searched for customers named Jones and were returned a display showing five (5) "matches", you could then cursor-select one of the displayed customers and receive either a display or update screen for it. Very often you will next want to go to another of the five "matching" customers to do a similar operation.

You can use the PF24 (Alt-F4 on PC) key to request a display showing the list of matching items; this is called the "Short-List" since it is a brief (up to sixteen items) list of selected items chosen from the much larger list (the entire customer file). The Short-List will display the range of 16 items that were displayed last on the LOC, SCN, or FND screen.

## Pop-Up Window

After seeing or updating the first (or any other) selected matching item, you may press PF24. The Short-List will appear in a small "pop-up" window. You can scroll forward and backward through the list in the window using the PF8 and PF7 (F8 and F7 on PC) keys (as you do in the NXT functions). You can cursor-select any item from the Short-List and press PF24 (Alt-F4 on PC) to be transferred immediately to a full-screen display for the selected item. This works whether you are updating (CHG function) or just looking at (SEE or NXT function) the items.

For example:

CUSFND 1 screen to enter search argument is displayed

enter search arg(s) list of up-to 16 customers displayed

cursor-select a customer full-screen display for selected customer is shown

press PF24 pop-up Short List is displayed

cursor select another
customer from Short List full-screen display for selected customer is shown

etc.

# Mouse Support-PC and LAN

MAGEC for Micro Focus Cobol includes mouse support under MS-DOS, Windows, OS/2, and Unix operating environments. If your MAGEC-generatedapplication is being executed in GUI (Graphical User Interface) mode, a mouse is an integral part of the application's user interface. If your application is being executed in text mode, the mouse is a nice-to-have accessory which takes advantage of the high degree of standardization of MAGEC applications to provide very handy features with no additional programming required of your developers. This topic discusses the mouse in text mode execution.

In text mode, only the mouse cursor position and the left mouse button can be sensed. The right button (and center button, if installed) are ignored. All mouse sensing is handled in MAGEC's Control Program and no code need be added to your applications to operate with a mouse. Any application can be used either with, or without, a mouse.

## PF Keys using Mouse

The first mouse service we will discuss here is the simulation of Program Function keys (PF-keys, or F- keys) using the mouse in text mode (as opposed to GUI mode). It is customary, and consistent with MAGEC's standards, to display PF key instructions on the screen telling the operator which PF keys provide which functions for every screen. The structure of these instrucdtions may vary, but should follow one of several formats which sill be discussed below. If the operator points the mouse cursor onto a screen message indicating the meaning for a PF key, MAGEC will automatically simulate that that key was pressed whcn the left mouse button is clicked. In order for MAGEC to recognize PF key instructions from miscellaneous text displayed, certain rules of form should be followed,. Below is a list of samples which will be recognized by MAGEC's mouse handler:

PFnn=blah-blah

Fnn=blah-blah

nn=blah-blah

nn=blah-blah/mm=this-n-that/pp=something-else

The key numbers may be one- or two-digit numbers. They may be preceded by "F", "PF", or by nothing (a space or a separator character). The recognized separators are: "/" "," ";" "(" or space.

The PF key instructions may be anywhere on the screen, including in SERRMSG (last three lines of screen), and SCOMPL (right half of the top line of the screen), but must be in a protected field on the screen. No PF key instructions will be recognized in a screen field which is unprotected (enterable by the application user). The mouse may be pointed to any character position within the message for the desired key, MAGEC will scan leftward until reaching a space or a separator, then will test for a valid key number. If the message contains embedded spaces and if the user points to the right of a space character, MAGEC will not recognize the key number as being part of the selected message and will ingnore it, assuming that the operator merely wished to position the text cursor where the mouse cursor was pointing when the left button was clicked.

## Pop-Up Error Help

It is another MAGEC standard that error messages be presented in the SERRMSG field (last three lines of the screen). Without a mouse, the operator can press PF1 any time such error messages are shown and will receive an expanded explanation for each error message on the screen. With a mouse, the operator can also point the mouse cursor to any such error message, click the left mouse button, and receive a pop-up window with an expanded explanation for the chosen error message. The pop-up window contains a push button saying "OK". pointig to the push button and clicking the left mouse button will remove the pop-up window. Pressing the CLEAR (Escape) key will also remove the pop-up window, any other keystroke will be ingored. While the pop-up window is being displayed, the error number at the front of the error message chosen will blink to indicate which error message the expanded explanation applies to. The operator can select another error message to get an explanation of it, if desired, after removing the pop-up window for the prior error message.

## Positioning Text Cursor with Mouse

The final function of the mouse in text mode is to re-position the text cursor. If the operator moves the mouse cursor to any screen position (not recognized as either a PF key message or an error message number) MAGEC will re-position the text cursor there when the left mouse button is clicked. Notice that nothing happens until the left mouse button is clicked. Just moving the mouse merely moves the mouse cursor around the screen display, but has no effect on where the operator is typing. The text cursor always controls where the operator's typed data is being entered into the screen.

## Cursor Appearance

The mouse cursor can easily be distinguished from the text cursor by its appearance. Its appearance changes depending on the environment you are operating in. The text cursor is always the blinking underscore character.

You can execute MAGEC under OS/2 (product of IBM) in either full-screen, or window mode. In OS/2 full-screen display mode, the mouse cursor appears as a rectangular block which has the inverse color scheme of the surrounding screen. In OS/2 window mode, the mouse cursor is a black diagonal arrow pointing toward the upper left. This is the standard OS/2 mouse cursor shape.

In MS/DOS (product of Microsoft), the mouse cursor is the inverse-colored rectangular block.

In Windows (product of Microsoft), the mouse cursor is the outlined white Windows cursor arrow pointing (more-or-less) toward the upper left.

If the mouse cursor is the rectangular block, moving the mouse moves the mouse cursor in increments of one schreen character at a time. If the mouse cursor appears as an arrow, moving the mouse moves the mouse cursor in increments of one pixel at a time. All other functionality is identical, as the pixel coordinates are converted into screen character coordinates automatically before being processed.

# Appendix A -- PC Template

On the following page is the MAGEC PC Template, which equates 3270 keys to their PC equivalents.

Listed below are the general use keys that MAGEC uses:

CLEAR Clear screen, display logo (or as altered by Special Keys Session Option)

PA1 Display menu screen (or as altered by Special Keys Session Option)

PF15 Exit MAGEC

PF9 Swap Windows

PF1 General HELP key

PF2 Field-level HELP key

PF16 Copy-to-buffer key

PF17 Paste-from-buffer key

In addition to the keys mentioned above, there may be keys assigned to functions in your session options, or programmed into your applications. Refer to the section in this manual titled Session Options for more detailed information.

Most MAGEC screens will display instructions regarding the usage of function keys at the bottom of the screen. Some instructions may be displayed at the top right corner of the screen, especially in cases where the bottom lines of the screen are already occupied.

## PC Keyboards

Various types of PC's and PS/2's have different keyboards which behave slightly differently from one another. The key equivalents, as shown on the template which follows, will work on all known variations of PC keyboards. In addition, there are some other keys which are supported if you have one of the "extended" keyboards. They are:

F11 equal to PF11

F12 equal to PF12

Bkspc equal to Backspace

Ctrl-up-arrow fast up-arrow

Ctrl-down-arrow fast down-arrow

PC-MAGEC 3270 Emulation Template
| F1 | F2 | F3 | F4 | F5 | F6 | F7 | F8 | F9 | F10 | Pg Dn | Pg Up | + | Esc | End | Tab
CTRL | PA1 | PA2 | PA3 |  |  |  |  |  |  |  |  |  |  |  | Erase EOF |
ALT | PF21 | PF22 | PF23 | PF24 |  |  |  |  |  |  |  |  |  |  |  |
SHIFT | PF11 | PF12 | PF13 | PF14 | PF15 | PF16 | PF17 | PF18 | PF19 | PF20 |  |  |  |  |  | Tab Left
| PF1 | PF2 | PF3 | PF4 | PF5 | PF6 | PF7 | PF8 | PF9 | PF10 | PF8 | PF7 | ENTER | CLEAR | RESET | Tab Right

Use this template to convert mainframe 3270 keys to their PC equivalents when using PC-MAGEC. The following keys all have the same meanings in both environments:

- HOME key
- RETURN key (sometimes labeled ENTER) (move cursor to beginning of next line)
- INSERT key (Ins)
- DELETE key (Del)
- the "arrows"

For compatibility with some other PC software, MAGEC will accept the "large plus" key (in the numeric key pad) as equivalent to the mainframe ENTER key (this does not apply to the "+" key which is above the alphabetic keys and which you must shift to use). The Ctrl-Return key combination is also equivalent to the 3270 ENTER key.

# Appendix B -- GUI Objects

MAGEC applications can be executed in a Graphical User Interface (GUI) mode if you are on a platform which supports graphics. If you are using MAGEC in GUI mode, certain standard menu items, icons, and pushbuttons will usually be built into your application. The following pages depict the most important of those. It is possible for the application developer to design graphical images and features, and to add them to the applications as customization. It is also possible for the developer to exclude some or all of the standard objects from any given application. The following pages discuss the standard, MAGEC-generated GUI objects.

## GUI Icons

The GUI version of MAGEC has been replaced by the LAMP-Stack Magec! Documentation remains here in case you happen to be still using it. If you wish to press a PF key which is not otherwise represented by an icon, you can select the "KEYS" icon. A pop-up "keyboard" containing all of the PF keys will be presented. You can then select the desired pushbutton for the PF key you want to press.

The ENTER key is used to process updates, to select from lists, et cetera. You can select this icon - or press ENTER (RETURN).

The GUI Color Options Panel (GCOSEE function) can be invoked by selecting the "Colors" icon. From this panel you can control the foreground and background colors for text displays on the application screens.

High-level (Function-level) help can be retrieved via PF1. You can click this icon or press F1.

Field-level help can be retrieved via PF2. You can select this icon or press F2.

The PF3 key is the ESCAPE-BACK key throughout MAGEC. You can select this icon - or press F3.

From a "maintenance screen" (i.e. xxxCHG, or xxxSEE function) you can press PF4 to start listing items (xxxLOC function) beginning with the current key value. You can select this icon - or press F4.

From a "browse screen" (i.e. xxxLOC, xxxSCN, xxxFND functions) you can point to an item and use PF4 to transfer to the change (xxxCHG) screen for that item. You can select this icon - or press F4.

PF7 can be used to browse backward from any browse display, and from most inquiry (xxxSEE) displays. You can select this icon - or press F7.

PF8 can be used to browse forward from any browse display, and from most inquiry (xxxSEE) displays. You can select this icon - or press F8.

PF9 will swap MAGEC windws. You can have two MAGEC sessions active and swap between them. You can select this icon - or press F9.

PF11 can be used to invoke a menu-driven search for online documentation. You can select this icon - or press Shift-F1.

PF13 can be used to generate a printed report or screen image from any MAGEC application. You can select this icon - or press Shift-F3.

PF15 is used to exit MAGEC and return to the operating environment (i.e. Windows, etc.) You can select this icon - or press Shift-F5.

The PF16 key can be used to copy (cut) data from a screen into a copy/paste buffer. You can select this icon - or press Shift-F6.

The PF17 key can be used to paste data from the copy/paste buffer to the screen. You can select this icon - or press Shift-F7.

From any browse or query screen, the ENTER key can be used (after pointing the cursor to a listed item) to transfer to the inquiry screen (xxxSEE function) for that cursor-selected item. You can select this icon - or press ENTER (RETURN).

## GUI Menus

## GUI Color Preferences

MAGEC application users who are executing in a GUI environment can set their personal color preferences for screen data display. To set preferences you can use the command:

`GCOSEE`

There is no key value needed for the GCOSEE function since MAGEC will automatically use your Employee number (from your SYSLOG ON) as the key value, i.e. GCOSEE 000000018. GCOSEE can be done in a text environment , or in a GUI environemnt; but, you will not be able to veiw the results of your changes unless your are in a GUI environment.

You can only set preferences for the Employee number you are logged on as at the time. If you have more than one "logon ID", you must set the preferences for each individually. You preferences are saved in the repository (on the GCO file) using your Employee number as the record key.

If you have never yet set any preferences, MAGEC uses default settings which should work acceptably well for any but the most severely colorblind users. Once you set any preferences a record is created for you containing your settings, with default values for those combinations you have not specified.

In order to effectively control your screen colors you must first have a little understanding of how the system works.

A MAGEC-generated application can be executed in either text mode or GUI mode interchangeably without modifying or "re-compiling" the program; therefore the programs operate using only the basic text-level color controls. Your GUI color preferences translate those text-level color controls into GUI color combinations. Every GUI panel has a background color. That color may be specified when the panel is initially created. Text-based screens have a background color of black only. Obviously, some combinations of text colors and background colors will be more pleasing and easily read than will others. This can vary from one individual to another, also.

Your preferences are coded as: "when the application program issues this text color, and the GUI panel background color is that color, then display it as such-and-such (which is a combination of a foreground color and a background color). There is one other variable which we omitted from the above description of your preference coding; it is the "emphasis code". This is merely a yes or no (Y or N) code indicating whether the application program is trying to emphasize (highlight) this field on the screen. In text mode, emphasis is normally accomplished by increasing the brightness of the field, changing its color, reversing the foreground and background colors (reverse-video), underlining the field, or causing it to blink. Which method is employed depends largely on the type of terminal or monitor equipment being used and its inherent capabilities. MAGEC has the built-in capability of automatically converting any of the various highlighting options into appropriate ones for each particular type of hardware, thus relieving the application programs of having to handle different display types internally.

Perhaps the most common type of text-based hardware includes a built-in color scheme which helps identify protected and unprotected (enterable) screen fields, and indicates which fields are being emphasized. This color scheme, being the default of the hardware, is a generally-accepted standard which has been proven to work well in almost all applications. It is helpful to know this standard when setting your GUI color preferences since most of the data fields on most of your application screens will probably use these colors by default.

The standard default colors are:

`UnProtected, no emphasis Green`

`UnProtected, with emphasis Red`

`Protected, no emphasis Blue`

`Protected, with emphasis White`

In order to help you to set your preferences for these standard colors more quickly, GCOSEE provides PF keys (and toolbar buttons, in a GUI mode) for each of these settings.

When any GUI panel is being generated, the developer can specify what background color that panel is to have. The default background color is White (actually, a light grey color -- True white, as you and I know it, is called: "Bright White"). The GCOSEE PF keys and toolbar buttons for each of the standard text colors also assume a White background.

Now, let us suppose that you are looking at a GUI panel for an application. Assume that the panel is White (default background color), and that the enterable (unprotected) data is being displayed in green (the default color for unprotected, non-emphasized data). Suppose that you do not like the appearance of this green-on-white display and would like to change it to appear as blue-on-white.

To enable you to quickly alter the preferences and then re-view your application display using the new settings, you might wish to swap MAGEC windows. This will give you two active windows, one for doing the GCOSEE function, the other for doing your application function. To swap windows you could press PF9, or in a GUI environment, mouse-select the SWAP icon from your toolbar.

On the GCOSEE screen, you would then type in the display color combination you wish to alter. This is done in the top three parameteres. In the example given, you would type "2" for Green into the text color parameter, "N" for no emphasis into the emphasis code, and "7" for White into the GUI panel background color parameter. Then press ENTER.

NOTE:

- In a GUI environment you could have accomplished all of the above by merely mouse-selecting the UNPROTECT REGULAR icon from the toolbar on the GCOSEE screen.

On the GCOSEE screen, just below the three parameters you filled in, MAGEC will display the GUI foreground and beckground color combination being used for the combination of parameters shown (where you typed them) above. Descriptions will be shown to the right of each code to help you to correctly interpret it.

NOTE:

- You will likely notice that the default settings specify a GUI field background color which is the same as the panel background color for all non emphasized data, and a field background color which contrasts with the panel background color for all emphasized data. You can alter this at your discretion, this is merely a convenient pattern which is readily understood by most users. You may prefer to use a contrasting background color for all enterable data, whether or not it is emphasized, or any other scheme that might help you to read the screens more quickly and accuarately.

You can now alter the values set into the GUI foreground and / or background color settings (the lower two parameters on the screen) and press ENTER; i.e. type a "1" for Blue into Foreground color. Your profile record will be updated -- the changes take place immediately.

Now, swap windows back to the application screen you were looking at originally. This can be done by pressing PF9 again, or using the GUI icon. You should now see the same display as before, but with the new color combination used for unprotected, non-emphasized data.