═══ 1. VRDistributedConnection Object ═══ The Distributed Connection Object allows you to create true Client/Server applications with VX-REXX version 2.1 or greater. The Distibuted Connection Object hides the complexity of the supported communication protocols. Several methods of interprocess and cross-network communication are available for OS/2. However, each has a different programming interface. This means that a programmer must learn different ways to accomplish the same task, depending on the protocol in use. The Distibuted Connection Object provides a single, consistent programming interface to any of the three supported communication protocols: OS/2 named pipes, NetBIOS, and APPC by using IBM* Distributed Application/2 services. The programmer must therefore learn only one interface in order to use multiple protocols. It allows runtime selection of communication protocol. Ordinarily, the programmer must decide when writing an application which communication protocol to use. If it becomes necessary to change protocols, the application must be rewritten. Because the Distibuted Connection Object uses the same APIs regardless of the underlying protocol, the selection of protocol need not be made until run time. This means that the protocol can be changed without access to source code and without recompiling. It also means that a distributed application can be developed and tested first on a single machine using OS/2 named pipes and later moved to span a network using NetBIOS or APPC without recoding. The Distibuted Connection Object supports three communication protocols: Named pipes A form of OS/2 interprocess communication that uses file-system calls to transfer data between processes running on the same workstation. Named-pipes connections across a network are not supported. NetBIOS A communications programming interface that supports peer-to-peer connections between applications running on a LAN. APPC Advanced Program-to-Program Communication, an implementation of the IBM* Systems Network Architecture (SNA) LU 6.2 protocol. APPC allows distribution of applications across an SNA network. ═══ 1.1. Setting Up Your System ═══ ═══ SUWin ═══ o Named-Pipes o NetBIOS protocol o APPC Protocol ═══ NetBIOS Protocol ═══ If you plan to use the NetBIOS protocol: o You must have one of the following installed on your computer: - The Requester feature of IBM LAN Server, in which case any NetBIOS communication partners must also have an IBM LAN requester installed - Novell** NetWare** with the Novell NetBIOS emulator, in which case any NetBIOS communication partners must also have the Novell NetWare requester installed Distributed Application/2 supports two NetBIOS interfaces: - IBM NetBIOS 3.0, used by the IBM LAN requester - IBM LAN Server NetBIOS, also called NetBIOS Submit, used by either the IBM LAN requester or Novell NetWare's NetBIOS emulator. If you are running Novell NetWare, you must use the IBM LAN Server NetBIOS interface. To select this interface, enter a value of 0 in the NetBIOS maximum sessions field of the connection profile. With the LAN Server interface, NetBIOS sessions are allocated on a systemwide, rather than per-process, basis. o You must select NetBIOS in the Protocol field of the Connection Profile. o You might need to modify the LAN Transport Protocol settings for NetBIOS.. Remember that each connection the system opens requires one NetBIOS session. o You must install the NetBIOS Daemon on a work-station where connections are accepted. ═══ APPC protocol ═══ If you plan to use the APPC protocol: o You must have Communications Manager/2 or OS/2 Extended Services installed on your computer. o You must select APPC in the Protocol field of the Connection Profile. o The connection profile must specify: - a TP name defined on the server machine - a partner type of Distributed Application/2 Native APPC is not guaranteed to work with the Distributed Connection Object. - the local LU alias or pool ID and partner LU alias or name, both of which must be defined in the Communications Manager APPC configuration - what data conversion to perform (remember that the partner code page is the code page of the server, or of the native APPC partner) - a timeout value (in the Millisecond wait for open field) that matches the RECEIVE_ALLOCATE_TIMEOUT and, if applicable, INCOMING_ALLOCATE_TIMEOUT values in the TP definition o On each client machine: - The connection profile must be in a directory listed on the system's DPATH. - The APPC configuration must define any SNA mode names, local LU aliases, and partner LU aliases or names specified in the connection profile. For more information, see the APPC Programming Reference. o On each server machine: - The connection profile must be in a directory listed on the system's DPATH. - The APPC configuration must define any SNA mode names and TP names specified in the connection profile. For more information, see the APPC Programming Reference. - If the server program uses Distributed Application/2, the TP definition should specify a SYNC_LEVEL of NONE or EITHER. Note: Several restrictions apply to character data conversion involving DBCS code pages: o When conversion is between DBCS code pages, the maximum amount of data that can be sent at one time is 16,000 bytes. Data conversion errors might result if larger blocks of data are sent. o To avoid data conversion errors, ensure that any character data being converted to EBCDIC from a PC DBCS code page (such as JISCII) does not end in a DBCS lead byte. If a trailing lead byte is detected during translation, Distributed Application/2 will save it and prepend it to the next buffer before translation. In this event, the next buffer must start with the second byte of the character. This capability may be useful for applications that send bulk data in multiple buffers (such as a file transfer program) and do not perform any checking for split DBCS characters. o Any EBCDIC data sent by a Distributed Application/2 application or a native APPC partner must be correctly bracketed by SO/SI control characters and be less than 16,000 bytes. Otherwise, data conversion errors will occur. ═══ Named-Pipes Protocol ═══ If you are using the named pipes protocol, you might not need to use a connection profile. If Distributed Application/2 finds no connection profile for a symbolic name, it will do the following: 1. Assume that the destination program is local and that the named pipes protocol should be used 2. Assume that the symbolic name specified by the calling program is the name of the program to start 3. Search for a FILENAME.CMD in the current directory, where FILENAME is the specified symbolic name 4. If no .CMD is found, search for FILENAME.EXE in the current directory 5. If no .EXE is found, return an error to the calling program ═══ 1.2. Connection Profiles ═══ Distributed Connection Objects use Distributed Application/2 services. You can modify these services at any time by editing the IBMDABB.CP file using the Profile Editor. Distributed Application/2 keeps runtime connection information in connection profiles. These profiles are stored in a file called IBMDABB.CP, which must be located in a directory listed on the DPATH of your system. If multiple files called IBMDABB.CP exist on the DPATH, all of them will be searched. When a program opens a connection to another program using Distributed Application/2, IBMDABB.CP is checked for that destination's connection profile. This provides the Distributed Application/2 with the details of how to open the connection. This information includes: o The communication protocol to use (named pipes, NetBIOS, or APPC) o The name of the destination program (for named pipes and NetBIOS) or the APPC transaction program (for APPC) o Where to find the destination program (if it's across a network) o Protocol-specific information The Distributed Connection Object consults the connection profile at run time, so a profile can be modified at any time to change protocols or other connection details. Because the connection profile is checked at run time, a copy of IBMDABB.CP must be accessible from each computer. Each computer can have its own copy, or multiple computers can share a single copy on a LAN. If separate copies are used, the profile for each connection should be the same for both client and server. For NetBIOS communications will have to run the NetBIOS Daemon on the server machine and you may also need to modify the LAN Transport Protocol settings. ═══ 1.2.1. Editing Connection Profiles ═══ ═══ Prof ═══ When you open the profile editor, you will see a window with one or more profiles. To edit one of these, double-click on the icon: this will bring up a notebook where you can define the communication profile. The profile editor notebook is composed of 4 pages: Common Page NetBIOS Configuration APPC Configuration 1 APPC Configuration 2 ═══ Profex ═══ ═══ 1.2.2. Common Page ═══ ═══ page1 ═══ Here you can choose the protocol that you wish to use and whether you want to use User Profile Management to implement security. Named Pipes You can only use named pipes to communicate locally. If you are networked you will need to use either NetBIOS or APPC if you have Communications Manager/2. NetBIOS This is the recommended protocol for LAN systems. If you choose this protocol, you must fill in the sections on the second page and ensure that you start the NetBIOS Daemon on the server work-station. APPC Use of this option requires Communications Manager/2 to be installed. If you choose this protocol, you must fill in the sections on the third and fourth pages. Sybolic Name Ensure that the Sybolic Name is the same in the profile and for the Client and Server Distributed Connection Object ConnectionName property. Note: The Sybolic Name Must be unique for each connection profile and no longer than 8 characters long (A-Z and 0-9). ═══ Page1ex ═══ ═══ 1.2.3. NetBIOS Configuration ═══ ═══ page2 ═══ NetBIOS Server Machine This field MUST contain the same name that is used to start the NetBIOS Daemon on the server work-station. This must be a valid UNC name consisting of up to 8 characters (A-Z and 0-9). Note: The server work-station does not have to be an IBM LAN Server. NetBIOS maximum sessions This field sets the maximum of concurrent clients that can connect to the server. If you need more connections, increase this value (see LAN Transport Protocol Settings for NetBIOS.). Note: The program MUST be foreground and Queued. ═══ page2ex ═══ ═══ 1.2.4. APPC Configuration 1 ═══ ═══ page3 ═══ if you choose this option, you will need to set the following items using Communications Manager/2 and match the entries on the APPC pages: o On the client machine the following items in the Communications Manager Configuration File must be defined and matched with the entries in the profile: 1. SNA mode name matching the name defined in SNA mode name: of the connection profile 2. Local LU alias matching the Local LU alias name: field in the connection profile or at least the first 2 characters matching the Local LU pool identifier: field 3. Partner LU alias matching the PLU alias name: field if alias is chosen in the PLU identifier: field o On the server machine the following items in the Communications Manager Configuration File must be defined and matched: 1. There should be a Transaction Program (TP) defined with the name which matched with the SNA mode name: in the connection profile. This would be the full path name of your server program. 2. The local LU name should also match the Fully qualified PLU name: in the connection profiles of the clients. ═══ Page3ex ═══ ═══ 1.2.5. APPC Configuration 2 ═══ ═══ Page4 ═══ DO NOT CHANGE ANY SETTINGS ON THIS PAGE if both your clients and server processes use the Distributed Connection Object. This page only applies if one of the partners is a Native APPC program. For the Distributed Connection Object set up the programs as: o Partner type = Application Specific o Data conversion = No character data conversion ═══ Page4ex ═══ ═══ 1.2.6. NetBIOS Daemon ═══ If your system needs to be able to accept NetBIOS connections from other machines, Distributed Application/2 requires a NetBIOS daemon to be running. The daemon identifies the NetBIOS machine name of your server. The following statement starts the NetBIOS daemon: ADDNETBL name [/N] where name is the NetBIOS machine name you want to assign to your computer. The machine name can be up to 8 characters long and can contain characters A-Z and 0-9. It must be unique on the network. Note: This name must be same as the Server Machine Name in the Connection Profile. The /N switch is optional and indicates that the daemon should use the IBM LAN Server NetBIOS (NetBIOS Submit) interface. This is required if the server is using the Novell NetWare NetBIOS emulator. You can run the NetBIOS daemon in either of two ways: o To run the daemon in the foreground, add the line START ADDNETBL name [/N] to your STARTUP.CMD file. The next time you reboot your computer, the daemon will start automatically. You can also start the daemon without rebooting by using the START command at an OS/2 command prompt. o To run the daemon in the background, add the line RUN=ADDNETBL name [/N] to your CONFIG.SYS file. The next time you reboot your computer, the daemon will start automatically. You can also start the daemon in the background without rebooting by using the DETACH command at an OS/2 command prompt. Warning: If the NetBIOS daemon is running in the background, server processes can only run in the background. Therefore, if your server programs need to display information or accept user input, do not run the NetBIOS daemon in the background. If the daemon encounters NetBIOS errors when starting up, it will indicate the return code from NetBIOS with one of the following error messages: NETBIOS RESET(nn) Return code from the NetBIOS RESET command was nn. This usually means there are insufficient NetBIOS resources available. NETBIOS ADDNAME(nn) Return code from the NetBIOS ADDNAME command was nn. This usually means the specified NetBIOS machine name is already in use on the network. NETBIOS LISTEN(nn) Return code from the NetBIOS LISTEN command was nn. For more information on NetBIOS return codes, refer to the LAN Technical Reference. ═══ 1.2.7. LAN Transport Protocol Settings for NetBIOS. ═══ For NetBIOS connections between the server and the clients you will probably have to modify the LAPS configuration for your card to add the resources needed by both the client and the server. Run the LAPS program (or Communications Manager/2 LAN Adapter and Protocol Support) and modify the NetBIOS configuration using the following guidelines: o For the server machine: - Increase maximum sessions by the value of NetBIOS maximum sessions - Increase maximum commands by 2 * the value of NetBIOS maximum sessions - maximum names by the value of NetBIOS maximum sessions o For each client: - Increase maximum sessions by the maximum number of connecting processes on the client machine - Increase maximum commands by 2 * the maximum number of connecting processes on the client machine - maximum names by the maximum number of connecting processes on the client machine ═══ 1.3. Initiating a connection ═══ The connection between two processes using Distributed Connection Objects is initiated in different ways depending whether the process is a server or client. Servers When a Server Distributed Connection Object is initialised by VX-REXX it starts a Server Thread which will automatically respond to connections and disconnections from client processes. Clients Clients can connect automatically or manually. A Client Object will connect automatically when it is initialised by VX-REXX if the AutoConnect property is set, otherwise you must initiate the connection with a call to the OpenConnection method. Note: If the server process has not started, the connection protocol will start the server automatically. ═══ 1.4. Communicating between processes ═══ There are two types of communication available between a server and client: o Synchronous communication initiated by the Client o Asynchronous communication initiated by the Server For asynchronous communication to be used you must start a listen thread on the client by either setting the Listen property at design time or by calling the StartListen method. When a client starts or stops a listen thread, a ClientListen event is posted on the server process. This allows you to track which clients can have conversations initiated from the server end of the connection. There is only one method in the Distributed Connection Object for handling communication between clients and servers; SendData, data retrieval is handled by events on the server or client: whenever data is read by either a server or a client a DataReady event is generated where you can retrieve the data and if necessary reply. There are two parts to the data transmitted between Distributed Connection Objects which give you the possibility of further refining the inter-process communication and control: o Command o Data Both these components of a transmission are available in the DataReady event. Warning: There are three reserved command strings used to control the listen state of a client and the set the user data for a client on the server: o "START_LISTEN" (client -> server) o "STOP_LISTEN" (client <-> server) o "USER_DATA" (client -> server) These commands are transmitted between the server and client internally. However, you can send the "STOP_LISTEN" command yourself from a server to a client. Communications beween processes Client Server If a listen thread is active Reads Data on <--------------------------- SendData Listen Thread Post DataReady   Process DataReady  Always available SendData -------------------------> Reads Data waits for reply Post DataReady   Process DataReady Reads Data <------------------------- SendData (reply) Post DataReady   Process DataReady To ensure that conversations are held between the correct processes, unique connection handles are generated for each connection, and all SendData operations from a server MUST use the handle retrieved in the DataReady event if it replies to a client. To further ensure that conversations are about the same "subject", you can also specify a Response ID which can also be retrieved in the DataReady event. The response id is generated internally by the initiator of the the conversation in the SendData call. ═══ 1.5. Error codes ═══ ═══ Error Codes - General ═══ The following error codes are retuned in the MsgNum Info item from a CSError event. The name of the error constant is that of a predefined variable that is added to the REXX Variable pool when the LoadVars method is called. ═══ Error code list ═══ General 9020 VRXDA_INVALID_HANDLE 9024 VRXDA_ERROR_NAME 1411 VRXDA_ALREADY_IDENTIFIED 1418 VRXDA_OPEN_TIMED_OUT 1421 VRXDA_STATE_CHECK 2023 VRXDA_MOD_LOAD_FAILED 2024 VRXDA_ERR_ENTRY_POINT 2025 VRXDA_ERR_START_PARTNER 2027 VRXDA_PARTNER_CLOSED 2028 VRXDA_INVALID_PARTNER 2029 VRXDA_ERR_CP_PAIRING 2030 VRXDA_ERR_CHAR_TABLE 2031 VRXDA_ERR_CHAR_CONVERT 2032 VRXDA_PROFILE_MISMATCH 2100 VRXDA_ERR_APPC 2200 VRXDA_ERR_NP 2300 VRXDA_ERR_NETBIOS 2301 VRXDA_SHORT_ON_NB_RESOURCES 3001 VRXDA_INVALID_FILE_OK 3002 VRXDA_INVALID_FILE 3003 VRXDA_NO_ENTRY 3004 VRXDA_ERR_MEMORY 3005 VRXDA_ERR_WRITE 3006 VRXDA_ERR_READ 3007 VRXDA_BAD_SYMBOLIC_NAME 3100 VRXDA_ERR_SERVER_THREAD 3101 VRXDA_ERR_CLIENT_THREAD 3102 VRXDA_ALREADY_CONNECTED ═══ 9020 VRXDA_INVALID_HANDLE ═══ A read or write operation was attempted using a connection that is not valid. Open the connection before using the SendData method. ═══ 9024 VRXDA_ERROR_NAME ═══ The name specified in a server object is invalid. This error will occur only in servers at startup. ═══ 1411 VRXDA_ALREADY_IDENTIFIED ═══ You have two server objects with the same connection name that are trying to run at the same time. Remove one of the objects or change its connection name. If this is not the case, please contact ADD Consulting. ═══ 1418 VRXDA_OPEN_TIMED_OUT ═══ The client connection to the server timed out waiting for a response. Either increase the number of ConnRetries or increase the Wait for connection time in the Connection Profile. ═══ 1421 VRXDA_STATE_CHECK ═══ You called a method that is not valid in the current APPC state. Note: This message applies only when the partner is a native APPC application. ═══ 2023 VRXDA_MOD_LOAD_FAILED ═══ Cannot load the DLL for the specified communication protocol. ErrorStem.3 will contain the system return code (see GetErrorData). ═══ 2024 VRXDA_ERR_ENTRY_POINT ═══ Cannot access an entry point in the DLL for the specified communication protocol. ErrorStem.3 will contain the system return code (see GetErrorData). ═══ 2025 VRXDA_ERR_START_PARTNER ═══ Could not start the partner. Confirm that a valid connection profile file exists on the DPATH and that it contains a correct profile for the destination, or that a .CMD or .EXE file with the specified name exists in the current directory. ErrorStem.3 contains the return code from DosExecPgm or DosStartSession (see GetErrorData). Note: If the connection uses the NetBIOS protocol and the server needs to run in the foreground, make sure the NetBIOS Daemon on the server machine is not running in the background. A value of 418 in ErrorStem.3 may indicate that this is the case. ═══ 2027 VRXDA_PARTNER_CLOSED ═══ The partner program has ended. Note: This message only applies to NetBIOS or Named Pipe connections. ═══ 2028 VRXDA_INVALID_PARTNER ═══ The partner program type is incorrectly defined in the Connection Profile ═══ 2029 VRXDA_ERR_CP_PAIRING ═══ The local code page and the partner code page specified in the connection profile are not compatible. Note: This message only applies to APPC connections. ═══ 2030 VRXDA_ERR_CHAR_TABLE ═══ Could not access the translation tables for the specified partner code page and the local code page. Note: This message only applies to APPC connections. ═══ 2031 VRXDA_ERR_CHAR_CONVERT ═══ Could not convert data between the local code page and the specified partner code page. Note: This message only applies to APPC connections. ═══ 2032 VRXDA_PROFILE_MISMATCH ═══ There is a discrepancy between the Connection Profiles of the client application and the server application. Make sure the Program type fields of the connection profiles match. If you are using NetBIOS, also make sure the NetBIOS server machine fields match. ═══ 2100 VRXDA_ERR_APPC ═══ An APPC error has occurred. The APPC primary and secondary return codes are returned in ErrorStem.3 and ErrorStem.4. The APPC operation code is returned in ErrorStem.5 (see GetErrorData). Note: This message only applies to APPC connections. ═══ 2200 VRXDA_ERR_NP ═══ An OS/2 Named Pipes error has occurred. ErrorStem.3 contains the system return code (see GetErrorData). Note: This message only applies to Named Pipes connections. ═══ 2300 VRXDA_ERR_NETBIOS ═══ A NetBIOS error has occurred. ErrorStem.3 contains the system return code (see GetErrorData). Note: This message only applies to NetBIOS connections. ═══ 2301 VRXDA_SHORT_ON_NB_RESOURCES ═══ Could not obtain the requested NetBIOS resources (sessions, names, or commands). ErrorStem.3 contains the number of available sessions. ErrorStem.4 contains the number of available commands. ErrorStem.5 contains the number of available names (see GetErrorData). To reduce the NetBIOS resource requirements, decrease the value in the NetBIOS maximum sessions field in the connection profile. For information on increasing available NetBIOS resources see LAN Transport Protocol settings for NetBIOS. Note: This message only applies to NetBIOS connections. ═══ 3001 VRXDA_INVALID_FILE_OK ═══ An invalid Connection Profile was found but the specified destination name was found in another profile file. ═══ 3002 VRXDA_INVALID_FILE ═══ The program encountered an invalid Connection Profile file and was not able to find the specified destination name. However, it will attempt to start the program without a connection profile by using the destination name and a named pipes connection. ═══ 3003 VRXDA_NO_ENTRY ═══ All connection profile files encountered were valid, but the specified destination name was not found. However, an attempt to start the program without a connection profile by using the destination name and a named pipes connection will be made. ═══ 3004 VRXDA_ERR_MEMORY ═══ There is insufficient system memory for the Distributed Connection Object to obtain necessary resources. ═══ 3005 VRXDA_ERR_WRITE ═══ An error was detected by the communications protocol code while attempting to send data. The error may be detected by APPC or NetBIOS. The protocol specific error information is returned in ErrorStem.3 (see GetErrorData). Note: This message only applies to NetBIOS or APPC connections. ═══ 3006 VRXDA_ERR_READ ═══ An error was detected by the communications protocol code while attempting to receive data. The error may be detected by APPC or NetBIOS. The protocol specific error information is returned in ErrorStem.3 (see GetErrorData). Note: This message only applies to NetBIOS or APPC connections. ═══ 3007 VRXDA_BAD_SYMBOLIC_NAME ═══ The specified connection name contains invalid characters. Valid characters are A-Z and 0-9 (see ConnectionName). ═══ 3100 VRXDA_ERR_SERVER_THREAD ═══ Either the server thread failed to start. Note: This is a fatal error. ═══ 3101 VRXDA_ERR_CLIENT_THREAD ═══ Either the listen or the Wait for answer thread failed to start. ═══ 3102 VRXDA_ALREADY_CONNECTED ═══ The client object is already connected. This will be posted from the OpenConnection method if the connection is already active. ═══ 1.6. Run-time files ═══ If you write commercial programs that use the Distributed Connection Object you will have to distribute the following DLLs along with your product: o VRXDA.DLL (The VX-REXX object DLL) o VDAAPPC.DLL (APPC protocol DLL) o VDANETB.DLL (NetBIOS protocol DLL) o VDANETBL.EXE (NetBIOS Daemon) o VDANP.DLL (Named Pipes protocol DLL) o VDAOCRW.DLL (Interface DLL) o VDAPROF.DLL (DLL for profile editor) o VDAPROF.EXE (Profile editor) o VDAPROF.HLP (Help for the profile editor) o IBMDABB.CP (A default profile for your program) ═══ 1.7. Shareware Software ═══ DEFINITION OF SHAREWARE SOFTWARE Shareware Software distribution gives users a chance to try software before buying it. If you try a Shareware software program and continue using it, you are expected to register. Individual programs differ on details -- some request registration while others require it, some specify a maximum trial period. With registration, you get anything from the simple right to continue using the software to an updated program with printed manual. Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights, with a few specific exceptions as stated below. Shareware software authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribution. The author specifically grants the right to copy and distribute the software, either to all and sundry or to a specific group. For example, some authors require written permission before a commercial disk vendor may copy their Shareware software. Shareware software is a distribution method, not a type of software. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware software. The Shareware software system makes fitting your needs easier, because you can try before you buy. And because the overhead is low, prices are low also. Shareware software has the ultimate money-back guarantee -- if you don't use the product, you don't pay for it. When you register the VRDistributedConnection object you will be sent a registered version of the DLL by e-mail. This version has the "nag" popup removed and you have the right to freely distribute software that includes the DLLs. If you are satisfied with the VRDistributedConnection object we ask you to freely distribute the shareware version to your freinds and colleagues. If you have any suggestions for enhancements or find any bugs in the software please contact us at one of our Contact Addresses ═══ 1.8. Registering your license ═══ VRDistributedConnection is a "Shareware software program" and is provided at no charge to the user for evaluation. Feel free to share it with your friends, but please do not give it away altered or as part of another system. The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products. If you find this program useful and find that you are using VRDistributedConnection and continue to use VRDistributedConnection after a reasonable trial period of 30 days, you must make a registration payment of $75.00 to ADD Consulting (CH). You can register through the CompuServe Shareware Registration facility: GO SWREG registration Number 7276 The registration fee will license one copy for use on any one computer at any one time. You must treat this software just like a book. An example is that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Just as a book cannot be read by two different persons at the same time. Payment of the registration fee gives you the right to distribute programs that include the object and the DLL without paying any other "run-time" licenses. Site-License arrangements may be made by contacting ADD Consulting (CH). ═══ 1.9. Distributing the VRDistributedConnection object ═══ Anyone distributing the VRDistributedConnection object for any kind of remuneration must first contact ADD Consulting (CH) at our address below for authorization. This authorization will be automatically granted to distributors recognized by the (ASP) as adhering to its guidelines for shareware distributors, and such distributors may begin offering VRDistributedConnection immediately, however ADD Consulting (CH) should still be advised so that the distributor can be kept up-to-date with the latest version of VRDistributedConnection. Registered users are free to distribute programs that use the the VRDistributedConnection object with no additional run-time fees. ═══ 1.10. Contact Address ═══ You can contact ADD Consulting at the addresses below or on the OS/2 Other Vendors on CompuServe (GO OS2AVEN) where all our products are supported. ADD Consulting (CH) Mr. Peter Kanis Via Suro 9 CH-7403 RhДzБns Switzerland Tel: +41 (0)81 630 2011 Fax: +41 (0)81 630 2015 CompuServe: 100275,350 (Peter Kanis) INTERNET: kanis@ibm.net ADD Consulting (RUS) Mr. Michael V. Schelkin 18-29 Molodezhnaya Street Jukovsky 140160 Moscow Region Russia Tel: +7 095 556 8533 INTERNET: michael@schelkin.msk.ru ═══ 1.11. Rights And Limitations ═══ ADD Consulting makes no warranties as to the information in this guide. Additionally, ADD Consulting is not responsible or liable for any loss or damage of any kind resulting from use of this product. The Software is protected by international copyright laws. All rights reserved. No part of the computer program, documentation or related files may be reproduced photocopied, stored on a retrieval system, or transmitted except as provided by copyright law or by express permission of the copyright owner. DISCLAIMER - AGREEMENT Users of VRDistributedConnection shall accept this disclaimer of warranty: ADD CONSULTING SUPPLIES THIS PRODUCT AS IS WITHOUT WARANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARANTIES OF MERCANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. ADD CONSULTING ASSUMES NO LIABILITY FOR DAMAGES, DIRECT OR CONSEQUENTIAL, WHICH MAY RESULT FROM THE USE OF THE PRODUCT. Some jurisdictions do not allow the exclusion or limitations for consequential or incidental damages, so the above may not apply to you. ═══ 2. VRDistributedConnection properties ═══ The Distributed Connection Object exports the following properties: o AutoConnect o Connected o ConnectionName o ConnHandle o ConnRetries o Listen o ProcessType inherits the following properties from the VX-REXX Descriptive Text Object: o Caption o ClassName o ClipSiblings o Enabled o FirstChild o Font o ForeColor o Height o HelpTag o HelpText o HintText o HWnd o Left o Name o Painting o Parent o Query o QueryColumns o Self o Sibling o SiblingOrder o Top o UserData o Visible o Width ═══ 2.1. AutoConnect ═══ ═══ Autoconnect - List ═══ Applies to Clients Data Type Boolean Possible Values 1 (true) 0 (false) See Also o Connected o ConnRetries o ConnectionName o ProcessType o Connect o OpenConnection ═══ AutoConnect - Description ═══ This property can only be set from the design environment. If set to 1 (TRUE), the object will connect to the server process when it is created, i.e. when the client process starts. Note: This property is read-only and cannot be set with VRSet. ═══ 2.2. Connected ═══ ═══ Connected - List ═══ Applies to Clients Data Type Boolean Possible Values 1 (true) 0 (false) See Also o AutoConnect o ConnRetries o Connect o OpenConnection ═══ Connected - Description ═══ This is a boolean property that indicates the connection status for a client object. if the object is connected to a server, the property is set to 1 (TRUE). Note: This property is read-only and cannot be set with VRSet. ═══ 2.3. ConnectionName ═══ ═══ ConnectionName - List ═══ Applies to Servers Clients Data Type String Possible Values String of up to 8 characters (A-Z and 0-9) See Also o AutoConnect o Connected o ConnRetries o ProcessType o Connect o OpenConnection ═══ ConnectionName - Description ═══ This property MUST be set. It contains the sybolic connection name and must be same for the Client, the Server and in the Connection Profile. Note: The Sybolic Name Must be unique for each connection profile and no longer than 8 characters long (A-Z and 0-9). Warning: if you set the AutoConnect property to 1 you MUST set the ConnectionName at design time. ═══ 2.4. ConnHandle ═══ ═══ ConnHandle - List ═══ Applies to Clients Data Type Numeric Possible Values Any whole number See Also o AutoConnect o Connected o ConnRetries o ProcessType o Connect o DataReady o OpenConnection ═══ ConnHandle - Description ═══ This is a numeric property that contains the unique connection handle for the client. It is only valid after connecting to a server. Note: This property is read-only and cannot be set with VRSet. ═══ 2.5. ConnRetries ═══ ═══ ConnRetries - List ═══ Applies to Clients Data Type Numeric Possible Values Any whole number See Also o AutoConnect o Connected o ProcessType o Connect o DataReady o OpenConnection ═══ ConnRetries - Description ═══ When connecting through the NetBIOS protocol to a server that has not started, the delay to start the server process can be quite long, especially with a VX-REXX application, and exceed the Wait for Open setting in the Connection Profile. This property tells the client object how many times to retry before returning an error; The default value is 2. ═══ 2.6. Listen ═══ ═══ Listen - List ═══ Applies to Clients Data Type Boolean Possible Values 1 (true) 0 (false) See Also o AutoConnect o OpenConnection o StartListen o StopListen ═══ Listen - Description ═══ This property is set at design time and cannot be changed. If the property is set, a thread is started that will listen for messages from the server. Use this property if you want to have the server send asynchronous messages to its clients. Note: This property is read-only and cannot be set with VRSet. ═══ 2.7. ProcessType ═══ ═══ ProcessType - List ═══ Applies to Clients Data Type String Possible Values Server Client See Also o AutoConnect o Connected o ConnRetries o Connect o OpenConnection ═══ ProcessType - Description ═══ This property is set at design time and cannot be changed. It defines the behaviour of the Distributed Connection Object as either a Client or a Server. Note: This property is read-only and cannot be set with VRSet. ═══ 3. VRDistributedConnection events ═══ The Distributed Connection Object inherits all the events of the VX-REXX Descriptive Text Object and also exports the following events: o ClientListen o Connect o CSError o DataReady o Disconnect ═══ 3.1. Connect ═══ ═══ Connect - List ═══ Topics o Description o VRInfo Items Applies to Servers See Also o Connected o OpenConnection ═══ Connect - Description ═══ This event is generated by a server object whenever a client connects. The connection protocol is handled internally and will already be active when this event is posted by the object. ═══ Connect - VRInfo Items ═══ DAHandle The connection handle for the client which has made the connection. ═══ 3.2. ClientListen ═══ ═══ ClientListen - List ═══ Topics o Description o VRinfo Items Applies to Clients Servers See also o Listen o DataReady ═══ ClientListen - Description ═══ This event is posted on a server whenever a client starts or stops listening for messages from the server. It is also posted on a client when the server sends a STOP_LISTEN command, either independently or as a response to the client having sent a STOP_LISTEN command. ═══ ClientListen - VRinfo Items ═══ DAHandle The handle to the connection that generated the error. If the object is a client this will be the same as the handle in the ConnHandle Start Flag indicating that the client has entered listen mode (1) or has stopped listening (0) ═══ 3.3. CSError ═══ ═══ CSError - List ═══ Topics o Description o VRinfo Items Applies to Servers Clients See also o GetErrorData o ErrorMessage ═══ CSError - Description ═══ This event is posted whenever an error is generated by a connection. If a Distributed Connection Object method returns 0, this event will be generated. For APPC connections this event can be posted with a severity of 0, in which case it indicates a state change. ═══ CSError - VRinfo Items ═══ DAHandle The handle to the connection that generated the error. If the object is a client this will be the same as the handle in the ConnHandle ErrNum The error return code (see Error codes). ErrSev Severity of error: 0 = No error, 1 = Warning, 2 = Recoverable error, 3 = Severe error. ErrMsg A message explaining the error. ═══ 3.4. DataReady ═══ ═══ DataReady - List ═══ Topics o Description o VRInfo Items Applies to Servers Clients See also o SendData o Communicating between processes ═══ DatReady - Description ═══ This event is generated whenever a Distributed Conection Object performs a read operation. It allows you to recover the data sent from a partner and to identify the sender and whether the receiver should reply. ═══ DataReady - VRInfo Items ═══ DAHandle The connection handle of the sender. CmdID The user defined Command identifier (see SendData) RespID The response identifier, if any, that was specified in SendData by the sender. Data The actual data that was sent. ═══ 3.5. Disconnect ═══ ═══ Disconnect - List ═══ Topics o Description o VRInfo Items Applies to Servers See also o CloseConnection o Connected o ConnHandle ═══ Disconnect - Description ═══ This event is generated whenever a client disconnects from a server. ═══ Disconnect - VRInfo Items ═══ DAHandle The connection handle for the client that has disconnected. ═══ 4. VRDistributedConnection methods ═══ The Distributed Connection Object inherits all the methods of the VX-REXX Descriptive Text Object and also exports the following methods: o CloseConnection o ErrorMessage o GetClientData o GetErrorData o LoadVars o OpenConnection o SendData o SetClientData o StartListen o StopListen ═══ 4.1. CloseConnection ═══ ═══ CloseConnection - List ═══ Topics o Description o Parameters Applies to Clients Servers See also o OpenConnection o Disconnect o Connected o ConnectionName ═══ CloseConnection - Description ═══ ok = VRMethod( object, "CloseConnection", hConn); Closes the connection between a Server and a client. The connection may be closed from either side, if the Server closes the connection then the connection handle must be passed as a parameter. Returns The method returns 1 (TRUE) if successful else 0 (FALSE ). ═══ CloseConnection - Parameters ═══ hConn The handle to the connection which you want to close. This parameter is only used when a Server closes a connection with a client. ═══ 4.2. ErrorMessage ═══ ═══ ErrorMessage - List ═══ Topics o Description Applies to Servers Clients See also o GetErrorData o CSError ═══ ErrorMessage - Description ═══ ok = VRMethod( object, "ErrorMessage"); Pops up a message box with details of the last connection error. If you receive persistent errors with same codes, note then down and contact ADD Consulting. Returns The method returns 1 (TRUE) if successful else 0 (FALSE ). ═══ 4.3. GetClientData ═══ ═══ GetClientData - List ═══ Topics o Description o Parameters Applies to Servers See also o SetClientData o StartListen o StopListen o Listen ═══ GetClientData - Description ═══ ok = VRMethod( object, "GetClientData", hConn, "Data."); Collect full information about a connected client process. This includes the connection handle, the listen state and any user data that has been set by client with SetClientData. Returns The method returns 1 (TRUE) if successful else 0 (FALSE ). ═══ GetClientData - Parameters ═══ hConn The handle to the connection for which data is sought. "Data." Quoted name of a stem variable to receive the client data. Data.0 Always 3 data.1 The connection handle. This should be the same as the hConn parameter passed to the method. Data.2 Flag indicating whether the client is in listen mode. 1 = Client is listening 0 = Client is not listening Data.3 Any user data associated with the client connection. ═══ 4.4. GetErrorData ═══ ═══ GetErrorData - List ═══ Topics o Description o Parameters Applies to Servers Clients See also o ErrorMessage o CSError ═══ GetErrorData - Description ═══ ok = VRMethod( object, "GetErrorData", "ErrorStem."); Collect full information about a connection error. This information should be noted and sent to ADD Consulting if you have a persistent error. Returns The method returns 1 (TRUE) if successful else 0 (FALSE ). ═══ GetErrorData - Parameters ═══ "ErrorStem." Quoted name of a stem variable to receive the error data. ErrorStem.0 Always 6 ErrorStem.1 Return code from the operation (see Error codes). ErrorStem.2 Severity of error: RETURN_CODE_OK (0) = No error RETURN_CODE_WARNING (1) = Warning RETURN_CODE_ERROR_OK (2) = Error that was recovered internally RETURN_CODE_ERROR (3) = Error ErrorStem.3 Return code from OS/2, NetBIOS or APPC ErrorStem.4 Return code from OS/2, NetBIOS or APPC ErrorStem.5 Return code from OS/2, NetBIOS or APPC ErrorStem.6 Error message (English) ═══ 4.5. LoadVars ═══ ═══ LoadVars - List ═══ Topics o Description Applies to Servers Clients See also o ErrorMessage o GetErrorData o Error codes ═══ LoadVars - Description ═══ ok = VRMethod( object, "LoadVars"); This loads the REXX variables that define error codes and severity codes used to allow easy comparison of the values returned by GetErrorData and available in the CSError event. Apart from the variables defined in Error codes, the following severity code variables are loaded: o RETURN_CODE_OK = 0 o RETURN_CODE_WARNING = 1 o RETURN_CODE_ERROR_OK = 2 o RETURN_CODE_ERROR = 3 Returns The method returns 1 (TRUE) if successful else 0 (FALSE ). ═══ 4.6. OpenConnection ═══ ═══ OpenConn List ═══ Topics o Description o Parameters Applies to Clients See also o CloseConnection o AutoConnect o ConnHandle o Connect o Connected o ConnRetries o ProcessType ═══ OpenConnection - Description ═══ ok = VRMethod( object, "OpenConnection", Retries); Opens the connection to the Server. Warning: This method only applies to Client processes Returns The method returns 1 (TRUE) if successful else 0 (FALSE ). ═══ OpenConnection - Parameters ═══ Retries If specified this parameter overrides the setting of ConnRetries but does not change it. ═══ 4.7. SendData ═══ ═══ SendData List ═══ Topics o Description o Parameters Applies to Servers Clients See Also o DataReady o CSError ═══ SendData - Description ═══ ok = VRMethod( object, "SendData", CmdId, Data, RespId, HConn, ExpectAnswer, WaitForAnswer); Send a block of data with a command to the connection partner. Returns The method returns 1 (TRUE) if successful else 0 (FALSE ). Warning: There are three reserved command strings used to control the listen state of a client and to set the user data for a client on the server: o "START_LISTEN" (client -> server) o "STOP_LISTEN" (client <-> server) o "USER_DATA" (client -> server) ═══ SendData - Parameters ═══ CmdId user defined command Identifier. This is sent with the data to the server process. This parameter MUST be present. Data The actual data you want to send. This parameter MUST be present. RespId If you are sending from a Client this parameter should be 0. It will be changed to a unique number by the system if you want an answer from the server. If you are replying from a server you MUST use the RespID info from the DataReady event. This parameter MUST be present. HConn The handle to the connection. When sending from a client this parameter can be set to 0. When replying from a server this MUST be the DAHandle info item from the DataReady event. The parameter MUST be present when called on a server. ExpectAnswer Boolean parameter which if set to 1 indicates that you wish to get a reply from the server. WaitForAnswer Boolean parameter that when set to 1 indicates that the call to SendData will not return until the server has replied. If you set this parameter to 0, a thread is started to wait asynchronously for the server reply. In both cases the data received will be available through the DataReady event. ═══ 4.8. SetClientData ═══ ═══ SetClientData List ═══ Topics o Description o Parameters Applies to Clients See Also o GetClientData ═══ SetClientData - Description ═══ ok = VRMethod( object, "SetClientData", data); Sets the user data associated with the client on the server. This data is NOT stored locally on the client, it is sent to the server. Returns The method returns 1 (TRUE) if successful else 0 (FALSE ). ═══ SetClientData - Parameters ═══ Data String representation of the data you want to send. This parameter MUST be present. ═══ 4.9. StartListen ═══ ═══ StartListen List ═══ Topics o Description o Parameters Applies to Clients See Also o DataReady o CSError o Listen o StopListen ═══ StartListen - Description ═══ ok = VRMethod( object, "StartListen"); Starts the listen thread for a client to receive asynchronous messages from the server. Any messages arriving on this thread will cause a DataReady event to be generated. While the thread is running the Listen property will be set to 1. Returns The method returns 1 (TRUE) if successful else 0 (FALSE ). ═══ StartListen - Parameters ═══ None ═══ 4.10. StopListen ═══ ═══ StopListen List ═══ Topics o Description o Parameters Applies to Servers Clients See Also o DataReady o CSError o Listen o StartListen ═══ StopListen - Description ═══ ok = VRMethod( object, "StopListen", hConn); Stops the listen thread where a client receives asynchronous messages from the server. The Listen property will be set to 0. This method can be called from a server to stop the listen thread on a client; in this case the connection handle parameter must be present. Returns The method returns 1 (TRUE) if successful else 0 (FALSE ). ═══ StopListen - Parameters ═══ hConn The handle to the connection. When sending from a client this parameter can be absent. The parameter MUST be present when called from a server.