VRDistributedConnection

Properties

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