# Compaq TP Desktop Connector
for ACMS
Installation Guide

Previous | Contents | Index

# Chapter 10
After Installing TP Desktop Connector Gateway for ACMS Software

After installing gateway software from the Gateway CD, perform the following tasks:

- Edit OpenVMS system startup and shutdown files (see Section 10.1).
- Perform any cluster operations (see Section 10.2).
- Match client and server versions (see Section 10.3).
- Read the management chapters in the appropriate document:
  - Compaq TP Desktop Connector for ACMS Client Application Programming Guide
  - Compaq TP Desktop Connector Getting Started

See Chapter 11 for information about how to run the Installation Verification Procedure (IVP) after the software has been installed.

# 10.1 Editing the OpenVMS System Files

You must edit the OpenVMS system startup and shutdown files to provide for automatic startup and shutdown of TP Desktop software when your system is rebooted. (This step is usually not necessary for system upgrades.)

## 10.1.1 Editing the System Startup File

The following files are located in the SYS$STARTUP directory.

    ACMSDI$SHUTDOWN.COM
    ACMSDI$STARTUP.COM

Add to the OpenVMS system startup file the command line that starts TP Desktop. If you separate the startup procedures into modules, be sure that you add the lines to the correct file.

Position the TP Desktop startup command line after the line that invokes the ACMS startup command procedure. For example:

    $ @SYS$STARTUP:ACMSTART.COM
       .
       .
       .
    $ @SYS$STARTUP:ACMSDI$STARTUP.COM

Note Start ACMS software before you start TP Desktop software.

Starting TP Desktop software automatically enables the use of the DECnet communication transport. To use NetWare or TCP/IP protocols as well, or instead of DECnet, list the transports you want to use in a parameter file. Specify the parameter file as a qualifier on the TP Desktop startup command line.

The parameter file is a simple ASCII text file that lists customer overrides to TP Desktop run-time quotas and defaults. These overrides can include the specification of the communication libraries that have been installed on the OpenVMS system. For example, to enable TP Desktop to use all transports, create the following file in the SYS$MANAGER directory:

    ACMS_DESKTOP_SERVER.DAT

Include in the file the following line:

    transport=(tcpip,netware,decnet,appletalk)

Modify the startup command line to specify the parameter file. For example:

    $ @SYS$STARTUP:ACMSDI$STARTUP.COM SYS$MANAGER:ACMS_DESKTOP_SERVER.DAT

To perform this same function in batch from DCL-level, issue a SUBMIT command. For example:

    $ SUBMIT/USER=SYSTEM/NOLOG SYS$STARTUP:ACMSDI$STARTUP-
    _$ /PARAMETER=(SYS$MANAGER:ACMS_DESKTOP_SERVER.DAT)

This command starts a batch job that runs the startup command procedure using the input file specified in the parameter qualifier. When the batch job completes, the TP Desktop software is started.

## 10.1.2 Editing the System Shutdown File

Find the following line, which stops the ACMS system, in the OpenVMS system shutdown file:

    $ @ACMSTOP.COM

At some point before this line, add the following command line:

    $ @SYS$STARTUP:ACMSDI$SHUTDOWN.COM

The command procedure cancels all active tasks and shuts down the TP Desktop process. This ensures that the TP Desktop system processes are run down properly. The command procedure also deinstalls TP Desktop images (using the Install Utility of OpenVMS) and deassigns the logical names.

# 10.2 Performing Cluster Procedures

Because TP Desktop software treats a VAXcluster or VMScluster system as if it were a local area network (LAN), you must prepare system-specific roots on each node of the cluster. For example:

    $ CREATE/DIRECTORY SYS$SPECIFIC:[ACMSDI]/OWNER_UIC=SYSTEM-
    _$  /PROTECTION=(S:RWE,O:RWE,G:RE,W:RE)
    $ CREATE/DIRECTORY SYS$SPECIFIC:[SYSTEST.ACMSDI]/OWNER_UIC=SYSTEM-
    _$  /PROTECTION=(S:RWE,O:RWE,G:RE,W:RE)
    $ CREATE/DIRECTORY SYS$SPECIFIC:[SYSHLP.EXAMPLES.ACMSDI]/OWNER_UIC=SYSTEM-
    _$  /PROTECTION=(S:RWE,O:RWE,G:RE,W:RE)
    $

