Performing the upgrade

Subject:

A guide for Technical Consultants working on the upgrade project

From:

Global Solution Center

To:

Global Solution Center - Technical Project Manager

Global Solution Center - Technical Consultant

Abstract

Written by Lee Flaherty

Date 2008-04-15
Version v1.1
Status Released
Approved by
Date
File 38972699.doc
Performing the upgrade
Introduction

Table of Contents
Table of Contents...................................................................................................................2

Introduction.............................................................................................................................3

Conversion Technique............................................................................................................3

Getting started........................................................................................................................3
Split all objects into batches.........................................................................................3
Make a list of modifications that are, or are not, being upgraded.................................4
Create a forum for Technical Consultants to share information on critical changes.....5
Redesign M3 Screens if Usability improvements have been ordered..........................5

Upgrading the different M3 object types.................................................................................6

Database interfaces (mvx.db.def + mvx.db.dta)...........................................................6
5.1 Extended fields in 7.1.....................................................................................6
5.2.1 Add suffix field.............................................................................................6
Data structures (mvx.app.ds).......................................................................................6
View definitions (mvx.dsp.obj + .xml object).................................................................7
Output interfaces (mvx.out.obj)....................................................................................9
Parameter lists (mvx.app.plist)...................................................................................11
Utilities (mvx.app.util).................................................................................................11
Programs (mvx.app.pgm)...........................................................................................12
MI (M3 Interface) Programs (mvx.app.pgm.xxxnnnMI)..............................................12
MRS001 (API metadata)....................................................................................12
Change of MI programming standard for 7.1......................................................12
Field help (.xml object)...............................................................................................13
Language files (.lng files + database tables)..............................................................13

Prepare database migration routine.....................................................................................13

Disable the 5.2 service pack.................................................................................................14

Additional notes on preparing the delivery............................................................................15

Demo 1: Upgrading a view definition....................................................................................16

Appendix 1: Example data conversion program – Split RIDL into RIDL and RIDX...............20

Page 2 of 23 Copyright © Lawson

 Performing the upgrade
Upgrading the different M3 object types

Introduction
This document is a guide for a Lead Technical Consultant and their team in performing the
upgrade.
It includes the basic steps and guidelines on how to work through the different object types.
Some knowledge is assumed.

Conversion Technique
It is more efficient to upgrade all objects of the same type, before moving onto the next. The
database is upgraded first; programs are upgraded after everything else.
Alternatives like upgrading by customization and delivering in batches should be avoided.
This causes delays as Technical Consultants exchange locks and ignore blocks of code that
don’t belong to their customization.
Assuming the project has been positioned correctly there will be an agreement to upgrade
everything that is needed, ignore anything that isn’t and deliver it all at the same time.

Getting started
If you have followed the steps in “Creating a Customization Upgrade environment” you will
now have the languages, and converted views installed.
Languages components should require no further changes.
Compilation dependencies require most object types to be created in a specific order. If you
work through the list of objects in this order you shouldn’t hit too many dependency issues.
1. Database interfaces (mvx.db.def + mvx.db.dta)
2. Data structures (mvx.app.ds)
3. View definitions (mvx.dsp.obj + .xml object)
4. Output interfaces (mvx.out.obj)
5. Parameter Lists (mvx.app.plist)
6. Utilities (mvx.app.util)
7. Programs (mvx.app.pgm)
The dependency on Field help is only at runtime. These can be upgraded anytime in the
process.

Split all objects into batches

Start by making a list of objects, by type, in the service pack delivery. This is your task list
for the upgrade. Objects can be allocated to Technical Consultants in batches.

TIP: Where possible, try to split batches of objects by the

program prefix/functional area (For example all MMSnnn,
ZMMnnn, MMZnnn programs).

Technical Consultants are more effective if they are upgrading

the same modification, or batch of modifications. Grouping by
functional area increases the probability of this.

Copyright © Lawson Page 3 of 23

Performing the upgrade
Upgrading the different M3 object types

Make a list of modifications that are, or are not, being

