After you build the Java client, set up the client (see Section 8.8.1) and the management environment (see Section 8.8.2).

8.8.1 Java Client Setup

To run and successfully access a TP application, a Java client depends on the Java adapter classes and the Java adapter JNI code.

Keep the Java adapter stub DLL and the JAR file containing the Java adapter classes synchronized. Both files must be generated from the same STDL build so that procedures in the DLL match procedures in the JAR file. If the procedures do not match, an UnsatisfiedLinkError is thrown.

Ensure that the Java client can locate and use the Java adapter classes. The JAR file containing the Java adapter classes must be available with other class libraries used by the client. Make the file available by adding its path to the classpath environment variable. For example:

java -classpath add_acms_appl_acmsda.jar;%classpath% add_acms_client 1 1

The command runs a console application in the same directory as the JAR file and explicitly names the JAR file and existing classpath environment variable. For convenient use, place the command in a .bat file.

If any task group classes in the JAR file are instantiated, the Java Virtual Machine locates and loads the adapter stub DLL and performs initialization operations. If the DLL location is not in the executable path when the Java client runs, an UnsatisfiedLinkError is thrown.

To run the Java client under a debugger, rename or copy the adapter stub DLL and append _g to the name of the DLL. For example:

C:\java> copy add_acms_appl_java_acmsda.dll add_acms_appl_java_acmsda_g.dll C:\java>

The Java Virtual Machine requires that the _g be appended to the DLL name.

8.8.2 Management Environment Setup

Set up the management environment for the client. Perform the following steps.

1. Use the management GUI to establish runtime parameters.
   • If the client calls ACMSxp tasks, set up parameters (see Section 10.2.3).
   • If the client calls ACMS tasks, set up parameters (see Section 10.2.4).
2. Set up error logging for the client (see Appendix A).
3. If the client calls ACMS tasks, set up the ACMS Gateway adapter environment (see Section 10.3).

This chapter describes various application set-up operations.

9.1 Setup for Clients Calling Tasks Running under a Portable TP for Windows NT System

If your client calls tasks running under a Portable TP for Windows NT system, you may have to perform the following setup:

• If your client runs on a platform with different hardware architecture (either Alpha or Intel) from that of the server, register the proxy stub (see Section 9.1.1).
• If the client executable needs to call the server on a different node than the node from which the MTS package was exported, redirect the client system (see Section 9.1.2).

If the client has a problem communicating with the server, use error logging to help determine the cause (see Appendix A).

9.1.1 Registering the Proxy for MTS Applications

When your client runs on a hardware platform with a different architecture from that of the server or runs on an Alpha platform, you need to register the proxy stub generated by the STDL compiler. Whenever the STDL compiler generates one or more stubs for a group containing an MTS adapter, the compiler also generates a proxy stub DLL for that group. When you export the MTS package, the software creates a self-extracting, self-installing setup program that is executed on the client system. It registers the proxy stub DLL for the client to call the server remotely by means of DCOM. However, this setup program is not generated on Alpha platforms and runs only on the same platform (Intel) from which you export the MTS package.

Therefore, if your client calls tasks executing under a Portable TP for Windows NT system and you cannot execute the exported_name.exe setup program, you need to register the proxy DLL on the system on which the client executes. To register the proxy, follow these steps:

1. Obtain the proxy file with a name in the following format:

   group_mts_ps.dll

   • If both the client and Portable TP for Windows NT application run on Alpha platforms, copy the proxy file from the server development system to the client execution system.
     This file is generated when you compile the STDL task group specification on the server development system (refer to Portable TP for Windows NT Getting Started).
   • If the either client or Portable TP for Windows NT application runs on an Intel platform in a mixed architecture environment, copy the proxy file from the client development system to the client execution system.
     This file is generated when you compile the STDL task group specification on the client development system.
2. On the client execution system, register the proxy DLL using regsvr32.

This DLL contains the marshaling routines required by client and server systems to marshal data between clients and servers using DCOM.

9.1.2 Redirecting the Client System

You may need to redirect the client system if one of the following conditions applies:

• The client executable needs to call the Portable TP for Windows NT application on a different node than the node from which the MTS package was exported.
• You cannot execute the exported_name.exe setup program.
• The client and server run in a mixed architecture environment.

To redirect the client system so that it calls an Portable TP for Windows NT application on a specific node, perform one of the following actions:

• Supply the alternate name when you export the MTS package on the server system (refer to Portable TP for Windows NT Getting Started).
• Modify the client source code to set call attributes that define the server node.
  • For a C client, see Section 6.3.
  • For an Automation client, see Section 7.4.
  • For a Java client, see Section 8.5.
