Datanex, Inc.

Data Transfer Services for Windows32

Users Guide


General

Data Transfer Services (DTS) is an easy to use, flexible software product that permits efficient communications between VAX/ALPHA systems running Open/VMS and IBM's popular AS/400 systems over SNA/APPC or TCP/IP. 32 bit Windows is also supported for TCP/IP. The DTS software enables users to perform bi-directional file transfers, execute remote jobs, print documents on remote printers, and develop program-to-program applications with an easy to use 5-verb API.

Data Transfer Services transfers messages or data records among VAX, Alpha, Windows32 and AS/400 systems instantaneously, so users and application programs can access information whenever they need it, whether the information is on the local system or not.  This helps alleviate unnecessary multiple terminal logins and allows users to work on the systems they know best.

Window32 caveat. Our goal has been to provide the user/programmer with as simple an interface as possible. This has meant that all related socket programming was to be provided in linking libraries. This, unfortunately, has meant that the asynchronous socket calls could not be used and other methods had to be employed to keep processes or systems from blocking. This has been accomplished with one exception. The address lookup phase is a blocking call during which the process, in the case of WindowsNT/2000, and the entire system, in the case of Windows98, will be unresponsive to user input of any kind.

Ordinarily this call returns instantaneously in a local network and even over the internet it usually returns in under a second. However, if the address specified is not registered on the internet, several seconds can elapse before the error condition is returned to the system to unblock the call. This is the only situation where a user could be inconvenienced.


      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.

      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 - that 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.






















Table of Contents

Chapter - 1  The Common Interface (CI)
	1.1 General
	1.2 Basic Conversation Concepts
	1.3 Configuration Examples for Cooperation Transaction Programs
	1.4 CI Conversation Implemented
	1.5 Example - CI File Transfer
	1.6 Platform Comparisons

Chapter - 2  CI Calls for Windows32
	2.1 CIstart
	2.2 CIopen
	2.3 CItalk
	2.4 CIlisten
	2.5 CIclose
	2.6 CIflilex
	2.7 Linking Programs
	2.8 Prototyper
		2.8.1 General
		2.8.2 Cross Environment Conventions
		2.8.3 The Tool
		2.8.4 Training Environment
		2.8.5 Design Environment
		2.8.6 Unit Testing Environment

Chapter - 3  Command Line Interface
	3.1 General
	3.2 Interactive CIsend and CIfetch
	3.3 Interactive CIsubmit
	3.4 Command Line CIsend, CIfetch and CIsubmit
	3.5 CIlink
	3.6 Default Locations
	3.7 Security

Chapter - 4  Print Services
	4.1 General
	4.2 Example

Appendix A  Windows32 Error Code Descriptions
	



Chapter 1 - The Common Interface (CI)

1.1 General

The Common user Interface (also called Real-time Services) is a programming language and operating system (OS) independent program interface for designing and writing Advanced Program to Program Communications (APPC) applications without in-depth knowledge of the underlying conversation calls and concepts. This approach provides maximum conversation functionality without using features that are not consistently supported. The acronym CI is used as a generic reference to the services provided (e.g. "the application was written in CI").

CI is a productivity enhancement tool because its inherent simplicity yields short learning curves and because managers, designers and programmers can define and discuss their application requirements in the same functional terms regardless of OS environment or application language. This means shorter lead times for project implementations and, more importantly, code that can be maintained and enhanced more easily.

There are interactive prototype program tools to accelerate learning, verify design concepts, and facilitate unit testing. CI is designed to isolate the communications functions from the application coding so that applications staff can maintain control of the code. This has positive benefits in costs, lead times, and personnel scheduling options compared to traditional dependency on highly specialized staff for inter-system communications applications.

The interface also provides a common error recovery mechanism that will automatically terminate active conversations with cooperating programs so that they may take appropriate action.

CI calls in a high level language (HLL) return a status that includes a CI specific code that is meaningful to the application developer.

1.2 Basic Conversation Concepts

Conversations are logical connections between cooperating Transaction Programs or TP's. The conversation is used to move information (e.g. records) between TP's. Although at any point in time only one TP can "talk" data and the other must "listen," the TP's can trade talking and listening roles. The conversation takes place on an available session of the underlying communication transport facility, which makes that session "busy" to any other potential users until the conversation has completed. A session is a serially reusable resource between locations over which conversations between TP's take place.







