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

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.