Executed on each node in the cluster, these commands create directory roots for the TP Desktop software. See Section 9.1.2 for the locations of files describing the directories added to your system.

# 10.3 Matching Client and Server Versions

If you are upgrading from ACMS Desktop Version 2.n to TP Desktop Version 3.m, you can use your existing client programs with the new server. But, if you build a new client program under TP Desktop Version 3.m, you cannot use this new program with the old ACMS Desktop Version 2.n server.

When the ACMS communication protocols do not match those of the desktop client, the gateway rejects the attempted connection. The gateway writes a message to the software event log (SWL).

The error code returned on the client side depends on the nature of the mismatch. The following error codes can indicate a mismatched condition:

    ACMSDI_SRVDEAD      -3020
    ACMSDI_INVPROTOCOL  -3025

# Chapter 11
Running the TP Desktop Connector Gateway for ACMS IVP

This chapter describes how to run the gateway installation verification procedure (IVP) separately from the installation procedure. The IVP can be run as a part of the normal installation when you answer YES to the IVP question. If the IVP fails for any reason, correct the error and rerun the IVP. See Chapter 9 for information on providing the IVP with information required for the installation procedure. Run separately from the installation procedure, the IVP can check the integrity of installed files on the system.

# 11.1 IVP Operations

The IVP checks that:

1. The installation procedure successfully completed installing TP Desktop software.
2. The installed software can be used to set up and run TP Desktop software.
3. All the necessary files are on the system.

The IVP does not check that the applications run correctly.

# 11.2 Running the IVP Independently

This section describes the requirements and steps to run the IVP.

## 11.2.1 IVP Requirements

If disk quotas are enabled, the IVP cannot run. The procedure checks to see whether disk quotas are enabled just after checking the process quotas. If disk quotas are enabled, the procedure provides an informational message to that effect and terminates.

## 11.2.2 IVP Steps

To run the IVP independently of the installation procedure, follow these steps:

1. Log in to the SYSTEM account:

       Username: SYSTEM
       Password:

2. Set your default to the test directory:

       $ SET DEFAULT SYS$TEST
       $

3. Run the IVP using the following file specification:

       ACMSDI$IVP.COM

   You can run the IVP only on your current booted system. You cannot run the IVP over a networked connection.

To start the IVP, enter the following command:

    $ @ACMSDI$IVP
    The TP Desktop Connector V3.1 Gateway for ACMS IVP completed successfully
       .
       .
       .
    The TP Desktop Connector V3.1 Gateway for ACMS IVP completed successfully

The IVP takes no more than 30 seconds to run, depending on the current system load.

## 11.2.3 IVP Error Recovery

As the IVP executes, it checks the success of each test and operation it performs. If any test or operation fails, the IVP does the following:

1. Stops processing.
2. Displays a message describing the failure.
3. Suggests a course of action to eliminate the cause of the failure.

Follow the suggested course of action and then restart the IVP.

# Part 4
Appendixes

Part 4 provides reference material related to software installation on a system.

Appendix A lists the files that are installed on your system for the various sample programs.

Appendix B contains helpful hints about errors that might occur when you run one of the sample applications.

# Appendix A
Files Installed

The following tables list the files that are installed on your systems for the various sample applications.

Table A-1 Files Installed for TP Desktop Connector Client Services for OpenVMS Systems
Files | Description
--- | ---
ACMSDI.H | Include file for the TP Desktop Connector client services declarations
ACMSDI$CLIENT_OBJLIB.OLB | Library for the TP Desktop Connector client services
FORMS.H | Include file for DECforms
NET_APPLETALK.OBJ | AppleTalk object file (for OpenVMS VAX systems only)
NET_DECNET.OBJ | DECnet object file
NET_NETWARE.OBJ | NetWare object file 1
NET_TCPIP.OBJ | TCP/IP object file
PPSTUBS.C | Presentation procedure and action routine stubs
TDMS.H | Include file for TDMS

1For testing purposes only, not officially supported.