1.3 Configuration Examples for Cooperating TP's

In any conversation there is always both a Source and a Target transaction program. Although the source code for each may look very similar, the distinction is two-fold:

a) The source TP always starts first and then "launches" or remotely evokes its target partner. Conversely, its source partner brings the target to life, although it may remain in execution even if the source exits.




b) The source program always has the first opportunity to "talk" or send data to its
Target partner.

Cooperating TP's can be used in three basic models:

1) Initiator - the TP's can initiate a conversation and immediately exit - typically to start some processing at one or more other locations (the TP's are contained in CL or DCL procedures that can provide the bulk of the processing).

2) Activity - the TP's can initiate a conversation, conduct some unit or batch of work, such as a file transfer, and then exit.

3) Pipeline - the TP's can initiate a conversation and remain in place to service units of work as they become available. This is the way most users operate their systems.

The main point here is that cooperating TP's are very general and flexible in nature. They are simple building blocks that can be applied in whatever way is most appropriate to the application needs.


1.4 CI Conversation Implementation


The underlying simplicity of the CI interface comes from using a small set of calls that base their protocol on common spoken language concepts. This yields an intuitive interface that is easy to apply to a wide range of circumstances.

CIstart for initialization

CIopen & CIclose to open and close conversations

CItalk & CIlisten to "hold" the conversation

All conversations begin when some Source transaction program (TP) causes its cooperating Target TP to be launched at some location in the network. This process of establishing a conversation between cooperating TP's is accomplished with the CIopen call specifying location and TPname. The "location" is a symbolic IP address that points to some node in the network. In the Source TP both the target location and TP name are specified. In the Target TP only the keyword 'REQUESTER' is specified and this is not needed in the Windows32 version. Once this conversation has been established, data may be exchanged between the cooperating TP's.

The protocol for the conversation is much like human conversations. Only one TP can talk at a time (initially it is the Source TP). The talker is also in control of the conversation and can continue talking (sending data with the CItalk call) as long as they like. The listener receives all of this data, and can do nothing else until he receives the over flag.

The talking TP could totally ignore the request in which case the listening TP must either continue listening or terminate the conversation with a CIclose with Abend set. If the listening TP sees the Over flag on its CIlisten call then it is no longer in Listening state. It immediately enters Talking state and thereby gains control of the conversation itself. The roles (and states) of the cooperating TP's are reversed. This simple two-state flip-flop conversation mechanism constitutes the entire protocol. State errors - e.g. calling CItalk when in Listening state - are not fatal, they just return a state violation code.

The use of the Over flag to change control and direction of the conversation (referred to as turning the conversation around) can be done in response to a request or as an unsolicited indication to the cooperating TP to take some action (e.g. confirm what was sent, send data of its own, etc.).

The CIclose operation can either indicate a normal or Abend condition. This information propagates to the cooperating TP, which must also call CIclose.

To summarize, a conversation is opened, data is exchanged through a series of talk and listen operations, and then the conversation is closed.

1.5 Example - Cl File Transfer

A sample program which copies some specific file to a cooperating TP that writes it to some specific file is a good way to understand CI operations.

The process of the "send" file transfer in CI is simply for the source TP to open the input file, remotely start its target partner, and open a conversation. The target TP opens the output file. The source will read records and CItalk them to the partner TP until end of file at which time it does a CIlisten.

For its part, the listening program does CIlisten until it sees the Over flag (indicating end of file) at which time it closes the file and then does a CIclose to indicate to its partner (by the "exited normally" completion code) that the file has been created and closed.




1.6 Platform Comparisons

As stated above, attempts have been made to make everything operate the same on all platforms. This has been accomplished to a large extent, however, there are differences in operating system requirements and differences in programming languages that the programmer must take into consideration. Programmers should read the detailed discussion on the individual subroutine calls for each platform before deciding how best to proceed.

How files are stored on a computer varies among platforms. VMS supports variable length files and multiple versions. Windows32 also supports variable length but not multiple versions. OS/400 does not support either. Instead it provides libraries (directories), which contain files. Files contain named members all of whom have the same record length and field layout regardless of what is put in them. Padding and/or truncation are used to assure this.



