SCC Client Interface User's Guide

ESP Alchemist Version 5.3.1

SCC Client Interface User’s Guide

AL-5.3.1-SCCUG-01 First Edition (October 2005) This edition applies to Version 5 Release 3 Maintenance Revision 1 of ESP Alchemist. The software and related manuals are protected by copyright law.

ESP Alchemist Documentation © Copyright 2000-2005 Cybermation International Distribution SRL All rights reserved. No portion of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by any means without the express written permission of Cybermation International Distribution SRL www.cybermation.com U.S. Government Users. RESTRICTED RIGHTS - Use, Duplication or Disclosure restricted by the GSA ADP Schedule Contract with Cybermation USA, Inc., a subsidiary of Cybermation International Distribution SRL.

Trademark Notice ESP Alchemist is a registered trademark of Cybermation International Inc. Cybermation is a registered trademark of Cybermation, Inc. z/OS and Visual Age for Java are registered trademarks of IBM Corporation. Windows, Visual Studio, and Visual Studio .NET are registered trademarks of Microsoft Corporation. All other brand and product names are trademarks or registered trademarks of their respective companies. Contents

Who should use this guide ...... 2 IDE application developers ...... 2 Alchemist administrators...... 2 Conventions and terminology ...... 2 Related documentation ...... 3 Documentation updates...... 3 1 Using the Installation Wizard 5 Before you start...... 6 Verify software versions...... 6 Gather required information ...... 6 Record this information as you install ...... 7 Installing the Alchemist plug-in and Data Transfer Server...... 7 Installing the software from a CD-ROM...... 7 Installing the software from the Cybermation website...... 7 Configuring the DTS connection to Alchemist...... 7 DTS initialization file syntax and parameters ...... 8 Establishing alternate Alchemist host connections...... 8 Uninstalling the software...... 9 Changing the Default Source-Code Control Provider...... 9 Logging in to Alchemist through the SCC Client Interface...... 10 Login fields ...... 11 Changing your Alchemist password...... 11

AL-5.3.1-SCCUG-01 iii Alchemist change password fields ...... 12 2 Using the Alchemist SCC Client Interface 13 Alchemist function summary...... 14 Using the SCC Client Interface with a standard IDE...... 14 Setting up your project...... 14 Sharing your project...... 15 Adding projects or files to source control...... 22 Checking in files ...... 23 Checking out files ...... 23 Undoing the checkout...... 23 Getting latest version...... 23 Refreshing status ...... 23 Using the SCC Client Interface with VisualAge for Java ...... 24 Setting up your project...... 24 Adding projects to Alchemist ...... 25 Refreshing projects...... 26 Sharing projects in VisualAge for Java ...... 26 Using the SCC Client Interface with Visual Studio .NET...... 27 Setting up your project...... 27 Adding solutions to Alchemist...... 29 Checking out an existing solution for the first time...... 30 Working with an Alchemist-controlled solution...... 30 Checkout on edit ...... 30 Refreshing projects...... 31 Working with previous file versions...... 31 Sharing projects in Visual Studio .NET ...... 31 Changing how Alchemist processes your files ...... 32 3 Basic Concepts in Alchemist 33 SCC API...... 34 What Alchemist does ...... 34 Preserves code assets ...... 34 Manages change ...... 34 Automates builds ...... 35 Zones...... 35 Division by purpose ...... 35 Zone hierarchy...... 35 Files and entities...... 35 Entity lifecycle...... 36 Change Requests...... 36 Entity locking ...... 37 Alchemist Agents...... 37 4 Error Messages 39 Alchemist SCC Client Interface messages...... 40

iv AL-5.3.1-SCCUG-01 Contents

IDE-generated error messages ...... 41 Alchemist Server error messages ...... 41

AL-5.3.1-SCCUG-01 v vi AL-5.3.1-SCCUG-01 About This Guide

The SCC Client Interface User’s Guide explains the concepts behind Alchemist’s organization and its SCC interface. It also describes the actions you carry out in the SCC Client Interface.

AL-5.3.1-SCCUG-01 1 Section–Who should use this guide

Who should use this guide

This guide is intended for application developers who use Alchemist SCC Client Interface to perform source-code control tasks, IDE application developers, and Alchemist Administrators who configure and troubleshoot the interface.

IDE application developers To effectively use the Alchemist SCC Client Interface to perform source-code control tasks, you must be familiar with: • Your Integrated Development Environment (IDE) source-code control conventions • Windows conventions You do not need to be familiar with Alchemist’s user or administrative functions.

Alchemist administrators To effectively use this guide to assist in SCC Client Interface trouble-shooting, you must be familiar with: • Alchemist administrative and user functions • Alchemist operational environment It will also be helpful to be familiar with the Windows operating-system conventions and general IDE source-code-control conventions.

Conventions and terminology

Typographical conventions Convention Usage Bold Indicates a menu item, field name, or other text you see on the screen. Courier Indicates text that you type in a field or on a command line, a path or URL name, or syntax of a command, definition file, or script. italics Indicates variables that you define.

Product terms Term Usage ISPF Interface Refers to the IBM interface to Alchemist. Web Interface Refers to the Web Interface to Alchemist. SCC Client Refers to the Microsoft Source-Code Control API-compliant interface Interface to Alchemist.

2 AL-5.3.1-SCCUG-01 About This Guide

Related documentation

This guide also refers to other Alchemist books: • The ISPF Interface User’s Guide describes Alchemist user operations and the Request Management and Entity Access ISPF panels. • The Administrator’s Reference Guide describes the administrative functions and utilities the Alchemist Administrator uses in Alchemist’s ISPF Interface. • The Installation and Configuration Guide describes how to install and configure Alchemist. • The Planning for Alchemist helps you to plan Alchemist’s installation and customization. This guide includes worksheets you can use to record the configuration options you decide on. • The Process Control Language Guide is a reference for Alchemist’s JCL-based proprietary language. • Messages and Codes is a reference for Alchemist’s error and status codes.

Documentation updates

You can find the most current electronic version of this document, along with the entire Alchemist documentation set, at your Cybermation customer-support website: http://support.cybermation.com.

AL-5.3.1-SCCUG-01 3 Section–Documentation updates

4 AL-5.3.1-SCCUG-01 Using the Installation Wizard

