ARCAD 11.0.x Upgrade Guide · NorthAmerica&LATAM EMEA(HQ) AsiaPacific 70MainStreet,Suite203...

North America & LATAM EMEA (HQ) Asia Pacific70 Main Street, Suite 203Peterborough NH 03458USA1-603-371-90741-800-676-4709 (toll free)[email protected]

55 Rue Adrastée – Parc Altaïs74650 Chavanod/AnnecyFrance

+33 450 578 [email protected]

c/o Pramex Intl Ltd1 Austin Rd West Intl Commerce Centre7107B 71/F Tsim Sha Tsui HONG KONGYau Ma Tei Hong Kong

[email protected]

Publication Date: July, 2019

Prepared by the ARCAD Documentation Team

Upgrade GuideARCAD

Version 11.0.x

ARCAD v11.0.xUpgrade Guide |

Copyright © 1992-2019 by ARCAD. All rights reserved.

The following terms are names owned by International Business Machines Corporation in the United States,other countries, or both: AS/400®, ClearCase, ClearQuest®, DB2, DB2 Connect™, DB2 Universal Database™,ibm.com, IBM i, iSeries, System i, OS/400, Rational®, SP2, Service Pack, WebSphere. Java and all names basedon Java are owned by Oracle Corp. in the United States, other countries, or both. Eclipse is a registeredtrademark of Eclipse Foundation, Inc. Other names of companies, products or services are the property of theirrespective owners.

/ 27ARCAD • Copyright © 2019 • All Rights reserved. • arcadsoftware.com

http://www.arcadsoftware.com/

ARCAD v11.0.xContact ARCAD | Upgrade Guide

Contact ARCAD

Headquartered in France at the foot of the Alps, ARCAD offers global services and has offices andpartners all over the world. ARCAD partners with leading-edge companies throughout the world tooffer full services, close to home.

Visit our website to Contact Us and find out more about our company and partners, or to request ademo.

The Customer Portal is intended for current and potential customers that have full or trial versions ofARCAD software. If you already use or are interested in using an ARCAD product, the portal lets youview all of your current licenses and generate your own temporary license keys for most ARCADproducts. It grants you access to the ARCAD product knowledge base (FAQ, new releases, fixes, etc.) aswell as the Release Notes and current documentation.

Do you have a request for change or have you encountered a bug? Log into the Helpdesk and create aticket.

ARCAD guarantees consultant support 24 hours a day, 5 days a week (24/5) to registered members.Calls received are redirected, according to the hour, to put you in contact with a support team in or nearyour timezone.

Country Address Account Contact Support Contact

FranceARCAD Software (HQ)55 Rue Adrastée74650 Chavanod

+33 4 50 57 83 96

[email protected] support-

[email protected]

ARCAD Software Deutschland GmbHc/o Pramex International GmbHIm Trutz, Frankfurt 55 60322

USAARCAD Software Inc.70 Main Street, Suite 203Peterborough, NH 03458

+1 (603) 371-9074+1 (800) 676-4709

[email protected]

[email protected]

HongKong

ARCAD Software Asiac/o Pramex Intl Ltd1 Austin Rd West Intl CommerceCentre7107B 71/F KowloonHong Kong

+852 3618 6118

[email protected]

China

ARCAD Software Products PrivateLmtdRoom D07, floor 34, No.32, ZhujiangEast RoadTianhe District, Guangzhou

+86 (020)22324643+86 (020)22324649

[email protected]

IndiaARCAD SoftwareD-280/281/282, Vibhuti KhandGomti Nagar, Lucknow

Table 1: Contact ARCAD


https://arcadsoftware.com/about/contact/

https://arcadsoftware.com/customer/

https://helpdesk.arcadsoftware.com/customer/customer?startup=generic

mailto:[email protected]













ARCAD v11.0.xUpgrade Guide | Contents

Contents

Contact ARCAD 3

Contents 4

Preface 5

1 General update tips and procedures 61.1 Preparation 61.2 Update the ARCAD Server 61.3 Update RCP clients and RDi plug-ins 61.4 Test 71.5 Roll back an update 7

2 Upgrade from v10.x to v11.0.7 8

3 Upgrade from v8 to v10 93.1 Installation 93.2 Understanding ARCAD ≥v10 audit results 123.3 Migrating licenses from v8 to ≥v10 133.4 Datamigration 133.4.1 Clear old and temp data 13

3.4.2 Run the DB migration 14

3.5 Macro conversion 143.5.1 Conversion 15

3.5.2 Macros with SQL 17

3.5.3 Macros with call commands 18

3.6 Customized programs 193.6.1 Types of customizations 19

3.6.2 Unicode conversion 19

3.6.2.1 Preparation 20

3.7 Testing and avoiding conflicts 213.7.1 Version library 21

3.7.2 ARRPLOBJ naming conflict 21

3.7.3 Distribution 22

3.8 Final ≥v10 update 233.8.1 Preparation 23

3.8.2 Process 23

3.8.3 Post update 24

4 Upgrade from v8 to v9 264.1 Test the databasemigration from v8 to v9 264.2 Pre-check before the livemigration 264.3 Livemigration 26