Path and file naming conventions vary. This is not only true on the target platform but the way in which a remote file is specified on a given platform may be set up to avoid parsing difficulties. For example, on the OS/400 operating system a proper library, file, member specification is "library/file.member". This will not parse correctly on a VMS or Windows32 system so the convention, library<file;member> is used in many situations. This information is detailed in the discussion on supplied commands.

While the basic information for Print Services is the same on all platforms, the degree of control over the actual print process varies a great deal, from almost none on Windows32 to a large amount of information for the AS/400. On VMS, ways have been devised to place this information in qualifiers associated with the spooled file, which the software can retrieve and pass to the AS/400. This is not possible with Windows32.  To summarize, the basic operations are platform independent. The devil is in the details.











Chapter 2 - CI Calls for Windows32


2.1 Call CIstart(cmn,retcod,role,logtype)

cmn - by reference, longword integer (dummy). This argument, although it must be present, is used only on the AS/400 as a pointer to critical information.

retcod - by reference, 6 characters. The return code argument is present in all CI calls and is always checked by the program on return from a call for error conditions. The actual values vary from call to call and are detailed in the appendix. In general, the first two characters are CI error codes. The remaining four have uses which vary with the underlying communications protocol and while not detailed here should be recorded in case of problems requiring support.

role - by reference, character (output "S" or "T", source or target). It is possible to write a program that can play both roles. The prototyper (see below) is an example. It is wise to check this on return so the program does what is expected.

logtype - by ASCII descriptor (input). For the SNA protocol, DEBUG and TRACE can be helpful. On TCP/IP little can be gained. PROD should be used.


Example


//This is a C++ example. To save space, it is incomplete and used //only to illustrate major points. The program segments //tntechodlg.cpp and tntechodlg.h have been provided in the //distribution as examples. Please examine these for details.

//The calls in Visual Basic are very straight forward. Only long //integer and string variables are used and the "pass by" arguments //are determined in the declaration module. Please examine //Module1.bas and Module2.bas included in the distribution for a //Visual Basic example of the simple echo program.

struct descriptor	PROD;
struct descriptor	PGMDEVNAM;
struct descriptor	TPNAME;
struct descriptor	USER;
struct descriptor	PASSW;

PROD.w_length = (short)strlen(strcpy(PROD.a_pointer, "PROD"));
/* 
 * Attach to the CI resource
 */
cistart(&cmn, retcode, role, &PROD);
if(strncmp(retcode, "01", 2) != 0)
{
    sprintf(logout, "CISTART error %s\n", retcode);
    tntecholog.Write(logout, strlen(logout));
    return(FALSE);
}






2.2 Call CIopen (cmn,retcod,cid,pgmdevnam,TPname,username,password)


cid - by reference, longword integer (output - ID for conversation opened). For the SNA version, up to 16 simultaneous conversation may be opened by a single program. Since only one conversation can be listened to at a time, programmers have not used this functionality. The TCP/IP software does not support multiple conversations and returns the value of zero for the is parameter.

pgmdevnam - by ASCII descriptor, max 256 characters (input). The name of this argument is a hold over from the original SNA version. What is used here in the TCP/IP version is the name, alias or IP address of the computer to which you wish to speak. If the open is being called in a target program, it can have the value of "REQUESTER" as in the SNA version or may be left blank.

TPname - by ASCII descriptor (input). This is the symbolic name of the target program you wish to have the communications manager start on the other computer. Another way of saying this is that it is the "search" name the communications manager will use to identify the program you want it to start. This name will be found in TP.DAT on the other computer.

Username - by ASCII descriptor, max 10 characters (input). The user name or user profile under which the target name is to be run. It and the password are limited to 10 characters to be compatible with the AS/400. Windows32 forces all user names and passwords to lower case.

Password - by ASCII descriptor, max 10 characters (input).

User names and passwords must be left blank for Windows98.

Example

PGMDEVNAM.w_length = (short)strlen(strcpy(PGMDEVNAM.a_pointer, "computer-a"));
TPNAME.w_length = (short)strlen(strcpy(TPNAME.a_pointer, "XYZ"));
USER.w_length = (short)strlen(strcpy(USER.a_pointer, "EZBRIDGE"));
PASSW.w_length = (short)strlen(strcpy(PASSW.a_pointer, "EZBRIDGE"));
/*
 * Open a hailing frequency to the caller
 */