The ESP Alchemist SCC Interface Installation Wizard guides you through installing and configuring the SCC plug-in and the Data Transfer Component (DTS). This chapter describes the installation process and the information the installer prompts you to enter.

AL-5.3.1-SCCUG-01 5 Section–Before you start

Before you start

Verify software versions You must have the following software versions: • Alchemist 5.3.1 or later • SCC-compliant IDE • Windows 98 and later Note: Cybermation tested the Alchemist SCC Client Interface with Windows Visual Studio, Visual Studio.NET, and IBM VisualAge for Java. Because IDEs may integrate SCC implementations differently, other SCC-compliant IDEs may not behave as documented.

Gather required information Before you begin, ensure you have the following information:

ESP Alchemist SCC Client Interface installation parameters Parameter Description Your information User Login ID The Alchemist user ID. It must have access to Alchemist libraries. It is not case sensitive. User Password The password associated with the Alchemist user ID. Zone The name of the Alchemist zone where you want to store the source code. Department The primary security group for your Alchemist user ID. May be optional depending on your Alchemist server configuration. Alchemist IP The ESP Alchemist server IP address. The Address or server IP address may be either in Domain Name hostname or numeric format. It is defined in the Alchemist server. Server Port The ESP Alchemist server IP port number. It is defined in the Alchemist server.

6 AL-5.3.1-SCCUG-01 Chapter 1–Using the Installation Wizard

Record this information as you install During the install, record the paths you specify for the following:

Required directory Default location Your site’s path location information ESP Alchemist SCC C:\Program Client Interface Files\Cybermation\ESP Alchemist SCC Interface DTS Component C:\Program Files\Cybermation\ESP Alchemist SCC Interface\DTS Component

Installing the Alchemist plug-in and Data Transfer Server

Installing the software from a CD-ROM 1. Insert the ESP Alchemist SCC Client Interface CD into a CD drive. 2. Double-click the Setup.exe icon. 3. Follow the instructions in the installation wizard. For descriptions of the fields the Installation Wizard prompts you to enter, see the “ESP Alchemist SCC Client Interface installation parameters” on page 6.

Installing the software from the Cybermation website 1. Connect to your company’s portal on the Cybermation website and navigate to the Alchemist installation location. 2. Double-click the Setup.exe icon. 3. Follow the instructions in the installation wizard. For descriptions of the fields the Installation Wizard prompts you to enter, see the “ESP Alchemist SCC Client Interface installation parameters” on page 6.

Configuring the DTS connection to Alchemist

1. In a text editor, open and edit the DTS initialization file dtsparam.txt. The default location for dtsparam.txt is C:\Program Files\Cybermation\DTS Component.

AL-5.3.1-SCCUG-01 7 Section–Configuring the DTS connection to Alchemist

2. Save your changes.

DTS initialization file syntax and parameters The dtsparam.txt file has the following syntax: localdomain=Machine Name basedomain=lparb baseport=7030 tracepath= trace=no sessions=5 localdomain — The network identification of the Windows computer running the DTS. This name identifies the SCC user in the Alchemist started task log when the SCC user’s associated DTS connects to Alchemist. basedomain — The Alchemist server domain name. It can be either an IP address in dotted-decimal format or a domain name that is converted to an IP address using the domain name server (DNS), for example, 10.1.1.10 or SYSA. baseport — The port number the Alchemist server monitors. This is the same port number specified by the ZSSCITCP DD statement in the JCL for the Alchemist started task. tracepath — The path to the log file the Data Transfer Server (DTS) creates when you enable the trace function. trace — Yes|No Enables or disables the trace function that logs all messages between the DTS and the Alchemist host. sessions — Number of DTS sessions or ports, to reserve. The Alchemist plug-in supports one to five sessions. The default is five. Set this parameter to the expected maximum number of transfers, process executions, and implementations that you may want to start concurrently. If you specify fewer sessions than required, DTS performance can be degraded, but reserving an inadequate number of sessions does not damage any files or cause Alchemist functions to fail. If you specify more sessions than required, the DTS uses more ports than necessary and a little more memory. Usually, you will require three to five sessions.

Establishing alternate Alchemist host connections For each Alchemist host you want to connect to, you need a unique dtsparam.txt file. 1. Make a copy of the DTS Component folder for each Alchemist server and rename them appropriately. You may want to use the DTS Component folder name to identify the Alchemist server it applies to.

8 AL-5.3.1-SCCUG-01 Chapter 1–Using the Installation Wizard

2. Configure the dtsparam.txt file in each DTS Component folder to communicate with a different Alchemist server. 3. Switch between Alchemist servers by clicking Advanced to change the DTS path in the Alchemist Login dialog. This allows you to select the DTS initialization file you want to use.

Uninstalling the software

1. From the Start menu, select Settings > Control Panel > Add/Remove Programs. 2. Select ESP Alchemist SCC Interface and click Change/Remove. 3. Click OK to confirm that you want to uninstall the software, and follow the instructions in the uninstallation wizard.

Changing the Default Source-Code Control Provider

You can have more than one SCC-compliant provider installed on your computer. When you install ESP Alchemist SCC, you can specify whether you want ESP Alchemist to be your default SCC provider. To change the default SCC, you must edit the Windows Registry file: 1. In the Start menu, select Run... 2. In the Open field, type regedit. 3. Navigate to the key, HKEY_LOCAL_MACHINE\SOFTWARE\SourceCodeControlProvider\ InstalledSCCProviders This key lists string values for every SCC provider. Review to ensure that the ESP Alchemist entry is Software\Cybermation\Alchemist. 4. Navigate to the key, HKEY_LOCAL_MACHINE\SOFTWARE\SourceCodeControlProvider The ProviderRegKey entry specifies the default SCC provider. 5. To make Alchemist to be the default SCC provider, enter Software\Cybermation\Alchemist as the value of ProviderRegKey. If you want to change the default SCC provider, enter the value of one of the other providers listed in the InstalledSCCProviders sub-key. 6. In the Registry menu, select Exit to exit the Registry Editor.

AL-5.3.1-SCCUG-01 9 Section–Logging in to Alchemist through the SCC Client Interface

Logging in to Alchemist through the SCC Client Interface

The Alchemist Login dialog appears when you access a project that is under source-code control or when you attempt to perform a source-code control function, such as adding a project to source-code control. Alchemist Login dialog - Advanced functions