upgraded
You should be provided with a list of customizations that are, or aren’t going to be upgraded.
Provide this to your team. If they are upgrading an object and all customizations within it
are not on the upgrade list The Technical consultant can make a note, and move onto the
next object.
The M3 Customization Analysis tool permits you to export the contents of the service pack
so that each object to upgrade is a task in Jira.

Contact Anders J Carlsson who can import these into a new Jira project for your customer.
This creates an effective task list. You can manage this by mass changing issues to
allocate them to your developers.
It also provides you with a progress bar and an indication of workload by assignee.
 Performing the upgrade
Upgrading the different M3 object types

Create a forum for Technical Consultants to share

information on critical changes
The following could be done with a spreadsheet, text document or Jira database entry.
Allow additional lists to be created and maintained by all Technical Consultants to track
important changes that everyone needs to be aware of and cross-check. For example:
1. Databases altered during upgrade
a. E.g. new extension fields like RIDX
b. To be used when changing any object that uses the table
c. Can be used to create the custom database migration kit (see Prepare
database migration routine)
2. Out definitions altered during upgrade
a. E.g. new extension fields like RIDX
b. To be used when upgrading the connected program
c. This is a good resource for the projects MOS (Stream serve) Technical
Consultant as they will need to alter the Stream serve document layout to
match the updated out interface
3. Custom view definitions altered during upgrade
a. E.g. new extension fields like RIDX
b. To be used when upgrading the connected program
c. Not needed if you can ensure the Technical Consultant who upgrades
the view, also upgrades the program

Redesign M3 Screens if Usability improvements have

been ordered
Lawson Product Development implemented a series of usability enhancements to most
standard views.
This is a manual task so should be undertaken as a modification in addition to the upgrade.
It is not part of the standard upgrade path.
Use the Usability Improvements Design Guideline when redesigning the view.

Copyright © Lawson Page 5 of 23

Performing the upgrade
Upgrading the different M3 object types

Upgrading the different M3 object types

Database interfaces (mvx.db.def + mvx.db.dta)
In most cases you can get a table, build and deploy it.
Shadow/modified files should remain the same, unless the primary key on a linked standard
table or a known field type has changed.
It is likely you will identify changed standard fields when compiling the programs when you
do please revisit the table.
MAK could enforce a new customization guideline, if so change the table
If you change a table, don’t just build and deploy. Advise the Technical Lead on the project.
It is possible a custom migration routine will be required.
There are some important changes highlighted in the “M3 BE 13.1 Programming Standard
Net Change” document. See below for where changes will be required. The number refers
to the section number in the net change document.

5.1 Extended fields in 7.1

The following fields: AFPO, ATPO, DINR, JDCD, NUGL, PONR, RELI are changed from
3.0 to 5.0. If any of the fields above are used, search the program according to the example
below for each field:
• Search Replace with
'PONR, 3' 'PONR, 5'

5.2.1 Add suffix field

Check the following fields: RIDL, RORL, ARDL and DRDL and add a suffix field according to
below:
• If Field Add Field
RIDL RIDX
RORL RORX
ARDL ARDX
DRDL DRDX
When a suffix field is added to a custom table a data migration routine will be required.
See “Appendix 1: Example data conversion program – Split RIDL into RIDL and RIDX” for a
sample program from the M3 standard conversion kit.
This needs to be documented and delivered in the “Prepare database migration routine”
step. Once written, unit test the fix program and provide details to the technical lead.

Data structures (mvx.app.ds)

These are similar to the table changes.
Custom data structures require little additional effort which is why they are preferred.
If they use one of the changed database fields a change will be required (see 5.1 Extended
fields in 7.1 and 5.2.1 Add suffix field).
If a change isn’t required get, build and deploy.
Changes to standard data structures will have to be merged into the latest version.
If you change a data structure, don’t just build and deploy. Advise the Technical Lead on the
project. It is possible a custom migration routine will be required.
 Performing the upgrade
Upgrading the different M3 object types

