Revision 2
September 25, 1992
The Natural Secured Menus Architecture (NSM-A) is both an approach for designing and developing online Natural applications and a collection of tools and facilities to assist in that endeavor. It has been designed to provide:
The NSM Architecture also provides a high level of commonality between applications so that training requirements of individuals who use or maintain multiple NSM applications is reduced significantly.
These Functional Specifications were prepared in order to provide a clear and concise definition of the NSM Architecture. This document is intended to provide all the information necessary for an individual to develop an application using this architecture. The UAF Program Generator functional specifications should also be consulted since that facility automates the creation of most program code for an NSM application. Additionally, portions of this documentation will assist individuals in using applications that have been developed in the NSM Architecture.
Features of the NSM Architecture include:
The University of Arkansas acquired Natural and other Software AG products in the Summer of 1986. The first Natural applications developed used their own approach to menu design and relied upon the security features of Natural Security. Through the Third Annual SAG University/College BIG User's Group Conference, UAF was exposed to John Wheat of the University of Texas and their Command-Driven, Menu-Augmented (CDMA) approach to applications development. Due to the many benefits which accompanied CDMA, this technique was used in the development of two applications. There were still many drawbacks, however. The system relied upon Natural Security, which was difficult to administer, and menus included all commands even though they might not have been valid for a user. Building on the CDMA approach plus adding ideas gleaned from other SAG user group conferences, the design of the NSM Architecture was begun in late 1987. The architecture was used in an application and continued to evolve through the first half of 1988. A complete definition of the NSM architecture was developed by the Fall of 1988 and all new Natural applications were being developed in NSM.
Significant enhancements were implemented in 1992 to create version 2 of the architecture. The core architecture changes were primarily made to support the suspend function. Most other enhancements were made to the model function modules used as the base for building NSM applications. A program generator was also specially designed to use these new function module models (see the UAF Program Generator Functional Specifications).
A parallel and related development is the NSM Maintenance System. The NSM Architecture relies upon nine logical data files. The NSM Maintenance System (NSM-MS) was designed to provide the necessary maintenance facilities for these files. The specifications for the NSM-MS were prepared in the late Spring and early Summer of 1988 and development completed in early 1989. In 1992, NSM-MS was converted to use version 2 of the NSM architecture. In June 2001, the transition was made to position based desk assignments which necessitated changes to NSM-MS and to some core components of the architecture.
Additional information regarding the NSM-MS application is available in the Functional Specifications for that system.
Commands provide the transportation for traveling to various destinations within an application while menus serve as road maps. More precise definitions for these components are:
Control is passed from one function or menu to any other by entering the desired command. A command will usually require only one screen, however some complex functions may require several screens or windows.
When a value is entered in the Command field,
it is validated and results in an error
message, display of the menu requested, or transfer of control to
the requested function associated with the command. If a command
is entered and PF2 is pressed, the current function is
suspended while the new function is executing. PF3
returns the user to the original function at the point of
suspension.
A menu contains an area where a command can be entered, an area where key field values may be specified, and a list of valid and related commands. The list of commands is accompanied by descriptions and identification of any required key fields for the commands. Commands may be selected in any of three ways:
Command.CMD within the list
in order to mark it for selection.CMD and the Enter key pressed.Values may also be entered into any of the key
fields that appear in the top portion of the screen (the
banner). Key field values which are entered on the menu will be
passed to other programs and thus speed up the operation of the
system by allowing the command and key field specification to be
entered in one step. The Required key fields column on the menu
identifies the key fields which are used by each command.
See Figure 1 for a sample menu screen from the NSM Maintenance System.
Enter, mark or position cursor to desired command
NSOMENU 1 TEST nsm maintenance system Main Menu - MM 01/04/01 09:34
Command: Action: V Desk: Appl: Cmd Sec Grp:
Val Sec Grp: Parm:
-------------------------------------------------------------------------------
CMD Command description Required key fields
---- ---------------------------------------- ------------------------------
_ LAAC List All Available Commands Command ID
_ MHAC Menu Hierarchy of Available Commands --none--
_ DAM Desk Administrator's Menu
_ ISM Initialization and Setup Menu
_ AAM Application Administrator's Menu
_ HELP nsm-ms system level HELP
_ CDCD Change desk/Display Current Desk info
_ LOG LOGon to another natural application
_ FIN FINish your session (sign off natural)
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
Help Quit
|
Most online functions require one or more key field values to be specified in order to define what is to be done. These values usually define what record or records are to be operated on and/or what operations are to be performed. The required keys are normally output modifiable fields in the top portion of the screen, the area above the dashed line known as the banner area. Once a value is entered in a key field, it is retained until another value is specified. In this manner, several commands may be accessed to operate on the same entity (a student) without re entry of the key (student ID).
The required key fields for a function define what is to be
done. These fields, and their corresponding tags, appear
intensified (or in a different color) within the banner area so they can be easily
identified for each function. The entry of new key values is
treated as a request to initiate a new operation within the
current function and/or to perform that operation on new data. If
a data base update was intended for the previous key values, it
would not be completed unless PF10 had been pressed. However, a
warning message is issued if modifications have been made but not
saved and new keys and/or a new command is issued. When the key
values specified are not valid, an appropriate error message is
displayed and re entry of the erroneous field requested. In this
manner, the current function module is used to perform various
operations on records until another command is requested by
entering a Command or exiting from the function module via PF3, Quit.
The banner area may contain one or two lines for the key fields. When possible, the format and content of the banner area should be consistent on all screens, i.e. the same key fields in the same place with the same tag. This is often not possible since there is a limited amount of room in the banner and some applications will utilize many key fields for various functions. A technique to accommodate this situation is to place the most common fields in the banner and leave space in one area for unique fields needed by only one function module. This method, however, prevents those unique key fields from being passed from the menu or from other functions. This quandary is addressed by providing an alphanumeric parameter field in the banner, defined as input only. Functions which utilize unique key fields then determine if there is a value in the parameter field, edit it for format consistency, and move it to the unique key field. When calling these functions from other function modules or a menu, the desired key or keys is then entered into the parameter. See Figure 2 for the banner area from the menu of an application using this technique and Figure 3 for the banner as it appears in a function module.
Figure 2.
Sample menu banner with parameter
DAMMENU TaBLe maintenance - TBL 02/17/89 16:52
Command: acct Act: v ISN: SSN: Date: 02/17/89 Dept:
Parm: aaaa DcReg: Pd#:
-------------------------------------------------------------------------------
|
Figure 3.
Sample function module banner with parameter
DAMACCT ACCount Table maintenance - ACCT 02/17/89 16:53 Command: ____ Act: V ISN: SSN: Date: 02/17/89 Dept: Account Cd: AAAA Parm: DcReg: Pd#: ------------------------------------------------------------------------------- |
| Action Value | Description |
| A | Add |
| U | Update |
| V | View (read only) |
| D | Delete |
| C | Copy (effect either an Add or an Update) |
All input data is checked and edited for accuracy (to a degree) prior to it being accepted and stored on the data base. This is accomplished through the execution of validation rules. When the user enters or modifies data on a screen, the execution of these rules may result in an error message. Error messages are displayed within the Natural message line and the cursor is placed on the field associated with the error. The user is not allowed to save the changes to the data base until the error is corrected.
In multiple screen functions, it may be required that data be entered and validated on several screens. In this situation, PF10 will not be labeled "Save" until valid entries have been made on all screens other than the current screen. The system will also prompt the user, identifying the screen number, when valid input data is required on a different screen (given the current screen passed all edit checks).
Warnings are messages displayed to the user for information purposes. They appear much like error messages, but always start with the the text "WARNING:". Unlike error messages, however, warnings are issued only once for the same screen, key fields and cause. One screen may issue many different warning messages for different reasons (causes).
An example of a situation where a warning would be issued is when a user makes changes to the data on a screen and then requests another command. Because PF10 was not pressed, a warning message is displayed that informs the user that the changes that have been made will not be saved. The user then has the option of pressing ENTER again to execute the command (and lose those changes), press PF2 to suspend to the requested function, or press PF10 (which will save the changes and then execute the command requested). If the user opts to suspend the current function, changes will not be lost. However, when the user returns to the suspended function, any other action that could result in the loss of modifications to the current record (e.g. PF3) will NOT result in a warning message. The warning for that reason for the keys being operated on has already been issued. Once a warning has been given, the user is allowed to proceed at his or her on discretion.
|
Key & Name |
Usage |
|
Enter |
If new key field values or a new command have been entered, initiate processing for the new keys or the new command issued. Otherwise, validate any entries made in the body of the screen and prompt for the next activity. |
|
PF1 (Help) |
Initiate help processing. This will be field help if the cursor is on a field defined with a help routine; otherwise, screen level help will be provided. |
|
PF2 (Suspd) |
Suspend the current program and transfer control temporarily to the requested function module. Entry of a command is required. Suspend is not valid from a menu. |
|
PF3 (Quit) |
Quit the current operation and back up one level in the processing hierarchy:
|
|
PF4 (DCode) |
Decode selected coded values on the screen by performing lookups and displaying associated names, descriptions, or other information. This key may also be used to explode a selected entry by displaying within a window more detailed information than was available on the original screen. |
|
PF5 (RStrt) |
Restart the operation with the keys specified in the banner area (disregard any changes or entries made within the body of the screen). On list functions, any previously marked entries for selection are cleared. |
|
PF7 (Back, PrevS) |
Page backward to values or previous screens displayed within the same function module. |
|
PF8 (NextS, NextR, NextT, Q/Nxt, Forwd) |
PF8 always moves the user forward to access the next set of data, although the key is labeled and the function is performed in a different manner dependent upon the circumstances.
|
|
PF10 (Save, Sav/Q) |
PF10 is the commit key. No changes are effected or permanent action taken within an NSM application unless PF10 is pressed. It will save onto the data base any changes that have been made or data that has been entered. It may also commit or finalize the action being performed, such as submission a batch job for processing based upon the specified parameters. Within a function module operating at level 2 or 3, the key is labeled "Sav/Q" to save the changes and then quit that function and return to the suspended function. |
|
PF11 (Options) |
This key is provided for the selection of options that may be available in individual function modules, or may indicate a specific option when further selection is not required. |
|
PF12 (Print, Email or Flip) |
On lists where a print function has been associated with the
listed items and the user has selected (by default via the user
profile or use of the |
|
PF24(Flip) |
This key flips the display of PF keys to show PF1 thru PF12. |
Data base updates are only performed in response to an explicit request. Pressing the ENTER key will cause all inputs to be validated, but it does not result in any data base change. Any input errors will be reported and the cursor placed on the invalid field. When all inputs are valid, a prompt will be displayed indicating that the entries should be saved by pressing PF10. Pressing PF10 serves as the explicit request to perform an update. Following all updates, a confirmation message is displayed indicating the action that has been performed. This confirmation will override the line of the screen containing the program name, program level, and function title (normally line 2 of the screen).
If a user is confident of his input and speed is essential, input data may be entered, new keys and/or another command specified, and PF10 pressed in the same step. If there are input errors the result will be the same as if ENTER were pressed; otherwise the update will be performed, the confirmation displayed, and the new keys and/or new command processed. If the only error is with a new key specification or command id, the update is performed, the confirmation displayed, and the appropriate error message displayed. This technique provides the power user with an alternative data entry method that supports fast and efficient operation in the production environment.
There is a special class of NSM functions designed to list information from the data base. These are inquiry only functions (no update capability) which allow browsing and selecting data online. There are several variations of these list functions, but they all share the following features and characteristics.
Employees 11 thru 20 of 39 displayedThe starting keys used to retrieve the data are also displayed immediately below the banner.
The suspend feature allows a user to access a second or third function while still retaining in a suspended state the activity within the original function, including any data entered prior to the suspend request. The ability to suspend is most useful in the following situations:
The suspend feature is invoked by entering the command and desired keys for the new function and then pressing PF2. The current function will be suspended temporarily, and the new function module will be invoked. PF3, PF10 and sometimes PF8 will return the user to the suspended function and restore the key fields to the values which were previously in effect. A warning message is provided whenever a user's actions would cause a suspended function to be lost (e.g. enter a command without pressing PF2). Three active levels are permitted, but suspending to or from a menu is not allowed. The level at which you are currently operating is displayed on the first line of the screen as the second element (just after the program name).
List functions are designed to allow selection of one or more entries from the lists provided. Values selected may be placed in the banner key fields so that they may be used to specify additional processing by other commands or the selection may be used to "decode" or explode the entry by displaying additional information about it within a pop-up window. The selection is made by marking an entry by entering a non-blank character in the field that precedes each entry of the list. If only one entry is to be selected, the cursor may simply be placed on the line of that entry. PF4 can then be pressed to decode the selected entries or another command entered to operate on the key fields selected.
Selection of listed entries is very helpful in conjunction with the Suspend feature of the NSM Architecture. Another command is entered, the desired entries are marked, and PF2 is pressed to effect the suspend function. In this case, the first marked entry is placed in the banner for operation by the requested function. PF8 is then used to retrieve the next marked entry until either PF3 (Quit) is pressed or there are no further selections. At that time, the suspended function is again presented.
On multiple screen functions, there are two ways a user may scroll through the screens. PF7 and PF8 are used to page back or page forward one screen, respectively. Secondly, an explicit screen number can be entered in the field beside the label "Screen," the field directly below the banner that also displays the current screen.
A great deal of data stored in computer systems is coded to reduce the time required for entry and the space required for storage. Often times there exist tables where coded values are stored along with descriptive text that identify the meaning of the codes. These tables are used to validate the data upon entry and to translate codes to descriptive and meaningful names on output.
In an on-line environment, system efficiency is critical and access to tables consumes scarce and critical data base resources. For this reason, descriptions associated with coded values are sometimes not automatically accessed and displayed on-line. This information is, however, available upon request. The method for requesting the de-coding of coded values is by pressing PF4 whenever this key is labeled "DCode".
In addition, the de-code function may be programmed to do more than just look-up descriptions for codes that appear on the screen. In some situations it is also used to explode data -- to access much more complete and detail information and display it within a window. This is often the case when there is a list of summary information displayed. A specific entry may be exploded by placing the cursor on the desired entry prior to pressing PF4.
There are four special types of data fields which are used on NSM on-line screens. These are:
|
Field Type |
Description |
|
Modifiable Default |
Fields that are modifiable but which are not being emphasized and are therefore displayed with default intensity. |
|
Modifiable Intensified |
Fields that are modifiable and are displayed intensified (bright) for emphasis. |
|
Conditionally Protected |
Fields for which update would normally be allowed but due to certain conditions have been conditionally protected and may not be modified (e.g. a view or delete action is being performed or an error exist in the key specification). |
|
Previous Value |
Fields that show a previous data value prior to an update transaction being entered (as opposed to the proposed value which represents the change being effected by the transaction). Previous value fields are used in TARGET functions. |
These field types have associated attributes and colors that can be customized by the user via the user profile. For instance, a user may prefer that all the modifiable default fields be shown in reverse video (i.e. the attribute) and in the color green while modifiable intensified fields are displayed in reverse video turquoise. If your terminal supports reverse video, that attribute is suggested for previous value fields since it will allow detection of a prior blank value.
The desk concept permits several individuals to be associated with the same desk when they perform the same job (e.g., registration data entry operators). However, the norm is one desk is associated with one individual since most jobs are unique. In addition, one employee is typically associated with only one desk. That desk is the employee's primary desk. An interim desk may be assigned in exceptional cases when an individual is asked to perform two jobs on a temporary basis. A user who is assigned to two desks is required to explicitly identify which desk he will be working at any one time. It is recommended that this dual desk feature only be used in situations where there are true interim assignments.
The association of an employee with a desk is based upon the type of employee and the type of user ID. For appointed employees with one primary user ID this is accomplished by assigning the desk to the PSB position the individual is filling or hired into. Some appointed employees have secondary or temporary user IDs for the purpose of loaning those IDs out to temporary employees on a short term basis. Desks for these IDs are assigned directly to the User IDs. Similarly, desks for hourly employees and non-University employees that require access are also assigned directly to their User IDs.
Application access privileges and required electronic transaction review and approval are determined by the employee's desk assignment. A discussion of these two separate uses of desks follow:
Desk-based security allows the access rights to all necessary applications to remain the same, regardless of who is filling a position (assigned a desk). The department head requests access to an application for a desk. The application owner establishes and maintains the access rights for a desk to an application. The department head can assign as many employees as desired to work that desk. When a user signs in with his individualized ID, the system automatically makes the association of that user/employee with the established desk assignment. The access rights and privileges of that user are those established for that desk.
For the purpose of routing electronic transactions for approval, a desk may be established as a review point for those transactions. The necessary routing definitions for electronic transactions are determined by the University administration, and are rather complex and voluminous in nature. The use of a desk ID to define a review point for a transaction permits the reassignment of personnel to be accommodated without requiring the redefinition of the routing information.
A user of online Natural applications must be issued a CICS ID. This User ID is assigned to the individual employee and should not be shared or assigned to someone else. When your department hires a new University employee who requires access to Natural applications, a CICS ID must be requested from Computing Services. This ID provides an audit trail of the activity performed, such as who updated a record, who initiated a transaction, and who reviewed a transaction.
A User ID can have one of three possible codes for its status: active, inactive, or temporary. Active status indicates the user is an active employee on the University's payroll system. (There is an exception for certain individuals who are not employees but have been granted access to University administrative systems.) Inactive status is set for a user who is no longer active on payroll and is therefore no longer authorized to access computer applications. Of course, desks cannot be assigned to inactive users. Temporary IDs are special types of IDs that are designed to fill the need of temporary workers. Temporary IDs are assigned to be the responsiblity of a supervisor in the department. That supervisor then distributes the ID and its password to the temporary worker. When the temporary worker leaves, the supervisor changes the password so that security is maintained. The supervisor is responsible for the actions performed by users of temporary IDs.
Active and temporary User IDs are associated with a budgetary unit based upon their type of employment, either appointed or hourly. Appointed employees are hired into a position which has been allocated to a budgetary unit. Hourly employees must have an active wage rate established for the budgetary unit in which they work. This budgetary unit association plays a significant role in the desk assignment process.
A desk is created for and designated as belonging to a specific budgetary unit. It may then be assigned to either a PSB (Personal Services/Budget) position (for appointed employees) or to a user ID (for hourly employees, temporary User IDs, or non-employees) which is associated with the same budgetary unit. These desk assignments are time stamped -- each has a designated beginning point in time and ending point in time (12/31/2099 designates an undefined ending period). Future assignments can be entered or changed, while historical assignments are frozen in order to provide an historical record of all desk assignments. The user's desk for a session is then determined by the system at signon using these desk assignments. This determination is based upon the status of the User ID according to the following steps.
This system has the primary advantage that for appointed employees, no maintenance is required when an employee leaves and the position is later filled by another individual (other than obtaining a CICS User ID if necessary). Further, access is automatically discontinued upon termination or transfer within the University, either for an appointed employee no longer assigned to a position or an hourly employee whose wage rate is inactivated.
The Natural Secured Menus (NSM) Architecture is a standardized approach for designing and developing online applications in Natural. The NSM Architecture includes several Natural subprograms and template objects which perform functions common to all applications. Each of these components is presented later in this section. A program generator is also available so that application function modules can be quickly and efficiently created using the most up-to-date NSM standard models. (See the UAF Program Generator Functional Specifications for more information).
The NSM Architecture is data based and requires the maintenance of information pertaining to applications, menus, users, desks, and security restrictions. It is intended that the responsibility for maintenance of this data be shared between the central data processing organization, the designated application administrators (also referred to as the application owners), and the departmental desk administrators. The NSM Maintenance System has been designed to provide this division of responsibility.
The general flow of control through all NSM v2 Architecture systems is the same:
FETCH RETURN to the new function. A PF3 will return to any
suspended function or, if none, invoke the menu program and
display the menu containing the current function module
command.This process is depicted graphically in Figure 4.
Figure 4.
Processing Flow of an NSM Application
The NSM Architecture utilizes nine logical files. These files are defined within the Predict Data Dictionary. Detail information from the data dictionary has been made available in the file and data element definition and the file and element summary. A summary description of these files follows.
|
File |
Description |
|
APPLICATION |
Contains information related to the online applications: application ID, application name, main menu command, notices, valid actions and security levels, application owners, etc. |
|
APPLICATION-DESK |
Identifies the desks that have explicit access to the application and the type of access: security level, command security group, value security group, and job classes permitted. |
|
APPLICATION-USER |
Identifies the users that have accessed an application and the last date of access. |
|
COMMAND-SECURITY |
Identifies the command security groups that have been defined for an application and their associated command restrictions. All desks defined to access an application must be assigned to a command security group. |
|
DESK |
Contains information related to desks which are created by departments to define the roles or computer usage needs of their personnel. Information contained here includes desk ID, budgetary unit, and short and long descriptions. |
|
DESK-ASSIGNMENT |
Contains time stamped (beginning and ending effective date and time) desk assignments for positions or user IDs. |
|
MENU-COMMAND |
Contains the information for each menu within an application: the menu command and description, and the commands, descriptions and required fields for each command on the menu. |
|
USER |
Contains information related to users of the online systems: user ID, name, SSN, preferred field attributes and colors, etc. |
|
VALUE-SECURITY |
Identifies the value security groups, if any, that have been defined for an application and their associated value restrictions. The use of value security is an optional feature. If used, all desks established with access to the application must be assigned to a value security group. |
SYSTEM library. A template global data area and the
map used for menus are provided and must be installed in the new
application's library, renamed and then modified for the specific
application. The 'xx' within the names of these components is
replaced with a standard application prefix used at the
University of Arkansas. All maps and local data areas for the
individual functions must be built by the programmer, but
guidelines and models for these are also provided. This process
is described further under the heading "How
To".
The entry module is easily generated using the Natural ISPF edit macro PGZENTRY.
NSNREADU is a utility program which takes as
input a user id, looks up the id on the USER file, and returns
the user's name in first-middle-last name sequence.
Note: The Type on the MENU-COMMAND file for
these commands must be 'U'.
|
xx |
The application prefix as defined on the APPLICATION file. |
|
O |
The UAF standard for online programs. |
|
cccc |
The command ID. |
|
xx |
The application prefix as defined on the APPLICATION file. |
|
M |
The UAF standard for map names. |
|
cccc |
The command ID. |
If the function contains more than one screen, it is required that the map names be in the format xxMccccn, where n is the number of the screen. If the command id is less than four characters, the remaining characters must be filled in with dashes ('-'). For example, for the two-screen function associated with command U (User maintenance), the map names are: NSMU---1 and NSMU---2.
Note: Maps used for decode also can follow the format xxMccccD, whereby the remaining positions of a command id (if less than 4) are filled in with dashes (e.g. NSMLAO-D is the decode map for the NSM-MS list function LAO).
These general characteristics may be customized by a user in his user profile by selecting an attribute and color for fields characterized as follows and retained in the control variable indicated:
| Description | Control Variable |
| Modifiable default intensity | #MD-FA |
| Modifiable intensified | #MI-FA |
| Conditionally protected | #CP-FA |
| Previous value | #PV-FA |
The required banner key fields use the control variable #MI-FA, while the remaining key fields use #MD-FA. On the menu, only the 'Command' field should be intensified (#MI-FA).
There are other control variables used in the standard NSM models and are required on elements within the body of the map. See the Program Generator Functional Specifications for further information.
Attempts should be made to limit each function module to one screen, but the model for multi-screen function modules will effectively handle from one to four screens. For function modules that do require more than one screen, separate maps are necessary, but no other irregular changes to the model or the generated program need to be made. The primary issue is to not establish one screen for entry of key fields and another to operate on the associated data. The purpose of the banner area is to avoid this design form.
The attributes of the fields within the body of the screen are established dynamically via control variables that are set by the program dependent upon the situation. Additionally, PF Key names are set based upon the circumstances and appropriateness of each PF Key. A skeleton of a standard multi-screen function module using this technique for traditional file maintenance is:
initialize program variables
processing-loop.
initialize loop variable
decide for every condition
command-id issued
process the command
new keys issued
initialize new key variables
validate action
access primary data base record(s)
validate data base key fields
set prompt
initialize NSM and screen values and screen
validity switches
none (no new keys or new command)
set next prompt
end of decide
conditionally set dynamic field attributes and
perform file dependencies and auto de-codes
conditionally set pf keys
input using map with prompt and confirmation
based on value of screen number requested
Process based on PFKey
Conditional quit and return to lower level function
end processing loop
The models used by the program generator conform to this
structure. See the functional specifications on the UAF
Program Generator for additional information.
Provision should be made to translate coded values which appear on a screen and display their associated descriptions. These descriptions are typically obtained by reading tables and must be provided for those users that are unfamiliar with the codes. However, this translation should only be performed upon request or when the description is already being accessed. This reduces the system overhead associated with these data base accesses to those situations where required. This function can also be used to explode an entry by displaying within a window more detail information than could fit on the base screen. PF4 is the standard means for making the de-code request.
Note: If using a window for de-code functions, it is standard practice for the only valid PF-Keys to be ENTER and PF3. No PF-Key validation rules should exist on these window maps since the window will be closed regardless of the program attention key pressed.
In some instances it is desirable to allow special options for the entry of a field. A date value is a prime example since input may be desired with or without delimiters between month, day, and year and with a two digit or a four digit year. This capability is provided by allowing entry into an alphanumeric equivalent field on the screen and translating this value to the native field format desired. This extra processing and coding is justifiable to avoid use of the Natural edit mask on modifiable data and to provide multiple input formats for the same data. The edit mask is avoided because the resulting error message from data entered in an incorrect format is cryptic and does not indicate the format that should be used. Multiple input options for a value are provided as a user convenience and can greatly speed data entry when formating characters are omitted.
There are a few common considerations and standards regarding the use of alpha equivalent variables.
Alpha equivalent variables are defined in the global data area's BKF group if the the corresponding native fields are banner keys. However, if they are not banner keys, these fields should be defined in either the MSE or a special AEV group within a function's LDA. Defining function specific alpha equivalent variables in the LDA's MSE versus AEV group is generally a matter of personnel preference; however, they cannot be in the MSE of TARGET functions.
The alpha equivalent value displayed on the screen must match the value of the native field and conform to a default presentation format. This is handled in one of three ways dependent upon whether the native variable is a banner key field, an MSE element whose value only changes based upon direct user input, or an MSE element whose value may be changed by program assignments. Furthermore, due to the suspend feature, the alpha equivalent of a banner key field must be defined at the end of the SKS to ensure the proper restoration of its value.
Banner key fields are often programmatically set based upon user selections and options. In order for program assigned values to be displayed correctly in their alpha equivalent variables, the alpha values must be assigned before the map is presented. This assignment normally involves MOVE EDITED statements for each alpha equivalent variable. The standard for these assignments is to code them in the copycode aaCSETAE and INCLUDE this object where required. This copycode is included in different places dependent upon the model used.
Non-list models: For a non-list model, there are two possible situations where banner keys have been set programmatically and in both situations #NEW-KEYS is true. To ensure that the alpha equivalent values are correct in these circumstances, the INCLUDE aaCSETAE statement should be placed in the NKRESET modifiable block. In fact, the program generator generates this statement but leaves it commented out.
An example of a non-list function with banner key AEV fields is LVOMB in the LEAVE library.
List models: For a list model, there are also two possible situations where banner keys have been set programmatically; however, the circumstances and solutions are different.
For an example of a list program that contains a banner key field that has an alpha equivalent value, see TAOLDPD in the TARGET library.
Due to the suspend function, there is also a need to restore the alpha equivalent value for a required banner key. On the function to which the user suspended, he may change the value of the AEV banner field. To ensure that the original alpha equivalent value for that required key is restored upon the return from the suspend, that AEV field should be included at the end of the SKS fields (beyond the bytes redefined as #SEARCH-KEY) in the function's LDA. Here they will be preserved by the MOVE BY NAME BKF TO SKS so that they may later be restored upon the return from a suspend via the MOVE BY NAME SKS TO BKF.
If the above steps are followed, the alpha equivalent values displayed in the banner of all functions will always match the native values actually being used by the programs prior to map presentation.
MSE elements that use alpha equivalent variables and are only altered via direct user input should be initialized whenever the keys change. This can be done any time after the MSE values are established. It is recommended that the statements that initialize these variables (MOVE EDITED or others) be placed in the INITVAL modifiable block. From this point forward, the alpha equivalent values will be maintained in sync with the native values by the processing rules discussed below in "Entry and validation".
MSE elements that use alpha equivalent variables that are altered via program assignments require a different solution to ensure that the alpha value displayed always corresponds with the native value. One approach is to reassign the alpha equivalent variable whenever the native value assignments are performed. However, this is sometimes accomplished in a complex routine or a protected area of code as with the PEGM model (the EdOpt changes the native values). The simplest solution is to place these assignments in the PREMAP modifiable block so they are always performed prior to the display of the map and thus always in sync with the native values.
The values entered from the screen into alpha equivalent variables must be edited for the correct format and the native fields must be set to the equivalent values. This is accomplished through the use of processing rules. Invalid entries should result in a REINPUT with the text of this message customized so that the proper format for the entry is included. This processing rule should be rank 0 for all banner key fields. For banner keys, the standard is to allow the user to exit with bad data in the alpha field. The code should allow an exit if PF3, PF4, or PF5 is pressed, OR 'FIN' or 'LOG' has been entered in the #COMMAND-ID-ISSUED field but the PF-KEY is not PF10 (see UACDATEI in SYSTEM for an example). For non-banner key fields, the rank of this format validation and translation processing rule must be established with consideration for how the corresponding native field may be used in other processing rules. For example, the native value may require further validation and may be used to perform a de-code function. In this case two rules would be used, both less than rank 50, and the rule that performs the alpha equivalent format validation and translation is a lower rank than the one performing the data base validation and de-code.
Note: Since these processing rules may be less than rank 50 they will be executed during a view action if PF4, de-code, is pressed. Therefore, the corresponding REINPUT should not be performed when PF4 has been pressed.
To facilitate use of this technique, to standardize input formats for common fields, and to maximize code reuse, several standard copycode objects have been created to accomplish this processing. These objects use the new Natural 2.2 feature of providing arguments to copycode so that the alpha equivalent and native variable names can vary with each invocation. These include:
|
UACDATEI |
Allows entry of a date in month-day-year format, with or without dashes or slashes, and with a two or a four digit year. The resulting value is always displayed as: MM/DD/YYYY. The native field must be format D. |
|
UACCCCIN |
Allows entry of Company Cost Center with or without delimiting characters and with or without the project number (last four digits). The resulting value is displayed as: 9999 99999-99-9999. |
|
UACSSNIN |
Allows entry of Social Security Number with or without dashes while displaying the result as: 999-99-9999. |
Please see the specific code for additional information. Also note that the last two routines accept a blank value which is translated to a null native field value (UACDATEI requires a parameter that determines if a blank value is allowed). When a non-null value is required, an explicit check for a non-null value must be provided. This can be done in the main program when dealing with banner key fields or by adding an additional processing rule for other fields.
The maintenance of department and budgetary unit associations throughout our applications has presented a unique problem because the names and associated codes (abbreviations) used to identify these organizations commonly change. Due to this situation, numeric identifiers for these entities were created, and applications were designed to store the numeric identifier rather than the code so that massive conversions would not be required when a unit changed its name. The DEPARTMENT and BUDGETARY-UNITS tables, where possible values reside, are keyed by both the numeric identifier and the code. To aid the user in data entry the convention is to allow entry of the familiar code, translate this to the equivalent numeric identifier, and store the numeric value on the data base. Similarly, to aid the user in interpreting output, the numeric value from the data base should be translated to the alphabetic code for display purposes.
The processing considerations for code translations are the same as those for "alpha equivalent" variables previously discussed and those standards should be applied. The difference is in the manner of translation, rather than IF ... MASK and MOVE EDITED statements being used these translations require table look-ups. Two subprograms have been developed to perform this function: UANRDEPT and UANRBU. Given a numeric identifier they will return the four character code and name, or given the code (and a zero numeric identifier) they will return the number and name. Use of these routines reduces the need to define the necessary data base views and FIND statements, and therefore is encouraged. To assist in the validation of alpha codes entered online, two copy code members have been developed: UACDEPTI and UACBUCN2. These accept arguments for the appropriate field names for: the 4 character alpha code, the 4 digit numeric identifier, and the name of the unit (the name is optional; see the actual copycode for further information). (UACBUCN2 also uses a control variable to reduce I/O by only reading the file when the code field has actually been modified.) These should be invoked from a processing rule on the alphabetic code field. The same guidelines as for alpha equivalent fields regarding the rank of these rules applies to these code translations (banner key fields should use rank 0).
Code translations for key fields have some unique circumstances that are not handled the same as the alpha equivalents. The following standards have been developed to address these situations.
IF #PS-PF-NAME = 'NextR'
CALLNAT code-translation-subprogram
END-IF
For a TARGET function, this code should be structured as follows:
IF (#ACTION-REQUESTED = 'R' OR TTF.TXN-SELECTED-FROM-LIST
AND TTF.TXN-EXIST) OR #PS-PF-NAME = 'NextR'
CALLNAT code-translation-subprogram
END-IF
An example of code translation can be found in NSM-MS, command LDB (List Desks for a Budgetary Unit).
The following steps describe how to develop an application using the NSM Architecture. For references to program generation, please consult the UAF Program Generator Functional Specifications for detailed instructions and a list of current models and their required components.
Centralized security administration is entirely removed from this loop, and the owner immediately establishes the necessary access for a new user or alters that access as circumstances require. This should not be a burden since the use of the online system is simpler and more confidential than a method of sending memos and making phone calls. The NSM Maintenance System also provides a record of who last made a change (See "Audit Log"), allowing some means of investigating any disputed entries.
Following the instructions in "How To" and the program generator documentation, construct your function's template local data area for the specific model (e.g. xxLMSF).