To log in to Alchemist and use SCC Client Interface functions 1. Complete the fields of the Alchemist Login dialog. For a description of each login field, see “Login fields” on page 11. 2. Click OK.

To use another DTS to connect to a different server 1. From the Alchemist Login dialog, click Advanced. 2. In the DTS Path field, enter the path to a different DTS or click Browse to locate the DTS component directory to use.

To change your Alchemist password 1. From the Alchemist Login dialog, click Change Password. 2. Follow the on-screen instructions.

To return to the IDE without logging in to Alchemist 1. From the Alchemist Login dialog, click Cancel. A confirmation message appears.

10 AL-5.3.1-SCCUG-01 Chapter 1–Using the Installation Wizard

2. Click OK to confirm that you do not want to log in to Alchemist.

Login fields User Login ID — The z/OS RACF user ID you use to log in to Alchemist. It must have access to Alchemist libraries. It is not case sensitive. User Password — The Alchemist user password. It is not case sensitive. You can change this password by clicking the Change Password button. Zone — The name of the Alchemist zone where you want to store the source code. Department — The primary security group for your Alchemist user ID. May be optional depending on your Alchemist server configuration.

DTS Path — Available when you click Advanced. The path to the Data Transfer Server (DTS) component’s initialization file, dtsparam.txt that you want to use.

Changing your Alchemist password

The Alchemist Change Password dialog appears when you click Change Password on the Alchemist Login dialog. Alchemist Change Password Dialog

This dialog allows you to change your z/OS RACF password as you log in to Alchemist through the SCC Client Interface.

To return to the Alchemist Login page and log in without changing your password From the Alchemist Change Password dialog, click Cancel.

AL-5.3.1-SCCUG-01 11 Section–Changing your Alchemist password

To change your Alchemist password and log in to Alchemist 1. Complete the fields of the Alchemist Change Password dialog. For a description of each login field, see “Alchemist change password fields” on page 12. 2. Click OK.

Alchemist change password fields Current Password — The current Alchemist user password. It is not case sensitive. New Password — The new RACF password Confirm Password — The new RACF password

12 AL-5.3.1-SCCUG-01 Using the Alchemist SCC Client Interface

The SCC API describes how an Integrated Development Environment (IDE) should implement SCC capabilities. However, each IDE may implement the API differently. For example, the SCC tasks may have slightly different names or be located in different menus. The SCC dialogs may also look different, depending on the IDE. Each IDE may also have different settings and options that control how SCC (and therefore Alchemist) is accessed. For example, in Visual C++, you may choose Tools > Options > Source Control to set various default options. For details of how your IDE implements the SCC API, refer to the documentation provided with your IDE. This chapter provides an overview of how a representative IDE (Microsoft Visual C++ 6.0) implements the Alchemist SCC Client Interface. It also shows some highlights of how IBM VisualAge for Java 4.0 and Microsoft Visual Studio .NET interacts with Alchemist’s SCC Client Interface.

AL-5.3.1-SCCUG-01 13 Section–Alchemist function summary

Alchemist function summary

Different IDEs may have different names for the various tasks provided by the SCC Client Interface.

Alchemist function and description Visual Studio VisualAge .NET for Java Add Add to Source Add (for file) or Add Solution to Places a file or project under version control for the Control Add to Version Source Control first time Control (for project) Check In Check In Check In • Check In Updates a previously checked-out file, including filename any changes to the checked-out files • Check In filename Now Undo Check Out Undo Check Out Undo Check Out Undo Checkout Removes locks from a previously checked-out file filename without accepting any changes to the checked-out file

Common tasks for retrieving files from Alchemist Alchemist function and description Visual Studio VisualAge .NET for Java Get Get Latest Not Get Latest Retrieves the latest version of the file without locking Version implemented Version Check Out Check Out Check Out • Check Out Retrieves the latest version of the file and locks it to filename prevent other users from retrieving and editing it. Now • Check Out filename Now Refresh Refresh Status Not Refresh Status Determines the status of every file in the project implemented

Using the SCC Client Interface with a standard IDE

This section describes how to use the SCC Client Interface with a standard representative IDE (Microsoft Visual Studio) and Visual C++.

Setting up your project Either create a new project or open an existing project in your IDE.

14 AL-5.3.1-SCCUG-01 Chapter 2–Using the Alchemist SCC Client Interface

You can specify options that control how your IDE accesses Alchemist. For example, specify whether the SCC Client should automatically add new projects to Alchemist. To set various source-control options, choose Tools > Options > Source Control. Usually, you save a project in a directory with the same name. For example, you can save a project called MyProject on your local disk as C:\Projects\Visual Studio\MyProject. When a project is under Alchemist control, Alchemist saves files belonging to this project with /prefix MYPROJECT/. However, you can also choose to add your files to a project that already exists in Alchemist.

Sharing your project This section describes how to share a standard IDE project and how to share a standard Visual C++ project. Sharing the project with Alchemist puts your files under Alchemist’s source-code control.

Sharing standard IDE projects When you first try to place a project under source-code control by adding it to Alchemist, the Alchemist Project dialog appears.

AL-5.3.1-SCCUG-01 15 Section–Using the SCC Client Interface with a standard IDE

Specify whether you want to create a new project in Alchemist or associate your local project with a project that already exists in Alchemist. You can also delete any existing projects in Alchemist.

To create a new project in the Alchemist zone you specified on login 1. In the Alchemist Projects dialog’s New project name field, ensure that the project name is correct. 2. To specify the new project’s hierarchy, click on the plus sign (+) and navigate to the Alchemist project under which you want to create a new subproject. 3. Select the Alchemist project under which you want to create a new project. 4. Click Create. The name of the project is added to the list of existing projects. 5. Click OK.

16 AL-5.3.1-SCCUG-01 Chapter 2–Using the Alchemist SCC Client Interface

To add files to an existing project 1. From the Alchemist Projects dialog, clear the contents of the New Alchemist project field. 2. Click the plus sign (+) in the Existing projects pane and navigate to the project under which you want to add the new files. 3. Select the project name under which you want to add the files and click OK. The Alchemist Add to “zonename” zone dialog appears.

4. From the drop-down list, select the entity type you want to associate with the file.

