Using Caché Direct
VisM.ocx Control Details
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter provides reference details for the Caché Direct ActiveX control (VisM.ocx). It discusses the following topics:

This control is a wrapper for the C++ classes listed in a later chapter.
VisM Extended Connection String Syntax
The Server property, Connect() method, and SetServer() method can all use a connection string, which is a pieced string that uses a colon for the delimiter. Usually it has the following form (as described in Connection Strings and Connection Tags):
"CN_IPTCP:server[port]"
The first piece of this argument, CN_IPTCP, is the connection method, which is always TCP. The second piece is the server name or IP address and port where the Caché superserver is running. For example, you could use the following syntax to set the connection of a VisM named VisM1:
VisM1.Server = "CN_IPTCP:127.0.0.1[57772]"
Runtime Form of the Connection String
For historical reasons, the connection string can have a slightly different form at runtime. Specifically, if you are connected, the connection string has an odd number of pieces, because Caché Direct inserts a third piece to this property, after the superserver information, as follows:
"CN_IPTCP:server[port]:slaveserver[port]"
This new third piece indicates the slave server to which you are connected. It has the same form as the master server piece. If you are not currently connected, this property is empty.
Usernames and passwords cannot contain characters that are used as delimiters in the connection string. These include the colon (":", the $Piece delimiter), and square brackets ("[" and "]", used to separate the port number).
Other Forms of the Connection String
The connection string can include the username and password; these are used only if you have enabled the Caché Direct login option. This login option has been rendered obsolete by Caché security and is thus not documented apart from this mention.
Caution:
Use of this form is discouraged. If you include a password in the connection string, your Caché is susceptible to any simple attack.
The connection string can include the username and encrypted password as follows:
"CN_IPTCP:server[port]:username:password"
In this case, if you are connected, the connection string would have the following form at runtime:
"CN_IPTCP:server[port]:slaveserver[port]:username:password"
Alternatively, the connection string can include the username and unencrypted password. If you are connecting to a 5.2 or later server, note that Caché requires the password in unencrypted format.
"CN_IPTCP:server[port]:username:@password"
In this case, if you are connected, the connection string would have the following form at runtime:
"CN_IPTCP:server[port]:slaveserver[port]:username:@password"
Note:
If your client is 5.2 or later, then the client automatically uses your Windows authorization information (username and password) for Kerberos validation if needed (see Connecting with an Indirect Reference for details on connections that use Kerberos authorization). This supplements the Caché Direct login (rather than replacing it). If Caché security is not turned on, then Caché Direct bypasses the Kerberos checking, but still passes the username/password if they are given. The server then does whatever is switched on at that end.
VisM Properties
The VisM control has a set of properties that are mirrored on the server, as well as other properties.
Mirrored VisM Properties
Caché Direct mirrors the values of certain VisM properties between the client and server, as described in the section Mirrored Properties in the chapter Basics of the VisM Control.
If you are using these properties for one-way communication – and especially if they are large – clear them before returning values from the server. Otherwise, your application will waste communication resources. See the chapter Best Practices. As with all other properties that the client sends to the server, the values must have only text characters; see the section Unicode and Locale Issues in that chapter.
P0, P1, P2, P3, P4, P5, P6, P7, P8, P9
These properties are mirrored on the client and server. On the client, they appear as properties of the VisM control; on the server, they appear as local variables, having the same values as the corresponding properties on the client.
PLIST
This property is mirrored on the client and server in a different manner. Because the client and Caché have different representations of arrays, Caché Direct uses this property to pass array-like values between the server and client. The property has a different form on the client and server. For complete details, see the section Using PLIST in the chapter Basics of the VisM Control.
VALUE
This property is mirrored on the client and server in the same way as P0, P1, and so on, with one addition: If the value of the Code property begins with a dollar sign or an equal sign, the server prepends “Set VALUE” or “Set VALUE =” to the start of the Code property. This means that the result is returned in the VALUE property in such a case.
Other VisM Properties
This section lists the other VisM properties (the properties that are not mirrored). Note that some of these properties are sent to the server.
Code
Contains the line of ObjectScript code that is sent to the server for execution. As with all other properties that the client sends to the server, this string must have only text characters; see the section Unicode and Locale Issues.
ConnectionState
This property always indicates the state of the connection. It is used in conjunction with the keep alive feature and tells an application whether the client has had a communication failure and, if so, when the connection was broken.
If ConnectionState is zero, the connection is OK or a successful disconnect has occurred. If the property is nonzero, then it indicates the time of day (in seconds since midnight) when the server was lost. (This is the same as the second piece of $Horolog. The day is not indicated; it is presumed to be recent.) This property is a long integer.
ConnTag
Runtime only. Indicates the tag of the CDConnect to which this VisM is connected. If you change this property, you change the tag of the associated CDConnect itself, rather than changing the connection. This property is mainly useful for informational purposes. Note that if this property is an empty string, either there is no connection or there is a connection but no tag is associated with it.
ElapsedTime
Indicates how long it took Caché Direct to process the last message; this is the time from when the client sent the message to the time when the client received a reply. This property is read-only at runtime.
Error
Contains an error number. If it is zero, no error has occurred. This property is read-only at runtime. See the description of the ErrorName property, next.
ErrorName
A string describing an error that has occurred. If it is empty, no error has occurred. This property is read-only at runtime.
The Error and ErrorName properties are set after every server call. If the call is successful, Error is set to 0 and ErrorName is cleared. If an error is reported from the server, the error number is set into Error and a short description is set into ErrorName. While these are not always fully distinctive or descriptive, they still allow the client portion of the application to inform the user that something has gone wrong and to take some action.
Note that errors reported at this level are errors noticed by the server, usually programming errors such as <SYNTAX> or <UNDEFINED>. Logical errors, inconsistencies, and others noticed by the application code should be reported by the application in its results. There are features in the server that allow an application to return error conditions through the Error and ErrorName properties.
ErrorTrap
Controls the handling of communication errors. There are two classes of errors that may occur in a Caché Direct application: errors in the communications process itself, and errors that occur in the application and are reported back to the client.
For historical reasons, the default value for ErrorTrap is False. You should usually set ErrorTrap to True before trying to connect to Caché from the VisM.
This matters only if the application is running without a user or if you want the application to handle such errors automatically.
ExecFlag
A switch that controls when the line of code in the Code property is executed. Its default value is 0, indicating that the client is idle and not sending messages to the server. Possible values:
A common use of the timer option is to do something periodically and use the Executed event to respond after each execution. To use the timer option, use the following overall flow:
  1. Set ExecFlag to 0.
  2. Set values for all the relevant mirrored properties and for the Interval property.
  3. Then set ExecFlag to 3 to switch on the timer.
