This chapter describes the installation of the TP Desktop Connector client services and samples for Apple Macintosh clients.

After you install the TP Desktop Connector Gateway for ACMS software on the DIGITAL OpenVMS system, you can install the TP Desktop Connector client services software on individual desktop systems.

7.1 Macintosh Installation Options

You can choose any of several installation options depending on the type of services you want to install on the target Macintosh:

• Run-Time Services option
  Permits the execution of TP Desktop Connector client applications, but does not include files that are helpful for developing new applications. You can install Run-Time Services with or without the Calypso Tool, which provides support for dialin applications to the host ACMS Desktop server. Choose this option (with or without Calypso) if you do not intend to develop new TP Desktop Connector applications on the target Macintosh.
• System Services option
  Includes the Run-Time Services plus a set of files that aids in the development of new TP Desktop Connector client applications on the target Macintosh. This option does not include the various examples that illustrate the use of the TP Desktop Connector client services. Choose the System Services option if you do not require the assistance of the examples, and want to conserve the disk space that the examples occupy.

• Examples option
  Includes the following:
  • Sample applications written in 4th Dimension, HyperCard, and C.
  • Two sets of 4th Dimension Externals that invoke the TP Desktop Connector client services, one of which includes C source code to illustrate how to write your own 4th Dimension Externals.
  • A set of HyperCard XFCNs that invoke the TP Desktop Connector client services, including C source code.
  • A set of utility files containing C source code for date and data conversion functions and programs useful in managing your development platform.
  
  You can install the Examples option separately, after installing the Run-Time Services.

This section describes the preparations and requirements for installing the TP Desktop Connector client services software for Macintosh systems.

7.2.1 Prerequisite Software for Macintosh Systems

Before you install the software, do the following:

1. Install TP Desktop Connector Gateway for ACMS software on the OpenVMS system running ACMS.
2. If you choose to use a VAXshare volume as the source from which to copy the client software to your Macintosh, identify a disk device on which to build a VAXshare volume.
   If you choose not to use a VAXshare volume as the source from which to copy the client software:
   1. Install a file transfer tool such as XMODEM or a DECnet file server on your host OpenVMS system.
   2. Install a corresponding file transfer tool such as MacTerminal or NetCopy on the Macintosh.

3. Install the appropriate Communications Tools on your Macintosh for the transports you plan to use:
   • AppleTalk-DECnet Tool
     To use the AppleTalk-DECnet Gateway
   • DECnet Tool
     To manage your Macintosh as a DECnet node
   • MacTCP
     To use a TCP/IP communications transport
   • AppleTalk ADSP Tool
     To manage your host OpenVMS node as a socket in an AppleTalk Internet
   • A tool that implements serial communications protocols, such as the Serial Tool or the Apple Modem Tool.
     To use serial communications
4. If you plan to manage your OpenVMS node as a socket in an AppleTalk Internet, install the PATHWORKS AppleTalk for OpenVMS Transport on your OpenVMS system.
5. Log in to the OpenVMS system using an account with sufficient privileges. Using the SYSTEM account is recommended.

The required disk space on your Macintosh depends on the installation option you choose, as listed in Table 7-1.

Table 7-1 Macintosh Disk Space Requirements

Option	Disk Space
Run-Time Services	138K bytes
Run-Time Services and Calypso	263K bytes
System Services	183K bytes
System Services and Calypso	308K bytes
Examples	2612K bytes
System Services, Calypso, and Examples	2920K bytes

7.3 Installing the Macintosh Software

This section describes how to install the TP Desktop Connector client services software for Macintosh on a Macintosh system.

7.3.1 Copying the TP Desktop Connector Installer to the Macintosh

All the files that comprise the TP Desktop Connector Macintosh client software are compacted into a single installation file, ACMSDI_DESKTOP.INSTALLER. The installation procedure consists of the following steps:

1. Copy or FTP ACMSDI_DESKTOP.INSTALLER to the target Macintosh.
2. Double click the installer file.
3. Follow the instructions that are displayed.

The files on the TPware Product Suite and Software Products Library CDs are in MacBinary format. Many file transfer facilities such as NetCopy and MacTerminal automatically convert files from MacBinary to standard Macintosh format as part of the copy operation. If your file transfer utility does not automatically do so, use a tool such as MacBinary Converter (mBin) to convert the ACMSDI_DESKTOP.INSTALLER to standard Macintosh format after you copy it.

After you have successfully copied the ACMSDI_DESKTOP.INSTALLER file to your Macintosh, proceed to Section 7.3.2.

7.3.2 Running the TP Desktop Connector Macintosh Installer

