Syntax of VIC Requests

In order to view VTS application information using Microsoft Internet Explorer, you issue a request to the VTS/IS by entering a destination into the Address field of your web browser.  It is worthwhile to understand the syntax of the address used to connect to an application page on a VTS/IS.

The address that you supply to your web browser is termed a Uniform Resource Locator (URL).

The general format of a URL is defined as:

{Protocol}Server{:Port}/Realm{/Verb}{/Application or GUID}{/Page}{?Parameters}

where curly braces {} define optional components of the URL.   Forward slash (/) characters, the colon (:) character, and the question mark (?) character are to be typed and serve as delimiters between each component. If an optional component is omitted, the delimiter immediately preceding it is also omitted. Each of these component parts is discussed in detail in the following sections.

Protocol

The {Protocol} component is optional. If specified, it must be either:

http://

or

https://

http:// (the default if this component is omitted) indicates that you are using plaintext HTTP (i.e. not encrypted) protocol to access data on a VTS/IS, whereas https:// indicates that the server to which you are attempting to connect is configured to use SSL (the Secure Sockets Layer protocol), for security.

Server{:Port}

The Server component is mandatory, and specifies the name or IP address of the VTS/IS. The Server component may be as simple as just a host name, if operating over a company intranet, or it may take the form of a fully qualified host and domain name, if operating over a wide area network or the Internet.

Optionally, the Server component may be suffixed with a : and the numeric port number on which the VTS/IS has the desired realm configured.

Realm

The realm component is mandatory and specifies the name of a realm configured on the VTS/IS (see Realms for more information).

Verb

Whereas the Protocol, Server, and Port components identify the server to be located and the protocol to be used to communicate with that server, the Verb describes the action to perform with the VTS/IS. The Verb component is optional, and may be one of the following:

 

Verb	Parameters	Description
AppsList	No parameters.	Generates a list of available applications within the specified realm.
	Example:   http://WHITE/TELRealm/AppsList
ViewApp	/Application or GUID required. For a VTS application (not a script application), /Page is required.	This is the default Verb, if no verb is specified. For a script application, runs the specified application and displays the application's graphical output. For a VTS application, displays the requested page within the last selected VIC window. If there is no VIC window for the specified application, a new window is created to display the requested page.
	Example:  http://WHITE/TELRealm/ViewApp/7fd9d82c-9ab9-11d1-a122-0060971477af/Chloride?x=50&y=50&w=720&h=640 Requests that the application page titled "Chloride" belonging to the application identified by the 36 character GUID be displayed in a secondary window that is sized 720 pixels high by 640 pixels wide, anchored at coordinates x=50 and y=50.
ViewWin	/Application or GUID required. For a VTS application (not a script application), /Page is required.	For a script application, runs the specified application and displays the application's graphical output. For a VTS application, displays the requested page within a new window.
VTS-Bin	/Application or GUID required. /Page is required (see description).	This verb causes a VTS subroutine module to be invoked on the server, allowing custom actions to be performed in response to the URL. This is an advanced function and should only be used by experienced VTS programmers.
	Example:  http://WHITE/VTS-BIN/7fd9d82c-9ab9-11d1-a122-0060971477af/HTMLMenu Requests a list of pages for the application identified by the 36 character GUID by directly running the "HTMLMenu" module.

Application or GUID

If the Verb requires an Application or GUID component to be specified, this is the name of an application within the specified realm, as it appears in the VTS Application Manager window or the output of an AppsList Verb. Alternatively, the application GUID may be provided. This is the 36-character GUID that VTS generates for each application and stores in the application's GDI.WIF file.

Page

If the Verb requires a Page component, this must be the name of a page within the specified VTS application that the user has permission to access. The only exception to this is the VTS-Bin Verb, when Page is the name of a subroutine module to be executed. Please refer to "VTS Programmer's Guide: URL Syntax" for more information on the VTS-Bin Verb.

Parameters

Parameters are always optional, and, if present, are the final parts of the URL. Parameters consist of one or more Parameter Name/Value pairs, with the first pair separated from the Page by the delimiting question mark character (?). Subsequent pairs are separated from each other by the delimiting ampersand character (&). A Parameter Name/Value pair consists of the parameter name separated from the value by the equals character (=). For example:

?x=50&y=100

specifies two parameters, the first assigning the value 50 to variable x, and the second assigning the value 100 to variable y.

VTS/IS provides four standard parameters: X, Y, W, and H. These control the X and Y coordinates of the upper left corner respectively, and the width and height of the VTS/IC window, in pixels.

Parameters can also be used with the VTS-Bin Verb. Please refer to "VTS Programmer's Guide: URL Syntax" for more information.

Minimum Requests

Unless you have special requirements, you will probably use the minimum request that you need in order to access a VTS/IS. This section presents some typical URLs that will suffice to get you started.

The URL:

Workstation9/Realm1

is sufficient to invoke the default page on the first configured application in realm "Realm1" on VTS/IS "Workstation9", using plaintext (i.e. not encrypted) HTTP protocol. Note that Workstation9 is a simple host name and therefore will be assumed to be within the same domain as the VIC. Assuming that the first configured application within the realm was called "SCADAApplication", and the default page for that application was configured to be "Page1", the above URL is equivalent to the more verbose form:

http://workstation9/realm1/ViewApp/SCADAApplication/Page1

Further, if we assume the domain of which the VTS/IS and VIC are members to be "trihedral.com", then we can also say that the following URL is also equivalent to the above.

http://workstation9.trihedral.com/realm1/ViewApp/SCADAApplication/Page1

If, instead, you wished to display "Page2", you must supply the page name, as "Page2" is not the default page. To do this, you will need to provide all the optional components of the URL to the left of the Page component and to the right of the Realm component. The minimum URL to do this would therefore be:

workstation9/realm1/ViewApp/SCADAApplication/Page2

On the first occasion that you attempt to access the VTS applications associated with a selected realm, you will be authenticated by the VTS Security Manager before you are permitted access; however, before you submit your username and password for authentication, it is recommended that you confirm that you are submitting your authentication data to the legitimate VTS/IS by authenticating the SSL certificate. The sections that follow provide instructions on the validation of an SSL certificate, and the authentication process.