Datanex, Inc.

Data Transfer Services for
Windows32
Installation and Administration Guide


The Data Transfer Services for Windows32 Installation- and Administrator's Guide describes the components of Windows32 connectivity and how to configure and use the product.





Intended Audience

This manual is intended for system managers of Windows32 communications who must oversee Windows32 connectivity and who are responsible for maintaining communication links with remote systems.



Associated Documents

The following documents may also be useful:

Data Transfer Services for Windows32 Users Guide, operational instructions for components of Windows32 connectivity.







TABLE OF CONTENTS

	
	Chapter 1 - Introduction
1.1 General 
1.2 Connectivity
1.3 Customer Support and Services 
	
Chapter 2 - Installation 
2.1 Installation Overview 
2.2 Management Overview 
2.3 Preparing for the DTS Installation 
2.4 DTS Installation and upgrading 
	
	Chapter 3 - System Components and Administration
3.1 DTS Components 
3.2 The Communications Manager 
3.3 Application Transaction Programs
3.4 Security
	
	Chapter 4 - Basic Operations 
4.1 Operational Primer 
4.2 Starting DTS
4.3 Stopping DTS 
4.4 Link Status Checking
4.5 Interactive Prototyper 
4.6 Print Services
4.7 Demo Programs
4.8 Default locations

Chapter 5 - International Languages 
 









Chapter 1

General

1.1 Datanex, Inc. is dedicated to meeting the diversified communications needs of our customers by providing a full spectrum of Data Transfer Services (DTS) products and services. 

1.2 Data Transfer Services operates over two basic types of connections, IBM's SNA LU6.2 and the popular TCP/IP protocols. This manual describes DTS for TCP/IP.

1.3 Datanex, Inc is dedicated to providing the best possible support to our customers. To this end we have provided a trouble shooting guide and problem report form as part of our web page - http://www.datanex.com - which will be automatically mailed to us on completion. Electronic mail is checked at 6am Pacific time Monday through Friday. If you do not have internet access, fax forms can be provided. We welcome your phone calls during normal working hours, from 8am to 5pm Pacific time.

















Chapter 2

Installation

2.1 Installation Overview

The process of installing Data Transfer Services consists of restoring a saveset on one or both systems, running installation and configuration procedures or programs, setting up procedures and programs to restore communications when the systems are restarted, and making the DTS facilities available to users.

In order to communicate with other systems using TCP, each system must be properly configured. This may involve personal communication and agreement between administrators on each system.

2.2 Management Overview

Managing DTS consists mostly of ensuring that users have proper access, that communications are restored after system restarts, and in troubleshooting problem events, should any occur. DTS is designed to be straightforward to manage and operate.

2.3 Preparing for Windows32 Installation

This section details the prerequisites for installing DTS on Windows32 systems.

Important Note - Upgrading an Existing System

If you are upgrading an existing installation and are using the communications manager and/or print services as a WindowsNT/2000 service, they must be stopped and uninstalled with the invoker program. The supplied remove.bat procedure accomplishes this easily. The supplied install.bat procedure will quickly re-install them as services. You will have to modify the startup conditions in services to their previous state after the upgrade. Existing user modifiable files such as tp.dat will not be overwritten during the upgrade.

It is always prudent to make a backup of your existing directory tree before a
re-install. This can be done to a disk file or backup tape unless you have ready access to a backup of the tree from routine system procedures.

Please note that the TCP version of the product utilizes the TCP software supplied by the platform vendor and not second party software.

Before performing the installation, there is an item of information that must be agreed upon by all system managers whose computers will communicate using this product. Each computer will run a communications manager process whose job it is to service incoming requests. All of these processes will communicate on a known previously determined port. It must have the same value as all other computers using this software. As shipped, the value is 2700. If you do not have a reason for changing it, then the installation is simplified.

2.4 Installation and upgrading.

The software can be FTP downloaded from the internet by special arrangement as a single self extracting executable named dst_tcp_32.exe . We suggest you place this file into an empty temporary directory. Log into your system as an administrator and run the executable to extract the setup files. Run setup.exe to install the product. The product should be installed in its own directory. The installation is incomplete by necessity. Please read these instructions carefully.

If the product has been supplied on media, please copy all files to an empty temporary directory on the hard drive and run setup.exe to install.

There are three main components in the product: executables, dynamic link libraries and data files. In order for the software to function under WindowsNT/2000, the dynamic link libraries must be in the user's path. To this end, you might choose to relocate them to \Winnt\system32. The preferred option is to place the directory into which you placed the software in the system path since it allows the executable programs to be located that much more easily. A third option, if you are the only person using the product on your computer, is to put the directory in your path.

