View source for Dictionary/204 migration subsystem


==Overview==
<p>
The DDMIG subsystem allows authorized users to migrate Dictionary data from one Model 204 environment to another. You can use DDMIG to export or import the following dictionary entities, including user-defined attributes and descriptions:</p>
<ul>
   <li>fields</li>
   <li>field groups</li>
   <li>procedures</li>
   <li>records</li>
   <li>screens</li>
   <li>screen items</li>
   <li>views</li>
   <li>view fields</li>
   </ul>
<p>
To migrate subsystem definitions, use the [[System requirements for Application Subsystems#Subsystem Import/Export options|SUBSYSMGMT Export and Import options]].</p>
<p>
Both DDMIG and the SUBSYSMGMT Export and Import options use the intermediate file D204SYS, a Model 204 file created during Dictionary/204 installation. The D204SYS file must be defined to each Model 204 environment that uses DDMIG or SUBSYSMGMT Export/Import.</p>
<p>
If you are migrating files belonging to a subsystem as well as the subsystem definitions, it does not matter which facility you use first.</p>

==DDMIG security==
<p>
To use DDMIG, you must be authorized by the dictionary administrator through the DICTADMIN Security screen.</p>
<p>
DDMIG is a semipublic AUTOSTART subsystem. </p>

==Invoking DDMIG==
<p>
If you are authorized to use DDMIG, you can invoke it by issuing the command DDMIG with any of the following parameters:</p>

<p class="syntax">DDMIG {EXPORT <span class="term">filename</span> | 
       IMPORT [CHECK | <span class="term">filename</span> | ALL | ALLC] PENDING |
       DELETE [<span class="term">filename</span> | ALL] |
       LIST}</p>

==DDMIG EXPORT command==
<p>
Exporting a file means that you add Dictionary/204 data to the intermediate file D204SYS, from which the data can then be imported to another Model 204 environment. </p>
<p>
To export a file, enter the command:</p>

<p class="syntax">DDMIG EXPORT <span class="term">filename</span></p>
<p>
where <var class="term">filename</var> is the name of the Model 204 file to be exported. </p>
<p>
Files must be exported one at a time. To export more than one file, you must issue the DDMIG EXPORT command repeatedly. The number of files you can export is limited only by the size of D204SYS (refer to the Rocket Model 204 installation instructions for your operating system for instructions on how to create and size D204SYS). </p>
<p>
If Model 204 file information differs from dictionary data, you must run [[Dictionary/204 administration#Creating or updating Dictionary entries with DDGEN|DDGEN]] before running DDMIG.</p>
<p>
The DDMIG EXPORT run terminates with an error message under any of the following circumstances:</p>
<ul>
<li>You omit the filename.</li>
<li>File has staged commands.</li>
<li>File does not exist in your Model 204 Dictionary.</li>
<li>File is being updated through the FILEMGMT facility.</li>
<li>You cannot access D204SYS.</li>
<li>File has already been exported to D204SYS.</li>
</ul>
<p>
If you want to export a file that has previously been exported, you can do so by first deleting the D204SYS entry with the DDMIG DELETE command.</p>
<p>
Once you have specified a valid filename, DDMIG issues the prompt:</p>
<p class="code">SPECIFY REPORT DESTINATION </p>
<p>
Here you can enter the name of a sequential file, or (if you are in Online mode) you can press Enter to display the report on the screen. </p>
<p>
A sample EXPORT Report is shown below.</p>
<p class="caption" style="width:400px">Sample EXPORT Report</p>
<p class="figure">[[File:Dictionary_fig12-1.png]] </p>

==DDMIG IMPORT command==
<p>
Importing means that you retrieve Dictionary data from the intermediate file D204SYS. When Dictionary data is imported, entries are added to the target Dictionary for the following entity types. User-defined descriptions and attributes are also added for each entity type.</p>
<p>
For each file that DDMIG imports, the following entries are created:</p>
<table>
<tr class="head">
<th>Entity type</th>
<th>Dictionary information stored</th>
</tr>
<tr>
<td>FILE</td>
<td>One entry is added, containing all Dictionary/204 data associated with the file, including links to procedures, fields, field groups, records, views, and view fields.</td>
</tr>
<tr>
<td>PROCEDURE</td>
<td>
One entry is added for each procedure with associated attributes. If the procedure defines a SCREEN, relationships among procedure, SCREEN, and SCREEN ITEMs are added, for each screen and item that has been exported.
</td>
</tr>
<tr>
<td>RECORD</td>
<td>One entry is added to the Dictionary, if no record is defined for the imported file. If records are defined, one Dictionary entry is added for each record. Preallocated field are cross-referenced to a record entry. Relationships between the file and a record are added, as are relationships between the record and its fields.</td>
</tr>
<tr>
<td>FIELD</td>
<td>One entry is added for each field, with values for field attributes and relationships between the file and each field.</td>
</tr>
<tr>
<td>FIELD GROUP</td>
<td>One entry is added for each group of repeating fields in the file.</td>
</tr>
<tr>
<td>VIEW</td>
<td>One entry is added for each view, including links to file, records, and view fields.
</td>
</tr>
<tr>
<td>VIEW FIELD</td>
<td>One entry is added for each view field, including links to views and fields.</td>
</tr>
<tr>
<td>DESCRIPTIONS</td>
<td>For each of the entity types, any user descriptions created through the DOCUMENT facility are added to the appropriate entries.</td>
</tr>
<tr>
<td>ATTRIBUTES</td>
<td>For each of the entity types, user attributes entered through the DICTADMIN facility are added to the appropriate entries.</td>
</tr>
</table>

===DDMIG IMPORT parameters===
<p>
You can use the following parameters with the DDMIG IMPORT command:</p>
<ul>
<li>CHECK</li>
<li>ALL</li>
<li>ALLC</li>
<li>filename</li>
</ul>
<p>
The parameters are described in detail in the following sections.</p>
<p>
A further option with ALL, ALLC, or filename is PENDING. When dictionary data is imported in Pending mode, CREATE commands can be executed either directly from the FILEMGMT Execute Commands screen or in batch mode, as described in [[#DDMIG IMPORT PENDING option|DDMIG IMPORT PENDING option]]. When the Pending commands are executed, the entities are defined to Model 204 as well as Dictionary/204. </p>

====CHECK parameter====
<p>
The CHECK parameter tells you which files currently reside in D204SYS, which of those files already exist in the target Dictionary. and which fields are undefined. It is usually prudent to run CHECK before importing Dictionary/204 data. A sample CHECK screen follows. </p>

<p class="caption" style="width:400px">Sample CHECK screen</p>
<p class="figure">[[File:Dictionary_fig12-2.png]]</p>

====ALL, ALLC, and <i>filename</i> options====
<p>
The ALL and ALLC options import all the file information currently residing in D204SYS to the target Dictionary. </p>
<p>
The ALL option executes the import command as a single update; if an error occurs while importing one of the files, processing terminates with an error.</p>
<p>
The ALLC option does not execute the IMPORT command as a single transaction; if an error occurs while importing one of the files, processing continues with the next file in D204SYS.</p>
<p>
The <var class="term">filename</var> option imports Dictionary data for a single file.</p>
<p>
The ALL, ALLC, and filename options can all take the further parameter [[#DDMIG IMPORT PENDING option|PENDING]].</p>
<p>
After you issue any of these forms of the DDMIG IMPORT command, you are prompted for a report destination. Supply the name of a sequential file or press Enter for screen output. </p>
<p>
The IMPORT run terminates with an error message under any of the following circumstances:</p>
<ul>
<li>File's metadata already exist in the target Dictionary.</li>
<li>File's datalink relationships are already in the target Dictionary.</li>
<li>Fields for user-defined attributes are not defined in the target Dictionary.</li>
<li>File name you specified is not in D204SYS.</li>
</ul>
<p>
You can avoid the above error conditions by running DDMIG IMPORT CHECK and taking the appropriate action (for example, by deleting or renaming data in the target Dictionary).</p>
<p>
If a user has updated D204SYS since the last LIST or CHECK performed by the importing user, the DDMIG subsystem displays a Y or N prompt asking you if you want to continue.</p>

===DDMIG IMPORT PENDING option===
<p>
The PENDING option can be used with ALL, ALLC or a single filename. When this option is specified, the Dictionary data is imported as staged data with the command state Pending. The staged commands can then be executed from the [[Executing and deleting commands with FILEMGMT#Execute Commands screen|Execute Commands screen]]. </p>
<p>
This job can also be performed in one step using the DDMIG job (z/OS or z/VSE) or the DDMIG option of the D204 EXEC (z/VM). You must specify a DD statement (z/OS); DBL, EXTENT and ASSIGN statements (z/VSE); or LINK, ACCESS and FILEDEF statements (z/VM) for each file to be actively imported and physically created using FIMO.BATCHCMD.</p>
<p>
Once the Pending commands are executed, the file is physically created along with any fields defined to the file.</p>
<p>
The following DDMIG CCAIN stream actively imports file data (executes staged commands with status Pending). Files can be imported actively by uncommenting the commands that follow the OUTFILE line. 
</p>
<p class="code"><nowiki>PAGESZ=6184,SPCORE=20000,NFILES=110,NDCBS=110,NDIR=110,
INCCC=0,MINBUF=10,LENQTBL=300,SERVSIZE=215000,LOGADD=10,
LITBL=150,LFSCB=7000,LSTBL=10000,LGTBL=500,LRETBL=5000,NORQS=6 
LOGON userid
password
DDMIG IMPORT filename PENDING
OUTFILE 
*OPEN M204PROC 
*IN M204PROC INCLUDE FIMO.BATCHCMD 
*filename 
*** 
EOJ</nowiki></p>
<p>
where:</p>
<table>
<tr>
<td>userid</td>
<td>Is filemanager.</td>
</tr>
<tr>
<td>password</td>
<td>Is the password for that user ID.</td>
</tr>
<tr>
<td>filename</td>
<td>Is the name of the file to be imported. Here you can specify ALL to import all files that have been exported.</td>
</tr>
</table>
<p>
Follow these guidelines: </p>
<ul>
<li>Three asterisks (***) following <var class="term">filename</var> are required for FIMO.BATCHCMD; if you are using active import, <strong>do not</strong> remove them.</li>
<li>If you are using active import for more than 10 files, you must increase LOGADD by the number of files exceeding 10.</li>
<li>OUTFILE refers to the report file for the run. </li>
</ul>

==DDMIG LIST command==
<p>
The command DDMIG LIST generates a report exactly like the CHECK report described in [[#CHECK parameter|CHECK parameter]], except for the error checking and undefined field messages.</p>

==DDMIG DELETE command==
<p>
To delete files from D204SYS, issue the command:</p>

====Syntax====
<p class="syntax">DDMIG DELETE [ALL | <span class="term">filename</span>]</p>
<p>
If you specify ALL, DDMIG deletes all files in D204SYS. Before clearing D204SYS, DDMIG displays a Y or N prompt, asking you if you want to continue.</p>

==DDMIG restrictions==
<p>
The following restrictions apply to the DDMIG subsystem:</p>
<ul>
<li>You must execute both the Export and Import steps using the same Model 204 version.</li>
<li>If DATALINK relationships exist in the target Dictionary for a file to be imported, they must be deleted or renamed before the import.</li>
<li>DDMIG does not import the file control record; therefore, it cannot migrate user-defined entities linked to files, fields, records, or procedures.</li>
</ul>

==See also==
{{Template: Dictionary/204 topic list}}

[[Category: Dictionary/204]]