• Set the MTS_DEFAULT_ENTRY environment variable equal to the name of the server node. For example:

  C:\> set MTS_DEFAULT_ENTRY=\\ALPHASVR

  Note A call attribute and the MTS_DEFAULT_ENTRY environment variable can be used with any client and server platform combination. Setting the call attribute or MTS_DEFAULT_ENTRY overrides the default remote node defined in the registry as a result of executing exported_name.exe on the client system. If a call attribute is specified and MTS_DEFAULT_ENTRY is defined, the call attribute takes precedence.

You can specify the name of the server node using DCOMCFG only if you ran exported_name.exe.

This chapter describes procedures that you use to manage the environment on a client system running the TP Desktop Connector software. The topics are as follows:

• Supplying management information (see Section 10.1)
• Using the TPware management utility GUI (see Section 10.2)
• Setting up the ACMS Gateway adapter environment (see Section 10.3)

In general, the TPware management utility provides information to various communications adapters. Whenever an adapter runtime needs information, it uses the following sources (the first listed has the highest precedence):

1. The call attributes (if any) from the client program
   Call attributes can supply only some of the required information. Some adapter information, such as DCE RPC principal information, cannot be supplied this way.
2. Local settings
   You supply local settings through the local TPware management utility. Local settings are used if the information is not or cannot be supplied as a call attribute.
3. Remote settings (if Sharing is enabled)
4. Cached information from the remote node (if Sharing is enabled)
   If an attempt is made to use settings from a remote node and that node cannot be reached, then the last information (if any) retrieved from that node is used.

The TPware management utility on Windows platforms gives you the ability to customize management settings that are specific to your applications and environment. You can enter settings at two levels:

• A group whose name you supply
• A default group

Entering an attribute for a named group allows you to tailor that management attribute for a specific task group. Entering an attribute for a default group sets up a value that is common for all task groups.

Find the TPware management utility in the TPware program group. The utility may have any combination of the following tabs:

• Computer for selecting the system on which you want to manage TPware components (see Section 10.2.1)
• Sharing for specifying either that the computer you are managing uses shared management settings from a remote node or that this computer uses local settings with the option to share its settings with other clients (see Section 10.2.2)
• RPC for setting parameters for the DCE RPC and Microsoft RPC output adapters on the computer that you are managing (see Section 10.2.3)
• ACMS for setting parameters for the ACMS Gateway adapter on the computer that you are managing (see Section 10.2.4)

The management tabs available depend on the TPware products and options you have installed.

10.2.1 Computer Settings

The Computer tab allows you to select either the local node or a remote node for management. This option defaults to the local node.

When you change the node, the tabs displayed reflect the options installed on that node. If you choose Share Local Settings, all the tabs appear.

The name of the computer being managed appears in the title bar.

10.2.2 Using Shared Settings

The Sharing tab allows you to set up a particular node from which multiple clients can read their management settings. If many client nodes need the same management settings, you can reduce setup time on each client node by using the shared-settings feature.

This tab allows you to choose a remote node or the local node as the source for the management settings that will apply to the node that you are managing. If you click Use Local Settings, you can also click Share Local Settings if you want to share this node's settings with other client nodes.

If you click Use Remote Settings, then you need to supply the Remote Node Name on which these management settings exist. In this context, remote node means another node on which you have configured TPware management settings and have enabled Share Local Settings. Each time a setting is read from a remote node, that setting is written to a local cache. The local cache is used when the remote node is unreachable.

If you change your remote node, or if you switch from Use Remote Settings to Use Local Settings, the management utility warns that all cached entries will be deleted and prompts you to confirm this action. If you confirm, the utility deletes all cached settings. If you do not confirm, the utility redisplays the original settings.

If you select Use Remote Settings but have configured local TPware management settings (including the Default settings), the local settings will override the remote settings.

Restrictions on Registry Access

On Windows NT platforms, there are various restrictions that affect how a client user account accesses a remote node's registry at runtime to obtain management information.

The following restrictions apply if the remote node is:

• A server in the domain:
  • When the client is logged in to the domain
    All users have access, regardless of whether the guest account on the remote node is enabled or not.
  • When the client is not logged in to the domain
    If a user has an account on the remote node, the password for the remote account must match the password for the local account. If the guest account is enabled on the remote node, all users have access, and the password restriction does not apply.
• A server not in the domain:
  If a user has an account on the remote node, the password for the remote account must match the password for the local account. However, if the guest account is enabled on the remote node, all users have access.

The following restrictions apply if the remote node is:

• A workstation in the domain:
  • When the client is logged in to the domain
    The user must be a member of the domain admin group, regardless of whether the guest account on the remote node is enabled or not.
  • When the client is not logged in to the domain
    The user must have an account (with matching password) on the remote node and be in the domain admin group for that node.
• A workstation not in the domain:
  The user must have an account (with matching password) on the remote node and be in the domain admin group for that node.