On Windows98, moving the libraries is not necessary.

Chapter 3

Components and Administration

3.1 Components

There are four major functions to the TCP/IP version of Data Transfer Services:

1) Source transaction programs
2) Print services functions
3) Target transaction programs
4) The Communications Manager to service incoming requests

The system comes with both source and target transaction programs to allow simple file transfer and the submittal of remote commands and jobs. This has been done to keep the look and feel of the original SNA LU6.2 version of the software. It is assumed that users will want to write their own cooperating client/server transaction programs. System administrators will need to make the communications manager aware of the target transaction programs. To this end we will discuss the communications manager and the associated TP.DAT file.

3.2 Communications Manager

It is the function of the communications manager to field incoming requests for target transaction programs to be run, start them and provide the port number to both the target and source. To clarify this discussion, please print the file TP.DAT.

TP.DAT is an ASCII text file with records whose fields are space delimited. The first record of the file contains operating parameters for the communication manager. The first field is the port on which all communications managers using this software will communicate. It can be changed but all must agree. The second field is for the AS/400 and, although ignored under Windows32, must be present.

The third field is the priority at which target programs will be run. HIGH_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS and IDLE_PRIORITY_CLASS are the only priority classes allowed and none but NORMAL_PRIORITY_CLASS is recommended. This is ignored by Windows98.

The last two fields are interpreted as the port range over which target programs will communicate with the requesting program (source). The values are arbitrary but should be considered reserved for our product. The range should ensure that two running targets are unlikely to use the same port number at the same time.

The second record contains the user name and password that will be used when security information is not provided by the incoming request. It should be a minimally privileged account. As shipped, we use the guest user name with a password of guest. Because of the variety of machines that might connect to your computer, we have made the arbitrary decision to force all incoming user names and passwords to be lower case. User names and security are not used for Windows98.

All remaining records pertain to target transaction programs and contain two fields. The first field is the symbolic name by which the target program is known by programmers on both (all) computers. The name is symbolic only. Obviously duplicate names must be avoided. The second field is the path to and name of the image to be executed. Both these fields should be provided to the administrator by the programmers involved. The system administrator will be required to add records as programmers require, using any simple text editor. Please note that since the contents of this data file tend to remain static for long periods of time, we have chosen to have the communications manager read this file only at startup. In order for changes to be recognized, the communications manager must be restarted.

3.3 Transaction Programs

Evoked transaction programs often leave log files in the log directory. These files accumulate and can consume disk space over time. We recommend the following procedure to eliminate disk clutter. Schedule a periodic shutdown of the communications manager and delete everything in the log directory. If full security (discussed below) is implemented, clearing this file prior to each startup of the communications manager is recommended.

3.4 Security - WindowsNT/2000

The level of security checking on Windows32 depends on the privilege level of the user starting the communications manager. If the communications manager does not have the SEC_TCP_NAME privilege, no user name - password checking can be done and the program launched by the communications manager will operate within the privilege and environmental scope of the user starting the communications manager.

When security is enabled, complete user id and user password verification is done. In addition the requested program will be run with the security privileges of the designated user, provided or default. This will have meaning only if the Windows32 NTFS file system is used, as the FAT file system has no security.

To enable full security, the person starting the communications manager must have the following special privileges:  "Act as part of the operating system," "Create a token object" and "Replace a process token."  This may be accomplished through the User Manager. Removing the privilege "Act as part of the operating system" will revert to the no security check mode.

When security is enabled, it is wise to clean out the \log sub-directory prior to starting the communications manager. This is because log names are restarted with the subscript of 001 and it may not be possible to overwrite a log file that already exists in the directory. Log files are written with the security of the user id that created them.

Chapter 4

Basic Operations

4.1 Operational Overview

DTS for TCP/IP consists of a group of programs which use the manufacturer's version of TCP/IP for communications. It is not our intent to describe the setup of the communications in this document. If the system administrator can ping the other computer and the other computer's communications manager is up and running, this software will work.

4.2 Starting DTS

DTS is "started" by starting the communications manager. There are three ways to accomplish this. We have provided a program called ci_main. The normal supplied functions can be started from this program. If you choose to use ci_main, the initial startup of the communications manager and print services is password protected. This is because these two programs necessarily need administrator privileges. As received, the password is "datanex," lower case, and is read from the protected file, datanex.pwd. This feature may be disabled by deleting the password file. Attempts to run two instances of these two programs will fail, as they rightly should.