AL-5.3.1-SCCUG-01 17 Section–Using the SCC Client Interface with a standard IDE

5. Choose to apply the same entity type for all files or select an entity type for each file. If you click Use the same type for all files, then from the drop-down list select an entity type. Proceed to the step 7. If you click Select a type for each file, then click the button to the right of that selection. The Select a type for each item dialog appears.

6. Click to the right of each file name and from the drop-down list, select an entity type to apply to that file. Click OK. 7. To add comments to associate with this file version, click Comments. The dialog expands to include a Comments section. Click OK.

To check-in files to an existing project 1. From your IDE, select the files to check-in and choose your check-in function. The Check in to “zonename” zone dialog appears.

2. To add comments to associate with this file version, click Comments. The dialog expands to include a Comments section. Click OK.

18 AL-5.3.1-SCCUG-01 Chapter 2–Using the Alchemist SCC Client Interface

To view or change a file’s Alchemist properties Note: If you change a file’s entity type, the Alchemist Client treats it as a new file. You must add it to Alchemist source-code control.

File is under Alchemist’s control 1. From your IDE, select the file whose properties you want to view. 2. Choose your IDE’s properties function. If the file is Alchemist source-code controlled, the Alchemist properties dialog appears.

On the Alchemist properties dialog you can view the file’s attributes. Local location — The path to your file on your computer. Alchemist entity name — Alchemist’s entity name includes the Alchemist project you assigned to your local project and the filename. Alchemist entity type — The entity type you assigned to the file. The entity type determines how Alchemist processes your file; such as how many versions to maintain in the archive, locking features, and access and build control. Zone name — The Alchemist zone where Alchemist stored your file. CC Reference — The change-control reference number that Alchemist uses to uniquely identify this file’s version.

AL-5.3.1-SCCUG-01 19 Section–Using the SCC Client Interface with a standard IDE

3. To change the file’s entity type, click Change. The following dialog appears.

4. From the drop-down list, select the entity type that Alchemist uses to control your file. Click OK.

File is not yet under Alchemist’s control 1. From your IDE, select the file whose properties you want to view. Choose your IDE’s properties function. The following dialog appears.

Before you add the file to Alchemist source control, you can set the entity type. This entity type appears as the default when later you add the file to Alchemist. You can also change the entity type when adding a file to Alchemist.

20 AL-5.3.1-SCCUG-01 Chapter 2–Using the Alchemist SCC Client Interface

2. Click Set Alchemist Type to choose an entity type for your file. The following dialog appears.

3. From the drop-down list, select the entity type that you want Alchemist to use to control your file. Click OK.

To delete the project name from the project list 1. From the Alchemist Projects dialog, click the plus sign (+) in the Existing projects pane and navigate to the project you want to delete. 2. Select the project name you want to delete and click Delete. A confirmation message appears. 3. Click Yes. Note: This does not remove the project files from Alchemist. To delete the files on the Alchemist server, you need to generate a delete Change Request from either the ISPF or Web Interface. For more information on creating Change Requests, see the ISPF Interface User’s Guide or Web Interface User’s Guide. For detailed information about project sharing in different IDEs, see “Sharing Visual C++ projects” on page 21, “Sharing projects in VisualAge for Java” on page 26 or “Sharing projects in Visual Studio .NET” on page 31.

Sharing Visual C++ projects In Visual C++ and other Visual Studio products, the project file (.dsp) stores information about the project, such as whether or not the project is under source-code control, the source files included in the project, and compilation options. This file should be stored in Alchemist, and shared between all developers who want to add or maintain files in the project. Before you can start sharing a project, one user should create the project and add the project and all its files to Alchemist using the SCC Client Interface. He should then distribute the .dsp file to other users who want to share the project. Once you receive the .dsp file, save it in a new folder on your workstation and open it. You can then get the latest version of it and the other project files from Alchemist.

AL-5.3.1-SCCUG-01 21 Section–Using the SCC Client Interface with a standard IDE

Retrieving a project saved in Alchemist to your local workstation 1. In Visual C++, open the .dsp file. The Alchemist login prompt appears. 2. Log in to Alchemist. Visual C++ opens the project and lists all the files belonging to the project in the FileView pane. 3. In the FileView pane, select all the files belonging to the project. 4. In the Project menu, select Source Control > Get Latest Version. The Get Latest Version dialog appears. 5. Click OK. Alchemist transfers and saves the latest checked-in version of the every project file to your local disk. You can now start updating the project. Note: Only one person at a time can check a file out for editing. For more information, see “Entity locking” on page 37.

Adding projects or files to source control Before you can use the source-control functions, you must add your project to source control. Add all the files included in the project (such as C++ source files and resource files), as well as files that define the project (such as .dsp files). You can specify whether the files you are adding to Alchemist should remain checked out so you can continue editing them. You must also specify the entity type. You can add comments to the files if you want. Adding a file to source control creates a new entity in Alchemist. The entity name consists of the project name and file name. For example, adding a file Hello.cpp in project MyProject to source control creates an entity named \MYPROJECT\HELLO.CPP in the Alchemist zone specified on login. When you add a project to source control for the first time, the Alchemist Projects dialog appears where you select an existing project or add a new project. Once you choose the Alchemist project you must choose the entity type to control how Alchemist processes the entity. For more information about this dialog and project sharing in Alchemist, see “Sharing standard IDE projects” on page 15. To delete an entity from Alchemist, or remove a project from Alchemist source control, you must use the Web or ISPF Interface.

22 AL-5.3.1-SCCUG-01 Chapter 2–Using the Alchemist SCC Client Interface

Checking in files Checking in a file adds an updated version of it to Alchemist. It replaces the version of the file currently stored in Alchemist. If you checked in and don’t choose to check it out immediately, other users can check it out and edit it. The file must exist in Alchemist before you can check it in. Use the Add function to add a file to Alchemist for the first time. You cannot undo the check-in using the SCC Client Interface with Visual Age for Java and Visual C++. For those applications, restore an earlier version of the file by creating a Change Request using the Web or ISPF Interface. Note: You can restore a previous version using the SCC Client Interface with Visual Studio .NET.