If all of the statements below are true, a migration routine will have to be written,
documented and delivered to the customer project.
1. A standard data structure has been modified
2. An additional standard field has been added
3. The data structure is used for persistent data (E.g. placed on CSYTAB, CSYPAR or
CSYSTP)
The fix programs usually take the format of a Java program to manipulate the relevant
database values. See S12500017 as an example! It is likely that your function will have to
work with the parameter (E.g. CTPARM) as a substring moving the old custom data after the
new standard data.
This fix program should also stamp the record as upgraded in case it is executed a second
or third time. This could be done by setting the last character on the long field to '1'. It
should be safe to run all fix programs multiple times without corrupting the database.
For changed standard data structures which do not represent persistent data. That is, are
used as parameter list in programs, or only used at runtime. It is only necessary to add the
modified fields to the end.

View definitions (mvx.dsp.obj + .xml object)

7.1 uses the XML files as source, 5.2 uses MVX files as source and generates the XML.
However the old 5.2 XML file is not compatible with 7.1.
There is a view definition parser available, this will have been run.
If a custom view uses one of the changed database fields a change will be required (see 5.1
Extended fields in 7.1 and 5.2.1 Add suffix field).
If a change isn’t required get, build and deploy.
For changes to a standard view take a copy of the custom 5.2 version and a copy of the
new 7.1 standard version. You will need to overwrite the old 5.2 version, with the new 7.1
standard version and use this as a base.
Changes to standard views need to be re-keyed in the screen design tool. There are some
generated values like tab sequence and record format length that will cause problems if you
try and use a Beyond Compare/WinMerge tool.
To identify the customer modifications in the 5.2 View Definition there is a tool to summarize
the view definition history log.
Check out the 5.2 version of the view definition in MAK to use with this tool
You need to set up the tool to run as an “External Tool” in the MAK 5.2 environment.

Copyright © Lawson Page 7 of 23

Performing the upgrade
Upgrading the different M3 object types

Create a “ViewDef Actions” option.

• Location
o Solution Center L:\SC\Tools\ViewDefActions\ViewDefActionAnalyzer.cmd

o Onsite C:\Program Files\Lawson\M3 SteppingUp Developers

Kit\ViewDefActionAnalyzer.cmd

• Arguments ${resource_loc}

To run the tool

1. Highlight the view definition .xml file in the Java perspective
2. Select “Run/External Tools/ViewDef Actions”
 Performing the upgrade
Upgrading the different M3 object types

This will generate a modification summary in the console window. There are in fact two
summaries; the first is by Panel, Component and Action number.

The second is by Action number, Panel and Component.

These summaries give you a list changes that need to be re-applied to the new standard
view to re-create the customization.
The upgrade process is not intuitive. See Demo 1: Upgrading a view definition for an
example of how to do this.

Upgrading changes to standard views is a complicated task that

requires care and skill.

Output interfaces (mvx.out.obj)

Custom output interfaces may not need to change
If they use one of the changed database fields a change will be required (see 5.1 Extended
fields in 7.1 and 5.2.1 Add suffix field).
If a change isn’t required get, build and deploy.
For changes to a standard output definition take a copy of the custom 5.2 version and a
copy of the new 7.1 standard version. You will need to overwrite the old 5.2 version, with
the new 7.1 standard version and use this as a base.

Copyright © Lawson Page 9 of 23

Performing the upgrade
Upgrading the different M3 object types

Differences can be merged, however it may be necessary to manually re-sequence the

appearance order of the record formats in the old 5.2 version of the Output interface.
Unlike View definitions there is no action history so refer to a copy of the standard 5.2 view
in another workspace if you are not sure that a changes is part of a customization or part of
the upgrade (E.g. changed length, indicators etc…).
There is an Output Definition compare tool available to compare two out
interface XML files and report the differences.
Check the customized 5.2 version and the standard 7.1 version into your
workspace to compare the old and new versions.
Browse for, and select the two MAK generated XML Files and press Compare to report the
differences.

The report will appear in the console window.

To upgrade to 7.1 from a previous version, for example 5.2:

1. Work through the above report. Use the Out Interface Editor in MAK to view the
fields and record formats in the old 5.2 modified version.
2. For each added, changed or removed field/format make the appropriate change to a
copy of the standard 7.1 version in MAK
 Performing the upgrade
