VRDistributedConnection

Exported Properties
The Distributed Connection Object exports the following properties:
 * AutoConnect
 * Connected
 * ConnectionName
 * ConnHandle
 * ConnRetries
 * Listen
 * ProcessType

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


 * Applies to : Clients


 * Data Type : Boolean


 * Possible Values
 * 1 (true)
 * 0 (false)

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


 * Applies to : Clients


 * Data Type : Boolean


 * Possible Values
 * 1 (true)
 * 0 (false)

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


 * Applies to :
 * Servers
 * Clients


 * Data Type : String


 * Possible Values : String of up to 8 characters (A-Z and 0-9)

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


 * Applies to : Clients


 * Data Type : Numeric


 * Possible Values : Any whole number

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


 * Applies to : Clients


 * Data Type : Numeric


 * Possible Values : Any whole number

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


 * Applies to : Clients


 * Data Type : Boolean


 * Possible Values
 * 1 (true)
 * 0 (false)

ProcessType
This property is set at design time and cannot be changed. It defines the behavior of the Distributed Connection Object as either a Client or a Server.

Note: This property is read-only and cannot be set with VRSet.


 * Applies to : Clients


 * Data Type : String


 * Possible Values
 * Server
 * Client

Inherited Properties
Inherits the following properties from the VX-REXX Descriptive Text Object:
 * Caption
 * ClassName
 * ClipSiblings
 * Enabled
 * FirstChild
 * Font
 * ForeColor
 * Height
 * HelpTag
 * HelpText
 * HintText
 * HWnd
 * Left
 * Name
 * Painting
 * Parent
 * Query
 * QueryColumns
 * Self
 * Sibling
 * SiblingOrder
 * Top
 * UserData
 * Visible
 * Width

Events
The Distributed Connection Object inherits all the events of the VX-REXX Descriptive Text Object and also exports the following events:


 * ClientListen
 * Connect
 * CSError
 * DataReady
 * Disconnect

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


 * Applies to :
 * Clients
 * Servers

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)

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


 * Applies to :
 * Clients
 * Servers

VRinfo Items

 * DAHandle : The connection handle for the client which has made the connection.

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


 * Applies to :
 * Clients
 * Servers

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.

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


 * Applies to :
 * Clients
 * Servers

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.

Disconnect
This event is generated whenever a client disconnects from a server.


 * Applies to :
 * Clients
 * Servers

VRinfo Items

 * DAHandle : The connection handle for the client that has disconnected.

Methods
The Distributed Connection Object inherits all the methods of the VX-REXX Descriptive Text Object and also exports the following methods:


 * CloseConnection
 * ErrorMessage
 * GetClientData
 * GetErrorData
 * LoadVars
 * OpenConnection
 * SendData
 * SetClientData
 * StartListen
 * StopListen

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

ok = VRMethod( object, "CloseConnection", hConn);


 * Applies to :
 * Clients
 * Servers


 * Returns : The method returns 1 (TRUE) if successful else 0 (FALSE ).

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.

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.

ok = VRMethod( object, "ErrorMessage");


 * Applies to :
 * Clients
 * Servers


 * Returns : The method returns 1 (TRUE) if successful else 0 (FALSE ).

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

ok = VRMethod( object, "GetClientData", hConn, "Data.");


 * Applies to :
 * Servers


 * Returns : The method returns 1 (TRUE) if successful else 0 (FALSE ).

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

GetErrorData
Collect full information about a connection error. This information should be noted and sent to ADD Consulting if you have a persistent error.

ok = VRMethod( object, "GetErrorData", "ErrorStem.");


 * Applies to :
 * Clients
 * Servers


 * Returns : The method returns 1 (TRUE) if successful else 0 (FALSE ).

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

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:


 * RETURN_CODE_OK = 0
 * RETURN_CODE_WARNING = 1
 * RETURN_CODE_ERROR_OK = 2
 * RETURN_CODE_ERROR = 3

ok = VRMethod( object, "LoadVars");


 * Applies to :
 * Clients
 * Servers


 * Returns : The method returns 1 (TRUE) if successful else 0 (FALSE ).

OpenConnection
Opens the connection to the Server.

Warning: This method only applies to Client processes

ok = VRMethod( object, "OpenConnection", Retries);


 * Applies to : Clients


 * Returns : The method returns 1 (TRUE) if successful else 0 (FALSE ).

Parameters

 * Retries : If specified this parameter overrides the setting of ConnRetries but does not change it.

SendData
Send a block of data with a command to the connection partner.

ok = VRMethod( object, "SendData", CmdId,                                   Data,                                    RespId,                                    HConn,                                    ExpectAnswer,                                    WaitForAnswer);


 * Returns : The method returns 1 (TRUE) if successful else 0 (FALSE ).


 * Applies to :
 * Clients
 * Servers

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.

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

ok = VRMethod( object, "SetClientData", data);


 * Applies to : Clients


 * Returns : The method returns 1 (TRUE) if successful else 0 (FALSE ).

Parameters

 * Data : String representation of the data you want to send. This parameter MUST be present.

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.

ok = VRMethod( object, "StartListen");


 * Applies to : Clients


 * Returns : The method returns 1 (TRUE) if successful else 0 (FALSE ).

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

ok = VRMethod( object, "StopListen", hConn);


 * Applies to
 * Servers
 * Clients


 * Returns : The method returns 1 (TRUE) if successful else 0 (FALSE ).

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.