Remember that all communication with the server is synchronous. The client must receive the reply to the current message before sending the next message. Using timers can occasionally cause the client to try to send a nonsynchronous message. For example, a user might perform an operation that generates a message while a timer-generated message is in progress. In this case, the client will receive a “nonsynchronous message” error, and the message will be not be sent.
Interval
The number of milliseconds between automatic execution of the Code property. The default value is 1000 milliseconds (= 1 second). See the ExecFlag property for value 3.
KeepAliveInterval
Specifies the interval between automatic keep alive messages from the client. It is an integer number of seconds. These messages are sent whenever the client is otherwise idle and the interval has expired.
KeepAliveTimeOut
Specifies how long the client waits for a reply from the server, after sending a keep alive message to the server.
LogMask
Used for debugging on the client side. This is a 32-bit integer property, with each bit assigned as a flag for a particular type of logging. If logging is on at any time during the run of a process, a text log file will be created in the same directory from which the executable is run. Its name will be CDxxx.log, where xxx is the next available sequential number, starting at 000. (So, the first time a log is created, it will be CD000.log.) . The log is closed when the process exits.
To enable client-slide logging, turn all the bits on by setting the value of this property to 2,147,483,647 (231 – 1). In Visual Basic, you can use &H7FFFFFFF, which is the hexadecimal representation of the same number. To turn off logging, set the value to 0.
The contents of the log are best interpreted by InterSystems personnel, but they include a trace of most of what happened to the VisM and a full dump of all the messages sent to and received from the server. It tends to err on the side of too much information rather than too little. If it is needed, it can be very helpful as a real-time record of what actually happened.
MServer
Has the same purpose as the Server property and can be set to any of the same values as that property. This property is provided only for backward compatibility and should not be used in new applications. See the appendix Notes for Users of the Previous Versions.
MsgText
A four-piece string that specifies the message to display when asking the user whether to cancel (see the PromptInterval property). This property must be a string of the form:
"prompt_message|title_text|OK_button_text|Cancel_button_text"
The message dialog box that is displayed has a window title (as given by title_text) and longer message (as given by prompt_message). The dialog box also has two buttons that have text labels.
The default value of this property is as follows:
"This may take a while. Do you wish to wait?|
Communications|Wait for Reply|Cancel Wait"
When you set this property, you can omit any piece. The client uses the default for any string piece that you omit or that you set to a zero length string.
NameSpace
Establishes the namespace context of the routines and globals referenced by the application code. The default value is the empty string. In that case, the routines and globals are referenced in the namespace in which the server is running. When the execution message arrives at the server, if the NameSpace property is not empty and is different from the current namespace, the namespace is changed as indicated. This occurs before the code is executed.
Remember that there is a significant cost to changing the namespace; see the chapter Best Practices.
PDELIM
The delimiter string used with the PLIST property; see the section Mirrored VisM Properties. It is read/write at runtime, which means it cannot be set at design time. For historical reasons, the default value is the string $C(13,10). If it is set to the empty string, there is effectively no delimiter and PLIST is taken as a single element. Note that this property is not sent to the server.
PromptInterval
Specifies how long to wait, in seconds (not milliseconds), before asking whether the user wants to keep waiting or cancel the activity (which is typically a long query). This prompt is displayed only if the server has not yet replied. This prompt would give the user the option of waiting longer or of canceling the activity. The MsgText property specifies the text of the message to display in this case. If the property is zero or negative, the user is never prompted; the default is zero.
Server
This property serves two purposes.
You can set this property to a connection string, a connection tag, a quoted question mark, or an empty string. For details on connection strings, see the section VisM Connection String, earlier in this chapter.
Setting the Server property has the same effect as calling the SetServer() method. See the section Comparison of Connection Methods, later in this chapter.
Tag
Not used by Caché Direct. This property exists for compatibility with Microsoft Visual Basic conventions. You may use it any way you wish.
TimeOut
The integer number of milliseconds that the client will wait for a reply from the server. The time is measured from just after the message is sent through TCP to when Windows reports that data has been received. When the timer goes off, meaning that no reply has been received within the allowable time, the connection is broken, which normally causes a TCP error on the server, causing it to shut down. The client then regains control with an error condition that can be handled. If the application wishes to proceed, it should create a new CDConnect, which will create a new slave server job, with access to the globals (naturally), but none of the local state of the old server job.
If this property is negative or zero, the client will wait forever for a return message. The default value is 60000 (60 seconds).
VisM Methods
The VisM control provides the following methods:
Connect
Connects this VisM to the specified Caché server, creating a new CDConnect if needed. Use any of the following syntaxes:
Connect(connection_string, tag)
Connect(connection_string)
Connect("?", tag)
Connect("?")
Connect(tag)
Connect("")
connection_string A string of the form CN_IPTCP:server_name[port] where server_name is the DNS name or the IP address of the machine that is running Caché and port is the port that the Caché superserver is using. Also see the section VisM Connection String earlier in this chapter.
tag An optional string that acts as the name for the newly created CDConnect object. Note that it is your responsibility to make sure that each tag is unique within a given client process, at any time.
"" In this case, VisM connects to most recently opened CDConnect, after first disconnecting if applicable. The original CDConnect is not changed.
For details on the behavior, see the subsection Comparison of Connection Methods.
DeleteConnection
Disconnects from and destroys the CDConnect connected to this VisM, and shuts down the server job.
Execute
This method is a shortcut way of setting the Code property and calling the server. It is exactly equivalent to saving the Code property, setting the Code property to the argument to the Execute method, setting the ExecFlag property to 1 to cause execution, and then restoring the Code property to what it was before the call. All error trapping and execution of the OnError and Executed events occurs in the same way.
LoadRtnFromFile
Obsolete. Do not use.
LoadGblFromFile
Obsolete. Do not use.
SetMServer
Has the same purpose as the SetServer() method. This method is provided only for backward compatibility and should not be used in new applications. See the appendix Notes for Users of the Previous Versions.
SetServer
Closes the existing connection for this VisM and creates a new connection, as specified. In contrast to the Connect() method, the SetServer() method can change the channel of an existing CDConnect. Use any of the following syntaxes:
SetServer(connection_string, tag)
SetServer(connection_string)
SetServer("?", tag)
SetServer("?")
SetServer(tag)
SetServer("")
connection_string A string of the form CN_IPTCP:server_name[port] where server_name is the DNS name or the IP address of the machine that is running Caché and port is the port that the Caché superserver is using. Also see the section VisM Connection String earlier in this chapter.
tag An optional string that acts as the name for the CDConnect object. Note that it is your responsibility to make sure that each tag is unique within a given client process, at any time.
"" In this case, VisM disconnects from the CDConnect, leaving its channel alone.
For details on the behavior, see the subsection Comparison of Connection Methods, next.
Comparison of Connection Methods
The following table describes the actions of the SetServer() and Connect() methods.
First Argument SetServer Method Connect Method
Connection string Action depends on whether already connected:
  • If not yet connected, connect to this server
  • If already connected, change channel of the CDConnect (and shut down old server process)