ciopen(&cmn, retcode, &cid, &PGMDEVNAM, &TPNAME, &USER, &PASSW);
if(strncmp(retcode, "01", 2) != 0) 
{
    sprintf(logout, "CIOPEN error %s\n", retcode);
    tntecholog.Write(logout, strlen(logout));
    return(FALSE);
}
	





2.3 Call CItalk (cmn,retcod,cid,data,length,flag)


data - by reference, character (input). This may be up to 32740 characters in size. On the AS/400 it must be that size.

length - by reference, longword integer (input). Number of characters actually desired to be sent.

flag - by reference, 8 character string (input & output). Positional dependant string of Y's and N's. A list is included below.

If length is set to the value minus one (-1) to do a Flush or Over then no data will be sent. In most OS environments including Windows32, a CItalk with length minus one (-1) can also be used to detect the presence of a Break request from the partner TP.



Example

/*
 * Send some data
 */
strncpy(flag, "NYNNNNNN", 8);  //The over flag is set.
strcpy(tranbuf, "Hello world!");
length = strlen(tranbuf);
convert_string_EBCDIC(tranbuf, length);	
citalk(&cmn, retcode, &cid, tranbuf, &length, flag);
if(strncmp(retcode, "01", 2) != 0) 
{
    sprintf(logout, "CITALK error %s\n", retcode);
	 tntecholog.Write(logout, strlen(logout));
    strncpy(flag, "NNNNNNNN", 8);
    ciclose(&cmn, retcode, &cid, flag);
    if(strncmp(retcode, "01", 2) != 0) 
    {
        sprintf(logout, "CICLOSE error %s\n", retcode);
        tntecholog.Write(logout, strlen(logout));
    }
       return(FALSE);
}











2.4 Call CIlisten (cmn,retcod,cid,data,length,flag,type,OSdepend)

length - by reference, longword integer (input max, output actual). Sets a maximum for the amount of data the program is willing to receive. It must be a power of 2 starting with 256. On return, it is the actual number of characters received. This also will be equal to the number of characters that the other computer intended to send.

type - by reference, integer (input). Value of 1. We only support one type of listen, conversation specific. This argument is ignored.

OSdepend - by reference, 10 character(output). Reserved for future use. Ignored.


Example

/*
 * listen
 */
label:  //Note! Cilisten is part of a loop.
memset (buf, 0, sizeof(buf));
type = 1;
length = 256;	
cilisten(&cmn, retcode, &cid, buf, &length,
         flag, &type, osdepend);
If(strncmp(retcode, "01", 2) != 0)
  {
    if(strncmp(retcode, "99", 2) == 0)
    {
         //We got a normal close from the other side
         strncpy(flag, "NNNNNNNN", 8);
         ciclose(&cmn, retcode, &cid, flag); 
         return(TRUE);
    }
    else
    {
        //we got a hard error
	     sprintf(logout, "CIlisten error = %s\n", retcode);
	     tntecholog.Write(logout, strlen(logout));
        return(FALSE);
    }
}
if(length > 0)
{
    //process the data
    convert_string_ASCII(buf, length);
    sprintf(logout, "Data received [%s]\n", buf);
    tntecholog.Write(logout, strlen(logout));
}
if(flag[OVERPOS] != 'Y')
{
    //We must continue to listen
    goto label;
}
//We are now in control of the conversation. We may talk, talk and            //turn the conversation around or close.



2.5 Call CIclose (cmn,retcod,cid,flag)

Example

strcpy(flag,"NNNNNNNN");
ciclose(&cmn, retcode, &cid, flag);
if(strncmp(retcode, "01", 2) != 0)
{
    sprintf(logout, "CICLOSE error %s\n", retcode);
    tntecholog.Write(logout, strlen(logout));
    return(FALSE);
}
exit;

Positional-Coded Flags

The flag encoding mechanism that is used in the CI Conversation Calls is based on an 8 character string where each position represents a particular indicator such as Break or Flush and contains a 'Y' if that flag is "Yes" or "On" (any other value means "No" or "Off"). The following table represents flag value positions (numbered left to right in the string):

	Position	Description	Sent by	Returned to
	1	FLUSH	CITALK                              (used in SNA only)
	2	OVER	CITALK	CILISTEN
	3	reserved
	4	reserved.
	5	BREAK	CILISTEN	CITALK       (used in SNA only)
	6	reserved.
	7	ABEND	CICLOSE
	8	reserved.

