ActiveXperts Networking Component Manual

ActiveXperts Software B.V.  contact@activexperts.com

 

1. Introduction

1.1. Introduction

Adding network communications capabilities to an application is not a simple matter. It requires specialized knowledge that might be outside an individual programmer's expertise. For years, VBScript, Visual Basic and Visual C++ developers have relied upon the power, flexibility and reliability of the ActiveXperts Networking Component from ActiveXperts Software. And today, also .NET developers use this control.

With the ActiveXperts Networking Component you can communicate across IP networks, including the Internet. ActiveXperts Networking Component provides an easy-to-use scripting interface for IP communications. The ActiveXperts Networking Component supports both IPv4 and IPv6 protocols. By using the ActiveXperts Networking Component, you can very easily create or enhance applications with network features.

Use the ActiveXperts Networking Component to integrate the following IP protocols in your application or script:

  • Dns - Query servers running a domain name service (DNS) application. Query DNS for specific information about hosts, like mail exchanger records [MX], IP address [A], canonical names [CNAME], etc.;
  • Ftp - Log on to an FTP server, change directory, list files, upload files (ftp/put), download files(ftp/get), create directories, delete directories, rename files, delete files, etc.;
  • Http/Https - Log on to a web server, get the web pages and analyze the contents. Support for Proxy servers, SSL and password protected web sites;
  • ICMP - See if you can reach another computer; Determine how long it takes to bounce a packet off of another site, which tells you its distance in network terms;
  • IP to Country - Translate an IP address to the associated country;
  • Msn - send an MSN message to one or more remote MSN recipients;
  • NTP - Query NTP time servers and retrieve the actual date and time. Calculate offset between servers to see if your LAN time is set properly;
  • RSH - Run a Shell Script on a remote UNIX or LINUX computer that runs the RSH (Remote Shell Script) daemon. Read StdErr and StdOut of the remote shell script;
  • SNMP - Query SNMP compliant devices and analyze the result. Set a value on a remote SNMP agent. Send SNMP traps to remote SNMP Managers, and receive incoming SNMP traps. Support for SNMP v1, SNMP v2c and SNMPv3; Use the SNMP Browser to browse through an SNMP MIB file;
  • SNMP Traps - Send and receive SNMP traps to (remote) SNMP agents. Support for SNMP v1, SNMP v2c and SNMP v3;
  • SNMP MIB Browser - Load a MIB database into memory and iterate over all objects and view all properties;
  • SSH - Login onto a remote machine running the SSH daemon, and execute a command or shell script in a secure way;
  • TCP/IP client/server communications - Create your own client/server applications; your server-application listens for an incoming connection on a specific port, while your client application makes a connection to it; Client and server can communication bidirectional, with support for ASCII and binary data, in your LAN or through the internet;
  • Telnet - Automate Telnet sessions. Use the Telnet object to logon to a switch or router and make changes to the configuration. Log on to a mail server and list all items. Access a print server through telnet and reboot it. There are many devices and services that can be accessed by this Telnet object;
  • Tftp - Trivial FTP protocol with limited functionality. It uses UDP to upload files (put) and download files(get);
  • UDP communications - UDP-based client/server (peer-to-peer) communications and UDP broadcasts.
  • VMware; Retrieve performance counters and virtual machine information from VMware Xen hosts;
  • Wake-On-LAN (WOL); Wake up machines on your LAN, based on their MAC address;
  • Xen; Retrieve performance counters and virtual machine information from XenServer hosts;

ActiveXperts Networking Component can be used by any of the following operating systems:

  • Windows 2012 (64-bit)
  • Windows 2008 (32-bit and 64-bit)
  • Windows 2003 (32-bit and 64-bit)
  • Windows 2000 (32-bit)
  • Windows 8 (32-bit and 64-bit)
  • Windows 7 (32-bit and 64-bit)
  • Windows Vista (32-bit and 64-bit)
  • Windows XP (32-bit and 64-bit)

ActiveXperts Networking Component can be used by any of the following development languages:

  • Visual Basic .NET - Windows .NET based application
  • Visual C# .NET - Windows .NET based applications
  • Visual Basic 5.x or higher - Windows based applications
  • Visual C++ 5.x or higher - Windows based applications
  • Deplhi 7.x or higher - Windows based applications
  • ASP .NET - Web site based on Active Server Pages and the .NET Framework
  • ASP 2.x - Web site based on Active Server Pages (server-side scripting)
  • PHP - Embedded HTML scripting
  • VBScript - Windows based scripts
  • VBA - Visual Basic for Applications
  • Javascript - Java based scripts
  • HTML - Client scripts within HTML pages
  • ColdFusion - Server based web applications
  • Any other development platform that supports ActiveX/COM components

1.2. Architecture

The core of the ActiveXperts Networking Component is an ActiveX/COM component that comes in a 32-bit and a 64-bit version:

  • AxNetwork32.dll - the 'ActiveXperts Networking COM Component' for 32-bit platforms;
  • AxNetwork64.dll - the 'ActiveXperts Networking COM Component' for 64-bit platforms;

ActiveXperts Networking Component can be distributed easily to any server and workstation in your network. This requires a Processional License, see also Once you have purchased the licenses, you copy the AxNetwork32.dll (or AxNetwork64.dll for 64 bit applications) to the PCs and register the DLL on that PC. Click here for more information about the installation.

2. System requirements

2.1. Operating Systems

ActiveXperts Networking Component can be used in any of the following operating systems:

  • Windows 2012 (64-bit)
  • Windows 2008 (32-bit and 64-bit)
  • Windows 2003 (32-bit and 64-bit)
  • Windows 2000 (32-bit)
  • Windows 8 (32-bit and 64-bit)
  • Windows 7 (32-bit and 64-bit)
  • Windows Vista (32-bit and 64-bit)
  • Windows XP (32-bit and 64-bit)

NOTE: On 64 bits systems, you can run 32- and 64 bit programs. To integrate ActiveXperts Networking Component in a 64-bit (web) application of service, use the 64-bit AxNetwork64.dll. To integrate ActiveXperts Networking Component in a 32-bit (web) application of service, use the 32-bit AxNetwork32.dll.

2.2. Development Platforms

The ActiveXperts Networking Component can be embedded in any Windows application, service or script. Almost all Windows development platforms allow embedding of ActiveX components, including:

  • Visual Basic .NET
  • Visual C# .NET
  • Visual Basic 5.x or higher
  • Visual C++ 5.x or higher
  • Delphi 6.x or higher
  • ASP .NET
  • ASP 2.x
  • PHP
  • ColdFusion
  • VBScript
  • Javascript
  • HTML
  • Any other development platform that supports ActiveX/COM components

3. Installation

3.1. Introduction

The ActiveXperts Networking Component package consists of 3 modules; any combination of components can be installed:

  • The ActiveXperts Networking Component COM components - core components 'AxNetwork32.dll' (to embed in 32-bit applications) and 'AxNetwork64.dll' (to embed in 64-bit applications);
  • The ActiveXperts Networking Component Help Files - documentation;
  • The ActiveXperts Networking Component Sample Files - samples for various development platforms.

3.2. Installation (Automatic)

To automatically install ActiveXperts Network Component, download AxNetworkSetup.exe and start the installation. The InstallShield wizard will guide you through the rest of the setup.

On 32-bit operating systems, it will automatically register the 32-bit ActiveX DLL 'AxNetwork32.dll', to support 32-bit applications.

On 64-bit operating systems, it will automatically register the 64-bit ActiveX DLL 'AxNetwork64.dll', to support 64-bit applications; it will also automatically register the 32-bit ActiveX DLL 'AxNetwork32.dll', to support 32-bit applications.

3.3. Installation (Manual)

To manually install the ActiveXperts Network Component core files, perform the following actions:

  • Perform one installation of ActiveXperts Network Component on an available computer, to extract the 'AxNetwork32.dll' and 'AxNetwork64.dll' core ActiveX files
  • To embed ActiveXperts Network Component in 64-bit applications, copy the 'AxNetwork64.dll' ActiveX file to the destination computer hard drive, and register the DLL by running the following command from the command-line on the destination computer:
    REGSVR32 <dest-location>\AxNetwork64.dll
  • To embed ActiveXperts Network Component in 32-bit applications, copy the 'AxNetwork32.dll' ActiveX file to the destination computer hard drive, and register the DLL by running the following command from the command-line on the destination computer:
    REGSVR32 <dest-location>\AxNetwork32.dll

4. How to use

4.1. Introduction

The ActiveXperts Network Component is an ActiveX component. ActiveX is a Microsoft framework for defining reusable software components in a programming language-independent way. This is why it's possible to use the Network Components in most programming and scripting languages available for Windows.

One of the most important aspects to using the Network Component may be creating an instance in the programming language of choice. O nce a reference to the ActiveX component has been made and it's objects have been instantiated the use of this component should be very straightforward.

In this section a couple of programming environments are highlighted and their way to access the objects in ActiveXperts Network Component is demonstrated.

4.2. Visual Basic .NET

Add a reference to the Network Component object using the Visual Basic Solution Explorer:

  • Start the Solution Explorer view, go to the project's 'References' container
  • Choose 'Add Reference' from the context menu
  • Select the COM tab, choose the 'ActiveXperts Network Component' component

The following code shows how to declare, create and use one of the Network Component objects:

Imports AxNetwork

...

Dim objTcp As AxNetwork.Tcp                          ' Declaration
objTcp = New AxNetwork.Tcp()                         ' Creation

' Display version information
Console.WriteLine("ActiveXperts Network Component {0}" & vbLf, objTcp.Version)

4.3. Visual C# .NET

Add a reference to the Network Component object using the Visual C# Solution Explorer:

  • Start the Solution Explorer view, go to the project's 'References' container
  • Choose 'Add Reference' from the context menu
  • Select the COM tab, choose the 'ActiveXperts Network Component' component

The following code shows how to declare, create and use one of the Network Component objects:

using AxNetwork;

...
    
AxNetwork.Tcp objTcp;                                // Declaration
objTcp = new AxNetwork.Tcp();                        // Creation

// Display version information
Console.WriteLine("ActiveXperts Network Component {0}\n", objTcp.Version);

4.4. Visual Basic

The Network Component can be used in Visual Basic 6.x or higher. In Visual Basic, go to the 'Project/References...' menu item and check the box next to Network Component Type Library. Now, you can declare and create Network Component objects.

The following code shows how to declare, create and use one of the Network Component objects:

Dim objTcp As AxNetwork.Tcp                          ' Declaration
Set objTcp = New AxNetwork.Tcp                       ' Creation

' Display version information
Me.Caption = "ActiveXperts Network Component " & objTcp.Version

4.5. Visual C++

ActiveXperts Networking Component can be used in Visual C++ projects. Include the *.h and *.c file provided by ActiveXperts to bind your code to the ActiveXperts Networking Component. These files are located in the Include directory of the Visual C++ samples directory. These are the files:

  • AxNetwork.h
  • AxNetwork_i.c
  • AxNetworkConstants.h

The following code shows how to declare, create and use one of the Network Component objects:

ITcp *pTcp = NULL;  
BSTR bstrVersion = NULL;
...   
// Initialize COM  
CoInitialize(NULL);                                  
 
// Create Instance   
CoCreateInstance( CLSID_Tcp, NULL, CLSCTX_INPROC_SERVER, IID_ITcp, (void**) &pTcp );
...
pTcp->get_Version( &bstrVersion  )
_tprintf(_T("ActiveXperts Network Component %ls\n"), bstrVersion );
...
SysFreeString( bstrVersion );

// Delete Instance  
pTcp->Release();

// Uninitialize COM  
CoUninitialize();

4.6. ASP Classic

To use the Network Component objects in ASP classic make sure the component has been installed on the server.

The following code shows how to declare, create and use one of the Network Component objects:

<html>
  <body>
    Version:
    <script language="vbscript" runat="server">
   
      Set objTcp = CreateObject("AxNetwork.Tcp")      ' Declaration and Creation

      ' Display version information
      Response.Write "ActiveXperts Network Component " & objSmpp.Version

    </script>
  </body>
</html>

4.7. HTML/Javascript

On top of your HTML/Javascript code, refer to the ActiveXperts Network Component in the following way:

<object codebase="http://www.activexperts.com/files/network-component/cab/4.4/axnetwork32.cab" 
        classid="CLSID:B52B14BA-244B-4006-86E0-2923CB69D881" ></object>

The following code shows how to declare, create and use one of the Network Component objects:

<script language="JavaScript" type="text/javascript">

  var objTcp = new ActiveXObject("AxNetwork.Tcp")          ' Declaration and Creation
  
  ' Display version information
  document.write("<h1>ActiveXperts Network Component " + objTcp.Version + "</h1>");

</script>

4.8. Delphi 7.x or higher

First, add a reference to the Network Component objects:

  • Go to Project->Import Type Library
  • Select 'ActiveXperts Network Component Type Library'
  • Click 'Install'
  • The project 'dclusr.dpk' will be opened. Click 'Yes'

The following code shows how to declare, create and use one of the Network Component objects:

program Project1;

{$APPTYPE CONSOLE}

' Use ActiveX, Windows and AxNetwork_TLB
uses
  SysUtils, ActiveX, Windows,
  AxNetwork_TLB;

var
 objTcp: Tcp;                                          ' Declaration

begin
  CoInitialize(nil);                                   ' Initialize COM

  objTcp := CoTcp.Create;                              ' Creation

  ' Display version information
  Writeln('ActiveXperts Network Component ' + objTcp.Version);

  CoUninitialize
end.

5. DnsServer

5.1. Introduction

DNS is the Domain Name System. DNS converts machine names to the IP addresses that all machines on the net have. It translates (i.e. 'maps') from name to address and from address to name, and some other things.

The ActiveXperts Networking Component DNS objects can be used to query servers running a domain name service (DNS) application. It will send domain name query packets to any designated DNS server. There are three data elements required in order to formulate a DNS query using ActiveXperts Networking Component:

  • DNS servername/address
  • Internet style address that is being queried
  • Type of record you are searching for

The ActiveXperts Networking Component DNS objects are useful for gathering address information about hosts in the network. It can be used to query DNS for specific information about hosts, like mail exchanger records [MX], IP address [A], canonical names [CNAME], etc. If you have an IP address, you can get a canonical name back for the address and vice versa. Another useful feature is the ability to get a listing of hosts which serve mail exchange [MX] methods for a specific domain.

The following sample (VBScript) shows how the DnsServer and DnsRecord objects can be used to list all DNS records for a specific domain name:

    
Set objDnsServer = CreateObject( "AxNetwork.DnsServer")        ' Create object
Set objConstants = CreateObject( "AxNetwork.NwConstants")

objDnsServer.Server     = "ns1.interstroom.nl"                  ' DNS server
       
objDnsServer.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_ANY                                   ' Show all DNS records 
                                                                ' for activexperts.com
WScript.Echo "Lookup, result: " & objDnsServer.LastError    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If

If ( objDnsServer.IsAuthoritative = True ) Then
    WScript.Echo "Server is an authority for this domain"
Else
    WScript.Echo "Server is not an authority for this domain"
End If
    
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Iterate over all DNS 
                                                                ' records; get first record   	
While ( objDnsServer.LastError = 0 )
    Select Case objDnsRecord.Type 
      Case objConstants.nwDNS_TYPE_A
        WScript.Echo "Type             : A"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "IPv4 Address     : " & objDnsRecord.Address
      Case objConstants.nwDNS_TYPE_AAAA
        WScript.Echo "Type             : AAAA"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "IPv6 Address     : " & objDnsRecord.Address
      Case objConstants.nwDNS_TYPE_CNAME
        WScript.Echo "Type             : CNAME"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "Alias            : " & objDnsRecord.Address
      Case objConstants.nwDNS_TYPE_MX 
        WScript.Echo "Type             : MX"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "Preference       : " & objDnsRecord.Preference
        WScript.Echo "Mail Exchange    : " & objDnsRecord.MailExchange
      Case objConstants.nwDNS_TYPE_NS
        WScript.Echo "Type             : NS"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "Name Server      : " & objDnsRecord.NameServer
      Case objConstants.nwDNS_TYPE_PTR
        WScript.Echo "Type             : PTR"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "Host             : " & objDnsRecord.Address
      Case objConstants.nwDNS_TYPE_SOA
        WScript.Echo "Type             : SOA"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "Name Server      : " & objDnsRecord.NameServer
        WScript.Echo "MailBox          : " & objDnsRecord.MailBox
        WScript.Echo "Serial           : " & objDnsRecord.SerialNumber
        WScript.Echo "Refresh          : " & objDnsRecord.RefreshInterval
        WScript.Echo "Retry Interval   : " & objDnsRecord.RetryInterval
        WScript.Echo "Expiration Limit : " & objDnsRecord.ExpirationLimit
        WScript.Echo "Minimum TTL      : " & objDnsRecord.MinimumTTL
    End Select
  
    WScript.Echo "TTL              : " & objDnsRecord.TTL
    WScript.Echo
    
    Set objDnsRecord = objDnsServer.GetNextRecord               ' Iterate over all DNS 
                                                                ' records; get next record
Wend

5.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
Server String In/Out Remote DNS Server's host name or IP address
ServerPort Number In/Out DNS Server port. Default: 53
LastError Number Out Result of the last called method
LogFile String In/Out Log file that can be used for troubleshooting purposes

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objDnsServer = CreateObject("AxNetwork.DnsServer")          ' Create new instance 
WScript.Echo  "Version: " & objDnsServer.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create new instance 
WScript.Echo  "Build: " & objDnsServer.Build

Module property

Return the module name of the Component.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create new instance 
WScript.Echo  "Module: " & objDnsServer.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create instance
WScript.Echo "LicenseStatus: " & objDnsServer.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objDnsServer = CreateObject("AxNetwork.DnsServer")          ' Create new instance
WScript.Echo "LicenseKey: " & objDnsServer.LicenseKey

Server property

Type:

String

Description:

Host name or IP address of the DNS server.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer")        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants")

objDnsServer.Server      = "ns1.xyz.intra"                      ' Remote DNS server: 
                                                                ' ns1.xyz.intra    
objDnsServer.Lookup "activexperts.com", _ 
  objConstants.nwDNS_TYPE_ANY                                   ' Lookup any record for 
                                                                ' activexperts.com    
...

ServerPort property

Type:

Number

Description:

TCP port number to identify a (remote) DNS server. If you don't specify the 'ServerPort' property, port 53 (default DNS port) is used.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer")        ' Create a new DnsServer
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants")

objDnsServer.Server      = "ns1.xyz.intra"                      ' Remote DNS server:
                                                                ' ns1.xyz.intra    
objDnsServer.ServerPort  = 8053                                 ' Use alternate port:8053    
objDnsServer.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_ANY                                   ' Lookup any record for
                                                                ' activexperts.com    
...

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer")        ' Create a new 
                                                                ' DnsServer instance
Set objConstants = CreateObject( "AxNetwork.NwConstants")

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS 
                                                                ' server ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_ANY                                   ' Lookup any record for 
                                                                ' activexperts.com    
WScript.Echo "Lookup, result: " & objDnsServer.LastError        ' Show result

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all DNS operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all DNS operations will be written to this log file.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer")        ' Create a new DnsServer
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants")

objDnsServer.LogFile = "c:\dns.log"                             ' Set log file    
objDnsServer.Server  = "ns1.interstroom.nl"                          
objDnsServer.Lookup "activexperts.com", objConstants.nwDNS_TYPE_ANY  
... 

5.3. Methods

Methods

Method Description
Clear Reset all properties to their default values
Lookup Lookup DNS record(s)
GetFirstRecord Get first DNS record
GetNextRecord Get next DNS record
IsAuthoritative Set to True if DNS server is authoritative
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval
Activate Activate Software

Clear method

Description:

Resets all properties to the initial, default values.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer")        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants")

objDnsServer.Server      = "ns1.xyz.intra"                      ' Remote DNS server: 
                                                                ' ns1.xyz.intra    
objDnsServer.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_ANY                                   ' Lookup any record for 
                                                                ' activexperts.com    
...
objDnsServer.Clear                                              ' Reset all properties  
objDnsServer.Server      = "ns1.interstroom.nl"                 ' Remote DNS server: 
                                                                ' ns1.xyz.intra    
...

Lookup method

Description:

Lookup DNS record(s).

Parameters:

  • The hostname or IP address of the (remote) DNS server server
  • Type of DNS record(s) to lookup. Click here for a list of valid DNS types. Specify nwDNS_TYPE_ANY to query for any type.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer")        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants")

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS server 
                                                                ' ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_ANY                                   ' Lookup any dns record for 
                                                                ' activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
...

GetFirstRecord method

Description:

Find the first DSN record that was a result of the Lookup query.
Use GetNextRecord to find the next DNS records.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsRecord")        ' Create a new DnsRecord 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants")

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS server 
                                                                ' ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_ANY                                   ' Lookup any dns record for 
                                                                ' activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
While( objDnsServer.LastError = 0 )
    WScript.Echo "Name: " & objDnsRecord.Name
    ...
    Set objDnsRecord = objDnsServer.GetNextRecord               ' Get next DNS record 
WEnd

GetNextRecord method

Description:

Iterate over all DSN records that were a result of the Lookup query.
Always start with GetFirstRecord to find the first DNS record.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsRecord")        ' Create a new DnsRecord 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants")

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS server 
                                                                ' ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_ANY                                   ' Lookup any dns record for 
                                                                ' activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
While( objDnsServer.LastError = 0 )
    WScript.Echo "Name: " & objDnsRecord.Name
    ...
    Set objDnsRecord = objDnsServer.GetNextRecord               ' Get next DNS record 
WEnd

IsAuthoritative method

Description:

Indicates if DNS server is authoritative for the queried domain.

Parameters:

  • True of False.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsRecord")        ' Create a new DnsRecord 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants")

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS server 
                                                                ' ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_ANY                                   ' Lookup any dns record for 
                                                                ' activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
WScript.Echo "IsAuthoritative: " & _ 
  objDnsServer.IsAuthoritative()                                ' Is authoritative ?

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code.

Return value:

The error description that is associated with the given error code.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsRecord" )        ' Create a new DnsRecord 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                            
objDnsServer.Lookup "activexperts.com", objConstants.nwDNS_TYPE_ANY   
WScript.Echo "LastError: " & objDnsServer.LastError
WScript.Echo "Error description: " & objDnsServer.GetErrorDescription( objDnsServer.LastError )
...

Sleep method

Description:

This method can be used in your script anywhere you want; Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to hold.

Return value:

Always 0.

Example:

Set objDnsServer   = CreateObject( "AxNetwork.DnsRecord" )   ' Create DnsRecord object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" ) ' Create constants object
...
objDnsServer.Sleep 500

Activate method

Description:

This method activates the ActiveXperts Networking Component product. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsRecord" )        ' Create DnsRecord object
objDnsServer.Activate "xyz", True                               ' Substitute xyz by your 
                                                                ' own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass 
' False, you need to call 
' Activate each time the product is started.

6. DnsRecord

6.1. Introduction

DNS is the Domain Name System. DNS converts machine names to the IP addresses that all machines on the net have. It translates (i.e. 'maps') from name to address and from address to name, and some other things.

The ActiveXperts Networking Component DNS objects can be used to query servers running a domain name service (DNS) application. It will send domain name query packets to any designated DNS server. There are three data elements required in order to formulate a DNS query using ActiveXperts Networking Component:

  • DNS servername/address
  • Internet style address that is being queried
  • Type of record you are searching for

The ActiveXperts Networking Component DNS objects are useful for gathering address information about hosts in the network. It can be used to query DNS for specific information about hosts, like mail exchanger records [MX], IP address [A], canonical names [CNAME], etc. If you have an IP address, you can get a canonical name back for the address and vice versa. Another useful feature is the ability to get a listing of hosts which serve mail exchange [MX] methods for a specific domain.

The following sample (VBScript) shows how the DnsServer and DnsRecord objects can be used to list all DNS records for a specific domain name:

    
Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )         ' Create object
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server = "ns1.interstroom.nl"                       ' DNS server
       
objDnsServer.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_ANY                                    ' Show all DNS records 
                                                                   for activexperts.com
WScript.Echo "Lookup, result: " & objDnsServer.LastError    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If

If ( objDnsServer.IsAuthoritative = True ) Then
    WScript.Echo "Server is an authority for this domain"
Else
    WScript.Echo "Server is not an authority for this domain"
End If
    
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Iterate over all DNS 
                                                                ' records; get first record   	
While ( objDnsServer.LastError = 0 )
    Select Case objDnsRecord.Type 
      Case objConstants.nwDNS_TYPE_A
        WScript.Echo "Type             : A"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "IPv4 Address     : " & objDnsRecord.Address
      Case objConstants.nwDNS_TYPE_AAAA
        WScript.Echo "Type             : AAAA"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "IPv6 Address     : " & objDnsRecord.Address
      Case objConstants.nwDNS_TYPE_CNAME
        WScript.Echo "Type             : CNAME"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "Alias            : " & objDnsRecord.Address
      Case objConstants.nwDNS_TYPE_MX 
        WScript.Echo "Type             : MX"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "Preference       : " & objDnsRecord.Preference
        WScript.Echo "Mail Exchange    : " & objDnsRecord.MailExchange
      Case objConstants.nwDNS_TYPE_NS
        WScript.Echo "Type             : NS"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "Name Server      : " & objDnsRecord.NameServer
      Case objConstants.nwDNS_TYPE_PTR
        WScript.Echo "Type             : PTR"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "Host             : " & objDnsRecord.Address
      Case objConstants.nwDNS_TYPE_SOA
        WScript.Echo "Type             : SOA"
        WScript.Echo "Name             : " & objDnsRecord.Name
        WScript.Echo "Name Server      : " & objDnsRecord.NameServer
        WScript.Echo "MailBox          : " & objDnsRecord.MailBox
        WScript.Echo "Serial           : " & objDnsRecord.SerialNumber
        WScript.Echo "Refresh          : " & objDnsRecord.RefreshInterval
        WScript.Echo "Retry Interval   : " & objDnsRecord.RetryInterval
        WScript.Echo "Expiration Limit : " & objDnsRecord.ExpirationLimit
        WScript.Echo "Minimum TTL      : " & objDnsRecord.MinimumTTL
    End Select
  
    WScript.Echo "TTL              : " & objDnsRecord.TTL
    WScript.Echo
    
    Set objDnsRecord = objDnsServer.GetNextRecord               ' Iterate over all DNS 
                                                                ' records; get next record
Wend

6.2. Properties

Properties

Property Type Read/Write Description
Name String Out Name of the record
Type Number Out Type of DNS record
Address String Out IP address (or name of A record in case of CNAME)
TTL Number Out Used as the default TTL for new records created within the zone
MailExchange String Out The email address (replace @ with a dot) of the person responsible for maintenance of the zone
Preference String Out MX preference
NameServer String Out The domain name of the primary DNS server for the zone
MailBox String Out The email address (replace @ with a dot) of the person responsible for maintenance of the zone
SerialNumber String Out Used by secondary DNS servers to check if the zone has changed
RefreshInterval Number Out How often secondary DNS servers should check if changes are made to the zone
RetryInterval Number Out How often secondary DNS server should retry checking if changes are made - if the first refresh fails
ExpirationLimit Number Out How long the zone will be valid after a refresh
MinimumTTL Number Out Used as the default TTL for new records created within the zone

Name property

Type:

String

Description:

Name of the record.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS 
                                                                ' server ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _ 
  objConstants.nwDNS_TYPE_ANY                                   ' Lookup any dns record 
                                                                ' for activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
If( objDnsServer.LastError = 0 ) Then
    WScript.Echo "Name: " & objDnsRecord.Name
    WScript.Echo "Type: " & objDnsRecord.Type
    WScript.Echo "Address: " & objDnsRecord.Address
End If

Type property

Type:

Number

Description:

Type of DNS record. Click here for a list of valid DNS types.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS server 
                                                                ' ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_ANY                                   ' Lookup any dns record for 
                                                                ' activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
If( objDnsServer.LastError = 0 ) Then
    WScript.Echo "Name: " & objDnsRecord.Name
    WScript.Echo "Type: " & objDnsRecord.Type
    WScript.Echo "Address: " & objDnsRecord.Address
End If

Address property

Type:

String

Description:

IP Address, or name of A record (in case of a CNAME).

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS 
                                                                ' server ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _ 
  objConstants.nwDNS_TYPE_ANY                                   ' Lookup any dns record 
                                                                ' for activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
If( objDnsServer.LastError = 0 ) Then
    WScript.Echo "Name: " & objDnsRecord.Name
    WScript.Echo "Type: " & objDnsRecord.Type
    WScript.Echo "Address: " & objDnsRecord.Address
End If

TTL property

Type:

Number

Description:

Used as the default TTL for new records created within the zone.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS 
                                                                ' server ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _ 
  objConstants.nwDNS_TYPE_ANY                                   ' Lookup any dns record 
                                                                ' for activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
If( objDnsServer.LastError = 0 ) Then
    WScript.Echo "Name: " & objDnsRecord.Name
    WScript.Echo "TTL: " & objDnsRecord.TTL
End If

MailExchange property

Type:

String

Description:

The A Record for the mail server to connect to its IP-address. The 'MailExchange' property is only set for MX records.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS 
                                                                ' server ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _ 
  objConstants.nwDNS_TYPE_MX                                    ' Lookup MX records for 
                                                                ' activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
If( objDnsServer.LastError = 0 ) Then
    WScript.Echo "Name: " & objDnsRecord.Name
    WScript.Echo "MailExchange: " & objDnsRecord.MailExchange
    WScript.Echo "Preference: " & objDnsRecord.Preference
End If

Preference property

Type:

Number

Description:

MX preference. An MX-record has a "Preference" number indicating the order in which the mail server should be used. (Only relevant when multiple MX-records are defined for the same domain name). Mail servers will attempt to deliver mail to the server with the lowest preference number first, and if unsuccessful continue with the next lowest and so on.
The 'Preference' property is only set for MX records.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS 
                                                                ' server ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _ 
  objConstants.nwDNS_TYPE_MX                                    ' Lookup MX records for 
                                                                ' activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
If( objDnsServer.LastError = 0 ) Then
    WScript.Echo "Name: " & objDnsRecord.Name
    WScript.Echo "MailExchange: " & objDnsRecord.MailExchange
    WScript.Echo "Preference: " & objDnsRecord.Preference
End If

NameServer property

Type:

String

Description:

The domain name of the primary DNS server for the zone. Only applies to SOA (Start of Authority) records.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS 
                                                                ' server ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _ 
  objConstants.nwDNS_TYPE_SOA                                   ' Lookup SOA record 
                                                                ' for activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
If( objDnsServer.LastError = 0 ) Then                                
    WScript.Echo "Name: " & objDnsRecord.Name                   ' Display all SOA record 
                                                                ' fields 
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "MailBox: " & objDnsRecord.MailBox
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "SerialNumber: " & objDnsRecord.SerialNumber
    WScript.Echo "RefreshInterval: " & objDnsRecord.RefreshInterval
    WScript.Echo "RetryInterval: " & objDnsRecord.RetryInterval
    WScript.Echo "ExpirationLimit: " & objDnsRecord.ExpirationLimit
    WScript.Echo "MinimumTTL: " & objDnsRecord.MinimumTTL
End If

MailBox property

Type:

String

Description:

The email address (replace @ with a dot) of the person responsible for maintenance of the zone. The standard for this is the "hostmaster" username - such as "hostmaster.activexperts.com" (= hostmaster@activexperts.com). Only applies to SOA (Start of Authority) records.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS server 
                                                                ' ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", ? 
  objConstants.nwDNS_TYPE_SOA                                   ' Lookup SOA record 
                                                                ' for activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
If( objDnsServer.LastError = 0 ) Then                                
    WScript.Echo "Name: " & objDnsRecord.Name                   ' Display all SOA 
                                                                ' record fields 
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "MailBox: " & objDnsRecord.MailBox
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "SerialNumber: " & objDnsRecord.SerialNumber
    WScript.Echo "RefreshInterval: " & objDnsRecord.RefreshInterval
    WScript.Echo "RetryInterval: " & objDnsRecord.RetryInterval
    WScript.Echo "ExpirationLimit: " & objDnsRecord.ExpirationLimit
    WScript.Echo "MinimumTTL: " & objDnsRecord.MinimumTTL
End If

SerialNumber property

Type:

String

Description:

Used by secondary DNS servers to check if the zone has changed. If the serial number is higher than what the secondary server has, a zone transfer will be initiated. Only applies to SOA (Start of Authority) records.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new 
                                                                ' DnsServer instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS 
                                                                ' server ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_SOA                                   ' Lookup SOA record 
                                                                ' for activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
If( objDnsServer.LastError = 0 ) Then                                
    WScript.Echo "Name: " & objDnsRecord.Name                   ' Display all SOA record 
                                                                ' fields 
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "MailBox: " & objDnsRecord.MailBox
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "SerialNumber: " & objDnsRecord.SerialNumber
    WScript.Echo "RefreshInterval: " & objDnsRecord.RefreshInterval
    WScript.Echo "RetryInterval: " & objDnsRecord.RetryInterval
    WScript.Echo "ExpirationLimit: " & objDnsRecord.ExpirationLimit
    WScript.Echo "MinimumTTL: " & objDnsRecord.MinimumTTL
End If

RefreshInterval property

Type:

Number

Description:

How often secondary DNS servers should check if changes are made to the zone. Only applies to SOA (Start of Authority) records.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new 
                                                                ' DnsServer instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS 
                                                                ' server ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_SOA                                   ' Lookup SOA record 
                                                                ' for activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
If( objDnsServer.LastError = 0 ) Then                                
    WScript.Echo "Name: " & objDnsRecord.Name                   ' Display all SOA record 
                                                                ' fields 
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "MailBox: " & objDnsRecord.MailBox
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "SerialNumber: " & objDnsRecord.SerialNumber
    WScript.Echo "RefreshInterval: " & objDnsRecord.RefreshInterval
    WScript.Echo "RetryInterval: " & objDnsRecord.RetryInterval
    WScript.Echo "ExpirationLimit: " & objDnsRecord.ExpirationLimit
    WScript.Echo "MinimumTTL: " & objDnsRecord.MinimumTTL
End If

RetryInterval property

Type:

Number

Description:

How often secondary DNS server should retry checking if changes are made - if the first refresh fails. Only applies to SOA (Start of Authority) records.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS 
                                                                ' server ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _ 
  objConstants.nwDNS_TYPE_SOA                                   ' Lookup SOA record for 
                                                                ' activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
If( objDnsServer.LastError = 0 ) Then                                
    WScript.Echo "Name: " & objDnsRecord.Name                   ' Display all SOA record 
                                                                ' fields 
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "MailBox: " & objDnsRecord.MailBox
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "SerialNumber: " & objDnsRecord.SerialNumber
    WScript.Echo "RefreshInterval: " & objDnsRecord.RefreshInterval
    WScript.Echo "RetryInterval: " & objDnsRecord.RetryInterval
    WScript.Echo "ExpirationLimit: " & objDnsRecord.ExpirationLimit
    WScript.Echo "MinimumTTL: " & objDnsRecord.MinimumTTL
End If

ExpirationLimit property

Type:

Number

Description:

How long the zone will be valid after a refresh. Secondary servers will discard the zone if no refresh could be made within this interval. Only applies to SOA (Start of Authority) records.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS 
                                                                ' server ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _ 
  objConstants.nwDNS_TYPE_SOA                                   ' Lookup SOA record for 
                                                                ' activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
If( objDnsServer.LastError = 0 ) Then                                
    WScript.Echo "Name: " & objDnsRecord.Name                   ' Display all SOA record 
                                                                ' fields 
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "MailBox: " & objDnsRecord.MailBox
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "SerialNumber: " & objDnsRecord.SerialNumber
    WScript.Echo "RefreshInterval: " & objDnsRecord.RefreshInterval
    WScript.Echo "RetryInterval: " & objDnsRecord.RetryInterval
    WScript.Echo "ExpirationLimit: " & objDnsRecord.ExpirationLimit
    WScript.Echo "MinimumTTL: " & objDnsRecord.MinimumTTL
End If

MinimumTTL property

Type:

Number

Description:

Minimum (default) TTL. Only applies to SOA (Start of Authority) records.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS 
                                                                ' server ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_SOA                                   ' Lookup SOA record for 
                                                                ' activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
If( objDnsServer.LastError = 0 ) Then                                
    WScript.Echo "Name: " & objDnsRecord.Name                   ' Display all SOA record 
                                                                ' fields 
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "MailBox: " & objDnsRecord.MailBox
    WScript.Echo "NameServer: " & objDnsRecord.NameServer
    WScript.Echo "SerialNumber: " & objDnsRecord.SerialNumber
    WScript.Echo "RefreshInterval: " & objDnsRecord.RefreshInterval
    WScript.Echo "RetryInterval: " & objDnsRecord.RetryInterval
    WScript.Echo "ExpirationLimit: " & objDnsRecord.ExpirationLimit
    WScript.Echo "MinimumTTL: " & objDnsRecord.MinimumTTL
End If

6.3. Methods

Methods

Method Description
Clear Reset all properties to their default values
GetErrorDescription Get the description of the given error

Clear method

Description:

Resets all properties to the initial, default values.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                     ' Apply queries to DNS server 
                                                                ' ns1.interstroom.nl    
objDnsServer.Lookup "activexperts.com", _ 
  objConstants.nwDNS_TYPE_ANY                                   ' Lookup any record for 
                                                                ' activexperts.com    
If( objDnsServer.LastError <> 0 ) Then
    WScript.Quit
End If
Set objDnsRecord = objDnsServer.GetFirstRecord                  ' Get first DNS record 
While( objDnsServer.LastError = 0 ) Then                                
    WScript.Echo "Name: " & objDnsRecord.Name                       
    objDnsRecord.Clear()                                        ' Clear DNS record 
    Set objDnsRecord = objDnsServer.GetNextRecord               ' Get next DNS record 
WEnd

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code.

Return value:

The error description that is associated with the given error code.

Example:

Set objDnsServer = CreateObject( "AxNetwork.DnsServer" )        ' Create a new DnsServer 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objDnsServer.Server  = "ns1.interstroom.nl"                            
objDnsServer.Lookup "activexperts.com", objConstants.nwDNS_TYPE_ANY   
WScript.Echo "LastError: " & objDnsServer.LastError
WScript.Echo "Error description: " & objDnsServer.GetErrorDescription( objDnsServer.LastError )
...

7. FtpServer

7.1. Introduction

FTP stands for File Transfer Protocol: a communication standard which allows computers to transfer files back and forth in spite of differences in how different operating systems handle file names, directories and file formats.

The local (client) computer is the one you're directly connected to, and the remote (server) computer is the one that you want to get files from or put files to. You need to specify the Internet address of the remote computer, e.g. ftp.activexperts-labs.com.

Some sites maintain archives of files for public use, permitting access using the username anonymous. Usually you are asked to enter your real e-mail address as the password. If a site is not using anonymous FTP, you must provide the username and password which has been assigned to you for that computer.

FTP programmes have different methods of handling plain-text files and binary files. The plain-text mode attempts to correct for the different ways that different operating systems handle line breaks in text files, while the binary mode ensures that all of the special non-printing bytes are transferred without change. HTML files are plain-text files, while word-processing documents and images are binary files.

The following sample (VBScript) shows how the FtpServer and FtpFile objects can be used to list files in a specific directory on an FTP server:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )

objFtpServer.Connect "ftp.activexperts-labs.com","anonymous","" ' Connect to the FTP server 
                                                                ' using the anonymous account 
Wscript.Echo "Connect, result: " & objFtpServer.LastError
If( objFtpServer.LastError <> 0 ) Then                          ' If connect failed then quit
   WScript.Quit
End If

objFtpServer.ChangeDir "samples/network-component/Visual Basic/Telnet"    ' Change directory
Wscript.Echo "ChangeDir, result: " & _
 objFtpServer.LastError
If( objFtpServer.LastError <> 0 ) Then                          ' If ChangeDir fails then 
                                                                ' disconnect and quit
   objFtpServer.Disconnect
   WScript.Quit
End If

Set objFtpFile = objFtpServer.FindFirstFile()                   ' Iterate over all files in dir 
                                                                ' Start with first file
While( objFtpServer.LastError = 0 )
   WScript.Echo "Name: " & objFtpFile.Name                      ' Display file name
   WScript.Echo "IsDirectory: " & objFtpFile.IsDirectory        ' Display directory or file
   WScript.Echo "Size: " & objFtpFile.Size                      ' Display file size
   WScript.Echo "Date: " & objFtpFile.Date                      ' Display file date
    
   ' To save the file, call the GetFile method. 
   ' strSaveAs = "C:\temp\" & objFtpFile.Name
   ' objFtpServer.GetFile objFtpFile.Name, strSaveAs
   ' Wscript.Echo "Save file, result: " & objFtpServer.LastError

   ' To delete a file, call the DeleteFile method. 
   ' objFtpServer.DeleteFile objFtpFile.Name
   ' Wscript.Echo "Delete, result: " & objFtpServer.LastError

   Set objFtpFile = objFtpServer.FindNextFile()                 ' Next file
Wend

objFtpServer.Disconnect                                         ' Disconnect

7.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
HostPort Number In/Out TCP port of the remote FTP server. Default: 21
PassiveMode Boolean In/Out Specifies how to connect: passive (default) or active
BinaryTransfer Boolean In/Out Specifies how to transfer files: binary (default) or ASCII
LastError Number Out Result of the last called method
LastResponse String Out Last response from FTP server
LogFile String In/Out Log file for troubleshooting purposes

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objFtpServer = CreateObject("AxNetwork.FtpServer")          ' Create a new FtpServer 
                                                                ' instance
WScript.Echo  "Version: " & objFtpServer.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' object
WScript.Echo  "Build: " & objFtpServer.Build

Module property

Return the module name of the Component.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create new instance 
WScript.Echo  "Module: " & objFtpServer.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create instance
WScript.Echo "LicenseStatus: " & objFtpServer.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objFtpServer = CreateObject("AxNetwork.FtpServer")          ' Create new instance
WScript.Echo "LicenseKey: " & objFtpServer.LicenseKey

HostPort property

Type:

Number

Description:

TCP port number to identify a (remote) FTP server. If you don't specify the 'HostPort' property, port 21 (default FTP port) is used.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
...
objFtpServer.HostPort = 8021                                    ' Use port 8021 instead 
                                                                ' of default port 21
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host 
                                                                ' ftpserver1 on port 8021
...

PassiveMode property

Type:

Boolean

Description:

Specifies the way to connect to the remote FTP server: in Passive mode or in Active mode. Default value: True (Passive)

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
...
objFtpServer.PassiveMode = False                                ' Use Active mode instead 
                                                                ' of the default Passive mode
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1 
                                                                ' in Active mode
...

BinaryTransfer property

Type:

Boolean

Description:

Specifies the way files are transfered when downloading (GetFile) or uploading (PutFile) files. Default value: True, indicating that files are tranferred in binary mode by default.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
...
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
...
objFtpServer.BinaryMode = False                                 ' Files transfer in ASCII mode 
                                                                ' when using GetFile/PutFile
Set objFtpFile = objFtpServer.GetFile( "c:\temp\log1.txt", _
  "/logfiles/log1.txt" )                                        ' Download log1.txt in ASCII 
                                                                ' mode

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
...
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
WScript.Echo "LastError: " & objFtpServer.LastError
...

LastResponse property

Type:

String

Description:

The last response of an FTP operation is stored in the 'LastResponse' property. It can be used for troubleshooting purposes.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
...
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
WScript.Echo "LastResponse: " & objFtpServer.LastResponse       ' Display the last response 
                                                                ' from the FTP server
...

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all FTP operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all FTP operations will be written to this log file.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
objFtpServer.LogFile = "C:\Ftp.log"                             ' Write all FTP operations 
                                                                ' to the specified log file
...
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
...

7.3. Methods

Methods

Method Description
Clear Reset all properties to their default values
Connect Connect to a remote FTP server
Disconnect Close the connection
GetCurrentDir Retrieve the current directory
ChangeDir Change directory
CreateDir Create directory
RenameDir Rename directory
DeleteDir Delete directory
FindFile Find a file in the current directory
FindFirstFile Find first file in the current directory
FindNextFile Find next file in the current directory
RenameFile Rename a file in the current directory
DeleteFile Delete a file in the current directory
GetFile Download (get) a file from the current directory
PutFile Upload (put) a file to the current directory
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval
Activate Suspends the execution of the object for at least the specified interval

Clear method

Description:

Resets all properties to the initial, default values.

Parameters:

  • None

Return value:

Always 0.

Example:

' Create a new FtpServer instance
Set objFtpServer = CreateObject( "AxNetwork.FtpServer" ) 
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
...
objFtpServer.Disconnect                                         ' Disconnect
objFtpServer.Clear                                              ' Clear properties before 
                                                                ' connecting to another FTP 
                                                                ' server
objFtpServer.Connect "ftpserver2", "account", "pwd"             ' Connect to host ftpserver2

Connect method

Description:

Call this method to connect to a remote FTP server. By default, a Passive connection will be established. If you want to establish a connection in Active mode, you should set the PassiveMode flag to False.

Parameters:

  • The hostname or IP address of the remote server
  • The FTP account; use 'anonymous' for anonymous login
  • The FTP password; use an e-mail address for anonymous login

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
If( objFtpServer.LastError = 0 ) Then
   ...
   objFtpServer.ChangeDir( "/pictures" )
   ...
   objFtpServer.Disconnect
End If

Disconnect method

Description:

Call this method to close a connnection that was established using the Connect method.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
If( objFtpServer.LastError = 0 ) Then
   ...
   objFtpServer.Disconnect                                      ' Close the session
End If

GetCurrentDir method

Description:

The directory string. If the method fails, an empty string is returned and the LastError property is set to a non-zero value indicating the reason for failing.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )         ' Create a new FtpServer 
                                                                 ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"              ' Connect to host ftpserver1
If( objFtpServer.LastError = 0 ) Then
   ...
   strCurrentDir = objFtpServer.GetCurrentDir()                  ' Retrieve current directory
   If( objFtpServer.LastError = 0 ) Then
      WScript.Echo "Current Directory: " & strCurrentDir
   End If
   objFtpServer.Disconnect                                       ' Close the session
End If

ChangeDir method

Description:

Change the current directory on the remote FTP server. You can use a fully qualified directory name, or a plain directory name.

Parameters:

  • Directory name

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
If( objFtpServer.LastError = 0 ) Then
   ...
   objFtpServer.ChangeDir( "/pictures" )                        ' Change directory to: 
                                                                ' /pictures
   objFtpServer.ChangeDir( "family" )                           ' Change directory to: 
                                                                ' /pictures/family
   ...
   objFtpServer.ChangeDir( "/pictures/friends" )                ' Change directory to: 
                                                                ' /pictures/friends
   ...
   objFtpServer.Disconnect                                      ' Close the session
End If

CreateDir method

Description:

Create a new directory on the remote FTP server in the directory indicated by GetCurrentDir.

Parameters:

  • The directory to create. You can use a fully qualified directory name, or a plain directory name.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
If( objFtpServer.LastError = 0 ) Then
   ...
   objFtpServer.ChangeDir( "/pictures" )                        ' Change directory to: 
                                                                ' /pictures
   objFtpServer.CreateDir( "family" )                           ' Create new directory 
                                                                ' 'family'
   ...
   objFtpServer.Disconnect                                      ' Close the session
End If

RenameDir method

Description:

Rename directory.

Parameters:

  • Name of the directory to rename
  • New name of the directory

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
If( objFtpServer.LastError = 0 ) Then
   ...
   objFtpServer.RenameDir( "pictures", "images" )               ' Rename directory 'pictures' 
                                                                ' into 'images'
   ...
   objFtpServer.Disconnect                                      ' Close the session
End If

DeleteDir method

Description:

Delete a directory.

Parameters:

  • The directory to delete. You can use a fully qualified directory name, or a plain directory name. Make sure that this directory is empty.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
If( objFtpServer.LastError = 0 ) Then
   ...
   objFtpServer.ChangeDir( "/pictures" )                        ' Change directory to: 
                                                                ' /pictures
   objFtpServer.DeleteDir( "family" )                           ' Delete directory 'family'
   ...
   objFtpServer.Disconnect                                      ' Close the session
End If

FindFile method

Description:

Find a file. You can use a plain filename (the file will then be retrieved from the current directory) or you can use a fully qualified filename.

Parameters:

  • Filename

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )         ' Create a new FtpServer 
                                                                 ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"              ' Connect to host ftpserver1
If( objFtpServer.LastError = 0 ) Then
   Set objFtpFile1 = objFtpServer.FindFile( _
     "/pictures/picture1.jpg")                                   ' Find file using a fully 
                                                                 ' qualified filename
   ...
   objFtpServer.ChangeDir( "/pictures" )
   Set objFtpFile2 = objFtpServer.FindFile( "picture2.jpg")      ' Find file using a plain 
                                                                 ' filename
   objFtpServer.Disconnect                                       ' Close the session
End If

FindFirstFile method

Description:

Iterate of all files and directories in the current directory. The 'FindFirstFile' method retrieves the first file/directory. You can call 'FindNextFile' until there are no more files/directories.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
If( objFtpServer.LastError = 0 ) Then
   Set objFtpFile = objFtpServer.FindFirstFile()
   While( objFtpServer.LastError = 0 )
       WScript.Echo "File: " & objFtpFile.Name                  ' Display filename 
                                                                ' (or directoryname)
       Set objFtpFile = objFtpServer.FindNextFile()
   WEnd
   objFtpServer.Disconnect                                      ' Close the session
End If

FindNextFile method

Description:

Iterate of all files and directories in the current directory. The 'FindFirstFile' method retrieves the first file/directory. You can call 'FindNextFile' until there are no more files/directories.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
If( objFtpServer.LastError = 0 ) Then
   Set objFtpFile = objFtpServer.FindFirstFile()
   While( objFtpServer.LastError = 0 )
       WScript.Echo "File: " & objFtpFile.Name                  ' Display filename (or 
                                                                ' directoryname)
       Set objFtpFile = objFtpServer.FindNextFile()
   WEnd
   objFtpServer.Disconnect                                      ' Close the session
End If

RenameFile method

Description:

Rename file.

Parameters:

  • Name of the file to rename
  • New name of the file

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
If( objFtpServer.LastError = 0 ) Then
   ...
   objFtpServer.ChangeDir( "/pictures" )                        ' Change directory to: 
                                                                ' /pictures
   objFtpServer.Rename( "old.jpg", "new.jpg" )                  ' Rename 'old.jpg' into
                                                                ' 'new.jpg'
   ...
   objFtpServer.Disconnect                                      ' Close the session
End If

DeleteFile method

Description:

Delete file.

Parameters:

  • Name of the file to delete

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host 
                                                                ' ftpserver1
If( objFtpServer.LastError = 0 ) Then
   ...
   objFtpServer.ChangeDir( "/pictures" )                        ' Change directory to: 
                                                                ' /pictures
   objFtpServer.Delete( "picture1.jpg" )                        ' Delete 'picture1.jpg'
   ...
   objFtpServer.Disconnect                                      ' Close the session
End If

GetFile method

Description:

Download a file from the FTP server.

Parameters:

  • Name of the file on the remote machine. This can be a fully qualified filename, or a plain filename. When using a plain filename, make sure you have changed the directory using ChangeDir.
  • Name of the file on the local machine. This can be a fully qualified filename, or a plain filename. When using a plain filename, the file will be stored in the current Windows directory.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
If( objFtpServer.LastError = 0 ) Then
   ...
   objFtpServer.ChangeDir( "/pictures" )                        ' Change directory to: 
                                                                ' /pictures
   objFtpServer.GetFile( "picture1.jpg", _
     "c:\pictures\file1.jpg" )                                  ' Download 'picture1.jpg'
   ...
   objFtpServer.ChangeDir( "/" )                               ' Change directory to: /
   objFtpServer.GetFile( "/pictures/picture1.jpg", _
     "c:\pictures\file1.jpg" )                                 ' Download 'picture2.jpg'
   objFtpServer.Disconnect                                     ' Close the session
End If

PutFile method

Description:

Upload a file to the FTP server.

Parameters:

  • Name of the file on the local machine. This can be a fully qualified filename, or a plain filename. When using a plain filename, the file will be uploaded from the current Windows directory
  • Name of the file on the remote machine. This can be a fully qualified filename, or a plain filename. When using a plain filename, make sure you have changed the directory using ChangeDir.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host ftpserver1
If( objFtpServer.LastError = 0 ) Then
   ...
   objFtpServer.ChangeDir( "/pictures" )                        ' Change directory to: 
                                                                ' /pictures
   objFtpServer.PutFile( "c:\pictures\picture3.jpg", _
     "/pictures/picture3.jpg" )                                 ' Upload 'picture3.jpg'
   ...
   objFtpServer.PutFile( "c:\pictures\picture4.jpg", _
     "/pictures/picture4.jpg" )                                 ' Upload 'picture4.jpg'
End If

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code.

Return value:

The error description that is associated with the given error code.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
...
objFtpServer.Connect "ftpserver1", "account", "pwd"             ' Connect to host 
                                                                ' ftpserver1
WScript.Echo "LastError: " & objFtpServer.LastError
WScript.Echo "Error description: " & objFtpServer.GetErrorDescription( objFtpServer.LastError )
...

Sleep method

Description:

This method can be used in your script anywhere you want; Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to hold.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer   = CreateObject( "AxNetwork.FtpServer" )   ' Create Ftperver object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" ) ' Create constants object
...
objFtpServer.Sleep 50

Activate method

Description:

This method activates the ActiveXperts Networking Component. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create FtpServer object
objFtpServer.Activate "xyz", True                               ' Substitute xyz by your 
                                                                ' own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call Activate each time the product is 
' started.

8. FtpFile

8.1. Introduction

FTP stands for File Transfer Protocol: a communication standard which allows computers to transfer files back and forth in spite of differences in how different operating systems handle file names, directories and file formats.

The local (client) computer is the one you're directly connected to, and the remote (server) computer is the one that you want to get files from or put files to. You need to specify the Internet address of the remote computer, e.g. ftp.activexperts-labs.com.

Some sites maintain archives of files for public use, permitting access using the username anonymous. Usually you are asked to enter your real e-mail address as the password. If a site is not using anonymous FTP, you must provide the username and password which has been assigned to you for that computer.

FTP programmes have different methods of handling plain-text files and binary files. The plain-text mode attempts to correct for the different ways that different operating systems handle line breaks in text files, while the binary mode ensures that all of the special non-printing bytes are transferred without change. HTML files are plain-text files, while word-processing documents and images are binary files.

The following sample (VBScript) shows how the FtpServer and FtpFile objects can be used to list files in a specific directory on an FTP server:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )

objFtpServer.Connect "ftp.activexperts-labs.com","anonymous","" ' Connect to the FTP server 
                                                                ' using the anonymous account 
Wscript.Echo "Connect, result: " & objFtpServer.LastError
If( objFtpServer.LastError <> 0 ) Then                          ' If connect failed then quit
   WScript.Quit
End If

objFtpServer.ChangeDir "samples/network-component/Visual Basic/Telnet"    ' Change directory
Wscript.Echo "ChangeDir, result: " & _
 objFtpServer.LastError
If( objFtpServer.LastError <> 0 ) Then                          ' If ChangeDir fails then 
                                                                ' disconnect and quit
   objFtpServer.Disconnect
   WScript.Quit
End If

Set objFtpFile = objFtpServer.FindFirstFile()                   ' Iterate over all files in dir 
                                                                ' Start with first file
While( objFtpServer.LastError = 0 )
   WScript.Echo "Name: " & objFtpFile.Name                      ' Display file name
   WScript.Echo "IsDirectory: " & objFtpFile.IsDirectory        ' Display directory or file
   WScript.Echo "Size: " & objFtpFile.Size                      ' Display file size
   WScript.Echo "Date: " & objFtpFile.Date                      ' Display file date
    
   ' To save the file, call the GetFile method. 
   ' strSaveAs = "C:\temp\" & objFtpFile.Name
   ' objFtpServer.GetFile objFtpFile.Name, strSaveAs
   ' Wscript.Echo "Save file, result: " & objFtpServer.LastError

   ' To delete a file, call the DeleteFile method. 
   ' objFtpServer.DeleteFile objFtpFile.Name
   ' Wscript.Echo "Delete, result: " & objFtpServer.LastError

   Set objFtpFile = objFtpServer.FindNextFile()                 ' Next file
Wend

objFtpServer.Disconnect                                         ' Disconnect

8.2. Properties

Properties

Property Type Read/Write Description
Name String Out Filename
IsDirectory Boolean Out Is the file a directory (True) or a file (False)
Size Number Out Size of file (in bytes)
DateSeconds Number Out Last modification date of the file (in seconds after 1/1/1970)
Date String Out Last modification date of the file (as a friendly string)

Name property

Type:

String

Description:

File name.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
...
objFtpServer.Connect( "ftp01", "myaccount", "mypassword" )      ' Connect to the FTP server    
...
Set objFtpFile = objFtpServer.FindFirstFile()                   ' Get first file in the 
                                                                ' directory
If( objFtpServer.LastError = 0 ) Then                           
   WScript.Echo "Name   : " & objFtpFile.Name                   ' Display name of the file
   WScript.Echo "IsDirectory  : " & objFtpFile.IsDirectory      
   WScript.Echo "Size (in bytes) : " & objFtpFile.Size         
   WScript.Echo "DateSeconds : " & objFtpFile.DateSeconds      
   WScript.Echo "Date : " & objFtpFile.Date                     
End If
...
objFtpServer.Disconnect                                         ' Disconnect

IsDirectory property

Type:

Boolean

Description:

True indicates a directory, False indicates a file.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
...
objFtpServer.Connect( "ftp01", "myaccount", "mypassword" )      ' Connect to the FTP server    
...
Set objFtpFile = objFtpServer.FindFirstFile()                   ' Get first file in the 
                                                                ' directory
If( objFtpServer.LastError = 0 ) Then                           
   WScript.Echo "Name   : " & objFtpFile.Name                   
   WScript.Echo "IsDirectory  : " & objFtpFile.IsDirectory      ' Display: Directory or File
   WScript.Echo "Size (in bytes) : " & objFtpFile.Size          
   WScript.Echo "DateSeconds : " & objFtpFile.DateSeconds       
   WScript.Echo "Date : " & objFtpFile.Date                     
End If
...
objFtpServer.Disconnect                                         ' Disconnect

Size property

Type:

Number

Description:

Size (in bytes) of the file.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
...
objFtpServer.Connect( "ftp01", "myaccount", "mypassword" )      ' Connect to the FTP server    
...
Set objFtpFile = objFtpServer.FindFirstFile()                   ' Get first file in the 
                                                                ' directory
If( objFtpServer.LastError = 0 ) Then                           
   WScript.Echo "Name   : " & objFtpFile.Name                   
   WScript.Echo "IsDirectory  : " & objFtpFile.IsDirectory     
   WScript.Echo "Size (in bytes) : " & objFtpFile.Size          ' Display size in bytes
   WScript.Echo "DateSeconds : " & objFtpFile.DateSeconds       
   WScript.Echo "Date : " & objFtpFile.Date                    
End If
...
objFtpServer.Disconnect                                         ' Disconnect

DateSeconds property

Type:

Number

Description:

Last modification date and time of the file, in seconds after 1/1/1970.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
...
objFtpServer.Connect( "ftp01", "myaccount", "mypassword" )      ' Connect to the FTP server    
...
Set objFtpFile = objFtpServer.FindFirstFile()                   ' Get first file in the 
                                                                ' directory
If( objFtpServer.LastError = 0 ) Then                           
   WScript.Echo "Name   : " & objFtpFile.Name                   
   WScript.Echo "IsDirectory  : " & objFtpFile.IsDirectory      
   WScript.Echo "Size (in bytes) : " & objFtpFile.Size         
   WScript.Echo "DateSeconds : " & objFtpFile.DateSeconds       ' Display last modification 
                                                                ' date/time in seconds after 
                                                                ' 1/1/1970
   WScript.Echo "Date : " & objFtpFile.Date                     
End If
...
objFtpServer.Disconnect                                         ' Disconnect

Date property

Type:

String

Description:

Last modification and time of the file, as a friendly string.

Example:

Set objFtpServer = CreateObject( "AxNetwork.FtpServer" )        ' Create a new FtpServer 
                                                                ' instance
...
objFtpServer.Connect( "ftp01", "myaccount", "mypassword" )      ' Connect to the FTP server    
...
Set objFtpFile = objFtpServer.FindFirstFile()                   ' Get first file in the 
                                                                ' directory
If( objFtpServer.LastError = 0 ) Then                           
   WScript.Echo "Name   : " & objFtpFile.Name                  
   WScript.Echo "IsDirectory  : " & objFtpFile.IsDirectory      
   WScript.Echo "Size (in bytes) : " & objFtpFile.Size    
   WScript.Echo "DateSeconds : " & objFtpFile.DateSeconds     
   WScript.Echo "Date : " & objFtpFile.Date                     ' Display modification 
                                                                ' date/time as a friendly string
End If
...
objFtpServer.Disconnect                                         ' Disconnect

9. HttpEx

9.1. Introduction

The HttpEx object provides a very simple interface to commonly used HTTP methods. This object uses connection pooling to speed up multiple calls to the same webserver. This will enhance performance for applications which need to get an entire web page including images, stylesheets, scriptfiles etc..

The method calls used in this object are analogous to the verbs that are used in the HTTP protocol. For instance, the http GET verb, which is the default way for a browser to query a web page, is translated to the 'Get' method.

In addition this object supports the use of proxy servers and web authentication. If also supports SSL and TLS encryption methods.

Here is a small example (in VBScript) to show how to use the HttpEx object:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")                ' Create HttpEx object
WScript.Echo objHttpEx.Get( "www.activexperts.com/products" )   ' Echo the contents of 
                                                                ' the products page  
If( objHttpEx.LastError <> 0 ) Then
   WScript.Echo "Error " & objHttpEx.LastError                  ' Failed to get the web page, 
                                                                ' print the error
End If
WScript.Echo "Ready."

9.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
LastError Number Out Result of the last called method
LastResponseCode Number Out Last HTTP response code
RequestTimeout Number In/Out Timeout value for HttpEx requests
ConnectionExpireTimeout Number In/Out Timeout value for connections to expire and be elegible for removal from the connection pool
ConnectionPoolSize Number In/Out The number of active connection that can be kept in the connection pool at one time
UserAgent String In/Out The user agent string that will be provided when making requests or posts
FollowRedirect Boolean In/Out Whether or not redirect a HTTP redirect will be automatically followed
MaxRedirectionDepth Number In/Out The maximum number of redirections to follow on a single request
ProxyServer String In/Out Use a proxy server
ProxyAccount String In/Out Use this account for proxy authentication
ProxyPassword String In/Out Use this password for proxy authentication
WebAccount String In/Out Use this account to authenticate at the web site
WebPassword String In/Out Use this password to authenticate at the web site
LogFile String In/Out Log file; use it for troubleshooting purposes

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
WScript.Echo  "Version: " & objHttpEx.Version

Build property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objHttpEx = CreateObject( "AxNetwork.HttpEx" )           ' Create HttpEx object
WScript.Echo  "Build: " & objHttpEx.Build

Module property

Return the module name of the Component.

Example:

Set objHttpEx = CreateObject( "AxNetwork.HttpEx" )        ' Create new instance 
WScript.Echo  "Module: " & objHttpEx.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objHttpEx = CreateObject( "AxNetwork.HttpEx" )        ' Create instance
WScript.Echo "LicenseStatus: " & objHttpEx.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")          ' Create new instance
WScript.Echo "LicenseKey: " & objHttpEx.LicenseKey

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
...
objHttpEx.Get "www.activexperts.com"
WScript.Echo "LastError: " & objHttpEx.LastError

LastResponseCode property

Type:

Number

Description:

The last received HTTP response code. Use this to check the HTTP response after a Get, Post or Head method call. When a HTTP call succeeded the response code should be 200 (Ok). More information about HTTP response codes can be found here.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
...
objHttpEx.Get "www.activexperts.com"
WScript.Echo "LastError: " & objHttpEx.LastError
Wscript.Echo "HTTP Response: " & objHttpEx.LastResponseCode

RequestTimeout property

Type:

Number

Description:

For large webpages, or pages that need to do some processing, you can use this property to increase the timeout. By default the HttpEx request timeout is set to 10 seconds. The value is specified in milliseconds.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
objHttpEx.RequestTimeout = 20000
...
objHttpEx.Get "www.activexperts.com/network-component/postdemo/default.asp?parameter=200"

ConnectionExpireTimeout property

Type:

Number

Description:

Timeout value for connections to expire and be elegible for removal from the connection pool. By default the ConnectionExireTimeout is set to 30 seconds. The value is specified in milliseconds.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
objHttpEx.ConnectionExpireTimeout = 300000
...
objHttpEx.Get "www.activexperts.com/axnetworking/postdemo/default.asp?parameter=200"

ConnectionPoolSize property

Type:

Number

Description:

The number of active connection that can be kept in the connection pool at one time. If the connection pool is full expired connections will be removed. If no connections have expired the oldest connection will be removed in favor of the new connection. By default this value is set to 32.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
objHttpEx.ConnectionPoolSize = 5
...
objHttpEx.Get "www.activexperts.com/axnetworking/postdemo/default.asp?parameter=200"

UserAgent property

Type:

String

Description:

Set this property to indicate which user agent is used to connect to a website. Some webservers will host different pages according to browser vendor or version.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
objHttpEx.UserAgent = "Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.2.3)"
...
objHttpEx.Get "www.activexperts.com"

FollowRedirect property

Type:

Boolean

Description:

Whether or not a HTTP redirect (HTTP code 301 or 302) will be automatically followed. This property is set to True by default.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
objHttpEx.FollowRedirect = False
...
objHttpEx.Get "http://google.com"

MaxRedirectionDepth property

Type:

Number

Description:

When the FollowRedirect properties is set to true, this is the maximum number of redirections that will be followed before cancelling the request.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
objHttpEx.MaxRedirectionDepth = 10
...
objHttpEx.Get "http://google.com"

ProxyServer property

Type:

String

Description:

If your Internet configuration requires access to a proxy server, you must assign the host name or IP address of the proxy server to the 'ProxyServer' property. Optionally, if proxy authentication is required, assign the proxy authentication values to the 'ProxyAccount' and 'ProxyPassword' properties. The proxy properties are used by the Get, Post, Head and GetFile method, so you must assign values to the proxy properties BEFORE calling one of these methods.

Example:

Set objHttp           = CreateObject("AxNetwork.HttpEx")
objHttp.ProxyServer   = "proxy01.intranet.dom"  ' Access through a proxy
objHttp.ProxyAccount  = "mjackson"              ' Proxy authentication required
objHttp.ProxyPassword = "mjackson1"             ' Proxy authentication required
...
objHttp.Connect "www.activexperts.com"

ProxyAccount property

Type:

String

Description:

If your Internet configuration requires access to a proxy server, you must assign the host name or IP address of the proxy server to the 'ProxyServer' property. Optionally, if proxy authentication is required, assign the proxy authentication values to the 'ProxyAccount' and 'ProxyPassword' properties. The proxy properties are used by the Get, Post, Head and GetFile method, so you must assign values to the proxy properties BEFORE calling one of these methods.

Example:

Set objHttp           = CreateObject("AxNetwork.HttpEx")
objHttp.ProxyServer   = "proxy01.intranet.dom"  ' Access through a proxy
objHttp.ProxyAccount  = "mjackson"              ' Proxy authentication required
objHttp.ProxyPassword = "mjackson1"             ' Proxy authentication required
...
objHttp.Connect "www.activexperts.com"

ProxyPassword property

Type:

String

Description:

If your Internet configuration requires access to a proxy server, you must assign the host name or IP address of the proxy server to the 'ProxyServer' property. Optionally, if proxy authentication is required, assign the proxy authentication values to the 'ProxyAccount' and 'ProxyPassword' properties. The proxy properties are used by the Get, Post, Head and GetFile method, so you must assign values to the proxy properties BEFORE calling one of these methods.

Example:

Set objHttp           = CreateObject("AxNetwork.HttpEx")
objHttp.ProxyServer   = "proxy01.intranet.dom"  ' Access through a proxy
objHttp.ProxyAccount  = "mjackson"              ' Proxy authentication required
objHttp.ProxyPassword = "mjackson1"             ' Proxy authentication required
...
objHttp.Connect "www.activexperts.com"

WebAccount property

Type:

String

Description:

If your Internet configuration requires access to a proxy server, you must assign the host name or IP address of the proxy server to the 'ProxyServer' property. Optionally, if proxy authentication is required, assign the proxy authentication values to the 'ProxyAccount' and 'ProxyPassword' properties. The proxy properties are used by the Get, Post, Head and GetFile method, so you must assign values to the proxy properties BEFORE calling one of these methods.

Example:

Set objHttp           = CreateObject("AxNetwork.HttpEx")
objHttp.ProxyServer   = "proxy01.intranet.dom"  ' Access through a proxy
objHttp.ProxyAccount  = "mjackson"              ' Proxy authentication required
objHttp.ProxyPassword = "mjackson1"             ' Proxy authentication required
...
objHttp.Connect "www.activexperts.com"

WebPassword property

Type:

String

Description:

If your Internet configuration requires access to a proxy server, you must assign the host name or IP address of the proxy server to the 'ProxyServer' property. Optionally, if proxy authentication is required, assign the proxy authentication values to the 'ProxyAccount' and 'ProxyPassword' properties. The proxy properties are used by the Get, Post, Head and GetFile method, so you must assign values to the proxy properties BEFORE calling one of these methods.

Example:

Set objHttp           = CreateObject("AxNetwork.HttpEx")
objHttp.ProxyServer   = "proxy01.intranet.dom"  ' Access through a proxy
objHttp.ProxyAccount  = "mjackson"              ' Proxy authentication required
objHttp.ProxyPassword = "mjackson1"             ' Proxy authentication required
...
objHttp.Connect "www.activexperts.com"

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all operations will be written to this log file.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
...
objHttpEx.LogFile = "c:\file.log"
objHttpEx.Get "www.activexperts.com:80/about"

9.3. Methods

Methods

Method Description
Clear Reset all properties to default
Get Gets the contents of a website as a string using an HTTP GET request
GetFile Downloads the contents of a website to a file using an HTTP GET request
Head Gets the headers for a website using the HTTP HEAD command
Post Post string data to a webpage and returns the response as a string using the HTTP POST command
SetHeader Set a custom header value for future GET or POST requests
UrlEncode Url Encode a given string
GetErrorDescription Get the error description
Sleep Suspends the execution of the object for at least the specified interval
Activate Activate the product

Clear method

Description:

Resets all properties to the initial value.

Parameters:

Return value:

Always 0.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
...
objHttpEx.SetHeader "Connection", "Keep-Alive"
objHttpEx.Clear
objHttpEx.Get "www.activexperts.com:8080/products/"
If( objHttpEx.LastError = 0 ) Then
  ...
End If

Get method

Description:

Get the contents of a webpage from a webserver and return it as a string value. This method defaults to non secure connections using the default HTTP port 80. The use of SSL or a diffent port can be specified as usual, e.g. https://cruisecontrol.intra:8080/dashboard connects securely on port 8080.

Parameters:

  • URL - The URL consists of a host name (or IP address), optionally a port number, and a relative path

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
...
WScript.Echo objHttpEx.Get("www.activexperts.com:8080/products/")
If( objHttpEx.LastError = 0 ) Then
  ...
End If

GetFile method

Description:

Get the contents of a webpage from a webserver and save it to a file. This method defaults to non secure connections using the default HTTP port 80. The use of SSL or a diffent port can be specified as usual, e.g. https://cruisecontrol.intra:8080/dashboard connects securely on port 8080.

Parameters:

  • URL - The URL consists of a host name (or IP address), optionally a port number, and a relative path

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
...
objHttpEx.GetFile "www.activexperts.com:8080/products/", "C:\products.txt"
If( objHttpEx.LastError = 0 ) Then
  ...
End If

Head method

Description:

Get the headers of a webpage from a webserver and return it as a string value. This method defaults to non secure connections using the default HTTP port 80. The use of SSL or a diffent port can be specified as usual, e.g. https://cruisecontrol.intra:8080/dashboard connects securely on port 8080.

Parameters:

  • URL - The URL consists of a host name (or IP address), optionally a port number, and a relative path

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
...
WScript.Echo objHttpEx.Head("www.slashdot.org")
If( objHttpEx.LastError = 0 ) Then
  ...
End If

Post method

Description:

Post a string to a website and returns the result as a string value. This method defaults to non secure connections using the default HTTP port 80. The use of SSL or a diffent port can be specified as usual, e.g. https://cruisecontrol.intra:8080/dashboard connects securely on port 8080.

Parameters:

  • URL - The URL consists of a host name (or IP address), optionally a port number, and a relative path

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
...
WScript.Echo objHttpEx.Post("www.activexperts.com:8080/products/", 
"COMPANY_NAME=test&COMPANY_URL=http://example.com")
If( objHttpEx.LastError = 0 ) Then
  ...
End If

SetHeader method

Description:

Set a custom HTTP header which will be include in future requests or posts made to a webserver. The header value will clear any header value of the same name that was previously set. To clear all header values call the Clear method.

Parameters:

  • Header - The name of the header
  • Value - The value

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
...
objHttpEx.SetHeader("Connection", "Keep-Alive")
WScript.Echo objHttpEx.Get("http://www.activexperts.com")
If( objHttpEx.LastError = 0 ) Then
  ...
End If

UrlEncode method

Description:

UrlEncode method encodes the given string. Use this method to encode parameters when using HttpEx to 'POST' or 'GET' specific parameters to a website.

Parameters:

  • Input string

Return value:

An encoded copy of the input string

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
...
Url = "http://www.google.com/search?hl=en&q=" & objHttpEx.UrlEncode("Hello, World !")
Wscript.Echo objHttpEx.Get(Url)
WScript.Echo "LastError: "         & objHttpEx.LastError
WScript.Echo "Error description: " & objHttpEx.GetErrorDescription( objHttpEx.LastError )

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objHttpEx = CreateObject("AxNetwork.HttpEx")
...
objHttpEx.Get "www.thispagedoesnotexist.dom/about"
WScript.Echo "LastError: "         & objHttpEx.LastError
WScript.Echo "Error description: " & objHttpEx.GetErrorDescription( objHttpEx.LastError )

Sleep method

Description:

This method can be used in your script anywhere you want; Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to hold

Return value:

Always 0.

Example:

Set objHttpEx        = CreateObject( "AxNetwork.HttpEx" )         ' Create HttpEx object
...
objHttpEx.Sleep 500

Activate method

Description:

This method activates the ActiveXperts Networking Component product. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objHttpEx         = CreateObject( "AxNetwork.HttpEx" ) ' Create HttpEx object
objHttpEx.Activate "xyz", True                ' Substitute xyz by your own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call
' Activate each time the product is started.

10. Icmp

10.1. Introduction

ICMP/Ping is one of the most commonly used utilities on the Internet by people and programs, with untold millions of pings flashing every second back and forth between computers. The original PING utility stood for "Packet Internet Groper", and was a package of diagnostic utilities used by DARPA personnel to test the performance of the ARPANET. Almost every operating system includes a Ping program. It has become one of the most versatile and widely used diagnostic tools on the Internet.

ICMP/Ping sends a small packet of information containing an ICMP ECHO_REQUEST to a specified computer, which then sends an ECHO_REPLY packet in return.

You can use Ping to perform several useful network diagnostics, such as the following:

  • Access - You can use Ping to see if you can reach another computer. If you can't ping a site at all, but you can ping other sites, then it's a pretty good sign that your network is fine and that site is down. On the other hand, if you can't ping any site, then likely your entire network connection is down - try rebooting;
  • Time & distance. You can use Ping to determine how long it takes to bounce a packet off of another site, which tells you its distance in network terms. For example, a site hosted on your neighbor's computer next door with a different Internet service provider might go through more routers and be farther away in network distance than a site on the other side of the ocean with a direct connection to the Internet backbone. If a site seems slow, you can compare ping distances to other sites to determine whether it is the site, the network, or your system that is slow. You can also compare ping times to get an idea of which sites have the fastest network access and would be most efficient for downloading, chat, and other applications;
  • Domain IP address. You can ping either a domain name or an IP address. If you ping a domain name, it will helpfully display the corresponding IP address in the response.

The ActiveXperts Networking Component Icmp object enables you to add Icmp/Ping functionality to your program.
Here is a small example (in VBScript) to show how to use the Icmp object:

Set objIcmp        = CreateObject("AxNetwork.Icmp")          ' Create Icmp object
objIcmp.Ping "www.activexperts.com", 2000                    ' Ping host; timeout 2000 ms
If( objIcmp.LastError = 0 ) Then
 WScript.Echo "Success, duration: " & objIcmp.LastDuration & "ms"
Else
 WScript.Echo "Error " & objIcmp.LastError & ": " &_
  objIcmp.GetErrorDescription( objIcmp.LastError )
End If
WScript.Echo "Ready."

10.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
LogFile String In/Out Log file; use it for troubleshooting purposes
Ttl Number In/Out Maximum Time To Live in next Ping call
BufferSize Number In/Out Send buffer size
LastError Number Out Result of the last called method
LastDuration Number Out Reply time of the last Ping call
LastTtl Number Out TTL of last Ping call

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objIcmp = CreateObject( "AxNetwork.Icmp" )       ' Create Icmp object
WScript.Echo  "Version: " & objIcmp.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objIcmp = CreateObject( "AxNetwork.Icmp" )       ' Create Icmp object
WScript.Echo  "Build: " & objIcmp.Build

Module property

Return the module name of the Component.

Example:

Set objIcmp = CreateObject( "AxNetwork.Icmp" )        ' Create new instance 
WScript.Echo  "Module: " & objIcmp.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objIcmp = CreateObject( "AxNetwork.Icmp" )        ' Create instance
WScript.Echo "LicenseStatus: " & objIcmp.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objIcmp = CreateObject("AxNetwork.Icmp")          ' Create new instance
WScript.Echo "LicenseKey: " & objIcmp.LicenseKey

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all operations will be written to this log file.

Example:

Set objIcmp = CreateObject( "AxNetwork.Icmp" )       ' Create Icmp object
objIcmp.LogFile = "c:\file.log

Ttl property

Type:

Number

Description:

Time To Live to be used in the next Ping call. Value must be between 1 and 255. Default value is 255.

Example:

Set objIcmp  = CreateObject( "AxNetwork.Icmp" )
objIcmp.Ttl  = 100                                              ' Use a different Time To Live 
                                                                ' than the default 255 value
objIcmp.Ping "www.monitortools.com", 2000                       ' Ping monitortools.com,timeout
                                                                ' after 2000 msec
If( objIcmp.LastError = 0 ) Then
  WScript.Echo "TTL: " & objIcmp.LastTtl
End If

BufferSize property

Type:

Number

Description:

Buffer size (in bytes) to be used in the next Ping call. Value must be between 0 and 8192. Default value is 32 (bytes).

Example:

Set objIcmp         = CreateObject( "AxNetwork.Icmp" )          ' Create Icmp object
objIcmp.BufferSize  = 64                                        ' Use a different buffer size
                                                                ' than the default (32 bytes)
objIcmp.Ping "www.monitortools.com", 2000                       ' Ping monitortools.com,timeout 
                                                                ' after 2000 msec

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objIcmp = CreateObject( "AxNetwork.Icmp" )               ' Create Icmp object
objIcmp.Ping "server.mydomain.com", 2000
WScript.Echo "LastError: " & objIcmp.LastError

LastDuration property

Type:

Number

Description:

The duration of the last Ping call. The property is read-only; you cannot assign a value to it.

Example:

Set objIcmp = CreateObject( "AxNetwork.Icmp" )               ' Create Icmp object
objIcmp.Ping "www.activexperts.com", 2000
WScript.Echo "Duration of ICMP/Ping operation: " & objIcmp.LastDuration

LastTtl property

Type:

Number

Description:

The Time To Live value of the last Ping call. The property is read-only; you cannot assign a value to it.
The maximum Time To Live value is indicated by the Ttl property. The default maximum Time To Live value is 255, but you can assign any value between 1 and 255 to it.

Example:

Set objIcmp = CreateObject( "AxNetwork.Icmp" )               ' Create Icmp object
objIcmp.Ping "www.monitortools.com", 2000
If( objIcmp.LastError = 0 ) Then
  WScript.Echo "TTL: " & objIcmp.LastTtl
End If

10.3. Methods

Methods

Method Description
Clear Clear all properties
Ping Ping the specified host
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval

Clear method

Description:

Reset all properties to their initial values. Use this method when you make consecutive calls to the Ping method.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objIcmp  = CreateObject( "AxNetwork.Icmp" )              ' Create Icmp object
objIcmp.Ping "192.168.1.1", 2000
objIcmp.Clear
objIcmp.Ping "192.168.1.2", 2000

Ping method

Description:

Ping the specified host. The method requires one parameter: the host that you want to check.

Parameters:

  • Host - Can be a host name, a NetBios name or an IP address
  • Timeout - Timeout in milliseconds to wait for a reply

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objIcmp  = CreateObject( "AxNetwork.Icmp" )              ' Create Icmp object
objIcmp.Ping "192.168.1.1", 2000
objIcmp.Clear
objIcmp.Ping "192.168.1.2", 2000

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objIcmp  = CreateObject( "AxNetwork.Icmp" )              ' Create Icmp object
objIcmp.Ping "www.thisdoesnotexist.com", 2000
WScript.Echo "LastError: " & objIcmp.LastError
WScript.Echo "Error description: " & objIcmp.GetErrorDescription( objIcmp.LastError )

Sleep method

Description:

This method can be used in your script anywhere you want. Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to suspend

Return value:

Always 0.

Example:

Set objIcmp        = CreateObject( "AxNetwork.Icmp" )        ' Create Icmp object
...
objIcmp.Sleep 500

11. IPtoCountry

11.1. Introduction

Today there are millions of internet users around the world. There are also numerous products and services available on the internet.

There are some key benefits of determines the country by IP address:

  • Marketing - adapt your business, web content or language according to the geographic location of the visitor;
  • Restrict access - restrict software or sites for users, based on the geographic location of the visitor;
  • Web server log analysis - restrict software or sites for users, based on the geographic location of the visitor;
  • Reduce credit card fraud.

The IPtoCountry object translates IP address to countries. It makes use of an internal IP-to-Coiuntry database, which resides as a data segment in the ActiveXperts Networking Component core component: AxNetwork32.dll. The accuracy is over 95%. The inaccuracy is due to dynamic IP address allocation by large ISPs such as AOL and MSN TV. It is also due to the use of proxy servers.

Here is a small example (in VBScript) to show how to use the IPtoCountry object and translate an IP address to a country:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )     ' Create instance of snmp mib
                                                                ' browser

objSnmpMib.LoadMibFile( "c:\windows\system32\hostmib.mib" )     ' Load MIB file
WScript.Echo "LoadMibFile, result: " & objSnmpMib.LastError
If( objSnmpMib.LastError <> 0 ) Then
  WScript.Quit 
End If

Set objSnmp = objSnmpMIB.Get("iso")                             ' Get first OID
While(objSnmpMIB.LastError = 0 )
  WScript.Echo "OID Name: " & objSnmp.Name & "; Full-path: " & objSnmp.Path
  WScript.Echo "  Description: " & objSnmp.Description
  WScript.Echo "  Access: " & objSnmp.Access
  WScript.Echo "  Status: " & objSnmp.Status                   
  Set objSnmp = objSnmpMIB.GetNext()                            ' Get next OID
WEnd

11.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
Host String In/Out Host or IP address to be translated to a country
CountryCode String Out Two-character country code (ISO 3166) associated with the given host or IP address
CountryCodeEx String Out Three-character country code (ISO 3166) associated with the given host or IP address
CountryName String Out Country name associated with the given host or IP address
LastError Number Out Result of the Query method
LogFile String In/Out Log file; use it for troubleshooting purposes

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objIPC = CreateObject( "AxNetwork.IPtoCountry" )         ' Create IPtoCountry object
WScript.Echo  "Version: " & objIPC.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objIPC = CreateObject( "AxNetwork.IPtoCountry" )         ' Create IPtoCountry object
WScript.Echo  "Build: " & objIPC.Build

Module property

Return the module name of the Component.

Example:

Set objIPC = CreateObject( "AxNetwork.IPtoCountry" )        ' Create new instance 
WScript.Echo  "Module: " & objIPC.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objIPC = CreateObject( "AxNetwork.IPtoCountry" )        ' Create instance
WScript.Echo "LicenseStatus: " & objIPC.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objIPC = CreateObject("AxNetwork.IPtoCountry")          ' Create new instance
WScript.Echo "LicenseKey: " & objIPC.LicenseKey

Host property

Type:

Number

Description:

Host name or IP address to be translated. The Query method translates this host/IP address to a country.

Example:

Set objIPC  = CreateObject( "AxNetwork.IPtoCountry" )       ' Create IPtoCountry object
objIPC.Host = "www.activexperts.com"                        ' Host name (or IP address) 
                                                            ' that you want to resolve
objIPC.Query()                                              ' Translate host/IP to country
WScript.Echo "Query, result: " & objIPC.LastError           ' Result of Query; 0 means: success
If objIPC.LastError <> 0 Then
   WScript.Quit
End If

WScript.Echo "Country (2 chars):" & objIPC.CountryCode      ' Two-character ISO 3166 country
                                                            ' code
WScript.Echo "Country (3 chars):" & objIPC.CountryCodeEx    ' Three-character ISO 3166 country
                                                            ' code
WScript.Echo "Country (full):"    & objIPC.CountryName      ' Full countryname

CountryCode property

Type:

String

Description:

Country associates with the given host or IP address. You need call Query to translate the host/IP address to a country. There are three different notations for a country; there's a property for each:

  • CountryCode - the two-character ISO 3166 country code. For instance: GB
  • CountryCodeEx - the three-character ISO 3166 country code. For instance: GBR
  • CountryName - the full country name. For instance: United Kingdom

For a list of possible country codes and country names, click here.

Example:

Set objIPC  = CreateObject( "AxNetwork.IPtoCountry" )           ' Create IPtoCountry object
objIPC.Host = "www.activexperts.com"                            ' Host name (or IP address) 
                                                                ' that you want to resolve
objIPC.Query()                                                  ' Translate host/IP to country
WScript.Echo "Query, result: " & objIPC.LastError               ' Result of Query; 
                                                                ' 0 means: success
If objIPC.LastError <> 0 Then
   WScript.Quit
End If

WScript.Echo "Country (2 chars):" & objIPC.CountryCode          ' Two-character ISO 3166 
                                                                ' country code
WScript.Echo "Country (3 chars):" & objIPC.CountryCodeEx        ' Three-character ISO 3166 
                                                                ' country code
WScript.Echo "Country (full):"    & objIPC.CountryName          ' Full countryname

CountryCodeEx property

CountryName property

TodoSirp

LastError property

Type:

Number

Description:

Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objIPC = CreateObject( "AxNetwork.IPtoCountry" )         ' Create IPtoCountry object
...
objIPC.Query() 
WScript.Echo "LastError: " & objIPC.LastError

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all operations will be written to this log file.

Example:

Set objIPC = CreateObject( "AxNetwork.IPtoCountry" )         ' Create IPtoCountry object
objIPC.LogFile = "c:\file.log"
...
objIPC.Query() 
WScript.Echo "LastError: " & objIPC.LastError

11.3. Methods

Methods

Method Description
Clear Reset all properties to the default values
Query Translate an IP address (or host name) to a country
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval
Activate Activate Software

Clear method

Description:

Reset all properties to their initial values. Use this method when you make consecutive calls to the Query method.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objIPC  = CreateObject( "AxNetwork.IPtoCountry" )           ' Create IPtoCountry object
...
objIPC.Query()                                              
objIPC.Clear()                                                  ' Clear all properties
objIPC.Query()

Query method

Description:

Translate an IP address (or host name) to a country.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objIPC  = CreateObject( "AxNetwork.IPtoCountry" )           ' Create IPtoCountry object
objIPC.Host = "www.activexperts.com"                            ' Host name (or IP address) 
                                                                ' that you want to resolve
objIPC.Query()                                                  ' Translate host/IP to country
WScript.Echo "Query, result: " & objIPC.LastError               ' Result of Query; 
                                                                ' 0 means: success
If objIPC.LastError <> 0 Then
   WScript.Quit
End If

WScript.Echo "Country (2 chars):" & objIPC.CountryCode          ' Two-character 
                                                                ' ISO 3166 country code
WScript.Echo "Country (3 chars):" & objIPC.CountryCodeEx        ' Three-character 
                                                                ' ISO 3166 country code
WScript.Echo "Country (full):"    & objIPC.CountryName          ' Full countryname
...

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objIPC  = CreateObject( "AxNetwork.IPtoCountry" )
objIPC.Host = "www.activexperts.com"                        
objIPC.Query()                                                  ' Translate host/IP to country
WScript.Echo "Query, result: " & objIPC.LastError & _           ' Error code
       objIPC.GetErrorDescription( objIPC.LastError )           ' Error Description

Sleep method

Description:

This method can be used in your script anywhere you want. Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to suspend

Return value:

Always 0.

Example:

Set objIPC         = CreateObject( "AxNetwork.IPtoCountry" ) ' Create IPtoCountry object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" ) ' Create constants object
...
objIPC.Sleep 500

Activate method

Description:

This method will activate the ActiveXperts Networking Component product. A valid registrationcode is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here).

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objIPC = CreateObject( "AxNetwork.IPtoCountry" )            ' Create IPtoCountry object
objIPC.Activate "xyz", True                                     ' Substitute xyz by your 
                                                                ' own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call 
' Activate each time the product is started

12. Msn

12.1. Introduction

The Msn object is an instant messaging client object. It allows you to connect to Microsoft's Live Messenger Service and send a basic message to one or more MSN recipients. It provides basic chat features only, i.e. a subset of the features provided by Windows Live Messenger (formerly known as MSN Messenger) which is available for most Windows operating systems. The Msn object doesn't provide enhanced features like emoticons and file transfers.

The features provided by the ActiveXperts Networking Component Msn object:

  • Connect to a Microsoft's Live Messenger Service; server is configurable (default: messenger.hotmail.com);
  • Login using a valid MSN account and MSN password;
  • Specify one or more MSN recipients;
  • Send a text message.

Here is a small example (in VBScript) to show how to use the Msn object to send an instant message to a remote MSN recipient:

Set objMsn = CreateObject( "AxNetwork.Msn" )                    ' Create Msn object

objMsn.LogFile      = "C:\MSNLog.txt"                           ' Set Log File (optional)

objMsn.MsnAccount   = "mymeself@activexperts.com"               ' Set MSN Account
objMsn.MsnPassword  = "topsecret"                               ' Set MSN Password

objMsn.Message      = "Hello World !!!!"                        ' Set MSN Message
objMsn.AddRecipient "mycollegue1@activexperts.com"              ' Add recipient(s)
objMsn.AddRecipient "mycollegue2@activexperts.com"               

objMsn.Send                                                     ' Send the message

WScript.Echo "Result : " & objMsn.LastError                     ' Display the result

12.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version of ActiveXperts Networking Component
Build String Out Build of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
Server String In/Out The MSN server you want to connect to
ServerPort Number In/Out The MSN server IP port number
MsnAccount String In/Out The MSN account used to logon to the MSN server
MsnPassword String In/Out The MSN password used to logon to the MSN server
MsnDisplayName String In/Out The MSN display name used when logged on to the MSN server
Message String In/Out The MSN message to send to the remote MSN recipient(s)
LastError Number Out Result of last used method
LogFile String In/Out Log file; use it for troubleshooting purposes

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )                    ' Create Msn object
WScript.Echo  "Version: " & objMsn.Version                      ' Show version information

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )                    ' Create Msn object
WScript.Echo  "Build: " & objMsn.Build                          ' Show build information

Module property

Return the module name of the Component.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )        ' Create new instance 
WScript.Echo  "Module: " & objMsn.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )        ' Create instance
WScript.Echo "LicenseStatus: " & objMsn.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objMsn = CreateObject("AxNetwork.Msn")          ' Create new instance
WScript.Echo "LicenseKey: " & objMsn.LicenseKey

Server property

Type:

String

Description:

The MSN server you want to connect to. Default value: messenger.hotmail.com

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )                    ' Create Msn object

objMsn.Server       = "messenger2.hotmail.com"                  ' Use messenger2.hotmail.com
objMsn.MsnAccount   = "mymeself@activexperts.com"        
objMsn.MsnPassword  = "topsecret"                    

objMsn.Message      = "Hello World !!!!"               
objMsn.AddRecipient "mycollegue1@activexperts.com"       

objMsn.Send                                                     ' Send the message

ServerPort property

Type:

Number

Description:

IP port of the MSN server you want to connect to. Default value: 1863.

Set objMsn = CreateObject( "AxNetwork.Msn" )                    ' Create Msn object

objMsn.Server       = "messenger2.hotmail.com"                  ' Use messenger2.hotmail.com
objMsn.ServerPort   = 8063                                      ' Use port 8063
objMsn.MsnAccount   = "mymeself@activexperts.com"        
objMsn.MsnPassword  = "topsecret"                      

objMsn.Message      = "Hello World !!!!"               
objMsn.AddRecipient "mycollegue1@activexperts.com"      

objMsn.Send                                                     ' Send the message

MsnAccount property

Type:

String

Description:

The MSN account used to logon to the MSN server.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )                    ' Create Msn object

objMsn.MsnAccount   = "mymeself@activexperts.com"               ' Set MSN Account
objMsn.MsnPassword  = "topsecret"                               ' Set MSN Password

objMsn.Message      = "Hello World !!!!"                 
objMsn.AddRecipient "mycollegue1@activexperts.com"      

objMsn.Send                                                     ' Send the message

MsnPassword property

Type:

String

Description:

The MSN password used to logon to the MSN server.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )                    ' Create Msn object

objMsn.MsnAccount   = "mymeself@activexperts.com"               ' Set MSN Account
objMsn.MsnPassword  = "topsecret"                               ' Set MSN Password

objMsn.Message      = "Hello World !!!!"                  
objMsn.AddRecipient "mycollegue1@activexperts.com"       

objMsn.Send                                                     ' Send the message

MsnDisplayName property

Type:

String

Description:

The friendly name that will be shown to the remote MSN users. If omitted, the MSN Account is displayed.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )                    ' Create Msn object

objMsn.MsnAccount   = "mymeself@activexperts.com"         
objMsn.MsnPassword  = "topsecret"                          
objMsn.MsnDisplayName = "Me Myself"                             ' Set MSN Display Name

objMsn.Message      = "Hello World !!!!"                 
objMsn.AddRecipient "mycollegue1@activexperts.com"     

objMsn.Send                                                     ' Send the message

Message property

Type:

String

Description:

The Message text that to send to the remote recipients. The maximum length of a message is 1664 characters.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )                    ' Create Msn object

objMsn.MsnAccount   = "mymeself@activexperts.com"         
objMsn.MsnPassword  = "topsecret"                         
objMsn.MsnDisplayName = "Me Myself"                        

objMsn.Message      = "Hello World !!!!"                        ' Set Message text
objMsn.AddRecipient "mycollegue1@activexperts.com"       

objMsn.Send                                                     ' Send the message

LastError property

Type:

Number

Description:

Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )               ' Create Msn object      
...
objMsn.Send                                                ' Send the message
WScript.Echo objMsn.LastError                              ' Display the result of the
                                                           ' Send method

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all operations will be written to this log file.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )               ' Create Msn object      
objLogFile = "c:\msn.log"                                  ' Set log file 
...
objMsn.Send                                                ' Send the message
WScript.Echo objMsn.LastError                              ' Display the result of the
                                                           ' Send method

12.3. Methods

Methods

Method Description
Clear Reset all properties to the default values
AddRecipient Add an MSN recipient
Send Send the MSN message to the remote MSN recipient(s)
GetErrorDescription Get the description of the given error
Activate Activate Software

Clear method

Description:

Reset all properties to their initial values. Use this method when you make consecutive calls to the Send method.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objMsn  = CreateObject( "AxNetwork.Msn" )              ' Create Msn object
...
objMsn.Send()                                              
objMsn.Clear()                                             ' Clear all properties
objMsn.Send()

AddRecipient method

Description:

Add an MSN recipient. You can add multiple recipients, i.e. call the AddRecipient method multiple times.

Parameters:

  • The MSN address of the remote MSN recipient

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )               ' Create Msn object

objMsn.Server       = "messenger2.hotmail.com"            
objMsn.MsnAccount   = "mymeself@activexperts.com"         
objMsn.MsnPassword  = "topsecret"                          

objMsn.Message      = "Hello World !!!!"                   
objMsn.AddRecipient "mycollegue1@activexperts.com"         ' Add recipient(s)
objMsn.AddRecipient "mycollegue2@activexperts.com"               

objMsn.Send                                                ' Send the message

WScript.Echo "Result : " & objMsn.LastError                ' Display the result

Send method

Description:

Send the MSN message to the remote MSN recipient(s).

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )               ' Create Msn object

objMsn.Server       = "messenger2.hotmail.com"            
objMsn.MsnAccount   = "mymeself@activexperts.com"         
objMsn.MsnPassword  = "topsecret"                          

objMsn.Message      = "Hello World !!!!"                   
objMsn.AddRecipient "mycollegue1@activexperts.com" 

objMsn.Send                                                ' Send the message

WScript.Echo "Result : " & objMsn.LastError

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )               ' Create Msn object
...
objMsn.Send                                                ' Send the message
WScript.Echo "Result : " & objMsn.LastError & _
  " (" & objMsn.GetErrorDescription ( objMsn.LastError ) & ")"

Activate method

Description:

This method will activate the ActiveXperts Networking Component product. A valid registrationcode is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here).

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objMsn = CreateObject( "AxNetwork.Msn" )                 ' Create Msn object
objMsn.Activate "xyz", True            ' Substitute xyz by your own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call 
' Activate each time the product is started

13. Ntp

13.1. Introduction

The Network Time Protocol (NTP) has been developed to address the issue of providing accurate and synchronized time across the Internet. The protocol itself has been in development since 1985 and has therefore reached a fairly mature status. The latest stable version of NTP is version 3 and described in RFC-1305 the latest testing version is NTP version 4.

The Network Time Protocol aims to synchronize a systems clock to Coordinated Universal Time (UTC). UTC is a development of Greenwich Mean Time (GMT). GMT is based on the rotation of the earth while UTC is based on the standard length of a second determined from quantum phenomena, but both use the Greenwich time zone as the zero offset.

NTP uses a augmented hierarchical client-server topology. A small number of servers distribute time to a larger number of clients which can simultaneously act as servers to further clients. The top level clients are referred to as stratum 1 servers and their clients are termed as being at stratum 2. Clients of a stratum 2 server are at stratum 3 and so on. The stratum 1 servers are synchronized to radio clocks which receive time signals from national time standards such as the MSF signal provided by the NPL broadcast from Rugby or the GPS time signal provided by the Global Positioning System. The radio clocks themselves are termed stratum 0 servers.

The ActiveXperts Networking Component Ntp object enables you to add Ntp functionality to your program. Here is a small example (in VBScript) to show how to use the Ntp object: The following sample (in VBScript) runs the '/bin/ls' command on host '192.168.1.10', and will timeout when the script takes more than 5000 milliseconds:

objNtp = CreateObject( "AxNetwork.Ntp" )       ' Create a new Ntp instance
objNtp.GetTime "mytimeserver.domain.dom"       ' Retrieve time from this time server
If( objNtp.LastError = 0 ) Then
  WScript.Echo "Time retrieved successfully, the results are:"
  WScript.Echo "Year : "   & objNtp.Year
  WScript.Echo "Month : "  & objNtp.Month
  WScript.Echo "Day : "    & objNtp.Day
  WScript.Echo "Hour : "   & objNtp.Hour
  WScript.Echo "Minute : " & objNtp.Minute
  WScript.Echo "Second : " & objNtp.Second
End If

13.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
LastError Number Out Result of the last called method
Year Number Out The year, as provided by the NTP server
Month Number Out The month, as provided by the NTP server
Day Number Out The day, as provided by the NTP server
Hour Number Out The hour, as provided by the NTP server
Minute Number Out The minute, as provided by the NTP server
Second Number Out The second, as provided by the NTP server
LocalOffsetSeconds Number Out The offset (in seconds) between the local computer and the Network Time Server

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objNtp = CreateObject( "AxNetwork.Ntp" )            ' Create Ntp object
WScript.Echo  "Version: " & objNtp.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objNtp = CreateObject( "AxNetwork.Ntp" )           ' Create Ntp object
WScript.Echo  "Build: " & objNtp.Build

Module property

Return the module name of the Component.

Example:

Set objNtp = CreateObject( "AxNetwork.Ntp" )        ' Create new instance 
WScript.Echo  "Module: " & objNtp.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objNtp = CreateObject( "AxNetwork.Ntp" )        ' Create instance
WScript.Echo "LicenseStatus: " & objNtp.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objNtp = CreateObject("AxNetwork.Ntp")          ' Create new instance
WScript.Echo "LicenseKey: " & objNtp.LicenseKey

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

objNtp = CreateObject( "AxNetwork.Ntp" )                   ' Create a new Ntp instance
objNtp.GetTime "timeserver01.domain.dom"                   ' Retrieve time
WScript.Echo "LastError: " & objNtp.LastError

Year property

Type:

Number

Description:

After a successful call to the GetTime method, the 'Year', 'Month', 'Day', 'Hour', 'Minute' and 'Second' properties are assigned with the time information that was retrieved from the Network Time Server. The properties are read-only; you cannot assign a value to it.

Example:

objNtp = CreateObject( "AxNetwork.Ntp" )                   ' Create a new Ntp instance
objNtp.GetTime( "timeserver.domain.dom" )                  ' Retrieve time
if( objNtp.LastError = 0 ) Then
  WScript.Echo "Year : " & objNtp.Year
  WScript.Echo "Month : " & objNtp.Month
  WScript.Echo "Day : " & objNtp.Day
  WScript.Echo "Hour : " & objNtp.Hour
  WScript.Echo "Minute : " & objNtp.Minute
  WScript.Echo "Second : " & objNtp.Second
End If

Month property

Type:

Number

Description:

After a successful call to the GetTime method, the 'Year', 'Month', 'Day', 'Hour', 'Minute' and 'Second' properties are assigned with the time information that was retrieved from the Network Time Server. The properties are read-only; you cannot assign a value to it.

Example:

objNtp = CreateObject( "AxNetwork.Ntp" )                   ' Create a new Ntp instance
objNtp.GetTime( "timeserver.domain.dom" )                  ' Retrieve time
if( objNtp.LastError = 0 ) Then
  WScript.Echo "Year : " & objNtp.Year
  WScript.Echo "Month : " & objNtp.Month
  WScript.Echo "Day : " & objNtp.Day
  WScript.Echo "Hour : " & objNtp.Hour
  WScript.Echo "Minute : " & objNtp.Minute
  WScript.Echo "Second : " & objNtp.Second
End If

Day property

Type:

Number

Description:

After a successful call to the GetTime method, the 'Year', 'Month', 'Day', 'Hour', 'Minute' and 'Second' properties are assigned with the time information that was retrieved from the Network Time Server. The properties are read-only; you cannot assign a value to it.

Example:

objNtp = CreateObject( "AxNetwork.Ntp" )                   ' Create a new Ntp instance
objNtp.GetTime( "timeserver.domain.dom" )                  ' Retrieve time
if( objNtp.LastError = 0 ) Then
  WScript.Echo "Year : " & objNtp.Year
  WScript.Echo "Month : " & objNtp.Month
  WScript.Echo "Day : " & objNtp.Day
  WScript.Echo "Hour : " & objNtp.Hour
  WScript.Echo "Minute : " & objNtp.Minute
  WScript.Echo "Second : " & objNtp.Second
End If

Hour property

Type:

Number

Description:

After a successful call to the GetTime method, the 'Year', 'Month', 'Day', 'Hour', 'Minute' and 'Second' properties are assigned with the time information that was retrieved from the Network Time Server. The properties are read-only; you cannot assign a value to it.

Example:

objNtp = CreateObject( "AxNetwork.Ntp" )                   ' Create a new Ntp instance
objNtp.GetTime( "timeserver.domain.dom" )                  ' Retrieve time
if( objNtp.LastError = 0 ) Then
  WScript.Echo "Year : " & objNtp.Year
  WScript.Echo "Month : " & objNtp.Month
  WScript.Echo "Day : " & objNtp.Day
  WScript.Echo "Hour : " & objNtp.Hour
  WScript.Echo "Minute : " & objNtp.Minute
  WScript.Echo "Second : " & objNtp.Second
End If

Minute property

Type:

Number

Description:

After a successful call to the GetTime method, the 'Year', 'Month', 'Day', 'Hour', 'Minute' and 'Second' properties are assigned with the time information that was retrieved from the Network Time Server. The properties are read-only; you cannot assign a value to it.

Example:

objNtp = CreateObject( "AxNetwork.Ntp" )                   ' Create a new Ntp instance
objNtp.GetTime( "timeserver.domain.dom" )                  ' Retrieve time
if( objNtp.LastError = 0 ) Then
  WScript.Echo "Year : " & objNtp.Year
  WScript.Echo "Month : " & objNtp.Month
  WScript.Echo "Day : " & objNtp.Day
  WScript.Echo "Hour : " & objNtp.Hour
  WScript.Echo "Minute : " & objNtp.Minute
  WScript.Echo "Second : " & objNtp.Second
End If

Second property

Type:

Number

Description:

After a successful call to the GetTime method, the 'Year', 'Month', 'Day', 'Hour', 'Minute' and 'Second' properties are assigned with the time information that was retrieved from the Network Time Server. The properties are read-only; you cannot assign a value to it.

Example:

objNtp = CreateObject( "AxNetwork.Ntp" )                   ' Create a new Ntp instance
objNtp.GetTime( "timeserver.domain.dom" )                  ' Retrieve time
if( objNtp.LastError = 0 ) Then
  WScript.Echo "Year : " & objNtp.Year
  WScript.Echo "Month : " & objNtp.Month
  WScript.Echo "Day : " & objNtp.Day
  WScript.Echo "Hour : " & objNtp.Hour
  WScript.Echo "Minute : " & objNtp.Minute
  WScript.Echo "Second : " & objNtp.Second
End If

LocalOffsetSeconds property

Type:

Number

Description:

After a successful call to the GetTime method, the 'LocalOffsetSeconds' holds the offset (in seconds) between the NTP server time and the local computer time. Use this value to check if your local computer time is in sync with the NTP server's time. The property is read-only; you cannot assign a value to it.

Example:

objNtp = CreateObject( "AxNetwork.Ntp" )                   ' Create a new Ntp instance
objNtp.GetTime( "timeserver.domain.dom" )                  ' Retrieve time
If( objNtp.LastError = 0 ) Then
  WScript.Echo "Time offset : " & objNtp.LocalOffsetSeconds & " seconds"
End If

13.3. Methods

Methods

Method Description
Clear Reset all properties to the default values
GetTime Query the NTP server to retrieve date and time
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval
Activate Activate Software

Clear method

Description:

Resets all properties to the initial values. Use this method when you make consecutive calls to the GetTime method. It sets Year, Month, Day, Hour, Minute and Second to 0.

Parameters:

  • None

Return value:

Always 0.

Example:

objNtp = CreateObject( "AxNetwork.Ntp" )                   ' Create a new Ntp instance
objNtp.GetTime( "timeserver.domain.dom" )                  ' Retrieve time
...
objNtp.Clear()
objNtp.GetTime( "timeserver02.domain.dom" )
...
objNtp.Clear()
objNtp.GetTime( "timeserver03.domain.dom" )
...

GetTime method

Description:

Query the network time server and retrieve its date and time.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

objNtp = CreateObject( "AxNetwork.Ntp" )                   ' Create a new Ntp instance
objNtp.GetTime( "timeserver.domain.dom" )                  ' Retrieve time
If( objNtp.LastError = 0 ) Then
  WScript.Echo "Year : "   & objNtp.Year
  WScript.Echo "Month : "  & objNtp.Month
  WScript.Echo "Day : "    & objNtp.Day
  WScript.Echo "Hour : "   & objNtp.Hour
  WScript.Echo "Minute : " & objNtp.Minute
  WScript.Echo "Second : " & objNtp.Second
End If

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objNtp = CreateObject("AxNetwork.Ntp")                 ' Create a new Ntp instance
objNtp.GetTime( "invalidtimeserver.com" )                  ' Retrieve time
WScript.Echo "Error description: " & objNtp.GetErrorDescription( objNtp.LastError )

Sleep method

Description:

This method can be used in your script anywhere you want. Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to suspend

Return value:

Always 0.

Example:

Set objNtp         = CreateObject( "AxNetwork.Ntp" )          ' Create Ntp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )  ' Create constants object
...
objNtp.Sleep 500

Activate method

Description:

This method activates the ActiveXperts Networking Component product. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objNtp         = CreateObject( "AxNetwork.Ntp" )       ' Create Ntp object
objNtp.Activate "xyz", True      ' Substitute xyz by your own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call
' Activate each time the product is started

14. RADIUS

14.1. Introduction

RADIUS (Remote Authentication Dial In User Service) is a networking protocol that provides centralized authentication and authorization management for computers to connect and use a network service. It was originally developed by Livingston Enterprises in 1991 as an access server authentication and accounting protocol and later brought into the IETF standards where it is described in RCF 2865 and RCF 2866.

RADIUS is a client/server protocol that uses UDP as a transport. A RADIUS server is usually a background process running on a UNIX or Windows NT server. The RADIUS component in ActiveXperts Networking Component currently only supports authenticating users. This means that the ActiveXperts Networking Component RADIUS implementation can be used to check against a RADIUS server whether or not a user has access to a network.

The following sample (in VBScript) tests if the user 'Test' has access to a network, and will timeout when the script takes more than 5000 milliseconds:

Set objRadius = CreateObject("AxNetwork.Radius")                ' Create a Radius instance

objRadius.CheckAccess "192.168.1.10", "test", "password", _ 
  "secret"                                                      ' Check if the test user is 
                                                                ' authorized
If objRadius.LastError <> 0 Then
  WScript.Echo "Error: "  & objRadius.LastError
  WScript.Echo "Description "  & objRadius.GetErrorDescription(objRadius.LastError)  
  WScript.Quit 1
End If

WScript.Echo "Ready."

14.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
LastError Number Out Result of the last called method
Timeout Number In/Out Specifies the number of milliseconds until the command times out

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objRadius = CreateObject( "AxNetwork.Radius" )            ' Create Radius object
WScript.Echo  "Version: " & objRadius.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objRadius = CreateObject( "AxNetwork.Radius" )           ' Create Radius object
WScript.Echo  "Build: " & objRadius.Build

Module property

Return the module name of the Component.

Example:

Set objRadius = CreateObject( "AxNetwork.Radius" )        ' Create new instance 
WScript.Echo  "Module: " & objRadius.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objRadius = CreateObject( "AxNetwork.Radius" )        ' Create instance
WScript.Echo "LicenseStatus: " & objRadius.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objRadius = CreateObject("AxNetwork.Radius")          ' Create new instance
WScript.Echo "LicenseKey: " & objRadius.LicenseKey

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objRadius           = CreateObject("AxNetwork.Radius")    ' Create an Radius instance
...
objRadius.CheckAccess "192.168.1.10", "test", "password", "secret"
WScript.Echo "LastError: " & objRadius.LastError

Timeout property

Type:

Number

Description:

Specifies the number of milliseconds before the command will time out.

Example:

Set objRadius           = CreateObject("AxNetwork.Radius")      ' Create an Radius 
                                                                ' instance
objRadius.TimeOut       = 6000                                  ' Timeout after 6000 
                                                                ' milliseconds
objRadius.CheckAccess "192.168.1.10", "test", "password", "secret"

14.3. Methods

Methods

Method Description
Clear Reset all properties to the default values
CheckAccess Check if a user would be authorized
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval
Activate Activate Software

Clear method

Description:

Reset all properties to the initial values. Use this method when you make consecutive calls to the CheckAccess method. It resets all properties

Parameters:

  • None

Return value:

Always 0.

Example:

Set objRadius = CreateObject("AxNetwork.Radius")                ' Create an Radius instance
...
objRadius.Timeout         = 10000
objRadius.CheckAccess "192.168.1.10", "test", "password", "secret"
objRadius.Clear                                                 ' Resets properties
' Set new property values
...
objRadius.Timeout         = 8000
objRadius.CheckAccess "192.168.1.10", "test", "password", "secret"
objRadius.Clear
...

CheckAccess method

Sirp

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objRadius           = CreateObject("AxNetwork.Radius")  ' Create an Radius instance
objRadius.CheckAccess "192.168.1.10", "test", "password", "secret"
WScript.Echo "Run: result = " & objRadius.LastError

Sleep method

ToDo

Activate method

Description:

This method activates the ActiveXperts Networking Component product. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objRadius         = CreateObject( "AxNetwork.Radius" )       ' Create Radius object
objRadius.Activate "xyz", True                  ' Substitute xyz by your own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call
' Activate each time the product is started

15. Rsh

15.1. Introduction

Rsh executes a command on a host. The remote hosts must run the Rsh daemon.
An Rsh client utility is shipped with most operating systems these days. This Rsh command line utility copies its standard input to the remote command, the standard output of the remote command to its standard output, and the standard error of the remote command to its standard error. Interrupt, quit and terminate signals are propagated to the remote command; rsh normally terminates when the remote command does.

The ActiveXperts Networking Component Rsh object has the same functionality as the Rsh command-line utility, except that it has no user interface by itself: standard error and standard output are not copied to the console, but are copied to the corresponding object properties (StdErr and StdOut) instead.

The following sample (in VBScript) runs the '/bin/ls' command on host '192.168.1.10', and will timeout when the script takes more than 5000 milliseconds:

Set objRsh           = CreateObject("AxNetwork.Rsh")            ' Create an Rsh instance
objRsh.Host          = "192.168.1.10"                           ' Hostname or IP address of  
                                                                ' remote UNIX/LINUX machine
objRsh.UserName      = "root"                                   ' Login as 'root'
objRsh.Password      = "topsecret"                              ' Use a password to login
objRsh.Command       = "/bin/ls"                                ' Command to execute
objRsh.ScriptTimeOut = 5000                                     ' Time-out (in milliseconds)
objRsh.Run                                                      ' Execute the command now
WScript.Echo "Run: result = " & objRsh.LastError 
If objRsh.LastError <> 0 Then
  WScript.Echo "Error "  & objRsh.LastError
End If
' YES, command has completed
WScript.Echo "StdErr: " & objRsh.StdErr                         ' Print Standard Error
WScript.Echo "StdOut: " & objRsh.StdOut                         ' Print Standard Output

WScript.Echo "Ready."

15.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
LastError Number Out Result of the last called method
Command String In/Out Specifies the command to run on the remote host
Host String In/Out Specifies the host on which to run the command
UserName String In/Out Specifies the user name to use on the remote host. If omitted, the logged on user name is used.
ScriptTimeOut Number In/Out Specifies the number of milliseconds until the command times out
StdErr String Out The Rsh 'Run' method copies its standard error to this property
StdOut String Out The Rsh 'Run' method copies its standard output to this property

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objRsh = CreateObject( "AxNetwork.Rsh" )                 ' Create Rsh object
WScript.Echo  "Version: " & objRsh.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objRsh = CreateObject( "AxNetwork.Rsh" )                ' Create Rsh object
WScript.Echo  "Build: " & objRsh.Build

Module property

Return the module name of the Component.

Example:

Set objRsh = CreateObject( "AxNetwork.Rsh" )        ' Create new instance 
WScript.Echo  "Module: " & objRsh.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objRsh = CreateObject( "AxNetwork.Rsh" )        ' Create instance
WScript.Echo "LicenseStatus: " & objRsh.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objRsh = CreateObject("AxNetwork.Rsh")          ' Create new instance
WScript.Echo "LicenseKey: " & objRsh.LicenseKey

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objRsh           = CreateObject("AxNetwork.Rsh")         ' Create an Rsh instance
...
objRsh.Run
WScript.Echo "LastError: " & objRsh.LastError

Command property

Type:

String

Description:

Specifies the command to run on the remote host.

Example:

Set objRsh           = CreateObject("AxNetwork.Rsh")         ' Create an Rsh instance
objRsh.Command       = "/bin/ls"
objRsh.Host          = "server01.domain.dom"
objRsh.Run

Host property

Type:

String

Description:

Specifies the host on which to run the command.

Example:

Set objRsh           = CreateObject("AxNetwork.Rsh")         ' Create an Rsh instance
objRsh.Host          = "server01.domain.dom"
objRsh.Command       = "/bin/ls"
objRsh.Run

UserName property

Type:

String

Description:

Specifies the user name to use on the remote host. If omitted, the logged on user name is used.

Example:

Set objRsh           = CreateObject("AxNetwork.Rsh")         ' Create an Rsh instance
objRsh.Host          = "server01.domain.dom"
objRsh.Command       = "/bin/ls"
objRsh.UserName      = "mjohnson"
objRsh.Run

ScriptTimeOut property

Type:

Number

Description:

Specifies the number of milliseconds before the command will time out.

Example:

Set objRsh           = CreateObject("AxNetwork.Rsh")            ' Create an Rsh instance
objRsh.Host          = "server01.domain.dom"
objRsh.Command       = "/bin/ls"
objRsh.ScriptTimeOut = 6000                                     ' Timeout after 6000 
                                                                ' milliseconds
objRsh.Run

StdErr property

Type:

String

Description:

Rsh connects to the command. Rsh copies its standard error of the remote command to the 'StdErr' property.

Example:

Set objRsh           = CreateObject("AxNetwork.Rsh")         ' Create an Rsh instance
...
objRsh.Run
If( objRsh.LastError = 0 ) Then
  WScript.Echo "StdErr: " & objRsh.StdErr
End

StdOut property

Type:

String

Description:

Rsh connects to the command. Rsh copies its standard out of the remote command to the 'StdOut' property.

Example:

Set objRsh           = CreateObject("AxNetwork.Rsh")         ' Create an Rsh instance
objRsh.Run
If( objRsh.LastError = 0 ) Then
  WScript.Echo "StdOut: " & objRsh.StdOut
End

15.3. Methods

Methods

Method Description
Clear Reset all properties to the default values
Run Run the command on the remote host
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval
Activate Activate Software

Clear method

Description:

Reset all properties to the initial values. Use this method when you make consecutive calls to the Run method. It resets all properties

Parameters:

  • None

Return value:

Always 0.

Example:

 
Set objRsh = CreateObject("AxNetwork.Rsh")                      ' Create an Rsh instance
...
objRsh.Run
objRsh.Clear                                                    ' Resets properties
' Set new property values
...
objRsh.Run
objRsh.Clear
...

Run method

Description:

Run the command on the remote host.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objRsh           = CreateObject("AxNetwork.Rsh")         ' Create an Rsh instance
objRsh.Host          = "192.168.1.10"
objRsh.Command       = "/bin/ls"
objRsh.Run
WScript.Echo "Run: result = " & objRsh.LastError

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objRsh           = CreateObject("AxNetwork.Rsh")         ' Create an Rsh instance
objRsh.Host          = "192.168.1.10"
objRsh.Command       = "/bin/ls"
objRsh.Run
WScript.Echo "Run: result = " & objRsh.LastError

Sleep method

Description:

This method can be used in your script anywhere you want. Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to suspend

Return value:

Always 0.

Example:

Set objRsh         = CreateObject( "AxNetwork.Rsh" )         ' Create Rsh object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" ) ' Create constants object
...
objRsh.Sleep 500

Activate method

Description:

This method activates the ActiveXperts Networking Component. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objRsh         = CreateObject( "AxNetwork.Rsh" )            ' Create Rsh object
objRsh.Activate "xyz", True                                     ' Substitute xyz by 
                                                                ' your own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call
' Activate each time the product is started

16. Scp

16.1. Introduction

Scp (Secure Copy Protocol) is a way to securely transfer files between two computers using the SSH (Secure SHell) protocol.

The Secure Copy Protocol is the secure analog of the old UNIX RCP command. It is implemented as a part of the SSH system, which means that an SCP client can be used to copy to any file or files to or from a host which has an SSH server running and which has the SCP service enabled.

An SCP client can only be used to copy files. To list the contents of a remote directory or to query for remote file information either SSH or SFTP would be required. In most applications the SCP protocol is considered to be superseded by the more advanced SFTP protocol. However, in some implementations copying a file using an SCP implementation can have a performance advantage.

The ActiveXperts Networking Component SCP implementation is based on the PuTTY SCP implementation.

When connecting to a remote host there are two ways to authenticate: by using a password or by using a 'private key'. When using a password to authenticate it is required that the host private key is known to the system. If the hosts private key is unknown to the system or if it was changed since the last connection the Scp object will return an error. To connect anyway and store the host key in the registry for future connections the 'AcceptHostKey' property can be set.

NOTE:

  • The ActiveXperts Networking Component Scp object is not thread safe (A process can only have one active session). However, it is possible to run multiple processes with active sessions at once.

The following sample (in VBScript) copies the 'Smalltoken.file to the 'demo' users home directory on 192.168.1.10 using a password:

  Set objScp           = CreateObject("AxNetwork.Scp")          ' Create an Scp instance
  objScp.Host          = "192.168.1.10"                         ' Hostname or IP address of 
                                                                ' remote UNIX/LINUX machine
  objScp.UserName      = "demo"                                 ' Login as 'demo'
  objScp.Password      = "topsecret"                            ' Use a password to login
  objScp.CopyToRemote "Smalltoken.file", "."                    ' Copy the file to the remote 
                                                                ' location
  WScript.Echo "Copy: result = " & objScp.LastError 
  If objScp.LastError <> 0 Then
    WScript.Echo "Error: "  & objScp.LastError
    If objScp.ProtocolError <> "" Then
      WScript.Echo "Protocol error: " & objScp.ProtocolError    
    End If
  End If
  ' YES, command has completed
  WScript.Echo "Ready."

The following sample (in VBScript) copies the 'Smalltoken.file to the 'demo' users home directory on 192.168.1.10 using a private key file:

  Set objScp           = CreateObject("AxNetwork.Scp")          ' Create an Scp instance
  objScp.Host          = "192.168.1.10"                         ' Hostname or IP address of 
                                                                ' remote UNIX/LINUX machine
  objScp.UserName      = "demo"                                 ' Login as 'demo'
  objScp.PrivateKeyFile = "c:\files\privkey.ppk"                ' Use a private key file to 
                                                                ' login    
  objScp.CopyToRemote "Smalltoken.file", "."                    ' Copy the file to the remote 
                                                                ' location
  WScript.Echo "Copy: result = " & objScp.LastError 
  If objScp.LastError <> 0 Then
    WScript.Echo "Error: "  & objScp.LastError
    If objScp.ProtocolError <> "" Then
      WScript.Echo "Protocol error: " & objScp.ProtocolError    
    End If
  End If
  ' YES, command has completed
  WScript.Echo "Ready."

16.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
LastError Number Out Result of the last called method
ProtocolError String Out If the last called method triggered a protocol error. This property will contain more information.
Host String In/Out Specifies the host to which or from which should be copied
Port Number In/Out TCP port number to identify a (remote) SSH/SCP daemon. Default: 22
UserName String In/Out Specifies the user name to use on the remote host
Password String In/Out Specifies the password to use on the remote host. If this property is left blank the 'PrivateKeyFile' property will be used to authenticate.
PrivateKeyFile String In/Out Specifies the private key file to logon to the remote host. If this property is left blank the 'Password' property will be used to authenticate.
Recursive Boolean In/Out Specifies whether to recursively copy directories
Compression Boolean In/Out Specifies whether to use compression when transferring files
AcceptHostKey Boolean In/Out Specifies whether to accept an unknown or changed host key
HostFingerprint String Out The Scp 'CopyToRemote' and 'CopyToLocal' methods copy the host key fingerprint to this property
LogFile Boolean In/Out Log file; use it for troubleshooting purposes

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objScp = CreateObject( "AxNetwork.Scp" )                 ' Create Scp object
WScript.Echo  "Version: " & objScp.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objScp = CreateObject( "AxNetwork.Scp" )                 ' Create Scp object
WScript.Echo  "Build: " & objScp.Build

Module property

Return the module name of the Component.

Example:

Set objScp = CreateObject( "AxNetwork.Scp" )        ' Create new instance 
WScript.Echo  "Module: " & objScp.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objScp = CreateObject( "AxNetwork.Scp" )        ' Create instance
WScript.Echo "LicenseStatus: " & objScp.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objScp = CreateObject("AxNetwork.Scp")          ' Create new instance
WScript.Echo "LicenseKey: " & objScp.LicenseKey

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objScp           = CreateObject("AxNetwork.Scp")         ' Create an Scp instance
...
objScp.CopyToRemote "Smalltoken.file", "."
WScript.Echo "LastError: " & objScp.LastError

ProtocolError property

Type:

String

Description:

If the last called method triggered a protocol error. This property will contain more information. The protocol error string is usually triggered and formulated into an error description at the remote host.

Example:

Set objScp           = CreateObject("AxNetwork.Scp")         ' Create an Scp instance
...
objScp.CopyToRemote "Smalltoken.file", "."
If objScp.LastError <> 0 Then
  WScript.Echo "Error: "  & objScp.LastError
  If objScp.ProtocolError <> "" Then
    WScript.Echo "Protocol error: " & objScp.ProtocolError    
  End If
End If

Host property

Type:

String

Description:

Specifies the host onto or from which the files will be copied.

Example:

Set objScp           = CreateObject("AxNetwork.Scp")         ' Create an Scp instance
objScp.Host          = "server01.domain.dom"
...
objScp.CopyToRemote "Smalltoken.file", "."

Port property

Type:

Number

Description:

TCP port number to identify a remote SSH/SCP daemon. If you don't specify the 'Port' property, port 22 (default SCP port) is used.

Example:

Set objScp           = CreateObject("AxNetwork.Scp")            ' Create an Scp instance
objScp.Host          = "server01.domain.dom"
objScp.Port          = 8022                                     ' Use port 8022 instead of 22
...
objScp.CopyToRemote "Smalltoken.file", "."

UserName property

Type:

String

Description:

Specifies the user name to use on the remote host. You must also specify either a Private Key to logon to the machine.

Example:

Set objScp           = CreateObject("AxNetwork.Scp")         ' Create an Scp instance
objScp.Host          = "server01.domain.dom"
objScp.UserName      = "mjohnson"
objScp.Password      = "topsecret"
objScp.CopyToRemote "Smalltoken.file", "."

Password property

Type:

String

Description:

Specifies the password to use on the remote host. If you do not use a password, you must use a Private Key to logon to the machine.

Example:

Set objScp           = CreateObject("AxNetwork.Scp")         ' Create an Scp instance
objScp.Host          = "server01.domain.dom"
objScp.UserName      = "mjohnson"
objScp.Password      = "topsecret"
objScp.CopyToRemote "Smalltoken.file", "."

PrivateKeyFile property

Type:

String

Description:

Specifies the private key file to use on the remote host. If you do not use a private key, you must use a Password to logon to the machine.

Example:

Set objScp           = CreateObject("AxNetwork.Scp")         ' Create an Scp instance
objScp.Host          = "server01.domain.dom"
objScp.UserName      = "mjohnson"
objScp.PrivateKeyFile= "c:\keys\root.ppk"
objScp.CopyToRemote "Smalltoken.file", "."

Recursive property

Type:

Boolean

Description:

Specifies whether to recursively copy directories. To copy a directory and its subdirectories the recursive property should be enabled.

Example:

Set objScp           = CreateObject("AxNetwork.Scp")         ' Create an Scp instance
...
objScp.Recursive = true
objScp.CopyToRemote "Smalltoken.file", "."

Compression property

Type:

Boolean

Description:

Specifies whether to use compression when copying files to the remote location. This will enable faster file transfer rates at the cost of a higher load on the server/client side.

Example:

Set objScp           = CreateObject("AxNetwork.Scp")         ' Create an Scp instance
...
objScp.Compression = true
objScp.CopyToRemote "Smalltoken.file", "."

AcceptHostKey property

Type:

Boolean

Description:

Specifies whether to accept an unknown or changed host key and add it to the registry. Leaving this property set to true when connecting to unknown or untrusted hosts poses a security risk.

Example:

Set objScp           = CreateObject("AxNetwork.Scp")         ' Create an Scp instance
...
objScp.AcceptHostKey = true
objScp.CopyToRemote "Smalltoken.file", "."

HostFingerprint property

Type:

String

Description:

The Scp 'CopyToRemote' and 'CopyToLocal' methods copy the host key fingerprint to this property

Example:

Set objScp           = CreateObject("AxNetwork.Scp")         ' Create an Scp instance
...
objScp.CopyToRemote "Smalltoken.file", "."
WScript.Echo "Host key fingerprint: " & objScp.HostFingerprint

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all operations will be written to this log file.

Example:

Set objScp           = CreateObject("AxNetwork.Scp")         ' Create an Scp instance
...
objScp.LogFile = "Log.txt"
objScp.CopyToRemote "Smalltoken.file", "."

16.3. Methods

Methods

Method Description
Clear Reset all properties to the default values
CopyToLocal Copy the files to the local host
CopyToRemote Copy the files to the remote host
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval
Activate Activate Software

Clear method

Description:

Reset all properties to the initial values.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objScp = CreateObject("AxNetwork.Scp")                      ' Create an Scp instance
...
objScp.CopyToRemote "Smalltoken.file", "."
objScp.Clear                                                    ' Resets properties
' Set new property values
...
objScp.CopyToRemote "Smalltoken.file", "."
objScp.Clear
...

CopyToLocal method

Description:

Copy a file or directory from the remote host specified in the 'Host' property to the local host.

Parameters:

  • The remote source path
  • The local destination path

Return value:

Always 0.

Example:

Set objScp = CreateObject("AxNetwork.Scp")                      ' Create an Scp instance
...
objScp.CopyToLocal "Smalltoken.file", "C:\test"

CopyToRemote method

Description:

Copy a file or directory from the local to the remote host specified in the 'Host' property.

Parameters:

  • The local source path
  • The remote destination path

Return value:

Always 0.

Example:

Set objScp = CreateObject("AxNetwork.Scp")                      ' Create an Scp instance
...
objScp.CopyToRemote "Smalltoken.file", "/var/www/upload"

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objScp           = CreateObject("AxNetwork.Scp")         ' Create an Scp instance
objScp.Host          = "192.168.1.10"
objScp.UserName      = "mjohnson"
objScp.Password      = "topsecret"
objScp.CopyToRemote "Smalltoken.file", "."
WScript.Echo "Error description: " & objScp.GetErrorDescription( objScp.LastError )

Sleep method

Description:

This method can be used in your script anywhere you want. Suspends the execution of the object for at least the specified interval.

  • The number of milliseconds to suspend

Return value:

Always 0.

Example:

Set objScp         = CreateObject( "AxNetwork.Scp" )         ' Create Scp object
...
objScp.Sleep 500

Activate method

Description:

This method activates the ActiveXperts Networking Component. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objScp         = CreateObject( "AxNetwork.Scp" )         ' Create Scp object
objScp.Activate "xyz", True     ' Substitute xyz by your own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call
' Activate each time the product is started

17. SFtp

17.1. Introduction

SFTP (Secure File Transfer Protocol) allows secure network file transfer over an insecure network, such as the Internet.

The Secure File Transfer Protocol is an extension to the SSH version 2.0 protocol. Most SSH server implementations will also allow for SFTP logins. SFTP is the secure successor to SFTP.

The ActiveXperts Networking Component SFTP implementation is based on the PuTTY implementation. With the ActiveXperts Networking Component SFtp object, you can login onto a remote machine running the SSH-2 daemon and has the SFTP service enabled.

There are two ways to authenticate: by using a password or by using a 'private key'. When using a password to authenticate it is required that the host private key is known to the system. If the hosts private key is unknown to the system or if it was changed since the last connection the Sftp object will return an error. To connect anyway and store the host key in the registry for future connections the 'AcceptHostKey' property can be set.

NOTE:

  • The ActiveXperts Networking Component SFtp object is not thread safe (A process can only have one active session). However, it is possible to run multiple processes with active sessions at once.

The following sample (in VBScript) changes to a 'test' directory, lists the directory and gets the 'Smalltoken.file' file on '192.168.1.10' by logging in using a password:

  ' Helper method to expand a string variable to a specified length
  Method Pad(ByRef Text, ByVal Length)
    Pad = Left(Text & Space(Length), Length)
  End Method

  ' Helper method to test and find the error description and exit
  Method test_lasterror()
    If objSFtp.LastError <> 0 Then
      WScript.Echo "Error "  & objSFtp.LastError
      If objSFtp.ProtocolError <> "" Then 
        WScript.Echo "Protocol error: " & objSFtp.ProtocolError
        WScript.Quit 1
      End If     
    End If
  End Method

  ' Connect to the host
  Set objSFtp           = CreateObject("AxNetwork.SFtp")        ' Create an SFtp instance
  objSFtp.Host          = "192.168.1.10"                        ' Hostname or IP address of 
                                                                ' remote UNIX/LINUX machine
  objSFtp.UserName      = "demo"                                ' Login as 'demo'
  objSFtp.Password      = "topsecret"                           ' Use a password to login

  WScript.Echo "Connect"
  objSFtp.Connect                                               ' Connect to the SFTP server
  test_lasterror

  ' Change directory
  objSFtp.ChangeDir "test"
  test_lasterror

  ' List directory contents
  Set f = objSFtp.FindFirstFile(".")
  test_lasterror
  While objSFtp.LastError = 0
    str = pad(f.name, 30) & pad(f.SizeKb & "KB", 10) & f.Date
    WScript.Echo str
    Set f = objSFtp.FindNextFile    
  WEnd

  ' Get smalltoken file
  objSFtp.GetFile "Smalltoken.file", "."
  test_lasterror

  objSFtp.Disconnect

  ' YES, command has completed
  WScript.Echo "Ready."

17.2. Properties

Properties

Property Type Read/Write Description
Name String Out Filename
IsDirectory Boolean Out Is the file a directory (True) or a file (False)
SizeBytes Number Out Size of file (in bytes)
SizeBytesHigh Number Out High part of he size of the file
SizeKB Number Out Size of file (in kilobytes)
SizeMB Number Out Size of file (in megabytes)
DateSeconds Number Out Last modification date of the file (in seconds after 1/1/1970)
Date String Out Last modification date of the file (as a friendly string)
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
LastError Number Out Result of the last called method
ProtocolError String Out If the last called method triggered a protocol error. This property will contain more information.
Host String In/Out Specifies the host to connect to
Port Number In/Out TCP port number to identify a (remote) SFTP daemon. Default: 22
UserName String In/Out Specifies the user name to use on the remote host
Password String In/Out Specifies the password to use on the remote host. If this property is left blank the 'PrivateKeyFile' property will be used to authenticate.
PrivateKeyFile String In/Out Specifies the private key file to logon to the remote host. If this property is left blank the 'password' property will be used to authenticate.
AcceptHostKey Boolean In/Out Specifies whether to accept an unknown or changed host key
HostFingerprint String Out The SFtp 'Connect' method copies the host key fingerprint to this property
Compression Boolean In/Out Specifies whether compression should be used while transferring files
LogFile String In/Out Log file; use it for troubleshooting purposes

Name property

Type:

String

Description:

File name.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )                  ' Create a new SFtp instance
...
objSFtp.Connect                                                 ' Connect to the SFTP server    
...
Set objSFtpFile = objSFtp.FindFirstFile(".")                    ' Get first file in the
                                                                ' directory
If( objSFtp.LastError = 0 ) Then                           
   WScript.Echo "Name   : " & objSFtpFile.Name                  
   WScript.Echo "IsDirectory  : " & objSFtpFile.IsDirectory      
   WScript.Echo "Size (in bytes) : " & objSFtpFile.SizeBytes   
   WScript.Echo "DateSeconds : " & objSFtpFile.DateSeconds     
   WScript.Echo "Date : " & objSFtpFile.Date                    ' Display last modified 
                                                                ' date/time as a friendly string
End If
...
objSFtp.Disconnect                                              ' Disconnect

IsDirectory property

Type:

Boolean

Description:

True indicates a directory, False indicates a file.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )                  ' Create a new SFtp instance
...
objSFtp.Connect                                                 ' Connect to the SFTP server    
...
Set objSFtpFile = objSFtp.FindFirstFile(".")                    ' Get first file in the 
                                                                ' directory
If( objSFtp.LastError = 0 ) Then                           
   WScript.Echo "Name   : " & objSFtpFile.Name                  
   WScript.Echo "IsDirectory  : " & objSFtpFile.IsDirectory      
   WScript.Echo "Size (in bytes) : " & objSFtpFile.SizeBytes   
   WScript.Echo "DateSeconds : " & objSFtpFile.DateSeconds     
   WScript.Echo "Date : " & objSFtpFile.Date                    ' Display last modified 
                                                                ' date/time as a friendly string
End If
...
objSFtp.Disconnect                                              ' Disconnect

SizeBytes property

Type:

Number

Description:

Size (in bytes) of the file. This field is actually the lower part of a 64Bit file size. The high part is located in the SizeBytesHigh property. Using only this property will be sufficient if files are not bigger than 4GB.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )                  ' Create a new SFtp instance
...
objSFtp.Connect                                                 ' Connect to the SFTP server    
...
Set objSFtpFile = objSFtp.FindFirstFile(".")                    ' Get first file in the 
                                                                ' directory
If( objSFtp.LastError = 0 ) Then                           
   WScript.Echo "Name   : " & objSFtpFile.Name                  
   WScript.Echo "IsDirectory  : " & objSFtpFile.IsDirectory       
   ' Calculate the size of the file.
   WScript.Echo "Size (in bytes) : " & _ 
     (objSFtpFile.SizeBytesHigh * (2^32) + bjFtpFile.SizeBytes)
   WScript.Echo "DateSeconds : " & objSFtpFile.DateSeconds     
   WScript.Echo "Date : " & objSFtpFile.Date                    ' Display last modified 
                                                                ' date/time as a friendly string
End If
...
objSFtp.Disconnect                                              ' Disconnect

SizeBytesHigh property

Type:

Number

Description:

The high 32bit part of he size of the file. The lower part is located in the SizeBytes property. If the filesize is smaller than 4GB this property will be 0.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )                  ' Create a new SFtp instance
...
objSFtp.Connect                                                 ' Connect to the SFTP server    
...
Set objSFtpFile = objSFtp.FindFirstFile(".")                    ' Get first file in the 
                                                                ' directory
If( objSFtp.LastError = 0 ) Then                           
   WScript.Echo "Name   : " & objSFtpFile.Name                  
   WScript.Echo "IsDirectory  : " & objSFtpFile.IsDirectory      
   ' Calculate the size of the file.
   WScript.Echo "Size (in bytes) : " & _
     (objSFtpFile.SizeBytesHigh * (2^32) + bjFtpFile.SizeBytes)
   WScript.Echo "DateSeconds : " & objSFtpFile.DateSeconds     
   WScript.Echo "Date : " & objSFtpFile.Date                    ' Display last modified 
                                                                ' date/time as a friendly string
End If
...
objSFtp.Disconnect                                              ' Disconnect

SizeKB property

Type:

Number

Description:

Contains the size in KB of the file when the file size is smaller than 4TB (4 Terabyte; 4 * 2^40 Bytes).

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )                  ' Create a new SFtp instance
...
objSFtp.Connect                                                 ' Connect to the SFTP server    
...
Set objSFtpFile = objSFtp.FindFirstFile(".")                    ' Get first file in the 
                                                                ' directory
If( objSFtp.LastError = 0 ) Then                           
   WScript.Echo "Name   : " & objSFtpFile.Name                  
   WScript.Echo "IsDirectory  : " & objSFtpFile.IsDirectory      
   WScript.Echo "Size (in KB) : " & objSFtpFile.SizeKB   
   WScript.Echo "DateSeconds : " & objSFtpFile.DateSeconds     
   WScript.Echo "Date : " & objSFtpFile.Date                    ' Display last modified 
                                                                ' date/time as a friendly string
End If
...
objSFtp.Disconnect                                              ' Disconnect

SizeMB property

Type:

Number

Description:

Contains the size in MB of the file when the file size is smaller than 4PB (4 Petabyte; 4 * 2^50 Bytes).

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )                  ' Create a new SFtp instance
...
objSFtp.Connect                                                 ' Connect to the SFTP server    
...
Set objSFtpFile = objSFtp.FindFirstFile(".")                    ' Get first file in the 
                                                                ' directory
If( objSFtp.LastError = 0 ) Then                           
   WScript.Echo "Name   : " & objSFtpFile.Name                  
   WScript.Echo "IsDirectory  : " & objSFtpFile.IsDirectory      
   WScript.Echo "Size (in MB) : " & objSFtpFile.SizeMB  
   WScript.Echo "DateSeconds : " & objSFtpFile.DateSeconds     
   WScript.Echo "Date : " & objSFtpFile.Date                    ' Display last modified 
                                                                ' date/time as a friendly string
End If
...
objSFtp.Disconnect                                              ' Disconnect

DateSeconds property

Type:

Number

Description:

last modified date and time of the file, in seconds after 1/1/1970.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )                  ' Create a new SFtp instance
...
objSFtp.Connect                                                 ' Connect to the SFTP server    
...
Set objSFtpFile = objSFtp.FindFirstFile(".")                    ' Get first file in the 
                                                                ' directory
If( objSFtp.LastError = 0 ) Then                           
   WScript.Echo "Name   : " & objSFtpFile.Name                  
   WScript.Echo "IsDirectory  : " & objSFtpFile.IsDirectory      
   WScript.Echo "Size (in bytes) : " & objSFtpFile.SizeBytes   
   WScript.Echo "DateSeconds : " & objSFtpFile.DateSeconds     
   WScript.Echo "Date : " & objSFtpFile.Date                    ' Display last modified 
                                                                ' date/time as a friendly string
End If
...
objSFtp.Disconnect                                              ' Disconnect

Date property

Type:

String

Description:

last modified date and time of the file, as a friendly string.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )                  ' Create a new SFtp instance
...
objSFtp.Connect                                                 ' Connect to the SFTP server    
...
Set objSFtpFile = objSFtp.FindFirstFile(".")                    ' Get first file in the 
                                                                ' directory
If( objSFtp.LastError = 0 ) Then                           
   WScript.Echo "Name   : " & objSFtpFile.Name                  
   WScript.Echo "IsDirectory  : " & objSFtpFile.IsDirectory      
   WScript.Echo "Size (in bytes) : " & objSFtpFile.SizeBytes   
   WScript.Echo "DateSeconds : " & objSFtpFile.DateSeconds     
   WScript.Echo "Date : " & objSFtpFile.Date                    ' Display last modified 
                                                                ' date/time as a friendly string
End If
...
objSFtp.Disconnect                                              ' Disconnect

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )            ' Create SFtp object
WScript.Echo  "Version: " & objSFtp.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )           ' Create SFtp object
WScript.Echo  "Build: " & objSFtp.Build

Module property

Return the module name of the Component.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )        ' Create new instance 
WScript.Echo  "Module: " & objSFtp.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )        ' Create instance
WScript.Echo "LicenseStatus: " & objSFtp.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objSFtp = CreateObject("AxNetwork.SFtp")          ' Create new instance
WScript.Echo "LicenseKey: " & objSFtp.LicenseKey

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objSFtp           = CreateObject("AxNetwork.SFtp")    ' Create an SFtp instance
...
objSFtp.Connect
WScript.Echo "LastError: " & objSFtp.LastError

ProtocolError property

Type:

String

Description:

If the last called method triggered a protocol error. This property will contain more information. The protocol error string is usually triggered and formulated into an error description at the remote host.

Example:

Set objSFtp           = CreateObject("AxNetwork.SFtp")    ' Create an SFtp instance
...
objSFtp.Connect
WScript.Echo "ProtocolError: " & objSFtp.ProtocolError

Host property

Type:

String

Description:

Specifies the host on which to run the command.

Example:

Set objSFtp           = CreateObject("AxNetwork.SFtp")    ' Create an SFtp instance
objSFtp.Host          = "server01.domain.dom"
...
objSFtp.Connect

Port property

Type:

Number

Description:

TCP port number to identify a remote SSH daemon. If you don't specify the 'Port' property, port 22 (default SSH port) is used.

Example:

Set objSFtp           = CreateObject("AxNetwork.SFtp")       ' Create an SFtp instance
objSFtp.Host          = "server01.domain.dom"
objSFtp.Port          = 8022                                 ' Use port 8022 instead of 22
...
objSFtp.Connect

UserName property

Type:

String

Description:

Specifies the user name to use on the remote host. You must also specify either a Password or Private Key to logon to the machine.

Example:

Set objSFtp           = CreateObject("AxNetwork.SFtp")    ' Create an SFtp instance
objSFtp.Host          = "server01.domain.dom"
objSFtp.UserName      = "mjohnson"
objSFtp.Password      = "topsecret"
objSFtp.Connect

Password property

Type:

String

Description:

Specifies the password to use on the remote host. If you do not use a password, you must use a Private Key to logon to the machine.

Example:

Set objSFtp           = CreateObject("AxNetwork.SFtp")    ' Create an SFtp instance
objSFtp.Host          = "server01.domain.dom"
objSFtp.UserName      = "mjohnson"
objSFtp.Password      = "topsecret"
objSFtp.Connect

PrivateKeyFile property

Type:

String

Description:

Specifies the private key file to use on the remote host. If you do not use a private key, you must use a Password to logon to the machine.

Example:

Set objSFtp           = CreateObject("AxNetwork.SFtp")    ' Create an SFtp instance
objSFtp.Host          = "server01.domain.dom"
objSFtp.UserName      = "mjohnson"
objSFtp.PrivateKeyFile= "c:\keys\root.ppk"
objSFtp.Connect

AcceptHostKey property

Type:

Boolean

Description:

Specifies whether to accept an unknown or changed host key and add it to the registry. Leaving this property set to true when connecting to unknown or untrusted hosts poses a security risk.

Example:

Set objSFtp           = CreateObject("AxNetwork.SFtp")    ' Create an SFtp instance
...
objSFtp.AcceptHostKey = true
objSFtp.Connect

HostFingerprint property

Type:

String

Description:

The SFtp 'Connect' method copies the host key fingerprint to this property

Example:

Set objSFtp           = CreateObject("AxNetwork.SFtp")    ' Create an SFtp instance
...
objSFtp.Connect
WScript.Echo "Host key fingerprint: " & objSFtp.HostFingerprint

Compression property

Type:

Boolean

Description:

Specifies whether to use compression when copying files to the remote location. This will enable faster file transfer rates at the cost of a higher load on the server/client side.

Example:

Set objSFtp           = CreateObject("AxNetwork.SFtp")    ' Create an SFtp instance
...
objSFtp.Compression = true
objSFtp.Connect

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all operations will be written to this log file.

Example:

Set objSFtp = CreateObject("AxNetwork.SFtp")    ' Create an SFtp instance
...
objSFtp.LogFile = "Log.txt"
objSFtp.Connect

17.3. Methods

Methods

Method Description
Clear Reset all properties to their default values
Connect Connect to a remote SFTP server
Disconnect Close the connection
GetCurrentDir Retrieve the current directory
ChangeDir Change directory
CreateDir Create directory
RenameDir Rename directory
DeleteDir Delete directory
FindFile Find a file in the current directory
FindFirstFile Find first file in the search pattern / directory
FindNextFile Find next file in the current directory
RenameFile Rename a file in the current directory
DeleteFile Delete a file in the current directory
GetFile Download (get) a file from the current directory
PutFile Upload (put) a file to the current directory
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval
Activate Suspends the execution of the object for at least the specified interval

Clear method

Description:

Resets all properties to the initial, default values.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )    ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                   ' Connect to host SFtp1
...
objSFtp.Disconnect                                ' Disconnect
objSFtp.Clear                                     ' Clear properties before connecting
                                                  ' to another SFTP server
objSFtp.Host = "SFtp2"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                   ' Connect to host SFtp2

Connect method

Description:

Call this method to connect to a remote SFTP server.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )    ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                   ' Connect to host SFtp1

If( objSFtp.LastError = 0 ) Then
   ...
   objSFtp.ChangeDir( "/pictures" )
   ...
   objSFtp.Disconnect
End If

Disconnect method

Description:

Call this method to close a connnection that was established using the Connect method.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )    ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                   ' Connect to host SFtp1
If( objSFtp.LastError = 0 ) Then
   ...
   objSFtp.Disconnect                             ' Close the session
End If

GetCurrentDir method

Description:

The directory string. If the method fails, an empty string is returned and the LastError property is set to a non-zero value indicating the reason for failing.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )         ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                        ' Connect to host SFtp1
If( objSFtp.LastError = 0 ) Then
   ...
   strCurrentDir = objSFtp.GetCurrentDir()             ' Retrieve current directory
   If( objSFtp.LastError = 0 ) Then
      WScript.Echo "Current Directory: " & strCurrentDir
   End If
   objSFtp.Disconnect                                  ' Close the session
End If

ChangeDir method

Description:

Change the current directory on the remote SFTP server. You can use a fully qualified directory name, or a plain directory name.

Parameters:

  • Directory name

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )         ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                        ' Connect to host SFtp1
If( objSFtp.LastError = 0 ) Then
   ...
   objSFtp.ChangeDir( "/pictures" )                    ' Change directory to: /pictures
   objSFtp.ChangeDir( "family" )                       ' Change directory to: /pictures/family
   ...
   objSFtp.ChangeDir( "/pictures/friends" )            ' Change directory to: /pictures/friends

   ...
   objSFtp.Disconnect                                  ' Close the session
End If

CreateDir method

Description:

Create a new directory on the remote SFTP server in the directory indicated by GetCurrentDir.

Parameters:

  • The directory to create. You can use a fully qualified directory name, or a plain directory name.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )         ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                        ' Connect to host SFtp1

If( objSFtp.LastError = 0 ) Then
   ...
   objSFtp.ChangeDir( "/pictures" )                    ' Change directory to: /pictures
   objSFtp.CreateDir( "family" )                       ' Create new directory 'family'
   ...
   objSFtp.Disconnect                                  ' Close the session
End If

RenameDir method

Description:

Rename directory.

Parameters:

  • Name of the directory to rename
  • New name of the directory

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )         ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                        ' Connect to host SFtp1
If( objSFtp.LastError = 0 ) Then
   ...
   objSFtp.RenameDir( "pictures", "images" )           ' Rename directory 'pictures' into 
                                                       ' images'
   ...
   objSFtp.Disconnect                                  ' Close the session
End If

DeleteDir method

Description:

Delete a directory.

Parameters:

  • The directory to delete. You can use a fully qualified directory name, or a plain directory name. Make sure that this directory is empty.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )         ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                        ' Connect to host SFtp1
If( objSFtp.LastError = 0 ) Then
   ...
   objSFtp.ChangeDir( "/pictures" )                    ' Change directory to: /pictures
   objSFtp.DeleteDir( "family" )                       ' Delete directory 'family'
   ...
   objSFtp.Disconnect                                  ' Close the session

End If

FindFile method

Description:

Find a file. You can use a plain filename (the file will then be retrieved from the current directory) or you can use a fully qualified filename.

Parameters:

  • Filename

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )         ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                        ' Connect to host SFtp1
If( objSFtp.LastError = 0 ) Then
  ' Find file using a fully qualified filename
   Set objSFtpFile1 = objSFtp.FindFile( "/pictures/picture1.jpg") 
   ...
   objSFtp.ChangeDir( "/pictures" )
   Set objSFtpFile2 = objSFtp.FindFile( "picture2.jpg") ' Find file using a plain filename
   objSFtp.Disconnect                                   ' Close the session

End If

FindFirstFile method

Description:

Iterate over all files and directories in the search pattern. The search pattern can either be a directory or a wildcard search. The 'FindFirstFile' method retrieves the first file/directory. You can call 'FindNextFile' until there are no more files/directories.

Parameters:

  • Search pattern

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )         ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                        ' Connect to host SFtp1
If( objSFtp.LastError = 0 ) Then
   Set objSFtpFile = objSFtp.FindFirstFile(".")
   While( objSFtp.LastError = 0 )
       WScript.Echo "File: " & objSFtpFile.Name        ' Display filename 
                                                       ' (or directoryname)
       Set objSFtpFile = objSFtp.FindNextFile()
   WEnd
   objSFtp.Disconnect                                  ' Close the session
End If

FindNextFile method

Description:

Iterate over all files and directories in the search pattern. The search pattern can either be a directory or a wildcard search. The 'FindFirstFile' method retrieves the first file/directory. You can call 'FindNextFile' until there are no more files/directories.

Parameters:

  • Search pattern

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )                  ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                                 ' Connect to host SFtp1
If( objSFtp.LastError = 0 ) Then
   Set objSFtpFile = objSFtp.FindFirstFile(".")
   While( objSFtp.LastError = 0 )
       WScript.Echo "File: " & objSFtpFile.Name                 ' Display filename (or dir.name)
       Set objSFtpFile = objSFtp.FindNextFile()
   WEnd
   objSFtp.Disconnect                                           ' Close the session
End If

RenameFile method

Description:

Rename file.

Parameters:

  • Name of the file to rename
  • New name of the file

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )        ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                       ' Connect to host SFtp1
If( objSFtp.LastError = 0 ) Then
   ...
   objSFtp.ChangeDir( "/pictures" )                   ' Change directory to: /pictures
   objSFtp.RenameFile( "old.jpg", "new.jpg" )         ' Rename 'old.jpg' into 'new.jpg'
   ...
   objSFtp.Disconnect                                 ' Close the session

End If

DeleteFile method

Description:

Iterate over all files and directories in the search pattern. The search pattern can either be a directory or a wildcard search. The 'FindFirstFile' method retrieves the first file/directory. You can call 'FindNextFile' until there are no more files/directories.

Parameters:

  • Search pattern

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )                  ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                                 ' Connect to host SFtp1
If( objSFtp.LastError = 0 ) Then
   Set objSFtpFile = objSFtp.FindFirstFile(".")
   While( objSFtp.LastError = 0 )
       WScript.Echo "File: " & objSFtpFile.Name                 ' Display filename (or dir.name)
       Set objSFtpFile = objSFtp.FindNextFile()
   WEnd
   objSFtp.Disconnect                                           ' Close the session
End If

GetFile method

Description:

Download a file from the SFTP server.

Parameters:

  • Name of the file on the remote machine. This can be a fully qualified filename, or a plain filename. When using a plain filename, make sure you have changed the directory using ChangeDir.
  • Name of the file on the local machine. This can be a fully qualified filename, or a plain filename. When using a plain filename, the file will be stored in the current Windows directory.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )                  ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                                 ' Connect to host SFtp1

If( objSFtp.LastError = 0 ) Then
   ...
   objSFtp.ChangeDir( "/pictures" )                             ' Change directory to: /pictures
   objSFtp.GetFile( "pict1.jpg", "c:\pictures\file1.jpg" )      ' Download 'pict1.jpg'
   ...
   objSFtp.ChangeDir( "/" )                                     ' Change directory to: /
   objSFtp.GetFile( "/pictures/pict1.jpg", "c:\pict\file1.jpg" )' Download 'pict2.jpg'
   objSFtp.Disconnect                                           ' Close the session

End If

PutFile method

Description:

Upload a file to the SFTP server.

Parameters:

  • Name of the file on the local machine. This can be a fully qualified filename, or a plain filename. When using a plain filename, the file will be uploaded from the current Windows directory
  • Name of the file on the remote machine. This can be a fully qualified filename, or a plain filename. When using a plain filename, make sure you have changed the directory using ChangeDir.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )                  ' Create a new SFtp instance
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                                 ' Connect to host SFtp1

If( objSFtp.LastError = 0 ) Then
   ...
   objSFtp.ChangeDir( "/pictures" )                             ' Change directory to: /pictures
   objSFtp.PutFile( "c:\pictures\pict3.jpg", "/pictures/pict3.jpg" )' Upload 'pict3.jpg'
   ...
   objSFtp.PutFile( "c:\pictures\pict4.jpg", "/pictures/pict4.jpg" )' Upload 'pict4.jpg'
End If

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code.

Return value:

The error description that is associated with the given error code.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )                  ' Create a new SFtp instance
...
objSFtp.Host = "SFtp1"
objSFtp.UserName = "demo"
objSFtp.Password = "demo"
objSFtp.Connect                                                 ' Connect to host SFtp1

WScript.Echo "LastError: " & objSFtp.LastError
WScript.Echo "Error description: " & objSFtp.GetErrorDescription( objSFtp.LastError )
...

Sleep method

Description:

This method can be used in your script anywhere you want; Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to hold.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp       = CreateObject( "AxNetwork.SFtp" )         ' Create Ftperver object
...
objSFtp.Sleep 50

Activate method

Description:

This method activates the ActiveXperts Networking Component. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSFtp = CreateObject( "AxNetwork.SFtp" )        ' Create SFtp object
objSFtp.Activate "xyz", True                          ' Substitute xyz by your 
                                                      ' own registrationkey

' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call 
' Activate each time the product is started.

18. SnmpManager

18.1. Introduction

SNMP stands for Simple Network Management Protocol. Simple Network Management Protocol is a set of standards for communication with devices connected to a TCP/IP network. It is often used to communicate with hubs and switches.

Since it was developed in 1988, the Simple Network Managment Protocol has become the de facto standard for network management. Because it is a simple solution, requiring little code to implement, vendors can easily build SNMP agents to their products. SNMP is extensible, allowing vendors to easily add network management methods to their existing products. SNMP also separates the managment architecture from the architecture of the hardware devices, which broadens the base of multivendor support. Perhaps most important, unlike other so-called standards, SNMP is not a mere paper specification, but an implementation that is widely available today.

The ActiveXperts Networking Component Snmp object enables you to add SNMP v1, SNMP v2c and SNMP v3 functionality to your programs.
Here is a small example (in VBScript) to show how to use the SnmpManager object:

    
Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager 
                                                                ' instance
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object

objSnmpManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V2c' Set SNMP protocol version 
                                                                ' before opening SNMP session
objSnmpManager.Open "192.168.1.10", "public"                    ' Open session to remote 
                                                                ' Snmp agent
If( objSnmpManager.LastError <> 0 ) Then
  WScript.Echo "Error " & objSnmpManager.LastError
Else
  Set objSnmpObject = objSnmpManager.Get( "system.sysName.0"  )     ' Retrieve Object 
                                                                ' Identifier value 
  If( objSnmpManager.LastError <> 0 ) Then
    WScript.Echo "Error " & objSnmpManager.LastError
  Else
    WScript.Echo "OID : "   & objSnmpObject.Value               ' Print Snmp data
    WScript.Echo "  Value:" & objSnmpObject.Value               ' Print Snmp data
    WScript.Echo "  Type:"  & objSnmpObject.Type                ' Print Snmp data
  End If
  objSnmpManager.Close()                                        ' Close session
End If

18.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
Timeout Number In/Out Number of millseconds before an SNMP operation will time out
ProtocolVersion Number In/Out Specifies the SNMP protocol version to use
AuthProtocol Number In/Out Specifies the authentication protocol to be used in SNMPv3
PrivProtocol Number In/Out Specifies the privacy protocol to be used in SNMPv3
AuthUsername String In/Out Specifies the username to be used in SNMPv3 authentication
AuthPassword String In/Out Specifies the password to be used in SNMPv3 authentication
PrivPassword String In/Out Specifies the password to be used in SNMPv3 privacy
Context String In/Out Specifies the context to be used in SNMPv3
LastError Number In/Out Result of the last called method

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objSnmpManager = CreateObject("AxNetwork.SnmpManager")   ' Create a new SnmpManager inst.
WScript.Echo  "Version: " & objSnmpManager.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objSnmpManager = CreateObject("AxNetwork.SnmpManager")   ' Create a new SnmpManager inst.
WScript.Echo  "Build: " & objSnmpManager.Build

Module property

Return the module name of the Component.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )        ' Create new instance 
WScript.Echo  "Module: " & objSnmpManager.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )        ' Create instance
WScript.Echo "LicenseStatus: " & objSnmpManager.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objSnmpManager = CreateObject("AxNetwork.SnmpManager")          ' Create new instance
WScript.Echo "LicenseKey: " & objSnmpManager.LicenseKey

Timeout property

Type:

Number

Description:

Specifies the number of milliseconds before an SNMP operation times out. Default value: 5000 milliseconds.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager inst.
objSnmpManager.Initialize                                       ' Initialize Snmp
...
objSnmpManager.Timeout = 5000                                   ' Allow 5000 msecs until an 
                                                                ' SNMP operation times out
objSnmpManager.Open "192.168.1.10", "public"
...

ProtocolVersion property

Type:

Number

Description:

Specifies the SNMP protocol version to use: nwSNMP_VERSION_V1, nwSNMP_VERSION_V2C or nwSNMP_VERSION_V3. The default is version nwSNMP_VERSION_V2C.
Note: To set the protocol version, you must set the 'ProtocolVersion' property before calling the Open method.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager inst.
Set objConstants = CreateObject( "AxNetwork.NwConstants" )      ' Create constants object
objSnmpManager.Initialize                                       ' Initialize Snmp
...
objSnmpManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V1 ' Use SNMP v1 protocol version. 
                                                                ' Set it before calling 'Open'
objSnmpManager.Open "192.168.1.10", "public"
...

AuthProtocol property

Type:

Number

Description:

Specifies the SNMPv3 authentication protocol to use: nwSNMP_AUTH_SHA1 or nwSNMP_AUTH_MD5. The default protocol is nwSNMP_AUTH_SHA1.

This property is only used when the 'ProtocolVersion' property is set to nwSNMP_VERSION_V3.

Note: To set the authentication protocol, you must set the 'AuthProtocol' property before calling the Open method.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a SnmpManager inst.
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object

objSnmpManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V3 ' Use SNMPv3
							
objSnmpManager.AuthProtocol    = objConstants.nwSNMP_AUTH_SHA1  ' Use SHA1 authentication
objSnmpManager.AuthUsername    = "user"                         ' Set SNMPv3 user
objSnmpManager.AuthPassword    = "password1"                    ' Set SNMPv3 password

objSnmpManager.Open "192.168.1.10", "public"
...

PrivProtocol property

Type:

Number

Description:

Specifies the SNMPv3 privacy protocol to use: nwSNMP_AUTH_SHA1 or nwSNMP_AUTH_MD5. The default protocol is nwSNMP_AUTH_SHA1.

This property is only used when the 'ProtocolVersion' property is set to nwSNMP_VERSION_V3.

Note: To set the authentication protocol, you must set the 'PrivProtocol' property before calling the Open method.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a SnmpManager inst.
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object

objSnmpManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V3 ' Use SNMPv3
							
objSnmpManager.AuthProtocol    = objConstants.nwSNMP_AUTH_SHA1  ' Use SHA1 authentication
objSnmpManager.AuthUsername    = "user"                         ' Set SNMPv3 user
objSnmpManager.AuthPassword    = "password1"                    ' Set SNMPv3 password

objSnmpManager.Open "192.168.1.10", "public"
...

AuthUsername property

Type:

Number

Description:

Specifies the username to be used in SNMPv3 authentication. A SNMPv3 username has to be at least 8 characters long. A username is required in SNMPv3, even if no authentication is used.

This property is only used when the 'ProtocolVersion' property is set to nwSNMP_VERSION_V3.

Note: To set the authentication username, you must set the 'AuthUsername' property before calling the Open method.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a SnmpManager inst.
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object

objSnmpManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V3 ' Use SNMPv3
							
objSnmpManager.AuthProtocol    = objConstants.nwSNMP_AUTH_SHA1  ' Use SHA1 authentication
objSnmpManager.AuthUsername    = "user"                         ' Set SNMPv3 user
objSnmpManager.AuthPassword    = "password1"                    ' Set SNMPv3 password

objSnmpManager.Open "192.168.1.10", "public"
...

AuthPassword property

Type:

Number

Description:

Specifies the password to be used in SNMPv3 authentication. A SNMPv3 password has to be at least 8 characters long. If no password is specified, SNMPv3 authentication is turned off. This property is only used when the 'ProtocolVersion' property is set to nwSNMP_VERSION_V3.

Note: To set the authentication password, you must set the 'AuthPassword' property before calling the Open method.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a SnmpManager inst.
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object

objSnmpManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V3 ' Use SNMPv3
							
objSnmpManager.AuthProtocol    = objConstants.nwSNMP_AUTH_MD5   ' Use MD5 authentication
objSnmpManager.AuthUsername    = "user"                         ' Set SNMPv3 user
objSnmpManager.AuthPassword    = "password1"                    ' Set SNMPv3 password

objSnmpManager.Open "192.168.1.10", "public"
...

PrivPassword property

Type:

Number

Description:

Specifies the password to be used in SNMPv3 privacy. A SNMPv3 password has to be at least 8 characters long. If no password is specified, SNMPv3 authentication is turned off. This property is only used when the 'ProtocolVersion' property is set to nwSNMP_VERSION_V3.

Note: To set the privacy password, you must set the 'PrivPassword' property before calling the Open method.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a SnmpManager inst.
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object

objSnmpManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V3 ' Use SNMPv3
							
objSnmpManager.PrivProtocol    = objConstants.nwSNMP_PRIV_DES   ' Use DES encryption
objSnmpManager.AuthUsername    = "user"                         ' Set SNMPv3 user
objSnmpManager.PrivPassword    = "password2"                    ' Set SNMPv3 password

objSnmpManager.Open "192.168.1.10", "public"
...

Context property

Type:

Number

Description:

Specifies the context to be used in SNMPv3 PDU's. This parameters is optional.

Note: To set context, you must set the 'Context' property before calling the Open method.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a SnmpManager inst.
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object

objSnmpManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V3 ' Use SNMPv3
							
objSnmpManager.AuthProtocol    = objConstants.nwSNMP_AUTH_SHA1  ' Use SHA1 authentication
objSnmpManager.AuthUsername    = "user"                         ' Set SNMPv3 user
objSnmpManager.AuthPassword    = "password1"                    ' Set SNMPv3 password
objSnmpManager.Context         = "SNMP"                         ' Set SNMPv3 context

objSnmpManager.Open "192.168.1.10", "public"
...

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager inst.
objSnmpManager.Initialize                                       ' Initialize Snmp
...
objSnmpManager.Open "192.168.1.10", "public"
WScript.Echo "LastError: " & objSnmpManager.LastError
...

18.3. Methods

Methods

Method Description
Clear Reset all properties to their default values
Open Open an SNMP session to a remote host, using a specified community string
Close Close the existing SNMP session
Get Get the Snmp Data object of the specified OID (Object ID) from the (remote) SNMP agent
GetNext Retrieve the next Snmp Data object from a table or list within an SNMP agent.
Set Assign a new value to the specified OID (Object ID) on the (remote) SNMP agent
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval
Activate Activate Software

Clear method

Description:

Resets all properties to the initial, default values. Use this method when you are opening/closing SNMP sessions multiple times.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager 
                                                                ' instance
objSnmpManager.Open "192.168.1.100", "public"
If( objSnmpManager.LastError = 0 )
  ...
  objSnmpManager.Close
End If
objSnmpManager.Clear
objSnmpManager.Open "192.168.1.200", "public"
If( objSnmpManager.LastError = 0 )
  ...
  objSnmpManager.Close
End If

Open method

Description:

Opens an SNMP session to a remote host, using a specified community string.

Parameters:

  • The SNMP agent, i.e. hostname or IP address of the computer running the SNMP agent software;
  • The community string; the default community name for most SNMP agents is 'public';
  • Port (optional) - UDP port number to identify a (remote) SNMP agent. If not specified, default port 161 is used.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager 
                                                                ' instance
objSnmpManager.Open "192.168.1.100", "public"
If( objSnmpManager.LastError = 0 )
  WScript.Echo  "Yes, session successfully established"
  ...
  objSnmpManager.Close
End If
...

Close method

Description:

Close an SNMP session that was opened by the Open method.

Parameters:

  • The SNMP agent, i.e. hostname or IP address of the computer running the SNMP agent software;
  • The community string; the default community name for most SNMP agents is 'public'.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager 
                                                                ' instance
objSnmpManager.Open "192.168.1.100", "public"
If( objSnmpManager.LastError = 0 )
  WScript.Echo  "Yes, session successfully established"
  ...
  objSnmpManager.Close
End If
...

Get method

Description:

Get the value and type of the specified OID (Object ID) from the (remote) SNMP agent. You must first open a session to the remote agent using the Open method. The return value is an SnmpObject object.

Parameters:

  • OID - The Object Identifier. This can be either an alphanumeric string (like 'system.sysName.0') or a numeric string with numbers separated by dots (like '.1.3.6.1.2.1.1.5.0')

Return value:

The LastError property contains the error code.

Example:

Set objSnmpManager = CreateObject("AxNetwork.SnmpManager")      ' Create a new SnmpManager 
                                                                ' instance
objSnmpManager.Initialize                                       ' Initialize Snmp
...
objSnmpManager.Open "192.168.1.100", "public"
If( objSnmpManager.LastError = 0 )
  Set objSnmpObject = objSnmpManager.Get( "system.sysName.0" )  ' Get SnmpObject object
  If( objSnmpManager.LastError = 0 )
    WScript.Echo "Type:  " & objSnmpObject.Type
    WScript.Echo "Value: " & objSnmpObject.Value
  End If
  Set objSnmpObject = objSnmpManager.Get(".1.3.6.1.2.1.1.5.0")  ' Get another SnmpObject 
                                                                ' object
  If( objSnmpManager.LastError = 0 )
    WScript.Echo "Type:  " & objSnmpObject.Type
    WScript.Echo "Value: " & objSnmpObject.Value
  End If
  objSnmpManager.Close
End If
...

GetNext method

Description:

Retrieve the next OID from a table or list within an SNMP agent. This method should only be called after a successfull Get method call.

Parameters:

  • None

Return value:

An SnmpObject object. If the method fails, the LastError property contains the error code.

Example (SNMP walker):

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new Snmp instance
objSnmpManager.Initialize                                       ' Initialize Snmp
...
objSnmpManager.Open "192.168.1.100", "public"
If( objSnmpManager.LastError = 0 )
  Set objSnmpObject = objSnmpManager.Get( "system.sysName.0" )  ' Get SnmpObject object
  While( objSnmpManager.LastError = 0 )
    WScript.Echo "Type:  " & objSnmpObject.Type
    WScript.Echo "Value: " & objSnmpObject.Value

    Set objSnmpObject = objSnmpManager.GetNext()                ' Get next SnmpObject object
  End If
  objSnmpManager.Close
End If
...

Set method

Description:

Set value and type of the SnmpObject object on the (remote) SNMP agent. You must first open a session to the remote agent using the Open method.

Parameters:

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager 
                                                                ' instance
Set objSnmpObject  = CreateObject( "AxNetwork.SnmpObject" )     ' Create a new SnmpObject 
                                                                ' instance
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
objSnmpManager.Open "192.168.1.100", "public"
If( objSnmpManager.LastError = 0 )
  objSnmpObject.Clear()                                         ' Clear all properties, a 
                                                                ' good practise
  objSnmpObject.OID   = ".1.3.1.2.3.4.5.6.7.8"                  ' Specify object properties
  objSnmpObject.Type  = objConstants.nwSNMP_TYPE_IPADDRESS      ' Specify object properties
  objSnmpObject.Value = "10.1.1.10"                             ' Specify object properties
  objSnmpManager.Set( objSnmpObject )                           ' Call Set
  objSnmpManager.Close
End If
...

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager 
                                                                ' instance
...
objSnmpManager.Open "www.thisdoesnotexist.com", "public"
WScript.Echo "LastError: " & objSnmpManager.LastError
WScript.Echo "Error description: " & objSnmpManager.GetErrorDescription( objSnmpManager.LastError )
...

Sleep method

Description:

This method can be used in your script anywhere you want; Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to hold.

Return value:

Always 0.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" ) ' Create SnmpManager object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" ) ' Create constants object
...
objSnmpManager.Sleep 500

Activate method

Description:

This method activates the ActiveXperts Networking Component. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" ) ' Create SnmpManager object
objSnmpManager.Activate "xyz", True       ' Substitute xyz by your own registrationkey
                                ' Pass True to make the activation persistent, so you need to call
                                ' Activate only once. If you pass False, you need to call 
                                ' Activate each time the product is started.

19. SnmpObject

19.1. Introduction

19.2. Properties

Properties

Property Type Read/Write Description
OID String In/Out SNMP Object Identifier
Type Number In/Out SNMP data type
Value String In/Out SNMP data value
RequestID Number Out SNMP node ID
Name String Out SNMP object name
Path String Out SNMP full path object name
NodeID String Out SNMP node ID
ParentNodeID Number Out n/a
Syntax String Out SNMP OID syntax
Access Number Out SNMP OID Access
Status Number Out SNMP OID Status

OID property

Type:

String

Description:

SNMP Object Identifier.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager 
                                                                ' instance
...
Set objSnmpObject = objSnmpManager.Get( ".1.3.1.1.1.1" )        ' Get an SnmpObject object
WScript.Echo "OID   : " & objSnmpObject.OID                     ' Print OID
WScript.Echo "Type  : " & objSnmpObject.Type                    ' Print Type
WScript.Echo "Value : " & objSnmpObject.Value                   ' Print Value

Type property

Type:

Number

Description:

SNMP data type. For an overview of all SNMP data types, check the SNMP Data Types section.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager 
                                                                ' instance
...
Set objSnmpObject = objSnmpManager.Get( ".1.3.1.1.1.1" )        ' Get an SnmpObject object
WScript.Echo "OID   : " & objSnmpObject.OID                     ' Print OID
WScript.Echo "Type  : " & objSnmpObject.Type                    ' Print Type
WScript.Echo "Value : " & objSnmpObject.Value                   ' Print Value

Value property

Type:

Variant

Description:

SNMP value as a string. The value type is indicated by the Type property.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager 
                                                                ' instance
...
Set objSnmpObject = objSnmpManager.Get( ".1.3.1.1.1.1" )        ' Get an SnmpObject object
WScript.Echo "OID   : " & objSnmpObject.OID                     ' Print OID
WScript.Echo "Type  : " & objSnmpObject.Type                    ' Print Type
WScript.Echo "Value : " & objSnmpObject.Value                   ' Print Value
WScript.Echo "RequestID : " & objSnmpObject.RequestID           ' Print RequestID

RequestID property

Type:

Number

Description:

This property indicates the request ID of the OID.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager 
                                                                ' instance
...
Set objSnmpObject = objSnmpManager.Get( ".1.3.1.1.1.1" )        ' Get an SnmpObject object
WScript.Echo "OID   : " & objSnmpObject.OID                     ' Print OID
WScript.Echo "Type  : " & objSnmpObject.Type                    ' Print Type
WScript.Echo "Value : " & objSnmpObject.Value                   ' Print Value
WScript.Echo "RequestID : " & objSnmpObject.RequestID           ' Print RequestID

Name property

MIB properties (only set when used with the SnmpMibBrowser object)

Type:

String

Description:

'Name' is only set when the SnmpObject is returned by SnmpMibBrowser's Get or GetNext method. This property indicates the plain name of the object.

Example:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )     ' Create a new SnmpMibBrowser 
                                                                ' instance 
objSnmpMib.LoadMibFile( "c:\windows\system32\hostmib.mib" )     ' Load MIB file
Set objSnmp = objSnmpMIB.Get("iso")                             ' Get first OID
WScript.Echo "OID Name: " & objSnmp.Name                        ' Display Name

Path property

MIB properties (only set when used with the SnmpMibBrowser object)

Type:

String

Description:

'Path' is only set when the SnmpObject is returned by SnmpMibBrowser's Get or GetNext method. This property indicates the full-path name of the object.

Example:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )     ' Create a new SnmpMibBrowser 
                                                                ' instance 
objSnmpMib.LoadMibFile( "c:\windows\system32\hostmib.mib" )     ' Load MIB file
Set objSnmp = objSnmpMIB.Get("iso")                             ' Get first OID
WScript.Echo "OID Name: " & objSnmp.Name                        ' Display Name
WScript.Echo "OID Full-path Name: " & objSnmp.Path              ' Display Full-patt Name

NodeID property

MIB properties (only set when used with the SnmpMibBrowser object)

Type:

Number

Description:

'NodeID' is only set when the SnmpObject is returned by SnmpMibBrowser's Get or GetNext method.
This property indicates the node ID of the OID.

Example:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )     ' Create a new SnmpMibBrowser 
                                                                ' instance 
objSnmpMib.LoadMibFile( "c:\windows\system32\hostmib.mib" )     ' Load MIB file
Set objSnmp = objSnmpMIB.Get("iso")                             ' Get first OID
WScript.Echo "OID Name: " & objSnmp.Name                        ' Display Name
WScript.Echo "NodeID: " & objSnmp.NodeID                        ' Display NodeID

ParentNodeID property

MIB properties (only set when used with the SnmpMibBrowser object)

Type:

Number

Description:

'ParentNodeID' is only set when the SnmpObject is returned by SnmpMibBrowser's Get or GetNext method. This property indicates the parent node ID of the OID.

Example:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )     ' Create a new SnmpMibBrowser 
                                                                ' instance 
objSnmpMib.LoadMibFile( "c:\windows\system32\hostmib.mib" )     ' Load MIB file
Set objSnmp = objSnmpMIB.Get("iso")                             ' Get first OID
WScript.Echo "OID Name: " & objSnmp.Name                        ' Display Name
WScript.Echo "ParentNodeID: " & objSnmp.ParentNodeID            ' Display parent NodeID

Syntax property

MIB properties (only set when used with the SnmpMibBrowser object)

Type:

Number

Description:

'Syntax' is only set when the SnmpObject is returned by SnmpMibBrowser's Get or GetNext method. This property indicates the syntax of the object.

Example:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )     ' Create a new SnmpMibBrowser
                                                                ' instance 
objSnmpMib.LoadMibFile( "c:\windows\system32\hostmib.mib" )     ' Load MIB file
Set objSnmp = objSnmpMIB.Get("iso")                             ' Get first OID
WScript.Echo "OID Name: " & objSnmp.Name                        ' Display Name
WScript.Echo "Syntax: " & objSnmp.Syntax                        ' Display Syntax

Access property

MIB properties (only set when used with the SnmpMibBrowser object)

Type:

Number

Description:

'Access' is only set when the SnmpObject is returned by SnmpMibBrowser's Get or GetNext method. Click here for a list of valid Access values

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager 
                                                                ' instance
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

objSnmpManager.Server  = "ns1.interstroom.nl"                   ' Apply queries to DNS 
                                                                ' server ns1.interstroom.nl    
objSnmpManager.Lookup "activexperts.com", _
  objConstants.nwDNS_TYPE_SOA                                   ' Lookup SOA record for 
                                                                ' activexperts.com    
If( objSnmpManager.LastError <> 0 ) Then
    WScript.Quit
End If
Set objSnmpObject = objSnmpManager.GetFirstRecord               ' Get first DNS record 
If( objSnmpManager.LastError = 0 ) Then                                
    WScript.Echo "Name: " & objSnmpObject.Name                  ' Display all SOA record fields 
    WScript.Echo "NameServer: " & objSnmpObject.NameServer
    WScript.Echo "MailBox: " & objSnmpObject.MailBox
    WScript.Echo "NameServer: " & objSnmpObject.NameServer
    WScript.Echo "SerialNumber: " & objSnmpObject.SerialNumber
    WScript.Echo "RefreshInterval: " & objSnmpObject.RefreshInterval
    WScript.Echo "RetryInterval: " & objSnmpObject.RetryInterval
    WScript.Echo "ExpirationLimit: " & objSnmpObject.ExpirationLimit
    WScript.Echo "MinimumTTL: " & objSnmpObject.MinimumTTL
End If

Status property

MIB properties (only set when used with the SnmpMibBrowser object)

Type:

Number

Description:

'Status' is only set when the SnmpObject is returned by SnmpMibBrowser's Get or GetNext method. Click here for a list of valid Status values

Example:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )     ' Create a new SnmpMibBrowser 
                                                                ' instance 
objSnmpMib.LoadMibFile( "c:\windows\system32\hostmib.mib" )     ' Load MIB file
Set objSnmp = objSnmpMIB.Get("iso")                             ' Get first OID
WScript.Echo "OID Name: " & objSnmp.Name                        ' Display Name
WScript.Echo "Status: " & objSnmp.Status                        ' Display Status

19.3. Methods

Methods

Method Description
Clear Reset all properties
GetErrorDescription Get the description of the given error

Clear method

Description:

Clears all properties of the object.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpManager" )    ' Create a new SnmpManager 
                                                                ' instance
Set objSnmpObject  = CreateObject( "AxNetwork.SnmpObject" )     ' Create a new SnmpObject 
                                                                ' instance
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
objSnmpObject.Clear()                                           ' Clear all properties
objSnmpObject.OID    = "1.3.1.2.3.4.5"
objSnmpObject.Type   = objConstants.nwSNMP_TYPE_IPADDRESS
objSnmpObject.Value  = "10.1.1.10"
objSnmpManager.Set( objSnmpObject )                             ' SNMP Set

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error - the numeric error code

Return value:

The error description that is associated with the specified error code.

Example:

' Create a new SnmpTrapManager instance
Set objSnmpObject = CreateObject("AxNetwork.SnmpTrapManager")
objSnmpObject.Initialize                                       ' Initialize SNMP
WScript.Echo "LastError: " & objSnmpObject.LastError
WScript.Echo "Error description: " & objSnmpObject.GetErrorDescription( objSnmpObject.LastError )

20. SnmpTrapManager

20.1. Introduction

An SNMP trap is simply a notification message that is transmitted by an SNMP-managed device whenever it has something of interest to report. Traps can be thought of as event messages, similar to the events in the Windows event logs. Traps, like regular SNMP variables, are defined in MIB (Management Information Base) files. They are defined as a set of SNMP variables contained in (or referenced by) an OID (Object Identifier). If you look at the system directory on any Windows machine that has SNMP installed, you will find several MIB files. (They have the extension ".mib".) If you look through them you will see the variables that are supported on that machine.
ActiveXperts Networking Component has interfaces for sending and receiving SNMP traps.

The SnmpTrapManager object provides properties and methods for sending and receiving SNMP traps.

Here is a small example (in VBScript) to show how to send an SNMP trap using the SnmpTrapManager object:

    
' Create a new SnmpTrapManager instance
Set objSnmpTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" ) 
Set objSnmpTrap   = CreateObject( "AxNetwork.SnmpTrap" )        ' Create a new SnmpTrap 
                                                                ' instance
Set objSnmpObject = CreateObject( "AxNetwork.SnmpObject" )      ' Create a new SnmpObject 
                                                                ' instance
Set objConstants  = CreateObject( "AxNetwork.NwConstants" )     ' Create a new Constants 
                                                                ' instance 
' Set trap properties
objSnmpTrap.Clear()
objSnmpTrap.Host	  = "server06"
objSnmpTrap.Community = "public"

' Add a variable to the trap
objSnmpObject.Clear()                                           ' Clear trap object
objSnmpObject.OID   = ".1.3.6.1.2.1.1.5.0"                      ' Set trap properties
objSnmpObject.Type  = objConstants.nwSNMP_TYPE_IPADDRESS        ' Set trap properties
objSnmpObject.Value = "10.0.0.1"                                ' Set trap properties 
objSnmpTrap.AddObject objSnmpObject                             ' Add the trap to the queue

' Add another variable to the trap
objSnmpObject.Clear()                                           ' Clear trap object
objSnmpObject.OID   = ".1.3.6.1.2.1.1.5.1"                      ' Set trap properties
objSnmpObject.Type  = objConstants.nwSNMP_TYPE_OCTETSTRING      ' Set trap properties
objSnmpObject.Value = "One two three"                           ' Set trap properties 
objSnmpTrap.AddObject objSnmpObject                             ' Add the trap to the queue

objSnmpTrapManager.Send objSnmpTrap                             ' Send trap
WScript.Echo "Send, result: " & objSnmpTrapManager.LastError    ' Display the result

A small example (in VBScript) to show how to receive SNMP traps using the SnmpTrapManager object. The sample listens for incoming traps and displays the results:

    
' Create a new SnmpTrapManager instance
Set objSnmpTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" ) 

objSnmpManager.EngineId        = "80001F8880012C000059354F50"   ' Set SNMPv3 engine (optional)

objSnmpTrapManager.StartListening "public"                      ' Start listening now
If( objSnmpTrapManager.LastError <> 0 ) Then
WScript.Quit
End If

Set objSnmpTrap = objSnmpTrapManager.GetFirstTrap               ' Get trap

While( objSnmpTrapManager.LastError = 0 )
WScript.Echo "Trap from      : " & objSnmpTrap.Host
WScript.Echo " Community     : " & objSnmpTrap.Community

Set objSnmpObject = objSnmpTrap.GetFirstObject      
While( objSnmpTrap.LastError = 0 )                              ' iterate over all variables 
                                                                ' in the trap

 WScript.Echo "  OID : " & objSnmpObject.OID
 WScript.Echo "  Value:" & objSnmpObject.Value   
 WScript.Echo "  Type:"  & GetTypeString( objSnmpObject.Type )

 Set objSnmpObject = objSnmpTrap.GetNextObject
WEnd

Set objSnmpTrap = objSnmpTrapManager.GetNextTrap                ' Get next trap
WEnd  

objSnmpTrapManager.StopListening                                ' Stop listening for 
                                                                ' incoming traps

ActiveXperts Networking Component ships with a utility to receive SNMP trap messages in the background. This program runs as a Windows service, and stored incoming traps in a database (MS Access database by default). Configration settings are stored in a plain ASCII file. For more information about this SNMP Trap Receiver Service, see Chapter: SNMP Trap Receiver Service.

20.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
ProtocolVersion Number In/Out Specifies the SNMP protocol version to use
AuthProtocol Number In/Out Specifies the authentication protocol to be used in SNMPv3
PrivProtocol Number In/Out Specifies the privacy protocol to be used in SNMPv3
AuthUsername String In/Out Specifies the username to be used in SNMPv3 authentication
AuthPassword String In/Out Specifies the password to be used in SNMPv3 authentication
PrivPassword String In/Out Specifies the password to be used in SNMPv3 privacy
Context String In/Out Specifies the context to be used in SNMPv3
EngineID String In/Out Specifies the EngineId you want to receive SNMPv3 traps from
LastError Number In/Out Result of the last called method

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

' Create a new SnmpTrapManager instance
Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" ) 
WScript.Echo "Version: " & objTrapManager.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

' Create a new SnmpTrapManager instance
Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" ) 
WScript.Echo "Build: " & objTrapManager.Build

Module property

Return the module name of the Component.

Example:

Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )     ' Create new instance 
WScript.Echo  "Module: " & objTrapManager.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )     ' Create instance
WScript.Echo "LicenseStatus: " & objTrapManager.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objTrapManager = CreateObject("AxNetwork.SnmpTrapManager")       ' Create new instance
WScript.Echo "LicenseKey: " & objSnmpTrapManager.LicenseKey

ProtocolVersion property

Type:

Number

Description:

Specifies the SNMP protocol version to use: nwSNMP_VERSION_V1, nwSNMP_VERSION_V2C or nwSNMP_VERSION_V3. The default is version nwSNMP_VERSION_V2C.
Note: To set the protocol version, you must set the 'ProtocolVersion' property before calling the Send method.

Example:

' Create a new SnmpTrapManager instance
Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" ) 
Set objSnmpTrap    = CreateObject( "AxNetwork.SnmpTrap" )       ' Create a new Create 
                                                                ' a new SnmpTrap instance
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
objSnmpTrap.Host   = ...                                        ' Set trap properties
objSnmpTrap.Community = ...                                     ' Set trap properties
...
objTrapManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V1 ' Use SNMP v1
objTrapManager.Send objSnmpTrap                                 ' Send trap
...

AuthProtocol property

Type:

Number

Description:

Specifies the SNMPv3 authentication protocol to use: nwSNMP_AUTH_SHA1 or nwSNMP_AUTH_MD5. The default protocol is nwSNMP_AUTH_SHA1.

This property is only used when the 'ProtocolVersion' property is set to nwSNMP_VERSION_V3.

Note: To set the authentication protocol, you must set the 'AuthProtocol' property before calling the Send method.

Example:

Set objSnmpManager = CreateObject( "AxNetwork.SnmpTrapManager" )    ' Create SnmpTrapManager
Set objSnmpTrap    = CreateObject( "AxNetwork.SnmpTrap" )           ' Create SnmpTrap
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )        ' Create Constants

objTrapManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V3     ' Use SNMPv3
							
objTrapManager.AuthProtocol    = objConstants.nwSNMP_AUTH_SHA1      ' Use SHA1 authentication
objTrapManager.AuthUsername    = "user"                             ' Set SNMPv3 user
objTrapManager.AuthPassword    = "password1"                        ' Set SNMPv3 password

...                                                                 ' Trap code

objTrapManager.Send objSnmpTrap                                     ' Send Trap

PrivProtocol property

Type:

Number

Description:

Specifies the SNMPv3 privacy protocol to use: nwSNMP_AUTH_SHA1 or nwSNMP_AUTH_MD5. The default protocol is nwSNMP_AUTH_SHA1.

This property is only used when the 'ProtocolVersion' property is set to nwSNMP_VERSION_V3.

Note: To set the authentication protocol, you must set the 'PrivProtocol' property before calling the Send method.

Example:

Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )    ' Create SnmpTrapManager
Set objSnmpTrap    = CreateObject( "AxNetwork.SnmpTrap" )           ' Create SnmpTrap
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )        ' Create Constants

objTrapManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V3     ' Use SNMPv3
							
objTrapManager.AuthProtocol    = objConstants.nwSNMP_AUTH_SHA1      ' Use SHA1 authentication
objTrapManager.AuthUsername    = "user"                             ' Set SNMPv3 user
objTrapManager.AuthPassword    = "password1"                        ' Set SNMPv3 password

...                                                                 ' Trap code

objTrapManager.Send objSnmpTrap                                     ' Send Trap
...

AuthUsername property

Type:

Number

Description:

Specifies the username to be used in SNMPv3 authentication. A SNMPv3 username has to be at least 8 characters long. A username is required in SNMPv3, even if no authentication is used.

This property is only used when the 'ProtocolVersion' property is set to nwSNMP_VERSION_V3.

Note: To set the authentication username, you must set the 'AuthUsername' property before calling the Send method.

Example:

Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )    ' Create SnmpTrapManager
Set objSnmpTrap    = CreateObject( "AxNetwork.SnmpTrap" )           ' Create SnmpTrap
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )        ' Create Constants

objTrapManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V3     ' Use SNMPv3
							
objTrapManager.AuthProtocol    = objConstants.nwSNMP_AUTH_SHA1      ' Use SHA1 authentication
objTrapManager.AuthUsername    = "user"                             ' Set SNMPv3 user
objTrapManager.AuthPassword    = "password1"                        ' Set SNMPv3 password

...                                                                 ' Trap code

objTrapManager.Send objSnmpTrap
...

AuthPassword property

Type:

Number

Description:

Specifies the password to be used in SNMPv3 authentication. A SNMPv3 password has to be at least 8 characters long. If no password is specified, SNMPv3 authentication is turned off. This property is only used when the 'ProtocolVersion' property is set to nwSNMP_VERSION_V3.

Note: To set the authentication password, you must set the 'AuthPassword' property before calling the Send method.

Example:

Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )    ' Create SnmpTrapManager
Set objSnmpTrap    = CreateObject( "AxNetwork.SnmpTrap" )           ' Create SnmpTrap
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )        ' Create Constants

objTrapManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V3     ' Use SNMPv3
							
objTrapManager.AuthProtocol    = objConstants.nwSNMP_AUTH_MD5       ' Use MD5 authentication
objTrapManager.AuthUsername    = "user"                             ' Set SNMPv3 user
objTrapManager.AuthPassword    = "password1"                        ' Set SNMPv3 password

...                                                                 ' Trap code

objTrapManager.Send objSnmpTrap
...

PrivPassword property

Type:

Number

Description:

Specifies the password to be used in SNMPv3 privacy. A SNMPv3 password has to be at least 8 characters long. If no password is specified, SNMPv3 authentication is turned off. This property is only used when the 'ProtocolVersion' property is set to nwSNMP_VERSION_V3.

Note: To set the privacy password, you must set the 'PrivPassword' property before calling the Send method.

Example:

Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )    ' Create SnmpTrapManager
Set objSnmpTrap    = CreateObject( "AxNetwork.SnmpTrap" )           ' Create SnmpTrap
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )        ' Create Constants

objTrapManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V3     ' Use SNMPv3
							
objTrapManager.PrivProtocol    = objConstants.nwSNMP_PRIV_DES       ' Use DES encryption
objTrapManager.AuthUsername    = "user"                             ' Set SNMPv3 user
objTrapManager.PrivPassword    = "password2"                        ' Set SNMPv3 password

...                                                                 ' Trap code

objTrapManager.Send objSnmpTrap
...

Context property

Type:

Number

Description:

Specifies the context to be used in SNMPv3 PDU's. This parameters is optional.

Note: To set context, you must set the 'Context' property before calling the Send method.

Example:

Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )    ' Create SnmpTrapManager
Set objSnmpTrap    = CreateObject( "AxNetwork.SnmpTrap" )           ' Create SnmpTrap
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )        ' Create Constants

objTrapManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V3     ' Use SNMPv3
							
objTrapManager.PrivProtocol    = objConstants.nwSNMP_PRIV_DES       ' Use DES encryption
objTrapManager.AuthUsername    = "user"                             ' Set SNMPv3 user
objTrapManager.PrivPassword    = "password2"                        ' Set SNMPv3 password
objTrapManager.Context         = "SNMP"                             ' Set SNMPv3 context

...                                                                 ' Trap code

objTrapManager.Send objSnmpTrap
...

EngineID property

Type:

Number

Description:

Specifies the EngineId you want to receive SNMPv3 traps from. This property is required when receiving traps from a SNMPv3 agent.

Note: You must set the 'EngineId' property before calling the StartListening method.

Example:

Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )    ' Create SnmpTrapManager
Set objSnmpTrap    = CreateObject( "AxNetwork.SnmpTrap" )           ' Create SnmpTrap
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )        ' Create Constants

objTrapManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V3     ' Use SNMPv3
							
objTrapManager.AuthProtocol    = objConstants.nwSNMP_AUTH_SHA1      ' Use SHA1 authentication
objTrapManager.AuthUsername    = "user"                             ' Set SNMPv3 user
objTrapManager.AuthPassword    = "password1"                        ' Set SNMPv3 password
objTrapManager.EngineId        = "80001F8880012C000059354F50"       ' Set SNMPv3 engine

objTrapManager.StartListening  ""
...

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

' Create a new SnmpTrapManager instance
Set objTrapManager = CreateObject("AxNetwork.SnmpTrapManager")
Set objTrap        = CreateObject("AxNetwork.SnmpTrap")

objTrapManager.Send objTrap

WScript.Echo "Send, LastError: " & objTrapManager.LastError
...

20.3. Methods

Methods

Method Description
Clear Reset all properties to their default values
Send Send a trap
StartListening Start listening for incoming traps
StopListening Stop listening for incoming traps
GetFirstTrap Get first trap in the 'Inbox'
GetNextTrap Get next trap in the 'Inbox'
Sleep Suspends the execution of the object for at least the specified interval
GetErrorDescription Get the description of the given error

Clear method

Description:

Resets all properties to the initial, default values. Use this method when you are opening/closing SNMP sessions multiple times.

Parameters:

  • None

Return value:

Always 0.

Example:

' Create a new SnmpTrapManager instance
Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
objTrapManager.Clear                                            ' Reset all properties
objTrapManager.ProtocolVersion = objConstants.nwSNMP_VERSION_V1 ' Use SNMP v1
...

Send method

Description:

Send a trap to a (remote) SNMP agent.

Parameters:

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

' Create a new SnmpTrapManager instance
Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )
Set objSnmpTrap    = CreateObject( "AxNetwork.SnmpTrap" )       ' Create a new SnmpTrap 
                                                                ' instance
Set objSnmpObject  = CreateObject( "AxNetwork.SnmpObject" )     ' Create a new SnmpObject 
                                                                ' instance
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create a new Constants 
                                                                ' instance 
' Set trap properties
objSnmpTrap.Clear()
objSnmpTrap.Host      = "server06"
objSnmpTrap.Community = "public"

' Add a variable to the trap
objSnmpObject.Clear()                                           ' Clear trap object
objSnmpObject.OID   = ".1.3.6.1.2.1.1.5.0"                      ' Set trap properties
objSnmpObject.Type  = objConstants.nwSNMP_TYPE_IPADDRESS        ' Set trap properties
objSnmpObject.Value = "10.0.0.1"                                ' Set trap properties 
objSnmpTrap.AddObject objSnmpObject                             ' Add the trap to the queue

' Add another variable to the trap
objSnmpObject.Clear()                                           ' Clear trap object
objSnmpObject.OID   = ".1.3.6.1.2.1.1.5.1"                      ' Set trap properties
objSnmpObject.Type  = objConstants.nwSNMP_TYPE_OCTETSTRING      ' Set trap properties
objSnmpObject.Value = "One two three"                           ' Set trap properties 
objSnmpTrap.AddObject objSnmpObject                             ' Add the trap to the queue

objTrapManager.Send objSnmpTrap                                 ' Send trap
WScript.Echo "Send, result: " & objTrapManager.LastError        ' Display the result

StartListening method

Description:

Start listening for incoming traps. The method returns immediately. From that moment, it will store all incoming traps in the internal queue. Use GetFirstTrap and GetNextTrap to fetch the received traps from the internal queue.

Parameters:

  • Community - the community string. If an empty string is specified, it will accept traps from any community.
  • Port (optional) - UDP port used for SNMP trap communications. Default: 162.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

' Create a new Snmp instance
Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )
...
objTrapManager.StartListening ""                                ' Start listening on 
                                                                ' this computer for any 
                                                                ' incoming traps
objTrapManager.Sleep 30000                                      ' Store all incoming 
                                                                ' traps for 30 seconds
objTrapManager.Stoplistening                                    ' Stop listening
...

StopListening method

Description:

Stop listening for incoming traps. It only makes sense to call this methods if the program is in 'listen' mode, i.e. if the program called StartListening in an earlier stage.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

' Create a new Snmp instance
Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )
...
objTrapManager.StartListening "public"                          ' Start listening on this 
                                                                ' computer for incoming traps
objTrapManager.Sleep 30000                                      ' Store all incoming traps 
                                                                ' for 30 seconds
objTrapManager.Stoplistening                                    ' Stop listening
...

GetFirstTrap method

Description:

Get the first trap from the internal queue. Traps are retrieve in FIFO (first-in-first-out) order. The queue is cleared automatically when GetNextTrap has fetched the last item in the queue.

Parameters:

  • None

Return value:

An LastError property to see if the method was completed successfully.

Example:

' Create a new Snmp instance
Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )
... 
objTrapManager.StartListening "public"                          ' Start listening now
...
Set objSnmpTrap = objTrapManager.GetFirstTrap                   ' Get trap
While( objTrapManager.LastError = 0 )
   WScript.Echo "Trap from      : " & objSnmpTrap.Host
   WScript.Echo "  Community   : " & objSnmpTrap.Community

   Set objSnmpObject = objSnmpTrap.GetFirstObject      
   While( objSnmpTrap.LastError = 0 )                           ' iterate over all variables in 
                                                                ' the trap
    
     WScript.Echo "OID : " & objSnmpObject.OID
     WScript.Echo "Value:" & objSnmpObject.Value   
     WScript.Echo "Type:"  & GetTypeString( objSnmpObject.Type )
  
     Set objSnmpObject = objSnmpTrap.GetNextObject
   WEnd

   Set objSnmpTrap = objTrapManager.GetNextTrap                 ' Get next trap
WEnd  

objTrapManager.StopListening                                    ' Stop listening for 
                                                                ' incoming traps

GetNextTrap method

Description:

Get the next trap from the internal queue. Traps are retrieve in FIFO (first-in-first-out) order. The queue is cleared automatically when 'GetNextTrap' has fetched the last item in the queue.

Parameters:

  • None

Return value:

Check the LastError property to see if the method was completed successfully.

Example:

' Create a new Snmp instance
Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )
... 
objTrapManager.StartListening "public"                          ' Start listening now
...
Set objSnmpTrap = objTrapManager.GetFirstTrap                   ' Get trap
While( objTrapManager.LastError = 0 )
   WScript.Echo "Trap from      : " & objSnmpTrap.Host
   WScript.Echo "  Community   : " & objSnmpTrap.Community

   Set objSnmpObject = objSnmpTrap.GetFirstObject      
   While( objSnmpTrap.LastError = 0 )                           ' iterate over all variables in 
                                                                ' the trap
    
     WScript.Echo "OID : " & objSnmpObject.OID
     WScript.Echo "Value:" & objSnmpObject.Value   
     WScript.Echo "Type:"  & GetTypeString( objSnmpObject.Type )
  
     Set objSnmpObject = objSnmpTrap.GetNextObject
   WEnd

   Set objSnmpTrap = objTrapManager.GetNextTrap                 ' Get next trap
WEnd  

objTrapManager.StopListening                                    ' Stop listening for 
                                                                ' incoming traps

Sleep method

Description:

Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to suspend execution.

Return value:

Always 0.

Example:

' Create a new SnmpTrapManager instance
Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )

...
objTrapManager.Send objSnmpTrap

objTrapManager.Sleep 5000                                       ' Suspend 5 seconds before 
                                                                ' sending the next trap
objTrapManager.Send objSnmpTrap
...

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error - the numeric error code

Return value:

The error description that is associated with the specified error code.

Example:

' Create a new SnmpTrapManager instance
Set objTrapManager = CreateObject("AxNetwork.SnmpTrapManager")

WScript.Echo "LastError: " & objTrapManager.LastError
WScript.Echo "Error description:" & objTrapManager.GetErrorDescription(objTrapManager.LastError)

21. SnmpTrap

21.1. Introduction

21.2. Properties

Properties

Property Type Read/Write Description
Host String In/Out SNMP host
Community String In/Out SNMP community
Port Number In/Out SNMP port
GenericTrap Number In/Out Generic Trap identifier
SpecificTrap Number In/Out Specific Trap identifier (custom trap)
Enterprise String In/Out Relative OID path
UpTime String In/Out UpTime

Host property

Type:

String

Description:

Host or IP address. If the object is used for sending traps, the 'Host' property specifies the remote host to send the trap to. If the object is returned by the GetFirstTrap or GetNextTrap method, the 'Host' propery identifies the host where the trap was received from.

Example:

' Create a new SnmpTrapManager instance
Set objSnmpManager = CreateObject( "AxNetwork.SnmpTrapManager" ) 
...
objSnmpTrapManager.StartListening "public"
...
Set objSnmpTrap = objSnmpTrapManager.GetFirstTrap
While objSnmpTrapManager.LastError = 0
   WScript.Echo "Host : "       & objSnmpTrap.Host          ' Print incoming trap properties
   WScript.Echo "Community:"    & objSnmpTrap.Community     ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime        ' Print incoming trap properties
   WScript.Echo "GenericTrap:"  & objSnmpTrap.GenericTrap   ' Print incoming trap properties
   WScript.Echo "SpecificTrap:" & objSnmpTrap.SpecificTrap  ' Print incoming trap properties
   WScript.Echo "Enterprise:"   & objSnmpTrap.Enterprise    ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime        ' Print incoming trap properties

   Set objSnmpTrap = objSnmpTrapManager.GetNextTrap
WEnd  
...
objSnmpTrapManager.StopListening

Community property

Type:

String

Description:

Community name. If the object is used for sending traps, the 'Community' property specifies the community used for sending traps. If the object is returned by the GetFirstTrap or GetNextTrap method, the 'Community' propery identifies the community on which the trap was received from.

Example:

' Create a new SnmpTrapManager instance
Set objSnmpManager = CreateObject( "AxNetwork.SnmpTrapManager" ) 
...
objSnmpTrapManager.StartListening "public"
...
Set objSnmpTrap = objSnmpTrapManager.GetFirstTrap
While objSnmpTrapManager.LastError = 0
   WScript.Echo "Host : "       & objSnmpTrap.Host          ' Print incoming trap properties
   WScript.Echo "Community:"    & objSnmpTrap.Community     ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime        ' Print incoming trap properties
   WScript.Echo "GenericTrap:"  & objSnmpTrap.GenericTrap   ' Print incoming trap properties
   WScript.Echo "SpecificTrap:" & objSnmpTrap.SpecificTrap  ' Print incoming trap properties
   WScript.Echo "Enterprise:"   & objSnmpTrap.Enterprise    ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime        ' Print incoming trap properties

   Set objSnmpTrap = objSnmpTrapManager.GetNextTrap
WEnd  
...
objSnmpTrapManager.StopListening

Port property

Type:

Number

Description:

SNMP port. If the object is used for sending traps, the 'Port' property specifies the port used for sending traps (default: 162). If the object is returned by the GetFirstTrap or GetNextTrap method, the 'Port' propery identifies the port on which the trap was received.

Example:

' Create a new SnmpTrapManager instance
Set objSnmpManager = CreateObject( "AxNetwork.SnmpTrapManager" ) 
...
objSnmpTrapManager.StartListening "public"
...
Set objSnmpTrap = objSnmpTrapManager.GetFirstTrap
While objSnmpTrapManager.LastError = 0
   WScript.Echo "Host : "       & objSnmpTrap.Host          ' Print incoming trap properties
   WScript.Echo "Port:"         & objSnmpTrap.Port          ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime        ' Print incoming trap properties
   WScript.Echo "GenericTrap:"  & objSnmpTrap.GenericTrap   ' Print incoming trap properties
   WScript.Echo "SpecificTrap:" & objSnmpTrap.SpecificTrap  ' Print incoming trap properties
   WScript.Echo "Enterprise:"   & objSnmpTrap.Enterprise    ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime        ' Print incoming trap properties

   Set objSnmpTrap = objSnmpTrapManager.GetNextTrap
WEnd  
...
objSnmpTrapManager.StopListening

GenericTrap property

Type:

Number

Description:

This property can only be used with SNMP v1. For a list of valid values, click here.

Example:

' Create a new SnmpTrapManager instance
Set objSnmpManager = CreateObject( "AxNetwork.SnmpTrapManager" ) 
...
objTrapManager.StartListening "public"
...
Set objSnmpTrap = objTrapManager.GetFirstTrap
While objSnmpTrapManager.LastError = 0
   WScript.Echo "Host : "       & objSnmpTrap.Host          ' Print incoming trap properties
   WScript.Echo "Community:"    & objSnmpTrap.Community     ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime        ' Print incoming trap properties
   WScript.Echo "GenericTrap:"  & objSnmpTrap.GenericTrap   ' Print incoming trap properties
   WScript.Echo "SpecificTrap:" & objSnmpTrap.SpecificTrap  ' Print incoming trap properties
   WScript.Echo "Enterprise:"   & objSnmpTrap.Enterprise    ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime        ' Print incoming trap properties

   Set objSnmpTrap = objTrapManager.GetNextTrap
WEnd  
...
objTrapManager.StopListening

SpecificTrap property

Type:

Number

Description:

This property can only be used with SNMP v1. You can specify a custom trap type.

Example:

' Create a new SnmpTrapManager instance
Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" ) 
...
objSnmpTrapManager.StartListening "public"
...
Set objSnmpTrap = objSnmpTrapManager.GetFirstTrap
While objSnmpTrapManager.LastError = 0
   WScript.Echo "Host : "       & objSnmpTrap.Host          ' Print incoming trap properties
   WScript.Echo "Community:"    & objSnmpTrap.Community     ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime        ' Print incoming trap properties
   WScript.Echo "GenericTrap:"  & objSnmpTrap.GenericTrap   ' Print incoming trap properties
   WScript.Echo "SpecificTrap:" & objSnmpTrap.SpecificTrap  ' Print incoming trap properties
   WScript.Echo "Enterprise:"   & objSnmpTrap.Enterprise    ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime        ' Print incoming trap properties

   Set objSnmpTrap = objSnmpTrapManager.GetNextTrap
WEnd  
...
objSnmpTrapManager.StopListening

Enterprise property

Type:

String

Description:

This property can only be used with SNMP v1. It indicates the relative OID.

Example:

' Create a new SnmpTrapManager instance
Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" ) 
...
objTrapManager.StartListening "public"
...
Set objSnmpTrap = objTrapManager.GetFirstTrap
While objTrapManager.LastError = 0
   WScript.Echo "Host : "       & objSnmpTrap.Host         ' Print incoming trap properties
   WScript.Echo "Community:"    & objSnmpTrap.Community    ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime       ' Print incoming trap properties
   WScript.Echo "GenericTrap:"  & objSnmpTrap.GenericTrap  ' Print incoming trap properties
   WScript.Echo "SpecificTrap:" & objSnmpTrap.SpecificTrap ' Print incoming trap properties
   WScript.Echo "Enterprise:"   & objSnmpTrap.Enterprise   ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime       ' Print incoming trap properties

   Set objSnmpTrap = objTrapManager.GetNextTrap
WEnd  
...
objTrapManager.StopListening

UpTime property

Type:

Number

Description:

Provides the amount of time that has elapsed between the last network reinitialization and generation of the trap. This property is available for both SNMP v1 and SNMP v2c.

Example:

' Create a new SnmpTrapManager instance
Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" ) 
...
objTrapManager.StartListening "public"
...
Set objSnmpTrap = objTrapManager.GetFirstTrap
While objTrapManager.LastError = 0
   WScript.Echo "Host : "       & objSnmpTrap.Host          ' Print incoming trap properties
   WScript.Echo "Community:"    & objSnmpTrap.Community     ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime        ' Print incoming trap properties
   WScript.Echo "GenericTrap:"  & objSnmpTrap.GenericTrap   ' Print incoming trap properties
   WScript.Echo "SpecificTrap:" & objSnmpTrap.SpecificTrap  ' Print incoming trap properties
   WScript.Echo "Enterprise:"   & objSnmpTrap.Enterprise    ' Print incoming trap properties
   WScript.Echo "Uptime:"       & objSnmpTrap.UpTime        ' Print incoming trap properties

   Set objSnmpTrap = objTrapManager.GetNextTrap
WEnd  
...
objTrapManager.StopListening

21.3. Methods

Methods

Method Description
Clear Reset all properties to their default values
AddObject Add a new SNMP object to the trap
GetFirstObject Get first variable
GetNextObject Get next variable

Clear method

Description:

Resets all properties to the initial, default values.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objSnmpTrap  = CreateObject( "AxNetwork.SnmpTrap" )         ' Create a new SnmpTrap instance
...
objSnmpTrap.Clear()                                             ' Clear all properties
objSnmpTrap.Host         = ...
objSnmpTrap.Community    = ...

AddObject method

Description:

Add an SnmpObject to the trap. You can add multiple SnmpObjects to a trap.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objTrapManager  = CreateObject( "AxNetwork.SnmpTrapManager" )
Set objSnmpTrap     = CreateObject( "AxNetwork.SnmpTrap" )   
Set objSnmpObject   = CreateObject( "AxNetwork.SnmpObject" ) 
Set objConstants    = CreateObject( "AxNetwork.NwConstants" )
objTrapManager.Initialize     
...                                      
' Set trap properties
objSnmpTrap.Clear()
objSnmpTrap.Host	  = "server06"
objSnmpTrap.Community = "public"

' Add a variable to the trap
objSnmpObject.Clear()                                           ' Clear trap object
objSnmpObject.OID     = ".1.3.6.1.2.1.1.5.0"                    ' Set trap properties
objSnmpObject.Type    = objConstants.nwSNMP_TYPE_IPADDRESS      ' Set trap properties
objSnmpObject.Value   = "10.0.0.1"                              ' Set trap properties 
objSnmpTrap.AddObject objSnmpObject                             ' Add the object to the trap

' Add another variable to the trap
objSnmpObject.Clear()                                           ' Clear trap object
objSnmpObject.OID     = ".1.3.6.1.2.1.1.5.1"                    ' Set trap properties
objSnmpObject.Type    = objConstants.nwSNMP_TYPE_OCTETSTRING    ' Set trap properties
objSnmpObject.Value   = "One two three"                         ' Set trap properties 
objSnmpTrap.AddObject objSnmpObject                             ' Add the object to the trap

objTrapManager.Send objSnmpTrap                                 ' Send trap
...

GetFirstObject method

Description:

Iterate over all SnmpTrap objects in the trap. There can be 1 or more SnmpTrap objects in one trap.

Parameters:

  • None

Return value:

A reference to an SnmpTrap object.

Example:

Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )
objTrapManager.Initialize                                       ' Initialize SNMP
... 
objTrapManager.StartListening "public"                          ' Start listening now
...
Set objSnmpTrap = objTrapManager.GetFirstTrap                   ' Get trap
While( objTrapManager.LastError = 0 )
   WScript.Echo "Trap from      : " & objSnmpTrap.Host
   WScript.Echo "  Community   : " & objSnmpTrap.Community

   Set objSnmpObject = objSnmpTrap.GetFirstObject      
   While( objSnmpTrap.LastError = 0 )                           ' iterate over all variables 
                                                                ' in the trap
    
     WScript.Echo "OID : " & objSnmpObject.OID
     WScript.Echo "Value:" & objSnmpObject.Value   
     WScript.Echo "Type:"  & GetTypeString( objSnmpObject.Type )
  
     Set objSnmpObject = objSnmpTrap.GetNextObject
   WEnd

   Set objSnmpTrap = objTrapManager.GetNextTrap                 ' Get next trap
WEnd  

objTrapManager.StopListening                                    ' Stop listening for 
                                                                ' incoming traps
objTrapManager.Shutdown                                         ' Uninitialize SNMP

GetNextObject method

Description:

Iterate over all SnmpTrap objects in the trap. There can be 1 or more SnmpTrap objects in one trap.

Parameters:

  • None

Return value:

A reference to an SnmpTrap object.

Example:

Set objTrapManager = CreateObject( "AxNetwork.SnmpTrapManager" )
objTrapManager.Initialize                                       ' Initialize SNMP
... 
objTrapManager.StartListening "public"                          ' Start listening now
...
Set objSnmpTrap = objTrapManager.GetFirstTrap                   ' Get trap
While( objTrapManager.LastError = 0 )
   WScript.Echo "Trap from      : " & objSnmpTrap.Host
   WScript.Echo "  Community   : " & objSnmpTrap.Community

   Set objSnmpObject = objSnmpTrap.GetFirstObject      
   While( objSnmpTrap.LastError = 0 )                           ' iterate over all variables in 
                                                                ' the trap
    
     WScript.Echo "OID : " & objSnmpObject.OID
     WScript.Echo "Value:" & objSnmpObject.Value   
     WScript.Echo "Type:"  & GetTypeString( objSnmpObject.Type )
  
     Set objSnmpObject = objSnmpTrap.GetNextObject
   WEnd

   Set objSnmpTrap = objTrapManager.GetNextTrap                 ' Get next trap
WEnd  

objTrapManager.StopListening                                    ' Stop listening for 
                                                                ' incoming traps
objTrapManager.Shutdown                                         ' Uninitialize SNMP

21.4. SNMP Trap Receiver Service

ActiveXperts Networking Component ships with a utility to receive SNMP trap messages in the background. This program runs as a Windows service, and stores incoming traps in a database (MS Access database by default). Configuration settings are stored in a plain ASCII file.

Installation of the service

The 'SNMP Trap Receiver Service' is not installed by default. You need to run the SNMP Trap Receive 'Installation and Configuration' program first. You can access this program from the Start menu:

  • Click 'Start', point to 'All Programs' and click 'ActiveXperts';
  • Click 'ActiveXperts Networking Component', click on 'SNMP Trap Receiver Service' and launch the 'Installation and Configuration' program;
  • The wizard will guide you through the process of installing and running the service.

After installation, you can run the same program again to make changes to the configuration. The same program can also be used to uninstall the service.

Configuration of the service

All configuration items are stored in a single text file. The following registry key points to the configuration file:

HKLM\Software\ActiveXperts\Network-Component\SnmpTrapReceiver\ConfigFile

By default, this entry points to the CONFIG.INI file located in the same directory as the service executable, i.e.:

C:\Program Files\ActiveXperts\Network-Component\Service\Config.ini

This plain text file can be modified by any text editor, including notepad.

The SNMP Trap Receiver Service uses two files for its output:

  • A database where the incoming traps are stored. The products ships with an MS Access database called SNMPTRAPS.MDB This database file is located in the <INSTALL>\SERVICE directory. By default, all incoming traps will be stored in this database file. You can change the database location from the CONFIG.INI file;
  • A log file where all SNMP operations are logged. By default, operations are logged to the SNMPTRAPS.LOG file located in the <INSTALL>\SERVICE directory. You can change the log file location from the CONFIG.INI file. You can also disable logging the the CONFIG.INI file.

The configration file holds the following entries:

Name Description
Port Port used by the service to listen for incoming SNMP traps. Default: 162
Community SNMP community name. Default: public
Database OLE/DB database connection string
LogEnabled Use this value to enable/disable logging. 0 means: disabled; 1 means: enabled
LogLevel Indicates the logging level. 0 indicates: minimal logging; 1 indicates: average logging; 2 indicates: maximum logging
LogFile Name of the log file

You can use the 'Installation and Configuration' program (the one that is also used to install the service) to configure the service.

Uninstalling the service

To uninstall the SNMP Trap Receiver Service, use the same program as used to install the service. The program has the option to uninstall the service.

22. SnmpMibBrowser

22.1. Introduction

A management information base (MIB) is a database used to manage the devices in a communications network. The database is hierarchical (tree-structured) and entries are addressed through object identifiers (OID's).

A MIB should contain information on these commands and on the target objects (controllable entities or potential sources of status information) with a view to tuning the network transport to the current needs. Each type of object in a MIB database has a name, a syntax, and an encoding. The name is represented uniquely as an OID. An OID is an administratively assigned name. The administrative policies used for assigning names are discussed later in this memo.

Use the ActiveXperts Networking Component's 'SnmpMibBrowser' object to load a MIB database into memory and iterate over all objects and view all properties.

Here is a small example (in VBScript) to show how to load a MIB file and display its complete tree structure:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )     ' Create a new SnmpMibBrowser 
                                                                ' instance

objSnmpMib.LoadMibFile( "c:\windows\system32\hostmib.mib" )     ' Load MIB file
WScript.Echo "LoadMibFile, result: " & objSnmpMib.LastError
If( objSnmpMib.LastError <> 0 ) Then
  WScript.Quit 
End If

Set objSnmp = objSnmpMIB.Get("iso")                             ' Get first OID
While(objSnmpMIB.LastError = 0 )
  WScript.Echo "OID Name: " & objSnmp.Name & "; Full-path: " & objSnmp.Path
  WScript.Echo "  Description: " & objSnmp.Description
  WScript.Echo "  Access: " & objSnmp.Access
  WScript.Echo "  Status: " & objSnmp.Status                   
  Set objSnmp = objSnmpMIB.GetNext()                            ' Get next OID
WEnd

22.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
LastError Number Out Result of the lasat called method
LogFile String In/Out Log file that can be used for troubleshooting purposes

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objSnmpMib = CreateObject("AxNetwork.SnmpMibBrowser")    ' Create SnmpMibBrowser object
WScript.Echo  "Version: " & objSnmpMib.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objSnmpMib = CreateObject("AxNetwork.SnmpMibBrowser")    ' Create SnmpMibBrowser object
WScript.Echo  "Build: " & objSnmpMib.Build

Module property

Return the module name of the Component.

Example:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )        ' Create new instance 
WScript.Echo  "Module: " & objSnmpMib.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )        ' Create instance
WScript.Echo "LicenseStatus: " & objSnmpMib.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objSnmpMib = CreateObject("AxNetwork.SnmpMibBrowser")          ' Create new instance
WScript.Echo "LicenseKey: " & objSnmpMib.LicenseKey

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objSnmpMib = CreateObject("AxNetwork.SnmpMibBrowser")    ' Create SnmpMibBrowser object
...
objSnmpMib.Get( "iso" ) 
WScript.Echo "LastError: " & objSnmpMib.LastError

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all MIB browser operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all MIB browser operations will be written to this log file.

Example:

Set objSnmpMib = CreateObject("AxNetwork.SnmpMibBrowser")    ' Create SnmpMibBrowser object
objSnmpMib.LogFile = "c:\snmpmib.txt"
...
objSnmpMib.Get( "iso" )

22.3. Methods

Methods

Method Description
LoadMibFile Load a MIB database from file into memory
Get Get the first object from the MIB database
GetNext Get the next object from the MIB database
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval

LoadMibFile method

Description:

Load a MIB database from file into memory.

Parameters:

  • The MIB file location

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )     ' Create a new SnmpMibBrowser 
                                                                ' instance
 
objSnmpMib.LoadMibFile( "c:\windows\system32\hostmib.mib" )     ' Load MIB file

Set objSnmp = objSnmpMIB.Get("iso")                             ' Get first OID
...

Get method

Description:

Get the first object from the MIB database. Use GetNext to retrieve the next object from the MIB database.

Parameters:

  • The parent OID

Return value:

An SnmpObject object. If the method fails, a null reference is returned and the LastError property is set to a non-zero value indicating the reason for failing.

Example:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )     ' Create a new SnmpMibBrowser
                                                                ' instance

objSnmpMib.LoadMibFile( "c:\windows\system32\hostmib.mib" )     ' Load MIB file
...
Set objSnmp = objSnmpMIB.Get("iso")                             ' Get first OID
While(objSnmpMIB.LastError = 0 )
  WScript.Echo "OID path: " objSnmp.Path
  Set objSnmp = objSnmpMIB.GetNext()                            ' Get next OID
WEnd

GetNext method

Description:

Get the next object from the MIB database. Use Get to retrieve the first object from the MIB database.

Parameters:

  • None

Return value:

The LastError property is set to a non-zero value indicating the reason for failing.

Example:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )     ' Create a new SnmpMibBrowser 
                                                                ' instance

objSnmpMib.LoadMibFile( "c:\windows\system32\hostmib.mib" )     ' Load MIB file
...
Set objSnmp = objSnmpMIB.Get("iso")                             ' Get first OID
While(objSnmpMIB.LastError = 0 )
  WScript.Echo "OID path: " objSnmp.Path
  Set objSnmp = objSnmpMIB.GetNext()                            ' Get next OID
WEnd

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objSnmpMib  = CreateObject( "AxNetwork.SnmpMibBrowser" )
objSnmpMib.Host = "www.activexperts.com"                        
objSnmpMib.Query()                                              ' Translate host/IP to country
WScript.Echo "Query, result: " & objSnmpMib.LastError & _       ' Error code
       objSnmpMib.GetErrorDescription( objSnmpMib.LastError )   ' Error Description

Sleep method

Description:

This method can be used in your script anywhere you want. Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to suspend

Return value:

Always 0.

Example:

Set objSnmpMib = CreateObject( "AxNetwork.SnmpMibBrowser" )  ' Create SnmpMibBrowser object
Set objConstants = CreateObject( "AxNetwork.NwConstants" )   ' Create constants object
...
objSnmpMib.Sleep 500

23. Ssh

23.1. Introduction

SSH Secure Shell allows secure network services over an insecure network, such as the Internet.

The Secure Shell concept originated on UNIX as a replacement for the insecure "Berkeley services", that is, the rsh , rcp, and rlogin commands. SSH Secure Shell replaces other, insecure terminal applications (such as Telnet and FTP). It allows you to securely login to remote host computers, to execute commands safely in a remote computer, to securely copy remote files, to forward X11 sessions (on UNIX), and to provide secure encrypted and authenticated communications between two non-trusted hosts. Also arbitrary TCP/IP ports can be forwarded over the secure channel, enabling secure connection, for example, to an email service.

SSH Secure Shell with its array of unmatched security features is an essential tool in today's network environment. It is a powerful guardian against the numerous security hazards that nowadays threaten network communications.

The ActiveXperts Networking Component Ssh implementation is based on the PuTTY implementation. With the ActiveXperts Networking Component Ssh object, you can login onto a remote machine running the SSH daemon, and execute a command or shell script. It has no user interface by itself: standard error and standard output are not copied to the console, but are copied to the corresponding object properties (StdErr and StdOut) instead.

There are two ways to authenticate: by using a password or by using a 'private key'. When using a password to authenticate it is required that the host private key is known to the system. If the hosts private key is unknown to the system or if it was changed since the last connection the Ssh object will return an error. To connect anyway and store the host key in the registry for future connections the 'AcceptHostKey' property can be set.

NOTES:

  • The ActiveXperts Networking Component Ssh object is not thread safe (A process can only have one active session). However, it is possible to run multiple processes with active sessions at once.

The following sample (in VBScript) runs the '/bin/ls' command on host '192.168.1.10' by logging in using a password:

Set objSsh           = CreateObject("AxNetwork.Ssh")            ' Create an Ssh instance
objSsh.Host          = "192.168.1.10"                           ' Hostname or IP address of 
                                                                ' remote UNIX/LINUX machine
objSsh.UserName      = "root"                                   ' Login as 'root'
objSsh.Password      = "topsecret"                              ' Use a password to login
objSsh.Command       = "/bin/ls"                                ' Command to execute
objSsh.ScriptTimeOut = 5000                                     ' Time-out (in milliseconds)
objSsh.Run                                                      ' Execute the command now
WScript.Echo "Run: result = " & objSsh.LastError 
If objSsh.LastError <> 0 Then
  WScript.Echo "Error "  & objSsh.LastError
End If
' YES, command has completed
WScript.Echo "StdErr: " & objSsh.StdErr                         ' Print Standard Error
WScript.Echo "StdOut: " & objSsh.StdOut                         ' Print Standard Output

WScript.Echo "Ready."

The following sample (in VBScript) runs the '/bin/ls' command on host '192.168.1.10' by using a private key file:

Set objSsh           = CreateObject("AxNetwork.Ssh")           ' Create an Ssh instance
objSsh.Host          = "192.168.1.10"                          ' Hostname or IP address of 
                                                               ' remote  UNIX/LINUX machine
objSsh.UserName      = "root"                                  ' Login as 'root'
objSsh.PrivateKeyFile = "c:\files\privkey.ppk"                 ' Use a private key file to login
objSsh.Command       = "/bin/ls"                               ' Command to execute
objSsh.ScriptTimeOut = 5000                                    ' Time-out (in milliseconds)
objSsh.Run                                                     ' Execute the command now
WScript.Echo "Run: result = " & objSsh.LastError 
If objSsh.LastError <> 0 Then
  WScript.Echo "Error "  & objSsh.LastError
Else
  ' YES, command has completed
  WScript.Echo "StdErr: " & objSsh.StdErr                      ' Print Standard Error
  WScript.Echo "StdOut: " & objSsh.StdOut                      ' Print Standard Output
End If
WScript.Echo "Ready."

23.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
LastError Number Out Result of the last called method
Host String In/Out Specifies the host on which to run the command
Port Number In/Out TCP port number to identify a (remote) SSH daemon. Default: 22
UserName String In/Out Specifies the user name to use on the remote host
Password String In/Out Specifies the password to use on the remote host
PrivateKeyFile String In/Out Specifies the private key file to logon to the remote host.
Command String In/Out Specifies the command to run on the remote host
ScriptTimeOut Number In/Out Specifies the number of milliseconds before the command will times out
AcceptHostKey Boolean In/Out Specifies whether to accept an unknown or changed host key
HostFingerprint String Out The Ssh 'Run' method copies the host key fingerprint to this property
StdErr String Out The Ssh 'Run' method copies its standard error to this property
StdOut String Out The Ssh 'Run' method copies its standard output to this property

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objSsh = CreateObject( "AxNetwork.Ssh" )                 ' Create Ssh object
WScript.Echo  "Version: " & objSsh.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objSsh = CreateObject( "AxNetwork.Ssh" )                 ' Create Ssh object
WScript.Echo  "Build: " & objSsh.Build

Module property

Return the module name of the Component.

Example:

Set objSsh = CreateObject( "AxNetwork.Ssh" )        ' Create new instance 
WScript.Echo  "Module: " & objSsh.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objSsh = CreateObject( "AxNetwork.Ssh" )        ' Create instance
WScript.Echo "LicenseStatus: " & objSsh.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objSsh = CreateObject("AxNetwork.Ssh")          ' Create new instance
WScript.Echo "LicenseKey: " & objSsh.LicenseKey

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")         ' Create an Ssh instance
...
objSsh.Run
WScript.Echo "LastError: " & objSsh.LastError

Host property

Type:

String

Description:

Specifies the host on which to run the command.

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")         ' Create an Ssh instance
objSsh.Host          = "server01.domain.dom"
...
objSsh.Command       = "/bin/ls"
objSsh.Run

Port property

Type:

Number

Description:

TCP port number to identify a remote SSH daemon. If you don't specify the 'Port' property, port 22 (default SSH port) is used.

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")            ' Create an Ssh instance
objSsh.Host          = "server01.domain.dom"
objSsh.Port          = 8022                                     ' Use port 8022 instead of 22
...
objSsh.Command       = "/bin/ls"
objSsh.Run

UserName property

Type:

String

Description:

Specifies the user name to use on the remote host. You must also specify either a Password or Private Key to logon to the machine.

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")         ' Create an Ssh instance
objSsh.Host          = "server01.domain.dom"
objSsh.UserName      = "mjohnson"
objSsh.Password      = "topsecret"
objSsh.Command       = "/bin/ls"
objSsh.Run

Password property

Type:

String

Description:

Specifies the password to use on the remote host. If you do not use a password, you must use a Private Key to logon to the machine.

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")         ' Create an Ssh instance
objSsh.Host          = "server01.domain.dom"
objSsh.UserName      = "mjohnson"
objSsh.Password      = "topsecret"
objSsh.Command       = "/bin/ls"
objSsh.Run

PrivateKeyFile property

Type:

String

Description:

Specifies the private key file to use on the remote host. If you do not use a private key, you must use a Password to logon to the machine.

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")         ' Create an Ssh instance
objSsh.Host          = "server01.domain.dom"
objSsh.UserName      = "mjohnson"
objSsh.PrivateKeyFile= "c:\keys\root.ppk"
objSsh.Command       = "/bin/ls"
objSsh.Run

Command property

Type:

String

Description:

Specifies the command to run on the remote host.

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")         ' Create an Ssh instance
objSsh.Command       = "/bin/ls"
objSsh.Host          = "server01.domain.dom"
objSsh.UserName      = "mjohnson"
objSsh.Password      = "topsecret"
objSsh.Run

ScriptTimeOut property

Type:

Number

Description:

Specifies the number of milliseconds before the command will time out.

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")            ' Create an Ssh instance
objSsh.Host          = "server01.domain.dom"
objSsh.UserName      = "mjohnson"
objSsh.Password      = "topsecret"
objSsh.Command       = "/bin/ls"
objSsh.ScriptTimeOut = 6000                                     ' Timeout after 6000 
                                                                ' milliseconds
objSsh.Run

AcceptHostKey property

Type:

Boolean

Description:

Specifies whether to accept an unknown or changed host key and add it to the registry. Leaving this property set to true when connecting to unknown or untrusted hosts poses a security risk.

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")         ' Create an Ssh instance
...
objSsh.AcceptHostKey = true
objSsh.Run

HostFingerprint property

Type:

String

Description:

The Ssh 'Run' method copies the host key fingerprint to this property

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")         ' Create an Ssh instance
...
objSsh.Run
WScript.Echo "Host key fingerprint: " & objSsh.HostFingerprint

StdErr property

Type:

String

Description:

Ssh connects to the command. Ssh copies its standard error of the remote command to the 'StdErr' property.

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")         ' Create an Ssh instance
...
objSsh.Run
If( objSsh.LastError = 0 ) Then
  WScript.Echo "StdErr: " & objSsh.StdErr
End

StdOut property

Type:

String

Description:

Ssh connects to the command. Ssh copies its standard out of the remote command to the 'StdOut' property.

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")         ' Create an Ssh instance
objSsh.Run
If( objSsh.LastError = 0 ) Then
  WScript.Echo "StdOut: " & objSsh.StdOut
End

23.3. Methods

Methods

Method Description
Clear Reset all properties to the default values
Run Run the command on the remote host
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval
Activate Activate Software

Clear method

Description:

Reset all properties to the initial values. Use this method when you make consecutive calls to the Run method. It resets all properties

Parameters:

  • None

Return value:

Always 0.

Example:

Set objSsh = CreateObject("AxNetwork.Ssh")                      ' Create an Ssh instance
...
objSsh.Run
objSsh.Clear                                                    ' Resets properties
' Set new property values
...
objSsh.Run
objSsh.Clear
...

Run method

Description:

Run the command on the remote host.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")         ' Create an Ssh instance
objSsh.Host          = "192.168.1.10"
objSsh.UserName      = "mjohnson"
objSsh.Password      = "topsecret"
objSsh.Command       = "/bin/ls"
objSsh.Run
WScript.Echo "Run: result = " & objSsh.LastError

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objSsh           = CreateObject("AxNetwork.Ssh")         ' Create an Ssh instance
objSsh.Host          = "192.168.1.10"
objSsh.UserName      = "mjohnson"
objSsh.Password      = "topsecret"
objSsh.Command       = "/bin/ls"
objSsh.Run
WScript.Echo "Error description: " & objSsh.GetErrorDescription( objSsh.LastError )

Sleep method

Description:

This method can be used in your script anywhere you want. Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to suspend

Return value:

Always 0.

Example:

Set objSsh         = CreateObject( "AxNetwork.Ssh" )         ' Create Ssh object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" ) ' Create constants object
...
objSsh.Sleep 500

Activate method

Description:

This method activates the ActiveXperts Networking Component. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objSsh = CreateObject( "AxNetwork.Ssh" ) ' Create Ssh object
objSsh.Activate "xyz", True                  ' Substitute xyz by your own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call
' Activate each time the product is started

24. Tcp

24.1. Introduction

The ActiveXperts Networking Component Tcp object is based on the Transport Control protocol (TCP) protocol. Transport Control Protocol is a Transport Layer host-to-host protocol that provides reliable, connection-oriented service for IP traffic. TCP transports a stream of data in both directions between end stations. TCP does this by breaking the data into segments for transmission across a network running Internet Protocol.

You can use the ActiveXperts Networking Component Tcp object basically for two purposes:

  • To create your own client/server applications; your server-application listens for an incoming connection on a specific port, while your client application makes a connection to it; client and server can do bidirectional communication, with support for ASCII and binary data, in your LAN or through the internet;
  • To automate Telnet sessions; for instance, network switches are usually configured manually from a telnet session. You can use ActiveXperts Networking Component to automate these Telnet sessions, hiding passwords and specific configuration menu's from the operators.

24.2. Client Server Communications

To establish a connection between two machines, one must act as a server and one must act as a client.
The server process waits for a client to connect. It listens on a port for an incoming connection of a client.
The client doesn't listen at all; it simply connects to a port on the server.
After a connection is established, there's no difference between client and server anymore. They can both send and receive, and they can both disconnect the session.

In order to communicate, the server must first create a socket object, and then 'listen' on a specific TCP port to wait for an incoming connection:

Set objTcp       = CreateObject( "AxNetwork.Tcp" )              ' Create Tcp object
Set objConstants = CreateObject( "AxNetwork.NwConstants" )      ' Create constants object
objTcp.StartListening 1500                                      ' listen on port 1500 for 
                                                                ' incoming connection

Then, the server must wait until a connection is established, i.e. when the state of the connection changes from nwSOCKET_CONNSTATE_LISTENING to nwSOCKET_CONNSTATE_CONNECTED:

Do While objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_LISTENING
Loop
If objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_CONNECTED Then
  ' YES, connection established.
End If

Once the connection has been established, server and client can communicate with eachother. They can both send and receive. To receive information, use the ReceiveString method:

Do While objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_CONNECTED
  str = objTcp.ReceiveString
Loop

Each time you call a method, you can check the result by checking the LastError property. For instance:

Set objTcp       = CreateObject( "AxNetwork.Tcp" )              ' Create Tcp object
Set objConstants = CreateObject( "AxNetwork.NwConstants" )      ' Create constants object
objTcp.StartListening 1500                                      ' listen on port 1500 for 
                                                                ' incoming connection
If objTcp.LastError = 0 Then
   ' Yes, socket is listening on the specific port for an incoming connection
End If

On the client side, the client must connect to a server on a specific server-port:

Set objTcp       = CreateObject( "AxNetwork.Tcp" )              ' Create Tcp object
Set objConstants = CreateObject( "AxNetwork.NwConstants" )      ' Create constants object
objTcp.Connect "remoteserver", 1500                             ' connect on port 1500
If objTcp.LastError = 0 Then
  ' YES, connection established
End If

Now, client and server are peers. They can both send and receive. They can send in the following way:

objTcp.SendData "This is a message from client.vbs."            ' Send data

A process can disconnect the session anytime they want:

objTcp.Disconnect                                               ' Disconnect

24.3. Telnet communications

Use the ActiveXperts Networking Component Tcp object to establish a telnet session to a server or device and read its contents or configuration, for instance:

  • To log on to a mail server and list all e-mails, and delete the ones that match a pre-defined pattern;
  • To log on to a switch or router and make changes to the configuration, automatically;
  • To log on to a telnet server and run a pre-defined command sequence;
  • To log on to an IT temperature device and read the temperature;
  • To log on to a print server and reboot it.

The following sample (in VBScript) reads information from the www.activexperts.com/network-component/demopage page:

Set objTcp       = CreateObject("AxNetwork.Tcp")                ' Create Tcp object
Set objConstants = CreateObject("AxNetwork.NwConstants")        ' Create constants object
objTcp.Protocol  = objConstants.nwSOCKET_PROTOCOL_TELNET        ' Telnet protocol
objTcp.Connect "www.activexperts.com", 80                       ' Connect on port 80 to 
                                                                ' remote server
WScript.Echo "Connect, result: " & objTcp.LastError
If objTcp.LastError <> 0 Then
  WScript.Quit
End If

If objTcp.ConnectionState = nwSOCKET_CONNSTATE_CONNECTED Then.
  WScript.Echo "Connection established" & vbCrLf
  strReceived = ""
  nCounter = nCounter + 1
  objTcp.Sleep 1000

  objTcp.SendString "GET /network-component/demopage/ HTTP/1.1"       ' Send data
  objTcp.SendString "Host: www.activexperts.com"                ' Send data	
  objTcp.SendString ""                                          ' Send data (only CRLF)

  objTcp.Sleep 1000

  If objTcp.HasData Then
    strReceived = objTcp.ReceiveString                          ' Receive data	
    WScript.Echo "RECV: " & strReceived
  End If
  objTcp.Sleep 1000
  objTcp.Disconnect                                             ' Disconnect
End If

24.4. Properties

Properties

Property Type Read/Write Description
Version String Out
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
Protocol Number In/Out The protocol to be used
NewLine String In/Out The character sequence that forms a newline
ConnectionState Number Out The state of the connection
IOTimeout Number In/Out Maximum time of read operations
RemoteAddress String Out The IP address and port number of the remote machine
IPVersion Number In/Out Sets whether to use IPv4 or IPv6 for in- and outgoing connections
LastError Number Out Result of the last called method
LogFile String In/Out Log file; use it for troubleshooting purposes

Version property

Build property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objTcp = CreateObject( "AxNetwork.Tcp" )                 ' Create Tcp object
WScript.Echo  "Build: " & objTcp.Build

Module property

Return the module name of the Component.

Example:

Set objTcp = CreateObject( "AxNetwork.Tcp" )        ' Create new instance 
WScript.Echo  "Module: " & objTcp.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objTcp = CreateObject( "AxNetwork.Tcp" )        ' Create instance
WScript.Echo "LicenseStatus: " & objTcp.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objTcp = CreateObject("AxNetwork.Tcp")          ' Create new instance
WScript.Echo "LicenseKey: " & objTcp.LicenseKey

Protocol property

Type:

Number

Description:

The protocol to be used. Can be either nwSOCKET_PROTOCOL_RAW for TCP/IP without supplemental on top, or nwSOCKET_PROTOCOL_TELNET. The property is read/write.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
objTcp.Protocol = objConstants.nwSOCKET_PROTOCOL_TELNET         ' Use telnet protocol
objTcp.Connect "server.mydomain.com", 23
Response.Write "Connect, result: " & objTcp.LastError

NewLine property

Type:

String

Description:

The character sequence that forms a newline. Default value: the CRLF (carriage return / linefeed) string. Most frequent used newline strings:

  • CR (carriage return) - a string containing only the ASCII-13 character (in C: "\r"; in VB: vbCr )
  • LF (linefeed) - a string containing only the ASCII-10 character (in C: "\n"; in VB: vbLf )
  • CRLF (carriage return / linefeed) - a string containing the ASCII-13, ASCII-10 sequence (in C: "\r\n"; in VB: vbCrLf )

A newline is used internally by two methods:

  • ReceiveString - bytes are read from the socket until a newline is detected;
  • SendString - bytes are written to the socket. Finally a newline is sent.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
...
objTcp.Connect "192.168.1.1", 8081                              ' Connect
If objTcp.LastError = 0 Then
  objTcp.NewLine  = vbCr                                        ' Use CR in the subsequent 
                                                                ' ReceiveString/SendString calls
                                                                ' transmitted by the WriteString
                                                                ' method
  objTcp.SendString "Hello"
  If objTcp.LastError = 0 Then
    WScript.Echo "SendString was successful"
  Else
    WScript.Echo "SendString failed"
  End If
  objTcp.Disconnect
End If

ConnectionState property

Type:

Number

Description:

The state of the connection. There are 3 valid Connection States. The property is read-only; you cannot assign a value to it.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
objTcp.StartListening 8081                                      ' Create Tcp object        
If objTcp.LastError <> 0 Then
   WScript.Quit
End If
...
Do While objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_LISTENING
  objTcp.Sleep 1000
Loop
If objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_CONNECTED Then
  ' YES, connection established.
End If

IOTimeout property

Type:

Number

Description:

Maximum IO timeout for read operations (specified in milliseconds). Increase this value when incomplete data is received.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
...
objTcp.Connect "192.168.1.1", 8081                              ' Connect to 192.168.1.1 
                                                                ' on port 8081
WScript.Echo "Connect, result: " & objTcp.LastError             ' Print the result
...
objTcp.IOTimeout = 1000                                         ' Set IO timeout to 1000ms
...
Wscript.Echo objTcp.ReadString

RemoteAddress property

Type:

String

Description:

The IP address and port of the remote party that you are connected to.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
...
objTcp.Connect "192.168.1.1", 8081                              ' Connect to 192.168.1.1 
                                                                ' on port 8081
WScript.Echo "Connect, result: " & objTcp.LastError             ' Print the result
If( objTcp.LastError = 0 And _
  objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_CONNECTED ) Then
    WScript.Echo "Connecteed to remote party: " & _
    objTcp.RemoteAddress                                        ' IP:Port of the remote party
End If

IPVersion property

Type:

Number

Description:

Sets whether to use IPv4 or IPv6 for in- and outgoing connections

The default mode is nwSOCKET_IPVERSION_IP6IP4 which means the software will first try to connect using IPv6 (if the DNS lookup results in a IPv6 address) and in case of failure will try to connect using IPv4.

You can force using IPv4 or IPv6 by using the nwSOCKET_IPVERSION_IP6 or nwSOCKET_IPVERSION_IP4 mode.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
Set objConstants   = CreateObject( "AxNetwork.ANwConstants")
...
objTcp.IPVersion = objConstants.nwSOCKET_IPVERSION_IP6
objTcp.Connect "localhost", 8081                                ' Connect to ::1 using IPv6 
                                                                ' on port 8081
WScript.Echo "Connect, result: " & objTcp.LastError             ' Print the result
If( objTcp.LastError = 0 And _
  objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_CONNECTED ) Then
    WScript.Echo "Connecteed to remote party: " & _
    objTcp.RemoteAddress                                        ' IP:Port of the remote party
End If

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objTcp     = CreateObject( "AxNetwork.Tcp" )             ' Create Tcp object
objTcp.Connect "server.mydomain.com", 8081
Response.Write "Connect, result: " & objTcp.LastError

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all operations will be written to this log file.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
objTcp.LogFile     = "c:\file.log"
objTcp.Connect "192.168.1.1", 8081                              ' Connect to 192.168.1.1 
                                                                ' on port 8081
WScript.Echo "Connect, result: " & objTcp.LastError             ' Print the result
...

24.5. Methods

Methods

Method Description
Connect Connect to a (remote) server
Disconnect Disconnect a connected session
SendString Send a string of ASCII data over the network
SendByte Send a single byte over the network
SendBytes Send raw data over the network
StartListening Start listening for an incoming connection on a specified port
StopListening Stop listening for an incoming connection
HasData Is there data available on the socket?
ReceiveString Receive incoming ASCII data on the socket
ReceiveBytes Receive incoming binary data on the socket
ReceiveByte Receive a single byte on the socket
Sleep Suspends the execution of the object for at least the specified interval
GetErrorDescription Get the description of the given error
Activate Activate the product

Connect method

Description:

Make a connection to a (remote) server on a TCP port.

Parameters:

  • Host; DNS hostname, a NetBIOS name or an IP address
  • TCP port

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
...
objTcp.Connect "192.168.1.1", 8081                              ' Connect to 192.168.1.1 
                                                                ' on port 8081
WScript.Echo "Connect, result: " & objTcp.LastError             ' Print the result

Example:

objTcp.Connect "myserver", 8081

Disconnect method

Description:

Disconnect an active TCP connection.
The method doesn't require any parameters.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
...
objTcp.Connect "192.168.1.1", 8081                              ' Connect
If objTcp.LastError = 0 Then
  objTcp.SendData "Hello"
  objTcp.Disconnect                                             ' Disconnect
End If

SendString method

Description:

This method sends a string of printable ASCII data to the (remote) server.
Telnet methods need a NewLine after the data string. ActiveXperts Networking Component will automatically append the NewLine to the string.
Use the SendByte or SendBytes methods to send binary data or strings without NewLine sequence over the network.

Parameters:

  • Datastring - the string you want to send

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
...
objTcp.Connect "192.168.1.1", 8081                              ' Connect
If objTcp.LastError = 0 Then
  objTcp.SendString "Hello"
  If objTcp.LastError = 0 Then
    WScript.Echo "SendString was successful"
  Else
    WScript.Echo "SendString failed"
  End If
  objTcp.Disconnect
End If

SendByte method

Description:

This method sends a single byte over the network. To send multiple bytes at once, use the SendBytes method. SendByte is ideal to send binary data; for ASCII data, it's recommended to use the SendString method.

Parameters:

  • Byte - the byte you want to send over the network

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
...
objTcp.Connect "192.168.1.1", 8081
If objTcp.LastError = 0 Then
  objTcp.SendByte &H01                                          ' Send one byte
  objTcp.SendByte &H04                                          ' Send one byte
  objTcp.SendByte &H00                                          ' Send one byte
End If

SendBytes method

Description:

This method sends the specified bytes over the network.
Use the 'SendBytes' method to send binary data. To send ASCII (displayable) data, use the SendString method.

Parameters:

  • Datastring - the data you want to send.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
...
objTcp.Connect "192.168.1.1", 8081
If objTcp.LastError = 0 Then
  objTcp.SendBytes "Hello"                                      ' Send a stream of bytes
End If

StartListening method

Description:

This method starts a new listening thread. If the functon succeeds, the ConnectionState will be set to nwSOCKET_CONNSTATE_LISTENING.

Parameters:

  • Port; the port number to listen on
  • IPv6; use this boolean to specify whether to listen on IPv6

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )         ' Create Tcp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" ) ' Create constants object
objTcp.StartListening 1500, true                             ' Start listening on IPv6 port 1500
If objTcp.LastError <> 0 Then
   WScript.Quit
End If
Do While objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_LISTENING
   objTcp.Sleep 1000                                         ' Still waiting for 
                                                             ' the incoming call
Loop
If objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_CONNECTED Then
   ' YES, connection established
   objTcp.Disconnect
End If

StopListening method

Description:

This method stops a listening thread. If the method succeeds, the ConnectionState will change from nwSOCKET_CONNSTATE_LISTENING to nwSOCKET_CONNSTATE_DISCONNECTED. There are no parameters required.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
...
objTcp.StartListening 15000                                     ' Wait for 15 seconds for 
                                                                ' an incoming connection
If objTcp.LastError = 0 Then
  objTcp.StopListening                                          ' Connection established; 
                                                                ' disconnect now
End If

HasData method

Description:

Check if there's incoming data available.

Parameters:

  • None

Return value:

True if there's data available; otherwise False.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
Do While objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_CONNECTED
  If objTcp.HasData Then                                        ' Data available ?
    str = objTcp.ReceiveString
    WScript.Echo "Received: " & str
    objTcp.Sleep 100
  End If
Loop

ReceiveString method

Description:

Read ASCII data from socket until a NewLine is read from the device or a timeout has elapsed.
NOTE: Use the ReceiveBytes or ReceiveByte methods to receive binary data from the (remote) computer).

Parameters:

  • None

Return value:

Empty string if there's no incoming data available; otherwise, the ASCII string that was read from the socket. Check LastError property to see if the method was completed successfully.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
Do While objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_CONNECTED
  If objTcp.HasData Then
    str = objTcp.ReceiveString
    WScript.Echo "Received: " & str
    objTcp.Sleep 100
  End If
Loop

ReceiveBytes method

Description:

Read binary data from socket (use the ReceiveString method to receive ASCII data from the network).
ReceiveBytes receives and returns all the binary data from the network.

Parameters:

  • None

Return value:

The received datastring. Check LastError property to see if the method was completed successfully.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
If objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_CONNECTED Then
  If objTcp.HasData Then
    WScript.Echo objTcp.ReceiveBytes                            ' Receive stream of bytes
  End If
End If

ReceiveByte method

Description:

Receive a single byte of binary data from the socket. Use the ReceiveBytes method to receive all binary data from the (remote) computer.

Parameters:

  • None

Return value:

The byte received. Check LastError property to see if the method was completed successfully.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )         ' Create Tcp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" ) ' Create constants object
...
If objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_CONNECTED Then
  While objTcp.HasData 
    WScript.Echo "Received Byte: " & objTcp.ReceiveByte 
  WEnd
End If

Sleep method

Description:

This method can be used in your script anywhere you want; Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to hold

Return value:

Always 0.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
Do while objTcp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_CONNECTED
  objTcp.Sleep 500                                              ' Hold for 500 msec
  str = objTcp.ReceiveString
Loop

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objTcp      = CreateObject( "AxNetwork.Tcp" )               ' Create Tcp object
...
objTcp.Connect "www.thisdoesnotexist.com", 1234
WScript.Echo "LastError: " & objTcp.LastError
WScript.Echo "Error description: " & objTcp.GetErrorDescription( objTcp.LastError )

Activate method

Description:

This method activates the ActiveXperts Networking Component. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objTcp         = CreateObject( "AxNetwork.Tcp" )            ' Create Tcp object
objTcp.Activate "xyz", True                                     ' Substitute xyz by 
                                                                ' your own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call
' Activate each time the product is started.

25. TftpServer

25.1. Introduction

The ActiveXperts Networking Component TftpServer object is based on the Trivial File Transfer Protocol (TFTP) protocol.

TFTP is a forerunner protocol of FTP. The TFTP protocol is basically used for information transfer from a server to a client or vice versa. TFTP is intended to be used when bootstrapping diskless systems are used. This is also used by memory less devices like routers, switches, etc. to get their boot strap information from their servers. TFTP protocol uses UDP for transferring files between server and the client and uses port "69" to transfer, by default. When TFTP is used, the file that is getting transferred is split up into packets each containing 512 bytes of data. The completion of the transfer is informed to the receiver by sending a packet that has 0-511 bytes. The tranfer mode is either ASCII or binary.

The following sample (VBScript) shows how the TftpServer object can be used to download a file from an TFTP server:

Set objTftpServer = CreateObject( "AxNetwork.TftpServer" ) 

objTftpServer.Get "10.1.1.10", "/folder1/file.txt", _
  "c:\\file.txt"                                                ' Download file,save it locally 
Wscript.Echo "Get, result: " & objTftpServer.LastError 
If( objTftpServer.LastError <> 0 ) Then                         ' If download failed then quit
  WScript.Quit
End If

WScript.Echo "Packets received: " & _
  objTftpServer.PacketsReceived                                 ' Print download statistics
WScript.Echo "Bytes received: "   & _
  objTftpServer.BytesReceived                                   ' Print download statistics

25.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
HostPort Number In/Out UDP port of the remote TFTP server. Default: 69
BinaryTransfer Boolean In/Out Specifies how to transfer files: binary (default) or ASCII
LastError Number Out Result of the last called method
LogFile String In/Out Log file that can be used for troubleshooting purposes

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objTftpServer    = CreateObject( "AxNetwork.Tftp" )      ' Create Tftp object
WScript.Echo"Version: " & objTftpServer.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objTftpServer = CreateObject( "AxNetwork.TftpServer" )        ' Create a new TftpServer 
                                                                  ' object
WScript.Echo  "Build: " & objTftpServer.Build

Module property

Return the module name of the Component.

Example:

Set objTftpServer = CreateObject( "AxNetwork.TftpServer" )        ' Create new instance 
WScript.Echo  "Module: " & objTftpServer.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objTftpServer = CreateObject( "AxNetwork.TftpServer" )        ' Create instance
WScript.Echo "LicenseStatus: " & objTftpServer.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objTftpServer = CreateObject("AxNetwork.TftpServer")          ' Create new instance
WScript.Echo "LicenseKey: " & objTftpServer.LicenseKey

HostPort property

Type:

Number

Description:

UDP port number to identify a (remote) TFTP server. If you don't specify the 'HostPort' property, port 69 (default TFTP port) is used.

Example:

Set objTftpServer = CreateObject( "AxNetwork.TftpServer" )      ' Create a new TftpServer 
                                                                ' instance
...
objTftpServer.HostPort = 8069                                   ' Use port 8069 instead of 
                                                                ' default port 69
objTftpServer.Get "10.1.1.10", "/file.txt"                      ' Download a file
...

BinaryTransfer property

Type:

Boolean

Description:

Specifies the way files are transfered when downloading (Get) or uploading (Put) files. Default value: True, indicating that files are tranferred in binary mode by default.

Example:

Set objTftpServer = CreateObject( "AxNetwork.TftpServer" )       ' Create a new TftpServer 
                                                                 ' instance
...
objTftpServer.BinaryMode = False                                 ' Transfer files in ASCII 
                                                                 ' mode when using Get/Put
objTftpServer.Get "10.1.1.10", "/file.txt"                       ' Download a file in ASCII mode

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objTftpServer = CreateObject( "AxNetwork.TftpServer" )       ' Create a new TftpServer 
                                                                 ' instance
...
objTftpServer.Get "10.1.1.10", "/file.txt"                       ' Download a file
WScript.Echo "LastError: " & objTftpServer.LastError
...

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all TFTP operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all TFTP operations will be written to this log file.

Example:

Set objTftpServer = CreateObject( "AxNetwork.TftpServer" )       ' Create a new TftpServer 
                                                                 ' instance
objTftpServer.LogFile = "C:\Tftp.log"                            ' Write all TFTP operations 
                                                                 ' to the specified log file
...
objTftpServer.Get "10.1.1.10", "/file.txt"                       ' Download a file
...

25.3. Methods

Methods

Method Description
Clear Reset all properties to their default values
Get Download a file from a TFTP host
Put Upload a file to a TFTP host
GetErrorDescription Get the description of the given error
Activate Suspends the execution of the object for at least the specified interval

Clear method

Description:

Resets all properties to the initial, default values.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objTftpServer = CreateObject( "AxNetwork.TftpServer" )       ' Create a new TftpServer 
                                                                 ' instance
objTftpServer.Get "10.1.1.10", "/file1.txt"                      ' Download a file
...
objTftpServer.Clear                                              ' Clear properties
objTftpServer.Get "10.1.1.10", "/file2.txt"                      ' Download a file

Get method

Description:

Download a file from the TFTP server.

Parameters:

  • Name of the file on the remote machine. This can be a fully qualified filename, or a plain filename. When using a plain filename, the file is donloaded from the TFTP root.
  • Name of the file on the local machine (optional). This can be a fully qualified filename, or a plain filename. When using a plain filename, the file will be stored in the current directory. If omitted, the file will be stored with the same filenamen as on the TFTP host, and will be saved in the current directory.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objTftpServer = CreateObject( "AxNetwork.TftpServer" ) 
objTftp.Get "10.1.1.10", "/folder1/file.txt", "c:\\file.txt"    ' Download file, save it 
                                                                ' to a fixed path 
Wscript.Echo "Get, result: " & objTftp.LastError 
If( objTftp.LastError <> 0 ) Then                               ' If download failed then quit
   WScript.Quit
End If

WScript.Echo "Packets received: " & objTftp.PacketsReceived     ' Print download statistics
WScript.Echo "Bytes received: " & objTftp.BytesReceived         ' Print download statistics

Example:

Set objTftpServer = CreateObject( "AxNetwork.TftpServer" ) 

objTftp.Get "10.1.1.10", "/folder1/file.txt"                    ' Download and save file with 
                                                                ' same name in current dir. 
Wscript.Echo "Get, result: " & objTftp.LastError 
If( objTftp.LastError <> 0 ) Then                               ' If download failed then quit
   WScript.Quit
End If

WScript.Echo "Packets received: " & objTftp.PacketsReceived      ' Print download statistics
WScript.Echo "Bytes received: " & objTftp.BytesReceived          ' Print download statistics

Put method

Description:

Upload a file to the TFTP server.

Parameters:

  • Name of the file on the local machine. This can be a fully qualified filename, or a plain filename. When using a plain filename, the file will be uploaded from the current directory
  • Name of the file on the remote machine (optional). Fully qualified filename on the remote TFTP server. If omitted, the file will be saved in the root of the TFTP host with the same name as the local file

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objTftpServer = CreateObject( "AxNetwork.TftpServer" ) 
objTftp.Put "10.1.1.10", "/folder1/file.txt"                     ' Upload and save file with 
                                                                 ' same name in current 
                                                                 ' directory 
Wscript.Echo "Put, result: " & objTftp.LastError 
If( objTftp.LastError <> 0 ) Then                                ' If upload failed then quit
   WScript.Quit
End If

WScript.Echo "Packets sent: " & objTftp.PacketsSent              ' Print upload statistics
WScript.Echo "Bytes sent: " & objTftp.BytesSent                  ' Print upload statistics

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objTftpServer = CreateObject( "AxNetwork.TftpServer" ) 
objTftp.Get "10.1.1.10", "/folder1/file.txt", "c:\\file.txt"    ' Download file, save 
                                                                ' it to a fixed path 
WScript.Echo "LastError: " & objTftpServer.LastError
WScript.Echo "Error description: " & _
  objTftpServer.GetErrorDescription( objTftpServer.LastError )
...

Activate method

Description:

This method activates the ActiveXperts Networking Component. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objTftpServer = CreateObject( "AxNetwork.Tftp" ) ' Create Tftp object
objTftp.Activate "xyz", True    ' Substitute xyz by your own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call
' Activate each time the product is started.

26. TraceRoute

26.1. Introduction

The ActiveXperts Networking Component's TraceRoute object is based on the Internet Control Message Protocol (ICMP). Internet Control Message Protocol (ICMP) is part of the Internet Protocol (IP). It is chiefly used by the operating systems of networked computers to send error messages indicating, for example, that a requested service is not available or that a host or router could not be reached.

One method of ICMP is to detect whether or not a host can be reached, so called pinging. This can be achieved with ActiveXperts Networking Component by using the Icmp object. Tracing a route is an alternative way of using this functionality of ICMP. It can be used to determine the exact route a packet is traveling through the internet.

For example, the route to google.com from a certain point on the internet could be:

Tracing route to www.google.com over max 30 hops

#1, IP: 192.168.31.2 [192.168.31.2], Time: 0ms
#2, IP: 80.65.112.1 [ip112-1.dsl.introweb.nl], Time: 11ms
#3, IP: 62.165.127.51 [AMSIX127-51.introweb.nl], Time: 11ms
#4, IP: *.*.*.* [], Time: 0ms
#5, IP: 209.85.254.90 [209.85.254.90], Time: 11ms
#6, IP: 209.85.255.70 [209.85.255.70], Time: 16ms
#7, IP: 209.85.240.221 [209.85.240.221], Time: 18ms
#8, IP: 209.85.252.83 [209.85.252.83], Time: 17ms
#9, IP: 209.85.243.81 [209.85.243.81], Time: 22ms
#10, IP: 209.85.229.103 [ww-in-f103.1e100.net], Time: 18ms

Done.
        
Disregarding the concept of dynamic routes, one may assume that all data packets sent to google.com will follow this route of nodes.

The route a packet follows can be traced by using the TTL property of an IP data packet. This TTL value starts out with a value that is >=1 and <=255. Every time a packet is sent to the next node in the network (a router or a PC), the TTL value is decreased by 1. As long as this value does not reach 0 before the target node is reached, the packet is delivered. However, if the packet's TTL reaches 0 before the target is reached, the packet is either dropped by the receiving node, or sent back to the source of the packet.

Using this feature, a route can be determined by sending a packet starting with a TTL of 1. When the origin PC sends out the packet, it decreases the TTL to 0, and the first node that receives it - the first node in the route - will send it back. Reading the source address of this return packet, the IP of the first node has been determined. Next, the TTL is set to 2, and the same packet is sent out once more. Now the first node will see a TTL of 1, send it out to the next node, which sees a TTL of 0, and the second node will send the packet back. This way the IP of the second node has been determined. This concept continues until the actual target node returns the packet, completing the route.

The ActiveXperts Networking Component TraceRoute object can be used to determine the path to any reachable host on the internet or local network. The following VBscript example shows how:

Dim objTraceRt
Dim objHop
Set objTraceRt = CreateObject("AxNetwork.TraceRoute")
objTraceRt.ResolveHostName = True
objTraceRt.MaxHops = 30
Set objHop = objTraceRt.FindFirstHop( "www.google.com" )
While( objTraceRt.LastError = 0 )
  WScript.Echo "#" & objHop.Hop & ", IP: " & objHop.IP & _
    " [" & objHop.Host & "], Time: " & objHop.ResponseTime & "ms"
  Set objHop = objTraceRt.FindNextHop
WEnd
	    

As the above example shows, the TraceRoute object works with a FindFirstHop and FindNextHop call, which return objects when no error occurred (always check with LastError). This object has a Hop, IP, ResponseTime and Host property. See TraceHop for more details.

26.2. Properties

Properties

Property Type Read/Write Description
Version String Out Version number of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
LastError Number Out Result of the last called method
LogFile String In/Out Log file; use it for troubleshooting purposes
ResolveHostName Boolean In/Out Determines if IPs are resolved to hostnames
MaxHops Number In/Out Sets the maximum length of the route
BufferSize Number In/Out Sets the ICMP buffer data size
Timeout Number In/Out Sets the ping timeout in milliseconds

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objTraceRoute = CreateObject("AxNetwork.TraceRoute")        ' Create a new TraceRoute 
                                                                ' instance
WScript.Echo  "Version: " & objTraceRoute.Version

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

' Create a new TraceRoute instance
Set objTraceRoute = CreateObject( "AxNetwork.TraceRoute" )     

WScript.Echo  "Build: " & objTraceRoute.Build

Module property

Return the module name of the Component.

Example:

Set objTraceRoute = CreateObject( "AxNetwork.TraceRoute" )        ' Create new instance 
WScript.Echo  "Module: " & objTraceRoute.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objTraceRoute = CreateObject( "AxNetwork.TraceRoute" )        ' Create instance
WScript.Echo "LicenseStatus: " & objTraceRoute.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objTraceRoute = CreateObject("AxNetwork.TraceRoute")          ' Create new instance
WScript.Echo "LicenseKey: " & objTraceRoute.LicenseKey

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Dim objTraceRt
Dim objHop
Set objTraceRt = CreateObject("AxNetwork.TraceRoute")
objTraceRt.ResolveHostName = True
objTraceRt.MaxHops = 30
Set objHop = objTraceRt.FindFirstHop( "www.google.com" )
While( objTraceRt.LastError = 0 )
  WScript.Echo "#" & objHop.Hop & ", IP: " & objHop.IP & _
	" [" & objHop.Host & "], Time: " & objHop.ResponseTime & "ms"
  Set objHop = objTraceRt.FindNextHop
WEnd
	    

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all operations will be written to this log file.

Example:

  Set objTraceRt     = CreateObject( "AxNetwork.TraceRoute" )         ' Create TraceRoute object
  objTraceRt.LogFile = "c:\file.log                                   ' Specify log file
  objTraceRt.Open "server.mydomain.com", 8081, False
  Response.Write "Open, result: " & objTraceRt.LastError

ResolveHostName property

Type:

Boolean

Description:

Determines if FindFirstHop, and FindNextHop calls will try to resolve IP addresses to hostnames. False means do not resolve. True means DNS is used to resolve IP addresses.
When this property is set to True, the Host property in TraceHop objects returned by FindFirstHop and FindNextHop are set to the appropriate hostname (or the IP address when the name could not be resolved.) When this property is set to False, the aforementioned Host property is always empty.

Example:

Dim objTraceRt
Dim objHop
Set objTraceRt = CreateObject("AxNetwork.TraceRoute")
objTraceRt.ResolveHostName = True
objTraceRt.MaxHops = 30
Set objHop = objTraceRt.FindFirstHop( "www.google.com" )
While( objTraceRt.LastError = 0 )
  WScript.Echo "#" & objHop.Hop & ", IP: " & objHop.IP & _
    " [" & objHop.Host & "], Time: " & objHop.ResponseTime & "ms"
  Set objHop = objTraceRt.FindNextHop
WEnd
	        

The default value for this property is False.

MaxHops property

Type:

Number

Description:

Sets the maximum length of the route determined by a TraceRoute object.
When the route is shorter or equal in length to the value for this property, the entire route can be determined. If the entire route is not found after the maximum amount of hops has been reached, the process stops and a specific error is returned.

Example:

Dim objTraceRt
Set objTraceRt = CreateObject("AxNetwork.TraceRoute")
objTraceRt.MaxHops = 5 ' stop tracing after 5 hops
	        

The default value for this property is 100.

BufferSize property

Type:

Number

Description:

ICMP ping packets as they are used in tracerouting may contain arbitrary data buffers, which are to be returned by nodes who reply to the packet. For example, sometimes this value is set to the maximum transmission unit (MTU) to test network components. However, setting this value to anything but the default of 0, may result in certain network nodes responding differently. For example, some nodes might not respond at all with a buffer data size of more than 0.

Example:

Dim objTraceRt
Set objTraceRt = CreateObject("AxNetwork.TraceRoute")
objTraceRt.BufferSize = 128 ' set data size of 128 bytes
	        

The default value for this property is 0.

Timeout property

Type:

Number

Description:

During the process of determining the route to an internet node, the TraceRoute object needs a timeout value to determine how long to keep waiting for a reply. This value is specified in milliseconds.
Note that some nodes will simply never reply when the TTL reaches 0. This explains why sometimes certain nodes cannot be discovered when tracing a route. For an example of this, see the google.com trace in the introduction of the TraceRoute object. The 4th node is set to *.*.*.* since a timeout has occurred. Packets with a TTL of >0 are handled normally, explaining why all consecutive nodes do respond.

Example:

Dim objTraceRt
Set objTraceRt = CreateObject("AxNetwork.TraceRoute")
objTraceRt.Timeout = 250 ' do not wait very long for slow hosts to reply
	        

The default value for this property is 2000 (two seconds.)

26.3. Methods

Methods

Method Description
Sleep Suspends the execution of the object for at least the specified interval
Clear Reset all properties to their default values
FindFirstHop Returns the first hop (node) in the route to the specified host
FindNextHop Returns the next hop (node) in the current route

Sleep method

Description:

This method can be used in your script anywhere you want; Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to hold.

Return value:

Always 0.

Example:

Set objTraceRoute   = CreateObject( "AxNetwork.TraceRoute" )   ' Create TraceRoute object
objTraceRoute.Sleep 500

Clear method

Description:

Resets all properties to the initial, default values.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objTraceRoute   = CreateObject( "AxNetwork.TraceRoute" )   ' Create TraceRoute object
objTraceRoute.Timeout = 1000 ' change timeout to 1 second in stead of default of 2 seconds
objTraceRoute.Clear ' timeout is 2 seconds again!

FindFirstHop method

Description:

Starts the traceroute process to the specified host. This method should be called only once per route. When this method succeeds, call FindNextHop to get all subsequent hops (nodes) in the route. This method stops any route tracing that was previously in progress. In other words, you cannot use the same TraceRoute object to trace routes to more than one host.

Parameters:

  • The host to start tracing a route to.

Return value:

A TraceHop object when the call succeeded, or a empty (Nothing) value when an error has occurred.

Example:

Set objTraceRoute   = CreateObject( "AxNetwork.TraceRoute" )   ' Create TraceRoute object
Set objHop = objTraceRoute.FindFirstHop( "www.google.com" );

FindNextHop method

Description:

Returns the next hop (node) in the current route, which was started with a call to FindStartHop. As long as the maximum number of hops hasn't been reached, and the final target of the route (the host specified to FindStartHop) hasn't been reached either, this method will keep returning the hops (nodes) in between.

Parameters:

  • None.

Return value:

A TraceHop object when the call succeeded, or a empty (Nothing) value when an error has occurred.

Example:

Set objTraceRoute   = CreateObject( "AxNetwork.TraceRoute" )   ' Create TraceRoute object
Set objHop = objTraceRoute.FindFirstHop( "www.google.com" );
While (objTraceRoute.LastError == 0)
  objHop = objTraceRoute.FindNextHop
End While

27. TraceHop

27.1. Introduction

The ActiveXperts Networking Component's TraceHop object is a helper object for the ActiveXperts Networking Component's TraceRoute object. It contains information about the current hop (node) in the trace route process.

27.2. Properties

Properties

Property Type Read/Write Description
IP String In/Out IP address of the node.
Host String In/Out Hostname of the node.
ResponseTime Number In/Out Hostname of the node.
Hop Number In/Out Hop number.

IP property

Type:

String

Description:

Contains the IP address of the current node. When a timeout occurred, the value of this property is "*.*.*.*".

Example:

Set objHop = objTraceRoute.FindFirstHop( "www.google.com" );
WScript.Echo  "IP " & objHop.IP

Host property

Type:

String

Description:

Contains the hostname address of the current node. This value is not always set. It's only set when the TraceRoute object's ResolveHostName property is set to True. Otherwise this value is always empty. When it's not empty, it's either the hostname of the current node, or the IP address of the current node when no name could be resolved.

Example:

...
objTraceRoute.ResolveHostName = True
Set objHop = objTraceRoute.FindFirstHop( "www.google.com" );
WScript.Echo  "Host: " & objHop.Host

ResponseTime property

Type:

Number

Description:

Contains the response time of the host in milliseconds. When a timeout occurred, this value is set to 0ms.

Example:

Set objHop = objTraceRoute.FindFirstHop( "www.google.com" );
WScript.Echo  "Time: " & objHop.ResponseTime

Hop property

Type:

Number

Description:

Contains the number of the current node in the route. The first node receives hop number 1. The second receives number 2, and so on.

Example:

Set objHop = objTraceRoute.FindFirstHop( "www.google.com" );
WScript.Echo  "# " & objHop.Hop

27.3. Methods

This object has no methods.

28. Udp

28.1. Introduction

The ActiveXperts Networking Component Udp object is based on the Transport Control protocol (UDP) protocol. User Datagram Protocol (UDP) is one of the core protocols of the Internet protocol suite. Using UDP, programs on networked computers can send short messages sometimes known as datagrams (using Datagram Sockets) to one another. UDP is sometimes called the Universal Datagram Protocol or Unreliable Datagram Protocol.

UDP does not guarantee reliability or ordering in the way that TCP does. Datagrams may arrive out of order, appear duplicated, or go missing without notice. Avoiding the overhead of checking whether every packet actually arrived makes UDP faster and more efficient, at least for applications that do not need guaranteed delivery. Time-sensitive applications often use UDP because dropped packets are preferable to delayed packets. UDP's stateless nature is also useful for servers that answer small queries from huge numbers of clients. Unlike TCP, UDP supports packet broadcast (sending to all on local network) and multicasting (send to all subscribers).

To send UDP packages between two machines, one (or more) should act as a server and one should act as a client.
The server process(es) wait(s) for a client to get the data, by listening on a port for an incoming packages of a client.
The client doesn't listen at all; it simply send to a port on the server.

In order to communicate, the server must first create a socket object, and then 'listen' on a specific UDP port to wait for incoming data:

Set objUdp       = CreateObject( "AxNetwork.Udp" )              ' Create Udp object
Set objConstants = CreateObject( "AxNetwork.NwConstants" )      ' Create constants object
objUdp.Open "localhost", 1500, True                             
  ' Listen on port 1500
  ' for incoming data;
  ' True indicates: receive
  ' (instead of send)

On the client side, the client must send UDP data to a server on a specific server-port:

Set objUdp       = CreateObject( "AxNetwork.Udp" )              ' Create Udp object
Set objConstants = CreateObject( "AxNetwork.NwConstants" )      ' Create constants object
objUdp.Open "remoteserver", 1500, False                         
  ' Send to remote machine on port 1500. False indicates: no receive but send.
  ' To broadcast, use "255.255.255.255" or an empty string.

Now, the client can send to the server(s) in the following way:

objUdp.SendData "This is a message from client.vbs."            ' Send data

When you're ready, you should close the socket:

objUdp.Close                                                    ' Close

On the client side, the client must connect to a server on a specific server-port:

Set objUdp       = CreateObject( "AxNetwork.Udp" )              ' Create Udp object
Set objConstants = CreateObject( "AxNetwork.NwConstants" )      ' Create constants object
objUdp.Connect "remoteserver", 1500                             ' connect on port 1500
If objUdp.LastError = 0 Then
' YES, connection established
End If

Now, client and server are peers. They can both send and receive. They can send in the following way:

objUdp.SendData "This is a message from client.vbs."            ' Send data

A process can disconnect the session anytime they want:

objUdp.Disconnect                                               ' Disconnect

  ' *** client.vbs (full code, VBScript) ***

' Create a socket instance
Set objUdp       = CreateObject( "AxNetwork.Udp" )
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

' Write some information to console
WScript.Echo "ActiveXperts Networking Component " & objUdp.Version & " demo."
WScript.Echo "Expiration date: " & objUdp.LicenseStatus & vbCrLf

' Open socket to send to port 1500 on remote server
' To broadcast, use "255.255.255.255" or an empty string.
objUdp.Open "localhost", 1500, False
WScript.Echo "Open, result: " & objUdp.LastError & _
" (" & objUdp.GetErrorDescription( objUdp.LastError ) & ")"
If( objUdp.LastError <> 0 ) Then
WScript.Echo "Ready."
WScript.Quit
End If

str = "This is just a message"
objUdp.SendString str                                           ' Send message
WScript.Echo "SendString '" & str & "': result = " & objUdp.LastError
objUdp.Sleep 100

str = "And this is another message"
objUdp.SendString str                                           ' Send another message
WScript.Echo "SendString '" & str & "': result = " & objUdp.LastError
objUdp.Sleep 100

str = "Quit"
objUdp.SendString str                                           ' Send last message
WScript.Echo "SendString '" & str & "': result = " & objUdp.LastError
objUdp.Sleep 100

objUdp.Close                                                    ' And finally, close the socket

  ' *** server.vbs (full code, VBScript) ***

' Create a socket instance
Set objUdp       = CreateObject( "AxNetwork.Udp" )
Set objConstants = CreateObject( "AxNetwork.NwConstants" )

' Write some information to console
WScript.Echo "ActiveXperts Networking Component " & objUdp.Version & " demo."
WScript.Echo "Expiration date: " & objUdp.LicenseStatus & vbCrLf

' Open socket to receive UDP datagrams on port 1500 on this machine
objUdp.Open "localhost", 1500, True
WScript.Echo "Open, result: " & objUdp.LastError & _
" (" & objUdp.GetErrorDescription( objUdp.LastError ) & ")"
If( objUdp.LastError <> 0 ) Then
WScript.Echo "Ready."
WScript.Quit
End If

Do While str <> "Quit"
str = objUdp.ReceiveString                                    ' Receive message
If( objUdp.LastError = 0 And str <> "" ) Then
WScript.Echo "ReceiveString: " & str
End If
objUdp.Sleep ( 100 )
Loop

objUdp.Close

28.2. Properties

Properties

Property Type Read/Write Description
Version String Out Display the version of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
NewLine String In/Out The character sequence that forms a newline
IOTimeout Number In/Out Maximum time of read operations
RemoteAddress String Out The IP address and port number of the remote machine
LastError Number Out Result of the last called method
LogFile String In/Out Log file; use it for troubleshooting purposes

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objUdp    = CreateObject( "AxNetwork.Udp" )              ' Create Udp object
Response.Write "Version: " & objUdp.Version

Build property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objUdp = CreateObject( "AxNetwork.Udp" )                 ' Create Udp object
WScript.Echo  "Build: " & objUdp.Build

Module property

Return the module name of the Component.

Example:

Set objUdp = CreateObject( "AxNetwork.Udp" )        ' Create new instance 
WScript.Echo  "Module: " & objUdp.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objUdp = CreateObject( "AxNetwork.Udp" )        ' Create instance
WScript.Echo "LicenseStatus: " & objUdp.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objUdp = CreateObject("AxNetwork.Udp")          ' Create new instance
WScript.Echo "LicenseKey: " & objUdp.LicenseKey

NewLine property

Type:

String

Description:

The character sequence that forms a newline. Default value: the CRLF (carriage return / linefeed) string. Most frequent used newline strings:

  • CR (carriage return) - a string containing only the ASCII-13 character (in C: "\r"; in VB: vbCr )
  • LF (linefeed) - a string containing only the ASCII-10 character (in C: "\n"; in VB: vbLf )
  • CRLF (carriage return / linefeed) - a string containing the ASCII-13, ASCII-10 sequence (in C: "\r\n"; in VB: vbCrLf )

A newline is used internally by two methods:

  • ReceiveString - bytes are read from the socket until a newline is detected;
  • SendString - bytes are written to the socket. Finally a newline is sent.

Example:

Set objUdp         = CreateObject( "AxNetwork.Udp" )         ' Create Udp object
...
objUdp.Open "192.168.1.1", 8081, False                          
  ' Open an UDP socket to send data.
  ' To broadcast, use "255.255.255.255" or an empty string.

If objUdp.LastError = 0 Then
objUdp.NewLine  = vbCr                                          
  ' Use CR in the subsequent
  ' ReceiveString/SendString calls


  ' transmitted by the
  ' WriteString method

objUdp.SendString "Hello"
End If

IOTimeout property

Type:

Number

Description:

Maximum IO timeout for read operations (specified in milliseconds). Increase this value when incomplete data is received.

Example:

Set objTcp         = CreateObject( "AxNetwork.Udp" )            ' Create Udp object
...
objUdp.Connect "192.168.1.1", 8081                              
  ' Connect to 192.168.1.1
  ' on port 8081

WScript.Echo "Connect, result: " & objTcp.LastError             ' Print the result
...
objUdp.IOTimeout = 1000                                         ' Set IO timeout to 1000ms
...
Wscript.Echo objUdp.ReadString

RemoteAddress property

Type:

String

Description:

The IP address and port of the remote party that you are connected to.

Example:

Set objUdp       = CreateObject( "AxNetwork.Udp" )         ' Create Udp object
...
objUdp.Open "192.168.1.1", 8081, True                           
  ' Open an UDP socket to receive data

If objUdp.LastError = 0 Then
str = objUdp.ReceiveString
If( objUdp.LastError = 0 ) Then
WScript.Echo "Message from:" & objUdp.RemoteAddress        ' Print remote address
End If
End If

LastError property

Type:

Number

Description:

The result of a previous called method. Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objUdp = CreateObject( "AxNetwork.Udp" )                ' Create Udp object
objUdp.Open "server.mydomain.com", 8081, False
Response.Write "Open, result: " & objUdp.LastError          ' print result of 'Open' call

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all operations will be written to this log file.

Example:

Set objUdp     = CreateObject( "AxNetwork.Udp" )                ' Create Udp object
objUdp.LogFile = "c:\file.log                                   ' Specify log file
objUdp.Open "server.mydomain.com", 8081, False
Response.Write "Open, result: " & objUdp.LastError

28.3. Methods

Methods

Method Description
Open Open an UDP socket
Close Close an UDP socket
HasData Is there data available on the socket?
SendString Send a string of ASCII data over the network
SendByte Send a single byte over the network
SendBytes Send raw data over the network
ReceiveString Receive incoming ASCII data on the socket
ReceiveBytes Receive incoming binary data on the socket
ReceiveByte Receive a single byte on the socket
Sleep Suspends the execution of the object for at least the specified interval
GetErrorDescription Get the description of the given error
Activate Activate the product

Open method

Description:

This method opens a socket that can be used to send or receive UDP datagrams.

Parameters:

  • Host - hostname or IP number of the remote host (in case you want to send) or the local host (in case you want to receive);
  • Port - Port number of the remote host (in case you want to send) or the local host (in case you want to receive);
  • Listen - Boolean indicating that you want to use the socket for receiving (True) or sending (False);
  • IPv6 - Boolean indicating that you want to use the socket for receiving on IPv6.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objUdp         = CreateObject( "AxNetwork.Udp" )            ' Create Udp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
objUdp.Open "10.1.1.10", 15000, False                           
  ' Open socket for sending
  ' to 10.1.1.10 on port 15000

If objUdp.LastError <> 0 Then
WScript.Quit
End If
objUdp.SendString "Hello, world."
objUdp.Close                                                    ' Close socket

Close method

Description:

Close a socket that was opened using the Open method.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objUdp         = CreateObject( "AxNetwork.Udp" )            ' Create Udp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
objUdp.Open "10.1.1.10", 15000, False                           
  ' Open socket for sending
  ' to 10.1.1.10 on port 15000

If objUdp.LastError <> 0 Then
WScript.Quit
End If
objUdp.SendString "Hello, world."
objUdp.Close                                                    ' Close socket
End If

HasData method

Description:

Check if there's incoming data available.

Parameters:

  • None

Return value:

True if there's data available; otherwise False.

Example:

Set objUdp         = CreateObject( "AxNetwork.Udp" )            ' Create Udp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
Do While objUdp.ConnectionState = objConstants.nwSOCKET_CONNSTATE_CONNECTED
If objUdp.HasData Then                                          ' Data available ?
str = objUdp.ReceiveString
WScript.Echo "Received: " & str
objUdp.Sleep 100
End If
Loop

SendString method

Description:

This method sends a string of printable ASCII data to the (remote) server.
Telnet methods need a NewLine after the data string. ActiveXperts Networking Component will automatically append the NewLine to the string.
Use the SendByte or SendBytes methods to send binary data or strings without NewLine sequence over the network.

Parameters:

  • Datastring - the string you want to send

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objUdp         = CreateObject( "AxNetwork.Udp" )            ' Create Udp object
...
objUdp.Open "10.1.1.10", 15000, False                           
  ' Open socket for sending
  ' to 10.1.1.10 on port 15000

If objUdp.LastError = 0 Then
objUdp.SendString "Hello"
If objUdp.LastError = 0 Then
WScript.Echo "SendString was successful"
Else
WScript.Echo "SendString failed"
End If
objUdp.Close
End If

SendByte method

Description:

This method sends a single byte over the network. To send multiple bytes at once, use the SendBytes method. SendByte is ideal to send binary data; for ASCII data, it's recommended to use the SendString method.

Parameters:

  • Byte - the byte you want to send over the network

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objUdp         = CreateObject( "AxNetwork.Udp" )            ' Create Udp object
...
objUdp.Open "10.1.1.10", 15000, False                           
  ' Open socket for sending
  ' to 10.1.1.10 on port 15000

If objUdp.LastError = 0 Then
objUdp.SendByte &H01                                        ' Send one byte
objUdp.SendByte &H04                                        ' Send one byte
objUdp.SendByte &H00                                        ' Send one byte
End If

SendBytes method

Description:

This method sends the specified bytes over the network.
Use the 'SendBytes' method to send binary data. To send ASCII (displayable) data, use the SendString method.

Parameters:

  • Datastring - the data you want to send.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objUdp         = CreateObject( "AxNetwork.Udp" )            ' Create Udp object
...
objUdp.Open "10.1.1.10", 15000, False                           
  ' Open socket for sending
  ' to 10.1.1.10 on port 15000

If objUdp.LastError = 0 Then
objUdp.SendBytes "Hello"                                        ' Send a stream of bytes
End If

ReceiveString method

Description:

Read ASCII data from socket until a NewLine is read from the device or a timeout has elapsed.
NOTE: Use the ReceiveBytes or ReceiveByte methods to receive binary data from the (remote) computer).

Parameters:

  • None

Return value:

Empty string if there's no incoming data available; otherwise, the ASCII string that was read from the socket. Check LastError property to see if the method was completed successfully.

Example:

Set objUdp         = CreateObject( "AxNetwork.Udp" )            ' Create Udp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
objUdp.Open "localhost", 15000, True                            
  ' Open socket for
  ' receiving on port 15000

Do
str = objUdp.ReceiveString                                      
  ' Receive messages in
  ' an endless loop

If( objUdp.LastError = 0 And str <> "" ) Then
WScript.Echo "Received: " & str
objUdp.Sleep 100
End If
Loop

ReceiveBytes method

Description:

Read binary data from socket (use the ReceiveString method to receive ASCII data from the network).
ReceiveBytes receives and returns all the binary data from the network.

Parameters:

  • None

Return value:

The received datastring. Check LastError property to see if the method was completed successfully.

Example:

Set objUdp         = CreateObject( "AxNetwork.Udp" )            ' Create Udp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
objUdp.Open "localhost", 15000, True                            
  ' Open socket for receiving
  ' on port 15000

Do
data = objUdp.ReceiveBytes                                      
  ' Receive messages in
  ' an endless loop

If( objUdp.LastError = 0 And data <> "" ) Then
WScript.Echo "Received: " & data
objUdp.Sleep 100
End If
Loop

ReceiveByte method

Description:

Receive a single byte of binary data from the socket. Use the ReceiveBytes method to receive all binary data from the (remote) computer.

Parameters:

  • None

Return value:

The byte received. Check LastError property to see if the method was completed successfully.

Example:

Set objUdp         = CreateObject( "AxNetwork.Udp" )            ' Create Udp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
objUdp.Open "localhost", 15000, True                            
  ' Open socket for receiving
  ' on port 15000

Do
byte = objUdp.ReceiveByte                                       
  ' Receive messages in
  ' an endless loop

If( objUdp.LastError = 0 And byte <> "" ) Then
WScript.Echo "Received: " & byte
End If
Loop

Sleep method

Description:

This method can be used in your script anywhere you want; Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to hold

Return value:

Always 0.

Example:

Set objUdp         = CreateObject( "AxNetwork.Udp" )            ' Create Udp object
Set objConstants   = CreateObject( "AxNetwork.NwConstants" )    ' Create constants object
...
objUdp.Open "localhost", 15000, True                            
  ' Open socket for receiving
  ' on port 15000

Do
data = objUdp.ReceiveBytes                                      
  ' Receive messages in
  ' an endless loop

If( objUdp.LastError = 0 And data <> "" ) Then
WScript.Echo "Received: " & data
objUdp.Sleep 100
End If
Loop

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objUdp      = CreateObject( "AxNetwork.Udp" )            ' Create Udp object
...
objUdp.Open "www.thisdoesnotexist.forsure", 1234, False
WScript.Echo "LastError: " & objUdp.LastError
WScript.Echo "Error description: " & objUdp.GetErrorDescription( objUdp.LastError )

Activate method

Description:

This method activates the ActiveXperts Networking Component. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

              Set objUdp         = CreateObject( "AxNetwork.Udp" ) ' Create Udp object
              objUdp.Activate "xyz", True                  
                ' Substitute xyz by your own registrationkey
              
              
                ' Pass True to make the activation persistent, so you need to call
                ' Activate only once. If you pass False, you need to call
                ' Activate each time the product is started.
              
            

29. VMware

29.1. Introduction

The VMware interface can be used to test connections to VMware ESX(i) host machines, and to retrieve performance counters. You can use it to determine which virtual machines are running, get the operating system running on those virtual machines and to get performance data such as CPU, memory and disk usage.

HTTPs is used to make a connection to the ESXi host. When connecting you need to supply an username and password.

The following sample (in VBScript) connects to an ESXi host and retrieves a list of virtual machines:


' ********************************************************************
' ActiveXperts Network Component sample - VMware
'   
' Witten by ActiveXperts Software 
'     http://www.activexperts.com
' ********************************************************************


Option Explicit

Dim objVMware, objConstants, fso
Dim strHostName, strVirtualMachine


' Create VMware and NwConstants instances


Set objVMware           = CreateObject( "AxNetwork.VMware" )
Set objConstants        = CreateObject( "AxNetwork.NwConstants" )


' Component info

Wscript.Echo "ActiveXperts Network Component " & objVMware.Version
Wscript.Echo "Build: " & objVMware.Build & vbCrLf & "Module: " & objVMware.Module
WScript.Echo "Expiration date: " & objVMware.LicenseStatus & vbCrLf


' Set Logfile

Set fso = CreateObject("Scripting.FileSystemObject")
objVMware.LogFile = fso.GetSpecialFolder(2) & "\VMware.log"
WScript.Echo "Log file: " & objVMware.LogFile & vbCrLf


' Set ESXi host information

objVMware.Server            = "esx01"
objVMware.ServerAccount     = "root"
objVMware.ServerPassword    = "password"


' Initialize

objVMware.Initialize

WScript.Echo "Initialize: " & objVMware.LastError & " (" & 
                                objVMware.GetErrorDescription( objVMware.LastError ) & ")"
WScript.Echo

If( objVMware.LastError <> 0 ) Then
   WScript.Quit
End If


' Connect

objVMware.Connect

WScript.Echo "Connect: " & objVMware.LastError & " (" & 
                            objVMware.GetErrorDescription( objVMware.LastError ) & ")"
WScript.Echo

If( objVMware.LastError <> 0 ) Then
   WScript.Quit
End If


' List  Machines

WScript.Echo "List of virtual machines on host " & objVMware.Server & " :"
WScript.Echo

strVirtualMachine = objVMware.GetFirstVirtualMachine

While ( objVMware.LastError = 0 )
    WScript.Echo "   " & strVirtualMachine
    strVirtualMachine = objVMware.GetNextVirtualMachine
WEnd


' Disconnect

objVMware.Disconnect 


' Shutdown

objVMware.Shutdown

WScript.Echo
WScript.Echo "Ready."
     

29.2. Properties

Properties

Property Type Read/Write Description
Version String Out Display version information of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
LastError Number Out Result of the last called method
LogFile String In/Out Log file; use it for troubleshooting purposes
Server String In/Out Hostname or IP address of the ESXi host
ServerAccount String In/Out Account used to authenticate with the ESXi host
ServerPassword String In/Out Password used to authenticate with the ESXi host
ProxyServer String In/Out Proxyserver to use to establish an HTTP connection with the ESXi host
ProxyAccount String In/Out Account used to authenticate with the proxyserver
ProxyAccount String In/Out Account used to authenticate with the proxyserver

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
WScript.Echo  "Version: " & objVMware.Version
			

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
WScript.Echo  "Build: " & objVMware.Build

Module property

Return the module name of the Component.

Example:

Set objVMware = CreateObject( "AxNetwork.VMware" )        ' Create new instance 
WScript.Echo  "Module: " & objVMware.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objVMware = CreateObject( "AxNetwork.VMware" )        ' Create instance
WScript.Echo "LicenseStatus: " & objVMware.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")          ' Create new instance
WScript.Echo "LicenseKey: " & objVMware.LicenseKey

LastError property

Type:

Number

Description:

Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Connect ()
...
WScript.Echo "LastError: " & objVMware.LastError

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all operations will be written to this log file.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")        ' Create a new VMware instance
objVMware.LogFile = "c:\file.log"                       ' Set log file
...
objVMware.Connect () 
...
WScript.Echo "LastError: " & objVMware.LastError

Server property

Type:

String

Description:

Sets the hostname or IP address of the ESXi host you want to monitor. Do not add the SDK path of the ESXi host to this string. It will be added by the software.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Server            = "ESX01"
objVMware.ServerAccount     = "root"
objVMware.ServerPassword    = "Testing123"

objVMware.Connect () 
...
WScript.Echo "LastError: " & objVMware.LastError

ServerAccount property

Type:

String

Description:

Sets the account name to use to authenticate with the ESXi host. A valid account name and password are required and need to be set before calling the Connect method.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Server            = "ESX01"
objVMware.ServerAccount     = "root"
objVMware.ServerPassword    = "Testing123"

objVMware.Connect () 
...
WScript.Echo "LastError: " & objVMware.LastError

ServerPassword property

Type:

String

Description:

Sets the password to use to authenticate with the ESXi host. A valid account name and password are required and need to be set before calling the Connect method.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Server            = "ESX01"
objVMware.ServerAccount     = "root"
objVMware.ServerPassword    = "Testing123"

objVMware.Connect () 
...
WScript.Echo "LastError: " & objVMware.LastError

ProxyServer property

Type:

String

Description:

Sets the Proxyserver to use to establish an HTTP connection with the ESXi host. You have to set this property before calling the Connect method.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.ProxyServer       = "proxy.activexperts.intra:8080"
objVMware.ProxyAccount      = "proxyaccount"
objVMware.ProxyPassword     = "proxypassword"

objVMware.Connect () 
...
WScript.Echo "LastError: " & objVMware.LastError

ProxyAccount property

Type:

String

Description:

Sets the account used to authenticate with the proxyserver that is used to establish an HTTP connection with the ESXi host. You have to set this property before calling the Connect method.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.ProxyServer       = "proxy.activexperts.intra:8080"
objVMware.ProxyAccount      = "proxyaccount"
objVMware.ProxyPassword     = "proxypassword"

objVMware.Connect () 
...
WScript.Echo "LastError: " & objVMware.LastError

ProxyAccount property

Type:

String

Description:

Sets the account used to authenticate with the proxyserver that is used to establish an HTTP connection with the ESXi host. You have to set this property before calling the Connect method.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.ProxyServer       = "proxy.activexperts.intra:8080"
objVMware.ProxyAccount      = "proxyaccount"
objVMware.ProxyPassword     = "proxypassword"

objVMware.Connect () 
...
WScript.Echo "LastError: " & objVMware.LastError

29.3. Methods

Methods

Method Description
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval
Activate Activate Software
Initialize Initialize Component
Shutdown Shutdown Component
Connect Connect to ESXi host
Disconnect Disconnect from ESXi host
GetFirstVirtualMachine Get first virtual machine name installed on ESXi host
GetNextVirtualMachine Get next virtual machine name installed on ESXi host
GetOperatingSystem Get operating running on virtual machine
GetFirstCounterID Get ID of first available performance counter
GetNextCounterID Get ID of next available performance counter
GetCounterDescription Get a performance counter's description
GetCounterDescription Get a performance counter's units
GetPerfData Retrieves the value of a performance counter

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
obj VMware.Connect ()
...
WScript.Echo "Error description: " & objVMware.GetErrorDescription( objVMware.LastError )

Sleep method

Description:

This method can be used in your script anywhere you want. Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to suspend

Return value:

Always 0.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Sleep 500

Activate method

Description:

This method activates the ActiveXperts Networking Component. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
objVMware.Activate "xyz", True                  ' Substitute xyz by your own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call
' Activate each time the product is started

Initialize method

Description:

Initializes the component for first use after it has been created. This method has to be called before connecting to an ESXi host.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Initialize ()

...                         ' Do some stuf here

objVMware.Shutdown ()

Shutdown method

Description:

Cleans up any resources used by the component. Do not call this method while still connected to the ESXi host.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

...
objVMware.Initialize ()

...                         ' Do some stuf here

objVMware.Shutdown ()

Connect method

Description:

Connect to ESXi host. A session to the ESXi host is established using HTTPS protocol. Before calling this method, you have to set the Server, ServerAccount and ServerPassword.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Initialize ()

objVMware.Server            = "192.168.32.123"
objVMware.ServerAccount     = "root"
objVMware.ServerPassword    = "Testing123"

objVMware.Connect () 
...
WScript.Echo "LastError: " & objVMware.LastError

Disconnect method

Description:

Disconnect from the ESXi host. The session will be closed.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Initialize ()
...

objVMware.Connect () 
...
WScript.Echo "LastError: " & objVMware.LastError
...
objVMware.Disconnect ()

objVMware.Shutdown ()

GetFirstVirtualMachine method

Description:

Gets the first virtual machine installed on the ESXi host. Use this method together with the GetNextVirtualMachine method to iterate through all installed virtual machines on the host. Before calling this method, you have to connect to the ESXi host by using the Connect method.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Initialize ()

objVMware.Server            = "192.168.32.123"
objVMware.ServerAccount     = "root"
objVMware.ServerPassword    = "Testing123"

objVMware.Connect () 
...
strVirtualMachine = objVMware.GetFirstVirtualMachine ()

While ( objVMware.LastError = 0 )
    WScript.Echo strVirtualMachine
    strVirtualMachine = objVMware.GetNextVirtualMachine ()
WEnd

GetNextVirtualMachine method

Description:

Gets the next virtual machine installed on the ESXi host. Use this method together with the GetNextVirtualMachine method to iterate through all installed virtual machines on the host. Before calling this method, you have to connect to the ESXi host by using the Connect method.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Initialize ()

objVMware.Server            = "192.168.32.123"
objVMware.ServerAccount     = "root"
objVMware.ServerPassword    = "Testing123"

objVMware.Connect () 
...
strVirtualMachine = objVMware.GetFirstVirtualMachine ()

While ( objVMware.LastError = 0 )
    WScript.Echo strVirtualMachine
    strVirtualMachine = objVMware.GetNextVirtualMachine ()
WEnd

GetOperatingSystem method

Description:

Gets the name and version of the operating system running on the selected virtual machine. Before calling this method, you have to connect to the ESXi host by using the Connect method.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Initialize ()

objVMware.Server            = "192.168.32.123"
objVMware.ServerAccount     = "root"
objVMware.ServerPassword    = "Testing123"

objVMware.Connect () 
...
strOperatingSystem = objVMware.GetOperatingSystem ( "VM-WIN7" )

WScript.Echo strOperatingSystem

GetFirstCounterID method

Description:

Gets the ID of the first performance counter supported by the virtualization host. Use this method together with the GetNextCounterID method. Before calling this method, you have to connect to the ESXi host by using the Connect method.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Initialize ()

objVMware.Server            = "192.168.32.123"
objVMware.ServerAccount     = "root"
objVMware.ServerPassword    = "Testing123"

objVMware.Connect () 
...
nCounter = objVMware.GetFirstCounterID ()

While ( objVMware.LastError = 0 )
    WScript.Echo "Performance counter : " & nCounter
    nCounter = objVMware.GetNextCounterID ()
WEnd

objVMware.Disconnect ()

GetNextCounterID method

Description:

Gets the ID of the next performance counter supported by the virtualization host. Use this method together with the GetFirstCounterID method. Before calling this method, you have to connect to the ESXi host by using the Connect method.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Initialize ()

objVMware.Server            = "192.168.32.123"
objVMware.ServerAccount     = "root"
objVMware.ServerPassword    = "Testing123"

objVMware.Connect () 
...
nCounter = objVMware.GetFirstCounterID ()

While ( objVMware.LastError = 0 )
    WScript.Echo "Performance counter : " & nCounter
    nCounter = objVMware.GetNextCounterID ()
WEnd

objVMware.Disconnect ()

GetCounterDescription method

Description:

Gets the description of a performance counter by passing the counter's ID as parameter. Before calling this method, you have to connect to the ESXi host by using the Connect method.

Parameters:

  • Counter ID

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Initialize ()

objVMware.Server            = "192.168.32.123"
objVMware.ServerAccount     = "root"
objVMware.ServerPassword    = "Testing123"

objVMware.Connect () 
...
nCounter = objVMware.GetFirstCounterID ()

While ( objVMware.LastError = 0 )
    WScript.Echo "Performance counter : " & objVMware.GetCounterDescription ( nCounter )
    nCounter = objVMware.GetNextCounterID ()
WEnd

objVMware.Disconnect ()

GetCounterDescription method

Description:

Gets the textual description of the units of the value returned by this performance counter by passing the counter's ID as parameter. Before calling this method, you have to connect to the ESXi host by using the Connect method.

Parameters:

  • Counter ID

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objVMware = CreateObject("AxNetwork.VMware")     ' Create a new VMware instance
...
objVMware.Initialize ()

objVMware.Server            = "192.168.32.123"
objVMware.ServerAccount     = "root"
objVMware.ServerPassword    = "Testing123"

objVMware.Connect () 
...
nCounter = objVMware.GetFirstCounterID ()

While ( objVMware.LastError = 0 )
    WScript.Echo "Performance counter : " & objVMware.GetCounterDescription ( nCounter )
    WScript.Echo "Value               : " & objVMware.GetPerfData ( "", nCounter, "" )
    WScript.Echo "Units               : " & objVMware.GetCounterUnits ( nCounter )
    nCounter = objVMware.GetNextCounterID ()
WEnd

objVMware.Disconnect ()

GetPerfData method

Description:

Retrieves the value of one of the performance counters supported by the virtualization host. For a list of supported counter, please refer to the performance counter constants. Before calling this method, you have to connect to the ESXi host by using the Connect method.

Parameters:

  • Counter ID

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objVMware    = CreateObject("AxNetwork.VMware")       ' Create a new VMware instance
Set objConstants = CreateObject("AxNetwork.NwConstants") ' Create a new Constants instance
...
objVMware.Initialize ()

objVMware.Server            = "192.168.32.123"
objVMware.ServerAccount     = "root"
objVMware.ServerPassword    = "Testing123"

objVMware.Connect () 
...
WScript.Echo "Counter Value = " & objConstants.nwVMWARE_CPU_USAGE
..
objVMware.Disconnect ()

objVMware.Shutdown

30. WOL

30.1. Introduction

A Wake-On-LAN utility has the ability to "power on" a PC remotely. This is accomplished by the generation of a 'Magic Packet' to remotely power on PCs attached to networks. When the remote network adapter hears a 'Magic Packet' created for it?s unique MAC address the network adapter alerts the computer to power on. If Wake-On-Lan has been enabled in the computer?s BIOS settings, the system will power on as if the power button had been pressed.

To accomplish this you will first need to ensure your PC is configured to accept a Wake-On-LAN remote command. You must also identify the IP Address and MAC Address of the remote device. When the device shuts down, it's Network Interface Card (NIC card) is still receiving power, and keeps listening on the network for a 'magic' packet to arrive.

ActiveXperts Networking Component has the ability to send such a "Magic Packet" to power on PCs. Here is a small example (in VBScript) to show how to use the WOL object:

Set objWOL = CreateObject("AxNetwork.WOL")                      ' Create a new WOL instance
objWOL.WakeUp "00-10-4B-BA-7A-51"                               ' Power-up machine based on 
                                                                ' its network MAC address
WScript.Echo "WakeUp: result = " & objWOL.LastError
If( objWOL.LastError <> 0 ) Then
  WScript.Echo "Error " & objWOL.LastError & ": " & _
    objWOL.GetErrorDescription( objWOL.LastError )
End If

30.2. Properties

Properties

Property Type Read/Write Description
Version String Out Display version information of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
LastError Number Out Result of the last called method
LogFile String In/Out Log file; use it for troubleshooting purposes

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objWOL = CreateObject("AxNetwork.WOL")                   ' Create a new WOL instance
WScript.Echo  "Version: " & objWOL.Version
			

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objWOL = CreateObject("AxNetwork.WOL")                   ' Create a new WOL instance
WScript.Echo  "Build: " & objWOL.Build

Module property

Return the module name of the Component.

Example:

Set objWOL = CreateObject( "AxNetwork.WOL" )        ' Create new instance 
WScript.Echo  "Module: " & objWOL.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objWOL = CreateObject( "AxNetwork.WOL" )        ' Create instance
WScript.Echo "LicenseStatus: " & objWOL.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objWOL = CreateObject("AxNetwork.WOL")          ' Create new instance
WScript.Echo "LicenseKey: " & objWOL.LicenseKey

LastError property

Type:

Number

Description:

Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objWOL = CreateObject( "AxNetwork.WOL" )                 ' Create WOL object
...
objWOL.Query() 
WScript.Echo "LastError: " & objWOL.LastError

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all operations will be written to this log file.

Example:

Set objWOL = CreateObject( "AxNetwork.WOL" )                     ' Create WOL object
objWOL.LogFile = "c:\file.log"                                   ' Set log file
...
objWOL.Query() 
WScript.Echo "LastError: " & objWOL.LastError

30.3. Methods

Methods

Method Description
Clear Reset properties to their initial default values
WakeUp Power-on a PC remotely, based on the MAC address
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval
Activate Activate Software

Clear method

Description:

Reset all properties to their initial values. Use this method when you make consecutive calls to the WakeUp method.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objWOL = CreateObject("AxNetwork.WOL")                  ' Create a new WOL instance
objWOL.WakeUp "00-10-4B-BA-7A-51"
WScript.Echo "LastError: " & objWOL.LastError
objWOL.Clear
WScript.Echo "LastError: " & objWOL.LastError               ' Will be 0
objWOL.WakeUp "00-10-4B-BA-7A-51"
...

WakeUp method

Description:

Power on a PC remotely, based on the MAC address.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objWOL = CreateObject("AxNetwork.WOL")                      ' Create a new WOL instance
objWOL.WakeUp "00-10-4B-BA-7A-51"                               ' Power on machine that has 
                                                                ' MAC address 00-10-4B-BA-7A-51
WScript.Echo "LastError: " & objWOL.LastError

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objWOL = CreateObject("AxNetwork.WOL")                   ' Create a new WOL instance
objWOL.WakeUp "00-10-4B-BA-7A-51"
WScript.Echo "LastError: " & objWOL.LastError
WScript.Echo "Error description: " & objWOL.GetErrorDescription( objWOL.LastError )

Sleep method

Description:

This method can be used in your script anywhere you want. Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to suspend

Return value:

Always 0.

Example:

Set objWol = CreateObject( "AxNetwork.WOL" )                 ' Create WOL object
...
objWol.Sleep 500

Activate method

Description:

This method will activate the ActiveXperts Networking Component. A valid registrationcode is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here).

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objWOL = CreateObject( "AxNetwork.WOL" )  ' Create WOL object
objWOL.Activate "xyz", True       ' Substitute xyz by your own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call 
' Activate each time the product is started

31. Xen

31.1. Introduction

The Xen interface can be used to test connections to XenServer host machines, and to retrieve performance counters. You can use it to determine which virtual machines are running, get the operating system running on those virtual machines and to get performance data such as CPU, memory and disk usage.

HTTPs is used to make a connection to the XenServer host. When connecting you need to supply an username and password.

The following sample (in VBScript) connects to an XenServer host and retrieves a list of virtual machines:

' ********************************************************************
' ActiveXperts Network Component sample - XenServer
'   
' Witten by ActiveXperts Software 
'     http://www.activexperts.com
' ********************************************************************

Option Explicit

Dim objXen, objConstants, fso
Dim strHostName, strVirtualMachine

' Create VMware and NwConstants instances
Set objXen          = CreateObject( "AxNetwork.Xen" )
Set objConstants    = CreateObject( "AxNetwork.NwConstants" )

' Component info
Wscript.Echo "ActiveXperts Network Component " & objXen.Version
Wscript.Echo "Build: " & objXen.Build & vbCrLf & "Module: " & objXen.Module
WScript.Echo "Expiration date: " & objXen.LicenseStatus & vbCrLf

' Set Logfile
Set fso = CreateObject("Scripting.FileSystemObject")
objXen.LogFile = fso.GetSpecialFolder(2) & "\Xen.log"
WScript.Echo "Log file: " & objXen.LogFile & vbCrLf

' Set XenServer host information
objXen.Server           = "xen02"
objXen.ServerAccount    = "root"
objXen.ServerPassword   = "password"

' Initialize
objXen.Initialize

WScript.Echo "Initialize: " & objXen.LastError & " (" & 
                                    objXen.GetErrorDescription( objXen.LastError ) & ")"
WScript.Echo

If( objXen.LastError <> 0 ) Then
   WScript.Quit
End If

' Connect
objXen.Connect

WScript.Echo "Connect: " & objXen.LastError & " (" & 
                                objXen.GetErrorDescription( objXen.LastError ) & ")"
WScript.Echo

If( objXen.LastError <> 0 ) Then
   WScript.Quit
End If

' List  Machines
WScript.Echo "List of virtual machines on host " & objXen.Server & " :"
WScript.Echo

strVirtualMachine = objXen.GetFirstVirtualMachine

While ( objXen.LastError = 0 )
    WScript.Echo "   " & strVirtualMachine
    strVirtualMachine = objXen.GetNextVirtualMachine
WEnd

' Disconnect
objXen.Disconnect 

' Shutdown
objXen.Shutdown

WScript.Echo
WScript.Echo "Ready."

31.2. Properties

Properties

Property Type Read/Write Description
Version String Out Display version information of ActiveXperts Networking Component
Build String Out Display build information of ActiveXperts Networking Component
Module String Read Module name of ActiveXperts Network Component
LicenseStatus String Out License Status of ActiveXperts Network Component
LicenseKey String Out License Key of ActiveXperts Network Component
LastError Number Out Result of the last called method
LogFile String In/Out Log file; use it for troubleshooting purposes
Server String In/Out hostname or IP address of the XenServer host
ServerAccount String In/Out Account used to authenticate with the XenServer host
ServerPassword String In/Out Password used to authenticate with the XenServer host
ProxyServer String In/Out Proxyserver to use to establish an HTTP connection with the XenServer host
ProxyAccount String In/Out Account used to authenticate with the proxyserver
ProxyPassword String In/Out Password used to authenticate with the proxyserver

Version property

Type:

String

Description:

Version information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
WScript.Echo  "Version: " & objXen.Version
			

Build property

Type:

String

Description:

Build information of ActiveXperts Networking Component. This property is read-only; you cannot assign a value to it.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
WScript.Echo  "Build: " & objXen.Build

Module property

Return the module name of the Component.

Example:

Set objXen = CreateObject( "AxNetwork.Xen" )        ' Create new instance 
WScript.Echo  "Module: " & objXen.Module
...

LicenseStatus property

Type:

String

Description:

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objXen = CreateObject( "AxNetwork.Xen" )        ' Create instance
WScript.Echo "LicenseStatus: " & objXen.LicenseStatus

LicenseKey property

A license key is required to unlock this component after the trial period has expired. For details, see Product Activation.

Example:

Set objXen = CreateObject("AxNetwork.Xen")          ' Create new instance
WScript.Echo "LicenseKey: " & objXen.LicenseKey

LastError property

Type:

Number

Description:

Use it to check the result of your last method call. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription method provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Initialize ()
...
WScript.Echo "LastError: " & objXen.LastError

LogFile property

Type:

String

Description:

For troubleshooting purposes, you can specify a log file to trace all operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all operations will be written to this log file.

Example:

Set objXen = CreateObject("AxNetwork.Xen")        ' Create a new Xen instance
objXen.LogFile = "c:\file.log"                    ' Set log file
...
objXen.Connect () 
...
WScript.Echo "LastError: " & objXen.LastError

Server property

Type:

String

Description:

Sets the hostname or IP address of the XenServer host you want to monitor. Do not add the SDK path of the XenServer host to this string. It will be added by the software.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Server            = "ESX01"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "Testing123"

objXen.Connect () 
...
WScript.Echo "LastError: " & objXen.LastError

ServerAccount property

Type:

String

Description:

Sets the account name to use to authenticate with the XenServer host. A valid account name and password are required and need to be set before calling the Connect method.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Server            = "XEN02"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "Testing123"

objXen.Connect () 
...
WScript.Echo "LastError: " & objXen.LastError

ServerPassword property

Type:

String

Description:

Sets the password to use to authenticate with the XenServer host. A valid account name and password are required and need to be set before calling the Connect method.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Server            = "XEN02"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "Testing123"

objXen.Connect () 
...
WScript.Echo "LastError: " & objXen.LastError

ProxyServer property

Type:

String

Description:

Sets the Proxyserver to use to establish an HTTP connection with the XenServer host. You have to set this property before calling the Connect method.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.ProxyServer       = "proxy.activexperts.intra:8080"
objXen.ProxyAccount      = "proxyaccount"
objXen.ProxyPassword     = "proxypassword"

objXen.Server            = "XEN02"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "Testing123"

objXen.Connect () 
...
WScript.Echo "LastError: " & objXen.LastError

ProxyAccount property

Type:

String

Description:

Sets the account used to authenticate with the proxyserver that is used to establish an HTTP connection with the XenServer host. You have to set this property before calling the Connect method.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.ProxyServer       = "proxy.activexperts.intra:8080"
objXen.ProxyAccount      = "proxyaccount"
objXen.ProxyPassword     = "proxypassword"

objXen.Server            = "XEN02"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "Testing123"

objXen.Connect () 
...
WScript.Echo "LastError: " & objXen.LastError

ProxyPassword property

Type:

String

Description:

Sets the password used to authenticate with the proxyserver that is used to establish an HTTP connection with the XenServer host. You have to set this property before calling the Connect method.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.ProxyServer       = "proxy.activexperts.intra:8080"
objXen.ProxyAccount      = "proxyaccount"
objXen.ProxyPassword     = "proxypassword"

objXen.Server            = "XEN02"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "Testing123"

objXen.Connect () 
...
WScript.Echo "LastError: " & objXen.LastError

31.3. Methods

Methods

Method Description
GetErrorDescription Get the description of the given error
Sleep Suspends the execution of the object for at least the specified interval
Activate Activate Software
Initialize Initialize Component
Shutdown Shutdown Component
Connect Connect to XenServer host
Disconnect Disconnect from XenServer host
GetFirstVirtualMachine Get first virtual machine name installed on XenServer host
GetNextVirtualMachine Get next virtual machine name installed on XenServer host
GetOperatingSystem Get operating running on virtual machine
GetFirstCounterID Get ID of first available performance counter
GetNextCounterID Get ID of next available performance counter
GetCounterDescription Get a performance counter's description
GetCounterDescription Get a performance counter's units
GetPerfData Retrieves the value of a performance counter
TranslatePerfData Retrieves the value of a performance counter constant

GetErrorDescription method

Description:

GetErrorDescription provides the error description of a given error code.

Parameters:

  • Error code

Return value:

The error description that is associated with the given error code.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
obj Xen.Connect ()
...
WScript.Echo "Error description: " & objXen.GetErrorDescription( objXen.LastError )

Sleep method

Description:

This method can be used in your script anywhere you want. Suspends the execution of the object for at least the specified interval.

Parameters:

  • The number of milliseconds to suspend

Return value:

Always 0.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Sleep 500

Activate method

Description:

This method activates the ActiveXperts Networking Component. A valid registration code is required.

Parameters:

  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' method only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here)

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objXen = CreateObject("AxNetwork.Xen")   ' Create a new Xen instance
objXen.Activate "xyz", True                  ' Substitute xyz by your own registrationkey
' Pass True to make the activation persistent, so you need to call
' Activate only once. If you pass False, you need to call
' Activate each time the product is started

Initialize method

Description:

Initializes the component for first use after it has been created. This method has to be called before connecting to a XenServer host.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

...
objVMware.Initialize ()

... ' Do some stuf here

objVMware.Shutdown ()

Shutdown method

Description:

Cleans up any resources used by the component. Do not call this method while still connected to the XenServer host.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

...
objVMware.Initialize ()

... ' Do some stuf here

objVMware.Shutdown ()

Connect method

Description:

Connect to XenServer host. A session to the XenServer host is established using HTTPS protocol. Before calling this method, you have to set the Server, ServerAccount and ServerPassword.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Initialize ()

objXen.Server            = "192.168.32.123"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "password"

objXen.Connect () 
...
WScript.Echo "LastError: " & objXen.LastError

Disconnect method

Description:

Disconnect from the XenServer host. The session will be closed.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Initialize ()
...

objXen.Connect () 
...
WScript.Echo "LastError: " & objXen.LastError
...
objXen.Disconnect ()

objXen.Shutdown ()

GetFirstVirtualMachine method

Description:

Retrieves the name of the first virtual machine installed on the XenServer host. Use this method together with the GetNextVirtualMachine method to iterate through all installed virtual machines on the host. Before calling this method, you have to connect to the XenServer host by using the Connect method.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Initialize ()

objXen.Server            = "192.168.32.123"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "password"

objXen.Connect () 
...
strVirtualMachine = objXen.GetFirstVirtualMachine ()

While ( objXen.LastError = 0 )
    WScript.Echo strVirtualMachine
    strVirtualMachine = objXen.GetNextVirtualMachine ()
WEnd

GetNextVirtualMachine method

Description:

Gets the next virtual machine installed on the XenServer host. Use this method together with the GetNextVirtualMachine method to iterate through all installed virtual machines on the host. Before calling this method, you have to connect to the XenServer host by using the Connect method.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Initialize ()

objXen.Server            = "192.168.32.123"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "password"

objXen.Connect () 
...
strVirtualMachine = objXen.GetFirstVirtualMachine ()

While ( objXen.LastError = 0 )
    WScript.Echo strVirtualMachine
    strVirtualMachine = objXen.GetNextVirtualMachine ()
WEnd

GetOperatingSystem method

Description:

Gets the name and version of the operating system running on the selected virtual machine. On XenServer, this information is only available when Guest Tools are installed on the Virtual Machine. Before calling this method, you have to connect to the XenServer host by using the Connect method.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Initialize ()

objXen.Server            = "192.168.32.123"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "password"

objXen.Connect () 
...
strOperatingSystem = objXen.GetOperatingSystem ( "VM-WIN7" )

WScript.Echo strOperatingSystem

GetFirstCounterID method

Description:

Gets the Counter ID of the first performance counter supported by the virtualization host. Use this method together with the GetNextCounterID method. Before calling this method, you have to connect to the XenServer host by using the Connect method.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Initialize ()

objXen.Server            = "192.168.32.123"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "password"

objXen.Connect () 
...
nCounter = objXen.GetFirstCounterID ()

While ( objXen.LastError = 0 )
    WScript.Echo "Performance counter : " & nCounter
    nCounter = objXen.GetNextCounterID ()
WEnd

objXen.Disconnect ()

GetNextCounterID method

Description:

Gets the Counter ID of the next performance counter supported by the virtualization host. Use this method together with the GetFirstCounterID method. Before calling this method, you have to connect to the XenServer host by using the Connect method.

Parameters:

  • None

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Initialize ()

objXen.Server            = "192.168.32.123"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "password"

objXen.Connect () 
...
nCounter = objXen.GetFirstCounterID ()

While ( objXen.LastError = 0 )
    WScript.Echo "Performance counter : " & nCounter
    nCounter = objXen.GetNextCounterID ()
WEnd

objXen.Disconnect ()

GetCounterDescription method

Description:

Gets the description of a performance counter by passing the counter's ID as parameter. Before calling this method, you have to connect to the XenServer host by using the Connect method.

Parameters:

  • Counter ID

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Initialize ()

objXen.Server            = "192.168.32.123"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "password"

objXen.Connect () 
...
nCounter = objXen.GetFirstCounterID ()

While ( objXen.LastError = 0 )
    WScript.Echo "Performance counter : " & objXen.GetCounterDescription ( nCounter )
    nCounter = objXen.GetNextCounterID ()
WEnd

objXen.Disconnect ()

GetCounterDescription method

Description:

Gets the textual description of the units of the value returned by this performance counter by passing the counter's ID as parameter. Before calling this method, you have to connect to the XenServer host by using the Connect method.

Parameters:

  • Counter ID

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objXen = CreateObject("AxNetwork.Xen")     ' Create a new Xen instance
...
objXen.Initialize ()

objXen.Server            = "192.168.32.123"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "password"

objXen.Connect () 
...
nCounter = objXen.GetFirstCounterID ()

While ( objXen.LastError = 0 )
    WScript.Echo "Performance counter : " & objXen.GetCounterDescription ( nCounter )
    WScript.Echo "Value               : " & objXen.GetPerfData ( "", nCounter, "" )
    WScript.Echo "Units               : " & objXen.GetCounterUnits ( nCounter )
    nCounter = objXen.GetNextCounterID ()
WEnd

objXen.Disconnect ()

GetPerfData method

Description:

Retrieves the value of one of the performance counters supported by the virtualization host. For a list of supported counter, please refer to the performance counter constants. Before calling this method, you have to connect to the XenServer host by using the Connect method.

Parameters:

  • Counter ID

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objXen    = CreateObject("AxNetwork.Xen")             ' Create a new Xen instance
Set objConstants = CreateObject("AxNetwork.NwConstants") ' Create a new Constants instance
...
objXen.Initialize ()

objXen.Server            = "192.168.32.123"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "password"

objXen.Connect () 
...
WScript.Echo "Counter Value = " & objConstants.nmXEN_CPU_USAGE
..
objXen.Disconnect ()

objXen.Shutdown

TranslatePerfData method

Description:

Retrieves the human readable value of a value returned by either the nmXEN_POWER_STATE or nmXEN_GUESTTOOLS performance counters. For a list of supported values, please refer to the following constants. Before calling this method, you have to connect to the XenServer host by using the Connect method.

Parameters:

  • Counter ID
  • Value

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objXen       = CreateObject("AxNetwork.Xen")         ' Create a new Xen instance
Set objConstants = CreateObject("AxNetwork.NwConstants") ' Create a new Constants instance
...
objXen.Initialize ()

objXen.Server            = "192.168.32.123"
objXen.ServerAccount     = "root"
objXen.ServerPassword    = "password"

objXen.Connect () 
...
nValue = objXen.GetPerfData ( "VM2332", objConstants.nmXEN_POWER_STATE, "" )
WScript.Echo "Counter Value = " & objXen.TranslatePerfData ( objConstants.nmXEN_POWER_STATE, nValue )
..
objXen.Disconnect ()

objXen.Shutdown

32. Constants and Error Codes

32.1. Constants

In ActiveXperts Networking Component, all constants are grouped together in a separate object called NwConstants. You must first create the Constants object before you can actually use constants:

Set objConstants = CreateObject( "AxNetwork.NwConstants" )
WScript.Echo objConstants.nwSOCKET_PROTOCOL_RAW
WScript.Echo objConstants.nwSOCKET_PROTOCOL_TELNET
...
WScript.Echo objConstants.nwSNMP_TYPE_INTEGER
WScript.Echo objConstants.nwSNMP_TYPE_IPADDRESS
...

Socket Protocol values definitions

Constant Value Description
nwSOCKET_PROTOCOL_RAW 1 TCP/IP protocol, without any protocol on top of it
nwSOCKET_PROTOCOL_TELNET 2 Telnet protocol (based on TCP/IP)

Socket Connection States definitions

Constant Value Description
nwSOCKET_CONNSTATE_DISCONNECTED 1 No TCP connection
nwSOCKET_CONNSTATE_LISTENING 2 Waiting for incoming connection
nwSOCKET_CONNSTATE_CONNECTED 3 No TCP connection

Socket IP Versions definitions

Constant Value Description
nwSOCKET_IPVERSION_IP6IP4 0 Try connecting using IPv6, fallback to IPv4 on failure
nwSOCKET_IPVERSION_IP6ONLY 1 Force connecting using IPv6
nwSOCKET_IPVERSION_IP4ONLY 2 Force connecting using IPv4

DNS Record Types definitions

Constant Value Description
nwDNS_TYPE_UNDEFINED 0 Undefined
nwDNS_TYPE_A 1 The A-record is the most basic and the most important DNS record type. They are used to translate human friendly domain names such as "www.jhsoft.com" into IP-addresses such as 212.97.55.136 (machine friendly number
nwDNS_TYPE_NS 2 Authoritative name server. NS-records identify DNS servers responsible (authoritative) for a zone
nwDNS_TYPE_CNAME 5 CNAME-records are domain name aliases. Often computers on the Internet have multiple methods such as web-server, ftp-server, chat-server etc.
nwDNS_TYPE_SOA 6 Start of authority. Each zone contains exactly one SOA-record
nwDNS_TYPE_PTR 12 Domain Name Pointer. PTR-records map IP addresses to domain names (reverse of A-records)
nwDNS_TYPE_MX 15 Mail exchange. MX-records identify mail server(s) responsible for a domain name
nwDNS_TYPE_AAAA 28 IPv6 host address
nwDNS_TYPE_SRV 33 IPv6 host address
nwDNS_TYPE_CERT 37 IPv6 host address
nwDNS_TYPE_ANY 33 Any DNS record

SNMP Authentication Protocol definitions definitions

Constant Value Description
nwSNMP_AUTH_SHA1 0 Authenticate using SHA1 hashing
nwSNMP_AUTH_MD5 1 Authenticate using MD5 hashing

SNMP Privacy Protocol definitions definitions

Constant Value Description
nwSNMP_PRIV_DES 0 Encrypt PDU's using DES encryption
nwSNMP_PRIV_AES 1 Encrypt PDU's using AES128 encryption

SNMP Data Types definitions

Constant Value Description
nwSNMP_TYPE_UNDEFINED 0 Undefined
nwSNMP_TYPE_INTEGER 2 Integer (16 bits)
nwSNMP_TYPE_INTEGER32 2 Integer (32 bits)
nwSNMP_TYPE_BITS 3 Bit stream
nwSNMP_TYPE_OCTETSTRING 4 Octet string
nwSNMP_TYPE_NULL 5 Null
nwSNMP_TYPE_OBJECTIDENTIFIER 6 Object Identifier
nwSNMP_TYPE_IPADDRESS 48 IP address
nwSNMP_TYPE_COUNTER32 64 Counter (32 bits)
nwSNMP_TYPE_GAUGE32 66 Gauge (32 bits)
nwSNMP_TYPE_TIMETICKS 67 Time ticks
nwSNMP_TYPE_OPAQUE 68 Opaque
nwSNMP_TYPE_COUNTER64 70 Counter (64 bits)
nwSNMP_TYPE_UNSIGNED32 71 Unsigned integer (32 bits)

SNMP Protocol Version Identifiers definitions

Constant Value Description
nwSNMP_VERSION_V1 1 SNMP v1 (RFCs 1155-1157)
nwSNMP_VERSION_V2C 2 SNMP v2c (RFCs 1901-1908)
nwSNMP_VERSION_V3 3 SNMP v3 (RFCs 2570-2576)

SNMP Trap Types definitions

Constant Value Description
nwSNMP_TRAP_COLDSTART 0 Cold start
nwSNMP_TRAP_WARMSTART 1 Warm start
nwSNMP_TRAP_LINKDOWN 2 Link down
nwSNMP_TRAP_LINKUP 3 Link up
nwSNMP_TRAP_AUTHFAILURE 4 Authentication failure
nwSNMP_TRAP_EGPNEIGHLOSS 5 Neighbor lost
nwSNMP_TRAP_ENTERSPECIFIC 6 Custom type

SNMP MIB Access constants definitions

Constant Value Description
nwMIB_ACCESS_NOACCESS 0 No access
nwMIB_ACCESS_NOTIFY 1 Notify access
nwMIB_ACCESS_READONLY 2 Read-only access
nwMIB_ACCESS_WRITEONLY 3 Write-only access
nwMIB_ACCESS_READWRITE 4 Rread-write access
nwMIB_ACCESS_READCREATE 5 Read-create access

SNMP MIB Status constants definitions

Constant Value Description
nwMIB_STATUS_CURRENT 0 Current
nwMIB_STATUS_DEPRECATED 1 Deprecated
nwMIB_STATUS_OBSOLETE 2 Obsolete
nwMIB_STATUS_MANDATORY 3 Mandatory

VMware Counter constants definitions

Constant Value Description
nwVMWARE_CPU_USAGE 100 CPU usage in percent
nwVMWARE_MEMORY_USAGE 200 Memory usage in percent
nwVMWARE_MEMORY_AVAILABLE 201 Available memory in MB
nwVMWARE_MEMORY_USED 202 Memory used in MB
nwVMWARE_NETWORK_PACKETSRX 300 Received packets during last interval
nwVMWARE_NETWORK_PACKETSTX 301 Transmitted packets during last interval
nwVMWARE_NETWORK_RATERX 350 Current Network Receiving rate in kbps
nwVMWARE_NETWORK_RATETX 351 Current Network Transmitting rate in kbps
nwVMWARE_DISK_USAGE 400 Current Disk usage in percent
nwVMWARE_DISK_AVAILABLE 401 Available disk space in Mb
nwVMWARE_DISK_USED 402 Used disk space in Mb
nwVMWARE_MACHINE_STATE 500 Determine whether virtual machine is running
nwVMWARE_POWER_STATE 501 Determine whether virtual machine is powered
nwVMWARE_GUESTTOOLS 502 Determine whether VM Guest Tools is running on Virtual Machine

VMware Powerstate constants definitions

Constant Value Description
nwVMWARE_POWERSTATE_INVALID -1 Invalid
nwVMWARE_POWERSTATE_OFF 0 Off
nwVMWARE_POWERSTATE_ON 1 On
nwVMWARE_POWERSTATE_SUSPENDED 2 Suspended

VMware Machinestate constants definitions

Constant Value Description
nwVMWARE_MACHINESTATE_INVALID -1 Invalid
nwVMWARE_MACHINESTATE_NOTRUNNING 0 Not running
nwVMWARE_MACHINESTATE_RESETTING 1 Resetting
nwVMWARE_MACHINESTATE_RUNNING 2 Running
nwVMWARE_MACHINESTATE_SHUTTINGDOWN 2 Shutting down
nwVMWARE_MACHINESTATE_STANDBY 2 Standby
nwVMWARE_MACHINESTATE_UNKNOWN 2 Unknown

VMware Guesttools constants definitions

Constant Value Description
nwVMWARE_GUESTTOOLS_UNKNOWN -1 Unknown
nwVMWARE_GUESTTOOLS_NOTRUNNING 0 Not running
nwVMWARE_GUESTTOOLS_RUNNING 1 Running

Xen Counter constants definitions

Constant Value Description
nmXEN_CPU_USAGE 100 CPU usage in percent
nmXEN_MEMORY_USAGE 200 Memory usage in percent
nmXEN_MEMORY_AVAILABLE 201 Available memory in MB
nmXEN_MEMORY_USED 202 Memory used in MB
nmXEN_NETWORK_RATERX 350 Current Network Receiving rate in kbps
nmXEN_NETWORK_RATETX 351 Current Network Transmitting rate in kbps
nmXEN_DISK_USAGE 400 Current Disk usage in percent
nmXEN_DISK_AVAILABLE 401 Available disk space in Mb
nmXEN_DISK_USED 402 Used disk space in Mb
nmXEN_POWER_STATE 501 Determine whether virtual machine is powered
nmXEN_GUESTTOOLS 502 Determine whether VM Guest Tools is running on Virtual Machine

Xen Powerstate constants definitions

Constant Value Description
nmXEN_POWERSTATE_HALTED 0 Halted
nmXEN_POWERSTATE_PAUSED 1 Paused
nmXEN_POWERSTATE_RUNNING 2 Running
nmXEN_POWERSTATE_SUSPENDED 3 Suspended
nmXEN_POWERSTATE_SHUTTINGDOWN 4 Shutting down
nmXEN_POWERSTATE_CRASHED 5 Crashed
nmXEN_POWERSTATE_UNKNOWN 6 Unknown

Xen Guesttools constants definitions

Constant Value Description
nmXEN_GUESTTOOLS_UNKNOWN -1 Unknown
nmXEN_GUESTTOOLS_NOTRUNNING 0 Not running
nmXEN_GUESTTOOLS_RUNNING 1 Running

32.2. Error Codes

When a method is called, the result of the method is stored in the object's 'LastError' property.
When 'LastError' is 0, it means that the last called method completed successfully; otherwise, an error occured.

The value of the LastError tells you why the method failed. All error codes are listed on the ActiveXperts web site:

www.activexperts.com/support/errorcodes (list of error codes).

Here, you can also lookup a specific error to find its description.

You can also call the 'GetErrorDescription' method of any of the objects to find the error description.

33. Support

33.1. Product samples

Samples for Visual Basic, Visual Basic .NET, Visual C++, Visual C# .NET, ASP and VBScript are included as part of the installation. You can also find the samples on our ftp site at ftp://ftp.activexperts-labs.com/samples/network-component/.

33.2. ActiveXperts Support

Visit the ActiveXperts Support Site for a complete list of FAQ items at:
http://www.activexperts.com/support

To contact support, please send an e-mail to: support@activexperts.com

34. Purchase and Product Activation

34.1. Purchase

Please visit www.activexperts.com/sales to buy the product. Here, you can also find the latest prices.

You can also contact us via email: sales@activexperts.com

34.2. Product Activation

After you purchase the product, you will receive a registration code. This code must be entered in the registry on your machine(s). There are three ways to accomplish this:

Automatic installation

The ActiveXperts Networking Component automatic installation performs all necessary steps to install and register the component. It will ask for the registration code during installation and will enter the registration code in the registry.

2. 'Activate' method

You can use the Activate method of any of the objects:, for instance

Set objTcp = CreateObject("AxNetwork.Tcp")
objTcp.Activate XXXXX-XXXXX-XXXXX", True ' Substitute XXXXX-XXXXX-XXXXX by 
                                         ' your own registration code
' Pass True to make the activation persistent, so you need to
' call Activate  only once. If you pass False, you need to call Activate
' each time the product is started.

If you prefer, you can also use the Activate method of any of the other objects, e.g. HttpEx or Ntp.

The Activate method of any of the objects writes the following entry to the registry, which will actually activate the product:

Key: HKEY_LOCAL_MACHINE\Software\ActiveXperts\Network-Component\LicenseKey  
Type: REG_SZ  Value: XXXXX-XXXXX-XXXXX

where 'XXXXX-XXXXX-XXXXX' is the registration code issued to you.

3. Manually insert code in the registry

You can activate the product by editing the registry manually:

  • Start the registry editor (either REGEDT32.EXE or REGEDIT.EXE);
  • Open the 'HKEY_LOCAL_MACHINE\Software\ActiveXperts\Network-Component\' key;
  • Add/modify the 'LicenseKey' value: Type: REG_SZ, Value: XXXXX-XXXXX-XXXXX
Distribution License

For information about how to use the registration code with a Distribution License, please read the following document: How to distribute an ActiveXperts Toolkit.

35. Appendix A - License Agreement

35.1. Licence Agreement

    
  PLEASE READ THIS SOFTWARE LICENSE AGREEMENT CAREFULLY BEFORE 
  DOWNLOADING OR USING THE SOFTWARE.  BY CLICKING ON THE 
  "ACCEPT" BUTTON, OPENING THE PACKAGE, DOWNLOADING THE PRODUCT, 
  OR USING THE EQUIPMENT THAT CONTAINS THIS PRODUCT, YOU ARE 
  CONSENTING TO BE BOUND BY THIS AGREEMENT. IF YOU DO NOT AGREE 
  TO ALL OF THE TERMS OF THIS AGREEMENT, CLICK THE "DO NOT 
  ACCEPT" BUTTON AND THE INSTALLATION PROCESS WILL NOT CONTINUE, 
  RETURN THE PRODUCT TO THE PLACE OF PURCHASE FOR A FULL REFUND, 
  OR DO NOT DOWNLOAD THE PRODUCT.

  GENERAL
  In this Software License Agreement:
  (i) "ActiveXperts" means ActiveXperts Software B.V.
  (ii) "Customer" means the individual(s), organization or business entity 
  buying a license of the Software from ActiveXperts or its Distributors 
  or its Resellers.
  (iii) "Software" means computer programs (and their storage medium) 
  supplied by ActiveXperts and known collectively as "ActiveXperts Networking Component" 
  in which ActiveXperts has property rights and any user manuals, 
  operating instructions, brochures and all other documentation relating 
  to the said computer programs (the expression "Software" to include all 
  or any part or any combination of Software).

  1. LICENSE GRANT
  ActiveXperts grants Customer the following rights provided that you 
  comply with all terms and conditions of this License Agreement:

  (a) Installation and use. Customer may install, use, access, display and 
  run one copy of the Software on a single computer, such as a 
  workstation, terminal or other device ("Workstation Computer"). A 
  "License Pack" allows you to install, use, access, display and run 
  additional copies of the Software up to the number of "Licensed Copies" 
  specified above.

  (b) Reservation of Rights. ActiveXperts reserves all rights not 
  expressly granted to you in this License Agreement.

  2. UPGRADES AND SUPPLEMENTS
  To use a product identified as an upgrade, you must first be licensed 
  for the Software as eligible for the upgrade. After upgrading, Customer 
  may no longer use the product that formed the basis for Customer's 
  upgrade eligibility.

  This License Agreement applies to updates or supplements to the original 
  Software provided by ActiveXperts, unless we provide other terms along 
  with the update or supplement.

  3. LIMITATION ON REVERSE ENGINEERING,DECOMPILATION, AND DISASSEMBLY
  Customer may not reverse engineer, decompile, or disassemble the 
  Software, except and only to the extent that it is expressly permitted 
  by applicable law notwithstanding this limitation.

  4. TERMINATION
  Without prejudice to any other rights, ActiveXperts may cancel this 
  License Agreement if Customer does not abide by the terms and conditions 
  of this License Agreement, in which case you must destroy all copies of 
  the Software and all of its component parts.

  5. NOT FOR RESALE SOFTWARE
  Software identified as "Not for Resale" or "NFR," may not be resold, 
  transferred or used for any purpose other than demonstration, test or 
  evaluation.

  6. LIMITED WARRANTY
  ActiveXperts warrants that for a period of ninety (90) days from the 
  date of shipment from ActiveXperts: (i) the media on which the Software 
  is furnished will be free of defects in materials and workmanship under 
  normal use; and (ii) the Software substantially conforms to its 
  published specifications. Except for the foregoing, the Software is 
  provided AS IS. This limited warranty extends only to Customer as the 
  original licensee. Customer's exclusive remedy and the entire liability 
  of ActiveXperts and its suppliers under this limited warranty will be, 
  at ActiveXperts or its service center's option, repair, replacement, or 
  refund of the Software if reported (or, upon request, returned) to the 
  party supplying the Software to Customer. In no event does ActiveXperts 
  warrant that the Software is error free or that Customer will be able to 
  operate the Software without problems or interruptions.
  This warranty does not apply if the software (a) has been altered, 
  except by ActiveXperts, (b) has not been installed, operated, repaired, 
  or maintained in accordance with instructions supplied by ActiveXperts, 
  (c) has been subjected to abnormal physical or electrical stress, 
  misuse, negligence, or accident, or (d) is used in ultrahazardous 
  activities.


  7. LIMITATION OF LIABILITY AND REMEDIES.
  Notwithstanding any damages that you might incur for any reason 
  whatsoever (including, without limitation, all damages referenced above 
  and all direct or general damages), the entire liability of ActiveXperts 
  and any of its suppliers under any provision of this License Agreement 
  and your exclusive remedy for all of the foregoing (except for any 
  remedy of repair or replacement elected by ActiveXperts with respect to 
  any breach of the Limited Warranty) shall be limited to the greater of 
  the amount actually paid by you for the Software or U.S.$5.00. The 
  foregoing limitations, exclusions and disclaimers (including Sections 4, 
  5 and 6 above) shall apply to the maximum extent permitted by applicable 
  law, even if any remedy fails its essential purpose.

  8. ENTIRE AGREEMENT

  This License Agreement (including any addendum or amendment to this 
  License Agreements which is included with the Software) are the entire 
  agreement between you and ActiveXperts relating to the Software and the 
  support services (if any) and they supersede all prior or 
  contemporaneous oral or written communications, proposals and 
  representations with respect to the Software or any other subject matter 
  covered by this License Agreement. To the extent the terms of any 
  ActiveXperts policies or programs for support services conflict with the 
  terms of this License Agreement, the terms of this License Agreement 
  shall control.

  This Agreement shall be construed in accordance with the laws of The 
  Netherlands and the Dutch courts shall have sole jurisdiction in any 
  dispute relating to these conditions. If any part of these conditions 
  shall be or become invalid or unenforceable in any way and to any extent 
  by any existing or future rule of law, order, statute or regulation 
  applicable thereto, then the same shall to the extent of such invalidity 
  or enforceability be deemed to have been deleted from the conditions 
  which shall remain in full force and effect as regards all other 
  provisions.

  9. Copyright
  The Software is protected by copyright and other intellectual property 
  laws and treaties. ActiveXperts or its suppliers own the title, 
  copyright, and other intellectual property rights in the Software. The 
  Software is licensed, not sold.