Converting Legacy Dates: The DATE NEW Subcommand

In this section:

How DATE NEW Converts Legacy Dates
What DATE NEW Does Not Convert
Using the New Master File Created by DATE NEW
Action Taken on a Date Field During REBUILD/DATE NEW

The REBUILD subcommand DATE NEW converts legacy dates (alphanumeric, integer, and packed-decimal fields with date display options) to smart dates (fields in date format) in your FOCUS data sources.

The utility uses update-in-place technology. It updates your data source and creates a new Master File, yet does not change the structure or size of the data source. You must back up the data source before executing REBUILD with the DATE NEW subcommand. We recommend that you run the utility against the copy and then replace the original file with the updated backup.

How DATE NEW Converts Legacy Dates

Reference:

DATE NEW Usage Notes

REBUILD DATE NEW subcommand overwrites the original legacy date field (an alphanumeric, integer, or packed-decimal field with date display options) with a smart date (a field in date format). When the storage size of the legacy date exceeds four bytes (the storage size of a smart date), a pad field is added to the data source following the date field:

Formats A6YMD, A6MDY, and A6DMY are changed to formats YMD, MDY, and DMY, respectively, and have a 2-byte pad field added to the Master File.
The storage size of integer dates (I6YMD, I6MDY, for example) is 4 bytes, so no pad field is added.
All packed fields and A8 dates add a 4-byte pad field.

When a date is a key field (but not the last key for the segment), and it requires a pad field, the number of keys in the SEGTYPE is increased by one for each date field that requires padding.

DATE NEW only changes legacy dates to smart dates. The field format in the Master File must be one of the following (month translation edit options T and TR may be included in the format):

A8YYMD A8MDYY A8DMYY A6YMD A6MDY A6DMY A6YYM A6MYY A4YM A4MY

I8YYMD I8MDYY I8DMYY I6YMD I6MDY I6DMY I6YYM I6MYY I4YM I4MY

P8YYMD P8MDYY P8DMYY P6YMD P6MDY P6DMY P6YYM P6MYY P4YM P4MY

If you have a field that stores date values but does not have one of these formats, DATE NEW does not change it. If you have a field with one of these formats that you do not want changed, temporarily remove the date edit options from the format, run REBUILD DATE NEW, and then restore the edit options to the format.

Reference: DATE NEW Usage Notes

The DBA password for the data source must be issued prior to issuing REBUILD.
The original Master File cannot be encrypted.
All files must be available locally during the REBUILD, including LOCATION files.
The Master File cannot have GROUP fields.
Some error numbers are available in &FOCERRNUM while all error numbers are available in &&FOCREBUILD. Test both &&FOCREBUILD and &FOCERRNUM for errors when writing procedures to rebuild your data sources.
To avoid any potential problems, clear all LETs and JOINs before issuing REBUILD.
DEFCENT/YRTHRESH are respected at the global, data source, and field level.
Correct all invalid date values in the data source before executing REBUILD/DATE NEW. The utility converts all invalid dates to zero. Invalid dates used as keys may lead to duplicate keys in the data source.
Adequate workspace must be available for the temporary REBUILD file. As a rule of thumb, have space 10 to 20% larger than the size of the existing file available.
REBUILD/INDEX is performed automatically if an index exists.
REBUILD/REBUILD is performed automatically after REBUILD/DATE NEW when any key is a date.
Sort libraries and work space must be available (as with REBUILD/INDEX). The REBUILD allocates default sort work space in z/OS, if you have not already. DDNAMEs SORTIN and SORTOUT must be allocated prior to issuing a REBUILD.

What DATE NEW Does Not Convert

The REBUILD DATE NEW subcommand is a remediation tool for your FOCUS data sources and date fields only. It does not remediate:

DEFINE attributes in the Master File.
ACCEPT attributes in the Master File.
DBA restrictions (for example, VALUE restrictions) in the Master File or central security repository (DBAFILE).
Cross-references to other date fields in this or other Master Files.
Any references to date fields in your FOCEXEC.