Checking out files Checking out a file retrieves the selected file’s latest version to the IDE workspace and locks it to prevent it from being checked out by another user. You can checkout a single file or multiple files at a time. If the file exists in the zone specified, Alchemist retrieves it from that zone. Otherwise, Alchemist searches for the file in other zones in the zone hierarchy by the file’s entity type. For more information, see “Zone hierarchy” on page 35.

Undoing the checkout Undoing the checkout achieves two purposes: • Retrieves the latest checked-in version of the file and backs out any changes to the entity you may have made since last checkout • Removes the locks on the selected file so that other users can checkout the file

Getting latest version Getting the latest version retrieves the latest version of the selected file to the IDE workspace without obtaining a lock. This means that the file is available to other users for checkout.

Refreshing status The file’s status indicates whether the entity is locked by a user and is displayed by a graphic next to the file or project name. The status of the file is also shown in its properties. To see file properties in Visual C++, right-click on the file name and select Properties.

AL-5.3.1-SCCUG-01 23 Section–Using the SCC Client Interface with VisualAge for Java

Using the SCC Client Interface with VisualAge for Java

IBM VisualAge for Java uses its External Version Control tool for implementing various source-code control options, including the SCC API. Read this section to understand the major differences between the VisualAge for Java implementation of the SCC API and the standard implementation described previously. For detailed information about using the External Version Control tool, refer to your VisualAge for Java documentation. Detailed task and concept information is available in the online help and in the External Version Control guide in PDF format. In addition, an External Version Control white paper is available on the IBM website for VisualAge for Java for Version 3.5 and for Version 3.5.3. Note: The Remove from Version Control and Delete commands, which are displayed in the External Version Control menu, are not implemented in the SCC Client Interface. You cannot use these commands from VisualAge for Java. You must use the Web or ISPF Interface instead to accomplish these functions.

Setting up your project

Setting version-control properties

To view or change version-control properties 1. In the Workbench, select the project, package or type whose properties you want to work with. 2. From the pop-up menu, select Tools > External Version Control > Properties. The Properties window opens. 3. Click the various tabs in the window and change the field values that display if necessary. For more information on each tab, press F1.

Activating the Remote Access to the Tool API You must activate the Remote Access Tool API before you can use the SCC Client Interface. You can have the Remote Access server active whenever you open VisualAge for Java.

To activate the Remote Access server on VisualAge Startup 1. In the Window menu, select Options. 2. Select Remote Access to Tool API. 3. Select the Start Remote Access To Tool API on VisualAge Startup option.

24 AL-5.3.1-SCCUG-01 Chapter 2–Using the Alchemist SCC Client Interface

Note: If you do not set this option, you must activate the server every time you open VisualAge for Java, before you can log in and use the SCC Client Interface. 4. Click Start Remote Access To Tool API to activate the Remote Access server immediately. 5. Click OK to exit the Options dialog.

To activate the Remote Access server 1. In the Window menu, select Options. 2. Select Remote Access to Tool API. 3. Click the Start Remote Access To Tool API button. 4. Click OK to exit the Options dialog.

Choosing the working directory Choose a working directory for your project before using the SCC Client Interface. Checking in a file will export the class to a .java file and add it to Alchemist.

Adding projects to Alchemist Add the project to Alchemist before adding classes and other files belonging to the project to Alchemist. If multiple version-control systems are installed on your computer, specify that your IDE should use the SCC Client Interface as the source-control software for the project when you first add a project to source control. Also, choose the working directory.

To select the source-control software and working directory for a project 1. Right-click the project name and select Tools > External Version Control > Add to Version Control. If more than one source-control system is installed on your computer, an Add to Source Control dialog appears requesting you to select a source-code management handler. 2. Select Microsoft SCCI and click OK. If more than one SCC-compliant source-control system is installed on your computer, the Select SCM System dialog appears. 3. Select Alchemist and click OK. The Alchemist Projects dialog appears.

AL-5.3.1-SCCUG-01 25 Section–Using the SCC Client Interface with VisualAge for Java

4. Specify the name for your project and whether it is new or already exists in Alchemist. Click OK. The Alchemist Add to “zonename” zone dialog appears. 5. From the drop down menu next to Select and Alchemist entity type, select the appropriate entity type for your file. The entity type determines how Alchemist controls and processes your file. 6. Click OK. The Select Local Directory dialog appears. 7. Navigate to the working directory and click OK. The Add to Version Control SmartGuide appears. 8. Complete the Add to Version Control SmartGuide and other VisualAge for Java dialogs as required.

Refreshing projects In the SCC API as implemented in Visual Studio, there are two distinct functions: • Get retrieves the latest version of a single file or the entire project from Alchemist without locking it • Refresh Status updates the status for each file in the project to reflect the status in Alchemist. There are no equivalent functions in VisualAge for Java. VisualAge for Java has a Refresh Project function, which does not interact with Alchemist, but merely imports files from the working directory. To ensure that you have the latest version of the files stored in Alchemist, use the Check Out function.

Sharing projects in VisualAge for Java For VisualAge for Java, only the source files (such as .java files) are stored in Alchemist. Project-level information (such as which files are in a project) is stored locally on your personal computer, and cannot be shared through Alchemist. You must share this information in other ways. Before you can start sharing a project, one user should create the project and add the project and all its files to Alchemist using the SCC Client Interface. He should then inform other users about the name of the project, and which files are in the project. Once you know this information about a project, you can create an equivalent dummy project in your local VisualAge for Java workspace. Then you can get the latest version of the project files from Alchemist.

26 AL-5.3.1-SCCUG-01 Chapter 2–Using the Alchemist SCC Client Interface

Recreating an Alchemist project in your VisualAge for Java workspace 1. Open VisualAge for Java. 2. Add a new project to your workspace. You can give the project the same name as the project stored in Alchemist, but this is not necessary. 3. For every class or resource file that exists in the Alchemist version of the project, add a new class or file with the same name to the project in your workspace. The other attributes of this class or file are irrelevant to Alchemist. 4. To add the project and its classes and resource files to version control, in the Existing Projects field of the Alchemist Projects dialog, select the name of the project you want to recreate, and click OK. At the end of the process of adding files to Alchemist source control, a VisualAge for Java message appears stating that files will be added to source control. 5. Click OK. An Alchemist message appears stating that the entities already exist in Alchemist and will not be added. 6. Click OK. VisualAge for Java is now aware that these files are under source control. 7. After the files have been added to Alchemist, check them out. This ensures that you have the latest version of the files in your workspace. You can now start updating the project. Remember that only one person at a time can check a file out for editing. Note: If you add new classes or resource files to the project, ensure that you inform other users sharing this project.