A note on passwords. If you enter the character "!" or bang, it resets the password to null for editing purposes.

The second method is to simply run the program, cm.exe. Once running, mouse click the launch button. The window may then be minimized.

The third way is more complicated, but survives log outs. Included in the distribution is a third party utility called "Invoker" which will allow a different version of the communication manager to be installed as a system service. If you wish to do this, follow these steps:

1) Set your default (current) directory to the DTS directory.

2) Issue the command:

invoker install cm "Communications Manager" "Drive:\full path to DTS\cms.exe" automatic

3) From the control panel, select "services" and highlight the Communications Manager service you just installed. Click on startup to select how it starts. Use your non-system highly privileged account, if you want security, or an administrators account for the startup

4) Start the communications manager logged in as the account specified in 3.

5) Invoker may be used to remove the stopped communications manager if it should be necessary for an upgrade of the software. Use:   invoker remove cm

Install.bat and remove.bat will both install and remove the communications manager and print services. This feature is not available in Windows98.




4.3 Stopping DTS

To stop the communications manager, simply bring up its screen and click on the exit button. If it is a system service, use the control panel services process.

Please note that starting and stopping DTS has nothing to do with starting or stopping TCP/IP. Even if the communications manager is not running on your system, you may still evoke target programs on another system where it is running.

4.4 Link Status Checking

You may check on the status of a link to another computer prior to running programs that communicate with it. This is advisable because if one attempts to communicate with a computer which is down, the program will take awhile to time out. Choose Link Check from ci_main or run it directly.

The term "ping" has meaning in the TCP/IP environment. It means to run a program to communicate in a minimal way with the other computer over a well known and agreed upon port number. The other computer will either recognize the incoming communication and minimally respond or the request will time out. A time out means that the other computer is not running the TCP/IP stack or cannot communicate for some other reason such as being down.

Ping the other computer first and check for the communications manager only if the other computer is responding.

4.5 Interactive Prototyper

The interactive Prototyper program will allow the user to start the same program on the other computer and interactively communicate in both directions. The interface is intuitive and the error checking and display thorough. Using this device, programmers have been able to develop production applications in a day. Please note that if the user of the Prototyper wishes to evoke CI on the other computer, the terminal on which the CI menu will appear must be appropriately set up. On Windows32 no special setup is required, the program will "pop up" on the default consol. Also note that the Windows32 version will time out after 5 minutes, so some coordination of prototyper to prototyper operations is needed.
4.6 Print Services

The print services program may also be started from ci_main. It obtains its data regarding where to print material from a file called pservices.dat. This file is modified using a simple text editor. The first record contains only the delay time between checks for material to print, in seconds. The first field of all subsequent records is a path to a directory into which files to be printed on another computer will be placed (Windows32 not having as sophisticated a queuing system as some others). These directories will have to be created. Please note as in the examples that the path terminates with a "\" or backslash.

The second field is the location of the other computer (the TCP name). The third field is the queue name on the other computer. The fourth field is the form name. An asterisk means standard. The next two fields are valid user name and passwords on that computer. Please note that the last three fields may be asterisks indicating "not needed," but the fields must be present or the program will not be able to scan the file correctly. If you are having difficulty, stop print services and look at its log file. It writes out what it reads in.

Print services is also available as a system service. It is called pservicess.exe (note double s's) and operates the same as cms.exe (note above).

4.7 Demo Program

In order to assist programmers, we have included demo programs, tntechoDlg.cpp, tntechoDlg.h, cisendDlg.cpp and cisendDlg.h to show how to use the verbs and how to call the dynamic link libraries.

4.8 Default Location

The administrator may provide both a system wide default location and default locations on a per user basis. This saves users the time and knowledge of having to provide a location each time a program is used. The system control from the control panel is used to define the environmental parameter "DEFAULT_LOCATION" for the system and/or individual users.





Chapter 5

National Languages

Translation files for translating text from ASCII to EBCDIC and back are located in the languages directory and have the t_xxx.xlt name. The xxx represents the translation "page," a concept originating with IBM. The default is for the US and Canada - 037. To change the usage of the files, copy the one of interest to the name trans.xlt in the installation directory. If this file does not exist in the installation directory, the software uses 037 which is hard coded. The following tables are provided:

Page	Country
037	USA-Canada
256	Multinational
260	Canada-Fr
273	Germany-Austria
277	Denmark-Norway
278	Finland-Sweden
280	Italy
284	Spain
285	United Kingdom
297	France
500	Multinational