Action depends on whether already connected:
  • If not yet connected, connect to this server
  • If already connected, disconnect from the original CDConnect and connect to a new CDConnect (original CDConnect is not changed)
Connection tag Connect to specified CDConnect (disconnecting first if already connected; original CDConnect is not changed) [permitted as of Caché version 2007.1] Connect to specified CDConnect (disconnecting first if already connected; original CDConnect is not changed)
Empty string Disconnect from the CDConnect, leaving its channel alone Connect to most recently opened CDConnect (disconnecting first if already connected; original CDConnect is not changed)
Quoted question mark Prompt user for a server and then:
  • If not yet connected, connect to this server
  • If already connected, change channel of the CDConnect (and shut down old server process)
Prompt user for a server and then:
  • If not yet connected, connect to the specified server
  • If already connected, disconnect from the original CDConnect and connect to a new CDConnect (original CDConnect is not changed)
Setting the Server property has the same effect as calling the SetServer() method.
Note that multiple VisMs sharing a single CDConnect should not try to communicate simultaneously. If they do, you will get a "nonsynchronous communication error" message.
VisM Events
Executed
This event is fired after every attempt to execute code on the server, whether successful or not. If an error occurred, the OnError event is fired before the Executed event.
OnError
This event is fired any time the server reports an error to the client (that is, whenever the Error and ErrorName properties are set to non-empty values). If the error occurred while trying to execute some code, OnError is fired before the Executed event.
ShutDown
This event is fired if any server message times out or if the server indicates it is in the process of shutting down. Your application can use this to inform the user, perform a graceful shut down, or attempt a reconnection. The integer argument to this event is the value of the ConnectionState property, the time when the server was lost.
Once a connection has been lost, further attempts to send a message result in a <ServerLost> error.