2.6 Special CI file transfer function

This CI function is a programming call that allows the complete transfer of a file between the local system from which the call is made and a remote system specified by the location pgmdevnam. The caller need only identify the OS-specific file information on each of the two systems and specify position-dependent flag indicators such as direction of transfer, append or replace file, and whether or not character translation is applied to the entire file.

Call CIfilex(cmn,retcod,pgmdevnam,lclfile,lclmem,rmtfile,rmtmem,flag,username,password)

lclfile - ASCII descriptor, max 64 chars (input). The format depends on the platform. A full file descriptor is allowed here. The 64 character limit comes form the AS/400.

lclmem - ASCII descriptor, max 10 chars (input). Used on the AS/400 only.

rmtfile - ASCII descriptor, max 64 chars (input). The exact form that this takes is platform dependant. In many cases, double quotes may be used.

rmtmem - ASCII descriptor, max 10 chars (input). Used on the AS/400 only.

flag - 16 position control function. Details below..

CIfilex Positional Flag Values

The flag mechanism that is passed to the CI programs is a 16 character string that uses positional values for each option where a value of 'Y' indicates "Yes, True, or On" and all other values are considered "No, False or Off." If using the C language, these position start at zero.

Position	Name	Description
1	FETCH	Fetch if set, otherwise Send.
2	TRAN	Character translation if set.
3	TRUN	Allow truncate if set.
4	APND	Append if exists.
5	REPL	Replace if exists.
6		reserved
7	MNTR	Monitor file transfer
8-16	reserved

Call Sequence

The following sequence of calls must be coded in order to invoke CIfilex.

1. Call CIshell {IBM Midrange Only}

This CI call must have already been made for any CI programs operating in the IBM midrange Environment. CIshell is called only once to invoke the user's CI program even though the program may contain multiple CIfilex calls and/or CI conversations.

2. Call CIstart {All Platforms}

This CI call must have already been made for any CI programs. CIstart is called only once during the user's CI program initialization even though the program may contain multiple CIfilex calls and/or (if CI is installed) CI conversations.

3. Call CIfilex (cmn,retcod,pgmdevnam,lclfile,lclmem,rmtfile,rmtmem,flag,username,password)

This CI service call provides for the complete transfer of a file between the local system from which the call is made and the remote system identified by pgmdevnam. CI must be installed on both systems.

The file may either be sent (moved to the remote system) or fetched (retrieved from the remote system) depending on the setting of the Flag parameter.

Data in the file may be delivered as is or character translation between ASCII and EBCDIC may be applied to the entire file.

CI will not return from the call until either a successful transfer has taken place or some error condition has been detected.

Because IBM midrange system physical files have fixed length records any library/file created will use the maximum record size of the source file. This will result in the "blank padding" of files from systems such as Windows32 which support variable length records (note that later retrieval will create a file that does not compare using the DIFFERENCES or COMP utility unless trailing blanks are ignored).

If you are calling CIFILEX from your Windows  program and wish to monitor the progress of the transfer, set the environment word "PARENT_WINDOW" equal to the CWnd handle, m_hWnd, and set the options variable at position [MNTR] to 'Y' prior to the CIFILEX call. Creating the environmental variable "PARENT_WINDOW" must be done in the code initialization section of your program as follows:

    UpdateData(false);                          // make sure handle is real
    sprintf(temp, "PARENT_WINDOW=%d\0", this->m_hWnd);    // char temp[30]
    _putenv(temp);

 Later:

if(m_monitor)
    options[MNTR] = 'Y';

2.7 Linking programs

Compiled high level language programs must be linked with both the Common Interface verbs and the manufacturer's provided TCP stack. On all systems this is accomplished through the dynamic link libraries provided. Please examine the example noted above to see how this is done.

2.8 The Prototyper

2.8.1 General

An integral component of CI is the Interactive Prototyper module that exists in each OS environment. This section provides a generic description of the tool and a discussion of its application. Each particular OS environment has an intuitive and self documenting implementation.

2.8.2 Cross Environment Conventions

The Prototyper is a special transaction program that displays a menu that allows a user to make CI verb calls interactively. In each OS environment, it is implemented with as much commonality in appearance and operation as practical. This makes it easy for a programmer familiar with the Prototyper in one environment to operate in any other supported environment. This ability to have members of the development team "cross systems" greatly enhances productivity during training and design. The Prototyper is essentially an intuitive learning and testing tool.




