Technical Bulletin
Issue Date
June 21, 2004
Win Prep-For Utility
Win Prep-For Utility ...............................................................................2
Introduction......................................................................................................... 2
Key Concepts...................................................................................................... 3
Theory of Operation .......................................................................................................... 3
Limitations ......................................................................................................................... 4
Detailed Procedures........................................................................................... 5
Switching Between Contract Databases Residing on the Same System.......................... 5
Creating the First Project Contract on a Branch Workstation or Laptop ......................... 10
Creating a New Contract on a Branch Workstation or Laptop ........................................ 14
Loading a Customer’s Machine with a Contract Created on a Branch Workstation or
Laptop ............................................................................................................................. 14
Troubleshooting ............................................................................................... 15
Error Messages............................................................................................................... 15
Prep-For Fatal Error Messages....................................................................................... 15
Prep-For Non-Fatal Error Messages ............................................................................... 17
© 2004 Johnson Controls, Inc.
Code No. LIT-1201656
www.johnsoncontrols.com
Software Release 5.4
2
Win Prep-For Utility Technical Bulletin
Win Prep-For Utility
Introduction
The Win Prep-For Utility is a Microsoft® Windows® Operating
System (OS) application that replaces the Microsoft Disk Operating
System (MS-DOS) based Prep-For utility. Do not use the MS-DOS
based Prep-For Utility with M5 Workstations. This improved version
can be used with Metasys® Person-Machine Interface (PMI) software
and M5 Workstation projects on computers running Windows 2000
Professional OS and Windows XP Professional OS software. Along
with typical M5 Workstation configurations, the Win Prep-For Utility
also supports Metasys system Web Access (MWA) and M-Alarm
Multimedia Extensions (MMX). The Win Prep-For Utility allows a
user to maintain multiple M5 Workstation project contracts on a single
computer and allows switching from one contract to another on the
same device.
This document describes how to:
•
switch between contract databases residing on the same system
•
create the first project contract on a branch workstation or laptop
•
create a new contract on a branch workstation or laptop
•
load a customer’s machine with a contract created on a branch
workstation or laptop
Win Prep-For Utility Technical Bulletin
3
Key Concepts
Theory of Operation
The Win Prep-For Utility allows you to switch between different M5
and Metasys PMI contract databases by updating the proper Windows
operating system environment variables and related project
initialization (INI) files and registry settings. The main distinction
between contracts is the path to the data files for each contract. The
utility also allows you to compile one or more Data Definition
Language (DDL) files during the switch operation.
When a Metasys PMI job is first installed, the Building Automation
System (BAS) environment variables point to a default directory
location (C:\FMS\DATA). Similarly, when an M5 job is first installed,
the M5 INI and registry settings point to a default directory location
(C:\Documents and Settings\All Users\Johnson Controls\M-Data).
When an M5 or Metasys PMI job is generated at the branch, the
location of the database is usually stored under a project contract
number directory scheme (for example, C:\PROJECT\CONTRACT#).
When both Metasys PMI and M5 are used on the same job, the
location of the databases is located under the same project contract
number. The M5 database is contained within an M-Data subdirectory
under the project contract directory.
When a job’s database is loaded on the customer’s system, Prep-For
must be run to change the database pointers to the project contract
number path that holds the database. Once the new path is set,
Prep-For does not need to be run on the customer’s system, provided
that the system has only one database.
4
Win Prep-For Utility Technical Bulletin
Run Win Prep-For in the following situations:
•
on any platform having multiple contracts prior to working with a
new contract, or when changing from one contract to another
•
on any platform having multiple contracts prior to doing any DDL
compiles or Graphic Programming Language (GPL) translates for
a contract
•
once after loading a customer’s computer with a branch-generated
job database, located in a project contract directory
Limitations
The Win Prep-For Utility modifies all environment, initialization
(INI), and registry settings that are required to activate a project
contract. It does not modify path-specific settings found in data files
such as M5 Network Map bindings and Screen Manager Layouts. Any
absolute path-specific settings in these files have to be modified
manually.
To reduce or eliminate the need to make such changes, use the same
project contract names on both the branch machine and the target
customer machine.
Note:
On the Windows 2000 Professional OS and
Windows XP Professional OS, the ampersand (&) character is used as
a separator in command lines. Do not use the ampersand character in
directory or contract names, particularly if you use any of the
MS-DOS based utilities such as DDL or GPL.
For example, the predefined Screen Manager Layouts refer to
documents in relative path format (that is, “...\M-Alarm\Views\alarms
n1 regular view.gdf”) and do not require modification. However, the
M5 Network Map bindings, located in the M-Bind.mdb file, use an
absolute path (for example, “C:\Project\45818058\M-Data\
M-Graphics\Examples\office\2ndfl.gdf”) and have to be changed
manually if the contract folder path is changed.
Win Prep-For Utility Technical Bulletin
5
Detailed Procedures
Switching Between Contract Databases Residing on the Same
System
To switch between contract databases residing on the same system:
1. Shut down all Metasys PMI and M5 applications before running
the Prep-For Utility.
2. On the Windows Start menu, click Programs > Johnson Controls >
Prep-for. The Win Prep-For Utility opens to the Select Project
Contract Folder screen (Figure 1).
Figure 1: Prep-For Utility - Select Project Contract Folder Screen
6
Win Prep-For Utility Technical Bulletin
3. Choose the contract to switch to from the contract drop-down list.
All available contracts under a project folder are listed in the
drop-down list of the Contract field.
Notes:
The current project directory path is automatically
displayed in the Project folder field, located left of the contract
field. If a project folder is not already defined on the machine,
Prep-For defaults to “C:\Project”.
You can select a different project directory by typing directly in
the Project Folder field or by browsing to the appropriate directory
using the Browse button. In most cases, you do not need to select a
different project folder once one has been defined on the machine.
All project and contract folder names are limited to eight
characters in length due to limitations in the Metasys PMI
software. However, the M5 database directories, located in the
‘M-Data’ subdirectory under the project contract folder, are not
restricted by this limitation. That is, only the path up to the contract
folder name has this limitation.
On the Windows 2000 Professional OS, and
Windows XP Professional OS, the ampersand (&) character is used
as a separator in command line commands. Do not use the
ampersand character in directory or contract names, particularly if
you use any of the MS-DOS based utilities such as DDL or GPL.
4. When a contract containing Metasys PMI data is selected, enable
the Perform DDL Compilation option to have Prep-For compile
one or more DDL files. The files are compiled after Prep-For is
finished switching to the selected contract.
Note:
DDL compilations are not normally required when
switching between contracts. The contents of the databases in each
contract are not touched when switching between contracts.
5. Once you are satisfied with the selected options, click Next.
Win Prep-For Utility Technical Bulletin
7
6. If you have selected the Perform DDL compilation option, the next
step allows you to select the DDL files you want compiled
(Figure 2). The DDL files are classified and grouped by DDL type
into four tabs – Network, Global, Model, and NC.
Notes:
Win Prep-For defaults to the DDL directory located
directly under the project contract folder. All DDL files located
under this directory, and all subdirectories of it, are available for
selection. You can change the DDL directory using the Browse
button next to the DDL Directory field. If the DDL directory is
changed, a new list of DDL files is displayed for selection and all
previously selected DDL files are removed from the right pane.
To select a particular DDL file for compilation, select the available
file in the left pane and then click on the Add button. Alternatively,
you can double-click on the DDL file in the left pane.
To remove a DDL file from compilation, select the DDL file in the
right pane and click on the Remove button. Again, you may also
double-click on the file in the right pane.
Figure 2: DDL File Selection
8
Win Prep-For Utility Technical Bulletin
7. Once you are satisfied with the selected files, click on the Next
button to proceed with the verification step.
Notes:
In most cases you do not have to worry about the order
in which the DDL files are compiled. Prep-For automatically
compiles all Network files, then all Global files, Model files, and
finally, all Network Controller (NC) files. If there are any
incremental DDL files (marked with a ‘+’ symbol), each one is
compiled after all other DDL files of its category type are
compiled. If there are two or more selected incremental files in a
particular category, they are compiled in the order in which they
are listed in the right pane.
The DDL compilation stops on the first Network or Global
compilation error. If there are no Network or Global compilation
errors (see Prep-For Non-Fatal Error Messages in this document),
all selected Model and NC DDL files are compiled regardless of
their compile status.
8. The verification step (Figure 3) allows you to review the changes
that will be made by Prep-For. This lists all the steps that will be
performed to switch to the selected contract. Once you are satisfied
with the listed steps, click on the Finish button to proceed.
Otherwise, click on the Back button to go back to any of the
previous steps and make changes.
Figure 3: Prep-For Utility - Verification
Win Prep-For Utility Technical Bulletin
9
Note:
When you click on the Finish button of the verification step,
a dialog appears (Figure 4) warning that you are about to switch
project folder settings.
Figure 4: Prep-For Utility - Switching Project Warning
9. Click on the Yes button to proceed. Click on the No button to go
back to the verification step. The Prep-For Utility runs with the
setting you chose. When the Prep-For process is complete the
Prep-For summary screen appears (Figure 5).
Notes:
During the Prep-For process, the progress status is
displayed in the status dialog. The status is updated as soon as each
step completes. If a problem is encountered during a particular
step, Prep-For notifies you with a message. If you selected one or
more DDL files for compilation, the files are compiled only after a
successful switch is completed.
Figure 5: Prep-For Summary
10
Win Prep-For Utility Technical Bulletin
10. Each DDL file that was compiled is listed in this dialog, along with
the compilation result status. View the details of each DDL
compilation by selecting the DDL file name in the list and then
clicking on the View button. Alternatively, double-click on the file
name in the list. Use Notepad to view detailed results of the DDL
compilation in the corresponding Compiler List File (which has a
DLT extension).
11. After reviewing the results, click the Done button to close the
Prep-For application. If you are using this utility on a
Windows 2000 Professional OS or Windows XP Professional OS,
Prep-For is complete. All necessary environment settings update
automatically.
Creating the First Project Contract on a Branch Workstation or
Laptop
To create the first project contract on a branch workstation or laptop:
Note:
On the Windows 2000 Professional OS and
Windows XP Professional OS, the ampersand (&) character is used as
a separator in command lines. We recommend that you do not use the
ampersand character in directory or contract names, particularly if you
use any of the MS-DOS based utilities such as DDL or GPL.
1. Ensure that all Metasys PMI and M5 applications are shut down
before running the Prep-For Utility.
2. On the Windows Start menu, click Programs > Metasys >
WinPrepFor. The Prep-For Utility opens to the Select Project
Contract Folder screen (Figure 6).
Note: Figure 6 shows Prep-For after installation of Metasys PMI
and M5 in default database directories. Since a project folder has
not been established, the project settings area shows the current
Metasys PMI and M5 data paths. The contract list is empty.
Win Prep-For Utility Technical Bulletin
11
Figure 6: Prep-For Utility - Select Project Contract Folder Screen
3. Choose the location and name of the target project contract folder.
By default, the project folder location is “C:\Project”.
4. Type in the contract number in the Contract field. This can be any
valid MS-DOS filename with a maximum length of eight
characters.
5. Click on the Next to proceed. The Prep-For Utility verification
screen appears (Figure 7).
Note:
Since the new contract does not yet exist, the Perform DDL
compilation field is disabled.
12
Win Prep-For Utility Technical Bulletin
Figure 7: Prep-For Utility – Change Verification Screen
6. Review the changes on the verification screen and, if satisfied with
the changes, click the Finish button. The Prep-For Utility runs.
When finished, the Prep-For complete screen appears (Figure 8).
Note that the DDL status fields in the completion step are disabled.
This occurs when DDL files are not compiled.
Note:
The creation of the initial project contract, or simply the
creation of any new project contract, may take a while to complete.
The length of time taken depends on the performance of your
computer.
Win Prep-For Utility Technical Bulletin
Figure 8: Prep-For Complete
7. Review the results and click Done to close the Prep-For
application. If you are using this utility on a Windows 2000
Professional OS or Windows XP Professional OS, Prep-For is
complete. All necessary environment settings update
automatically.
13
14
Win Prep-For Utility Technical Bulletin
Creating a New Contract on a Branch Workstation or Laptop
To create a new contract directory when you already have one or more
contracts in your project folder.
The current settings displayed by Win Prep-For will be similar to the
first snapshot shown in the first procedure, Switching Between
Contract Databases Residing on the Same System.
Use the following guidelines to create a new contract on a branch
workstation or laptop:
1. Ensure that all related Metasys system and M5 applications are
shut down and launch the Win Prep-For Utility.
2. In the Contract field, enter a new contract number. Follow the
same naming rule that is described in the previous section.
Note:
Since the new contract does not yet exist, the Perform DDL
compilation field is disabled.
3. In the verification step, review the changes that will be made and
then click on the Finish button to proceed.
Loading a Customer’s Machine with a Contract Created on a
Branch Workstation or Laptop
To load a customer’s computer with a contract created on a branch
workstation or laptop:
1. Copy the contract from the branch workstation or laptop to the
project folder on the customer’s machine. You can use removable
media such as a CD-RW, or copy directly using a Local Area
Network (LAN) connection.
2. To make the contract the active project on the customer’s machine,
run Win Prep-For and select the proper project contract.
Note:
It does not matter if the customer’s machine is configured
with the default set of databases, or if the machine already has an
active project contract. The procedure to switch to the new contract is
the same.
Win Prep-For Utility Technical Bulletin
15
Troubleshooting
Error Messages
This section describes the most common error messages encountered
in Prep-For and has two main subsections:
•
Prep-For Fatal Error Messages
•
Prep-For Non-Fatal Error Messages
Prep-For Fatal Error Messages
Any possible error message is displayed in a message box. Fatal errors
are usually encountered by the Windows operating system rather than
Win Prep-For itself. The more common fatal error messages are
encountered when there is not enough disk space to create a new
project or when you do not have proper access rights on the
computer’s Windows NT or Windows 2000 operating system. Always
check to ensure that you have Administrative rights and that you have
enough disk space when you are running Prep-For or creating a new
contract.
Disk Space Error Message
When a disk storage problem is encountered, the Windows operating
system displays a warning message (Figure 9). The format of the
message depends on the version of the Windows operating system you
are using.
Figure 9: Disk Space Error Message
In addition to the Windows operating system specific message,
Prep-For also displays a message to tell you that it cannot proceed. In
this situation, Prep-For only knows that the copy operation has been
canceled or aborted. It does not know that the copy operation has
actually run out of disk space.
16
Win Prep-For Utility Technical Bulletin
Figure 10: Prep-For Unsuccessful Error Message
All files that Prep-For was copying are removed from the target
directory and the process is aborted. Prep-For also displays an abort
message as part of its status in the top part of the completion as shown
in Figure 11.
Figure 11: Prep-For Utility Aborted Message on Completion Screen
Win Prep-For Utility Technical Bulletin
17
Prep-For Non-Fatal Error Messages
DDL Compilation Errors
After Prep-For finishes the switch to an existing contract, it compiles
the selected DDL files. If there are any DDL compile errors, Prep-For
display the warning shown in Figure 12.
Figure 12: Prep-For Unsuccesful DDL Compilation Message
Prep-For also displays the DDL file name with its compilation status
in the status dialog, as shown in Figure 13. View the corresponding
DLT file by selecting the file and clicking View or by double-clicking
the file name.
18
Win Prep-For Utility Technical Bulletin
Figure 13: Prep-For Complete with DDL Status Displayed
Prep-For does not consider DDL compile errors to be fatal and the
selected contract remains active.
Note:
After correcting the original DDL file, you can run Prep-For
again and re-select the currently active project to recompile the DDL
files. Be aware that the settings in the contract will be updated with the
current settings in the environment. This should not make a difference
since the settings should be the same.
Metasys® is a registered trademark of Johnson Controls, Inc.
All other marks herein are the marks of their respective owners.
© 2004 Johnson Controls, Inc.
Controls Group
507 E. Michigan Street
P.O. Box 423
Milwaukee, WI 53201
www.johnsoncontrols.com
Published in U.S.A.