Upgrading the different M3 object types

3. Deploy the customized 7.1 version as the new customized version

This is a similar procedure to the View Delimitation upgrade process.
This process only compares the customized version to the latest version of standard. It
does not show you which changes are standard ones and which relate to the customization.
A three way compare is necessary for this.
Here is a guide on how to read and apply the changes:
• If a field is missing from the original customized version or the new standard version
add it into the new customized version.
This may generate some unmanaged event exceptions in stream serve but the
project should be anticipating these.
• If field length has changed, take the longest length from either version (new
standard or old customized)
This ensures we do not lose precision in the data stream. For right adjusted fields it
can mean the data streams may not handle the full length of the amended fields,
however the project should be anticipating changes like these.
• If a field/record format has had some attributes changed (E.g. INxx or type change)
use the customized version attributes.
Without a 3 way compare it is difficult to determine if it is a required change in
standard or a customization. It is safer to assume it is a customization.

Identifying the modified components in standard output

interfaces; and applying these to the new version takes longer
than the original customization.

Upgrading changes to standard output interfaces is a

complicated task that requires care and skill. It is hoped this can
be improved in future.

Parameter lists (mvx.app.plist)

Custom parameter lists may not need to change
If they use one of the changed database fields a change will be required (see 5.1 Extended
fields in 7.1 and 5.2.1 Add suffix field).
If a change isn’t required get, build and deploy.
For changes to standard parameter lists get a copy of the modified 5.2 version and a copy
of the new 7.1 standard version. Use the Eclipse Compare with > Each other to merge all
the standard changes into the modified version.
Parameter lists don’t use inheritance, be sure to duplicate the entire standard 7.1 object.

Utilities (mvx.app.util)
Custom parameter lists may not need to change
If they use one of the changed database fields a change will be required (see 5.1 Extended
fields in 7.1 and 5.2.1 Add suffix field).
If a change isn’t required get, build and deploy.
For changes to standard utilities get a copy of the modified 5.2 version and a copy of the
new 7.1 standard version. Use the Eclipse Compare with > Each other to merge all the
standard changes into the modified version.

Copyright © Lawson Page 11 of 23

Performing the upgrade
Upgrading the different M3 object types

Utilities don’t use inheritance, be sure to duplicate the entire standard 7.1 object.

Programs (mvx.app.pgm)
A 5.2 to 7.1 program parser is available to simplify the coding changes.
However this is not an automated process.
There are a significant number of changes to the code base between 5.2
and 7.1.
The 5.2 to 7.1 program parser and all related documentation is available
as a shortcut on the development servers.
The program parser is also available for download from the wire as part of the M3
SteppingUp Developer Kit.

MI (M3 Interface) Programs (mvx.app.pgm.xxxnnnMI)

MRS001 (API metadata)
The MRS001 metadata for MI programs installed in the development environment is the 7.1
standard API metadata.
For changed standard programs, use the marked changes in the customized 5.2 program to
determine the new/changed transactions and fields and re-enter these manually in MRS001.
For custom programs (E.g. MMZ701MI) the old metadata should have been exported and
can be re-imported into the new MI programs.

Change of MI programming standard for 7.1

The MI programming standard has been rewritten in 7.1. The standard MI programs have
also been rewritten.
The 5.2 MI programming standard is supported! If you are upgrading a custom MI program
perform the parser changes and deliver the upgraded function. There is no need to rewrite
custom MI programs.
If the customization is a change to a standard MI program, re-write the customization in the
new MI program.
Refer to the new MI programming standard documentation in the MI Technical Consultant’s
kit for more details on the differences between 5.2 and 7.1.
 Performing the upgrade
Upgrading the different M3 object types

The attached code generator also includes a new option for generating the externally
defined data structures (instead of the internally defined MvxStruct objects).

Field help (.xml object)

