Introduction

Who Should Read This Guide

This chapter is intended for persons who will be involved in using, developing, or securing applications and data. It should be read by:

Prerequisite Reading

In order to fully understand the MAGEC security system, it is necessary to understand the overall MAGEC environment. Other chapters of the MAGEC manuals offer detailed explanations which would be valuable to you. As needed, please refer to the following manuals/chapters:

Application User's Guide

"Database Administration"

Since it is also possible for your application programs (MMP's) to have logic within them to accommodate special security requirements, you may need to also refer to the following chapters:

"Insertion Points"

"Analysis of the Generated MMP"

"Application Developer" Tutorial

"Customization" Tutorial

"Data Definition" Tutorial


Overview

The MAGEC Online Security System is designed to:

1) govern all access to online functions and data,

2) provide audit trails of accesses to such functions and data,

3) provide immediate real-time control of all security parameters.

Security verification is done for every online transaction and yet imposes no appreciable overhead because it is done in the resident MAGEC nucleus in highly optimized modules. All security parameters are stored in the MAGEC Dictionary, with full online real-time updating accommodated, but are compressed and loaded into main memory "buffers" in order to eliminate I/O overhead at execution time.

An automatic Menu facility produces three levels of user Menu screens from the MAGEC Dictionary. No coding or maintenance is required and no overhead is imposed on the applications, users may bypass all or any portion of the menus as they desire. Thus, the Security System serves both to prevent unauthorized accesses and to assist authorized accesses.


Entities Controlled

Function Codes

The basic unit of control is the Function Code, a six-character identification for every MAGEC transaction. The Function Code is the first data field (top line, left corner) on every screen, whether a MAGEC system screen or an application screen, it is usually a mnemonic code which describes what the transaction does. For instance, the screen to add customers might have a function code of "CUSADD", to change customers "CUSCHG", etc.

MAGEC's nomenclature for generated online programs is MMP's (MAGEC Message Processors). Standard MMP's will contain a set of nine function codes which represent nine complementary online functions done against the database. In the example of "CUS" data, the Functions would be: CUSADD, CUSCHG, CUSDEL, CUSSEE, CUSNXT, CUSDUP, CUSLOC, CUSSCN, and CUSFND. Each of these represents a different operation which can be done against the "CUS" data even though all of them would actually be handled by the same one MMP and use the same one screen format Mask (except that the SCN, FND, and LOC Functions are "browses" and use a common "browse Mask").

If the developer has added customization to the generated application then there might be more than the standard nine functions, or some or all of the standard ones may be suppressed or replaced.

There are no restrictions on the naming of "non-standard" function codes except that they must all be six characters in length and must be unique.

The Security System, by controlling access to Function Codes, thus controls who may do what operation to what data. This is a finer level of control than just providing security by either program or file.

Logical Applications

The MAGEC Dictionary is used to define up to 50 Logical Applications. A Logical Application is any meaningful grouping of Function Codes as defined by the company's needs. Examples of Logical Applications might be: General Ledger, Payroll, Security System, etc.

As new systems are developed using MAGEC, new Logical Applications may be defined, each having a unique Logical Application (LAP) number assigned to it (from 01 to 50 inclusive). The LAP's 48, 49, and 50 are reserved for the MAGEC system software, they are defined at the time of the installation of the software as: TP Spooling (48), Security System (49), and Development and Testing (50).

Every Function Code (FCD) must be specified as being part of one (and only one) LAP.

Terminals

Video and hardcopy devices are defined to the MAGEC Dictionary. The device (DVC) profile specifies WHERE the device is, WHEN it may be legally used, and WHICH LAP's it may access, and with what maximum level of authorization for each LAP.

Hardcopy devices need only be defined to the Dictionary if the MAGEC TP Spooler option is to be used to print reports at local printers.

Operators

Operators are defined to the MAGEC Dictionary. The Operator's Security Information File (SIF) profile controls his/her access to LAP's as well as When and Where he/she may access them. Password security is verified against the SIF profile at Log On time.

Provision is made to manually or automatically suspend an Operator based on Termination date, failed Log On attempts, etc.

Automatic time-out is accommodated for Operators who forget to Log Off before leaving the terminal.

User Views

