Laderman Associates - ADSO Migration Utility User's Guide

     LADAMU05       Extract components from the source IDD
     LADAMU07       Produce the Imbedded Dialog Report
     LADAMU10       Determine migration status
     LADAMU11       Produce the Replacement Prerequisite Report
     LADAMU12       Analyze replacement impact
     LADAMU15       Create CA-IDMS compiler syntax
     LADAMU17       Modify CA-IDMS compiler syntax
     LADAMU19       Propagate migration status for LADAMU20
     LADAMU20       Produce the Component Listing by Dialog
     LADAMU25       Produce the Component Cross-Reference by Entity
     LADAMU30       Migrate User passwords
     LADAMU35       User template facility
     LADAMU40       Merge files  (DOS only)
     LADAMU50       Check for null input  (OS only)

All programs are written in COBOL and may be treated as standard batch application programs. LADAMU05 and LADAMU10 are both retrieval run units, using IDMSNWKA, and may be executed in local mode or through the central version. LADAMU30, which is an optional facility, will directly update the USER-047 record in the object IDD and should be executed through the central version. The remainder of the programs are non-IDMS.

System Flow

For the purposes of this manual, we will call the dictionary from which entities are being migrated the source IDD, and the dictionary to which entities are being migrated the object IDD. The ADSO Migration Utility is executed in five Phases, as follows:

Phase I (LADAMU05), based upon user-supplied selection criteria, reads the source IDD and extracts a file containing information about all component entities. LADAMU07 (optional) will inform you of any called dialogs/programs which you may have accidentally omitted from your selection criteria.

Phase II (LADAMU10), using the extracted file, reads the object IDD and determines the migration status of each component entity. It also performs a complete impact analysis regarding the replacement of modified entities (LADAMU11, LADAMU12).

Phase III (LADAMU15) creates the appropriate CA-IDMS compiler syntax to migrate new or modified entities; entities which are identical on the two dictionaries are not migrated.

Phase IV uses IDMSDDDL, IDMSUBSC, and RHDCMPUT to extract definitions from the source IDD. If you have chosen to change entity versions or subschema names during migration, LADAMU17 will modify the extracted definitions in the appropriate manner.

Phase V uses IDMSDDDL, IDMSUBSC, RHDCMAP1, RHDCMPUT, and ADSOBCOM (or ADSOBGEN) to update the object IDD.

LADAMU30 (optional) may be used to migrate the passwords of any USERs migrated in Phase V. This function is not performed by IDMSDDDL.

LADAMU35 may be used to create DCMT VARY NEW COPY syntax for a UCFBATCH execution, as this function is not performed by any of the batch CA-IDMS compilers. This program may also address a variety of other requirements, and should not be overlooked.

LADAMU20 and LADAMU25 may be executed, if desired, at any time after the completion of Phase I.

Operational Notes

Executing in Local Mode

It is recommended that the AMU be executed in local mode to achieve optimal performance.

If you are executing against a secondary dictionary, then ensure that the load library you have specified contains the appropriate database name table. This standardly resides in the DDLDCLOD area, but must be punched and linked to a load library for local mode execution.

Return Codes

Return codes are standardly issued at the termination of each program. In DOS environments, they are displayed on the console. In OS environments, they may be used to halt execution if certain conditions have been found. In general, the following severity levels are used:

04 indicates that a warning message has been issued.
08 indicates that a condition which may be critical has been encountered.
12 indicates that a critical error has been encountered.
16 indicates that a fatal error has been encountered.

The return codes for each Phase are described in the appropriate chapter.

Abnormal Termination

For most fatal errors, the AMU program will call ABORT to abort the program. Prior to aborting, the program will print an error message at the end of its listing indicating the cause. For DOS environments, this CSECT is not supplied with the AMU, but you may link the AMU programs with IDMSCANC which does include this CSECT. If you do not, the program will abort anyway, with a PROGRAM NOT FOUND message. See the DOS Installation section for more details.

Operational Responsibilities

The following suggested procedures may or may not be suitable for your environment, and should only be implemented if they seem appropriate.

Test to Production Migrations

The application project team executes Phases I & II, assuming the responsibility for the selection of entities to be migrated. The listings produced by LADAMU05, LADAMU10, and LADAMU12 are used as the production turnover documents. The group responsible for updates to the object IDD (DBA staff, production control, or whoever) then assumes responsibility for completing the migration. If migrations from multiple teams are scheduled within the same time frame, it would be wise to restart at Phase I, combining the input from all sources, in order to eliminate possible duplicate updates of shared entities. If only one migration is scheduled, the update group could simply continue the migration, starting at Phase III. In this case, be aware that any changes made in the source or object IDD after the completion of Phase II might have an impact upon Phases IV or V. For example, if, after Phase I, a new response process is added to a dialog which has been selected by the AMU, the process is not known to the AMU and is not migrated, and the dialog generation will fail.

Test to Test Migrations

If you are migrating between primary and/or secondary test dictionaries, the procedure outlined above could be followed, or programmers could actually execute the AMU from start to finish.

Other Ideas

You may want to combine several Phases into one jobstream. Assuming you are executing in local mode and all disk files are available on a single machine (because you only have one CPU or you have shared DASD), you may wish to combine Phases I & II, I II & III, or I through IV into a single job. In OS environments, condition codes may be used to halt execution at any point. OS users may wish to create a TSO/ISPF (or other interactive) front-end for the AMU. If you currently have such a facility for other IDMS functions (e.g. compiles, IDMSDDDL, etc.), execution of the AMU could be specified as another menu function.

Performance Considerations

Optimizing Performance