The ACMSDI_DESKTOP.INSTALLER file is a self-extracting file containing all the TP Desktop Connector Macintosh client services files in compressed form. During installation, files are automatically moved to the appropriate folders. The installation process provides instructions with each step:

1. Begin the installation process by double clicking on the ACMSDI_DESKTOP.INSTALLER file.
2. A window appears that identifies the product as TP Desktop Connector Version 2.3. Click on the Continue button.
3. A second window appears containing a copyright notice. Read the copyright notice. Buttons are available to save or print the notice. You can cancel the installation at this point by clicking the Cancel button, in which case nothing is installed. Click the Continue button if you want to proceed with the installation.
4. The next window provides some information about the installer. It tells you where the files to be installed will be placed and tells how much disk space is required for the (standard) full installation. The Calypso Tool mentioned is the software that enables serial (dialin) communication between TP Desktop Connector client applications and the host ACMS Desktop server.
   You have three buttons to choose from at this point:
   1. Custom button:
      Allows you to proceed to another window where you can choose which parts of the software you want to install.
   2. Quit button:
      Allows you to cancel the installation at this point; nothing is installed.
   3. Install button:
      Causes a full installation to occur; everything is installed.
   
   If you want a standard, full installation, click the Install button now, and skip to step 6. If you want to examine additional options, click the Custom button and proceed to step 5.
5. If you choose a custom installation, a window appears with six installation options. Text appears to describe each option and how much disk storage it requires. Section 7.1 presents a more complete description of the installation options.
   • System Services, Calypso, and Examples: This option installs everything. It is identical to the standard installation presented on the previous window.
   • System Services: This option installs everything except the examples and Calypso software.
   • System Services and Calypso: This option installs everything except the examples.
   • Examples: This option installs the examples only. Use it as a follow-up installation to a system services or run-time services option with or without Calypso.
   • Run-Time Services: This option installs only the basic software needed for run-time support. The development aids, the Examples and the Calypso software are not installed.
   • Run-Time Services and Calypso: This option installs the basic software needed for run-time support and the Calypso software. The development aids and examples are not installed.
   
   You again have three buttons from which to choose:
   1. Standard button:
      Allows you to return to the standard installation window.
   2. Quit button:
      Allows you to cancel the installation at this point; nothing is installed.
   3. Install button:
      Cause an installation to occur. Before clicking on this button, select one of the installation options by clicking on it to highlight it.
6. Clicking on the Install button from either the standard or custom installation window causes a window to appear from which you can select the location to place the folder "TP Desktop Connector folder (2.3)". All files except the DDEV and Calypso Tool are installed in this folder. Clicking the Cancel button cancels the installation, in which case nothing is installed. Clicking the Save button causes the installation to occur, as indicated by a progress window.
7. If the installation is successful, a dialog box appears indicating success. From this window, you can quit or continue with additional installations.

This part covers the server-side software and samples, but not the client-side software and samples. See Part 2 for the client-side instructions.

This chapter discusses the preparations and requirements necessary for installing DIGITAL TP Desktop Connector Gateway for ACMS software. Your bill of materials (BOM) and indented bills report (BIL) specify the number and contents of your media. Be sure to verify the contents of your kit with this information. If your kit is damaged or incomplete, contact your Compaq representative.

TP Desktop Connector gateway software includes online release notes and gives you the option of printing or displaying them during the installation procedure. Compaq strongly recommends that you read the TP Desktop Connector release notes before proceeding with the installation, in case they contain important information regarding the installation procedure.

8.1 Required Operating System Components

To install TP Desktop Connector gateway software, you must have one of the following operating systems installed:

OpenVMS VAX operating system

• Version 5.5-2
• Version 6.1
• Version 6.2
• Version 7.1
• Version 7.2 <>

OpenVMS Alpha operating system

• Version 6.1
• Version 6.2
• Version 7.1
• Version 7.2 <>

The Software Product Description (SPD) contains a list of the prerequisite software, as well as a complete list of the products that are compatible with this version of TP Desktop Connector gateway software.

On OpenVMS Alpha systems, the SPD is on the media CD. <>

8.3 Installation Procedure Requirements

The installation procedure, VMSINSTAL, checks for various conditions on your system. If VMSINSTAL detects any problems during the installation, it notifies you of the problem and asks whether you want to continue the installation. In some instances, you can answer YES to continue. To stop the installation process and correct the situation, answer NO or press [Return] .

You can avoid having to stop and restart VMSINSTAL by following the directions in this section before you run VMSINSTAL. The time required for installing TP Desktop Connector gateway software is approximately five minutes.

8.3.1 Disk Space

Installing TP Desktop Connector gateway software requires a certain amount of free storage space during the installation. Table 8-1 summarizes the storage requirements for TP Desktop Connector gateway during and after installation.