The RPC tab allows you to set options for the DCE RPC and Microsoft RPC output adapters used to call ACMSxp tasks. Use this tab to specify the following information:

• The name of the user principal and key file that an RPC client uses to log in to DCE (DCE RPC only)
• The default namespace entry name used to locate other ACMSxp servers

To use DCE key files instead of an interactive login, you can specify the DCE settings for the principal and key file by performing the following steps:

1. Click the RPC tab.
2. Check the Automatically login to DCE checkbox in the main window.
   Selecting this option causes TPware to establish the client DCE credentials and to create a thread that refreshes the credentials before they expire. If you leave this option unchecked, TPware does not perform a DCE login.
3. Enter the full path for the key file name. If you are sharing settings, you must enter a Universal Naming Convention (UNC) file name (with a node name and no device name). For example:

   \\node_name\share_name\dir_name\file_name

   
   Clicking the Browse button allows you to browse for key files.

To specify the default namespace entry name, click the Use the following default namespace entry checkbox. The utility uses the default entry name if the client does not provide an entry name as one of its call attributes.

TP Desktop Connector software locates ACMSxp servers by searching in the following order for the first entry name specified:

• The entry name specification as a call attribute
• The default entry name specified in the RPC settings
• The RPC_DEFAULT_ENTRY environment variable

The settings (except for call attributes) apply to all programs using DCE RPC or Microsoft RPC adapters on a system, regardless of which task group is invoked.

If you change the settings while a DCE RPC or Microsoft RPC client is running, restart the client for the changes to take effect.

10.2.4 ACMS Gateway Adapter Settings

The ACMS tab allows you to provide information related to the ACMS Gateway adapter. The STDL task group (for which you provide this information) is generated by the ACMSADU extension and given the ACMS application name as its task group name.

When you click the ACMS tab, the Default group entry appears in the Group Name drop-down box, but the ACMS Gateway Adapter settings fields for Default remain empty until you enter the relevant information and click Save. Configuring the Default group allows the runtime system to use these default settings if it cannot find an entry for a particular task group.

The ACMS Gateway adapter settings that you need to provide are as follows:

• Server Node: The TCP/IP node on which the ACMS gateway resides. Running on an ACMS system, the ACMS gateway connects the ACMS Gateway adapter in the client on the Windows system to the ACMS tasks running on the OpenVMS system.
• Username: The name of the user account on the OpenVMS system that clients use for ACMS calls.
• Password: The password for the OpenVMS user account that clients use for ACMS calls. (The password is not echoed.)

When the ACMS tab settings of a specified group change, all newly started clients see the changed settings. Clients that are running when the changes take effect do not see the changes. Ensure that you restart all clients that call the group so that the changes take effect.

If the gateway node uses a TCP/IP port that is different from the default, you also need to provide that information through an environment variable (see Section 10.3.2).

If the client specifies call attributes, they override all management settings.

10.2.4.1 Configuring a New ACMS Group

You need to configure a new ACMS group when the group is the Default task group or any task group that does not use the default settings. If you want a group to use the Default group settings, do not perform the following configuration procedure for that group (the runtime system applies default group information to any group without an entry).

To configure a new ACMS task group, perform the following steps:

1. Click the ACMS tab. The Default group automatically appears in the Group Name box.
2. If you are configuring the Default group, skip to Step 5. If you are configuring a new group that does not use default settings, click the New Group button.
3. A pop-up window appears. Enter the group name.
4. Add the group to the Group Name list box by clicking the Add button.
5. Enter specific Server Node, Username, and Password information for the group shown in the Group Name box.
6. Click Save.
7. Restart all clients that call the group so that the changes take effect.

To change the ACMS Gateway adapter settings of a group, perform the following steps:

1. Click the ACMS tab.
2. Select a group from the Group Name list box to view its settings.
3. Type in the new information.
4. After you make changes, save them by clicking the Save button.
5. Restart all clients that call the group so the changes take effect.

If there are any unsaved changes, a dialog box asks whether you want to save all changes.

10.2.4.3 Deleting ACMS Gateway Adapter Group Settings

To delete the settings of a group, perform the following steps:

1. Click the ACMS tab.
2. Select the group in the Group Name list box.
3. Click the Delete button.
4. Restart all clients that call the group so the changes take effect.

If a group does not appear in the Group Name list box, that group uses the settings for the Default group, provided that you have entered the Default group settings.

10.3 Setting Up the ACMS Gateway Adapter Environment

If your client calls ACMS tasks (uses the ACMS Gateway adapter), you might need to do the following tasks:

• Specify an ACMS Gateway adapter error log file (see Section 10.3.1).
• Specify a TCP/IP port number (see Section 10.3.2).
• Manage the TP Desktop Connector Gateway for ACMS (see Section 10.3.3).