












                ______________________________________________


                        Distributed Transaction System

                               DTS OS/2 Gateway

                                 Release 010

                ______________________________________________










                           U S E R ' S    G U I D E









                                First Edition    
                                January 1990













                                                             



                                                  
                         (c) Copyright DIGITAL 1990
                             All Rights Reserved
 DTS OS/2 Gateway (c) User's guide    Contents                               I
 _______________________________________________________________________________



         Contents
         --------


         1. General ...............................................   1-1

               Example DTS network ................................   1-2

         2. YFIAPPC ...............................................   2-1

               General ............................................   2-1
               YFIAPPC's calling model ............................   2-2
               YFIAPPC's parameters ...............................   2-3
               Input parameter area's contents ....................   2-4
               Output parameter area's contents ...................   2-7
               Programming rules ..................................   2-8

         3. Subroutine called by DTS ..............................   3-1

               General ............................................   3-1
               Subroutine's calling model .........................   3-1
               Subroutine's parameters ............................   3-2
               Parameters .........................................   3-3
               Programming rules ..................................   3-4

         4. Testing programs ......................................   4-1

               General ............................................   4-1

         5. DTS system management and parameterisation ............   5-1

               General ............................................   5-1
               DTS parameters for remote nodes ....................   5-2
               DTS parameters for spooling ........................   5-3
               DTS parameters for local subroutines ...............   5-3
               DTS parameters for trace ...........................   5-3

         6. DTS architecture and internal structure ...............   6-1

               Layered architecture ...............................   6-1
               Message compression ................................   6-2
               Routing of the subroutine call .....................   6-3
               Recovery implementation ............................   6-5
               DTS OS/2 GW environment ............................   6-6

         7. Installation ..........................................   7-1

               Installation from diskette .........................   7-1
 DTS OS/2 Gateway (c) User's guide    General                              1-1
 _______________________________________________________________________________



         1. General
         ----------

         DTS is a general purpose transaction link which makes it
         possible for a subroutine in computer B to be called from
         computer A. DTS implements the Remote Procedure Call (RPC).

         In practise this has been arranged so that program YFIAPPC is
         always called in computer A. YFIAPPC is sent parameters
         informing it of, amongst other things, the actual subroutine's
         program name and the computer node name. After this the
         DTS system contacts computer B and makes the subroutine call.

         A maximum of 32,000 bytes can be sent to the subprogram in
         computer B. The subprogram can return a maximum of 32,000
         bytes to the calling program.

         The subroutine call can be made in three different ways.

         1. 'Real-time call', the calling program waits until
             subprogram execution has been completed. The calling
             program also immediately receives the subroutine's
             possible output parameters for its own use.

         2. 'On-line' call, as real-time, but if the connection does
             not immediately succeed, so the subroutine call is stored
             in the buffer and is made right away when the connection
             comes back into use. The calling program is able to
             continue immediately after the subroutine call has been
             executed or buffered. With this function, however, the
             subroutine cannot return any parameters to the main program
             because the main program execution may have completed
             prior to the subroutine even having started.

         3. 'Batch' as before, but the call is not even attempted
             immediately but is only written to file and executed later
             after the time interval set in the DTS parameters.

         A recovery mechanism has been built into the system which
         ensures that no subprogram calls can possibly disappear
         or be duplicated in an error situation. The system carries out
         its own locks in both computers and is able to manage recovery
         even if the computers are rendered inoperative or
         communications lines are disconnected during message
         transmission.

         DTS OS/2 Gateway supports both SNA LU6.2 and DECnet/OSI 
         protocols and can routing transactions between DECnet/SNA
         networks.

         At this time the DTS system has been completely built for
         VAX/VMS, OS/2 PC:s, IBM/CICS and AS400.
 DTS OS/2 Gateway (c) User's guide    General                              1-2
 _______________________________________________________________________________



         Example DTS Network
         -------------------

         Each computer in this network can call any other computer via DTS.






                                          +---------------+
         +-------+    +-------+           !               !
         !OS/2 PC!    ! AS400 !           !               !
         !       !    !       !           !  IBM          !
         !DTS    !    ! DTS   !           !  Mainframe    !
         +-------+    +-------+           !               !      +-------+
            !            !                !  CICS         ! APPC !OS/2 PC!
       APPC !            ! APPC           !               !------!       !
            !  ......... !                !  DTS          !      !DTS    !
            !..         .!                !               !      +-------+
            !             .               !               !
           .  TOKEN RING  .               !               !
           .             .                +---------------+
            ..         ..                         !
              .........                           !
                !                                 !
                !                                 !
           APPC !                            APPC !
                !                                 !
            +-------+                        +----------+
            !OS/2 PC!                        !Digital   +
            !DTS    ! SNA PU 2.1             !DECnet/SNA! SNA PU 2
            !Gateway!                        !Gateway   !
            +-------+                        +----------+
                !                                 !
                !                                 !
                ! DECnet/OSI                      ! DECnet/OSI
                !                                 !  
                !                                 !  
                !                     Ethernet    !  
       +-------------+--------------------+-------+---------------+---------+
                     !                    !                       !
                     !                    !                       !
          DECnet/OSI !         DECnet/OSI !            DECnet/OSI !
                     !                    !                       !
                     !                    !                       !
                 +-------+         +-------------+         +-------------+
                 !OS/2 PC!         !             !         !             !
                 !       !         ! Digital VAX !         ! Digital VAX !
                 !DTS    !         !             !         !             !
                 +-------+         ! DTS         !         ! DTS         !
                                   !             !         !             !
                                   +-------------+         +-------------+

 DTS OS/2 Gateway (c) User's guide    YFIAPPC                              2-1
 _______________________________________________________________________________



         2. YFIAPPC
         ----------

         Instructions/documentation for DTS client service YFIAPPC.



         General
         -------

         YFIAPPC is a DTS function, which uses the LU6.2/APPC or DECnet/OSI
         protocol or both to communicate with other computers. YFIAPPC
         makes it possible to call, for example, a subroutine in VAX or IBM,
         from an OS/2 computer.

         Maximum message length is 32,000 bytes. Message data can be
         in either character or binary form. Both character and
         binary forms cannot be in the same message or used
         at the same time if there are different character
         representations in the two communicating computers
         e.g. ASCII/EBCDIC. DTS carries out any needed
         character conversion.

 DTS OS/2 Gateway (c) User's guide    YFIAPPC                              2-2
 _______________________________________________________________________________




         YFIAPPC calling model/function definition.
         ------------------------------------------

         void YFIAPPC (InputMSG, InpLength, OutputMSG, OutLength)

         unsigned char  *InputMSG;
         unsigned short *InpLength;
         unsigned char  *OutputMSG;
         unsigned short *OutLength;



         InputMSG  Pointer of user input data area, message to be send.
                   DTS not change the contents of user message, so after
                   YFIAPPC call this area is unchanged except first 39
                   bytes (DTS header). Exception is function code 04,
                   then input area is unknown after call.

         InpLenght Pointer of length variable which indicates the length
                   of input message in user area. Length is 2 bytes binary
                   number. User set this.

         OutputMSG Pointer of user output data area. DTS puts the received
                   message to this area. Area must be so big that there are
                   enough room for the biggest message (max 32000 bytes). 

         OutLength Pointer of length variable which indicates the length
                   of received message in out_area. Length is 2 bytes binary
                   number.

      
         All pointers are far pointers (32 bit addressing). User must set all
         parameters except out_length before YFIAPPC call. DTS set the right
         value to out_length. Look also example program YFIA.C.
     


         YFIAPPC's Calling example in OS/2
         ---------------------------------

         YFIAPPC is function, written in C language, which is located in
         DTS.DLL dynamic link library. DTS.LIB has produced with IMPLIB
         utility from DTS.DLL.

         unsigned char  IMSG[32000];
         unsigned short ILength;
         unsigned char  OMSG[32000];
         unsigned short OLength;
         ...

         YFIAPPC(IMSG, &ILength, OMSG, &OLength);




         Look also an example program YFIA.C in installation kit.
 DTS OS/2 Gateway (c) User's guide    YFIAPPC                              2-3
 _______________________________________________________________________________



         YFIAPPC's parameters
         --------------------

         The parameters are at the beginning of the message, the input
         parameter area is the message's first 39 bytes = DTS header.
         The only output parameters are the return code and
         the possible response data. The return code is in the first
         2 bytes of the output area. The application program does not
         have to set parameter fields other than those marked with
         asterisk (*) characters. After YFIAPPC's call the application
         program can also investigate the parameters set by DTS
         if necessary.







                           YFIAPPC's input parameter area
                           ------------------------------
                         1 Timestamp
                           YDDDHHMMSSXX      char (12)
                         2 Status            char  (1)
                         3 Sender            char  (8)
                      *  4 Receiver          char  (8)
                      *  5 Function code     char  (2)
                      *  6 Handler ID        char  (8)
                      *  7 Message           char  (*)

         (Handler ID = logical name of the remote subroutine)






                           YFIAPPC's output parameter area
                           -------------------------------
                         8 Return code       char  (2)
                         9 Message           char  (*)




 DTS OS/2 Gateway (c) User's guide    YFIAPPC                              2-4
 _______________________________________________________________________________



         Contents of the input parameter area
         ------------------------------------


         1 Timestamp YDDDHHMMSSXX
         ------------------------

         When YFIAPPC is called by a certain message for the first time,
         YFIAPPC always places in this field the year, day and clock
         time. XX contains hundredths of a second. This together with
         the sender is the message's ID for its whole lifetime.
         DTS ensures that the timestamp is unique for every
         different message, even if the messages are processed
         in exactly the same hundredths of a second.


         2 Status
         --------
         YFIAPPC records its own status code here which is intended for
         its own internal use. Possible values are:

                        0  Default value which is placed when the
                           message comes for the first time to
                           YFIAPPC.

                        1  Message is being processed. When YFIAPPC
                           is called with a function code which has
                           a recovery characteristic specified and
                           when connecting to another computer the
                           message does not transmit successfully
                           due to computer error or similar.
                           The message will be written on disk with
                           status = 1 which indicates that the message
                           has already been sent once and has not been
                           transmitted successfully.


         3 Sender
         --------
         YFIAPPC puts the identifier of the sending computer here.


         4 Receiver (*)
         --------------
         The receiving computer's identifier is set by the application
         program. The computer node in question has to be set for DTS.


 DTS OS/2 Gateway (c) User's guide    YFIAPPC                              2-5
 _______________________________________________________________________________


         5 Function code (*)
         -------------------
         YFIAPPC's function code. The function code is a 2 bytes long
         code which defines the DTS function to be carried out.
         Both bytes of the code XY are independent of each other.
         The different codes are described below:

                       X=0  Character conversion is needed and it is
                            done to the message in the DTS.

                       X=1  Character conversion is not done to
                            the message in the DTS.

                       X=2  The message is compressed in the sending
                            computer, decompression takes place in the
                            receiving computer and character
                            conversiona are also done in the DTS.

                       Y=1  Message is sent and the response is required
                            in real time.

                       Y=2  Message is sent on-line, in other words
                            an attempt to send is made immediately.
                            However, if the transmission does not succeed
                            the message is filed for a later attempt.
                            The calling program receives a 00 return code
                            immediately when the transmission has
                            succeeded or a 01 return code when the
                            message is recorded successfully on file.

                       Y=3  The message is filed for later sending.
                            The calling program receives a 00 return
                            code right away when the message has been
                            recorded on file.

                       Y=4  All the messages which have been recorded
                            for later sending are sent. The messages
                            are deleted from this file when the later
                            transmission succeeds. If the transmission
                            fails due to a logic error (e.g. the
                            parameter defined handler or subroutine does
                            not exist) then the message is written to
                            the error log and is deleted from the earlier
                            file. Return code 00 is given if all the
                            messages recorded for later transmission have
                            either been successfully sent or have been
                            transferred to the error log. DTS calls
                            itself with this function code at the
                            intervals set in the DTS parameters,
                            this code has not been intended for use 
                            by applications.

         The following combinations of functions have been reserved
         for use by applications: 01,02,03,11,12,13,21,22,23.
 DTS OS/2 Gateway (c) User's guide    YFIAPPC                              2-6
 _______________________________________________________________________________



         6 Handler's ID (*)
         -------------------
         The logical name of the remote message handler which corresponds
         to a specified physical program module. Based on this a quite
         specific subroutine is initiated in the other computer to which
         the message is sent.

         7 Message (*)
         --------------
         Data which is sent to the subroutine in the other computer
         in addition to the previously described parameters.



 DTS OS/2 Gateway (c) User's guide    YFIAPPC                              2-7
 _______________________________________________________________________________



         Contents of the output parameter area
         -------------------------------------


         8 Return code
         --------------
         YFIAPPC's own return code which reports the success of the
         data transfer. This return code is in no way associated with
         the return code which is given by the possible message handler
         which is message data to YFIAPPC. Possible values:

                        00  Completed successfully

                        01  Completed successfully,
                            the on-line message has been sent with
                            function code 02 but the line has not
                            functioned. The message has been written
                            to the file to be saved for later
                            transmission.

                        10  Unknown receiver node.

                        11  Receiver node environment variable not ok

                        12  Spooling environment variables not ok  

                        20  Message handler is unrecognised in the
                            receiving computer.

                        30  Data communications error, link fails.

                        31  Communications Manager not loaded  

                        32  Error in character conversion -CONVERT-  

                        33  APPC not started in Communications Manager  

                        34  DECnet error: xxxxxx...                     

                        40  Input parameter errors,
                            e.g.  unknown function code.

                        60  A message buffer has been emptied with
                            function code 04, but all the messages were
                            not sent because the data communcations links
                            did not function. The messages will be sent
                            as soon as the link becomes operational.

                        70  Protected resource, the subroutine call
                            with the given parameters is not allowed
                            in the other computer.

                        90  Not enough memory available -DosAllocSeg-  

                        91  DTS not correctly installed, DTS_LOG ???  

         9 Message
         ----------
         The response data which is returned from the called subroutine
         in the other computer.
 DTS OS/2 Gateway (c) User's guide    YFIAPPC                              2-8
 _______________________________________________________________________________


         Programming rules
         -----------------

         - Operation codes x1 should not be used in other than
           'non updating ' operations. In other words when, for example,
           another system's database is read, so the codes in question
           stay in place.

         - Function codes x2 and x3 are intended for updating operations,
           when these codes are used DTS guarantees that the
           subroutine call is performed successfully just once in the
           required computer. DTS also ensures that the calls are
           performed in the exact sequence as they were created in the
           sending system.
           (timestamp order).

         - Although DTS message length (subroutine parameter area)
           is a maximum of 32,000 bytes, it is not all at the disposal
           of the application. DTS needs the first 39 bytes for its
           own header, but in addition, for example, routing might demand
           another 39 bytes. DTS looks after this sort of extra header
           itself and the user is not even aware of it. The user has to
           be aware not to send, however, the absolute maximum length.
           If the application sends a maximum of only 31,800 bytes, then
           one can be sure that all possible headers will be accomodated.

         - If some application transfers a large amount of data to
           another system through DTS e.g. copying a file, then the
           application should send the data in as large blocks as
           possible. This is a lot more efficient than sending
           data in small blocks. Every YFIAPPC call loads the machine
           to the same degree almost regardless of the quantity of data.
           If, for example, 1 Megabyte of information is transferred
           to another computer in 30,000 byte chunks, 34 YFIAPPC
           calls are needed. If the same quantity of information
           is transferred in 1,000 byte chunks, 1,000 calls are
           required. The latter method is approximately 30 times
           heavier on resources.

         - When the messages are taken from spool to the other DTS
           system if some logical error occurs which is the sort not
           worth sending again, the message is transferred to the
           DTS_ERROR file. This sort of 'error caller' can be located
           with the normal DIR command. The logical error could be such
           that a subroutine is called which does not exist in the other
           system or its calling has not been permitted.
                               
 DTS OS/2 Gateway (c) User's guide    Subroutine called by DTS             3-1
 _______________________________________________________________________________



         3. Subroutine called by DTS
         ---------------------------

         Rules/documentation on how DTS transfers an external incoming
         call to a user subroutine. The calling method and how the
         subroutine has to be coded is described here.






         General
         -------

         The application subroutine which is called by DTS can be coded
         in any of the programming languages which supports the OS/2
         runtime dynamic linking. Each user subroutine, which are called
         from remote system via DTS, must be in some Dynamic Link Library
         (.DLL). The DLL must locate in some of the LIBPATH directory (Look
         Your CONFIG.SYS LIBPATH variable). DTS use the OS/2 runtime
         dynamic link, when it calls user subroutines, so it is not
         necessary to link those sobroutines with DTS. However DTS 
         must know the DLL name where the called subroutine is. We
         use the environment variables to tell this to DTS.





         Calling model of the subroutine 
         -------------------------------

         Format is same than YFIAPPC, but subroutine must use the PASCAL
         calling conventions, so the format is

         void far pascal XXX (&inp_area, &inp_length, &out_area, &out_length)

         DTS reserves all areas, user subroutine input parameters are in 
         inp_area and total length of them in inp_length. User subroutine
         must put its output parameters to out_area and length of them in
         out_length. User subroutine must set out_length atleast 2, because
         DTS needs itself those 2 bytes, so user can not use the first 2
         bytes in out_area. Look also some example program in DTSEXSUB.C
         file.
   



 DTS OS/2 Gateway (c) User's guide    Subroutine called by DTS             3-2
 _______________________________________________________________________________



         The subroutine's parameters
         ---------------------------

         The parameters of the subroutine is of exactly the same form
         as in the earlier described YFIAPPC. The subroutine
         has to set the parameters marked here with an '*', the other
         parameters cannot be changed by the subroutine.




                    Subroutine's parameters
                    ------------------------
                  1 Input parameter area address 
                  2 Input message length         
                  3 Output parameter area address
               *  4 Output message length        






         1 Input parameter area address
         ------------------------------
         DTS has put here the memory address of the first byte of its
         transferred parameter area. The area pointer is the far     
         pointer.


         2 Input parameter area length
         -----------------------------
         DTS has placed the total length of its transferred parameter
         area here.


         3 Output parameter area address
         -------------------------------    
         DTS has put here the memory address of the first byte of its
         reserved user output area. The area pointer is the far     
         pointer and max user msg lenght is 32000 bytes.


         4 Output parameter area length  (*)
         -----------------------------------
         The user's subroutine records the total length of its output
         message here. The output length is always at least 2 bytes
         in other words the length of the return code.
 DTS OS/2 Gateway (c) User's guide    Subroutine called by DTS             3-3
 _______________________________________________________________________________



         Parameters
         ----------

         The input parameter area which is given to the user's subroutine
         is the same as the sending application program made in the
         other system. At the beginning of the parameter area is also
         the 39 byte DTS header prior to the application data. The
         subroutine can take advantage of the header information if it
         wants to know which computer node made the call. The DTS header
         has been described in connection with YFIAPPC.

         The subroutine's input parameter area


          __________________________________________....___________
         !                !                                        !
         ! DTS Header     !      Application's own data            !
         !________________!________________________....____________!
         !
         !    39 bytes       recommended max 31,800 bytes
         !<--------------> <-------------------------------------->
         !
         !                    max 32,000 bytes
         !<------------------------------------------------------->
         !
         V
         Input area's address 





         The output parameter area has its two first bytes for the
         DTS return code and the remainder is available for use by the
         application. Please note, however, that the first two bytes
         of the area it has reserved have to be left unused.


         The subroutine's output parameter area


          ______________________________________....___________
         ! DTS return-!                                        !
         ! code space !      Application's own data            !
         !____________!________________________....____________!
         !
         !  2 bytes       recommended max 31,800 bytes
         !<----------> <-------------------------------------->
         !
         !                    max 32,000 bytes
         !<--------------------------------------------------->
         !
         V
         Output area's address


 DTS OS/2 Gateway (c) User's guide    Subroutine called by DTS             3-4
 _______________________________________________________________________________


         Programming rules
         -----------------


         - DTS guarantees recovery from error situations when remaining
           inside the basic OS/2 task. If one wants to start a new OS/2
           task from the subroutine, the application programmer has to
           take care of recovery him/herself inside this new task.

         - The subroutine's execution time (wallclock time) should be
           as short as possible, preferably only a few seconds, a
           maximum of approximately 5 minutes. The reason for this
           is that the communication conversation to the other computer
           is active continuously and is reserved during the execution
           of the subroutine.

         - The subroutine should not intentionally go into an crash.
           DTS repeats the transmission after the call's parameterised
           time interval after a possible crash. If the subroutine
           continually crashes it will terminate all message traffic to
           the node in question because DTS wants to perform the calls
           in time sequence. No call which is created later from the
           node in question will come through until the crashed call
           in question has been successfully executed. This rule
           applies to messages sent with x2 and x3 function codes.

         - When a subroutine has been intiated from a second system
           the initiated subroutine can call YFIAPPC again and by means
           this means call a third system's subroutine. It is, however,
           worth carefully examining whether the call in question is
           required synchronously (function codes x1 and x2). If the
           call is synchronous so the subroutine's original initiator
           in the first system also waits for the third system's
           subroutine's termination (because the second system also
           waits). DTS completely supports this type of operation, but
           from the standpoint of resource utilisation it is better if
           the second system calls the third asynchronously
           (function code x3).

         - It is very important, that user own subroutines release all
           resources what they have reserved. So, if subroutine opens
           a file it must also close it. The DTS Back_End server is a one
           simple process, and all subroutine calls are processed under
           that same process.
     
 DTS OS/2 Gateway (c) User's guide    Testing programs                     4-1
 _______________________________________________________________________________



         4. Testing programs
         -------------------



         General
         -------


         DTS has two transactions for application program testing;
         YFIA.C and LU62LOOP.C. YFIA/LU62LOOP is intended for testing any 
         application program or for testing DTS itself.

         If you like to debug Your Back_End programs (and of course You like
         to do that !) You must link that subroutine with some test program
         which calls normally your subroutine. You can modify YFIA program
         easily for that purposes, just replace the YFIAPPC call to your
         own subroutine call. Remember that subroutine call uses the Pascal
         calling convention !

         You can use also DTS trace utility to look and record all incoming
         and outgoing messages to disk. You must set the DTS_TRACE 
         environment variable in the CONFIG.SYS and boot your PC
         before trace is activated.

         It is also possible to use Communications Manager trace or DECnet
         utilities like NCP.

 DTS OS/2 Gateway (c) User's guide    Management and parameterisation      5-1
 _______________________________________________________________________________



         5. DTS system management and parameterisation
         ---------------------------------------------


         General
         -------


         When DTS is once installed and parameterised, it need not
         generally be touched again, only when the system is changed.
         These sort of changes can be, for example, when adding new
         application programs or new nodes. So that covers
         the production side. However, on the test side where programs
         are developed, it is even more worth operating with DTS. DTS
         provides a number of tools for program testing such as trace
         for the saving of arriving subroutine calls for analysis etc.
         use of these in program testing saves a lot of time and trouble.


         DTS usually recovers from all error situations under its own
         control. DTS does not require operator action when, for
         example, there is a break in the line connection, in this
         case DTS automatically starts to spool messages which would
         otherwise be transmitted over the disconnected line. When the
         line connection is re-established DTS automatically transmits
         all the spooled messages from the system where they were
         created and spooled.


         If one of the LU6.2 pipes is corrupted because a remote PU
         connection goes inoperative in the middle of a conversation,
         DTS guarantees recovery, but is not necessarily able to get
         the data traffic started again. Then the LU in question is
         in some error situation when looking at it with NCCF. If
         the LU is corrupted it has to be INACTivated and ACTivated with
         NCCF, if NetView is available this process can be automated.
         Anyhow when LU is again operational then DTS starts to use
         it again with no need for any other action.


         All DTS system parameters are OS/2 environment variables and
         must set in CONFIG.SYS file. There are example DTS configuration
         file DTS.CFG in installation kit.

 DTS OS/2 Gateway (c) User's guide    Management and parameterisation      5-2
 _______________________________________________________________________________



         DTS parameters for remote nodes
         -------------------------------


         Parameters for DTS remote node. There can be any number of           
         remote node definitions, your communication manager and/or DECnet    
         configuration must be compatible with these. Format:                 
                                                                              
         DTS_ND_AAAAAAAA= BBBBBBBB CCCCCCCC D EEEEEEEE FFFFFFFF GGGGGGGG XX TT
                                                                              
         AAAAAAAA    DTS remote node name                                     
         BBBBBBBB    Local DTS node name                                      
         CCCCCCCC    DTS routing node name or '-' character if no routing     
         D           Automatic data Compress (Y=Yes, N=No)                    
         EEEEEEEE    Remote LU alias name (APPC) or DECnet node name (DECnet) 
         FFFFFFFF    Local LU alias name (APPC) or string DECnet (DECnet)     
         GGGGGGGG    Name of mode entry (APPC) or - (DECnet)                  
         XX          Allocate type (Wait,Free,Immediate) and syncronizing     
                     level (0=no,1=commit) or count of remote objects(DECnet) 
         TTTTTTTT... Remote transaction (APPC) or object (DECnet) name,       
                     max 14 characters.                                       
                                                                              
                                                                              
         Examples:                                                            
    
    Remote DTS       Local    Routing  C Remote   Local    Mode     AS Tran or
    Node             Node     Node     P LU/Node  LU Alias Entry    NR Object
    ---------------  -------- -------- - -------- -------- -------- -- --------
