OS/2 Shareware BBS: 14 Text

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 14 Text / 14-Text.zip / dtsv010.zip / dtsos2.txt

Wrap

Text File | 2002-01-12 | 71KB | 1,540 lines

______________________________________________ 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. ___________________________________________________________________ ___________________________________________________________________ ___________________________________________________________________ ___________________________________________________________________ ___________________________________________________________________ ___________________________________________________________________ ___________________________________________________________________ ___________________________________________________________________ ___________________________________________________________________ ___________________________________________________________________ ___________________________________________________________________