Using the SCC Client Interface with Visual Studio .NET

The following instructions apply to Visual Studio .NET 2003. Subsequent versions of Visual Studio .NET may implement source control differently.

Setting up your project

Setting source-control properties In Visual Studio .NET’s source-control properties, you can select some timesaving functions such as Get everything when a solution is opened and Check in everything when a

AL-5.3.1-SCCUG-01 27 Section–Using the SCC Client Interface with Visual Studio .NET

solution is closed. You can also specify what the Alchemist SCC Client Interface should do when you try to edit a locked file.

To view or change version-control properties 1. From the Solution Explorer, right-click the solution whose properties you want to work with and select Tools > Options. .NET displays the Options window. 2. Click the Source Control folder to access General or SCC Provider options. 3. Click General or SCC Provider to review or change the values if necessary. For more information on these options, press F1.

Understanding source-control graphics

When you add a solution to Alchemist’s control, Visual Studio .NET displays a graphic next to the projects and files. To find out the status of a project or file, hover your mouse over the file. A message appears that indicates the file’s status. The following table describes some of the symbols that display next to your projects and files when they are under Alchemist’s control.

Symbol Description • The solution is under Alchemist’s control. • You can obtain a lock (checkout exclusively) for some of the files in the project. • The application is under Alchemist’s control. • Some of the files in the application have been checked out.

28 AL-5.3.1-SCCUG-01 Chapter 2–Using the Alchemist SCC Client Interface

Symbol Description • The file is under Alchemist control. • You do not have a lock for it. • The file is read only. • The file is checked out exclusively by someone else or in another place.

• You have checked out this file. • You have changed the file since you last checked it into Alchemist.

Adding solutions to Alchemist When you choose to add a solution to Alchemist, the Alchemist SCC Client Interface adds all project files to Alchemist and duplicates Visual Studio .NET’s directory structure in the Alchemist zone. Note: To move files (entities) from one zone to another, use either the Alchemist ISPF or Web interface. For more information on creating Change Requests to upgrade an entity, see the ISPF Interface User’s Guide or Web Interface User’s Guide.

To add a new solution to Alchemist 1. Right-click the solution name. A pop-up menu appears. 2. Select Add Solution to Source Control. The Alchemist login dialog appears. 3. Log in to Alchemist. The Alchemist Projects dialog appears. 4. From the list of projects, select the name for your project or create a new project and click OK. The Add to Zone dialog appears. 5. Select the entity type for your project files and click OK. Visual Studio .NET adds to and checks out a .NET system file from Alchemist. Once Visual Studio .NET completes this process, the Alchemist SCC Client Interface adds all the selected solution’s files and folders to Alchemist. If you want to exclude a file from source control, right-click the file name and select Exclude filename from Source Control.

AL-5.3.1-SCCUG-01 29 Section–Using the SCC Client Interface with Visual Studio .NET

Checking out an existing solution for the first time If you need to work on a solution that has already been added to Alchemist and you do not have those files on your computer you can open the solution from Alchemist. 1. Select File > Source Control > Open From Source Control. The Alchemist Login dialog appears. 2. Log in to Alchemist The Alchemist SCC Client Interface lists the existing projects under Alchemist’s control. 3. Select the project you want to work with and the location where you want to store the project on your computer. 4. The Alchemist SCC Client Interface downloads the project files from the Alchemist server. Visual Studio .NET updates the file graphics in the Solution Explorer to reflect whether the file is read only but available for you to checkout, or whether another user. has checked out the file for exclusive use. 5. Checkout the files you want to work with.

Working with an Alchemist-controlled solution You can use Visual Studio .NET’s source-control options to automatically get the files from Alchemist when you open a solution. If you automatically get the server’s version of the file, you will always have the most up-to-date version. If you choose not to use this option, you can open the solution and manually checkout the files you want to work with.

To checkout individual files 1. Right-click the file you want to open and select Check Out Now. The Alchemist Login dialog appears. 2. Log in to Alchemist You can replace your local file with Alchemist’s version or leave your local file as is.

Checkout on edit Once you add your project to Alchemist, the files are read only and appear with lock icons next to their names. If you try to edit a locked file, Visual Studio .NET looks to

30 AL-5.3.1-SCCUG-01 Chapter 2–Using the Alchemist SCC Client Interface

the source-control properties to determine what to do next. You can set the checkout properties to perform one of the following actions when you try to edit a locked file: • Prompt for check out • Prompt for exclusive checkouts • Check out automatically • Do nothing

Refreshing projects In the SCC Client Interface as implemented in Visual Studio .NET, there are two distinct functions: • Get retrieves the latest version of a single file or the entire project from Alchemist without locking it. • Refresh Status updates the status for each file in the project to reflect the project’s status in Alchemist.

Working with previous file versions Each time you check-in a file, Alchemist creates a new version and archives the older version. The number of file versions Alchemist tracks depends on how the Alchemist Administrator defined the entity type you associated with a particular file. At any time you can view the file’s contents, comments, and creation date. To work with archived file versions, select File > Source Control > History from the Visual Studio .NET menu. You can view, compare, and restore previous file versions. For more information, see your Visual Studio .NET user documentation or press F1.

Sharing projects in Visual Studio .NET For Visual Studio .NET, only the source files (such as .java files) are stored in Alchemist. Visual Studio .NET stores project-level information (such as which files are in a project) on your personal computer and you cannot share them through Alchemist. You must share this information in other ways. Before you can start sharing a project, one user should create the project and add the project and all its files to Alchemist using the SCC Client. He or she should inform other users about the name of the project and which files the project contains. Once you know this information about a project, you can create an equivalent dummy project in your local VisualAge for Java. Then you can get the latest version of the project files from Alchemist.

Recreating an Alchemist project in your VisualAge for Java workspace 1. Open Visual Studio .NET. 2. Add a new project to your workspace. You can give the project the same name as the project stored in Alchemist, but this is not necessary.

AL-5.3.1-SCCUG-01 31 Section–Using the SCC Client Interface with Visual Studio .NET

