Appendix 4. Upgrading from Older Versions of Wizard

WIZARD-I To WIZARD-III
WIZARD-II/III To Wizard/Pro
	Installing Wizard/Pro into the WIZARD-III User Account
	Upgrading Proc Menus
	Updating Screens and Reports
		Updating User Code Segments
		Changed Wizard Variables
		Changes to the Sequence of Events
Further Support

WIZARD-I To WIZARD-III

Included in Wizard/Pro is a routine to help users of WIZARD-I upgrade their software. This will allow you to convert WIZARD-I screens to WIZARD-III format, from which you can proceed to Wizard/Pro by following the next set of instructions.

WIZARD-I stored program definitions in two files: WVD and WFD. Wizard/Pro, however, stores definitions only in the WVD file. To convert from WIZARD-I, the following procedure is recommended:

Create a new account and install Wizard/Pro into that account. Also create a file called WFD (using WIZARD's file maintenance routine).

Copy all items from WIZARD-I's WVD and WFD files into the corresponding files in your new account. You should be able to do this with the following steps:
```
   SET-FILE WIZARD-I WVD
   COPY QFILE *
   TO: (WVD
```
After which the items will be listed as they are copied. Do the same for the WFD file:
```
   SET-FILE WIZARD-I WFD
   COPY QFILE *
   TO: (WFD
```
(NOTE: On your system, the WIZARD-I account may have another name. Check and substitute in the above commands.)

Create a pointer file to the file CONV.BP in the Wizard/Pro account. You can do this as follows:
```
   ED MD CONV.BP
```
(If the system does not respond with "New item, type EX and hit [Return]", the pointer already exists. Skip to point 4.)

Type I and <Return>, then enter:
```
   001 Q
   002 WIZARD
   003 CONV.BP
```
To exit the editor's insert mode, type <Return> twice. Then type FI and hit <Return>.

Run the conversion program:
```
   RUN CONV.BP WIZ1.CONV
```
This will automatically convert all the WIZARD-I programs in the account. You may then access them using Wizard/Pro's FS command (or from the W menu).

You are now ready to proceed to the second stage in conversion, from WIZARD-III to Wizard/Pro screens.

WIZARD-II/III To Wizard/Pro

When upgrading it is a good idea to work with a copy of your data accounts in case you need to refer back to the original version of your screens or data. The following instructions outline the steps suggested to upgrade a WIZARD-II or WIZARD-III account to Wizard/Pro.

Part 1: Installing Wizard/Pro into the WIZARD-III User Account:

The first step in upgrading your account is the installation of Wizard/Pro into the WIZARD-III account. The steps you should follow to accomplish this are:

From the WIZARD-III account you wish to upgrade (not the WIZARD account itself, but the user account), copy login proc to backup location. This is only a precaution, but you may need to be aware of some of the processes undertaken by your old account’s login when you want to finish configuring the account.

Log to the Wizard/Pro account, called WIZARD by default. From the main menu, select option 1, "Install Wizard." This will open a Wizard/Pro screen asking for details of the account you wish to install Wizard/Pro into. For more detailed information on the Wizard Installer routine, see Chapter 4.

You should use the following responses for this screen:
```
  1 Account Name     : [The name of the account you're upgrading]
  2 Install Menus    : Y
  3 Install Generator: Y
  4 Use data files in: [Do not enter anything, just press <return>]
```
You should then press <return> at the acceptance prompt to begin the install.

During the install, you may be asked further questions. You should answer "Y" to all questions. Types of questions you may see include:
An item "xxxx" exists in destination MD. Overwrite (Y/N) :
An item "xxxx" exists in the MD - overwrite (Y/N) :

The installer will copy a number of items into the new account. This may take a couple of minutes. When it has completed, it may report that some errors were encountered. These are probably not serious, but will be stored in an item in the MD called "WIZ.INST.ERRS" which you should examine. If Wizard/Pro failed to create certain files, this could cause problems later on and you should determine why the creation of those files failed and, if necessary, create them manually.

If all goes well you should then be asked for confirmation of your terminal type and presented with the default menu. You are now ready to update you programs, reports, and menus.

Part 2: Upgrading Proc Menus

Older versions of Wizard allowed users to create menus which were written as PICK PQ-procs. Wizard 4.1.0 and above employ a more sophisticated Menu processor. These versions of Wizard include a process which will upgrade older proc menus to new Menu definition items.

To convert WIZARD-III's "proc" menus you must have the original Menu definition items (which Wizard will have written into your old WVD file). If you have these, you can proceed. If you do not have these, you will have to rebuild your menus manually using the menu entry screen.

To convert your menus, follow these steps:

From TCL in the account you are upgrading, enter:
```
   RUN WIZ.BP W.ProcMenuConv
```
Followed by the <return> key twice. You should then be presented with the conversion screen, a small window in the bottom left corner of your screen. This screen is depicted below.

The first option is the name of the Menu file into which you wish to have your menus created. The default is the file MENU, which is Wizard's default menu file.

The second option allows you to enter the name of a specific menu to convert, or "*" which means convert all menu definitions in the WVD file.

The third field is display only and will display the name of the menu currently being converted when the conversion process begins.

To initiate the conversion process, enter the above information and, from the Acceptance Prompt press <return>. The last field on the screen should display the names of the menus as they are processed. When this is complete, you may add these menus to user's menu trees.

Note that certain information cannot be derived from the older WIZARD menus. Menu security levels are left at "0" for all converted menus. To alter these, you should edit the newly created menus from the Maintain Menus screen.

The second step of the conversion process is required to update security details used by Wizard/Pro's menu system. Before you can begin, you need to make sure that the menus are linked to user login definitions in the WIZ.LID file. To do this, you must create a WIZ.LID entry which links to the top menu in your menu tree. This is done using the "Logon Security" option from the "Account Security" menu in the default menus installed into your account.

When you have created a user login definition which links to the menus, you are ready to run the second stage of the upgrade process over the menus. To do this, from TCL type:

   RUN WIZ.BP WUpgrade

Followed by <return>. The process may take a couple of minutes, depending on the size of the account.

This process requires as a bare minimum:

A WSEC file.

Access to menu files. It determines which are valid menu files by looking at the items in the WIZ.LID file to determine where the security system will look for menus.

Appropriate MD (or VOC) catalog pointers for B, C, W, and S type menu processes. The upgrader will try to determine the file in which the source and/or object for the process exists.

NOTE that this process irreversibly changes menus. It is a good idea to make a backup of your menu files prior to running this process.

The upgrader routine uses this information to build the appropriate WSEC security file information for all the processes. It removes from the MENU items security level information and help item information.

Part 3: Upgrading Screens and Reports

Probably the most time consuming part of the upgrade process is the conversion of old screens and reports. The reason for this lies in the flexibility inherent in the Wizard 4GL. Since Wizard developers are permitted to add their own custom code to Wizard screens, there is no way Wizard can predict every possible variation of coding in screens. For this reason, you will have to test each screen you convert to ensure that it behaves as you expect.

The first step in the upgrade process for screens and reports is to upgrade the WVD items. To do this, you should go to TCL in the account you are upgrading, and run the commands:

   SSELECT WVD
   RUN WIZ.BP UpGradeWVD

This process will run through the screen and report definitions and update them. Once it has run, you should be able to begin regenerating your screens.

To regenerate all screens, from TCL type:

   WIZ.GEN.ALL

This will produce the message:

   There is no active SELECT list.
   Are you sure you want to generate ALL your Wizard screens?
   Type "Y" to continue :

Answer "Y" to begin regenerating all of your screens. Once this process is complete, it will be necessary to test each screen and report individually and ensure that they are working correctly.

Updating User Code Segments

The one area of your programs you should be aware may cause you problems as you upgrade are your code segments. These may behave differently if you use any Wizard variables or call any Wizard subroutines.

Changed Wizard Variables:

Some obsolete or changed Wizard variables are described below:

CURRENT.FIELD

This variable was used to store a numeric value representing the currently active Wizard field. It has been renamed CF.

I$

This variable did, and still does, contain the data entered by the user in the most recent input field. In earlier versions of Wizard this variable was interrogated to determine whether a command (such as /ED) had been entered.

Now, a variable WCOM is checked to see whether a command was entered. WCOM is virtually identical to I$ except that some pre-processing is performed.

This means that if at some point you change the user's input to a Wizard command you will now need to alter WCOM rather than (or in some cases in addition to) I$.

ESC.DM, ESC.ADDS

Older versions of Wizard interpreted the <Esc> key followed by <Return>. Sometimes user code may also check to see whether the <Esc> key was pressed by checking I$ against these values.

In Wizard 4.1.0 and above, Wizard's keyboard processing routines re-map the keyboard entry to internal values. Thus, when <Esc> or [F10] is pressed, Wizard returns the code stored in the Exit variable in I$ and WCOM. Occurrences of ESC.DM and ESC.ADDS in your programs should be replaced by a single check against Exit as follows:

   Before:
      IF I$ = ESC.DM OR I$ = ESC.ADDS THEN ...

   After:
      IF WCOM = Exit THEN ...

Changes To Sequence Of Events:

Wizard versions prior to Wizard 4.1/WIZ4+ (that is, Wizard-I, Wizard-II, and Wizard-III) executed Input Conversion code segments differently to how Wizard 4.1 and later perform this code.

When a null character (i.e. the <Return> key is pressed without any data being entered) in Wizard 4.1 and above, the Input Conversion code segment is NOT executed. In earlier versions of Wizard the Input Conversion code was executed no matter what was entered into a field.

If you have code which must be executed at a field, regardless of what the user enters, but that code is currently in the Input Conversion code segment, you can consider one of the following solutions:

Move your code from Input Conversion to either Before Field or After Field code.

If the field is Display Only or input is not performed by Wizard but rather by your own code, you can simply place the line:
```
   GOSUB 450000
```
in either Before field or After field code segments. (If data entry is allowed and you do this you may process the code twice - once when Input Conversion is done and once when After Field is done.)

You may place the code in Command Time code, although you will have to include a check to ensure that you are at the appropriate place (since Command Time code is executed for each field). If you do this, you may include your code as follows:
```
   IF FLDNM(CF)=DESIRED.FIELD.NAME THEN
      * Your code...
   END
```
Where DESIRED.FIELD.NAME is the internal name of the field as displayed at the head of the EP screen, or as displayed in the RS sequence list.

Problems may also arise when you change platforms (say from R83 Pick to UniVerse) if you EXECUTE or PERFORM any system functions from your code.

Further Support

If you encounter any difficulties, we at Pick Products would be happy to help you out. Send us a fax or an email with a description of the problem. If you have narrowed the difficulty down to a particular code segment print that out and fax it, together with a description of what you want to achieve, to us. Entitle the fax Wizard Upgrade Difficulties and fax to +61 2 8213 3615. Remember to include your return fax number (including your Country and Area codes).

If you have access to email, you can attach a copy of the WVD for the screen to an email with a description of the problem (and, if necessary, a description of exactly what you expect to happen) and we'll take a look at the problem for you.

For Wizard support, email wizard@pickproducts.com.au.

Appendix 4. Upgrading from Older Versions of Wizard

Contents