COMMON USER INTERFACE

INTERACTIVE PROTOTYPER

 Cistart
 Ciopen
 Citalk
 Cilisten
 Ciclose
 Cifilex


Here are some helpful hints for using the Prototyper:

1. Have ready the name of the remote side.

2. Usually the name for the remote target transaction program (TP) must be entered IN CAPS in the CIopen screen.

3. When the Windows32 side uses CItalk to send a message with the OVER flag set, the remote side receives the OVER with the first CIlisten. When the remote side uses CItalk to send a messages with the OVER flag set, the Windows32 side may need to use CIlisten twice to get the OVER. This is because the AS/400 may not send data and flags at the same time. Please review the CIlisten programming suggestions discussed above.

4. The IBM or the Windows32 side Prototyper target TP user must perform a CIstart, CIopen, and CIlisten. On VMS the CIstart is performed automatically.

5. When the target TP issues a CIopen specifying REQUESTER, the TP name need not be specified. On Windows32, the location may also be ignored.

2.8.3 The Tool

The Interactive Prototyper is a specialized TP that does not execute the CI conversation calls in some predetermined order like a normal application program. Instead it determines the order and parameters for each call by presenting a menu to an interactive user at a terminal.

The Prototyper can be the source program or the target program.

In all cases the Prototyper interacts with the user by providing a series of screen menus with options selected by the user.

The top level menu can appear either as a result of the Prototyper being run as a source TP from an interactive terminal or as a result of some target Prototyper TP allocating a terminal specified for use in that OS environment (e.g. by typing "CISET" in the VMS environment). Windows32 does not need any special treatment.

From the top level menu the interactive user can choose the verb and parameters they desire and execute the calls. Provisions are made for entering data records from the terminal or reading them from a physical file (VMS only) for CItalk. Returns from the calls display the appropriate codes and flags that may have been set by the partner TP. The entire session is a menu-controlled interactive conversation with the partner TP.

For learning and testing purposes it is suggested that whenever CItalk is used the Translate flag always be chosen (this causes the "network transport" level of communication to be accomplished in EBCDIC and the display to be in the "native" character set).

The Prototyper can evoke or be evoked by either a pre-existing TP or its own partner. This feature is extremely important in the development process and is a big improvement over simply "turning the programs loose" against each other (see 2.10.6).


2.8.4 Training Environment

The Prototyper can be used to train applications programming personnel in an extremely short period of time. This is accomplished by providing side by side terminal access to the two (or more) OS environments involved and running the Prototyper as both the source and target TP.

This allows the trainees to directly and interactively experience the effect of various combinations of operations and errors so that they can explore and enhance their understanding by hands-on experience with the product. The availability of a common tool to programmers in different environments will greatly enhance the team effort required to develop effective solutions to integration requirements. If only a single screen is available, you can use the Prototyper against a "Target echo" program (TVAXECHO or TIBMECHO) which will simply send back whatever is sent to it (this is a good technique for verifying that APPC is working properly).

2.8.5 Design Environment

This is a further use of the Prototyper environment discussed above. As in that environment, side by side terminals will operate Prototyper TP's, but here the objective is for designers to verify their TP design by actually "playing" its sequence of events to insure that (a) everybody meant the same thing when they agreed on the design, and (b) that it actually works out as had been envisioned.

This activity can take place very early in the design cycle so that concept testing need not wait for investment in the production of code.

2.8.6 Unit Testing Environment

Once a design has been verified and documented, the actual cooperating TP's can be developed. Without the Prototyper, TP's cannot be verified without "running against" their cooperating partners. This creates the potential for a lengthy and chaotic test phase since "compensating errors" can make two TP's "appear" as if they are working properly and "interacting errors" can produce results which are very puzzling and difficult to debug because they "span TP's" and therefore are not apparent from individual analysis of a single component.

It is therefore prudent for each developer (or development team) to verify that their TP is doing what they expect it to do under various data driven and error driven circumstances. The Prototyper is an excellent tool to accomplish such unit testing before individual TP's are permitted to "run free" against their partner programs. As discussed above, the Prototyper TP can be run as either a source or target against either the Target or Source customer-designed TP's. It is possible to send any kind of data and generate any kind of error sequence interactively. This allows the TP's to be debugged by "driving" the various paths with the Prototyper playing the role of each cooperating TP.
