3. For every class or resource file that exists in the Alchemist version of the project, add a new class or file with the same name to the project in your workspace. The other attributes of this class or file are irrelevant to Alchemist. 4. To add the project and its classes and resource files to version control, in the Existing Projects field of the Alchemist Projects dialog, select the name of the project you want to recreate and click OK. At the end of the process of adding files to Alchemist source control, Visual Studio .NET displays a message stating that files will be added to source control. 5. Click OK. An Alchemist message appears stating that the entities already exist in Alchemist and will not be added. 6. Click OK. VisualAge for Java is now aware these files are under source control. 7. After you add the files to Alchemist, check them out. Checking the files out ensures you have the latest version of the files in your workspace and prevents other users from simultaneously updating the files. You can now start updating the project. Remember that only one person at a time can checkout a file for editing. Note: If you add new classes or resource files to the project, ensure you inform other users sharing this project.

Changing how Alchemist processes your files The entity type you associate with a file determines how Alchemist controls the file. The entity type control attributes such as whether you can checkout the file in an emergency, what information you must specify to checkout a file, and how many file versions Alchemist archives.

To change a file’s entity type 1. Checkout the file you want to associate with another entity type. 2. Right-click the file you want to change and select Properties. The Alchemist Properties dialog appears. 3. Click Change and select another entity type from the drop-down list. 4. Click OK.

32 AL-5.3.1-SCCUG-01 Basic Concepts in Alchemist

Alchemist is a change-management system that you can access through an ISPF, Web, Line Mode, Eclipse Client or an SCC Client Interface. You can integrate the Alchemist SCC Client Interface with many Windows-based IDEs. To understand how to use the SCC Client Interface to store and maintain source code, you must understand its structure and learn some of its terms. This chapter also explains the ideas that govern the organization of an Alchemist environment and the processes that affect files in that environment, as they apply to the SCC Client Interface. This chapter is aimed at experienced IDE users who are not familiar with Alchemist.

AL-5.3.1-SCCUG-01 33 Section–SCC API

SCC API

The Microsoft Source Code Control API (SCC API) is the common interface specification that allows source-code control systems to be integrated with various development tools. This interface allows different version-control systems, such as Alchemist, to work with different development environments, such as Microsoft Visual C++ or IBM VisualAge for Java. The Alchemist SCC Client Interface is the interface to the Alchemist server from your IDE. It is compliant with the SCC API.

What Alchemist does

Alchemist is a change-management and automated build-processing program. It structures and automates the processes by which files are managed and compiled.

Preserves code assets Designed to preserve code at every stage of its development, Alchemist manages both source and build information in its system. It keeps: • Records and copies of each code asset in its libraries • Libraries of compiled code and all references to source code for each build By automatically keeping track of a software component’s source and history, Alchemist guards against loss caused by system failure, tampering, or human error.

Manages change Alchemist provides an automated process for submitting and recovering code: • When you want to change any information in the system, Alchemist supports the approval workflow for this change. • When you want to reverse a change to any information, Alchemist restores it. Once code has been submitted through Alchemist, it is automatically included in new build processes for all the programs it affects. Note: This functionality is unavailable through the SCC Client Interface. It can only be done through the Web or ISPF Interface.

34 AL-5.3.1-SCCUG-01 Chapter 3–Basic Concepts in Alchemist

Automates builds In addition to storing source code, Alchemist automates programming processes, like builds and binds. To facilitate an automated build, Alchemist can: • Associate a particular software type with the appropriate jobs • Schedule these jobs on a timer or on the basis of trigger processes Alchemist stores all code and controls job processes through configured facilities in its environment. Note: This functionality is unavailable through the SCC Client Interface. It can only be used through the Web or ISPF Interface.

Zones

Alchemist moves code assets in and out of a virtual location called a zone. A zone is a logical group of files on a machine or network that only Alchemist has the authority to change.

Division by purpose In a zone, Alchemist stores codes assets for a specific purpose, like code development, code testing, quality assurance, or production. When a purpose has been achieved, for example, once a code asset has finished quality assurance testing, an Alchemist Change Request can be released to move the selected asset to another zone. When using the SCC interface your development zone should be set up as a “check-in only” zone. It provides an environment for developers to check in and out entities, but does not provide any automated build procedures. This ensures that your developers are provided with optimum performance in their day-to-day development activities.

Zone hierarchy Zones can be organized into a hierarchy. Where a quality assurance zone and production zone exist, the production zone is considered the highest point in a hierarchy. When a user transfers a software component from a development zone to a production zone, the user promotes it. A move from a production zone to a development zone retrieves a code asset.

AL-5.3.1-SCCUG-01 35 Section–Files and entities

Files and entities

Alchemist stores each data or code asset in its source libraries as an entity. The entire change management and automation process is based on moving and processing entities. When you submit an entity to Alchemist, you assign two important attributes: • Entity Name — An alphanumeric identifier that labels a software component, distinguishing it from all in others in the same zone, library, and node. If the Entity Name is not unique to the entire zone, Alchemist does not share the entity across zones. For entities added to Alchemist through the SCC Client Interface, the entity name consists of the project name and the file name. • Entity Type — An attribute that determines how Alchemist processes the entities of each type. The Alchemist Administrator defines the Entity Type Definition (ETD) on the server. Each ETD entry in the ETD file also controls how Alchemist transfers files between Alchemist Agents and other networked systems, compiles and builds source code, and stores the resulting code at a specific location Alchemist Agents can access. For more information on Agents, see “Alchemist Agents” on page 37. Each zone has a set of ETDs. If the ETD entry for an entity is not defined or not correctly defined, Alchemist does not load the entity into the zone. Together, these two attributes govern how Alchemist manages an entity.

Entity lifecycle Once you add an entity to a zone in Alchemist, it begins its lifecycle. An entity’s lifecycle involves being: • Superseded by newer versions of itself • Implemented into a load module • Promoted to the next zone in a hierarchy You can only use the SCC Client Interface to put an entity into Alchemist and then supersede this entity. You must use the ISPF or Web Interface to implement the entity into a load module or to promote an entity. When you use the SCC Client Interface, you can build source code using your IDE and then store the load module in Alchemist. Once you promote an entity, it begins the lifecycle all over again until it is finally implemented in production. Change Requests drive this lifecycle to its completion.