Table A-2 Files Installed for the Motif Sample for OpenVMS Systems
Name | Description
--- | ---
Makefile | Makefile for building the sample
acmsdi.h | Include file for the TP Desktop Connector client services
forms.h | Sample include file with DECforms status values
help.txt | Overview of the AVERTZ user interface
sys$login:m_avertz.dat | Motif sample resource file
m_avertz.c | Entry point for the sample; manages the main window of the sample
m_avertz.h | AVERTZ header file; defines global names
m_avertz.opt | Linker-purge options file for building the sample
m_avertz.uid | Runtime representation of the sample's UIL definition
m_avertz.uil | User interface template; defines the layout of the main window and the session dialog box
m_avertzpp.c | Reserve task presentation procedures; stubs for the checkin and the checkout tasks' presentation procedures
m_avertzpp.h | Header file for m_avertzpp.c
m_disable.c | Presentation procedure stub
m_enable.c | Presentation procedure stub
m_icons.uil | User interface template; defines the various session icons
m_list_pkg.c | Provides linked list feature
m_list_pkg.h | Header file for list_pkg.c
m_message.c | Performs message box handling in the sample
m_message.h | Header file for m_message.c
m_read_write.c | Presentation procedure stub
m_receive.c | Presentation procedure stub
m_request.c | Presentation procedure stub
m_resvform.c | Management and convenience routines for handling the reservation form
m_resvform.h | Header file for m_resvform.c
m_resvform.uil | User interface template; defines the layout of the reservation form
m_send.c | Presentation procedure to dispatch to specific routines in m_avertzpp.c
m_session.c | Manages multiple sessions; switches context for using TP Desktop Connector gateway for ACMS routines and updates the user interface
m_session.h | Header file for m_session.c
m_sitelist.c | Creates (using m_sites.dat) and manages the list box of AVERTZ sites
m_sitelist.h | Header file for m_sitelist.c
m_sites.dat | Contains data about AVERTZ sites; read in at run time
m_transceive.c | Presentation procedure that dispatches to specific routines in avertzpp
m_version.c | Version-checking action routine stub
m_wkspaces.c | Support routines for AVERTZ workspace structures
m_wkspaces.h | Defines the AVERTZ workspace structures
tdms.h | Sample include file with TDMS status values

Table A-3 Files Installed for the PowerBuilder Win32 Sample
Name | Description
--- | ---
`pbreadme.doc` | Contents of the folder in text format
`pbavertz.pbl` | PowerBuilder library containing PowerBuilder objects for the blocking sample that does not support exchange I/O
`pbavertz.exe` | Executable form of the PBAVERTZ sample
`pbavertz.doc` | Declarations and scripts used by PBAVERTZ in text format
`pbpointr.dll` | Dynamic link library required for memory management with PowerBuilder applications that use TP Desktop Connector gateway for ACMS services.
`pbpointr.h` | Interface definition file for `pbpointr.dll`
`acmsdipb.doc` | Microsoft Word document that explains how to use the `pbpointr.dll` services.
`cars.ico` | Icon used by PBAVERTZ
`fnbsampl.pbl` | A PowerBuilder library containing a sample application that executes an ACMS task with exchange I/O using the forced nonblocking extension to the TP Desktop Connector client services.
`fnbsampl.exe` | Executable form of the forced nonblocking sample
`fnbsampl.doc` | Microsoft Word document that describes forced nonblocking

Table A-4 Files Installed for the Visual Basic Win32 Sample
Name | Description
--- | ---
`mainmenu.frm` | GUI objects and code for the main window of Visual Basic AVERTZ
`reserve.frm` | GUI objects and code for the car rental reservations screen of Visual Basic AVERTZ
`signin.frm` | GUI objects and code for the session-login screen of Visual Basic AVERTZ
`readme.1st` | Contents of the folder in text format
`readme.txt` | Text document that explains how to use the helper DLL, `divb.dll`
`vbavertz.bas` | Global source code for Visual Basic AVERTZ
`vbavertz.exe` | Executable version of Visual Basic AVERTZ
`vbavertz.mak` | Project makefile for Visual Basic AVERTZ