Chapter 3 - Command Line Interface


3.1 General

In addition to the High Level Language (HLL) call described above, CI functions can also be accessed by running specific programs or from ci_menu.exe.

The CI distribution includes the programs that are available for file transfer between various systems. The programs cifetch and cisend can be issued at the interactive user level . Hence, there are two ways in which file transfers can be accomplished with CI, because the cifilex function call described in the previous section can be invoked by any high-level language (HLL).

The  DTS distribution also includes a program that is available for executing command strings on remote systems. This command, cisubmit, can be issued at the interactive user level.

NOTE: The AS/400 target program for CIsubmit puts out completion messages each time it is run. These messages appear both in the job log and in the QSYSOPR message queue.

A data area CISBMDEF has been provided to control this action. If it contains 'NO', 'no', or 'No', the messages to QSYSOPR will not be sent.

























3.2 Interactive CIsend and CIfetch (both screens are nearly identical)



Translate - default is YES. Translation being YES by default insures that text files are always handled properly. In this mode data records, while "in" the network, are always in EBCDIC . These same records, when "leaving" the network, are always translated to the OS default (e.g. ASCII on Windows32).

Special cases where one might not translate are those involving non-text data or when both the source and target systems are the same OS.

Replace - default is NO. This option allows one to replace an existing file or member. The default state "NO" prevents one from accidentally replacing a file or member when that was not the intent (e.g. not knowing the file or member already exists).

Append - default is NO. This option allows one to append data to an existing file or member. The default state "NO" prevents one from accidentally appending data when that was not the intent (e.g. not knowing the file or member already exists).

Truncate - default is NO. Applies to IBM mid-range systems only. On these systems if one is transferring to an existing IBM destination file (replace, append, or new member) the maximum length has already been determined by the fixed length characteristic of the file when it was originally created. Setting truncation on will allow any records that are longer than this maximum to be truncated and stored in the file.

Monitor - default is YES. This option causes a graphic display of the percent complete for the file transfer to be displayed. It is only valid for interactive source jobs.

Security - default is NONE. This option allows one to use the username/password account on the remote system instead of the default account. Any VMS username specified must have TMPMBX, NETMBX, and SYSLCK privileges.

3.3 Interactive Cisubmit



3.4 Command Line Cisend, Cifetch and Cisubmit

CISEND_CMD, CIFETCH_CMD and CISUBMIT_CMD are versions of the windows interactive programs which can be used in .BAT or similar files to carry out the functions without being in interactive mode. They take a series of command line arguments which are reminiscent of UNIX. In general each switch that involves a yes/no choice consists of a plus sign to assert TRUE or a minus sign to assert FALSE followed by a single lower case letter suggesting which logical value is to be asserted.

For arguments that indicate an associated argument will follow, we use a minus sign and a single lower case letter followed by a space and the associated argument. In all cases, all command line arguments are space delimited. The following letters have a plus or minus sign implied. Signs are not written here because of printing requirements.

c	Truncate	Default FALSE
t	Translate	Default TRUE
p	Replace	Default FALSE
a	Append	Default FALSE

l	Local File
r	Remote File
m	Remote Member
u	Username
s	Password
w	Location
z	Path and File Name where the return code will be written.
c	Cisubmit Only, The Command


cisend_cmd -l c:\test\data.test -r test/citest -m member2 +p -u name -s password
 -w computer_name -z c:\temp\retcode.dat

A Few notes on this approach. The remote file specification for IBM files is library/file and the optional -m for the member name. Windows32 not being batch oriented, we decided to put the return code results in a user selected data file. This file may then be processed for the end result of the command according to the desires of the programmer.
	
3.5 Cilink - Checking the status of the link.



CIlink is a program that allows the user to determine if the desired link is functioning prior to actually running programs. The first operation must be the "ping" operation. If the user were to test for the presence of the other computer's communication manager when the other computer was unavailable, the program would lock up and time out after 8 minutes.

While the program will immediately report as an error a location which the system cannot identify, legal locations will allow the system to attempt the ping operation. The operation will return the same status regardless of whether the other computer is responding. Therefore the user must watch the operation to make the determination himself. Do not attempt to check for the presence of the communication manager if the ping operation times out.

