PURPOSE: The equated command FLATTEN converts a copy of a Data Base Library (DBL) into ASCII form and places it into a "flat" text file. This file can be edited by any of the text editors available on your system such as EDT, EMACS and VI. The original DBL is still intact after FLATTEN is used. This is useful for doing global searches of the text.
FLATTEN can be used in conjunction with the REBUILD utility to REBUILD a DBL from a Flattened version. If you need to move a DBL from one system to another, FLATTEN and REBUILD can facilitate the move.
There are two forms for FLATTEN: the utility command invoked by itself will prompt the user for information; or the user may supply options and bypass the prompts (see EXAMPLE).
The FLATTEN and REBUILD utilities are used together. These utilities assist with large-scale modification of ACCENT R applications and the conversion of one version of ACCENT R to another. With FLATTEN and REBUILD, the need to edit and compile each object individually is eliminated. FLATTEN will use INSERT for defining DBL items which defaults to line numbers beginning at 100 incremented by 10. If you want to change this, store the INSERT command you want used into @STRING before giving the FLATTEN command. For example:
*SET "INSERT 1,1" TO @STRING
FLATTEN_ALL will take a directory specification and flatten all DBL's found in the path defined. It will tell you whether or not the current version of ACCENT R can FLATTEN the DBL and if not, will show you which version created the DBL. The following files are created.
|
DBL_LIST.LOG |
Lists all the DBL's found. It indicates if they can be flattened in this version of ACCENT R or displays error messages as to why they cannot be flattened. |
|
ACC_FLATTEN_DBL.COM |
A COM file to be executed to flatten the specified DBL's. |
|
ACC_REBUILD.COM |
A COM file to be executed to REBUILD all the FLATTENED DBL's. |
|
ACC_REMOVE_DBL.COM |
A COM file to be executed to delete all the flattened files after the DBL's have been recreated. |
|
ACC_REMOVE_OLD_DBLS.COM |
A COM file to be executed to delete the old DBL files that were renamed as DBL_name_DBL_OLD so you could restore them if the rebuild failed for any reason. |
FORM 1: with prompts
FLATTEN [HELP]
FORM 2: options bypass prompts
FLATTEN DBL dbl_name TO flat_file [SECURITY TO security_file]
[CLEAN] [LIST] [HOLD]]
|
FLATTEN DBL dbl_name |
specifies the DBL to be copied and FLATTENed into a text file. |
|
TO flat_file |
specifies the name of the text file that will hold the FLATTENed DBL copy. |
|
SECURITY TO security_file |
separates security information (like passwords) before the DBL is flattened to protect access. A cipher code must be also be set if the DBL is ciphered. |
|
CLEAN |
provides a version of the DBL that can be rebuilt with USE SF sf_name. (The System File (SF) name is the equivalent to the flat_file name.) It removes the old version before starting (no option to rename rebuilt DBL and save old DBL) without using REBUILD comments. |
|
LIST |
displays the DBL objects as they are being flattened. |
|
HOLD |
will HOLD all Process Modules (PM) rather than SAVE (for cases of DBL cross references). Each PM will have to be COMPILEd later. |
FORM 3: *flatten_all
FLATTEN_ALL
Make sure you have sufficient privileges allowing you to access the directories that are being searched for DBL's to be Flattened. You must have both READ and WRITE access for this utility to succeed. Enter YES to proceed or else the process will abort: yes
The following five files are created by the FLATTEN_ALL command: The file DBL_LIST.LOG lists all the DBL's found. It indicates if the can be flattened in this version of ACCENT R with error messages as to why they cannot be flattened if that is the case.
The file ACC_FLATTEN_DBL.COM is a COM file to be executed to flatted the specified DBL's.
The file ACC_REBUILD_DBL.COM is a COM file to be executed to rebuild all the flattened DBL's.
The file ACC_REMOVE_DBL_FLT.COM is a COM file to be executed to delete the old DBL file that were renamed as DBL_name.DBL_OLD so you could restore them if the rebuild failed for some reason.
The file ACC_REMOVE_OLD_DBL.COM is a COM file to be executed to delete the old DBL file that were renamed as DBL_name.DBL_OLD so you could restore them if the rebuild failed for some reason.
It is suggested that you review these files before executing them to correct any errors that might appear. The COM files will not be executed by this utility. They must be run manually.
Please enter a search string to identify the directories you want searched for DBL's to be converted, for EXAMPLE: Directory: CS:[*.*]
DIRECTORY: dkaa100:[test]
SF DBL_LIST.LOG is ready for examination. You should check for DBL's which cannot be flattened by this version of ACCENT R or if it has other problems. The first part of the file contains error messages, if any are present. At the end is a list of all DBL's examined. A "YES" in the first column indicates that the utility should be able to FLATTEN the DBL listed in the account shown. if the word "VERSION" is in the first column, the DBL cannot be flattened with the version you are running and the version it was created by is shown.
Would you like the file listed?: yes
DKA100:[TEST]AUCTEST not accessible by this version (1160)
DKA100:[TEST]COMAPARE_SOURCE not accessible by this version (1137)
DKA100:[TEST]UTIL no accessible by this version (1112)
VERSION Built by 1160 DKA100:[TEST]AUCTEST
VERSION Built by 1137 DKA100:[TEST]COMAPARE_SOURCE
YES Built by 1179 DKA100:[TEST] TEST
YES Built by 1177 DKA100:[TEST] TESTV1177
VERSION Built by 1112 DKA100:[TEST]UTIL
Do you wish to proceed?: yes
The file ACC_FLATTEN_DBL.COM is ready to use to do the FLATTEN. The file ACC_REBUILD_DBL.COM is ready to use to do the REBUILD.
ACC_REMOVE_DBL_FLT.COM can be executed after the flatten/rebuild operation is completed and checked. It will deleted all the flattened files that were generated in the different accounts.
ACC_REMOVE_OLD_DBLS.COM can be executed after the flatten/rebuild operation is completed and checked. It will delete all the old DBL files that were saved in case of problems occurring.
The FLATTEN prompts will vary slightly depending on whether a DBL is declared or not at the time the utility is invoked. If no DBL is declared, there is no default DBL listed in the prompt. If a DBL is declared, it is the default DBL to be flattened. Defaults can be selected by pressing the return key (without entering data). HELP lists a description of the utility. QUIT returns control to the ACCENT R command level. An error message ("No DBL name given, try again.") will be displayed if the return key is pressed without a DBL name specified (and no default).
The following example shows FORM 1 of FLATTEN. Responses to prompts are shown in bold.
*FLATTEN
CM FLATTEN version 16.00
Enter the DBL name, HELP or QUIT: BOOKS
[Enter <cr> to use DBL BOOKS: <-- if DBL BOOKS is declared]
Enter the text file name
or <cr> to use FLAT1WLBLD.TMP: BOOKS.FLAT
Now generating flattened DBL file…
System file BOOKS.FLAT is ready.
The text file can now be edited. Invoke the editor with the MODIFY command.
*MODIFY SF BOOKS.FLAT
The text file will have comments (! **REBUILDER CODE**) inserted to show where the FLATTEN utility has placed commands to rebuild the DBL. These commands will be used by the REBUILD utility.
A partial list of REBUILDER CODE lines is provided below:
DEFINE SD name ! **REBUILDER CODE**
DEFINE DI name ! **REBUILDER CODE**
DEFINE GS name ! **REBUILDER CODE**
DEFINE PM name ! **REBUILDER CODE**
DEFINE CM name ! **REBUILDER CODE**
SAVE ! **REBUILDER CODE**
HOLD ! **REBUILDER CODE**
STOP ! **REBUILDER CODE**
END
! The preceding 'END' statement was **REBUILDER CODE**
The following example shows FORM 2 of FLATTEN.
*FLATTEN DBL BOOKS TO BFLAT CLEAN<CR>
The DBL must be rebuilt (if the CLEAN option is used) with:
*USE SF BFLAT<CR>
Now generating flattened DBL file…
System file BFLAT.CMD is ready.
NOTES: If any REBUILDER CODE lines are removed or changed, the REBUILD utility may not be able to successfully rebuild a DBL. In such a case, rerun FLATTEN and generate another text file and start editing again.
The REBUILDER CODE lines can help locate the objects to be modified. Each object’s text is preceded by a DEFINE statement, as shown above, and followed by a SAVE statement. The order of appearance for the objects in the DBL is:
1) Code Segment (CS)
2) Schema Definitions (SD)
3) Control File (CF)
4) Data Sets (DS)
5) Data Indexes (DI)
6) Global Storages (GS)
7) Process Modules (PM)
8) Command Modules (CM)
Within each group, objects will appear in the order in which they were originally created. Unless all Data Sets (DS) are empty, it is extremely hazardous to make changes that involve a field’s data type or width in any SD. This may invalidate the data by making the SD and the DS incompatible.
SEE ALSO: REBUILD Utility, COMPILE Utility Command, MODIFY Command, CONVERT Command, Security and RESAVE Command