home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 18 REXX
/
18-REXX.zip
/
vrxda12.zip
/
VRXDA.INF
(
.txt
)
< prev
next >
Wrap
OS/2 Help File
|
1995-08-29
|
130KB
|
1,965 lines
ΓòÉΓòÉΓòÉ 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> SUWin ΓòÉΓòÉΓòÉ
o Named-Pipes
o NetBIOS protocol
o APPC Protocol
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> 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
ΓòÉΓòÉΓòÉ <hidden> Profex ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ 1.2.2. Common Page ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> 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).
ΓòÉΓòÉΓòÉ <hidden> Page1ex ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ 1.2.3. NetBIOS Configuration ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> page2ex ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ 1.2.4. APPC Configuration 1 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> Page3ex ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ 1.2.5. APPC Configuration 2 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> 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
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 9024 VRXDA_ERROR_NAME ΓòÉΓòÉΓòÉ
The name specified in a server object is invalid. This error will occur only in
servers at startup.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 2023 VRXDA_MOD_LOAD_FAILED ΓòÉΓòÉΓòÉ
Cannot load the DLL for the specified communication protocol.
ErrorStem.3 will contain the system return code (see GetErrorData).
ΓòÉΓòÉΓòÉ <hidden> 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).
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 2027 VRXDA_PARTNER_CLOSED ΓòÉΓòÉΓòÉ
The partner program has ended.
Note:
This message only applies to NetBIOS or Named Pipe connections.
ΓòÉΓòÉΓòÉ <hidden> 2028 VRXDA_INVALID_PARTNER ΓòÉΓòÉΓòÉ
The partner program type is incorrectly defined in the Connection Profile
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 3001 VRXDA_INVALID_FILE_OK ΓòÉΓòÉΓòÉ
An invalid Connection Profile was found but the specified destination name was
found in another profile file.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 3004 VRXDA_ERR_MEMORY ΓòÉΓòÉΓòÉ
There is insufficient system memory for the Distributed Connection Object to
obtain necessary resources.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 3007 VRXDA_BAD_SYMBOLIC_NAME ΓòÉΓòÉΓòÉ
The specified connection name contains invalid characters.
Valid characters are A-Z and 0-9 (see ConnectionName).
ΓòÉΓòÉΓòÉ <hidden> 3100 VRXDA_ERR_SERVER_THREAD ΓòÉΓòÉΓòÉ
Either the server thread failed to start.
Note:
This is a fatal error.
ΓòÉΓòÉΓòÉ <hidden> 3101 VRXDA_ERR_CLIENT_THREAD ΓòÉΓòÉΓòÉ
Either the listen or the Wait for answer thread failed to start.
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> 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
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> Connected - List ΓòÉΓòÉΓòÉ
Applies to
Clients
Data Type
Boolean
Possible Values
1 (true)
0 (false)
See Also
o AutoConnect
o ConnRetries
o Connect
o OpenConnection
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> 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
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> 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
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> 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
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> Listen - List ΓòÉΓòÉΓòÉ
Applies to
Clients
Data Type
Boolean
Possible Values
1 (true)
0 (false)
See Also
o AutoConnect
o OpenConnection
o StartListen
o StopListen
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> ProcessType - List ΓòÉΓòÉΓòÉ
Applies to
Clients
Data Type
String
Possible Values
Server
Client
See Also
o AutoConnect
o Connected
o ConnRetries
o Connect
o OpenConnection
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> Connect - List ΓòÉΓòÉΓòÉ
Topics
o Description
o VRInfo Items
Applies to
Servers
See Also
o Connected
o OpenConnection
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> Connect - VRInfo Items ΓòÉΓòÉΓòÉ
DAHandle The connection handle for the client which has made the
connection.
ΓòÉΓòÉΓòÉ 3.2. ClientListen ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> ClientListen - List ΓòÉΓòÉΓòÉ
Topics
o Description
o VRinfo Items
Applies to
Clients
Servers
See also
o Listen
o DataReady
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> CSError - List ΓòÉΓòÉΓòÉ
Topics
o Description
o VRinfo Items
Applies to
Servers
Clients
See also
o GetErrorData
o ErrorMessage
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> DataReady - List ΓòÉΓòÉΓòÉ
Topics
o Description
o VRInfo Items
Applies to
Servers
Clients
See also
o SendData
o Communicating between processes
ΓòÉΓòÉΓòÉ <hidden> 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.
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> Disconnect - List ΓòÉΓòÉΓòÉ
Topics
o Description
o VRInfo Items
Applies to
Servers
See also
o CloseConnection
o Connected
o ConnHandle
ΓòÉΓòÉΓòÉ <hidden> Disconnect - Description ΓòÉΓòÉΓòÉ
This event is generated whenever a client disconnects from a server.
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> CloseConnection - List ΓòÉΓòÉΓòÉ
Topics
o Description
o Parameters
Applies to
Clients
Servers
See also
o OpenConnection
o Disconnect
o Connected
o ConnectionName
ΓòÉΓòÉΓòÉ <hidden> 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 ).
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> ErrorMessage - List ΓòÉΓòÉΓòÉ
Topics
o Description
Applies to
Servers
Clients
See also
o GetErrorData
o CSError
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> GetClientData - List ΓòÉΓòÉΓòÉ
Topics
o Description
o Parameters
Applies to
Servers
See also
o SetClientData
o StartListen
o StopListen
o Listen
ΓòÉΓòÉΓòÉ <hidden> 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 ).
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> GetErrorData - List ΓòÉΓòÉΓòÉ
Topics
o Description
o Parameters
Applies to
Servers
Clients
See also
o ErrorMessage
o CSError
ΓòÉΓòÉΓòÉ <hidden> 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 ).
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> LoadVars - List ΓòÉΓòÉΓòÉ
Topics
o Description
Applies to
Servers
Clients
See also
o ErrorMessage
o GetErrorData
o Error codes
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> 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
ΓòÉΓòÉΓòÉ <hidden> 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 ).
ΓòÉΓòÉΓòÉ <hidden> OpenConnection - Parameters ΓòÉΓòÉΓòÉ
Retries If specified this parameter overrides the setting of
ConnRetries but does not change it.
ΓòÉΓòÉΓòÉ 4.7. SendData ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> SendData List ΓòÉΓòÉΓòÉ
Topics
o Description
o Parameters
Applies to
Servers
Clients
See Also
o DataReady
o CSError
ΓòÉΓòÉΓòÉ <hidden> 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)
ΓòÉΓòÉΓòÉ <hidden> 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 ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> SetClientData List ΓòÉΓòÉΓòÉ
Topics
o Description
o Parameters
Applies to
Clients
See Also
o GetClientData
ΓòÉΓòÉΓòÉ <hidden> 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 ).
ΓòÉΓòÉΓòÉ <hidden> SetClientData - Parameters ΓòÉΓòÉΓòÉ
Data String representation of the data you want to send. This
parameter MUST be present.
ΓòÉΓòÉΓòÉ 4.9. StartListen ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> StartListen List ΓòÉΓòÉΓòÉ
Topics
o Description
o Parameters
Applies to
Clients
See Also
o DataReady
o CSError
o Listen
o StopListen
ΓòÉΓòÉΓòÉ <hidden> 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 ).
ΓòÉΓòÉΓòÉ <hidden> StartListen - Parameters ΓòÉΓòÉΓòÉ
None
ΓòÉΓòÉΓòÉ 4.10. StopListen ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> StopListen List ΓòÉΓòÉΓòÉ
Topics
o Description
o Parameters
Applies to
Servers
Clients
See Also
o DataReady
o CSError
o Listen
o StartListen
ΓòÉΓòÉΓòÉ <hidden> 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 ).
ΓòÉΓòÉΓòÉ <hidden> 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.