Adabas Environment Data Naming Standards

AIS Standards and Procedures Manual 3.5.08 Technical Standards And Additional Definitions and Good Practices 6/5/2012 Table of Contents
Standards and Procedures Manual 3.5.08 Technical Standards Types of Adabas data element names Conventions for naming data elements Additional Definitions and Good Practices DDM's -- Data Definition Modules Dictionary Metadata Calculating to make sure there is ample space for any DBA request ISIS Refresh Information Guidelines for Reusing Fields Tips when changing existing numeric fields currently in use Steps to follow when changing a field format: Required Steps to Designate a field UNUSED and REUSABLE Renaming of fields Some General Adabas Naming Conventions and Good Practices Security levels Adding a new Userview Caution Regarding SSN Requests Caution Defining the Security Level on SSN Fields Other General Adabas Precautions

Standards and Procedures Manual 3.5.08 Technical Standards

Types of Adabas data element names Two types of data element names are used in the Adabas database system: a data dictionary name used in natural programming and a two-character Adabas name that is used in direct-call programs and internally by the system software. Conventions for naming data elements All data elements will be assigned meaningful, descriptive names. Dictionary names are limited to 32 characters and will be identified by the responsible analyst at the time of system specification. Data Administration (a unit of the office of Administrative Information Systems) will review all names and make changes as deemed appropriate. Data element names and associated information, such as length, format, and description will be provided to Data Administration through the Enterprise Systems DBA database maintenance request form available in the AIS Request for Service system. Data elements names are made up of the following subparts, separated by a dash: Class Word Entity Identifier Modifier Words Class Word The Class Word identifies what type of data the element represents. Each data element name must begin with one of the following Class Words: Class Word / Definition NAME Alphanumeric data, which identifies specific entities (e.g. EMPLOYEE NAME) NUMB Numeric or alphanumeric data used for identification and not used arithmetically (e.g. PART NUMBER, ORDER NUMBER) CODE Data that identifies classifications or statuses of entities (e.g. STATUS CODE) QNTY The numeric quantity of anything, except monetary amounts (e.g. QUANTITY ORDERED) 2