ARCAD v11.0.xPreface | Upgrade Guide

Preface

Document purposeThis guide covers the particularities you may encounter when updating the ARCAD Server andARCAD RCPs and plug-ins.

Please read this entire document before planning your upgrade.

This guide serves as a way to prepare for upgrades but is not exhaustive. Always check with techsupport for any additional instructions and a current list of patches before proceeding. If you areupgrading during non-business hours you can make arrangements for direct support for this process.

In order to completely understand the notions in this document, you should have sufficient knowledgeof the various functions available in the ARCAD product suite.

This guide does NOT cover step-by-step installation or update instructions.

ReferenceFor complete installation and update instructions for anyARCAD entity, refer to the ARCAD Installation Guide.

Related Documentation

ARCAD Compatibility Sheet

ARCAD Installation Guide

ARCAD Sever Configuration Guide

ARCAD SSL Configuration Guide

Publication record

Productversion

Documentversion Publication date Update record

≥ 11.0.x 1.2 July, 2019

Added prerequisites and tips to update fromv10.x to v11.0.7

Updated document instructions to clarify that thisdocument does not cover simple step-by-stepupgrade procedures but rather special cases whenupgrading from/to specific versions that requireextra planning.

10.09.xx 1.1 September,2018 No functional changes.

10.08.10 1.0 June, 2018Initial Publication. This document brings togetherthree individual upgrade documents to centralizethe upgrade processes for ARCAD core products.

Table 2: ARCAD Upgrade Guide publication record



ARCAD v11.0.xUpgrade Guide | 1 General update tips and procedures

1 General update tips and procedures

Preparation is key for a successful update with no impact to productivity. A number of differentelements must be updated when you upgrade ARCAD from one version to another and sometimes,there is more work to do than usual if the new version includes a lot of core changes.

After the server update, developers using RDi will also have to update their plug-ins. Also, due toparameter changes, any interfaces you have from ARCAD, interfaces you may have developed yourselfusing ARCAD APIs, and additional ARCAD clients (studios) will need to be updated.

If you have a highly complex implementation with interfaces and multiple ARCADmodules, you maywant to test the upgrade in a parallel copy of ARCAD. If you have any concerns about compatibilityplease contact support and they will find out what the requirements for anything specific.

1.1 Preparation

When planning the cumulative, the actual runtime of the process will vary depending on the spanbetween your current version and the cumulative version because the number of changes will increase.The speed of your server can also play a role.

When doing a significant update it’s a good idea to save the ARCAD_SYS, ARCAD_ENG and ARCAD_PRD libraries and /arcadifsprd IFS directory into SAVFs. ARCAD_SYS contains some files and objectsthat can be changed during the installation (to follow the installation status, for example) and the/ARCADIFSPRD directory contains lots of components used by ARCAD for xrefs (XML files) purposes orby ARCAD products linked to java (jar, scripts…). This also verifies there are no locks on them beforethe update.

There can be no locks on theARCAD_PRD and ARCAD_ENG ARCAD libraries, so the ARCADsubsystemmust be shutdown and no one should be using ARCAD through any interface. You can usethe WRKOBJLCK command to ensure that these libraries are not locked. Once the cumulative and anypatches are applied, then functional testing should commence to identify any issues that could possiblybe unique to your workflow.

1.2 Update the ARCAD Server

The update in place can be done from an optical disc or SAVF on the IFS.

The update process is the same as the installation process detailed in the ARCAD Installation Guideexcept for one difference: you do not have to replace the ARCINST.dta SAVF. Because theARCINST library already contains the contents from this SAVF (the installation contents are already onyour server from initial installation).

During a cumulative update, ARCAD uses theARCINST library to update itself and you can see theupdates in the transfer log. This is important for rollback options.

The ARCAD support teammay also supply patches to any release if issues have been discovered toolate to be incorporated into the GA (General Availability) packaging. Contact support for a current list ofpatches prior to applying a cumulative. Patches will be shipped as SAVFs that restore to a patch-specificlibrary and are applied post-cumulative with the RCVFIX command.

1.3 Update RCP clients and RDi plug-ins

Client installers will also perform an update. Run the appropriate setupxxx.exe. If you are using theObserver Documentation plug-in, you must also run the ARCAD Home core_setup.exe.



ARCAD v11.0.x1 General update tips and procedures | Upgrade Guide

The update process is detailed in the ARCAD Installation Guide.

TipChange the perspective to RSE to prevent locking any preferences thatmay need to be updated and start RDi with as admin. ARCAD will rarelychange the name of a plug-in in a cumulative, but if it has beenchanged, it’s recommended to uninstall the plug-ins and re-installationfrom scratch. Contact support if you are on a very old version ofARCAD.

1.4 Test

Testing should be done throughout the update cycle. Ideally, there should be a set of test objects thatincorporate one of each type commonly used at your site. The idea is to test key functions so any issuesdiscovered later can be worked around, or will not be blocking issues until a patch is supplied.

1.5 Roll back an update