To optimize performance of Phases I (LADAMU05) and II (LADAMU10), execute in local mode

You may receive further benefits by specifying the following options in Phase I:

OPTIONS=DUPS=DROP if you do not intend to run LADAMU20 or LADAMU25
OPTIONS=DBRECS=BYP if you do not intend to run LADAMU20 or LADAMU25 and you do not wish to migrate any schema records
OPTIONS=DIRL=BYP if IDMSDIRL has been executed against the object IDD.

To optimize the performance of Phase IV, execute in local mode.

To optimize the performance of Phase V, specify:

OPTIONS=UPDREADY=PROTECTED (in Phase III) if you can afford to lock out other object IDD updates during the execution of Phase V

For an extremely large migration, you might consider backing up the object IDD, prior to Phase V, and executing in local mode. The major drawback to this procedure is that, in the event of an abend, there is no automatic rollback, so you must restore the dictionary and restart from the beginning of Phase V.

File Descriptions

The intent of this section is to provide a description of the key fields in the various sequential files employed by the AMU. This information may be used to:

Add your own reporting capabilities
Drop entities from the extract file to limit the scope of the reports produced by LADAMU20 and LADAMU25
Assist in the diagnosis of any problems

Both the EXTRACT and REPLACE files contain fields which are described as entity code. The definitions of those fields are as follows:

     Figure 1. Definition of Entity Codes

050 - source IDD definition   	260 - Module
051 - object IDD definition   	270 - Panel
110 - ADSA application          280 - Program
120 - Attribute  	        300 - Record
140 - Class  	                320 - Schema
160 - Dialog   	                340 – Subschema
170 - Edit module  	        380 - Table
180 - Element  	                400 - User
200 - File   	                420 - User defined comment
220 - Map  	                440 - User defined nest
240 - Message

Extract File

The EXTRACT file (record length = 250) is the hub of the AMU. It is created, updated, or read by almost every program. Its key fields are:

     Figure 2. Layout of EXTRACT file

Start	  Length	Type	     Description
1	    3	          N	     Entity Code
4	   40	         AN	     Entity Name
44	    4	          N	     New version of entity
48	    4	          N	     Existing version of entity
99	    8	         AN	     Date last updated
107         8            AN          Time last updated
115	    1	         AN	     Migration status, M = yes, N = no, R = review
			                               L = replace, E = error
116	    1	         AN	     Duplicate occurrence indicator
				      D= this is a duplicate
175	   14	         AN	     Load last updated
193	    8	         AN	     Prog last updated


Note: These descriptions are not valid for 050 and 051 entity codes.

Imbed File

The IMBED file (record length = 50) contains one record for each occurrence of a called dialog/program (i.e. a dialog or program called from a dialog via an inter-dialog control command such as LINK, INVOKE, or TRANSFER). Its key fields are:

     Figure 3. Layout of IMBED file

Start	  Length	Type	     Description
 1	1	         AN	     D = dialog, P = program
 2	8	         AN	     Dialog/program name
10      8	         AN	     Inter-dialog control command
18     32	         AN	     Calling module name

Replace File

When any entity is assigned the migration status of review in LADAMU10, one record is written to the REPLACE file for each prerequisite entity which would be affected by its replacement. LADAMU12 matches the REPLACE file with the EXTRACT file to determine if all prerequisites have been included in the migration. The key fields of the REPLACE file (record length = 90) are:

     Figure 4. Layout of REPLACE file

Start	  Length	Type	     Description
1	        3         N	     Prerequisite entity code
4	       40        AN	     Prerequisite entity name
44	        4    	  N	     Prerequisite entity version
48	        3         N	     Review entity code
51	       32      	 AN	     Review entity name
83	        4         N	     Review entity version

The review entity code, name & version may be the entity which has been assigned the migration status of review, or may be an intermediate entity. For example, if an element is assigned the status of review, owning records, maps, and programs are considered to be prerequisites. In actuality, records are the only prerequisites for elements; maps and programs are prerequisites for records. So, in this case, the REPLACE file would contain prerequisite records for review elements, and prerequisite maps and programs for review records (which were the prerequisite records for review elements).

Sequential File Flow

     Figure 5: Sequential File Flow

FILE NAME	       CREATED BY 	     READ BY
sorted05 	         Phase I             Phase II
extract10                Phase II 	     Phase III
sorted10 	         Phase III 	     Phase IV
		                             LADAMU20
		                             LADAMU25
	                                     LADAMU30
		                             LADAMU35
ph4dddl1 	         Phase III 	     Phase IV
ph4dddl2 	         Phase III 	     Phase IV
ph4ubsc 	         Phase III 	     Phase IV
ph4mput 	         Phase III           Phase IV 
		                             Phase V
ph5dddl1 	         Phase III 	     Phase V
ph5dddl2 	         Phase IV 	     Phase V
ph5dddl3 	         Phase III 	     Phase V
ph5dddl5 	         Phase III 	     Phase V
ph5dddl6 	         Phase IV 	     Phase V
ph5ubsc1 	         Phase III 	     Phase V
ph5ubsc2 	         Phase IV 	     Phase V
ph5ubsc3 	         Phase III 	     Phase V
ph5map1a 	         Phase III 	     Phase V
ph5map1b 	         Phase IV 	     Phase V
ph5map1d 	         Phase III 	     Phase V
ph5mput 	         Phase III 	     Phase V
ph5bgen 	         Phase III 	     Phase V
ph4sysi	                 Phase III	     Phase IV
ph5sysi	                 Phase III	     Phase V

This figure shows the usage of sequential files between Phases of the AMU; files which are not passed are not shown. Many of these files may also be read and/or updated within the same Phase which creates them.