AMNT The quantity of monetary amounts (e.g. UNIT PRICE, SALARY) DATE Actual date. (e.g. BIRTH DATE, FISCAL YEAR) TIME Actual time of day TEXT Data having relatively undefined content (e.g. ITEM DESCRIPTION, SHIPPING INSTRUCTIONS) INDC A one-byte flag limited to two conditions, such as Y, N or blank PCNT Rations between data values expressed as a numeric percentage ADDR Data that is part of an address, such as street, city, state or zip code GRUP The Class Word given to an element that describes a group of other data elements DESC Description is used for comments and is used more frequently than TEXT Entity Identifier The second part of the element name is a four-character abbreviation of the entity to which the element pertains. Entities can be identified by answering the question: This is a class of what? A list of existing entity abbreviations can be found in ROSCOE member RN.ENTITIES. If an entity abbreviation is needed that is not on the list, then Data Administration should be contacted. Modifier Words The remainder of an element name consists of modifier words separated by a dash, which further define the element. Modifier words should proceed from the general to the specific. e.g., QNTY-EMPL-TENURED-FEMALE (i.e., TENURED is a subclass within EMPLOYEE and FEMALE is a subclass within TENURED EMPLOYEE.

Additional Definitions and Good Practices

3

Any new elements for PROVINCE should be A20 instead of A40. It is restricted to only allow A20. Please refer to the universal module to review: A6ADDR (address edit module). If you are requesting a new file and it is student related, then you must request the ID element/field as a descriptor.

DDM's -- Data Definition Modules For natural to be able to access a database file, a logical definition of the physical database file is required. Such a logical file definition is called a DDM. The DDM contains information about the individual fields of the file information, which is relevant for the use of these fields in a Natural program. A DDM constitutes a logical view of a physical database file. For each physical file of a database, one or more DDMs can be defined. DDMs are defined by DBA with PREDICT/SYSDIC.

Dictionary Metadata Field Type (T) M = MULTIPLE-VALUE FIELD - This type of field can have more than one value within a record. P = PERIODIC GROUP - A periodic group is a group of fields that may have more than one occurrence within a record. G = GROUP - A group is a number of fields defined under one common group name. This makes it possible to reference several fields collectively by using the group name instead of the names of all the individual fields. Level (L) The level number (1-9) assigned to the field. Levels are used to indicate the structure and grouping of the field definitions. This is relevant with view definitions, as well as redefinitions and field groups. Database Name (DB) The two-character database-internal field name. Name The three- to 32-character external field name. This is the field name used in a natural program to reference the field. Length (Leng) 4

The length of the field. For numeric fields (format N), length is specified as nn.m", where "nn" represents the number of digits before the decimal point and "m" represents the number of digits after the decimal point. The length of a field/element cannot exceed 253 bytes. While technically possible in Adabas 8, DBA has not implemented all Adabas eight features as of 4/12/12; therefore, the limitation of 253 is still in effect. Format (F) The format of the field: A = alphanumeric N = numeric unpacked P = packed numeric Suppression (S) The type of suppression assigned to the field: A blank = normal compression, which means the trailing blanks in alphanumeric fields and leading zeros in numeric fields are suppressed. N = null-value suppression, which means the null values for the field will not be returned when the field is used to construct a basic search criterion (WITH clause of a FIND statement) in a HISTOGRAM statement or in a READ LOGICAL statement). F = the field is defined with the fixed storage option (that is, the field is not compressed). Descriptor (D) The descriptor type of the field: A blank in this column indicates that the fields is not a descriptor. D - elementary descriptor S - superdescriptor or subdescriptor P - phonetic descriptor REMARK This column can be used for comments about the field.

The following is an example of the information above from a listing for STUDENT-SEM-FILE (F233): TL - G1 * * 2 DB Name F Leng S D Remark ---- -------------------------------- - ----- - - -----------------DM MAJOR-DEGREE-GROUP1 A GROUP CONSISTING OF A GROUP CONSISTING OF THE FOLLOWING ELEMENTS: CODE-STUD-ACDT1 DN CODE-STUD-MAJR1 A 5 N A STUDENT'S PRIMAR 5

Calculating to make sure there is ample space for any DBA request: Step 1: List Userview Step 2: Using DB short name eliminate dups Step 3: Add up data bytes:make some assumptions about MU's and PE's or run an ADHOC to get the max C* value on file or look at code to see how many occurrences are populated. Step 4: Is the number of data bytes less than 5040? This restriction goes away with Adabas V8. As of 4/12/12, not all features are in Adabas 8 per DBA. ISIS Refresh Information 1. ISIS Refresh runs in September and March. During this time, you may experience delays with requests because of the refreshing of these files: 202,203,204,205,207,208,214,218,222, 225,227,228. 2. Ample time should be allowed to move pending changes into both test and production since these test and production files must be in sync at the time of the REFRESH. If you have elements in test and not in production with any of these files at the time of the REFRESH, then the changes will be lost from TESTAIS. 3. FILES 188 AND 189 ARE NOW EXCLUDED FROM THE REFRESH. (These are Degree Audit Files and Registrar is in the process of deleting them and the programs accessing these files.) Note that File 208 FILE-LOAN-TABLE was added to the ISIS Refresh March 27, 2005. Note that File 334 LETTER-TABLE is a table file but will not be a part of the REFRESH. The users are using this file uniquely; therefore, it is kept out of the REFRESH for now (per Jean Chamberlin).

Guidelines for Reusing Fields 1. When reusing fields in ADABAS files, it is feasible to do the following with the following cautions: You should not reuse an INDC field because it is almost always fixed length, unless youre reusing it for another INDC or it was never defined to fixed length originally. In Natural, elements no longer in use are marked UNUSED by the data steward in the online data dictionary. It does not mean that the data has been cleaned up. Look at the eDDS cross references as well. The data steward has to release the field manually. The goal is to clean up the references, remove them from modules, and reset the data accordingly when marking them as UNUSED. Please use eDDS, natscans, and any other tools/utilities to determine UNUSED elements. In all cases, it is your responsibility to

initialize the contents of the field and to see whether the existing unused field is used in any production/test modules, adhoc libraries, and to remove them. 2. For alphanumeric fields, it is possible to: Keep the same format Increase the length of the field (except when it was fixed length originally)

3. For numeric fields, it is possible to: Keep the same format. Change the format from numeric to alpha. o Requires a conversion and is not advisable. o Must check if the existing unused field is used in any production/test modules and remove any data that is in those fields. Keep in mind this is also important to remove or change them in adhoc libraries. Increase the length of the field (except when fixed length originally) o NOTE: If the field has decimal places, the system will not adjust for the new length. You are responsible for initializing or adjusting the contents of the field. Tips when changing existing numeric fields currently in use 1. When increasing the field in the last position, for example going from N3.1 to N3.2, you must convert your data. 2. Adabas will right justify the data and put in leading zeros. Note that, when moving from N6 to N5.2, Adabas will not automatically change the number 310 to 310.00. It will instead become 3.10, and you will have to convert your data and restow any modules that use that converted element in the DDM. Likewise, changing 0.123 (a N1.3 field) to N1.6 will produce the resulting number 0.000123 without converting the data. New fields are usually defined as numeric even when there is a chance for the data to be used for arithmetic functions. One caution when choosing a numeric format, such as with a field for phone number, is that since there is the real potential for the field to not be filled in, for a numeric formatted field, you would have to move zeros to it or the update/store will fail. Also, some foreign numbers used to have alpha characters in them.

Steps to follow when changing a field format: 1. Coordinate with DB/DBA groups on this file and the conversion. 2. Convert all the data with your adhoc from the beginning of time to the present (including archived data). 3. Restow all the modules with a comment of why restow occurred (Typically: New DDM resulting from the change of format). 7

4. Send an email to all those involved on this conversion of the file from your cross references (eDDS, scans, and so forth) so that they are informed in case of any problems. 5. It is not advisable to reuse a field when one or more of the following conditions are required: Changing an alpha/numeric format to a numeric format. We can change a numeric to an alpha/numeric because numerics are accepted in an alphanumeric format. Decreasing the length of the field. Changing from a MU (multiple value) or PE (periodic group) to a single occurrence or vice/versa. Moving the field around within the record.

Note: It is not permitted to have a PE within a PE. Also, experience has shown that currently (in our environment), reformatting a PE does not work. If a descriptor is labeled as "U" (unique) in the dictionary, there should be a one-to-one match between the ID and Name.

Required Steps to Designate a field UNUSED and REUSABLE. 1. You must see if the existing unused field is used in any production/test modules and remove them by utilizing all cross references (eDDS, natscan, and so forth). This also pertains to adhoc libraries. Most of the time, you will find that they only exist in the GU modules (testdata, deldata) if they are cleaned up properly. If the referencing GU modules are glue/action routines, then they may need to be changed. 2. You must clear out (reset) the data that is in that field--in both test and production with a updatable adhoc. 3. Once this is done, send a request to the data steward of the field for approval and then request to have it marked as UNUSED for test and production with DBA. 4. Once you receive official confirmation that it is now marked as UNUSED, you can use the UNUSED function (AIS UNUSED FIELDS INQUIRY) in testais Natural and list your file that the element(field) is in to make sure it shows there as UNUSED. It should also show in the online DICT as not maintained. If you need a status update, then you can check your request in the RFS system. 5. In eDDS, fields that are not in use are those that do not cross reference any modules in production. Elements may still appear in the Adabas Field To Module XREF with reference to general utility modules. Modules other than general utilities will need to be investigated should you choose to reuse the element. Second, check the Adabas Fields Not Used XREF. This XREF shows unused fields from a weekly examination of source code.

6. Some additional cautions:

Do not assume the list of unused elements is complete with up-to-the-minute accuracy. Unused elements that were used previously may contain data that will need to be deleted.

Renaming of fields Renaming of fields must be coordinated with the Data Administrators of the DBA group to carefully track when your changes occur. You must restow your modules under the new DDM definition and move your modules to production at the same time as the database changes occur.

Some General Adabas Naming Conventions and Good Practices The first-level qualifier for a database field should be INDC for indicator, PCNT for percentage, QNTY for number, and so forth. Refer to the section CONVENTIONS FOR NAMING DATA ELEMENTS. The second-level qualifier for database requests is in RN.ENTITIES for element names. The second-level qualifier must be unique to the file. There are no restrictions on the bytes for SD's with length. They should have KEY in the first or last bytes of the SD. New Superdescriptors should be named with the values that make up the Superdescriptor. For example, SEM-CAMP-COLL-MAJR-LVL-RES-KEY (code-univ-yr-sem, codecamp, code-coll, code-stud-tuit-major, code-stud-lvl, code-stud-residence) or KEYSTUD-REC-SEM would consist of STUD (NUMB-STUD-ID), REC (CODE-UNIVREC-TYPE), and SEM (CODE-UNIV-YR-SEM). This is helpful when you list the file online as it can make it unnecessary to drill down on the Superdescriptor. MUs or PEs should have GRUP as the first-level qualifier or last-level qualifier. If GRUP is the first-level qualifier, then the second-level qualifier should be the four-byte name of the file (for an example STUD, UNIV, CSEC, and so forth). If GRUP is the lastlevel qualifier, then the first-level qualifier should be the four-byte name of the file. Please list the file in natural to see the proper naming conventions using the command: L F STUDENT-SEM-FILE <ENTER>. Change of documented description information in an element is the Data Steward's responsibility. This is done using the DICT application. Adding of new record types to Userviews or files should be sent to Data Administration for them to document. This is valuable when accessing the DICT function in natural and with analysis. Maximum length of element name and File Names for the DDMs can only be 32 bytes, including hyphens. Within Adabas, the file names are shorter. When creating a code field for tracking the userid, the USERID should be the third-level qualifier on the field name. For example: CODE-EMPL-USERID-MINR2-UPD 9

When creating a date field for tracking, the UPDT or UPD (based on field length) should be the last-level qualifier on the field name. For example: DATE-STUD-MAJR1-UPDT Caution should be used when running data conversion for files 211, 212, 217, 219, 233, 235, and 238 as these can have long run times. Also, run time for converting File 223 should be a concern if it involves the conversion of a PE. When creating a new file, you must specify the number of records in test and production. If not estimated correctly, then the file will lock (a bad thing that results in night phone calls). Both test and production counts are required. Database requests should be requested in a timely manner for test and production so that they are not out of sync for a long period of time. Never request test (229) and production (227) at the same time. Your changes must be tested in TESTAIS first. You cannot request production changes (227) during any production freeze period. These requests should be thoroughly tested to make sure it is working the way it is intended. Conversions of fields must be coordinated with the users, DBA, stewards, and so forth. Date and time of stewards approval must be on the RFS request for auditing purposes. Approval of IT manager must be on the RFS request for Auditing purposes. If the IT manager is also defined as the steward, then this will be sufficient. Please refer to ROSCOE member CG.STEWARDS for a list of stewards when requesting database fields, new Userview, or a file. If you are adding a new steward, then you must submit that information to Data Administration of AIS. Data Administration will set the individual up in PREDICT as a valid steward. Once this is done, you can then send your field requests.

Security levels Level 0: Basic student data, which is best thought of as the directory information items defined by FERPA. Level 1: Student demographic data, such as veteran status or EOP codes (Educational Opportunity Program) Level 2: Student sensitive data such as student number, grade information, graduation status, tuition, and so forth. Level 3: Most sensitive data, such as ethnic code.

Data security with regard to changing sensitive elements within PE groups: It is likely that programs will obtain the entire PE group including newly sensitive group elements. You may need to change the program to obtain the individual fields of the PE group.

Adding a new Userview When adding your userviews, remember to include your individual libraries as well on the initial request. 10

On the add request form, if you do not do the auxiliary option area, then you will have to have the data steward of that element incorporate it into the data dictionary. If you include it on the initial form, then data administration will take care of it for you. This information is optional. You must provide a short abstract for the new Userview. The usual format is a short description of the function of the Userview. Some examples: U-NSLDS-OVERVIEW: This Userview contains the overall current and cumulative balances, processing codes, and contacts for a borrower. Supplied by the federal processor. U-NSLDS-LOAN-DETAIL: This Userview is an array of individual loan information for a borrower across all times and locations. Supplied by the federal processor. And for the file: The NSLDS file is designed to house information for a borrower chronicling his/her loan history at all schools and all years.

Caution Regarding SSN Requests 1. According to AD-19, if an SSN is stored anywhere except on CIDR, then the Privacy Officer needs to approve it. Documented approval by the Privacy Officer must accompany the DBA requests for storing SSN. It is required that you inform DBA and name the field NUMB (A9) if you have an SSN in that field. 2. At this time, Scott Bitner (Steward of CIDR) and Sarah Morrow (Chief Privacy Officer) must be involved in the approval process. Caution Defining the Security Level on SSN Fields 1. TESTDATA should reset any Production SSN field or replace it with a unique (non-SSN) number when moving to TESTAIS. If necessary, simply do not copy the database field to TESTAIS that has SSN in production. 2. DUMPDATA should include the Production SSN field. (If in doubt, ask a senior team member for advice.) The SSN could be different on the bad record verses the good record and hence the actual value could be critical in a DUMPDATA usage. 3. Watch emails or hardcoding in modules, especially in ADA225 Other General Adabas Precautions New supers, PE's, MU's, etc. are database changes that require an ADAREORG that can be time consuming and storage intensive (unloading and reloading of the file structure). Larger files must be done during the weekend. These jobs cannot be interrupted without risking the file integrity. Poor time estimations on run time can leave these jobs still running at 7 a.m. in a locked condition and inaccessible, essentially bringing down at least portions of ISIS or IBIS. To remove a screen or path from the menu system, refer to the appropriate form within the AIS Request for Service (RFS) system. 11

Please always value the integrity of these names, data, files, and the database with your changes. If you are unsure, then please contact multiple people. Also, whether your changes require a conversion or not, please involve all necessary parties (eLion, ISIS, IBIS, DB, DBA, managers, stewards, and users) to ensure proper seamless implementation.

12