Always plan the testing process in a short time frame from the cumulative update so rollback is viable ifissues are discovered.

When doing a significant update it’s a good idea to save the ARCAD_SYS, ARCAD_ENG and ARCAD_PRD libraries and /arcadifsprd IFS directory into SAVFs. ARCAD_SYS contains some files and objectsthat can be changed during the installation (to follow the installation status, for example) and the/ARCADIFSPRD directory contains lots of components used by ARCAD for xrefs (XML files) purposes orby ARCAD products linked to java (jar, scripts…). This also verifies there are no locks on them beforethe update.

The ARCAD cleanup job will delete those archived ARCAD objects out of ARRPLOBJ the very next timeit runs. If you perform the cumulative update and have testing planned the next day, you may want tohold the scheduled job to allow for rollback.

NoteIf you place the SAVFs in theARCAD_NET library, they will be deletedby the ARCAD cleanup job in 10 days if you forget about them.

Both rollback techniques, using SAVFs and using ARCAD to roll itself back, involve replacing the filedata with the previous data. It should be sufficient to test ARCAD functions with test objects. If youperform the cumulative over the weekend then use ARCAD for live actions, and then rollback, ARCADwill not have data (object history, checkout records, records of versions created) because the ARCADdata set will date from before the cumulative update was applied.

Server rollback can be done by renaming the updated ARCAD_PRD and ARCAD_ENG and restoring thesaved libraries. You can also restore using the transfer log and a time-span criteria. If you appliedpatches, the patchesmust be rolled back first and then the cumulative update.

Client/plugin rollback can only be accomplished by uninstalling the client/plugins and installing theprevious version. Be sure you have the previous version available to reinstall before starting the update.



ARCAD v11.0.xUpgrade Guide | 2 Upgrade from v10.x to v11.0.7

2 Upgrade from v10.x to v11.0.7

Preparation is key for a successful update with no impact to productivity.

ARCAD v11.0.7 is compatible with:

l RDi ≥v9.5l IBM i ≥7.1 (compatibility with IBM i v7.4 confirmed)

Check that the IBM cross-references are correct using this command:

RCLDBXREF OPTION(*CHECK) LIB(*ERR)

NoteIf an ARCAD library is in the resulting message, run RCLDBXREFOPTION(*FIX) LIB(ARCAD_PRD)

Clean old cross references to reduce the volume of your system. Launch the following command in thedays or weeks before the upgrade for all the applications to remove all the “obsolete” XRef data.:

ACLRXRF APP(xxxx) MIN(1) RGZDB(*NO)

TipIf you set RGZDB(*NO), you can run it during the day, while usingARCAD.

If you set RGZDB(*YES), you will savemore space but the RGZPFMmay take at long time.

Be careful to check the size of different ARCAD files to be sure that the upgrade doesn't take hours andhours. ARCAD files to check:

l AARDFLTF1: cross-ref headers per application/component/versionl AARDFLRF1: component zonesl AARDFLLF1: used lines in component zonesl AARDFLAF1: component literalsl AARDFLFF1: external references to component zonesl AARDFLCF1: links between component zonesl AARDFLDF1: links between component linesl AARDFPRF1: component proceduresl AARDFPSF1: component procedure parametersl AARDPXRF1: components' procedure-level cross-refsl AARDOXRF1: objects used by a componentl AARDSXRF1: sourcemembers used by a componentl AARDMXRF1: components' messages IDs



ARCAD v11.0.x3 Upgrade from v8 to v10 | Upgrade Guide

3 Upgrade from v8 to v10

3.1 Installation

To install the ARCAD Server ≥v10.xx.xx on IBM i alongside a v8, first download the v10 installationmaterials.

NoteIf needed, contact support to retrieve the information required toaccess the version to install.

Important!The following instructions assume you are upgrading via a DVD or amounted virtual optical drive.

Step 1 Using the QSECOFR profile or similar, initiate the installation with the LODRUN [optical drivename] command.

You will see the response below as it restores the install library ARCINST.

Step 2 When that is complete you be presented with the install interface that indicates there is alreadya library out there with the default name ARCAD_XXX by highlighting the first line in red.

Select option 4 to modify the name of the instance which will change library name.



ARCAD v11.0.xUpgrade Guide | 3 Upgrade from v8 to v10

Step 3 Enter 10 for the instance value and press Enter.

Step 4 You will be back on the install interface which will indicate the new library names.

Select option 1 or 2 to submit the job.




Step 5 If you launch the job in batch mode, the install will prompt you for install parameters and youcan submit to any specific JOBQ or JOBD etc.

Step 6 Press Enter to submit the batch job.




Result Once the install is complete you will have 2 separate installs of ARCAD that will co-exist withoutconflict while you test the ≥v10, as long as you’re careful.

3.2 Understanding ARCAD ≥v10 audit results

The audit you run before any migration generates information about potential issues you will haveduring migration. You should have received a spreadsheet containing the output so you can use this todetermine any problems or space requirements during themigrations. In the spreadsheet there aremultiple worksheets with the name on the tab.

Content of these worksheets:

l LSTCHROVER: Version chronology problem after transfer from SBCS into Unicode.l LSTMACCVT: v8-v9 conversion results of themacro-commands. This list contains all retrievedmacro-commands, and especially those with a v9 conversion error (status = ‘Abn’). Thesemacro-commands with conversion error must be checked and modified.

l LSTMACUNK: List of macro-commands not found in the restore library of the SAVF sent by thecustomer.

l LST_CFG: List of configuration information.l LSTOPNSRC: List of customized programs.l LSTOPTFLT: List of warnings after the conversion of list filters, version options, list options anduser options.

l LSTMACCALL: List of macro-commands containing programs calls (use of the CALL command).l LSTMACSQL: List of macro-commands containing SQL queries (use of AEXCSQL, RUNSQLSTM,

STRQMQRY commands).l LSTCVTFIL: List of all files from ARCAD_PRD with their size.

The lists in red contain errors that must be analyzed before themigration to v10.

The lists in orange contain elements that must be analyzed before themigration to v10.

The lists in blue contain elements that must be verified after the installation of v10.




The lists in green contain only information.

3.3 Migrating licenses from v8 to ≥v10

The licenses from ARCAD v8 will work in ARCAD ≥v10 but the names of the products are slightlydifferent. See below for themapping.

3.4 Data migration

The next step is to migrate data from v8 to ≥v10. This process copies the data from v8 to ≥v10 withoutaffecting v8. Please use the following steps:

3.4.1 Clear old and temp data

Clear old and temp data to reduce copy time.

SBMJOB CMD(CLRXREF NBMIN(2) RGZDB(*YES))

Step 1 Clean up the ARDILPF1 and ARDILQF1 files (temporary info for prototypes definition in /COPYof ILE programs in versions):

l DELETE FROM ARCAD_PRD/ARDILQF1 WHERE ILQ_APPID = ' '

l DELETE FROM ARCAD_PRD/ARDILQF1 WHERE ILQ_VERS IN (SELECT VRVERS FROM ARCAD_PRD/ARMVERF1 WHERE VRMRFD <> 0 AND VRVERS < ‘versionnumber’ AND VRAPP =‘appId’) AND ILQ_APPID = ‘appId’

l DELETE FROM ARCAD_PRD/ARDILPF1 WHERE ILP_APPID = ' '




l DELETE FROM ARCAD_PRD/ARDILPF1 WHERE ILP_VERS IN (SELECT VRVERS FROM ARCAD_PRD/ARMVERF1 WHERE VRMRFD <> 0 AND VRVERS < ‘versionnumber’ AND VRAPP =‘appid’) AND ILP_APPID = ‘appId’

appId = Application Id

versionnumber = reference version - 5 (we keep info for the last 5 closed versions)

Step 2 Clean up the ARMMOQF1 (temporary info for DB2 components in versions):

l DELETE FROM ARCAD_PRD/ARMMOQF1 WHERE MOQ_APP = ' '

l DELETE FROM ARCAD_PRD/ARMMOQF1 WHERE MOQ_VERS IN (SELECT VRVERS FROM ARCAD_PRD/ARMVERF1 WHERE VRMRFD <> 0 AND VRVERS < ‘versionnumber’ AND VRAPP =‘appid’) AND MOQ_APP = ‘appId’

Step 3 Reorganize these 3 files (ARDILPF1, ARDILQF1 and ARMMOQF1) after clean-up: RGZPFM

Step 4 Check the referential constraints for the ARCAD_PRD library using one of the following way:

l ACHKPFCST LIB(ARCAD_PRD) (if you use an v08.15.00 or higher)l WRKPFCST FILE(ARCAD_PRD/*ALL) TYPE(*CHKPND)

NoteIf you have some constraints in check pending, please solve itbefore themigration

Step 5 Check if the IBM Cross References are correct:

l RCLDBXREF OPTION(*CHECK) LIB(*ERR)

NoteIf an ARCAD library is in the resulting message, run RCLDBXREFOPTION(*FIX) LIB(ARCAD_PRD)

3.4.2 Run the DB migration

l CHGSYSLIBL ARCAD_ENG *REMOVE

l CHGSYSLIBL ARC10_ENG *ADD

l Be sure the initial LIBL, Current library and system LIBL are set to *CURRENT on the submit jobcommand.

l SBMJOB CMD(ACVTARCDBF FROMLIB1(ARCAD_PRD) FROMLIB2(ARCAD_ENG) TOLIB(ARC10_PRD)CRTFILE(*YES) DEPLGL(*YES))

Check the databasemigration results: ADSPCVTLOG

You can enter the new c10 instance of ARCAD by qualifying the command ARC##_ENG/ARCAD andverify data migration by looking at the repository or version list.

3.5 Macro conversion

Once the data is migrated the next step is to convert themacros you have customized in v8 to the ≥v10format. One of the changes in v10 is that the commands all had an A added in front of them as well asfields and files were changed. The conversion goes through and changes all the command referencesand files and field references. Themacro engine was enhanced as well so parameters have gone fromtwo character to 10 characters and naming conventions have been instituted such that an internal parmmust start with W and an entry parmmust start with P. Themacro conversion process takes the v8




macro and updates it into a new library and attempts to parse through and adjust to all the changes. Itgenerally does a great job but it can miss internal parms and it has an issue with SQL used in macros.When the conversion completes it identifies thosemacros that had issues with conversions. One ofresults in the upgrade audit is all macros that contain SQL. There is also a list of macros that CALLprograms, again requiring careful review because of parameter and program name changes. Seesections on those below.

3.5.1 Conversion

The best practice for macro conversion is to create a new library to convert to for testing purposes forexample ARCAD_MC##. You can either identify individualmacros to convert, or make a list of all v8macros and convert themwith a batch job. To convert an individualmacro use the command:

ACVTMACCMD MACRO(ARCAD_ENG/[macro]) TOMACRO(ARCAD_MC10/*FROMMAC) EDIT(*NO) CHKOBJREF(*NO)

If you wanted to do amass conversion you could:

l Create the list of existing macro-commands:

ACRTOBJLST LIB(ARCAD_ENG) TYPE(*CMD) USRDFNATR(MACRO) TOLIST(ARCAD_MC10/LSTMAC)OMTLSTMAC(*NO)

l Convert the existing macro-commands:

SBMJOB CMD(AEXCLST LIST(ARCAD_MC10/LSTMAC) CMD(ACVTMACCMD MACRO(ARCAD_ENG/&LOBJ)TOMACRO(ARCAD_MC10/*FROMMAC) EDIT(*NO) CHKOBJREF(*NO)))

l Check and fix each converted macro-command in ARCAD_MC10.

You have to identify each macro you use for checking for errors and subsequent testing. In themacroheader you can see the last execution date to verify if a macro is actively used.

To check for errors or work on specific errors enter themacro with a 2 and use F22 to verify. In thisscenario where the converted macros live in an alternate library you want to enter your v10 version ofARCAD and use the command:

AWRKMACCMD MACRO(ARCAD_MC10/*ALL)

Then select 2 on amacro to edit and use F22 to interactively validate themacro and you’ll be presentedwith the error panel:




Either no errors or a list

When you F3 to exit it brings you into themacro with all the lines with errors highlighted in red

If you drill into a line with a 2 the error is shown specifically at the bottom of the panel




Every time you go into amacro to edit when leaving editing themacro is checked again and the error listcomes up. Use F8 to truly exit.

3.5.2 Macros with SQL

Macros that have SQL statements in themmust be checked very carefully as the SQL syntax is NOTchecked by ARCAD’s macro validation process. Review themacros listed in the LSTMACSQL worksheetcarefully. Each entry is a line in amacro that executes SQL. The conversion does try to change all theARCAD file and field names referenced in the SQL statement, but the parser can be confused by SQLsyntax. Since the field types and lengths have changed that might also cause issues with an SQLstatement that would need to be resolved. This would be especially true of any non-ARCAD tables areused, like work tables.

Below are some examples of SQL.

Here we see a line with SQL, note that SQL statements are often quite long and get truncated in thedisplay. F20 will show a full page line.




As an example here is an SQL statement from v8

AREXCSQL SQLSTM('insert into &LS/RPTCHKOUT (LSNOM, LSAPP, LSVERS, LSZSL2, LSOBJ, LSTYP,LSZSEL, LSATR, LSDATM, LSTXT, LSTTYP, LSLIB) SELECT LKAPP, LKAPP, LKFVER, LKSRCF,LKSRCM, LKTYPE, LKPGMR , '' '', LKDATE , LKREFR , ''O'', LKSRCL FROM armlckf1 WHERELKapp = ''&AP''')

This is the same statement converted to v10, again manual remediation can be necessary depending onhow the parser fared during the conversion.

AEXCSQL SQLSTM('insert into &ALSTLIB/RPTCHKOUT (LST_JZSEL3, LST_CApp, LST_CVer, LST_JZSel2, LST_JObj, LST_CType, LST_JZSel1, LST_CAtr, LST_TDATE, LST_CTxt, LST_CEltTy, LST_JLib) SELECT LCK_CAPP, LCK_CAPP, LCK_CFMVER, LCK_JSRCF, LCK_JOBJ, LCK_CTYPE, LCK_JPGMR,'' '', LCK_TDATE, LCK_TCRTT, ''O'', LCK_JLIB FROM AARMLCKF1 WHERE LCK_CAPP = ''&AAPP''')

Remember that files normally had an A appended to the v8 name but not always. Additionally all fieldnames changed.

3.5.3 Macros with call commands

LSTMACCALL is a list of all macro entries that use the CALL command. If an ARCAD program is calledthen the conversion should adjust the program name and parameters appropriately. This should still bedouble checked. If it’s a custom program that will also reference ARCAD artifacts then the customprogramwill need to be adjusted for ARCAD’s new files, fields and program names and as such couldvery well have its parameters changed. The conversion will not take into account changes that will bemade to called programs after themacro conversion.




In this example we see a call made in v8 to generate a temporary library

In this example here is the same line automatically converted to v10 with Unicode parameters.

3.6 Customized programs

3.6.1 Types of customizations

There are 2 types of customized programs, those that ARCAD ships in the ARxxxxxx source files inARCAD_PRD and those that are created from scratch with unique names. The ones that ARCAD shipsare called or can be called from ARCAD ’s normal functions and have a different name in ≥v10. Theprograms unique to your installation can be called from amacro, or an exit point by customizing thecommand defaults.

If a customized program calls other ARCAD command or programs and/or it accesses ARCAD files thenit will most likely have to be converted to Unicode along with updating any parameters. The process isthe same for both types. So the steps are to fix the codemanually and then use the ARCAD Unicodeconversion process for correct functionality.

3.6.2 Unicode conversion

It is required that the program successfully compile before conversion can be performed by ARCAD’sprocess. So the first step is change parameters. Here is a list of v8 parameters:

DCL VAR(&APPID) TYPE(*CHAR) LEN(3)DCL VAR(&TSTID) TYPE(*CHAR) LEN(1)DCL VAR(&VERS) TYPE(*CHAR) LEN(8)DCL VAR(&OBJ) TYPE(*CHAR) LEN(10)DCL VAR(&LIB) TYPE(*CHAR) LEN(10)DCL VAR(&OBJTYP) TYPE(*CHAR) LEN(7)DCL VAR(&SRCFIL) TYPE(*CHAR) LEN(10)DCL VAR(&SRCLIB) TYPE(*CHAR) LEN(10)DCL VAR(&SRCTYP) TYPE(*CHAR) LEN(10)DCL VAR(&CPLTYP) TYPE(*CHAR) LEN(7)




Here is the same list converted to the v10 format, note that each parameter length has been doubled tosupport Unicode format and the parameter name is following a naming convention to support theUnicode conversion

DCL VAR(&W_CAPP) TYPE(*CHAR) LEN(20)DCL VAR(&W_CENV) TYPE(*CHAR) LEN(20)DCL VAR(&W_CVER) TYPE(*CHAR) LEN(16)DCL VAR(&W_JOBJ) TYPE(*CHAR) LEN(20)DCL VAR(&W_JLIB) TYPE(*CHAR) LEN(20)DCL VAR(&W_CTYPE) TYPE(*CHAR) LEN(20)DCL VAR(&W_JSRCF) TYPE(*CHAR) LEN(20)DCL VAR(&W_JSRCLIB) TYPE(*CHAR) LEN(20)DCL VAR(&W_CSRCT) TYPE(*CHAR) LEN(20)DCL VAR(&W_CCPLT) TYPE(*CHAR) LEN(14)

Of course any reference to an ARCAD object must be updated so a CL that uses CPLOBJwill now callACPLOBJwith updated parameters.

You should be doing this source remediation IN ARCAD ≥v10 using a special function, the ARCAD ZIAapplication.

3.6.2.1 Preparation

It is highly recommended to manage the Open Source programs in the ZIA application

Open Sources are stored in two source files:

l ARCLSRC and ARRPGLESRC for standard types RPGLE, CLPl ARCLSRC2 and ARRPGLESR2 for RPGLE2, CLP2

NoteIf you need to change one of them outside ZIA application (notrecommended), you have to change and compile the RPGLE2 or CLP2

If the program contains some input parameters, check if they areUnicode or not (Unicode parameters need to double the variable size:for example a variable 10 Unicode equals a variable 20 A)

You can check as for example AARM255C6 that uses ARTVAPPD command

If these sources aremanaged in the ZIA application:

1. Be sure that no version are open for ZIA application2. Open a new empty version (with the next “official number”)3. Check if source files are correctly set for application ZIA (topology)4. CHGJOB CCSID(297)5. Launch themacro PRPUNI0:

It creates all the CLP2, RPGLE2, .. source type

It creates the parameter for source file (with correspondences for maintained/generated source files)

Entry parameters:

-Create source types 2 . . '*YES'-Applic. for source files . ZIA-Version for source files . ’version number’




After that, you can check-out or create CLP/ RPGLE in the ZIA versions (the version mentioned above,and all the new versions)

When you compile using option 9, the ARCAD Unicode pre-compiler is activated and you will see thatthe CLP2, RPGLE2will appear in the version:

-maintained source (type CLP, RPGLE)-generated source (type CLP2, RPGLE2)

NoteYou may have to change something in themacro used when a ZIAversion is closed (transferred to production)

It is not useful to calculate Xref for CLP, RPGLE, when thecorresponding CLP2, RPGLE2 exists

With this, by default all CLP / RPGLE sources in ZIA application will usethe ARCAD Unicode pre-compiler

In a source, you can inhibit this if you put:

/* %PRECPL *NOCVT */

In that case, the 2 sources will be exactly the same.

If you compile the CLP but no CLP2 appears, perhaps it can be causedby the general parameters. Check the AWRKCPLTYP (I_ARCAD option12) if the *CLP is defined as "*INT". If not change to *INT and retry tocompile the CLP in the ZIA version.

3.7 Testing and avoiding conflicts

Oncemacro conversion has been completed it’s time for testing. The test cycle should encompass acomplete cycle of your current CM process and this section will cover those areas that require specialhandling to avoid conflict with v8 activity. Since every customer of ARCAD has some uniqueness totheir process this document can not cover your CM process but rather help you avoid the possibleconflicts.

3.7.1 Version library

Themost significant conflict is the version library. Since all your information was copied from v8 to≥v10, including application name and environment names, the same naming convention will be usedfor versions and version libraries. When you create a version in v10 you MUST assign a specific versionname and not use *GEN for version name. If you create a version with the same name as an existingversion in the other install of ARCAD you will have a conflict so be sure to specify a version namewelloutside of the current range in v8, for example using X instead of V at the beginning or 99 at thebeginning. These version(s) used for testing will go away once you go live on v10 although the versionlibraries must be deleted manually if the test versions are not deleted from ≥v10 before go live.

3.7.2 ARRPLOBJ naming conflict

A potential conflict can come up in the ARRPLOBJ and ARRPLSRC library when object and source isarchived. If the ≥v10 install of ARCAD uses the same name as was used in the v8 version then there willbe a conflict and the archive will not occur in ≥v10 and possibly vice-versa. The solution is to reset thefile that controls the sequence used in the name using SQL, in the case below to start in the 8 millionsequence:




Update ARC10_PRD/AARKPRKF1 Set PRK_IVALUE = 8000000 Where PRK_JFILE = ‘ARRPLOBJID’

3.7.3 Distribution

If you distribute to a remote system then you have 2 options to test this.

When ≥v10 is installed it creates its own profile and staging library. If you use the ## value for the ≥v10instance then ARC##_NET profile and library are created. There is also a communication job createdcalled ARC10 under the profile ARC##_NET in the ARCAD subsystem.

The first option is to use the ARC##_NET profile, which means you have to change the profilereferenced in the system definitions in the distribution menu. Your current profile (typically ARCAD_NET) has been copied over with the other data about your site definitions. The newARC##_NET profileis created with no password so that must be set on the systems involved and setup on the sitedefinitions. If you have security on FTP then ARC10_NETmust be authorized to do all the FTP actionsneeded.

The second option is to continue to use the ARCAD_NET profile, which means that the USER specifiedin the AMSGCMDE job description in ARC##_PRDmust be changed to ARCAD_NET. In this case theauto-start job entry on the ARCAD subsystem for the ARCAD job must be deleted as only one job canbe running under the ARCAD_NET profile. Then the ARCAD subsystem is restarted and you will havethe ARC## job running under ARCAD_NET.

So to set the auto start jobs for ≥v10

l RMVAJE SBSD(ARCAD_SYS/ARCAD) JOB(ARCAD)

l ADDAJE SBSD(ARCAD_SYS/ARCAD) JOB(ARC10) JOBD(ARC10_PRD/AMSGCMDE)

So to set the auto start jobs back for v8

l RMVAJE SBSD(ARCAD_SYS/ARCAD) JOB(ARC10)

l ADDAJE SBSD(ARCAD_SYS/ARCAD) JOB(ARCAD) JOBD(ARCAD_PRD/MSGCMDE)

In both of the above options you must check to see if the ARCAD subsystem has ARCAD_ENG definedas a system library, which is common on remote systems.

l DSPSBSD SBSD(ARCAD_SYS/ARCAD) and take option 1 for operational attributes.

l CHGSBSD SBSD(ARCAD_SYS/ARCAD) SYSLIBLE(ARCAD_ENG) for v8

l CHGSBSD SBSD(ARCAD_SYS/ARCAD) SYSLIBLE(ARC10_ENG) for v10

Once you have completed your adjustments to the ARCAD subsystem for testing in v10 or putting itback to v8 it must be stopped and started again.




l ENDSBS ARCAD *IMMED

l STRSBS ARCAD_SYS/ARCAD

3.8 Final ≥v10 update

When you have completed your testing with v10 you will upgrade your v8 installation directly so yourv8 installation will then be ≥v10. You will have a single set of ARCAD libraries when complete.

3.8.1 Preparation

Preparation for the v8 upgrade is minimal. Be sure to backup ARCAD_ENG and ARCAD_PRD beforedoing this and verify there are no locks on any of the ARCAD libraries. The ARCAD_ENG and ARCAD_PRD libraries will be renamed during the live upgrade so any locks will prevent this. One scenario thatcan prevent the rename is if you have ARCAD_ENG in the QSYSLIBL system value. This will placeARCAD_ENG in the system portion of the LIBL of ALL JOBS. If the ARCAD_ENG library in on anyactive job’s LIBL it CANNOT BE RENAMED and the upgrade will fail. The only reasonable way toaccomplish this is to change the QSYSLIBL system value and IPL the system so all the system jobs arerestarted.

3.8.2 Process

The process is to run the install again but leave the defaults in place to upgrade v8. Be sure to backupARCAD_ENG and ARCAD_PRD before doing this and verify there are no locks on any of the ARCADlibraries.

You will likely see a reference to the v10 testing instance as well. And then:




During the running of this upgrade job you will receive additionalmessages from the batch job, so itshould bemonitored. Answer yes to the prompts about migrating configuration data and convertingmacros. It’s normal to receive amessage that macros have failed to convert because that was the one ofthe reasons for creating the v10 test instance - to fix thosemacros that would not convert under thestandard process.

When this job completes you then want to copy any customized macros from the v10 testing copy toyour new upgraded copy of v10. You can accomplish this by entering the testing copy and in the list ofmacros copying them to the ARCAD_PRD library. The date field should indicate which macros you hadto edit. If any other remediation was necessary during the testing of ≥v10, such as customizedcommands or programs they should also be copied.

You can also execute themacro PRDNEWVER in case you have customization in that macro that needsto be applied.

At this point, it’s also a good idea to remove any extra copies of ARCAD from the instance file inARCAD_SYS. This file is read when you connect from the RDi plugins or ARCAD Client as well as by thecumulative upgrade process and there is an opportunity to accidentally choose the wrong instance, likethe ≥v10 testing instance. The name of the file is AARCINSF1 and the simplest way to do it is to useSQL:

To display any additional instances SELECT * FROM ARCAD_sys/aarcinsf1 WHERE INS_JCODE <>'AD'.

To remove themDELETE FROM ARCAD_sys/aarcinsf1 WHERE INS_JCODE <> 'AD'.

Be sure to make a copy of the file first before updating it. You may also need to set your job CCSID to37 before using interactive SQL.

3.8.3 Post update

After the upgrade if you have copied the ARCAD command anywhere like QGPL be sure to delete theold ARCAD command and copy the newARCAD command to that location as the CPP has changed.Once you have been using the newARCAD v10 upgraded instance and are comfortable you have notforgotten anything you can delete the ARC10_ENG, ARC##_NET and ARC##_PRD libraries.




Additionally if you have incorporated any ARCAD commands (but not macro commands) into menuoptions or utility programs, don’t forget to add the A prefix onto the command. For example,initializing on a version or environment in v8 INZCURENV becomes AINZCURENV in ≥v10.

Be sure to test the upgraded version of ARCAD completely before deleting the ARC##_ENG andARC##_PRD libraries and the backed up v8 libraries.




4 Upgrade from v8 to v9

The only procedure to install the ARCAD Server v9 is to use an ARCADMaster v9.

Pre-requisites: an ARCAD version 08.09.xx or higher. If you are running an older ARCAD version, thefirst step is to upgrade to ≥08.09.xx.

Important!This updatemust be preceded by an audit prior to installation to ensurethat themacros are converted and special cases are detected.

It’s recommended to execute the upgrade in three steps:

1. Execute the audit macro from v8 to v9. Transfer the SAVF to ARCAD Support.2. Install an ARCAD v9 (in a test instance for example - 'T9') to test themigration database from v8 to

v9.3. Test themigration database using the ACVTARCDBF command. Delete the T9 instance (Test

instance).4. If themigration and the audit analysis are valid, install the ARCAD Server v9 in the AD instance

(cancel &replace).

Adapt the product installation in ARCAD v9 when migrating from a v8 version (>08.06.00):

1. Backup library name change (ARCxx_OLDP, ARCxx_OLDE or ARCxx_OLDF)2. Convert v8 database (SBCS EBCDIC-) to a v9 database (Unicode).

4.1 Test the database migration from v8 to v9

ACVTARCDBF - Convert ARCAD v9 database in Unicode.

This new command is responsible for migrating permanent files from an ARCAD database at level v8 (>= 08.06.00) in SBCS, to an ARCAD database at level v9 in Unicode.

4.2 Pre-check before the live migration

You have installed a new instance v9 (without data transfer).

You can then simulate the process of migration from the libraries of the v8 instance (or a copy of it) to atarget library, created empty with any name you choose (just for the test).

This allows you to better plan the actual process of migration (knowing the necessary disk space andprocessing time).

It is possible to run thesemigration tests by reading data directly from v8 to convert libraries ARCxx_PRD and (ARCxx_ENG or ARCxx_FRA), from a v8 instance is used and updated. However, this maycreate inconsistencies in the results file.

4.3 Live migration

This command is run at the end of the installation process of an ARCAD instance for version v9. Itcancels and replaces the same instance in ARCAD v8.

During the process, status or log messages indicate:




l The number of files processed/to process (and files in error, if any)l The number of records processed/to process (and records in error, if any)

During the process, or after the end of the process, you can consult the conversions performed viacommand ADSPCVTLOG.

Here are the indications concerning the necessary disk-space:

l Test prior to migration without creating the logical filesl Size of target library = 1,6 x Original library size of ARCxx_PRD.l Test prior to migration when creating the logical files or for the Real/LiveMigrationl Size of target library = 2 x Original library size of ARCxx_PRD.



ARCAD 11.0.x Upgrade Guide · NorthAmerica&LATAM EMEA(HQ) AsiaPacific 70MainStreet,Suite203...

Documents

Transcript of ARCAD 11.0.x Upgrade Guide · NorthAmerica&LATAM EMEA(HQ) AsiaPacific 70MainStreet,Suite203...