|
Define / Convert File |
Last Revised: 12/27/16 |
This called routine will define or convert a file based on information contained in the Data Dictionary and define or replace the .tpl template file. The Data Dictionary is maintained using the Data Dictionary Maintenance on the FMS menu.
CDS034 provides the following functions:
Defines permanent data files in the XX/ directory (or other directory
specified) if the data file does not
exist.
Defines or replaces the template file in the XX/tpl/ directory (or in tpl
directory below data file) for permanent
data files if the data file does not exist.
Defines temporary data files in the $SMSDIR/tmp directory using a unique file
name and placing the template in global memory for use by applications.
Takes no action and exits quietly if the data dictionary field structure
(including mask and title fields) is the same as the .tpl template file, and the
data dictionary key structure matches that of the existing data file.
Analyzes the differences between the data dictionary and current file, returns these differences to calling program, and converts the file (when necessary) to match the data dictionary.
When file conversion takes place, CDS034 optionally archives the original
file with the standard .YYMMDD suffix when S034.MODE$ is passed as "Y".
Can convert files of one type to another, i.e., DIR to SKY or MKY, SKY to MKY.
Optionally performs analysis but does not perform any conversion.
Field conversion includes: adding fields, deleting fields, changing the number of elements in an array, changing the field type, i.e., U(3) to B, or N(7) to C(7), etc.
When file conversion is required, the converted data file will reside in the
same directory as the original, even if in an alternate directory such as in XX/DAT/ instead of just in XX/.
Warning: In most cases you should not simply CALL "CDS034" from console mode. It is much better to use the File Utility 'Compare to Data Dictionary' option, since it will give you a chance to review the changes to be made before deciding to convert. The File Utility archives both the original file and template file so that you can restore the archived copies when necessary.
Warning: CDS034 assumes that the data in the original file matches the template. If there is ever any uncertainty, then run the File Utility option 'Verify Data to Template' before converting the file.
Calling Format:
Call "CDS034", ERR=XXXX, FILNAM$, { S034$ }
Sometimes the template field type is changed. For example, an N(2) field could be converted to a U(2) field, or an N(10*) field could be converted to a B type field. CDS034 will attempt to convert all field types, even C type fields to a numeric when possible. CDS034 will display an error message and abort a file conversion should a field conversion not be possible, or the data does not match the template.
We recommend that you avoid N type fields, especially when they are used in key segments. BBx left justifies N type fields and is not consistent as shown in the example below. Another reason to avoid N type fields in key segments is that the BBx SELECT optimization logic used to choose the best KNUM for the file, and to do a position READ within the file only works with C type fields.
| BBx N type field issues | Note |
>DIM REC$:"NO:N(6)"
|
BBx zero fills N type fields upon a DIM. |
>REC.NO=0
|
BBx does not zero fill on a simple assignment. This can cause problems if the field is used in a key segment. |
>REC.NO=15
|
BBx left justifies N type fields within the field. |
>REC.NO$=STR(15:"######")
|
You can right justify N type fields by using STR() but then you have to be careful that every program does it. |
Special Field Conversion Notes
| Current Field Type |
New Field Type |
Notes |
| C | N | File conversion will abort if you cannot take NUM() of string field. When new field type is a fixed length such as N(2) not N(2*), and is the same length as the current field type, i.e., C(2), the field will be converted as a string instead of a numeric, so that a field containing " 5" will remain " 5" and not "5 ". This is especially important when the field is used as a key segment. |
| N | C | This field conversion is similar to the C to N conversion described above, in that CDS034 will copy the field as a string retaining any leading spaces in the string version of the original field, when the new field type is a fixed length, and the field sizes are the same. |
| U | C | CDS034 converts the U type field to its numeric value, then pads the value with leading spaces, so that a U(2) field with a value of 10, will become " 10" if converted to a C(4) or C(4*) field. If the field sizes are the same, and you simply want a U(3) field to be copied as a string to a C(3) field, then you should edit the .tpl file, and not use CDS034. |
| C | U | This will work properly if the current field simply contains
numbers, but if the C type field contains binary data, as a U type field
does, then CDS034 will abort with an error message should it be unable
to take the NUM() of the current C field. |
Examples:
This example will compare the current file structure to that in the data dictionary and return the details in S034$. No file conversion will take place. Note that the File Utility (SMU) 'Compare to Data Dictionary' also performs this step and displays the results in a scrolling window.
| Test only, no data conversion example |
|---|
READY
|
| Define/Revise single file |
|---|
CALL "CDS034","DSCM01"
|
Defines file DS/DSCM01 if it did not exist in any prefix. If it does exist, the data structure including field names, field sizes, and key structure are compared to that contained in the Data Dictionary. If a conversion is required, then the file and template will be converted to match the specification contained within the Data Dictionary. If the file exists, it will remain in the same directory it was located in. For example if the PFX includes PY/ PY/DAT and the file PY/DAT/PYUD10 exists, calling CDS034 with PYUD10 will convert this file and the converted file will remain in the PY/DAT directory.
Template files are typically created in a tpl directory immediately below the data file directory. In this example, the template file should be PY/DAT/tpl/PYUD10.tpl. Note that these template files are created by CDS034 and should not normally be edited or altered. If the template is not found in the preferred location, the tpl directory under the company code is used, i.e., PY/tpl/PYUD10.tpl. See CDS041 for additional information about templates.
| Archive original file |
|---|
S034$="Y"
|
| Check/Convert all files in company |
|---|
CALL "CDS034","DS"
|
Checks each data file contained within the Data Dictionary for company DS, and defines or converts those required.