Table A-5 Files Installed for the DOS Sample
Name | Description
--- | ---
ACMSDI.H | Include file for ACMS desktop interface programs
BLD-CLI.BAT | Batch file to compile and link the sample client program
BLD-PPS.BAT | Batch file to compile and link presentation procedures used by the sample client program
CHK-DATE.CBL | COBOL program to validate dates
CLASSES.CBL | Sample workspace
CLIENT.C | Sample client C main program
CLIENT.EXE | Sample client program
CONTROL.CBL | Sample workspace
CUSTOMER.CBL | Sample workspace
CUSTSHDW.CBL | Sample workspace
CU_TRANS.CBL | Sample workspace
DISABLE.C | Sample presentation procedure
ENABLE.C | Sample presentation procedure
FORMS.H | Sample include file with DECforms status values
GETSITE.CBL | Sample presentation procedure
LOGIN.CBL | Sample client initialization procedure
LOGOFF.CBL | Sample client termination procedure
MENU.CBL | Sample client menu procedure
RECV.C | Sample presentation procedure
REQUEST.C | Sample presentation procedure
RESERVTN.CBL | Sample workspace
SELCUST.CBL | Sample presentation procedure
SELSITE.CBL | Sample presentation procedure
SEND.C | Sample presentation procedure
SENDCTRL.CBL | Sample workspace
SHWCUST.CBL | Sample presentation procedure
SHWRESV.CBL | Sample presentation procedure
SITES.CBL | Sample workspace
SI_TRANS.CBL | Sample workspace
TDMS.H | Sample include file with TDMS status values
TRANS.C | Sample presentation procedure
TRANS.CBL | Sample workspace
TRANSHDW.CBL | Sample workspace
VERSION.C | Sample version-checking procedure

Table A-6 Files Installed for the Windows 3.11 Sample
Name | Description
--- | ---
ACMSDI.H | Include file for the ACMS desktop interface
AVERTZ | Makefile for building the sample
AVERTZ.C | Entry point for the sample; manages the main window
AVERTZ.DEF | Defines entry points and stack size for Microsoft Windows
AVERTZ.EXE | Microsoft Windows sample executable file
AVERTZ.H | AVERTZ header file; defines globals
AVERTZ.RC | User interface template; defines the main window, menus, and reservation form layout
AVERTZMM.C | Handles memory management for AVERTZ structures
AVERTZMM.H | Header file for AVERTZMM.C
AVERTZPP.C | Reserve task presentation procedures; stubs for checkin and checkout tasks and presentation procedures
AVERTZPP.H | Header file for AVERTZPP.C
DISABLEW.C | Presentation procedure stub
DRIVING.ICO | Icon for (an unselected) session that is currently processing a task
ENABLEW.C | Presentation procedure to define the session ID
FORMS.H | Sample include file with DECforms status values
HELP.TXT | Overview of the AVERTZ user interface
LIST_PKG.C | Provides linked list feature; preallocates memory using arrays to reduce fragmentation of the local heap
LIST_PKG.H | Header file for LIST_PKG.C
RECVW.C | Presentation procedure stub
REDCAR.ICO | Icon for (an unselected) session that is not currently processing a task
REQUESTW.C | Presentation procedure stub
RESVFORM.C | Management and convenience routines for handling the reservation form
RESVFORM.H | Header file for RESVFORM.C
SDRIVING.ICO | Icon for a selected session that is currently processing a task
SENDW.C | Presentation procedure to dispatch to specific routines in AVERTZPP.C
SESSION.C | Manages multiple sessions; switches context for using TP Desktop Connector gateway for ACMS routines and updates the user interface
SESSION.H | Header file for to obtain the files for building against the static link libraries SESSION.C
SITELIST.C | Creates (using SITES.DAT) and manages list box of AVERTZ sites
SITELIST.H | Header file for SITELIST.C
SITES.DAT | Contains data about AVERTZ sites; read in at run time
SREDCAR.ICO | Icon for a selected session that is not currently processing a task
TDMS.H | Sample include file with TDMS status values
TRANSW.C | Presentation procedure that dispatches to specific routines in AVERTZPP.C
VERSIONW.C | Version-checking procedure stub
WKSPACES.C | String conversion support for AVERTZ workspace structures
WKSPACES.H | Defines the AVERTZ workspace structures

Table A-7 Files Installed for the 16-Bit PowerBuilder Sample
Name | Description
--- | ---
ACMSDIPB.DOC | Document discussing TP Desktop Connector gateway for ACMS support for PowerBuilder
PBAVERTZ.PBL | PowerBuilder library containing the blocking sample which does not support exchange I/O
PBAVERTZ.EXE | Executable form of the PBAVERTZ sample
PBAVERTZ.DOC | Declarations and scripts used by PBAVERTZ in text format
CARS.ICO | Icon used by PBAVERTZ
PBPOINTR.DLL | Dynamic link library containing the required memory management program
PBPOINTR.H | Interface definition file for PBPOINTR.DLL