Table 8-1 Disk Space Requirements

	Blocks During Installation	Blocks After Installation
TP Desktop Connector gateway	23 304	6 500

To determine the number of free disk blocks on the current system disk, enter the following command at the DCL prompt:

$ SHOW DEVICE SYS$SYSDEVICE

In the output column under the heading Free Blocks is the number of 512-byte blocks available on the device.

8.3.2 Privileges and Authorization

To install TP Desktop Connector gateway software, you must be logged in to an account with the following privileges:

• NETMBX
• SETPRV
• TMPMBX

The SYSTEM account has all the privileges you require for the installation.

VMSINSTAL turns off the BYPASS privilege at the start of the installation and sets whatever privileges it needs during the installation.

At the end of the installation procedure, if the TP Desktop Connector gateway system components were installed, the TP Desktop Connector gateway process on OpenVMS is started using the same user name that you use to install the product. Compaq recommends that you run the gateway under the user name SYSTEM or another user name with a [1,4] UIC.

For the TP Desktop Connector for ACMS process to be properly started, the user name under which the installation is done must be an authorized ACMS agent. Use the ACMSUDU Utility to authorize the user name. For example:

$ SET DEFAULT SYS$SYSTEM $ RUN ACMSUDU UDU> ADD SYSTEM/AGENT UDU>

If the user name is not authorized as a ACMS agent, the IVP can fail and TP Desktop Connector client programs cannot sign in to the ACMS system. To allow client programs to successfully sign in to the ACMS system, stop the TP Desktop Connector gateway and restart it under a user name that is an authorized ACMS agent.

8.3.3 OpenVMS License Management Facility

TP Desktop Connector gateway supports the OpenVMS License Management Facility (LMF). To install TP Desktop Connector gateway on an OpenVMS system, you must register your software license.

LMF requires registration of a Product Authorization Key (PAK). The license registration information you need is contained in the PAK that is shipped with TP Desktop Connector gateway software. The PAK is a paper certificate that contains information about the license you have to run a particular piece of software.

Register your TP Desktop Connector gateway license before you perform the installation. During the installation, you are asked whether you have registered the TP Desktop Connector gateway license and loaded the appropriate authorization key. You cannot run either the TP Desktop Connector gateway software or its IVP unless your license is loaded. After you perform the license registration and load an authorization key, you can run the IVP and use TP Desktop Connector gateway software.

To register a license, first log in to the system manager account, SYSTEM. You then have a choice of two ways to register:

• Run the SYS$UPDATE:VMSLICENSE.COM procedure. When it prompts you for information, respond with data from your PAK.
• Issue the LICENSE REGISTER command with the appropriate qualifiers that correspond to information on the PAK.

For complete information on using LMF, see VMS License Management Utility Manual.

8.3.4 System Disk Backup

At the beginning of the installation, VMSINSTAL asks whether your system disk is backed up. Compaq recommends that you always do a system disk backup before installing new software on the operating system.

Use the backup procedures that are established at your site to do this backup. For details on performing a system disk backup, see the section on the Backup Utility in the OpenVMS documentation set.

8.3.5 Stopping ACMS and TP Desktop Connector Gateway

If you have TPware components already installed and running, shut them down. While logged in to the system under an account having the appropriate privileges as described in Section 8.3.2, execute the following commands.

1. Stop the TP Web Connector Gateway for ACMS process. For example:

   $ @SYS$STARTUP:ACMSDI$SHUTDOWN $

2. If you have ACMS software already installed and running, shut it down. Execute the following commands.
   1. Stop the ACMS system. For example:

      $ ACMS/STOP SYSTEM . . . $

   2. Stop the ACMS controller. For example:

      $ @SYS$STARTUP:ACMSTOP . . . $

If you have not already inserted the compact disk (CD) media in the CD drive, do so now.

To obtain the directory location of the saveset for the TP Desktop Connector gateway software on the :CD-ROM, refer to the OpenVMS Layered Products Compact Disc User's Guide, or, before starting the installation, complete these steps:

1. To determine whether the :CD-ROM drive is already mounted (MOUNT command), enter a command in the following format:

   SHOW DEVICE device-name

2. If the device is not mounted, enter a command in the following format:

   MOUNT/OVERRIDE=ID device-name

   
   For example:

   $ MOUNT/OVERRIDE=ID DKA200:

3. Locate the distribution files. The directory-name depends on the OpenVMS platform, as follows:

   OpenVMS Platform	Directory Name
   Alpha	VMSALPHA
   VAX	VMSVAX

4. To obtain the saveset name, use a DIRECTORY command in the following format and specify the saveset name from the previous command.

   DIRECTORY device-name:ACMSDI031