SET DTS_ND_ANT001  = PS/2     TINFOCIC Y TINFOCIC PBR04    PSLU62   W1 YLUX
SET DTS_ND_DEMOCICS= PS/2     TINFOCIC Y TINFOCIC PBR04    PSLU62   W1 YLUX
SET DTS_ND_FINN01  = PS/2     TINFOCIC Y TINFOCIC PBR04    PSLU62   W1 YLUX
SET DTS_ND_FINN01_C= PS/2     TINFOCIC Y TINFOCIC PBR04    PSLU62   W1 YLUX
SET DTS_ND_FINN02  = PS/2     TINFOCIC Y TINFOCIC PBR04    PSLU62   W1 YLUX
SET DTS_ND_HAM001  = PS/2     TINFOCIC Y TINFOCIC PBR04    PSLU62   W1 YLUX
SET DTS_ND_LON001  = PS/2     TINFOCIC Y TINFOCIC PBR04    PSLU62   W1 YLUX
SET DTS_ND_MEMOAPI = PS/2     -        Y TINFOCIC PBR04    PSLU62   W1 YLUX
SET DTS_ND_NYC001  = PS/2     TINFOCIC Y TINFOCIC PBR04    PSLU62   W1 YLUX
SET DTS_ND_PS/2    = PS/2     TINFOCIC Y TINFOCIC PBR04    PSLU62   W1 YLUX
SET DTS_ND_TFPCICS = PS/2     TINFOCIC Y TINFOCIC PBR04    PSLU62   W1 YLUX
SET DTS_ND_TINFOCIC= PS/2     -        Y TINFOCIC PBR04    PSLU62   W1 YLUX
SET DTS_ND_TYCICS  = PS/2     TINFOCIC Y TINFOCIC PBR04    PSLU62   W1 YLUX
SET DTS_ND_HSKPRF  = OS2DTS   -        Y HSKSWB   DECnet   -        01 YLUX
SET DTS_ND_HSKSWB  = OS2DTS   -        Y HSKSWB   DECnet   -        01 YLUX
SET DTS_ND_OS2DTS  = OS2DTS   -        Y OS2DTS   DECnet   -        02 YLUX


 DTS OS/2 Gateway (c) User's guide    Management and parameterisation      5-3
 _______________________________________________________________________________



         DTS parameters for spooling     
         ---------------------------

         Parameters for DTS spooling. There are 4 paramaters which You must   
         set:                                                                 
                                                                              
         Path of spool directory   DTS_SPOOL=path                             
         Path of error directory   DTS_ERROR=path                             
         Path of log   directory   DTS_LOG  =path                             
         Spool send retry interval DTS_INTERVAL=HHMMSS                        
                                                                              
                                                                              
         Examples:                                                 
                                                                              
         SET      DTS_SPOOL=C:\DTS\SPOOL\*.*       
         SET      DTS_ERROR=C:\DTS\ERROR\*.*       
         SET      DTS_LOG  =C:\DTS\LOG\*.*         
         SET      DTS_INTERVAL=000030              
                                                                              


         DTS parameters for local subroutines
         ------------------------------------

         Local subroutines which are called from remote computers (message    
         handlers). Each subroutine must located in some dynamic link         
         library. DTS reads these environment variables to find and load      
         correct DLL. There can be any number of User subroutines and         
         User DLLs. Several subroutines can also be in the same DLL.          
                                                                              
         Format:  DTS_PG_XXXXXXXX=YYYYYYYY                                    
                                                                              
         XXXXXXXX = Subroutine logical name, Handler id, 8 characters         
         YYYYYYYY = DLL name, must be in LIBPATH dir, max 8 characters        
                                                                              

         Add Your own DLL and subroutines to this list:                       
                                                                              
         SET      DTS_PG_ECHO    =DTSEXSUB    
         SET      DTS_PG_PBRCRASH=DTSEXSUB    
         SET      DTS_PG_ROUTER  =DTSEXSUB    
         SET      DTS_PG_DTSFSRV =DTSEXSUB


         DTS parameters for trace
         ------------------------

         Optional DTS TRACE service: You can activate DTS internal trace     
         defining environment variable DTS_TRACE, format:                    
                                                                             
         DTS_TRACE=path   , path points to trace directory, which must exist 
                                                                             

         Example:                                                            
                                                                             
         SET      DTS_TRACE=C:\DTS\TRACE\*.*    
                                                                             
         If You define this environment variable, then DTS writes each       
         incoming and outgoing message to trace directory. This option       
         is for temporary test use only, don't use it permanently.           
 DTS OS/2 Gateway (c) User's guide    Architecture and internal structure  6-1
 _______________________________________________________________________________



         6. DTS architecture and internal structure
         ------------------------------------------


         Layered architecture
         --------------------

         DTS has been structured in layers so that the system consists
         of four different logical layers each of which perform their
         own operations.



            DTS / COMPUTER   A                     DTS / COMPUTER   B

         +----------------------+               +----------------------+
         !                      !               !                      !
         !  Application program !       4       !  Application program !
         !                      ! A           A !                      !
         +----------------------+ !           ! +----------------------+
                                  !           !
         +----------------------+ !           ! +----------------------+
         !  DTS applic. server  ! !           ! !  DTS applic. server  !
         !  Security, Spooling, ! !     3     ! !  Security, Spooling, !
         !  Recovery ...        ! !           ! !  Recovery ...        !
         +----------------------+ !           ! +----------------------+
                                  !           !
         +----------------------+ !           ! +----------------------+
         !  DTS protocol server ! !           ! !  DTS protocol server !
         !  SNA LU6.2 or        ! !     2     ! !  SNA LU6.2 or        !
         !  DECnet/OSI          ! !           ! !  DECnet/OSI          !
         +----------------------+ !           ! +----------------------+
                                  !           !
         +----------------------+ !           ! +----------------------+
         !  Communication inter.! V           V !  Communication inter.!
         !  IBM Comm mgr and/or ! <---- 1 ----> !  IBM Comm mgr and/or !
         !  DECnet OS/2         !               !  DECnet OS/2         !
         +----------------------+               +----------------------+



         Level 1: Communications interface which is used in the
                  conversation with a second party. This level is,
                  DECnet OS/2 and/or IBM OS/2 EE communications      
                  manager                             

         Level 2: DTS' protocol server, which converses with the lower
                  level in commands of the required protocol. This
                  level uses APPC or DECnet/OSI verbs, for example,
                  taking care of remote system synchronisation,
                  packing of data etc..

         Level 3: DTS' application program server. Looks after recovery,
                  security, spooling, routing etc. matters which are
                  protocol independent.

         Level 4: Application program which calls or is called by DTS.
 DTS OS/2 Gateway (c) User's guide    Architecture and internal structure  6-2
 _______________________________________________________________________________



         Message compression
         -------------------

         Data packing can be a chosen characteristic. If the function
         code's first byte is '2' then the packing is done/undone.

         Data packing can also be specified by the receiver in other
         words by the remote node. This node's parameter data can then
         specify the data packing. If it is done this way then DTS
         immediately changes the first byte of all '0' starting
         function codes to '2' at the beginning of the YFIAPPC call.  '

         Compression takes place for character-form data, compression
         is done just before DATA transmission or immediately when DATA
         is received. Messages are ALWAYS in uncompressed form in the
         logs and other temporary storage places for the messages.

         Compression starts from the message's 40th byte and ends at the
         last, the message header is not compressed. The whole of the
         return message is compressed.

         Every byte which consecutively repeats 4...255 times in the
         message is compressed to a 3 byte long repeater indicator. If
         the same byte repeats over 255 times consecutively then more
         consecutive byte indicators are set.

         Every HEX FF byte is compressed into a 3 byte repeater indicator
         even though it would only be one HEX FF byte.


         Repeater indicator
         ------------------

         FF xx yy       FF = Repeater indicator character, in other words
                             (HEX FF) character which reports that this
                             is a repeating byte.

                        xx = Repeating byte in ASCII/EBCDIC form.

                        yy = Number of times repeated in binary form
                             (8 bytes).



         Example:
         --------

         Uncompressed character queue (HEX)

         F0F0F140404040404040FF9492F0F0F0F0F0F0F0F0F0F0F0A7A6


         Same character compressed (HEX)

         F0F0F1FF4007FFFF019492FFF00BA7A6
 DTS OS/2 Gateway (c) User's guide    Architecture and internal structure  6-3
 _______________________________________________________________________________



         Routing of the subroutine call
         ------------------------------

         DTS OS/2 routes the subroutine call to the required system
         without the OS/2 calling program knowing anything about the
         matter. DTS OS/2 uses YFIROUTE subroutine for the automatic
         routing which can also make a call externally direct. This
         makes it possible for external systems to call for routing
         services from DTS OS/2. In the event of this the viewing
         of the routing depends on the implementation of the completely
         external system. Routing of the OS/2 applications is never
         viewed at all, it occurs automatically without the application
         needing to have any knowledge of the matter whatsoever.

         YFIROUTE is the program which routes the subroutine call to
         other DTS systems, to other computers. YFIROUTE's 'handler
         name' is ROUTER. YFIROUTE's parameter area is DTS standard,
         in other words the first 39 bytes are the YLUX header.
         The end of the parameters are given as such to YFIAPPC, which
         YFIROUTE calls. In other words the following 39 bytes are also
         a YLUX header. YFIROUTE returns the data which comes back from
         YFIAPPC to YFIROUTE's original caller. In addition to
         this the original YFIAPPC return code comes at the beginning of
         the message. In other words the first 4 bytes in the returning
         message are the YFIAPPC return codes.


         Input parameter area

               ____________________________________________________
              !             !                                      !
              !  YLUX       !   YFIAPPC's parameter area/ DTS 2    !
              !  Header     !______________________________________!
              !             !  YLUX       !  3rd DTS system's      !
              !             !  Header     !  Handler's inp.param.  !
              !_____________!_____________!________________________!

              1            39            78                    32000


              Input parameter area's minimum length is thus
              78 bytes. Maximum 32,000 bytes.


         Output parameter area

               ____________________________________________________
              !             !             !                        !
              !  YFIAPPC    !  YFIAPPC    !  Handler's output      !
              !  Ret code   !  Ret code   !  parameters            !
              !             !             !                        !
              !  DTS 1/2    !  DTS 2/3    !  DTS 3                 !
              !_____________!_____________!________________________!

              1             2             4                    32000

              Output parameter area's minimum length is thus
              4 bytes. Maximum 32,000 bytes.
 DTS OS/2 Gateway (c) User's guide    Architecture and internal structure  6-4
 _______________________________________________________________________________



         Diagram of the routing
         ----------------------

         In this case there are 3 DTS systems each of which are in
         different computers. They do not need to be this way, routing
         always occurs between DTS systems, not necessarily between
         computers. In other words if the same computer has more than one
         DTS system which can communicate with each other so they can
         also route messages to each other within the same computer.
         There can also be more than one routing node (see diagram DTS 2)
         The number of routing nodes has no limit and the message may
         flow through any number of computers before reaching its
         final destination.




                +----------+
               /Computer A/!
              +----------+ !
              !          ! !
              !  _____   ! !                   DTS 1 calls DTS 2's
              ! ! DTS !--------------+         ROUTER and gives it
              ! !__1__!<-----------+ !         parameters.
              !          !/        ! !
              +----------+         ! !
                                   ! !
                                   ! !
                                   ! !
                                   ! !                    +----------+
                                   ! !                   /Computer B/!
                                   ! !                  +----------+ !
                                   ! !                  !          ! !
                                   ! !                  !  _____   ! !
                                   ! +------------------->! DTS !----------+
                                   +----------------------!__2__!<-------+ !
                                                        !          !/    ! !
                                                        +----------+     ! !
                                                                         ! !
                                                                         ! !
                                                                         ! !
                                             DTS 2's ROUTER calls DTS 3  ! !
                                             with the given parameters   ! !
                             +----------+                                ! !
                            /Computer C/!                                ! !
                           +----------+ !                                ! !
                           !          ! !                                ! !
                           !  _____   ! !                                ! !
                           ! ! DTS !-------------------------------------+ !
                           ! !__3__!<--------------------------------------+
                           !          !/
                           +----------+


                     DTS 3 executes the subroutine which was requested
                     by the original DTS 1 function.
                     DTS 3 returns the reply message to DTS 2
                     which again returns it to DTS 1.
 DTS OS/2 Gateway (c) User's guide    Architecture and internal structure  6-5
 _______________________________________________________________________________



         Recovery implementation
         -----------------------

         When YFIAPPC operates in real time with the x1 function code
         there is no recovery mechanism. The user receives as a return
         code information about the failure of an operation. 

         At the receiving end always when something is done with
         x2,x4 function codes, the message header is recorded on the
         log at the receiving end after the message handler's call.
         If the line is disconnected suddenly or the receiving end's
         program fails, then STATUS = 1 was updated in the message
         at the sending end, which meant that the message was sent
         at least one time to the subroutine in the other computer.

         Always when the message buffer is undone with function code
         x4, then at the receiving end if the message STATUS =1 the log
         is checked to find if the message header is there. If found,
         then the message has already been handled one time so the
         subroutine will not be called again, and control only returns
         back to the calling program. (return code= 00).


         Computer A                                    Computer B
         +------------+
         !Application !                            +---------+
         !Program     !                            !         V
         !            !                            !   +------------+
         !CALL YFIAPPC!---------+                  !   !Application !
         !            !<------+ !                  !   !Subroutine  !
         !            !       ! !                  !   !xyz         !
         +------------+       ! !                  !   !            !
                              ! !                  !   +------------+
                              ! !                  !         !
                              ! !   Application    !         !
         =====================!=!==================!=========!=============
                              ! !       DTS        !         !
         +--------------------+ !                  +-------+ !
         !                      V                          ! !
         !    _____        +-----------+                   ! !
         !   (_____)       !YFIAPPC    !                   ! ! 
         !   !DTS  !<------!           !     +-----------+ ! ! 
         !   !spool!----+  !Start YLUX !---->!Tran YLUX  ! ! ! 
         !   (_____)    !  !           !     !           ! ! ! 
         !              !  !SEND msg   !---->!RECEIVE msg! ! ! 
         !    _____     !  !           !APPC !           ! ! !   _____ 
         !   (_____)    !  !           ! or  !CALL xyz   !-+ !  (_____)
         !   !DTS  !    !  !           !Dnet/!           !<--+  !DTS  !
         !   !error!<---+  !           ! OSI !           !----->!log  !
         !   (_____)       !RECEIVE msg!<----!SEND msg   !      (_____)
         !                 !           !     !           !
         !                 +-----------+     +-----------+
         !                      !
         +----------------------+
 DTS OS/2 Gateway (c) User's guide    Architecture and internal structure  6-6
 _______________________________________________________________________________



         DTS OS/2 Gateway environment     
         ---------------------------- 



             +-------------+
             !             !
             ! ENVIRONMENT !                            
             !             !          YLUZ.EXE              STOPYLUZ.EXE
             ! VARIABLES   !         +--------------+      +------------+
             !             !         !Call YFIAPPC  !      !Stops the   !
             +-------------+         !with FC 04,   !      !DTS spooler !
                                     !sleeps a while!<- - -!process     !
          +--------------------------!and do it     !      !YLUZ, when  !
          !                          !again         !      !necessary   !
          !                          +--------------+      +------------+
          !                  
          !   Single Threaded                  
          !   Dynamic Link            User Front-End         +------------+ 
          !   Library                 Applications           !YLUXDEC.EXE !
          !                          +--------------+      +------------+ !
          !      DTS.DLL             !YFIA and other!      ! YLUX.EXE   ! !
          !  +--------------+        !example       !      !            ! !
          !  !All DTS       !        !programs which!      !DTS Back-End! !
          !  !internal and  !<-------!call DTS serv.!      !server main ! !
          !  !external func-!        !YFIAPPC       !      !program.    ! !
          !  !tions         !        +--------------+      !Calls User  ! !
          !  !              !                              !subroutines ! !
          !  !Routines:     !                              !via OS/2    ! !
          +->!              !         User subroutine      !runtime     ! !
             !YFIAPPC       !         libraries .DLL.      !dynamic link! !
             !YFITIMES      !        +--------------+      !Linked also ! !
             !YFICOMPR      !        !DTS exampl DLL!      !with DTS.OBJ! !
             !YFIAPPCX      !<- - - -!DTSEXSUB and  !<-----!(APPC/DECnet!-+
             !YFIAPPCY      !        !any number of !      ! communic.) !
          +--!...           !<-+     !user own DLL  !      +------------+
          !  !...           !  !     !DTSEXSUB      !            !
          !  !...           !  !     !...           !            !
          !  +--------------+  !     +--------------+            !
          !                    !                                 !
          !                    !                                 !
          !                    !                                 !
          !                    !                                 !
          !       _______      !   _______          _______      !
          !      (_______)     !  (_______)        (_______)     !
          !      !       !     !  !       !        !       !     !
          +----->! SPOOL !-----+  ! ERROR !        !  LOG  !<----+
                 !       !- - - ->!       !        !       !
                 (_______)        (_______)        (_______)
                       



         Spooled DTS messages are each in own file, those files are
         in directory which user has specified when DTS was installed.
         Messages with logical error are moved to other directory which
         was also specified by user. Filename is the message timestamp.
         DTS Back-End uses the LOG directory for recovery reasons. If
         DTS TRACE service is active, then we need also TRACE directory
         for trace records (not in picture).
 DTS OS/2 Gateway (c) User's guide    Installation                         7-1
 _______________________________________________________________________________



         7. DTS Gateway installation from diskette
         -----------------------------------------
                                                                             
         Before You start be sure that You have correctly installed the      
         DIGITAL DECnet OS/2 product and/or IBM OS/2 EE Communications       
         Manager.                                                            
                                                                             
                                                                             
         1. Make first a backup copy of your DTS installation diskette, use  
            DISKCOPY utility.                                                
                                                                             
         2. Create \DTS directory to Your hard disk and copy all files from  
            diskette to that directory, use XCOPY utility with /S option.    
                                                                             
         3. Edit DTS.CFG file and add the file to the end of Your CONFIG.SYS.
            In DTS.CFG there are all parameters what DTS need. Parameters    
            are environment variables. Parameters and Your Communications    
            Manager and/or DECnet configuration must be compatible with      
            each others. With DTS there comes two example configuration      
            file of Comm Mgr, file names are DTSPU2.CFG and TOKEN.CFG.       
            Copy these files to Your Communications Manager work directory   
            (normally C:\CMLIB) and start Comm Mgr with one of these,        
            then You can look how Comm Mgr must configurate.                 
            If You allready have configured You Comm.Mgr, then don't copy    
            files, just Edit DTS.CFG and add it to end of CONFIG.SYS.        
                                                                             
         4. Copy DTSCHARS.TAB to Your Comm. Mgr directory (normally C:\CMLIB)
            and add the file name 'DTSCHARS.TAB' to Your Comm.Mgr Workstation
            profile (Translation table file name).                           
                                                                             
         5. Copy DTS.DLL, DTS.LIB and DTSEXSUB.DLL to directory              
            where You other dynamic link libraries are located.              
            You have specified this directory in Your CONFIG.SYS             
            (LIBPATH environment variable).                                  
                                                                             
         6. If You use APPC, add DTS spooler start to your Communications    
            Manager startup procedure. Look first an example procedure       
            STARTDCM.CMD in installation diskette.                           
            DTS spooler program is YLUZ.EXE, so if your DTS subdirectory is  
            in C: drive, the start command is:   DETACH C:\DTS\YLUZ          
                                                                             
         7. If You use DECnet, modify Your STARTUP.CMD and add DTS startup   
            to that procedure. Look examples STARTUP.CMD STARTDTS.CMD        
            YLUX01.CMD and YLUX02.CMD in installation diskette.              
                                                                             
         8. DTS is now installed, before You can use it You must configurate 
            also remote DTS (VAX or CICS DTS for example). You must also     
            boot Your OS/2 and start Communication before DTS can run.       
            If remote DTS is CICS, then in CICS side in PS/2 node definition 
            'ALLOCATE with ACQ test' field must be blank (not ACQ).          
            Check this with CICS YFIN transaction.                           
            CICS DTS release must be 020-005 or later, check with CICS DTS   
            transaction (first line on top of screen).                       
                                                                             
         You can verify installation with program YFIA which is a simple     
         application that use DTS (call YFIAPPC function). In installation   
         diskette there are also source code available of YFIA (YFIA.C).     
         Makefile YFIA is an example how to compile and link YFIA or other   
         applications which use DTS. Look also source code of DTSEXSUB.DLL   
         and its MAKE file if You like to use DTS Back-End services.         
                                                                            
                                                                             
                            E R R O R  R E P O R T                           


         DTS software is not guaranteed and its maintenance after
         installation is the customer's responsibility. DIGITAL is
         not responsible for accidents caused by DTS' defective
         operation.

         If the customer has DTS' latest release in use and a problem
         occurs we hope, however that the customer informs us so we can
         according to the opportunity, help. The easiest way to inform us
         is to complete the form below and send it to the address:




         Digital Equipment Corporation       phone:  +358 0 4345315
         Peter Blomster
         PL 16            
         02201 ESPOO   
         FINLAND



         Sender's name/company ..... _______________________________________

         Telephone number .......... _______________________________________

         Postal address ............ _______________________________________

                                     _______________________________________


         Current DTS release in use ..........  ____________________________

         Comm Mgr and/or DECnet OS/2 version .  ____________________________

         Operating system and equipment  .....  ____________________________



         Short description of the problem, use the reverse side of this
         form if required.

         ___________________________________________________________________

         ___________________________________________________________________

         ___________________________________________________________________

         ___________________________________________________________________

         ___________________________________________________________________

         ___________________________________________________________________

         ___________________________________________________________________

         ___________________________________________________________________

         ___________________________________________________________________

         ___________________________________________________________________

         ___________________________________________________________________