Former 5.2US projects only need to check out and redeploy field help. The 7.1 help text
format was introduced in 5.2US.
Changes to standard field help when upgrading from a version which is 5.2 or older need to
be re-keyed in MAK.
1. Open the 5.2 field help manually by navigating to the help location on the 7.1
Workplace server. Double click to open it.
E.g. \\10.20.17.244\qibm\M3BE_MNEFileRootPath_71\Help\GB\FieldHelp\xml\CUS
2. Copy the header and content of the help to a temporary document (e.g. notepad).
3. Delete the field help manually from the 7.1 Workplace server
4. Re-create the field help in MAK

Language files (.lng files + database tables)

No changes required. The modified language components will be copied across, the
standard ones will be upgraded.
There is a risk that some standard messages used by the customizations may have been
removed between versions.
These will be identified during testing and logged as issues or a single issue in the
StepWise Project Database.
If a standard language component from 5.2 is no longer available in 7.2 key the old 5.2
message into the customer language file and substitute this in the view definition or
program.

Prepare database migration routine

Changes to the database should have been noted throughout the upgrade project,

Copyright © Lawson Page 13 of 23

Performing the upgrade
Upgrading the different M3 object types

The standard JCpyDta tool can be used by the project SE to copy records from the old
customer database to the new one. Document this and deliver it to the project.
The JCpyDta tool will only copy values where the table name + field name + field type
match. It will set new values to 0 or blank depending on type.
If the name or type of a field has changed, create a custom SQL script that will move data
from one schema to another. Document this and deliver it to the project.
If fix routines have been written, document how to run them, it is also worth noting potential
side effects if they are not executed.
Refer to “Custom database migration instructions.doc” in for a sample migration document.

Disable the 5.2 service pack

The customizations should not be tested with the legacy 5.2 customizations still in place.
This will cause a false test result if an upgraded program still uses an object that was not
upgraded.
The 5.2 service pack should now be disabled. Remove the service pack references in
MNS104
A restart of the server will be required following this.

Remove Service
pack and service
pack View path

After the service pack is disabled it will no longer be possible to

access 5.2 objects that have not been redeployed in MAK.

To create a 5.2 object in 7.1 after the service pack is removed

copy the source manually to the HFix location on the server. This
will make the object available.
 Performing the upgrade
Upgrading the different M3 object types

Additional notes on preparing the delivery

• If MI programs have been modified, a full extract of the API metadata (all CMIxxx
tables) is a required in the delivery. This can be done with JCpyDta.
• Ensure a full extract of the language tables is prepared. MAK will only pack what
has changed which isn’t enough to create a fresh installation.

Copyright © Lawson Page 15 of 23

Performing the upgrade
Upgrading the different M3 object types

Demo 1: Upgrading a view definition

Get a copy of the modified 5.1 view from the old service pack.

Go to the java perspective, select the View Definition source and run the ViewDef Actions
tool.
 Performing the upgrade
Upgrading the different M3 object types

The console produces 2 lists one by panel, component and action…

… One by action, panel and component

In this case we can see one modification (P003). It affects W0SEAH on the F0 panel.
Now we get the 7.1 standard version of the view.

Copyright © Lawson Page 17 of 23

Performing the upgrade
Upgrading the different M3 object types

Open the old 5.2 version (for read only).

In the Java perspective, copy the standard 7.1 view...

 Performing the upgrade
Upgrading the different M3 object types

...and overwrite the 5.2 version (leaving the old 5.2 copy open for reference)

Now open the overwritten view in the MAK perspective. You have two view definitions
open.
In the foreground is the modified 5.2 version. In the background is the standard 7.1 version.

You may now use the checklist shown earlier to review the listed components, identify the
modifications and apply these to the new standard 7.1 version of the view.
This has to be done by comparing the component properties in the standard 7.1 view to the
modified 5.2 view.

Copyright © Lawson Page 19 of 23

Performing the upgrade
Upgrading the different M3 object types

In the example below WOSEAH had a new value (7) added to the drop down list.

Notice how the Upgrade took longer than the original

modification.

Appendix 1: Example data conversion

program – Split RIDL into RIDL and RIDX
package mvx.app.pgm;

