Common Data Elements - System Modification
Assure consistency of definition of common data elements across all files in which they appear.
micsrm140
Required roles: systems programmer, security administrator, database administrator |
|---|
The example file definition contains the component generator definition statements:
... TYPE N 3 . 3 . 3 . NAME NCPMNFBL 00 0 0 0 0 0 Free Buffer Low Water Mark NAME NPANRRLS 99 0 0 0 0 0 . NAME NPANRSLS 99 0 0 0 0 0 . NAME NPATMAOT 99 0 0 0 0 0 . ...
Notice the data elements whose option code is 99. These data elements are NPANRRLS, NPANRSLS, and NPATMAOT. They are also contained in the generation library member $DEGENIN:
... TYPE XR 3 . 3 . 3 . NAME NPANRRLS Receiving Line Speed (line/link) TYPE XR 3 . 3 . 3 . NAME NPANRSLS Sending Line Speed (line/link) TYPE XA 5 TIME11.2 6 TIME15.2 6 TIME15.2 NAME NPATMAOT Actual Observation Time ...
The reason for having data elements that are defined in this common manner is to assure consistency of definition of such common data elements across all files in which they appear. Data elements that are not of this "common" nature are named "standard" data elements.
Most common data elements are named generically, according to their function or contents. Examples of such data elements are ENDTS (end time-stamp) and INTERVLS (the number of recording intervals in a measurement summarization).
Some common data elements take their names from the component. The first three characters of the data element name are the component identifier, and the remaining five characters are a cryptic abbreviation of the data element's function. Examples are NPANRRLS (NPA component receiving line speed) and NPATMAOT (NPA component actual interval observation time).
It is possible to redefine common data elements into standard data elements. For example, the previous extract could have been coded:
... TYPE N 3 . 3 . 3 . NAME NCPMNFBL 00 0 0 0 0 0 Free Buffer Low Water Mark TYPE XR 3 . 3 . 3 . NAME NPANRRLS 00 0 0 0 0 0 Receiving Line Speed (line/link) NAME NPANRSLS 00 0 0 0 0 0 Sending Line Speed (line/link) TYPE XA 5 TIME11.2 6 TIME15.2 6 TIME15.2 NAME NPATMAOT 00 0 0 0 0 0 Actual Observation Time ...
Redefining these elements in this manner defeats the main purpose of common data elements single source format definition. Common data elements are often key data elements in the file, which is used in sequencing the file's observations. If you attempt to bring two files together, and both files have data elements of the same name in the key (for example, both have ENDTS in the file sequence structure), then those data elements must have the same format on both files.
Changing Attributes of Common Data Elements
Changing the attributes of a common data element involves making modifications to the
MICS Component Generator
(MCG) TYPE group that includes the common data element. This will be done in one of the following sharedprefix.MICS.GENLIB members:- Elements that are common to allMICSfiles are defined in sharedprefix.MICS.GENLIB($DEGENIN).
- Elements that are common to the files in a singleMICSproduct are defined in the applicable cccGENIN member, where ccc is aMICSproduct identifier.
For information about the statements in the TYPE group, see Generation Type Statement (GEN).
The following example is used in discussing the considerations for changing common element attributes.
... COMP NPA 050 32000 VBS NOACCT NPA Component TYPE XR 3 . 3 . 3 . NAME NPANRRLS Receiving Line Speed (line/link) TYPE XR 3 . 3 . 3 . NAME NPANRSLS Sending Line Speed (line/link) TYPE XA 5 TIME11.2 6 TIME15.2 6 TIME15.2 NAME NPATMAOT Actual Observation Time ... AREA NPA NPA Activity Information Area ...
Changing the description of a common data element changes the element in all files in which it is referenced. Such changes are:
- Changing the format or length specification of the element.
- Changing the label that is attached to the data element.
- Changing the type code of the data element.
For example, the data element NPATMAOT could be changed as follows:
New Type New Length and Code Format for (Common MONTHS and Maximum) YEARS time-spans | | V V ... -- ----------- TYPE XM 5 TIME11.2 6 TIME15.2 8 TIME18.2 +-->ALIAS NPATIME | NAME NPATMAOT Actual Measurement Time | ... ----------------------- | New Label | +---hypothetical new data dictionary member where all NPA time data elements would be documented (for example only; no such convention exists or should).
Changes to common data elements affect all files in which each changed data element appears. The following items must be considered:
- Common data elements are often used as file sequence elements for the files in which they appear. Even if they are not in any file's key, they might be very important by virtue of being used in many places or being used in extended, user-generated report processes. These data elements should not have their attributes that are modified without the advice of theBroadcom SupportGroup. Further considerations are detailed in Change a File's Sequence in a Timespan, which addresses the impact of changing a file's sequence in a time-span.
- Changing Existing Data Element Definitions presented considerations for changing existing data element definitions. The information presented there also pertains to common elements.
- Changing the definition of a data element will not necessarily be reflected immediately in time-spans greater than DAYS. Accumulating data to the WEEKS, MONTHS, and YEARS time-spans takes some time to complete. Also, the accumulation of to-date data in these time-spans might result in combining unlike data. Changing data elements from accumulated to maximum or minimum, for example, will always produce spurious results in these time spans until a new interval is begun in each time-span, and unlike data is no longer combined in the archive files.Examine the need for retrofitting existing data in such situations. If the need for a retrofit exists, see Retrofitting Guidelines.
Making the Modifications
To change a common data element's attributes:
- Modify the MCG control statements explained previous for each common data element to be modified.
- Generate the component by running the cccCGEN job for each affected product.
- The next daily update for any database unit in which the product has been installed reflects the change.
Adding New Common Data Elements
Adding a common data element involves adding a
MICS Component Generator
(MCG) TYPE group that includes the common data element. Then add the common element to the files in which you want it reported.If the new common data element is local to any single component, add the TYPE group to the component's cccGENIN member in sharedprefix.MICS.GENLIB. If the new common data element is useful for more than one component, add the TYPE group to the $DEGENIN member in sharedprefix.MICS.GENLIB.
As discussed in chapter 4, a common data element TYPE group is made up of the following statements:
- A TYPE statement, mandatory
- An ALIAS statement, optional
- An ALTNAME statement, optional
- A NAME statement, mandatory
The example file definition contains the component generator definition statements:
... COMP NPA 050 32000 VBS NOACCT NPA Component TYPE XR 3 . 3 . 3 . NAME NPANRRLS Receiving Line Speed (line/link) TYPE XR 3 . 3 . 3 . NAME NPANRSLS Sending Line Speed (line/link) TYPE XA 5 TIME11.2 6 TIME15.2 6 TIME15.2 NAME NPATMAOT Actual Observation Time ... AREA NPA NPA Activity Information Area ...
Adding a common data element can be done by adding the TYPE group for the data element into the NPAGENIN member. For example, assume that a data element called PHASE were to be added to the NPA component. PHASE is intended to contain the character strings "FULL", "1Q ", "3Q ", or "NEW ", so it should be defined as a character data element of length four. Define the data element in NPAGENIN by keying in the following before the first AREA statement:
... TYPE XR $4. . $4. . $4. . NAME PHASE Phase of Processing Period ...
Then add the new common element to each file in which you want the element reported by adding a NAME statement like the following after each FILE statement:
NAME PHASE 99 0 0 0 0 0 .
Since this is a retained data element, we also need to add statements that describe the calculation necessary to put an initial value in PHASE. The value could be set by any means. Assume that the site has a user-written routine that returns a character value for the "phase" and the argument that is supplied to the routine is the timestamp of the end of the measurement interval.
To store a value in the data element in the DETAIL timespan, modify logic in the component's daily format routine using standard
MICS
file exits. (See the User Exit Facilities section in chapter 4 for more information.)For this NPA example, the file exit for the NPANCP file is _USRSNCP, in sharedprefix.MICS.SOURCE(#NPAEXIT). The calculation must be added to the stub exit macro that currently exists. The current macro is:
MACRO _USRSNCP % which should be modified to: MACRO _USRSNCP PHASE = UPHASE(ENDTS); %
This code is executed immediately before the format routine writes a DETAIL observation of the NPANCP file, and the data element value is set when the OUTPUT occurs.
Such logic would have to be executed to set a value for PHASE before the format routine OUTPUT for each file of each component in which the data element is to be carried.
Making the Modifications
To add a data element to one or more timespans of one or more files within one or more components, if the data element is not a sequence data element in the file, perform the following:
- Code the MCG type group statements for the data element to be added to either $DEGENIN or cccGENIN.
- Add the element to the files in which you want it reported.
- Add initial calculations for the data element's DETAIL timespan value to the standard file exit in the component's standard exit member on theMICSsource library.
- Run the component generation for the components in question.
The next daily update for any database unit in which the component has been installed reflect the change, and add the data element to the files in the desired timespan(s).
To add a data element to one or more timespans, if the data element IS a sequence data element in the file, see the sections in this chapter on modifying the sequence of a file. Modify the sequence, and follow the instructions to add the data element.
Assigning Alternate Data Element Names
The
MICS Component Generator
(MCG) contains a facility for changing the name of a common data element for reference purposes.Using the facility that is described in this section can have major, unexpected impacts. Very few installations truly need this capability. Contact
Broadcom Support
before attempting to assign an alternate name to any data element. We do not recommend use of this facility
.Normally, changing the name of a data element is a matter of deleting the old data element and adding a new data element. Such changes for common data elements have more impact than for standard data elements. Common data elements, such as MONTH, are used in VERY MANY places. Changing all the
MICS
logic that references such data elements would be a great effort, prone to errors.The ALTNAME statement is an attempt to eliminate the need to change logic if it is desirable to change the name (tag) associated with a common data element.
According to the definition in the MCG section of this document, a common data element type group is made up of a TYPE statement, followed by one or more NAME statements. Each NAME statement defines a data element. The NAME statement can be preceded optionally by an ALIAS statement, and can be preceded optionally by an ALTNAME statement.
The example NPANCP file definition contains the component generator definition statements in the NPAGENIN member of sharedprefix.MICS.GENLIB:
... NAME DAY 99 5 5 N N N . NAME HOUR 99 6 6 6 N N . NAME WEEK 99 0 0 4 N N . NAME YEAR 99 3 3 3 3 3 . NAME MONTH 99 4 4 N 4 N . ...
Where the common data elements (cluster code 99) point to common data element definitions for these data elements. These definitions are contained in the generation library member $DEGENIN:
... TYPE XR 2 . 2 . 2 . NAME DAY Day of Month TYPE XR 2 . 2 . 2 . NAME HOUR Hour Of Day TYPE XR 2 . 2 . 2 . NAME MONTH Month of Year TYPE XR 2 . 2 . 2 . NAME WEEK Week Of Year TYPE XR 2 . 2 . 2 . NAME YEAR Year of Century ...
Let us assume that there was a need to rename the data element MONTH to another name, which is recognized in your company's current report structure. Let us call the new name PERIOD.
Adding the following ALTNAME statement to the $DEGENIN member aids in the rename of the data element.
... TYPE XR 2 . 2 . 2 . NAME DAY Day of Month TYPE XR 2 . 2 . 2 . NAME HOUR Hour Of Day TYPE XR 2 . 2 . 2 . --->ALTNAME PERIOD NAME MONTH Month of Year TYPE XR 2 . 2 . 2 . NAME WEEK Week Of Year TYPE XR 2 . 2 . 2 . NAME YEAR Year of Century ...
What Assigning An Alternate Name Does:
Assigning an alternate name to a common data element adds a new data element to all files that reference the old data element name in their file definition MCG statements in sharedprefix.MICS.GENLIB member cccGENIN. The old data element name is dropped from the file.
In our example, the NPAGENIN member defines files that contain the data element MONTH. Specifying the ALTNAME of PERIOD for MONTH in $DEGENIN means that MONTH is not on the files, but PERIOD is there instead.
This means that any report process can reference the item by the new name.
What Assigning An Alternate Name Does Not Do:
This modification does not assign an initial value to the new data element. In the example, the value for the data element PERIOD has to be set by some other
MICS
modification. Several methods for such a modification exist.If the data element exists in many
MICS
files, modification of common system routines is indicated.If the data element exists in a few
MICS
files, especially if the files are localized to one component, use the standard MICS
file exits described in MICS
Facilities.For this NPA example, the file exit for the NPANCP file is _USRSNCP, in sharedprefix.MICS.SOURCE(#NPAEXIT). The calculation must be added to the stub exit macro that currently exists. The current macro is:
MACRO _USRSNCP % which should be modified to: MACRO _USRSNCP PERIOD = MONTH; %
Such a calculation is possible because renaming the data element does not drop the original data element from standard
MICS
calculations. In fact, all existing MICS
logic will reference the data element name by the old name. This allows a flexibility in the file structure without massive MICS
logic changes.This code is executed immediately before the format routine writes a DETAIL observation of the NPANCP file, and the data element value is set when the OUTPUT occurs.
Such logic would have to be executed to set a value for PERIOD before the format routine OUTPUT for each file of each component in which the data element is to be carried.
Making the Modifications
To assign an alternate name to a common data element, follow these steps:
- Code the MCG ALTNAME statements for the data element to be added to $DEGENIN.Note:the cccGENIN members do not need to be changed.
- Add initial calculations for the data element's DETAIL timespan value to the standard file exit in the component's standard exit member on theMICSsource library, if the change is local to a component.OrAdd initial calculations for the new data element to a common data element determination routine, in the recommended method for such modifications.
- Run the component generation for the components in question.
- The next daily update for any database unit in which the component has been installed reflect the change and add the data element to the files in the desired timespans.
To assign an alternate name to a data element, if the data element IS a sequence data element in the file, see the sections in this chapter on modifying the sequence of a file. Modify the sequence, and follow these instructions to assign the alternate name.