|
December 31,
2001: Updated version of mvComponents Suite 2.0 is now available for
download.
Overview
On December 31st 2001 a new release of mvComponents was made
available for download from our FTP site. This new release features some
major changes to the way client applications connect to and communicate
with a MultiValue (PICK) host system. The changes involve the
replacement of the out-of-process communication executables VPDir20.exe
and VPRem20.exe with a consolidated single set of executables
(VPGwsv20.exe, VPCtrl20.exe, and VPChnl20.exe) that support local (what
use to be call "Direct" connections) as well as
"Remote" connections that are made through a central
"gateway" Windows 2000 Server. This new version also includes
a new VPDb20.dll component. The changes incorporated into the low level
database component (vpdb20.dll) will shield any of your current
applications or components from the changes in the gateway interface and
operation. With this release the same software handles either local or
remote connections. How you configure your client and gateway options
makes a difference on how it operates and behaves.
New Gateway
Components and Operation
There are four new COM out-of-process
servers and a new version of the standard communication DLL that are
part of the new Gateway components associated with dbObjects. These are:
VPGw20.exe |
Gateway Controller Service Application |
VPGwsv20.exe |
Multi-threaded Gateway Server |
VPCtrl20.exe |
Gateway Control Server |
VPChnl20.ede |
Gateway Channel Server |
|
VPmv20.dll |
Vantage
Communication Protocol Library |
The
Gateway Controller Service (VPGw20) application is programmed as
a Windows Service and is used to startup or shutdown the Gateway
object of the Multithreaded Gateway Server (VPGwsv20) executable.
During startup the Gateway object instantiates the Control
object from the VPCtrl20 executable and places its reference into
the Windows Running Object Table (ROT). During the Control object
initialization individual Channel objects of the VPChnl20
Executable are instantiated with references added to the Channels
collection object. As Remote Client applications make requests through
the gateway, individual Server objects are instantiated from the VPGwsv20
executable and get a reference to the Control object in the VPCtrl20
executable from the ROT. From there they can get assigned and receive a
reference to a given Channel object of the VPChnl20
executable with which to send on requests to the Host system. A Remote
Gateway Monitor application can instantiate a Monitor object that
gets a reference to the Control object in the VPCtrl20
executable from the ROT and from the Control object it can access
information on the last (n) number of messages from the individual Channel
objects for monitoring and reporting purposes. A diagram of this architecture
is given below:
Click image to expand
The interaction of objects and operations within dbObjects
to support communication requests such as the OpenDatabase request, an
ExecuteProc request, or a CloseDatabase is as follows:
1) An OpenDatabase request will instantiate a Request
object (one of the internal VPDb20 classes) and initializes the object
with the Application name and SessionId name (Network login user name or
supplied name).
Set mRequest = New Request
mRequest.Initialize
mDatabasesCollection.Parent.AppName, mstrSessionId
2) The Initialize method of the Request object does the
following:
a)
Starts up the Gateway server if it is not already running
using the Gateway object
If mssGatewayStatus.Item <> "STARTED" Then
Set mobjGateway = New VPGwsv20.Gatewy
mobjGateway.Startup "False"
End If
Starting
up the Gateway involves Creating a Control
object and
starting
any predefined channel objects using the OpenChannels
method.
For a direct or local use of the Gateway there usually will
not
be any predefined channel connections defined through the Gateway
Configuration Program.
b)
Creates a Server object from the Gateway to be used to send
requests
Set mobjServer = CreateObject("VPGwsv20.Server")
3) Next a connection to the host system is started using
the SendRequest method of the Request object. This method passes a
command string that includes what command number is to be executed on
the host system (i.e. vxOpenConnectionCmd), a connection handle value (in the case of an open connection it is zero because we are
making a new connection), a SessionID (Wsid), the User and Password
(ADMIN and null password), and the connect string from the MSD. The
other parameters passed include the VDD name, the MSD name, and a
timeout value (pulled from the registry Timeout value). This function
returns a connection handle if a connection is made successfully.
strRtnVal = mRequest.SendRequest(CStr(vxOpenConnectionCmd) _
& vxRM & CStr(mlngConnectHndl) & vxRM & mRequest.Wsid _
& vxRM & mstrUser & vxRM & mstrPassword _
& vxRM & strConnect, mVdd.Name, mstrMsdName, mlngTimeout)
For later command requests such as the ExecuteProc method
the SendRequest method will look like the following:
strRtnVal = mRequest.SendRequest(strCmd _
& vxRM & CStr(mlngConnectHndl) & vxRM & CStr(mlngServerHndl) _
& vxRM & CStr(mlngDbHndl) & vxRM & Name _
& vxRM & strParams, mVdd.Name, mstrMsdName, mlngTimeout)
4) The SendRequest method of the Request object passes on
the supplied parameters to the Server object Request method of the
Gateway (VPGwsv20.exe) and passes back any returned values.
5) Within the Gateway Server object the Request method uses
the Control object of the Gateway to get an assignment to a particular
channel object of the Gateway. It assigns a channel based on the passed
Vdd name. If there is not a channel object created for a particular Vdd
name then a new channel object is created and that new channel object
that is passed back as an assigned channel. Getting a channel assignment
occurs only once for Gateway Server object. From that point on any other
requests to a given Server object uses the already assigned Channel
object.
Set mChannel = mControl.GetChannel(VddName)
If the Channel object is enabled, the Request method of the
Server object gets a request id from the Gateway control object and then
sends on the command request to the Channel object’s SendMessage
method.
strRequestID = mControl.GetRequestID
mChannel.SendMessage(strRequestID, Command, strResult, _
User, AppName, Timeout)
The
Channel object’s SendMessage is where the actually communication to
the host system occurs. An internal function within the Channel object
communicates to the VPmv20 communication DLL and the request is
transmitted to the Host system. Any results are passed back up the line
to the client database object.
6) A CloseDatabase request will close an open connection to
the host system. This process is started using the SendRequest method of
the Request object. The method passes a command string that includes
what command number is to be executed on the host system (i.e.
vxCloseConnectionCmd), and a connection handle. The other parameters
passed include a timeout value (pulled from the registry Timeout value).
A connection to the host maintained by the Channel object is not
actually closed so that it can be reused by other client requests or
other users, but the Server object held by the Request object is
released and the Request object is also released. For a local connection
where the gateway process is controlled by the client (rather than
started as a service) the reference to the actual Gateway object is also
released and the Gateway process is shutdown including any open channel
objects.
Gateway
Configuration
Normally
the Gateway Server objects will be configured to run on a centralized
Windows 2000 server (NT is also supported) and all client interaction is
remote to the Gateway system. This is accomplished by setting Client and
Gateway configuration values that are stored in the system registry.
There are new configuration programs for maintaining these registry
values. Having a client connect use remote connections will allow all user requests to be routed
to a central server where the requests can be multiplexed to a series of
pre-opened, cached Channel connections. The new Gateway Service is set
up so that each client request is processed by its own Server object and
assigned to one of several Channel objects for communication to the MultiValue Host system. This provides a safe, scalable, multithreaded
process that maximizes data communication to the Host MultiValue
database system.
When a client makes an initial connection, using a given VDD name, it creates a server object
(VPgwsv20:Server) within the
gateway software (VPgwsv20.exe) and this Server object goes to a Gateway
Control object (VPCtrl20:Control) and asks, “Do you have any channel
objects created for my VDD name?” The Gateway Control object then
assigns an existing Channel object (VPChnl20:Channel) to that Server object and the Client
software then uses that assigned Channel object for any communication to
the host system. If there are no Channel objects that already exist for
a given VDD name then the Control object is responsible for creating a
new Channel object to support a given Virtual Database Definition (VDD).
When the Gateway service is started up it looks at the system registry
to see if there are any pre-defined VDDs and channel counts it should
use in initializing a set of Channel objects. These system registry
values are maintained by the Gateway Configuration program
(VPGwm20.exe). Any clients using those same VDD names when making a
connection will reuse those initial Channel objects and this gives the
Gateway the ability to multiplex the connection process with each Channel
object running as a separate executable and therefore a separate thread
of operation.
Now if a client makes a request through a channel that
takes longer then the timeout values for a channel then the request
fails and that Channel object is marked as disabled along with a new Channel
object being created in its place using the same VDD. A timeout situation
should be a very rare occurrence and if your system is properly tuned
(with proper values for both request timeout and packet timeouts) then
it should never happen under normal circumstances. If you are experiencing a number of timeouts and
failed channels then your timeout values are not set correctly or you
are calling some stored procedure that is failing or taking to much time to
execute and should probably be constructed in a way that uses phantom
processing. This would involve breaking the stored procedure into two parts, one that
starts the phantom and executes the needed process, saving any results
into a file, and another stored
procedure that checks for the results. In designing your stored
procedures the maximum time that should be allow for execution is about 5 to
10 seconds. Anything that takes longer than this would be a candidate to
use a phantom process.
The Packet timeout value deals with the time it
takes to process a TCP/IP packet within the Vantage mvServer communication protocol. This
value is the maximum time it should have to wait for a send packet and
acknowledge packet roundtrip. The value set for this property does not
effect overall communication speed, but it does set a tolerance value
that can allow the system to handle occasional network slow downs and
latency issues within the network. You should set this value to at least
1500 milliseconds or more to allow for the occasional slowness due to
network traffic or server network problems within TCP/IP. The Request
Timeout value determines how long the client process (in this case the
channel) should wait for a response from the host system. A recommend value
should be anywhere from 5000 to 15000 milliseconds which represents 5 to
15 seconds to process a stored procedure and return a result. What you set
this value to depends on the type of stored procedures you have designed
and the expectation that you have that a stored procedure can complete
its assigned task and get back within the Request timeout value. If you
set this value to high then when there is a failure of a request the
channel will have to wait for the full prescribed time which will block
any processing for all clients who share that channel. For this reason
you should not set this value unreasonably high such as a minute for
more.
Objects
provided by the Gateway Servers
VPGwsv20
Server
(Threading model: Thread pool of 10)
Gateway Object (Instancing: MultiUse)
Object Members:
Shutdown
Startup (Options*1)
Monitor Object (Instancing: MultiUse)
Object Members:
GetChannelReports*4
Server Object (Instancing: MultiUse)
Request(Command*2, VddName, MsdName, User, AppName)
VPCrl20
Server (Threading
model: Thread per object)
Control Object (Instancing: MultiUse)
AddChannel (VddName)
CloseChannels
GetChannel (VddName)
GetChannelReports*4
GetChannelStatus*5
GetRequestID
OpenChannels (Options*1)
Status [Property Get]
Channels Collection Object (Instancing: Private)
Add (ChannelID)
Count
Item (ChannelID)
Remove (ChannelID)
VPChnl20
Server (Threading
model: Thread pool of 1)
Channel Object (Instancing: SingleUse)
ChannelID [Property Get]
ChannelProps [Property Get]*3
ChannelReport*4
Enabled [Property Get/Set]
LastError [Property Get]
LastError Description [Property Get]
SendMessage (RequestID, Command*2, User, AppName, TimeOut)
ServerName [Property Get]
Shutdown
Startup (ChannelID, ServerName, VddReference, LoginName, TimeOut)
Notes on some of the data structures associated with Gateway Object
parameters:
1) Options is a dynamic array string (vxAM,
vxVM) with the following architecture:
|
Element |
Description
|
|
Startup |
Code to control startup of Gateway: M = enable Channel
Monitor
window and Systray Icon; S = enable Channel
Monitor
window, Systray Icon, and show splash screen;
N
= disable all display windows and Systray Icon.
|
|
Timeout |
Number
of milliseconds for full message processing.
|
|
LogPath |
Set
the path name for the Log files on the Gateway System.
|
|
LogTimePeriod |
Set
time period before starting new log file. Options are
(N)o logging, (D)aily
(vpgwlog_yymmdd.log), (W)eekly (vpgwlog_yyww.log), or (M)onthly
(vpgwlog_yymm.log).
|
|
MsgCount |
Set
the maximum messages kept for status reporting.
|
|
NotifyEmailList |
List
of E-mail address to send failure or problem reports that the
Gateway system encounters during operations. Names are delimited
by semicolon.
|
|
ServerNameList |
List
of Server Names setup for Gateway operations.
|
|
ServerVddList |
List
of Virtual Database Definition references for each Server.
|
|
ServerChannelCnt |
List
of Channel Counts for each Server.
|
|
ServerChannelEnabled |
List
of Status Flags (Enabled:True/False). |
2) Command is a dynamic array string (vxRM)
with the following architecture:
|
Element |
Description
|
|
Code |
Protocol
command code.
|
|
ConnectHndl1 |
Connection
Handle parameter.
|
|
CommandParams |
Command
parameters which can include:
ServerHndl
- Server Handle parameter.
DatabaseHndl
- Database Handle parameter.
ProcName
- Stored Procedure Name parameter.
Parameters*
- Other command parameters.
*The Parameters value is a dynamic string
array (vxAM, vxVM, vxSVM) of argument values used for Stored
Procedures or other Protocol commands. The dynamic array
architecture varies based on the Command Code involved. |
3) ChannelProps is dynamic string array (vxAM)
of Channel properties with the following architecture:
|
Element |
Description
|
|
VddName |
The
name of the VDD used to open channel.
|
|
MsdName |
The
name of the MSD used to open channel.
|
|
LoginName |
The
name of the Login Server name used to open channel. |
|
DbName |
The
name of the Database name preopened for channel. |
|
ConnectString |
The
connection string used to initialize connection to Host system.
|
|
RequestCount |
Number
of requests processed since Channel startup.
|
|
AverageResponseTime |
Average
elapsed response time for request processing within Channel. |
4)
Message
is a dynamic string array (Chr(1), Chr(2)) of properties and statistics
associated with a communication messages sent through a given channel of
the Gateway with the following architecture:
|
Element |
Description
|
|
ChannelID |
Channel
Identification Number.
|
|
ServerName |
Current
server name.
|
|
VddName |
Current
Vdd object name used.
|
|
MsdName |
Current
Msd object name used.
|
|
DbName |
Current
database name.
|
|
RequestID |
Request Identification Number.
|
|
Status |
Current
status messages.
|
|
UserName |
Current
User or Client network login or session name.
|
|
AppName |
Current
application name.
|
|
ConnectHndl |
Current
connection handle.
|
|
ServerHndl |
Current
server handle.
|
|
DbHndl |
Current
database handle.
|
|
QueryHndl |
Current
query handle.
|
|
CommandCode |
Message
command code.
|
|
SPName |
Stored
Procedure name.
|
|
CommandString |
Command
message with parameters. |
|
Results |
Return
values from message execution.
|
|
ErrorCode |
Error
Code.
|
|
ErrorDescription |
Error
Description.
|
|
Time |
Time
of message
|
|
Date |
Date
of message.
|
|
BeginTime |
Begin
time of message being sent.
|
|
EndTime |
End
time when results or errors returned based on execution of
message.
|
|
ElapseTime |
Elapse
time in milliseconds of message processing. |
5) ChannelStats is a dynamic string array
(Chr(1), Chr(2)) of gateway operational statistics.
|
Element |
Description
|
|
ChannelID |
Channel
Identification Number.
|
|
ServerName |
Current
server name.
|
|
VddName |
Current
Vdd object name used.
|
|
MsdName |
Current
Msd object name used.
|
|
DbName |
Current
database name.
|
|
ChannelStatus |
Current
Status of Channel [Enabled/Disabled].
|
|
RequestCount |
Number
of requests processed since startup.
|
|
AverageResponseTime |
Average
elapsed response time for request processing.
|
|
LastError |
Last
recorded Error Code.
|
|
LastErrorDescription |
Last
recorded Error Description. |
 dbObjects Overview
For additional information or to request the latest release of mvComponents Suite
2.0, please send an E-mail to:
support@vpsoft.com
|