import mvx.app.common.*;
import mvx.runtime.*;
import mvx.db.dta.*;
import mvx.app.util.*;
import mvx.app.plist.*;
import mvx.app.ds.*;
import mvx.util.*;
import mvx.util.KQLOG;
/**
*<BR><B><FONT SIZE=+2>Fix: Split RIDL into RIDL and RIDX </FONT></B><BR>
* <BR>
*
*<B>(c) 2007 Lawson Software. All rights reserved </B>
*<B>Licensed material property of Lawson Software</B><BR><BR>
*
*<PRE>
*<B>Use of indicator 61 - 89</B>
 Performing the upgrade
Upgrading the different M3 object types

*<B>Indicator</B>
*
*</PRE>
*<PRE>
*<B>Modification area - Customer
*Nbr Date Usid Description</B>
*
*99999 999999 XXXXXXXXXX x
*
*RIDL0 061004 LAGCAR0 RIDL_conversion
*OL100 061026 LAGCAR0 Order_line_Extension_Batch_1
*
*</PRE>
*/

public class S13000001 extends Batch

{
public void movexMain() {
INIT();
// Select a view that doesn't contain RIDL in the key
// Convert to POSX first
ITTRA.SETLL("00");
while (ITTRA.READ("00")) {
newRIDX = RIDLConversion.getPOSX(ITTRA.getRIDL(), ITTRA.getTTYP());
newRIDL = RIDLConversion.getPONR(ITTRA.getRIDL(), ITTRA.getTTYP());
newRORX = RIDLConversion.getPOSX(ITTRA.getRORL(), ITTRA.getRORC());
newRORL = RIDLConversion.getPONR(ITTRA.getRORL(), ITTRA.getRORC());
if (newRIDL != ITTRA.getRIDL() || newRORL != ITTRA.getRORL()) {
if (ITTRA.CHAIN_LOCK("00", ITTRA.getKey("00"))) {
ITTRA.setRIDL(newRIDL);
ITTRA.setRIDX(newRIDX);
ITTRA.setRORL(newRORL);
ITTRA.setRORX(newRORX);
ITTRA.UPDAT("00");
}
}
}
SETLR();
return;
}

/**
* INIT - Init subroutine
*/

Copyright © Lawson Page 21 of 23

Performing the upgrade
Upgrading the different M3 object types

public void INIT() {

}

public int newRIDL;

public int newRIDX;
public int newRORL;
public int newRORX;
// Movex MDB definitions
public mvx.db.dta.MITTRA ITTRA;
// Movex MDB definitions end

public void initMDB() {

ITTRA = (mvx.db.dta.MITTRA)getMDB("MITTRA", ITTRA);
ITTRA.setAccessProfile("00", 'U');
}

public cRIDLConversion RIDLConversion = new cRIDLConversion(this);

public String getVarList(java.util.Vector v) {

super.getVarList(v);
return version;
}

public void clearInstance() {

super.clearInstance();
newRIDL = 0;
newRIDX = 0;
newRORL = 0;
newRORX = 0;
}

/**
*
*/
public String getVer() {
return version;
}

public final String version = "Pgm.Name: S12415003, " + "Source creation date: Tue
Dec 14 11:00:00 CET 2004, " + "ID number: ?";

public String getVersion() {

return _version;
}
 Performing the upgrade
Upgrading the different M3 object types

public String getRelease() {

return _release;
}

public String getSpLevel() {

return _spLevel;
}

public String getSpNumber() {

return _spNumber;
}

public final static String _version = "13";

public final static String _release = "0";
public final static String _spLevel = "0";
public final static String _spNumber = "*NONE";
public final static String _GUID = "81E090BBEF6B4f00B5E4DD9132A83BD6";
public final static String _tempFixComment = "";
public final static String _build = "0";
public final static String _pgmName = "S13000001";

public String getGUID() {

return _GUID;
}

public String getTempFixComment() {

return _tempFixComment;
}

public String getVersionInformation() {

return _version + '.' + _release + '.' + _spLevel + ':' + _spNumber;
}

public String getBuild() {

return (_version + _release + _build + " " + _pgmName + "
").substring(0, 34);
}

public String[][] getStandardModification() {

return _standardModifications;
}

public final static String[][] _standardModifications = {};

}

Copyright © Lawson Page 23 of 23