Table A-8 Files Installed for the Visual Basic Avertz Sample
Name | Description
--- | ---
ACMSDI.BAS | Include file of the ACMSDI declaration for Visual Basic applications
HELP.TXT | Online help file for the Visual Basic sample
MAINMENU.FRM | GUI objects and code for main window of Visual Basic AVERTZ
RESERVE.FRM | GUI objects and code for reservation form of Visual Basic AVERTZ
SIGNIN.FRM | GUI objects and code for session-login screen of Visual Basic AVERTZ
VBAVERTZ.BAS | Global module file for Visual Basic AVERTZ
VBAVERTZ.EXE | Visual Basic sample executable file
VBAVERTZ.MAK | Visual Basic makefile for AVERTZ sample

Table A-9 Files Installed for the Forced NonBlocking Tutorial
Name | Description
--- | ---
ACMSDI.BAS | ACMSDI declarations for Visual Basic applications
FORM1.FRM | GUI objects and code for the Forced Nonblocking Tutorial main window
FORMS.BAS | DECforms message code definitions for Visual Basic
FNBSAMPL.MAK | Visual Basic make file for the Forced Nonblocking Tutorial
FRMLOGIN.FRM | GUI objects and code for the Forced Nonblocking Tutorial session login window
FRMRECVC.FRM | GUI objects and code for the Forced Nonblocking Tutorial receive control text window
MTEXT.BAS | Declarations and code to initialize ACMSDI message text for Visual Basic applications
NONBLK.BAS | Global declarations for the Visual Basic Forced Nonblocking Tutorial

Table A-10 Files Installed for the Client Services for Tru64 UNIX Systems
Name | Description
--- | ---
acmsdi.h | Include file for the TP Desktop Connector client services
forms.h | Include file for DECforms
libacmsdi.a | Library for TP Desktop Connector client services
net_tcpip.o | TCP/IP file for TP Desktop Connector client services
net_decnet.o | DECnet file for TP Desktop Connector client services
ppstubs.c | Presentation procedure and action routine stubs
tdms.h | Include file for TDMS

Table A-11 Files Installed for the Motif Sample for Tru64 UNIX Systems
Name | Description
--- | ---
makefile | Makefile for building the sample
acmsdi.h | Include file for the TP Desktop Connector client services
forms.h | Sample include file with DECforms status values
help.txt | Overview of AVERTZ user interface
load_motif.sh | Command shell to download the Motif sample from the OpenVMS system
m_avertz | Motif sample executable file
m_avertz.c | Entry point for the sample; manages the main window of the sample
m_avertz.dat | Font definitions for the sample screens
m_avertz.h | AVERTZ header file; defines globals
m_avertz.uid | Runtime representation of the sample UIL definition
m_avertz.uil | User interface template; defines the layout of the main window and the session dialog box
m_avertzpp.c | Reserve task presentation procedures; stubs for the checkin and the checkout tasks' presentation procedures
m_avertzpp.h | Header file for m_avertzpp.c
m_disable.c | Presentation procedure stub
m_enable.c | Presentation procedure stub
m_icons.uil | User interface template; defines the various session icons
m_list_pkg.c | Provides linked list feature
m_list_pkg.h | Header file for list_pkg.c
m_message.c | Performs message box handling in the sample
m_message.h | Header file for m_message.c
m_read_write.c | Presentation procedure stub
m_receive.c | Presentation procedure stub
m_request.c | Presentation procedure stub
m_resvform.c | Management and convenience routines for handling the reservation form
m_resvform.h | Header file for m_resvform.c
m_resvform.uil | User interface template; defines the layout of the reservation form
m_send.c | Presentation procedure to dispatch to specific routines in m_avertzpp
m_session.c | Manages multiple sessions; switches context for using TP Desktop Connector gateway for ACMS routines and updates the user interface
m_session.h | Header file for m_session.c
m_sitelist.c | Creates (using m_sites.dat) and manages the list box of AVERTZ sites
m_sitelist.h | Header file for m_sitelist.c
m_sites.dat | Contains data about AVERTZ sites; read in at run time
m_transceive.c | Presentation procedure that dispatches to specific routines in m_avertzpp.c
m_version.c | Version-checking action routine stub
m_wkspaces.c | Support routines for AVERTZ workspace structures
m_wkspaces.h | Defines the AVERTZ workspace structures
tdms.h | Sample include file with TDMS status values

Previous | Next | Contents | Index