Documenting application data

After you have determined what data elements a business process requires, record as much information about each of the data elements as possible.

This information is useful to the DBA. Be aware of any standards that you are subject to regarding data documentation. Many places have standards concerning what information should be recorded about data and how and where that information should be recorded. The amount and type of this information varies from place to place. The following list is the type of information that is often recorded.

The descriptive name of the data element: Data element names should be precise, yet they should be meaningful to people who are familiar and also to those who are unfamiliar with the application.
The length of the data element: The length of the data element determines segment size and segment format.
The character format: The programmer needs to know if the data is alphanumeric, hexadecimal, packed decimal, or binary.
The range of possible values for the element: The range of possible values for the element is important for validity checking.
The default value: The programmer also needs the default value.
The number of data element occurrences: The number of data element occurrences helps the DBA to determine the required space for this data, and it affects performance considerations.
How the business process affects the data element: Whether the data element is read or updated determines the processing option that is coded in the PSB for the application program.

You should also record control information about the data. Such information should address the following questions:

What action should the program take when the data it attempts to access is not available?
If the format of a particular data element changes, which business processes does that affect? For example, if an education database has as one of its data elements a five-digit code for each course, and the code is changed to six digits, which business processes does this affect?
Where is the data now? Know the sources of the data elements required by the application.
Which business processes make changes to a particular data element?
Are there security requirements about the data in your application? For example, you would not want information such as employees' salaries available to everyone?
Which department owns and controls the data?

One way to gather and record this information is to use a form similar to the one shown in the following table. The amount and type of data that you record depends on the standards that you are subject to. For example, the following table lists the ID number, data element name, length, the character format, the allowed, null, default values, and the number of occurrences.

Table 1. Example of data elements information form
ID #	Data element name	Length	Char. format	Allowed values	Null values	Default value	Number of occurrences
5	Course Code	5 bytes	Hexa- decimal	0010090000	00000	N/A	There are 200 courses in the curriculum. An average of 10 are new or revised per year. An average of 5 are dropped per year.
25	Status	4 bytes	Alpha- numeric	CONF WAIT CANC	blanks	WAIT	1 per student
36	Student Name	20 bytes	Alpha- numeric	Alpha only	blanks	N/A	There are 3 to 100 students per class with an average of 40 per class.

A data dictionary is a good place to record the facts about the application's data. When you are analyzing data, a dictionary can help you find out whether a particular data element already exists, and if it does, its characteristics. With the IBM® OS/VS DB/DC Data Dictionary, you can determine online what segments exist in a particular database and what fields those segments contain. You can use either tool to create reports involving the same information.