If the other computer is responding to the ping, checking the communications manger will immediately return an answer regarding the communication manager's availability on that machine.



3.6 Default locations

The administrator may provide for a system wide default location. The individual user may provide his own by using the system control from the system control panel and defining the environmental variable, DEFAULT_LOCATION, to be the desired value.




3.7  Security WindowsNT/2000

CI target transaction programs run under Windows32 as separate processes. The context of these processes can be controlled by supplying security information, provided that the communications manager was started by a user with the appropriate privileges. Please see the installation guide for a detailed discussion of these privileges.

CI will verify remotely supplied username/password security data. Invalid security information will be rejected and an appropriate return status transmitted to the remote system. In the case of the system receiving a valid username/password pair, the transaction program will be started using the privileges and context of the given username.

















Chapter 4

Print Services

Windows32to AS/400 or VMS Print Services

4.1 General

Windows32 Print Services is a set of programs that allows the transmission of Windows32 print files from Windows32 to any remote system. The Windows32 program runs as a background process and monitors a user-defined list of Windows32 queues (directories). When a file is placed onto one of these queues, Print Services converts it to EBCDIC and transmits it to a remote output queue, where it is printed as if it were a normal spool file. Both the output queue and the system that it resides on are specified by the administrator utilizing a simple text editor.

4.2  Example

   30
   c:\rick\printv\ charm ttb1: * * *
   c:\rick\printa\ lepton RICK/RICK * EZBRIDGE EZBRIDGE

The first record consists of the delay in seconds between scans of the listed directories for files.

Each subsequent record contains space delimited fields as follows:

Field 1: The path of the directory into which files will be placed to sprint on the computer specified.

Field 2: The name, alias, or IP address of the computer on which the files are to be printed.

Field 3: The output queue on the remote printer on which the file is to be printed.

Field 4: The form name to be associated with the print file. the "*" means standard or default.

Fields 5 and 6: The user name and password associated with the operation of transferring and queuing the file. "*"'s mean the default user.







Appendix A - Windows32 Error Code Descriptions

00	CI$_CALTWI	Function order error - CIstart has not been called - no action possible or - CIstart has already been called - no action taken
01	CI$_NORMAL	Normal successful return from CI function
02	CI$_BADPAR	Parameter error - Too few or missing parameters
04	CI$_COMERR	Communications error - Cannot start partner program
07	CI$_INVSTA	Invalid state, program must listen - CItalk or - Not in the proper state (talk) to end conversation without Abend
09	(none)	Timer expired {IBM only} - CIlisten
11	CI$_INVCID	Invalid CID, no such conversation
12	CI$_INVSIZ	Record rejected, exceeds 32740  max length
13	CI$_INVTYP	Multiple or missing TYPE (c)listen)
14	CI$_NOCIDS	No posted CIDs (c)listen)
15	CI$_BADLEN	Unsupported length (IBM must = 256,512,1024,2048,8192 or 32768) - CIlisten
16	CI$_BUFOVF	Buffer size exceeded - Record truncated to length specified in call (return length = actual) - CIlisten
20	CI$_MISFIL	File or member does not exist
21	CI$_LBALIB	Local library or dir doesn't exist
22	CI$_RBALIB	Remote library or dir doesn't exist
23	CI$_BADCRE	Could not create file or member
24	CI$_EXISTS	File or member already exists
25	CI$_INVLCS	Local specification invalid
26	CI$_INVRMS	Remote specification invalid
27	CI$_TRUPAD	Truncation or padding not allowed
28	CI$_OPTCON	Option conflict
29	CI$_BADOPT	Option not supported
30	CI$_INVPID	Invalid program ID
31	CI$_BADREV	Incompatible revision level
32	CI$_NOAUTH	Could not access file; insufficient authority
41	CI$_CONERR	Conversation was active when CISHELL was exiting
51	CI$_TRANER	File Transfer did not complete normally
61	CI$_SUBERR	CIsubmit failed
62	CI$_PSVERR	Print Services failed
63	CI$_SPLERR	Local Spool file doesn't exist or is not ready
64	CI$_ROQERR	Remote output queue doesn't exist or is invalid
77	CI$_ABNDER	Partner ABEND de allocation error - link down, program failure, or Abend flag set
99	CI$_DEALLO	Normal de allocation - Partner program ended the conversation normally