A User View is an arbitrary grouping of Functions (regardless of which LAP's they belong to), Devices, and Files. Any Function, Device, or File may belong to one or many User Views. MAGEC contains 16 User Views, they are defined by the 16 Transaction ID's (TS01 - TS08, and PR01 - PR08).

If a database management system (DBMS) is installed then selected files may be opened and accessible to selected User Views via the mechanism provided by the DBMS vendor or TP Monitor access tables.

The Dictionary profiles for each Function, Device, and Operator contains a specification as to which User View(s) may be accessed by or have access to (as appropriate) that entity.

User Views are a high-level security parameter which eclipses all other parameters. Regardless of any other authorizations and restrictions, an Operator who is authorized only to access MAGEC applications via, say, User View PR01, is thus limited to only those Devices and Functions which are allowed via User View PR01. A Device which is only authorized access via User View PR01 may only be Logged On to in that User View and is thus limited to only those Functions allowed in PR01. A Function which is only authorized to be executed in User View PR01 thus may only be done by Operators and Devices authorized for PR01.

Before Logging On to a Device the Operator must "enter MAGEC" via one of its User Views, unless that has already been done. He/She does this by entering the appropriate Transaction ID. Then, when the Log On Function is entered, MAGEC verifies that this Device and Operator are allowed in this User View. If not , the Log On is rejected. As each transaction is received by MAGEC, the Security System verifies that the Function Code entered is allowed in this User View.

Security Entity Relationships

Figure 01 --  Security Entity Relationships

Data Elements

When a database administrator defines data Elements to the MAGEC dictionary he/she can also specify security authorization levels required to develop batch and online applications accessing this Element. This enables you to give limited development privileges to your users without risking their developing screens and reports which reveal sensitive information.

Since the MAGEC dictionary consists of ordinary data files which can be accessed by ordinary programs, and since they contain some sensitive information (i.e. Passwords), certain Data Items are stored "encrypted". The encryption routine used is not yet available to you; however, it might be made available at some future time to enable you to encrypt some of your own data.


Control Parameters

Passwords

A four-character Password is associated with each Operator and is stored on his/her Security Information (SIF) profile. When the Operator is initially set-up, the Security Officer assigns the initial Password. Thereafter the Operator may alter the Password at will any time he/she Logs On to MAGEC.

There is no requirement that an Operator's Password be unique with respect to any other Operator's. However, MAGEC prevents him/her from changing the Password to an obvious and easy-to-guess code, such as his/her first name, etc. A complex "guessing routine" is invoked to attempt to "guess" the new Password. If it is guessed, the Operator is signalled to choose a better new Password to change to.

The SIF profile may specify that this Operator MUST alter the Password at some given interval. The interval is specified as the number of days this Operator's Password is "good for", if that number of days has passed since the Password was last changed, the Operator will be told to change it when he/she next attempts to Log On. The Log On will not be accepted until the Password is successfully changed.

In the Log On process MAGEC always "darkens" the Password on the screen and clears it to spaces on the screen as an added precaution. Therefore, if the Operator has to re-key any portion of the screen data because of any entry error(s) the Passowrd(s) must always be re-keyed.

Dates

The Operator's SIF profile includes Termination Date. MAGEC will check if today's date is later than the Operator's Termination Date at the time the Operator attempts to Log On. If it is, MAGEC rejects the Log On and suspends the Operator by setting a "Hold Flag" in the SIF profile.

Each time the Operator's Password is altered the Last Changed Date is stored in the SIF profile. When the Operator attempts to Log On, the Last Changed Date is compared to today's date and the difference is compared to the number of days the Password is Good For (from the SIF). If the number of days has elapsed, the Operator is forced to enter a new Password (twice for verification) before the Log On will be accepted.

Each time an Operator successfully Logs On to MAGEC today's date is stored into the SIF profile as the Last Logon Date. Before accepting the Log On, MAGEC compares the Last Logon Date to today's date and then compares the difference to the number of Inactive Days specified in the SIF profile. If the number of days since the Operator's last successful Log On exceeds the maximum number of Inactive Days specified, MAGEC rejects the Log On and suspends the Operator by setting a "Hold Flag" in the SIF. This feature automatically "terminates" operators who may have resigned or transferred but whom the Security Officers neglected to terminate.

Day of Week

The Operator profile (SIF) and the Terminal profile (DVC) both include specifications for which days of the week are permitted. At the time that an Operator attempts to Log On to a Device, MAGEC checks the parameters for both the Operator and Device to see that they are allowed to Log On or to be Logged On to today, if not then the Log On is rejected.

Holidays

A standard MAGEC Lookup Table (Table # 244) defines the legal Holidays for the company. It is maintained by the Security Officers using the standard MAGEC system Functions: TBLADD, TBLCHG, etc. The profiles for Operators (SIF) and for Devices (DVC) both contain a specification for whether the defined entity may Log On to MAGEC on Holidays. At the time an Operator attempts to Log On, MAGEC looks up today's date in the Holiday Table, if today is a Holiday then it checks the Holiday parameter for the Operator and Device. If either is "No" then the Log On is rejected.

Time of Day

The profiles for Operator and Device both include a starting and ending time of day (hours and minutes, 24-hour clock) to define the time period during which they may Log On or be Logged On to MAGEC. At the time that an Operator attempts to Log On to a terminal, MAGEC compares the current time of day against the ranges specified for both the Operator and Device. If the current time is not within both ranges then the Log On is rejected.

Maximum Number Logon Attempts

Each time an Operator tries and fails to successfully Log On, a counter in the SIF profile is incremented. Each time the Operator successfully Logs On, the counter is zero'd. The Operator's SIF profile includes a Maximum Number of Failed Logons parameter. Each time the Failed Logons counter is incremented it is compared to the Maximum parameter. If the Maximum is reached then MAGEC suspends the Operator by setting a "Hold Flag" in the SIF profile. This feature prevents would-be intruders from "guessing" the correct Password by iteratively trying every possible combination, probably using another computer to do so.

Maximum Unauthorized Functions

The Operator's SIF profile includes a specification for the maximum number of times the Operator may attempt to do any Function Code for which he/she is not authorized before MAGEC suspends him/her by setting the "Hold Flag" in the SIF profile.

Time Out

The Operator and Device profiles both include parameters to specify the number of minutes which may elapse since the last time a transaction was entered, after which MAGEC automatically Logs them Off. At the time that an Operator successfully Logs On to a Device, MAGEC saves the lesser of the two Time Out specifications (either from the SIF or DVC profiles) and as each subsequent transaction is received compares the number of elapsed minutes since the last transaction versus the saved Time Out specification. If the Time Out period has elapsed, MAGEC Logs Off the Operator instead of processing the transaction. This feature provides some protection for Operators who forget to Log Off leaving all of their own security authorization available to anyone who happens to sit down at that terminal. The greater the Operator's authorization, the lower the Time Out should be set; the greater the terminal's exposure to uncontrolled access, the lower the Time Out should be set.

Multi-Terminal Log On

The Operator's SIF profile includes a specification as to whether this Operator is allowed to be concurrently Logged On to more than one Device. If an Operator is permitted to be Logged On to more than one Device, when Logging onto the second or subsequent terminals a warning message will advise him/her that he/she is already Logged On to another terminal. If the Operator is not allowed to be Logged On to more than one terminal, the second and subsequent Log On attempts will be rejected until a Log Off is done at the first terminal. A similar message is issued to advise him/her.

Group Identifier

The Operator's SIF profile includes an optional Group Identifier which may contain any 10-character literal value to identity that Operator as belonging to an organization or project. MAGEC's security system does not act upon this in any way, however, facilities are provided for the Security Officers to do online "Scan and Find" operations to locate all Operators based on Group Identifier (and other Parameters). One useful purpose for this feature might be to terminate a group of contract workers at the conclusion of their project.

Since all security parameters for this session are passed (read-only) to the MMP's, it is possible that the MMP might interrogate the Group ID and impose certain security restrictions of its own.

Location Code

A standard MAGEC Lookup Table (Table # 252) defines the company's Location Codes. Location Codes may be used to describe physical locations (NYC = New York, DAL = Dallas) or to describe departments (FIN = Financial, ACP = Accts. Payable) or virtually any division of the entire environment appropriate for the company's needs. They are set up and maintained by the Security Officers using the standard functions: TBLADD, TBLCHG, etc.

The Device (DVC) profile, which is used to define terminals or network nodes, includes the Location Code to indicate the Location of this Device. If the TP Spooler option of MAGEC is installed then the Location Code specified on the DVC record which defines each printer will also be used for routing report data.

The Operator's (SIF) profile includes an Authorized Location parameter to indicate at which Locations he/she is allowed to Log On to MAGEC. MAGEC, at the time an operator is logging on, compares the Location Code of the device with the operator's Authorized Location code to determine whether this operator may log onto this terminal. The Authorized Location parameter may be "generic". That is, it need not specify an exact Location Code. For instance, it might contain "N . .", which would allow access at any Location with a Code having an N in the first position and any other characters in the second and third. Likewise, a value of ". . L" would allow access at any Location Code ending in "L". The dot (.) is a "wild card" used to indicate that MAGEC is to ignore comparisons on that position. A value of ". . ." would allow access at any Location.

Hold Codes

The profiles for Operators, Devices, and Function Codes each include a "Hold" or "Disable" code which may be set or reset by Security Officers in real-time. In many cases MAGEC might automatically set a "Hold" in a profile also as discussed above. An Operator whose Hold Code is set to Y may be said to be "suspended".

Authorization Levels

An Authorization Level is expressed as a one-digit number from 0 through 9 inclusive, 0 being the lowest and 9 being highest. Each Function code (FCD) profile includes a Test Authorization Level and a Production Authorization Level for that Function Code. Remember, too, that each Function Code must belong to one (no more, no fewer) Logical Application.

The Operator's profile includes up-to 50 Authorization Levels, one for each Logical Application (LAP). The Device profile also includes up-to 50 such Authorization Levels, one per LAP. When an Operator Logs On to a Device, MAGEC saves his list of Authorization Levels for this session. In each LAP it saves the lower of either the Operator's or the Device's authorization level.

As each online transaction is received, MAGEC compares the Authorization Level for the Function Code (either Test or Production, depending upon User-View) against the corresponding saved Authorization Level (for this session) for the LAP to which the Function Code belongs.


Other Features

Custom Security Within MMP

Before MAGEC passes control to an MMP, it fills in an area near the top of the TWA (Task Work Area) named: TWA-SECURITY-DATA. That area contains information about the Operator and Terminal, including Location, Authorization Levels, the Logical Application of this transaction's Function Code, Group ID, and other security data. The MMP is free to interrogate this area and to restrict Operator access to, say, certain fields or certain values in certain fields.

Protection Against Program Violations

When an operator successfully logs on, MAGEC saves the necessary security data (Authorization Levels, etc.) into main memory in order to avoid having to re-read it for each subsequent transaction. MAGEC recognizes that main memory is ordinarily vulnerable to corruption by programs which might accidentally or deliberately alter it. In order to protect against possible Security Violations, MAGEC senses any change in the sensitive portion of memory and aborts the offending task with a message. It also logs off the operator who initiated that task and issues a marginally polite message.

Passwords on Library Members

In order to prevent unauthorized users from modifying any given member on the MAGEC Librarian, a Password facility is built in. Any user who is authorized to access and update a given member can also set a Password for it. Thereafter, only that user and others who know the Password can update that member. Refer to the "Librarian" chapter for more information.

VERZUN - Version Verification

A Security Officer might wish to know if and when a given application was last modified. This is especially valid when there is a suspicion that a production application was used to violate security restrictions or to access data which should not have been accessed. Because of MAGEC's central active dictionary, version numbers and date-changed information is always available; however, since an application consists of many different entities, the task of verifying versions could become tedious. MAGEC includes a special Version Verification function to take the drudgery out of the job. To execute it (online), enter the command: VERZUN MSKxxx, or VERZUN MMPyyy. Where xxx = Mask number, or yyy = MMP number.

The VERZUN function will produce a display showing (regardless which format of the command you chose) the status and versions for the load library member of the program, the screen Mask, the dictionary specifications used to create the Mask and program, the copybooks included into the program when it was compiled, and so forth. This accomplishes in one stroke what would take an average of ten or more individual transactions.


Audit Trails

Database Records

The database administrator (DBA), in defining files to MAGEC, specifies for each file whether or not its records include an Audit Stamp. An Audit Stamp is a 36-byte Element (portion of a record) which is used to note Who, When, Where, and What program last updated/added this record. If a file is specified as having Audit Stamps, MAGECIO (MAGEC's I/O module) will automatically maintain them as the online MMP's and batch MBP's (MAGEC Batch Programs) update the file. If a file does have Audit Stamps then it may also be specified for "Pseudo Deleting". In that case MAGECIO will update a "Delete Flag" in the Audit Stamp instead of actually deleting the record when an MMP or MBP requests a delete. Thereafter, MAGECIO will simulate a "NOT FOUND" condition whenever a program tries to read that record. The record will remain on file intact indefinitely until an application program is run to "Purge" flagged records to a history file (tape) and physically delete them. It is the responsibility of the application developers to provide such a Purge program. In cases where the data is extremely sensitive it is worthwhile to provide such protection for deleted data.

Online Activity

The MAGEC Activity Logging (MAL) facility is provided to produce a record of online activity (mainframe versions of MAGEC, only) for use in System Tuning, User Chargeback, and Security activities. A system global parameter specified in the MAGEC paramaters table (Table #243) determines whether this feature is activated or not. The Logging is done in the resident MAGEC nucleus and may be activated or deactivated by changing the global parameter (named "MAG-ACT-LOG" in Table #243) and issuing the **LOAD command at any time. Since there is usually a complete MAGEC system installed for Test and another for Production, MAL may be activated for either, both, or neither as needs dictate. The MAGEC nucleus consists of the modules MAGECCP and MAGECIO.

If the feature is activated, statistics will be recorded for Functions, Terminals, and Operators. The statistics captured include detailed I/O counts, transaction counts, and error counts. An offline (batch) utility program (MALUTIL) is provided to extract statistics from the Log file (MAL file) and append them to a cumulative Log tape. This may be done on any desired frequency without losing any data. A utility reporting program is also provided (MALRPT) which produces a variety of reports from the tape file. Detailed or summarized figures may be reported in a variety of sequences and with consolidation capabilities. Summaries of activity by Location and by Logical Application may be produced. Potential Security violations will be highlighted on the report.

Online inquiry Functions are provided for Security Officers and other concerned parties to view MAL statistics as the system is running. In seconds, the Security Officer can see who may do any Function (WHOMAY function code), or who did do any Function (WHODID function code), or peruse Operator activity (OPRACT function code).


Dictionary Maintenance

All the Security parameters are stored on MAGEC Dictionary files and maintained online via real-time Functions.  In most cases the standard set of nine Functions is provided against each type of data, the standard functions are:

xxxADD Add a record to the file

xxxDEL Delete a record from the file

xxxCHG Change a record on the file

xxxSEE See a record on the file

xxxNXT See the next record

xxxDUP Duplicate a record

xxxLOC Locate a record (browse)

xxxSCN Scan for selected records

xxxFND Find records meeting selection criteria

In all cases there is full online documentation for all Functions. The Security Officer who requires assistance may reference this chapter and/or review the online documentation. To see the online documentation for any MAGEC Function just enter the Function Code, when the screen returns (in the proper format for that Function) then press PF1 (F1 on a PC), the universal MAGEC "HELP" key. When entering the desired Function Code (in upper left corner of the screen) it is a good idea to clear the screen key area, SKEY (immediately following Function Code) to spaces so that MAGEC will not think that you have mis-entered the key and, therefore, present the key analysis rather than the function-level HELP text.

While doing these (or any) Functions, entry errors will be noted by Error messages presented on the last three lines of the screen. Pressing the HELP key while Error messages are shown will result in MAGEC's displaying documentation for those Error messages instead of for the Function Code. Also, it is possible that there might be a "Broadcast Message" which MAGEC "thinks" the Terminal Operator has not yet seen. In that case there would be a "Notification" on the last line of the screen, pressing HELP then would result in a display of the "Broadcast Message" instead of documentation for the Function. The Notification will disappear after the Broadcast Message has been seen and the HELP key will revert to its usual purpose.

The Functions ending in LOC, SCN, or FND are browse Functions. From any browse Function screen the cursor may be used to select an item. By positioning the cursor on the line of the screen on which an item is listed and pressing the ENTER key (large plus key, on a PC) control will transfer to the SEE (full screen display) Function for the selected item. Pressing PF4 (F4, on a PC) instead of ENTER will pass control to the CHG (update) Function.

The MAGEC Menu Facility may be used to access any of the Security Maintenance Functions by entering a Function Code of: **MENU. When the MAIN MENU appears the cursor may be moved down to select the Security System Logical Application (49) second-level Menu. The second-level menu shows a list of functions and groups of functions which are part of the security system and for which you are authorized. You can cursor-select one of these items. If you select an individual function, you will be transferred to its screen immediately. If you select a group, you will be transferred to a low-level menu for that group. You may then select a function from the group.


Security Officers

There are two levels of Security Officers, Central Security Officers and Local Security Officers. The determination of which type one is is solely a factor of the Authorization Level He/She possesses in the Security System Logical Application (49) on the SIF profile. Operators with a Level of 9 in LAP 49 are, by definition, Central Security Officers. Those with a Level of 8 are, by definition, Local Security Officers. Operators having a Level 0 through 7 in LAP 49 are not Security Officers at all.

A Central Security Officer has virtually unrestricted access to any MAGEC Function and any MAGEC User View. Many of the restrictions which limit ordinary Operators are summarily bypassed when a Central Security Officer Logs On. Needless to say, there should be a limited number of Central Security Officers and their Passwords should be carefully guarded.

A Local Security Officer has the ability to do maintenance Functions to the Dictionary profiles which control security, but only within certain limitations. The Local Officer can inquire into almost all the security profiles but will be able to update only those for his/her Location. Passwords will be suppressed from all displays except for Operators at the same Location. Local Officers may update Device profiles only for Devices at that Location, and Function Code profiles may be updated only if the Local Officer's Authorization would allow access to them.

When a (SIF) profile for a Security Officer is displayed on the screen, a heading will be displayed on the right half of the top line of the screen (SCOMPL). The heading will say either CENTRAL SECURITY OFFICER or LOCAL SECURITY OFFICER as appropriate. If the Operator is Suspended or Terminated, whether a Security Officer or not, SCOMPL will contain a message saying so.


Compatibility

Co-Existence with Other Security

The MAGEC Security System does not interfere with any other System which may be installed. It does not involve any alterations to the TP Monitor or Operating System software. It is totally acceptable to use the MAGEC Security system and also continue using another security system as well to control access to Trans-ID's.

Automatic Log On

You can interface between MAGEC and an external security system, One way of doing that is to use the interface program provided with MAGEC to extract security ID's from some other security system and to automatically log the Operator onto MAGEC. This means that the Operator never sees the MAGEC Log On screen, but full security protection is still afforded. The interface program is a Cobol program for which source code is available. The interface program is named MAGLOGON. It enables interfaces to TopSecret, RACF, ACF2, Novell NetWare, and even to home-grown security systems.

A trans-id of MAGL is provided to invoke the Automatic Log On facility which provides the same functionality on either a mainframe or on a Novell network. Also refer the the topic "Auto Log On" later in this section

MAGEC Security as the Master

Another approach is to allow the MAGEC security system to be the controlling, or master, system for all online applications, MAGEC or non-MAGEC. This is done using the transfer-in, transfer-out utilities provided with MAGEC (MAGXFRIN, MAGXFROT) to seamlessly transfer control back and forth between MAGEC and non-MAGEC programs. You can then write a simple dispatcher, or menu, program in MAGEC which governs access to external Trans-ID's based upon Operator ID and authorization levels.

Dynamic Calls to External Security

Yet another architecture is provided to interface with external security systems. You can specify that MAGEC is to issue a call to an external security module after doing any appropriate security checking against the intrinsic MAGEC security parameters. This enables you to code a program which accesses any other security system and makes a determination as to whether a given operator is authorized to do a given transaction.

MAGEC will first do all of its own security checking. If the transaction is rejected by the intrinsic checks, it will issue the standard "unauthorized..." message without ever calling the external security module; however, if MAGEC security parameters show the operator to be authorized, it will then call your module for further checking. If your module passes back an unauthorized status, a message is issued to the operator. If your module returns an authorized status, the transaction will be allowed to process.

The external security program you write is an ordinary, usually Command-Level Cobol, program which may issue calls to an interface provided with your external security system. You specify to MAGEC the name of that program in the MAGEC System Parameters table, Table #243. The parameter is named SECURITY-EXIT. Thus, you could enter the command online:

TBLCHG 243/SECURITY-EXIT  

and then set or alter the name of your security checking program. If you specify a name of all spaces, MAGEC will bypass attempting to call your program and only the intrinsic MAGEC security parameters will be used.

In order to write a security checking program you must follow a few simple conventions. Those conventions are discussed in this chapter under the heading Security Exit.

Bypassing MAGEC Security

Some MAGEC users may wish to bypass MAGEC's security checking altogether. Normally this would be because they have written a security exit program which will accomplish the necessary authorization checking instead.

To bypass MAGEC's security the MAGEC-SECURITY System Parameter should be set to NO. This can be done using the online command:

TBLCHG 243/MAGEC-SECURITY  

A setting of YES (the default) will allow normal MAGEC security checking, a setting of NO will bypass MAGEC's security checking altogether.

If you choose to bypass MAGEC's security you should be careful to consider that the activity logging and automatic menu systems are based upon the security parameters and ID's. Also,the employee ID in any audit stamp (maintained by the MAGEC I/O module) is taken from the employee number given when the operator logs on. With MAGEC's security bypassed, it is not necessary for an operator to log on to MAGEC in order to do any function; therefore, the empoloyee number would be zero.

One suggestion which might help minimize difficulties associated with bypassing MAGEC security is to have a SECURITY-EXIT program set a meaningful value into the employee number in the TWA security area. It could also set authorization levels to help the dynamic menu system in MAGEC to produce more concise menus.


Online Maintenance

LAP Definitions

Maintenance to the MAGEC LAP file is done online using the LAP File Maintenance Screen (see opposite page) and the LAPADD, LAPCHG, etc. Function Codes. The standard set of nine Functions is provided. The key value (nn) must be numeric and not less than 01 nor greater than 50. The LAP must be defined here before it can be specified as the Logical Application for any Function Code (FCD). The Main Menu screen (**MENU Function Code) is produced from the LAP file, it shows all the Logical Applications for which the Operator (who invoked the Menu) is authorized (has an Authorization Level greater than 0).

The SHORT NAME is a four-character (or less) abbreviation for the Logical Application, such as: G/L, or A/P, for General Ledger or Accounts Payable, etc. It is used where there is insufficient space to show the LONG NAME, such as on the SIF and DVC Maintenance screens.

The LONG NAME is a 35-character (or less) name for the LAP which will be used where space permits, such as on the Main Menu.

Logical Applications are an important part of MAGEC security. However, since there is a limit of 50 LAP's it is wise to avoid indiscriminately using up all available numbers. The User View and Location Code security provide added dimensions which can logically subdivide the Logical Applications. For instance: an Operator at Headquarters, having the same Authorization Level for General Ledger as another Operator at a Remote Site, might actually possess vastly greater authorization access since many General Ledger Functions might be available only via a User View which the other Operator is not allowed to log onto.

NOTE:


 LAPxxx nn


  M A G E C
LOGICAL APPLICATION DEFINITION

LOGICAL APPLICATION NUMBER= nn

  SHORT NAME: ____
  LONG NAME: ___________________________________













Press PF4 for browse (LOC) screen  Press PF13 for Hardcopy
Press PF16 to Copy field to buffer  Press PF17 to Paste data from buffer
Press PF2 for field-level HELP

Figure 02 -- LAP File Maintenance Screen

FCD Definitions

Online maintenance to the FCD file is done using the FCD File Maintenance Screen shown on the facing page. The standard set of Function Codes is provided: FCDADD, FCDCHG, etc. The key value (ffffff) is a six-character Function Code.

The DESCRIPTION is a 30-character literal which will appear, among other places, on the third-level Menu screen.

The LOGICAL APPLICATION NUMBER is the number of the LAP to which this Function Code belongs, it must be defined on the LAP file to be valid.

The LAP description will be displayed beside the LAP number.

The parameters which appear under TEST and PRODUCTION headings apply to this Function depending whether in a TSnn or PRnn User View.

The USER VIEWS fields are to contain "masks" of Yes/No indicators (Y and N) to specify in which User Views this Function Code is to be allowed. A blank in any position is equivalent to an N.

The MMP NUMBER fields specify which program (MMP) is to be invoked by MAGEC to handle this Function Code.

The AUTH LEVEL specifies the Authorization Level (0 - 9) which the Operator/Device must possess in the LAP specified above in order to do this Function.

The HOLD flag may be set to Y (Yes, on hold) or N (No, not on hold) by the Security Officers.

The AUTO EDIT parameter specifies that the MAGEC Automatic Editing is to be done for this Function. Functions ending in ADD, CHG, and DUP must be specified Y (Yes). Other Functions may be Y or N. This allows non-standard Functions to take advantage of the Auto-Editing.

Central Security Officers may add or change any FCD record. Local Security Officers may only change those which their own Authorization Levels permit them to do.


 FCDxxx ffffff


  M A G E C
  FUNCTION CODE DEFINITION
 FUNCTION CODE= ffffff DESC: ___________________________

 LOGICAL APPLICATION NUMBER:  __ _______________________________

TEST PRODUCTION
87654321 87654321
USER VIEWS: ________ USER VIEWS: ________

MMP NUMBER: ___ MMP NUMBER: ___

AUTH LEVEL: _ AUTH LEVEL: _

  HOLD: _ HOLD: _

THIS FUNCTION WILL INVOKE AUTO EDIT (Y OR N): _


Press PF4 for browse (LOC) screen  Press PF13 for Hardcopy
Press PF16 to Copy field to buffer  Press PF17 to Paste data from buffer
Press PF2 for field-level HELP

Figure 03 --  FCD File Maintenance Screen

**LOAD Function

Security data is maintained on online Dictionary files but is transferred into main memory tables for run-time efficiency. Data from the FCD-File, DCL-File, ELT-File, and KYF-File are handled this way for use by the Security system and other MAGEC Features.

When the Security Officer does an update to the FCD-File, for example, the file record is changed, but not the in-memory image. At system start-up time (when the TP Monitor is "brought-up") these in-memory images are loaded from the files. In order to permit dynamically changing Security parameters without stopping and starting the TP Monitor; a special Function is provided for Security Officers (and others who need it). The Function is:

**LOAD xxxxxxxx  

where: xxxxxxxx               = "ONLY FCD" or "ONLY DB " or "ALL "

Any other value defaults to "ALL ". This permits reloading only the Function Code Table from the FCD-File or only the database definitions from the DB definition files or all of them. The loading of these in-memory tables will take (usually) 30 to 60 seconds during which MAGEC must quiesce online processing. Any operator who enters a transaction while the tables are being loaded will receive the message:

SYSTEM LOADING - ONE MOMENT  

The operator's screen will not be destroyed. Pressing ENTER (or any other transmit key) again will retransmit the same transaction.

Auto-Generated FCD's

When a new application is generated containing the standard set of nine Function Codes, MAGEC automatically generates the nine FCD entries in order to reduce the work of the Security Officers. It generates them with the LAP code set to 50 (Testing) and all Production User-Views set to N and all Test User-Views to Y. The Security Officers may alter them at will, usually after Testing is complete and they are ready to "put into Production".

It is important to note that the way that MAGEC knows whether an application is using the standard set of nine functions, as opposed to custom functions, is by checking whether the developer has done any customization in the Insertion Point named %FUNCT. If there is no customization for %FUNCT then the MMPCRE program will automatically generate definitions for the nine standard fucntions. If there is custom code for %FUNCT, then it will not generate any such definitions, the developer will have to add the definitions using the online FCDxxx functions. If a developer wishes to create an application which supports a set of functions which is similar to the standard functions (possibly with some added functions or a few of the standard ones removed), then it is usually easier to first generate the application once with no %FUNCT customization, then to add the customization for %FUNCT and re-generate. That way MMPCRE will save the developer work by generating the standard definitions, which can be easily altered or added to online.


 ***LOAD xxxxxxxx                        nnnn Functions Loaded






















Figure 04 --  Security Table Reload Screen

Global FCD Changes

You will often want to be able to make changes to a group of function code definitions, therefore MAGEC provides a global change facility to help you to aviod having to do many individual updates.

The global change facility uses the function code: FCDGBL. There are two formats for the command.

FCDGBL  

FCDGBL xxxxxx  

In the first format (with a blank "key" value), you will be presented a screen into which you are to enter change parameters. The screen will have all its enterable fields filled with underscores.

In the second format (with xxxxxx = a valid function code), you will be presented a screen with the enterable fields filled in using values copied from the function code specified (xxxxxx). This enables you to use "model" function codes you have set up to reduce your keystrokes and opportunity for errors.

On this first screen you are to specify which fields you wish to update. Any fields which are set to blanks (underscores are equivalent to blanks) will not be updated at all. You must specify a non-blank value in at least one field in order to continue.

This screen does not update any records, nor does it specify which records are to be updated. It merely captures the values to be used for the fields to be updated when you select which records are to be updated (that will happen later).

Pressing PF10 indicates that you have entered the values and wish to proceed to the next step. Pressing PF3 will back you up in the sequence, or back you out of the FCDGBL function altogether. PF key instructions are displayed on every screen throughout the sequence.

When you proceed forward, the next screen will simply give you some instructions and tell you to press ENTER to continue. It will display the field value(s) you have entered, but the screen fields will be protected so that you cannot alter them from here. After reading the instructions you should press ENTER to proceed forward. The next step will be a scan-like function very similar to MAGEC's standard xxxSCN functions.

You can enter a selection mask to produce a list (one screenful at a time) of functions which are candidates to be updated. No updating will take place yet. You will merely create a list of items from which you can then make your selections.

The items which match your selection mask will be listed on the screen with an ACTION code of "Change" initially shown. You can use the cursor and PF keys to toggle each item's action code from Change to Skip and vice-versa. When you have set all of the action codes as you wish, you just press PF10 to initiate the updating. Now, it will update records. All items which have their action codes set to Change will be updated. Only the fields specified with non-blank values in the first screen will be altered. You will receive a display showing OK in the action codes for the items updated.

If there are more items which match your selection mask (for the scan operation), you can press ENTER to page forward for more candidate functions.


FCDGBL xxxxxx                      Enter values in fields to be changed


  M A G E C GLOBAL FUNCTION CODE MAINTENANCE
 
 FUNCTION CODE DESCRIPTION: ___________________________

 LOGICAL APPLICATION NUMBER:  __ _______________________________

TEST PRODUCTION
87654321 87654321
USER VIEWS: ________ USER VIEWS: ________

MMP NUMBER: ___ MMP NUMBER: ___

AUTH LEVEL: _ AUTH LEVEL: _

  HOLD: _ HOLD: _

THIS FUNCTION WILL INVOKE AUTO EDIT (Y OR N): _


Enter new values into those fields which you wish to change, blanks into those
you do not wish to change. No updating occurs now, you will select records you
wish to have updated later. PF3 = ABORT PF10 = CONTINUE

Figure 05 --  FCD Global Change Screen

DVC Definition

Maintenance to the Device profiles is done using the DVC File Maintenance Screen shown on the facing page, and the standard set of nine Function Codes: DVCADD, DVCCHG, etc. The key (tttt) is a four-character Terminal ID. In a Westi environment this should match the first four characters of the 8-character Westi terminal ID, they should be unique within the first four characters.

The LOCATION is the three-character Location Code indicating where this Device is, the Location Code must be defined on MAGEC Lookup Table # 252.

The Location description will display beside the code.

The BUF SIZE is the hardware buffer size, used by the MAGEC TP Spooler to limit the maximum number of bytes of message which can be transmitted to this terminal.

TYPE is the terminal type (3278, 3279, etc.).

L/R is the line type (L = Local, R= Remote, D= Dialup, U=Logical Unit, ).

The DESCRIPTION is 30 characters maximum.

STATUS may be AVAILABLE or DISABLED, Operators may not Log On to a Disabled Device.

FORM is used by the TP Spooler only if the Device is a Hardcopy type.

The USER VIEWS fields specify which User Views are available to this Device using Y and N codes as on the FCD Screen earlier.

ACTIVE REPORT applies only to TP Spooler Hardcopy devices.

TIME OUT is the number of minutes which may elapse between transactions from this Device before MAGEC will automatically Log Off the Operator, the lesser value between this and the time out from the SIF profile will apply.

PRINT CLASSES applies to the TP Spooler.

AUTHORIZED HOURS is the range of time (Hours and Minutes) during which this Device may be Logged On to.

DAYS indicates, using Y and N codes, the days-of-week during which this Device may be Logged On to and whether it may be used on Holidays.

MAXIMUM AUTHORIZATION LEVELS BY APPLICATION is an array of up-to 50 Authorization Codes (0 - 9) corresponding to the defined LAP's. When an Operator Logs On to this Device the lesser value (for each LAP) of these and the ones from the Operator's SIF profile will apply.


 DVCxxx tttt

  M A G E C DEVICE DEFINITION (CRT/PRINTER)
 ID= tttt
 Location: ___ ( ___________________
_________________________ ) Buf Size:  _____
 Type: ____ L/R:______ 7-Color(Y/N):  --TEST--  --PROD--
 Desc: ______________________________ 87654321 87654321
 Status _________  Form: ____  User Views: ________ ________
 Active Report _____  Time Out: ___ min.
 Print Classes: ______________________ SMTWTFSH
Authorized Hours : __ __ to __ __  Days: ________
 ................MAXIMUM AUTHORIZATION LEVELS BY APPLICATION....................
G/L (01): _  A/P (02): _







  SPLR(48): 9  SEC.49: 9  PROG(50): 9
Press PF4 for browse (LOC) screen  Press PF13 for Hardcopy
Press PF16 to Copy field to buffer  Press PF17 to Paste data from buffer
Press PF2 for field-level HELP

Figure 06 --  DVC File Maintenance Screen

Global DVC Changes

You will often want to be able to make changes to a group of device definitions, therefore MAGEC provides a global change facility to help you to avoid having to do many individual updates.

The global change facility uses the function code: DVCGBL. There are two formats for the command.

DVCGBL  

DVCGBL tttt  

In the first format (with a blank "key" value), you will be presented a screen into which you are to enter change parameters. The screen will have all its enterable fields filled with underscores.

In the second format (with tttt = a valid existing device ID), you will be presented a screen with the enterable fields filled in using values copied from the device definition specified (tttt). This enables you to use "model" devices you have set up to reduce your keystrokes and opportunity for errors.

On this first screen you are to specify which fields you wish to update. Any fields which are set to blanks (underscores are equivalent to blanks) will not be updated at all. You must specify a non-blank value in at least one field in order to continue.

This screen does not update any records, nor does it specify which records are to be updated. It merely captures the values to be used for the fields to be updated when you select which records are to be updated (that will happen later).

Pressing PF10 indicates that you have entered the values and wish to proceed to the next step. Pressing PF3 will back you up in the sequence, or back you out of the DVCGBL function altogether. PF key instructions are displayed on every screen throughout the sequence.

When you proceed forward, the next screen will simply give you some instructions and tell you to press ENTER to continue. It will display the field value(s) you have entered, but the screen fields will be protected so that you cannot alter them from here. After reading the instructions you should press ENTER to proceed forward. The next step will be a scan-like function very similar to MAGEC's standard xxxSCN functions.

You can enter a selection mask to produce a list (one screenful at a time) of devices which are candidates to be updated. No updating will take place yet. You will merely create a list of items from which you can then make your selections. The items which match your selection mask will be listed on the screen with an ACTION code of "Change" initially shown. You can use the cursor and PF keys to toggle each item's action code from Change to Skip and vice-versa. When you have set all of the action codes as you wish, you just press PF10 to initiate the updating. Now, it will update records. All items which have their action codes set to Change will be updated. Only the fields specified with non-blank values in the first screen will be altered. You will receive a display showing OK in the action codes for the items updated. If there are more items which match your selection mask (for the scan operation), you can press ENTER to page forward for more candidate devices.


DVCGBL tttt                        Enter values in fields to be changed


  M A G E C GLOBAL DEVICE MAINTENANCE

TERMINAL LOC: ___ TEST  87654321 PROD  87654321  WEEK SMTWTFSH  AUTHORIZED HRS
VIEW: ________ VIEW: ________ DAYS: ________  __ __ TO __ __

BUFSZ: _____ TYPE: ____ LOCAL/REMOTE: ______ 7-COLOR: _ STATUS: __________
TIME OUT: ___ FORM: ____ PRINT CLASSES: ____________________________________

......................AUTHORIZEATION LEVELS BY APPLICATION.......................







 


Splr (48): _ Sec.(49) _ Prog(50): _
Enter new values into those fields which you wish to change, blanks into those
you do not wish to change. No updating occurs now, you will select records you
wish to have updated later. PF3 = ABORT PF10 = CONTINUE

Figure 07 --  DVC Global Change Screen

SIF Definition

Maintenance to the Operator (SIF) profiles is done using the SIF File Maintenance Screen shown on the opposite page, and the standard set of nine Functions: SIFADD, SIFCHG, etc. The key value (nnnnnnnnn) is the nine-digit Employee number identifying the Operator.

PASSWORD is the four-character Log On Password, displays as "****" except for this Operator's Local Security Officer or any Central Officer.

LOCATION is the exact or generic Location Code at which this Operator may Log On, as discussed earlier.

DAYS indicates, using Y and N codes, on which days-of-the-week this Operator may Log On and whether on Holidays.

U-VIEWS indicates which User Views this Operator may Log On to, Y and N codes in corresponding positions.

LAST and FIRST NAME are required.

ON HOLD indicates (Y or N) whether this Operator is Suspended from Logging On - if Y then an appropriate message will be shown on the top line of the screen also.

TERM DATE is the Termination Date (MM/DD/CCYY) for this Operator.

MAX # UNAUTH FUNCT and LOGON ATTEMPTS limit the number of unauthorized Functions and failed Log On attempts this Operator may do before being automatically Logged Off and Suspended by MAGEC.

TIME OUT is the number of minutes which may elapse since the last transaction before the Operator is automatically Logged Off. The lesser value between this and the Time Out specified on the DVC profile will apply.

MULTI-TRM LOGON (Y or N) specifies whether this Operator may be Logged On to multiple Devices at any one time.

GROUP IDENT is an up-to 10-character literal (optional) which may be used by Security Officers to help find Operators belonging to some group, etc.

LAST LOGON will display the date this Operator last Logged On and, if still Logged On, the Terminal (Device) ID.

SUSPEND AFTER is the number of days which may elapse since the last Log On date before MAGEC will automatically Suspend this Operator.

PSWD CHGD will display the date the Password was last changed by the Operator. GOOD FOR is the number of days which may elapse since the date the Password was last changed before MAGEC will require the Operator to again change it in order to successfully Log On. The Password may be changed in the Log On process any time.

AUTH HOURS is the range of time-of-day (hours and minutes) during which this Operator may Log On, 00 00 to 24 00 allows Log On any time of day. When Log On is attempted the current time-of-day must be in the valid range for both the Operator and the Device or the Log On is rejected.

AUTHORIZATION LEVELS BY APPLICATION is an array of up-to 50 Authorization Levels (0 - 9) corresponding to the valid LAP's. Only the valid (defined on the LAP file) Logical Applications appear on the screen. If a new LAP is added to the LAP file then it will automatically begin to appear on this (and the DVC Maintenance) screen. The Authorization Level which will initially appear for a newly added LAP will be 0 on the SIF and DVC profiles until a Security Officer changes those Levels for those Devices and Operators which are to have access to the new LAP.


 SIFxxx nnnnnnnnn                       ++ CENTRAL SECURITY OFFICER ++

  M A G E C OPERATOR SECURITY INFORMATION
  EMPLOYEE # nnnnnnnnn _ _  TEST  PROD
  PASSWORD: ____ SMTWTFSH 87654321 87654321
  LOCATION: ___ DAYS: ________ U-VIEWS: ________ ________
 LAST NAME: _________________________ , FIRST: _______________  ON HOLD: _
 TERM DATE: __________ MAX # UNAUTH FUNCT: ___ LOGON ATTEMPTS: ___
  TIME OUT: ___ MIN. GROUP IDENTIFIER: __________ MULTI-TRM LOGON:
 LAST LOGON: tttt MM/DD/CCYY  SUSPEND AFTER: ___ INACTIVE DAYS
PSWD CHNGD: MM/DD/CCYY ,GOOD FOR ___ DAYS AUTHORIZED HOURS: __ __ TO __ __
 .....................AUTHORIZATION LEVELS BY APPLICATION......................
  G/L (01): _ A/P (02): _









  SPLR(48): 9  SEC.(49): 9 PROG(50): 9
Press PF4 for browse (LOC) screen  Press PF13 for Hardcopy
Press PF16 to Copy field to buffer  Press PF17 to Paste data from buffer
Press PF2 for field-level HELP

Figure 08 --  SIF File Maintenance Screen


Inquiries & Browses

Each of the Dictionary files described in the preceding discussions includes the standard set of MAGEC Functions, which includes a SEE Function for full-screen display using the screen format shown. Each also includes the browse Functions LOC, SCN, and FND which may be used to browse through, search, and select data to be displayed to the Security Officer. Since the Online Documentation feature will provide complete succinct instructions and explanation for each of these simply by pressing the Help key (PF1, F1 on PC) this chapter will not attempt to re-explain them. It will just present some of the possible applications of these very powerful Functions here as an example.

In addition to the standard inquiry and browse functions several special Functions are also provided. They may be used to quickly find information of particular interest to Security Officers, such as: who may access a given Function or who has accessed it or what Functions has a given Operator done and where.

SIFSCN - Queries-by-Example

Scans for selected Operators may be done via the SIF Scan Function (SIFSCN). The key value is any nine-digit Employee number or simply a "1" to indicate to start at the beginning. The Heading line containing column headings for the data to be presented is displayed. Just below it is a "Selection Mask" line. By entering onto the Selection Mask the list of records shown will be limited to those in which an exact match is found in those display columns which are entered into. Any character may be entered into the Selection Mask except the Dot (.) which is the one which is interpreted to mean "any character". The Selection Mask initially is presented with all Dots in every character position except that spaces are shown in those areas between data fields. If you key a space over a position where a Dot was displayed, it will search for a space in that position.

In the sample shown in Figure 09, the Scan is selecting those SIF records where the character sequence "JONES" appears in the first five positions of the Last Name and where the Location Code begins with "H". Notice that all alphabetic data is compared on the basis of its upper-case value, ignoring the fact that the entered Mask or the record's data may be in lower-case.

The SCN screen and the LOC screen are actually one and the same. Therefore, a SCN may be done to search for matches on any data shown on the LOC screen.

Full explanation is available by pressing HELP while in the SCN Function for SIF or any other Data Class. You can also refer to the MAGEC Application User's Guide for more information.


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


. . .  N A M E  . . . . LOC TRM.DATE LAST.ON TRM.  PSW.CHGD GROUP.ID. 
. JONES....................... H.. .......... .......... .... .......... .......

A Jones HQ1 12/31/1999 01/10/1984 L1T2 08/17/1988 ProjA
C Jones HQ2 10/12/1989 02/12/1984 
R JONESBERG HQ1 11/11/1993 08/08/1983 L2T3 07/12/1988 ProjA
  ++++ 54 Records Scanned, 03 DISPLAYED SO FAR PAGE 1 ++++












KEY 1 = MAGEC SIF FILE MASTER KEY  Press PF13 for Hardcopy
 You may Position the CURSOR on an Item and Press ENTER to 'SEE" it
  or Press 'PF4" to 'CHG" it

Figure 09 --  SIF Scan Screen

SIFFND - Compound Boolean Selections

Searches may be done using one or two search arguments to Find Operators meeting certain criteria using the SIFFND Function. The key value is, again, a nine-digit Employee number or simply "1" meaning to start at the beginning. The Heading line showing column headings for the data to be displayed is again presented with the Selection Mask line below. A "Search Argument" line is also displayed above the Heading. In the FND Function the search argument is entered and the Selection Mask line may be used to delimit the "Search Zone". By entering a left parenthesis preceeding the first column of the desired search zone and a right parenthesis following the last column, the search may be restricted. Omitting either defaults to columns 0 and 81 respectively.

Whereas the SCN Function seeks records having a character for character match on the Selection Mask the FND Function will seek records in which the search argument(s) appear anywhere in the search zone. Logical connections of AND, OR, NOT, XOR, and NOR are supported between the arguments if two are given.

In the sample shown in FIgure 10 a search is being done for Operators records in which the character string "PROJECT A" or "HQ" is found. The search zone is the area from Location Code to Group ID inclusive. As in the SCN Function, upper- and lower-case alphabetics are considered equal.

Full explanation is provided by pressing HELP while in the FND Function for SIF or any other Data Class. You may also refer to the MAGEC Application User's Guide.


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

  SEARCH ARG: proja|OR|hq...................................................
. . .  N A M E  . . . . LOC TRM.DATE LAST.ON  TRM. PSW.CHGD GROUP.ID.
. ............................(... .......... .......... .... .......... ......)

A Jones HQ1 12/31/1999 01/10/1984 L1T2 08/17/1988 ProjA
C Jones HQ2 10/12/1989 02/12/1984 
R JONESBERG HQ1 11/11/1993 08/08/1983 L2T3 07/12/1988 ProjA
  ++++ 54 Records Scanned, 03 DISPLAYED SO FAR PAGE 1 ++++












KEY 1 = MAGEC SIF FILE MASTER KEY  Press PF13 for Hardcopy
 You may Position the CURSOR on an Item and Press ENTER to 'SEE" it
  or Press 'PF4" to 'CHG" it

Figure 10 --  SIF Find Screen

Global SIF Changes

You will often want to be able to make changes to a group of Security Information File (SIF) definitions, therefore MAGEC provides a global change facility to help you to aviod having to do many individual updates.

NOTE:

The global change facility uses the function code: SIFGBL. There are two formats for the command.

SIFGBL  

SIFGBL nnnnnnnnn  

In the first format (with a blank "key" value), you will be presented a screen into which you are to enter change parameters. The screen will have all its enterable fields filled with underscores.

In the second format (with nnnnnnnnn = a valid existing operator ID), you will be presented a screen with the enterable fields filled in using values copied from the operator's SIF definition specified (nnnnnnnnn). This enables you to use "model" operators you have set up to reduce your keystrokes and opportunity for errors.

On this first screen you are to specify which fields you wish to update. Any fields which are set to blanks (underscores are equivalent to blanks) will not be updated at all. You must specify a non-blank value in at least one field in order to continue.

This screen does not update any records, nor does it specify which records are to be updated. It merely captures the values to be used for the fields to be updated when you select which records are to be updated (that will happen later).

Pressing PF10 indicates that you have entered the values and wish to proceed to the next step. Pressing PF3 will back you up in the sequence, or back you out of the SIFGBL function altogether. PF key instructions are displayed on every screen throughout the sequence.

When you proceed forward, the next screen will simply give you some instructions and tell you to press ENTER to continue. It will display the field value(s) you have entered, but the screen fields will be protected so that you cannot alter them from here. After reading the instructions you should press ENTER to proceed forward. The next step will be a scan-like function very similar to MAGEC's standard xxxSCN functions.

You can enter a selection mask to produce a list (one screenful at a time) of devices which are candidates to be updated. No updating will take place yet. You will merely create a list of items from which you can then make your selections. The items which match your selection mask will be listed on the screen with an ACTION code of "Change" initially shown. You can use the cursor and PF keys to toggle each item's action code from Change to Skip and vice-versa. When you have set all of the action codes as you wish, you just press PF10 to initiate the updating. Now, it will update records. All items which have their action codes set to Change will be updated. Only the fields specified with non-blank values in the first screen will be altered. You will receive a display showing OK in the action codes for the items updated. If there are more items which match your selection mask (for the scan operation), you can press ENTER to page forward for more candidate operators.


SIFGBL tttt                        Enter values in fields to be changed


  M A G E C GLOBAL SECURITY MAINTENANCE
 
OPERATOR LOC: ___ TEST 87654321 PROD 87654321 WEEK SMTWTFSH AUTHORIZED HRS
GROUP: __________ VIEW: ________ VIEW: ________ DAYS: ________ __ __ TO __ __

ON HOLD: _ TIME OUT: ___ MULTI-TERM: _ #LOGON ATTEMPTS: ___ SESSION OPT: _
#UNAUTH FUNCT: ___ PASSWORD DAYS: ___ INACTIVE DAYS: ___ TERM-DATE: _________

........................AUTHORIZED LEVELS BY APPLICATION........................









Splr(48): _ Sec.(49): _ Prog(50): _
Enter new values into those fields which you wish to change, blanks into those
you do not wish to change. No updating occurs now, you will select records you
wish to have updated later. PF3 = ABORT PF10 = CONTINUE

Figure 11 --  SIF Global Change Screen

WHOMAY - Authorization List

To obtain a list of all Operators who may do a given Function based upon their Authorizations, the WHOMAY Function Code can be used. The key value is any valid six-character Function Code.

The display will show the names and Employee numbers of Operators who are authorized to do the specified Function. The display will also show whether they are authorized in Test User-Views, Production User-Views, or both.

To see the full-screen display of one of the listed Operators, move the cursor down to the line on which that person is shown and press the ENTER key. The SIFSEE screen will result. Pressing PF4 (F4 on a PC) instead of ENTER will result in the SIFCHG screen.


 WHOMAY ffffff                          END OF LIST - PF5=Restart/PF7=Backward


M A G E C D I C T I O N A R Y

AUTHORIZED OPERATORS FOR A FUNCTION
111111111 Jones William PRODUCTION TEST
123456789 Smith John PRODUCTION
222222222 White Mary TEST
  ++++ 10 Records Scanned, 03 DISPLAYED SO FAR -  PAGE  1  ++++












ffffff IS IN LOGICAL APPLICATION nn  Press PF13 for Hardcopy
 You may Position the CURSOR on an Item and Press ENTER to 'SEE" it
  or Press 'PF4" to 'CHG" it

Figure 12 --  WHOMAY Screen

WHODID Function

To obtain a list of Operators who have done a given Function Code, the WHODID Function may be used. This Function is only supported when the MAL Activity Logging (TIMACCT=YES) is specified in the installation parameters. It is not supported on the PC implementation of MAGEC.

The key value (ffffff) is any valid Function Code. The display shows data from the MAL Logging file. The specified Function Code is shown along with the Device ID's and Operator ID's and associated Logging statistics of I/O, errors, etc.

The OPRACT Function Code uses the same screen format and provides displays of activity for selected Operators, Terminals, and Functions with the ability to specify Terminals and Functions generically using the Dot (.) as a generic character as in the SCN Functions. Pressing HELP while in the OPRACT Function will result in full online documentation and explanation of the capabilities of OPRACT.

Placing the cursor onto any line of display and pressing ENTER will result in a more detailed full-screen display which includes the Function Code's description, Device description, and Operator Name. The full-screen inquiry uses the Function Code MALSEE, described below.

WHOSON Function

If you wish to see a list of Operators who are currently logged on to MAGEC you can use the WHOSON function code. No key value is necessary. If you enter a key value into SKEY it will be accepted as a terminal ID (4-character DVC identifier) and the WHOSON function will try to display to you who is logged on to that terminal.


 WHODID ffffff                         END OF LIST - PF5=Restart/PF7=Backward


FUNCTION TERM OPER.ID. TRANS ERROR READS UPDAT DELET ADDIT

 ffffff TRM1 111111111 12 5 24
  "  TRM1 121212121 3 1 6
  "  TRM1  223232323 14 3 28
"  TRM2  121212121 2  6
  ++++ 10 Records Scanned, 04 DISPLAYED SO FAR -  PAGE  1  ++++












KEY 1 - FUNCTION/TRM-ID/OPER-ID  "OPRACT" LISTS OPERATOR ACTIVITY
"MALLOC" SHOWS DETAIL STATISTICS  "MALSUM" SHOWS THEM SUMMARIZED
(Browsing Forward)

Figure 13 --  WHODID Screen (Operator Activity Screen)

MALSEE Function

The MALSEE and MALNXT Functions provide full-screen inquiry to the MAL Logging statistics. The key value is Function Code (ffffff)/ Device ID (tttt)/ and Employee # (nnnnnnnnn). This screen is usually accessed from the browse displays for the MAL data: OPRACT, WHODID, MALLOC, and MALSUM since the correct entry of this rather large key is difficult to do manually.

This display shows more statistics than the browses and interprets the Function Code, Employee #, and Device ID into descriptive names for more clarity. The MALNXT Function will index the display to the next MAL record from the one being shown. Pressing PF4 will transfer control to the MALLOC browse starting at the record displayed on this screen.

This screen is, of course, available only if the Activity Logging feature is activated (MAG-ACT-LOG set to YES) in the global system parameters table (Table #243). It is not available on PC implementations of MAGEC.


 MALSEE ffffff/tttt/nnnnnnnnn


MAGEC ACTIVITY LOG SCREEN

FUNCTION CODE: ______ _____________________________

TERMINAL: ____ _____________________________

OPERATOR ID: _________ __________ __________________

____ ADDS
____ UPDATES
____ READS
____ LOCATES
____ DELETES
____ NOT-FOUND'S
____ MMP ALLOCATE'S
____ TRANSACTIONS
____ TRANSACTIONS REJECTED FOR ENTRY ERRORS


Press PF4 for browse (LOC) screen  Press PF13 for Hardcopy
Press PF16 to Copy field to buffer  Press PF17 to Paste data from buffer
Press PF2 for field-level HELP

Figure 14 --  MAL Inquiry Screen

**MENU - Main Menu

The Main Menu may be obtained by any operator at any time by using the function code **MENU. If the Operator's Session Option is set appropriately, then pressing the CLEAR key will also produce the Main Menu.

Logical Application numbers and Long Names will be listed on the Main Menu screen. If the operator has a Level 0 Authorization Level in any given Logical Application, it will not appear on his/her Main Menu screen.

Positioning the cursor down to the desired LAP and pressing ENTER will produce the Intermediate (group-level) Menu for the selected LAP for this Operator, in this User-View, at this Terminal.

If a new LAP is added to the system using LAPADD, it will automatically appear on the Main Menu for all Operators who are authorized to access it. The menu screens are dynamically generated as the user asks for them without any further effort on the part of the Development or Security staff.


 **MENU                                  END OF DATA Reached


  M A G E C  USER VIEW TS01
MAIN MENU
01 General Ledger
02 Accounts Payable
50 MAGEC Development/Testing/DBA
** END OF MENU **













To select a Logical Application move the CURSOR down to its line  - Press ENTER

PF15 = EXIT MAGEC, PF9 = Swap Windows, PF1 = HELP, PF5 = RESTART

Figure 15 --  Main Menu Screen

++ MENU - Intermediate Menu

When the operator selects a Logical Application from the high-level menu, MAGEC transfers to the Intermediate-level menu. On this menu there will be a list of functions and groups of functions that the operator is authorized to do. An example of a group of functions is:

CUSADD

CUSCHG

CUSDEL

Functions are grouped based upon the first three characters of the function code. If the operator is only authorized for a single function out of a group, that function will appear intact on this menu. If the operator is authorized for several functions making up a group, they will appear as a single line item with dots (.) in the last three character positions of the function code. For example:

CUS...

There will be a description to help the operator identify the functions and groups of functions.

If the operator cursor-selects an individual function s/he will be transferred directly to that function's screen without having to pass through any other level of menus.

If the operator selects a group of functions, s/he will be transferred to the Application-level menu which will display each of the individual functions which make up the group.

It is important to note that in all cases the determination of which functions are to be presented on the menu screens is driven by the security parameters in the dictionary.


 ++MENU 01                                            END OF DATA Reached

  User View TS01
MENU FOR: General Ledger



  COA...  Chart of Accts  (  3 Functions)
  JEF...  Journal Entries (  4 Functions)
  BALANC  Trial Balance






  **END OF MENU **





To select a function (or set of functions), point with the cursor, press ENTER
PF3=return to Main MENU,  PF8=page forward,  PF5=restart list from top

Figure 16 --  Intermediate Menu Screen

$$MENU - Application Menu

The Application Menu screen may be accessed from the Main Menu or by entering the Function Code $$MENU. The key value is any valid Logical Application number defined on the LAP file.

This Application Menu screen lists Function Codes from the FCD file. It shows only those which are available to this Operator, at this Device, and in this User-View. If new Function Codes are added, they will appear automatically on the Application Menu for the appropriate LAP for those Operators authorized to do them at authorized Devices.

When using this Menu screen the Operator may move the cursor down to a line on which a desired Function appears and press ENTER to transfer immediately to that Function. If appropriate, the key value may be entered directly onto the Menu screen before pressing ENTER, or it may be entered onto the selected Function's screen when it comes up.

Selecting a Function by pressing PF1 instead of ENTER will result in the Online Documentation display for that Function.

If an Operator's Authorization Levels are changed and he then Logs On, the Application Menu's for that Operator will automatically reflect the increased or decreased number of Functions allowed. No maintenance need be done by Developers or Security Officers to keep the Menu's current and they will never reveal the existence of Functions for which the Operator is not authorized.


 $$MENU 01

  User View TS01
MENU FOR: General Ledger

FUNCTION KEY INFORMATION ENTRY ACTION  DESCRIPTION

 COAADD  _____________________ ADD  Chart of Accts
 COACHG  _____________________ CHG  Chart of Accts
 COADEL  _____________________  DELETE  Chart of Accts












To SELECT a Function, Position the CURSOR down to the line on which it isshown,
Enter the KEY VALUE beside it if appropriate, Press ENTER
-or- Press PF2 for HELP Instruction for selected Function

Figure 17 --  Application Menu Screen

SYSLOG - Log On/Off

Logging on to and off of MAGEC is done using the Function Code SYSLOG. The key value is either ON or OFF, depending on whether log on or off is desired. The ON or OFF must not have any leading spaces, the standard MAGEC screen format provides a 3270 screen attribute after SFUNCT (the six-character function code) which will "skip" the cursor to the first character of SKEY (the key entry field immediately following SFUNCT.

The Employee Number is the Operators nine-digit ID.

The 4-character Password must be entered correctly every time log on is attempted. MAGEC clears all three Password fields to spaces after every transmission to reduce the possibility that system error might reveal it.

The Operator may change his Password any time while Logging On. As specified on the SIF profile he may occasionally be required to change it. The Operator may not change the Password to the same one just used nor to one recently used by the same Operator nor to one so simplistic that MAGEC is able to "guess" it in its built-in "guessing routine".

If the Device's Maximum Authorizations by Application cause MAGEC to temporarily reduce those for this Operator (this session only), then a Notification message will appear at the bottom of the Log On screen.

If there is a new Broadcast Message on file, then a Notification will be placed in the SCOMPL area of the screen (upper right) and the HELP key will be equated to MSGSEE until the Operator views the new Message.


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


  M A G E C
SYSTEM LOG ON/OFF

EMPLOYEE NUMBER: _________ DATE: MM/DD/YY
THURSDAY
PASSWORD: ____


NOTE - To change your password: (1) enter OLD password above - DO NOT HIT
  ENTER, (2) enter NEW password below, (3) repeat it for verification,
  (4) hit enter.

NEW PASSWORD: ____

REPEAT TO VERIFY: ____






Figure 18 --  Log On/Off Screen


Activity Logging

An optional Activity Logging facility is provided with MAGEC in a mainframe environment. The Logging is done in MAGEC's Control Program and I/O Module. Whether activity logging is active or not is controlled by a MAGEC Global Parameter Table entry. The parameter may be set to "YES" or "NO "; Yes activates the option, No deactivates it. After altering the setting of a parameter in the table, you should enter the **LOAD command to put the new parameter into effect immediately. To look at "MAG-ACT-LOG" enter:

TBLSEE 243/MAG-ACT-LOG

When Logging is activated, the system will update the MAGEC Log File (MAL file) for every online transaction. The file is keyed by a combination of Function Code, Operator ID, and Terminal ID. It holds statistics of cumulative transactions, error screens, program (MMP) allocations, and DB activity (Adds, Reads, etc.). "Transaction" is defined as: every time an Operator sends a message to the host CPU by pressing the ENTER or any PF key, PA key, or the CLEAR key.

Online inquiries are provided to permit monitoring activity as the system is running. They are:

MALLOC Browse through MAL-File

MALSUM Summarized Browse

MALSEE Display Specific MAL-Record

OPRACT Selective Display of Operator Activity

WHODID List of which Operators have done a Function

MALSCN Scan for Selected MAL Records

MALFND Find Selected MAL Records

Each of these functions is fully documented online via the standard "PF1" key Online Documentation facility of MAGEC.

A batch utility program (and job stream) is provided to extract the cumulative statistics from the MAL-File to tape. The program name is "MALUTIL" and the job stream is "MALUTLEX". No control card is needed. The program reads the MAL file and builds a work file of statistics records. It then reads the old, input tape file (Ignored/Dummied the first time it is run) and writes to a new output tape file all the old records plus all those new records from the extracted work file. After it does that it then goes back to the MAL file and "subtracts out" the activity it has "added" to the cumulative tape, thus this extract may be done while the system is running and Logging without interrupting processing.

The "MALUTLEX" job may be run on any frequency desired since the extracted records are stamped with the "From/To" dates and times for which they apply. Running it more frequently, say daily, will provide a finer breakdown of activity but will also produce a larger (more records) cumulative tape file.

A batch utility report program and job stream are provided to print a report of statistics from the tape. The program is named 'MALRPT' and the job stream is called 'MALRPTEX'. A control card is used to specify various options which will result in the report being listed in detail or consolidated form and in a variety of sequences. The report uses data selected from the tape file. The control card also defines selection criteria.

The MALRPT Control Card format is:

COL 01 - 07 'MALRPT ' constant

COL 08 - 13 Start date (YYMMDD)

COL 14 - 14 Blank

COL 15 - 20 End date (YYMMDD)

COL 21 - 21 Date consolidate flag

COL 22 - 25 Terminal ID

COL 26 - 26 Trm-ID consolidate flag

COL 27 - 35 Employee # (Operator ID)

COL 36 - 36 Op-ID consolidate flag

COL 37 - 42 Function Code

COL 43 - 43 Function consolidate flag

COL 44 - 46 Report sequence code

COL 47 - 48 Op-ID suppress flag

COL 48 - 48 Op name suppress flag

COL 49 - 51 Major grouping

LAP = Logical Application

LOC = Location

COL 52 - 52 T = Print summary Totals only

Blank = Detail and summary

The Start and End Dates are used to limit the extract to activity records between the two. If Start Date is omitted (Blank) then '000000' is assumed. If End Date is omitted then '999999' is assumed. The extract will select statistics records having a Start Date or End Date which is between the Control Card Start and End Dates.

If Operator-ID is given then only that Operator's activity will be extracted. If omitted then all Operators will be assumed.

It Terminal (Device) ID is given then only that Terminal's activity will be extracted, otherwise all Terminals will be assumed.

If Function Code is given then only that Function (or Functions if generic) will be extracted, otherwise all Functions will be assumed.

The Function Code and Terminal-ID entries may be Generic, that is, they may contain the Mask Character Dot (.) in positions in which the matching comparison is to be ignored. Thus, a Function Code entry of "CUS..." will select all Function Codes starting with "CUS", an entry of "...ADD" will select all Function Codes ending with "ADD", etc.

The Consolidate Flags control whether the report is to show detailed or consolidated entries for the respective fields. A "C" indicates consolidation while a "D" or Blank indicates detail.

The Report Sequence Code controls the sort and report sequence. It may contain:

FTO Function/Terminal/Operator

TFO Terminal/Function/Operator

OFT Operator/Function/Terminal

OTF Operator/Terminal/Function

FOT Function/Operator/Terminal

TOF Terminal/Operator/Function

(Blanks) Function/Terminal/Operator

If the Op-ID Suppress Flag is "S" then the Operators' Employee numbers will not be shown on the report. If the Flag is "P" or Blank then the numbers will be shown.

If the Op-Name Suppress Flag is "S" the Operators' names will not be shown. If the Flag is "P" or Blank the names will be shown.

If the Control Card is omitted entirely then a card of:

'MALRPT YYMMDD YYMMDD '  

is assumed, where YYMMDD equal Today's Date.

The MALRPT report columns are:

FUNCT - Function Code

TRM - Terminal ID

OPERATOR - Operator ID

ADDS - 'ADDIT' Requests

UPDS - 'UPDAT' Requests

READS - 'RED..' or 'RDU..' Requests

LOCS - 'LOC..' Requests

DELS - 'DELET' Requests

NOT-FND - Return Code '14'

ALLOC - Program Allocations from MAGECCP

TRANS - Two-Way Terminal Transmissions

ERROR - Screens sent with Error Messages

DATES - Range of Dates (YY/MM/DD)


Broadcast Message

A general purpose Broadcast Message facility is provided by MAGEC for use by Security Officers and other Central Site personnel having the need from time to time to distribute information to all Operators.

There is a single record on the DOC File designated to contain the Broadcast Message, which may be up-to 15 lines long. Standard Functions are provided to enter or alter, and delete the message. The Functions used are:

MSGADD Add a message

MSGCHG Change the message

MSGDEL Delete the message

If there is already a message record on file the ADD Function acts as a CHG Function. The DEL Function merely updates the message record with a "message" of all Blanks.

Whenever a non-blank message is ADDed or CHG'd MAGEC sets a flag in the TWA records for all terminals indicating "there is a message for you". Operators who are currently Logged On to the system then begin seeing a Notification on the bottom line of their screens, such as:

** THERE IS A MESSAGE FOR YOU - PRESS PF1 TO SEE IT **  

While this Notification is shown the PF1 Key is temporarily equated to the Function Code MSGSEE. When the Operator presses PF1 (or enters the Function Code MSGSEE) the Broadcast message will be displayed with the Function Code set to MSGSAW. Pressing ENTER again (with MSGSAW) will set the TWA flag off and the Notification will disappear. The Operator may still use MSGSEE to re-read the message, but the PF1 Key reverts to its standard usage (HELP Key).

Whenever any Operator Logs On MAGEC checks whether the Broadcast Message record on the DOC File is Blank, if not then it sets the TWA flag on and the new Operator will begin seeing the Notification until he/she reads the message.

Whenever the Broadcast Message record is "deleted" (blanked) MAGEC sets the TWA flag off for all terminals. You can delete the message by using the MSGCHG Function and blanking the message text or by using the MSGDEL Function (same results).


Security Exit

Some MAGEC users may wish to provide their own security logic and to have MAGEC invoke it to determine whether an operator or terminal is authorized to access a given function or screen. This can be accomplished via the security exit of MAGEC's Control Program.

A security exit program is an ordinary CICS program. It may be Cobol, Assembler, or any other language supported in your environment. It may call any external security system (i.e. ACF2, RACF, TopSecret, or homegrown system) to make a determination of authorization or no authorization. Most users will probably wish to specify, in the DFHPPT, that the security exit program is to be RESIDENT in order to minimize overhead as online transactions are processed.

You must first code and compile (or assemble) and link the security exit program. It may have any valid 8-character (7-character for VSE) name and it must be defined to CICS's PPT. MAGEC's Control Program will access the security exit via the EXEC CICS LINK command, when appropriate.

To tell MAGEC that a security exit program exists, and its name, you must specify the name in the MAGEC table number 243. This can be done online using the command:

TBLCHG 243/SECURITY-EXIT  

The first 8 characters of the description will be accepted as the program name. If the first 8 characters are blank, MAGEC assumes that there is no security exit.

When MAGEC calls the security exit program the exit program has access to the TWA. The security exit program may interrogate any area of the TWA and may even alter the contents, but you should be careful. The TWA contains the standard fields SFUNCT and SKEY which contain the function code and key value. It also contains a field named TWA-ACF-OK which is one byte long (PIC X).

The exit program is expected to set a value of '0' thru '9' into TWA-ACF-OK. A value of '0' indicates that access is denied, any greater value indicates that access is approved. The application MMP's may interrogate the TWA-ACF-OK field to determine a degree of authorization, if desired.

Before calling the security exit program MAGEC's Control Program defaults the TWA-ACF-OK field to a value of '9', the highest possible authorization level.

If the security exit sets a value of '0' MAGEC's Control Program will issue a message indicating that the external security system has rejected the transaction and will not pass control to the MMP.

If the operator is a Central Security Officer, MAGEC's Control Program will give him/her access regardless what authorization level the security exit program returns. This enables a Central Security Officer to break deadlocks.

Coding the exit program

The security exit program may access any external security system via any valid means provided. It must obtain addressibility to the TWA and it must include a definition of the TWA in order to communicate with the MAGEC Control Program. This means that the exit program should probably include the standard TWA definition provided with MAGEC via:

-MAGECINC TWADSC-C  

This should be included into the LINKAGE SECTION of the exit program (the member TWADSC-C begins with the LINKAGE SECTION statement, so you should not code such a statement into your program).

In the PROCEDURE DIVISION (probably near the very beginning of it) you should get addressibility to the TWA. This is done one of two ways, depending on whether you are using Cobol II or VS Cobol. For Cobol II, code:

EXEC CICS ADDRESS TWA(ADDRESS-FROM-CICS)
END-EXEC
SET ADDRESS OF TWA TO ADDRESS-FROM-CICS.
 

The ADDRESS-FROM-CICS field is defined as:

01 ADDRESS-FROM-CICS USAGE IS POINTER.  

It may be in WORKING-STORAGE.

For VS Cobol, code:

EXEC CICS ADDRESS TWA(TWAPTR)
END-EXEC
ADD 4096 TTWAPTR GIVING TWAPTR2
ADD 4096 TWAPTR2 GIVING TWAPTR3
ADD 4096 TWAPTR3 GIVING TWAPTR4
SERVICE RELOAD TWA.
 

The TWAPTR, TWAPTR2, TWAPTR3, and TWAPTR4 fields are BLL cells (PIC S9(8) COMP).


PF15--Auto-starting a TransID

Some MAGEC users prefer to have MAGEC automatically start a particular CICS TransID whenever the operator exits via the PF15 key. This can be accomplished by setting the global parameter called PFKEY15-TRANSID in MAGEC Table #243, the MAGEC Configuration Parameters table.

To set this parameter use the online command:

TBLCHG 243/PFKEY15-TRANSID  

or, if the parameter has never yet been defined:

TBLADD 243/PFKEY15-TRANSID  

as appropriate.

Then set the DESCRIPTION associated with this parameter to a value of:

tttt-START  

where tttt is the desired TransID (must be defined to CICS in the PCT in order to work correctly).

You may enter any desired comments after the -START, they will be ignored.

If you wish for MAGEC to simply set the specified TransID into an unformatted screen, but not to actually start it, you simply omit the -START, as:

tttt  comments, blah, blah...  

This gives the operator a chance to alter the TransID or to type data behind it, if desired.

If you omit this parameter altogether, or leave it blank, MAGEC will default to a TransID of CSGM, the standard CICS "Good Morning" message. This is usually a harmless default which gives the operator complete freedom to type any other TransID (after pressing the CLEAR key).

NOTE:


Auto Log On

If you would like to provide an automatic log on for your users, based upon some external security system such as RACF, TopSecret, ACF2, Novell NewWare, or a home-grown security system, MAGEC makes it easier by providing the MAGLOGON program.

MAGLOGON is a Command-Level CICS program which accepts input parameters, in the form of a COMMAREA, and which automatically logs the operator on to MAGEC, or off of MAGEC. The input parameters identify who this operator is (external security system operator ID) and which user-view he/she is to be logged on to (or off of).

To use MAGLOGON on a mainframe, you must code a program which does the following:

1. Determine who is logged on to this terminal by accessing your external security system. Most external security systems provide a CALL interface for this purpose.

2. Build the COMMAREA to be passed to MAGLOGON. The structure of the COMMAREA is shown below, the length must be 32.

3. Call MAGLOGON passing the COMMAREA, the format is shown below.

4. Test the return code (MAGEC-REQUEST-COMPLETE) for a successful completion upon return to your calling program.

On either a mainframe or on a network, in order to translate an external security system's operator ID into a MAGEC employee number, MAGLOGON accesses the MAGEC TBL file. A special table (table #SSS) is provided to accommodate such translations. Table #SSS can be maintained online using the standard set of nine functions (SSSADD, SSSCHG, et cetera) provided with MAGEC. The structure of the TBL-file records for table #SSS is:

01 TBL-RECORD.  

the total record length is 100 bytes

  03 TBL00-ELEMENT PIC X(36).  

element 00 is the 36-byte audit stamp

  03 TBL01-ELEMENT.  

element 01 is the 64-byte data portion which includes the key

  05 TBL01-KEY.  

the key length is 19 bytes

  07 TBL01-TABLE-NO PIC XXX.  

the high-order portion of the key is the table number, in this case "SSS"

07 TBL01-CODE PIC X(16)  

the remainder of the key is the external security ID for the employee

  05 TBL01-MAGEC-EMPNUM PIC 9(9).  

the MAGEC employee number is stored as a 9-digit, unsigned, zoned-decimal number

  05 FILLER PIC X(36).  

The COMMAREA may be coded into the WORKING-STORAGE SECTION of your program. It is defined as:

01 MAGLOGON-COMMAREA.  

the total length must be 32 bytes

  03 MAGEC-REQUEST PIC X(3).  

  88 MAGEC-REQUEST-LOGON VALUE 'ON '.  

  88 MAGEC-REQUEST-LOGOFF VALUE 'OFF'.  

  88 MAGEC-REQUEST-COMPLETE VALUE SPACES.  

the 3-byte request code is used to tell MAGLOGON what to do, and it is used by MAGLOGON to pass back a return code (SPACES) to indicate successful completion.

  03 MAGEC-USER-VIEW PIC X(4).  

the user-view must be TS01 thru TS08 or PR01 thru PR08

  03 MAGEC-EXTERNAL-ID PIC X(16).  

the external ID may be up-to 16 bytes long

  03 MAGEC-EMPNUM PIC 9(9).  

the employee number will be returned to your program from MAGLOGON

If your external ID happens to be the same format as the MAGEC ID, i.e. both are 9-digit numbers, then MAGLOGON will not bother to look for a translation in table #SSS. It will just use the 9-digit number as the MAGEC employee number. This eliminates both the reading of the TBL file, and your need to maintain table #SSS.

When your program calls MAGLOGON it should look like this:

EXEC CICS LINK  

  PROGRAM('MAGLOGON')  

  COMMAREA(MAGLOGON-COMMAREA)  

  LENGTH(32)  

END-EXEC.  

it should always test the return code, as:

IF (MAGEC-REQUEST-COMPLETE)  

  NEXT SENTENCE  

ELSE  

  error routine...  

your program can use the returned MAGEC-EMPNUM (if you desire) if the request was successfully completed.