Introduction

---

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:

As well as any other individuals in the organization who might come in contact with MAGEC or the application systems developed using 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:

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.

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.

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.

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).

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.

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 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.

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.

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.

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:

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.

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

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.

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.

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:

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 (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:

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.

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).

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:

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.

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.

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:

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:

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.

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.

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.

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:

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.

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.

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.

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.

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.

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.

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.

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

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.

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:

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.

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:

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:

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.

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.

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.

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.

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:

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.

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:

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

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.

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.

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:

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.