36 AL-5.3.1-SCCUG-01 Chapter 3–Basic Concepts in Alchemist

Change Requests

To change entities using the Alchemist’s ISPF or Web Interface, you submit an electronic requisition, hence the name Change Request. When you are using the SCC Client to check-in entities, the entities are placed directly into the Alchemist repository in your “check-in only” zone. No change request is created, therefore this zone cannot have target files or automated build procedures associated with the entities. Target files and automated build procedures would be defined in the higher zones and be applied when the entities are promoted from the “check-in only” zone to a higher zone. A Change Request in the Web or ISPF Interface can • Add entities to Alchemist • Delete entities from Alchemist • Move entities to a higher zone (promote entities) Retrieving stored entities does not alter entities in the Alchemist system, so it is not accomplished through a Change Request. Instead, each entity retrieval is recorded in the Zone Control Library (ZCL). One ZCL exists for each zone and contains an updated version of every uncompiled piece of source code.

Entity locking Alchemist uses entity locking to prevent two different developers from inadvertently retrieving and concurrent modify the same entity, each unaware of the other’s actions. This situation could occur if separate development teams are allocated individual projects and two concurrent projects require changes to the same program. The entity-locking feature can be selected or inhibited for different types of entities in different zones for ISPF and Web Interface users. For SCC Client Interface users, entity-locking is always enabled. Only one person can checkout an entity at a time using the SCC Client.

Alchemist Agents

The Alchemist Agent is a Java program that runs on Windows and UNIX. It allows Alchemist to initiate and control entity software builds (by compilation or make/link) on the Agent platform.

AL-5.3.1-SCCUG-01 37 Section–Alchemist Agents

The Alchemist Agent encompasses the following components and functionality: • The Process Execution engine executes user-supplied scripts, such as UNIX, Java, Perl or Windows scripts the Alchemist Administrator specified in the ETD of the entity being built on the Agent platform. • The Data Transfer Server (DTS) transfers files between Alchemist and an executing build process. The DTS also receives and distributes TYPE(COPY) target files Alchemist automatically creates as an exact copy of the entity input source. Using the DTS, Alchemist can also transfer entity source that does not require a build process directly into the staging area on the build machine. • The Version Transition Server (VTS) manages how Alchemist implements new entity versions and archives their predecessors. The Alchemist administrator configures build management using the ETD PROCESS parameter. This parameter calls PCL procedures that allow Alchemist to execute processes that control the build on UNIX and Windows platforms. ETD parameters also control how Alchemist transfers files between the Agent and other networked systems, compiles and builds source code, and stores the resulting code at a specific location the Agent can access. For more information on the ETD, see the Installation and Configuration Guide. For more information on Alchemist Agents, see the ESP System Agent R6.1 Administrator’s Guide.

38 AL-5.3.1-SCCUG-01 Error Messages

There are three types of error messages you may encounter when using the Alchemist SCC Client Interface: • Messages generated by the Alchemist SCC Client Interface. • Messages generated by the host IDE. • Messages generated by the Alchemist server. This chapter explains them and suggests solutions. This chapter is intended for both IDE developers and Alchemist Administrators.

AL-5.3.1-SCCUG-01 39 Section–Alchemist SCC Client Interface messages

Alchemist SCC Client Interface messages

You may encounter the following messages when attempting to log in to Alchemist or use Alchemist functions through the SCC Client Interface.

Error Message Description/Solution Entity not found in There is a problem connecting with the Alchemist server. Ensure Alchemist. that the Alchemist server is active and try connecting again. Alchemist is unavailable. Ensure that • The correct Alchemist IP address is entered in the Server IP field. • The Alchemist server is active. Alchemist login was canceled. You can continue using the IDE, but you will not be connected to Alchemist. If you want to perform an Alchemist SCC function, exit the IDE and try to log in again. Alchemist SCC operation has You are not logged in to Alchemist. Log in to Alchemist, and try not been performed. to perform the function again. Entity entityName already If you are trying to update an entity that already exits in exists in Alchemist. This Alchemist, use the check-in function. entity will not be added. Otherwise, ensure that the project and file names are unique. Password has expired. Click Change Password to change your Alchemist password, and log in again. New password and Re-enter the new password in the New Password and Confirm confirmation password do not Password fields. match. entityname is already locked. This entity has already been checked out. Only one user at a time can checkout an entity. This entity must be checked in before you can check it out. The zonename zone is not The Alchemist zone specified on login has not been defined on defined in Alchemist. Contact the Alchemist server. For more information, see the Installation your Alchemist administrator and Configuration Guide. for the correct zone name. The entitytype type is not The Alchemist server is not properly configured for this entity defined in Alchemist. Contact type. For more information, see the Installation and your Alchemist administrator. Configuration Guide. entityname is not locked. You can only undo the checkout of entities that are currently checked out. This entity is not currently checked out.

40 AL-5.3.1-SCCUG-01 Chapter 4–Error Messages

IDE-generated error messages

Each IDE can integrate the SCC Client Interface differently, and may also have different settings and options that control how SCC (and therefore Alchemist) is accessed. You may encounter error messages generated by your IDE while using Alchemist’s SCC Client Interface. For example, when using VisualAge for Java, you must connect to the remote access server to use the SCC API. If you do not connect to the server before trying to log in to Alchemist, you will receive the error message: “The Remote Access Server is down. Start the Remote Access Server from the Options dialog and try again.” Messages like this are generated by the IDE (in this case, VisualAge for Java) and not by the SCC Client Interface. You should refer to the documentation provided with your IDE for help in dealing with these errors.

Alchemist Server error messages

When a communication between the SCC Client Interface and the Alchemist server fails or completes with errors, Alchemist issues an error message. Each message contains an identifier and a description that indicates the nature of the failure. Alchemist server error message identifiers consist of: • An alphabetic prefix that classifies it in a particular class of messages. This prefix is either ZDE or a four-letter alphabetical prefix starting with the letter Z. • A unique numeric message identifier. It is either a four-digit number, for ZDE messages, or a three-digit number for other Alchemist error messages. Alchemist error codes are cataloged in Messages and Codes. To interpret any error from this subset of errors, look up the error code in this book.

AL-5.3.1-SCCUG-01 41 Section–Alchemist Server error messages

42 AL-5.3.1-SCCUG-01