Example: Using the DATE NEW Subcommand in Windows

The following procedure:

1. SET DFC = 19, YRT = 50 
2. REBUILD 
3. DATE NEW 
4. NEWEMP.MAS 
5. YES

Sets the DEFCENT and YRTHRESH parameters that determine which century to use for each date.
Initiates the REBUILD facility.
Specifies the DATE NEW subcommand.
Provides the name of the Master File that specifies the dates to convert.
Indicates that the data source has been backed up.

The dates will be converted and the appropriate statistics will be generated, including the number of segments changed.

The new Master File is an updated copy of the original Master File except that:

The USAGE format for legacy date fields is updated to remove the format and length. The date edit options are retained. For example, A6YMDTR becomes YMDTR.
Padding fields are added for those dates that need them:
```
FIELDNAME= ,ALIAS= ,FORMAT=An,$ PAD FIELD ADDED BY REBUILD
```
where:

n

Is the padding length (either 2 or 4). Note that the FIELDNAME and ALIAS are blank.
The SEGTYPE attribute is updated for segments that have remediated dates as keys when the date requires padding and the date is not the last field in the key. The SEGTYPE number will be increased by the number of pad fields added to the key.
If the SEGTYPE is missing for any segment, the following line is added immediately prior to the $ terminator for that segment:
```
SEGTYPE=segtype,$ OMITTED SEGTYPE ADDED BY REBUILD
```
where:

segtype

Is determined by REBUILD.
If the USAGE attribute for any field (including date fields) is missing, the following line is added, immediately prior to the $ terminator for that field:
```
USAGE=fmt,$ OMITTED USAGE ADDED BY REBUILD
```
where:

fmt

Is the format of the previous field in the Master File. REBUILD automatically assigns the previous field format to any field coded without an explicit USAGE= statement.

Using the New Master File Created by DATE NEW

REBUILD DATE NEW subcommand creates an updated Master File that reflects the changes made to the data source. Once the data source has been rebuilt, the original Master File can no longer be used against the data source. You must use the new Master File created by the DATE NEW subcommand.

Example: Sample Master File: Before and After Conversion by DATE NEW

Before Conversion	After Conversion
FILE=`filename`	FILE=`filename`
SEGNAME=`segname`, SEGTYPE=S2	SEGNAME=`segname`, SEGTYPE=S3
FIELD=KEY1,,USAGE=A6YMD,$	FIELD=KEY1,,USAGE= YMD,$ FIELD=, ,USAGE=A2,$ PAD FIELD ADDED BY REBUILD
FIELD=KEY2,,USAGE=I6MDY,$	FIELD=KEY2,,USAGE= MDY,$
FIELD=FIELD3,,USAGE=A8YYMD,$	FIELD=FIELD3,,USAGE= YYMD,$ FIELD=, ,USAGE=A4,$ PAD FIELD ADDED BY REBUILD

When REBUILD DATE NEW subcommand converts this Master File:

The SEGTYPE changes from an S2 to S3 to incorporate a 2-byte pad field.
Format A6YMD changes to smart date format YMD.
A 2-byte pad field with a blank field name and alias is added to the Master File.
Format I6MDY changes to smart date format MDY (no padding needed).
Format A8YYMD changes to smart date format YYMD.
A 4-byte pad field with a blank field name and alias is added to the Master File.

Action Taken on a Date Field During REBUILD/DATE NEW

REBUILD/DATE NEW performs a REBUILD/REBUILD or REBUILD/INDEX automatically when a date field is a key or a date field is indexed. The following chart shows the action taken on a date field during the REBUILD/DATE NEW process.

Date Is a Key	Index	Result
No	None	NUMBER OF SEGMENTS CHANGED = n
No	Yes	REBUILD/INDEX on date field.
Yes	None	REBUILD/REBUILD is performed.
Yes	On any field	REBUILD/REBUILD is performed. REBUILD/INDEX is performed for the indexed fields.