Administering an ArcIMS site from the command line

Related Topics
Overview of Spatial Servers, Virtual Servers, and ArcIMS services ADMINCMD in the ArcXML Programmer's Reference Guide Creating and changing your password Checking site status using URL requests

About administering an ArcIMS site from the command line

ArcIMS services, Spatial Servers, and Virtual Servers can be managed from the command line. In addition, information about an ArcIMS site can be retrieved using the command line. To manage ArcIMS from the command line, the ArcIMS Servlet Connector must be installed on the Web server.

You can do most of the tasks you do in Administrator using the command line. The exception is managing MapNotes and EditNotes. One of the advantages of the command line is it allows you to automate processes such as starting, stopping, and refreshing ArcIMS services.

To administer ArcIMS services, Spatial Servers, and Virtual Servers from the command line you must create two files:

An ADMINCMD xml file.
A batch file or script that launches the xml file.

Administering ArcIMS Services, Spatial Servers, and Virtual Servers

The ADMINCMD xml file contains the instructions for adding or removing ArcIMS services, Spatial Servers, and Virtual Servers, and starting or stopping of ArcIMS services. Before you continue, you should be familiar with the terms Spatial Server, Virtual Server, and ArcIMS service.

The following table lists tags available for command line administration:

Tag	Description
ADMINCMD	Root element.
SERVICES and SERVICE	Used for managing ArcIMS services.
PSERVERS and PSERVER	Used for managing Spatial Servers
VSERVERS and VSERVER	Used for managing Virtual Servers.

The following examples show typical xml files for managing ArcIMS services and servers from the command line.

Adding and starting an Image Service, ArcMap Image Service, and Feature Service.

During administration, starting a service is a two-step process: first add the service and then start it. Each service type also has a set of required attributes. See SERVICE for descriptions of these attributes. The following example shows starting one of each type of service.

<?xml version="1.0"?>
<ADMINCMD version="1.0">
  <SERVICES>


    <SERVICE type="add" name="world_image" axl="c:\arcims\axl\world.axl" vsname="ImageServer1" imgloc="c:\arcims\output" imgurl="http://mycomputer.domain.com/output" imagememory="4" cleanup="20" imgtype="GIF" />
    <SERVICE type="start" name="world_image" />


    <SERVICE type="add" name="world_arcmap" axl="c:\arcims\axl\world.mxd" vsname="ImageServerArcMap1" imgloc="c:\arcims\output" imgurl="http://mycomputer.domain.com/output" imagememory="4" cleanup="20" imgtype="JPG" />
    <SERVICE type="start" name="world_arcmap" />


    <SERVICE type="add" name="world_feature" axl="c:\arcims\axl\world.axl" vsname="FeatureServer1"
/>
    <SERVICE type="start" name="world_feature" />

  </SERVICES>
</ADMINCMD>

Refreshing an existing Image Service, ArcMap Image Service, and Feature Service.

When a service is refreshed in Administrator, it is actually removed, added, and started again. Therefore, the xml file for refreshing services must follow the same sequence.

<?xml version="1.0"?>
<ADMINCMD version="1.0">
  <SERVICES>


    <SERVICE type="remove" name="world_image" />
    <SERVICE type="add" name="world_image" axl="c:\arcims\axl\world.axl" vsname="ImageServer1" imgloc="c:\arcims\output" imgurl="http://mycomputer.domain.com/output" imagememory="4" cleanup="20" imgtype="GIF" />
    <SERVICE type="start" name="world_image" />


    <SERVICE type="remove" name="world_arcmap" />
    <SERVICE type="add" name="world_arcmap" axl="c:\arcims\axl\world.mxd" vsname="ImageServerArcMap1" imgloc="c:\arcims\output" imgurl="http://mycomputer.domain.com/output" imagememory="4" cleanup="20" imgtype="JPG" />
    <SERVICE type="start" name="world_arcmap" />


    <SERVICE type="remove" name="world_feature" />
    <SERVICE type="add" name="world_feature" axl="c:\arcims\axl\world.axl" vsname="FeatureServer1"
/>
    <SERVICE type="start" name="world_feature" />

  </SERVICES>
</ADMINCMD>

Adding Spatial Servers and Virtual Servers.

By default, the ArcIMS Application Server starts one Spatial Server process on every machine with a registered Monitor. If you have installed ArcMap Server, two additional Spatial Server processes start. If you need more than the default number of Spatial Servers, you need to add them. You then must associate any newly added Spatial Servers to a Virtual Server. When using the command line, you can associate new Spatial Servers to new Virtual Servers but not to existing Virtual Servers.

Before you can add the Spatial Servers, you will need to determine their name ahead of time. Spatial Servers are numbered sequentially. Once you have this information, you can add them to Virtual Server groups.

Machine Default Spatial Servers New Spatial Server you add

machinea machinea_1
machinea_2
machinea_3 machinea_4

machineb machineb_1 machineb_2

Machine	Default Spatial Servers	New Spatial Server you add
machinea	machinea_1 machinea_2 machinea_3	machinea_4
machineb	machineb_1	machineb_2

In the following example, one Spatial Server is added to "machinea", and a second Spatial Server is added to "machineb". The machine name may be case sensitive. Both of these Spatial Servers are added to ImageServer2. See VSERVER for a description of the attributes.

Adding Spatial Services, Virtual Servers, and ArcIMS services in one xml file.

The following example is a combination of the previous examples. This example can be used as a backup or alternative to the site configuration file (ArcIMSSite.sez). First, two Spatial Servers (PSERVER) are added. Next they are associated with a Virtual Server (VSERVER). Once this association is made, a service can be added.

<?xml version="1.0"?>
<ADMINCMD version="1.0">
  <PSERVERS>
    <PSERVER type="add" machine="machinea"/>
    <PSERVER type="add" machine="machineb"/>
  </PSERVERS>
  <VSERVERS>
    <VSERVER type="add" name="ImageServer2" access="Public" description="ImageServer Example" servicetype="ImageServer" version="" >

      < PSERVER id="machinea_4" threads="2"/>
      < PSERVER id="machineb_2" threads="2"/>
    </VSERVER>
  </VSERVERS>


    <SERVICE type="add" name="world_image" axl="c:\arcims\axl\world.axl" vsname="ImageServer2" imgloc="c:\arcims\output" imgurl="http://mycomputer.domain.com/output" imagememory="4" cleanup="20" imgtype="GIF" />
    <SERVICE type="start" name="world_image" />
</ADMINCMD>

Removing services.

The following example shows how to remove services. You must first stop the service before removing it.

<?xml version="1.0"?>
<ADMINCMD version="1.0">
  <SERVICES>
    <SERVICE type="stop" name="world_image" />
    <SERVICE type="remove" name="world_image" />
  </SERVICES>
</ADMINCMD>

Removing Spatial Servers and Virtual Servers.

You can remove Spatial Servers and Virtual Servers using the command line. You must be careful with these operations since some of the safeguards provided through Administrator and Service Administrator are not present in the command line. In Administrator you must first remove all services associated with a Spatial Server you want to remove. This safeguard is not in the command line. Therefore, you can delete both Spatial Servers and Virtual Servers without first removing services.

You can also delete both the default Spatial Servers and Virtual Servers, such as mymachine_1 and ImageServer1, respectively. It is recommended that you never delete either the default Spatial Servers or Virtual Servers. If you do, your site will no longer run correctly.

The following example shows removing a Spatial Server and Virtual Server.

Using the command line to permanently remove Spatial Server references

If a Spatial Server machine is meant to be removed permanently from your site configuration, you must delete its reference and save the new site configuration by running some commands from the command line prompt. For more information, see Managing ArcIMS Spatial Servers.

Available commands for getting statistics from the host site

You can get different statistics on ArcIMS services, Spatial Servers, and Virtual Servers using the following key words.

Command

Description

SERVICE

Lists service names, the configuration files used, and the virtual server each service is running on.

VSERVER

Lists each ArcIMS Spatial Server and the number of instances within each ArcIMS Virtual Server for the host site.

PSERVER

Lists each ArcIMS Spatial Server ID and its host.

MONITOR

Lists each host that an ArcIMS Monitor is running on.

SAVE

Saves the current ArcIMS configuration.

STATS

Gives the information described in the following table for each Virtual Server. The fields described in this table correspond to fields that display when you view Virtual Server statistics from within Administrator. For more information, see the statistics section of Managing ArcIMS Virtual Servers using Administrator.

Current # of users	The number of instances belonging to a Virtual Server. This field corresponds to the Users field in Administrator.
Current response time	Lists the current average response time in milliseconds. This field corresponds to the Time field in Administrator.
Minimum time-request	Lists the shortest response time for a fulfilled request measured in milliseconds.
Maximum time/request	Lists the longest response time for a fulfilled request measured in milliseconds.
Average time/request	Lists the average response time for a fulfilled request measured in milliseconds.
Number Xs Srvr Invk	Lists the number of times the Virtual Server has successfully sent responses to the Application Server since the last time the Application Server was started.
Idle registered Srvr	Lists the number of Virtual Server instances ready to handle a request. A value of zero indicates that all Virtual Server instances are in use.
Clients waiting-Srvr	Lists the number of requests that have been kept waiting by the Application Server (in the Application Server queue) for the Virtual Server since the last time the Application Server was started. Corresponds to the Waited for server field in ArcIMS Administrator.
Timeouts per request	The number of timeouts since the last time the Application Server was started.

SERVICESTATS

This command pings a service. If a machine name is returned, the service is running successfully.

VSERVICESTATS

This command pings a Virtual Server. If a machine name is returned, the Virtual Server is running successfully.

How to administer an ArcIMS site from the command line

Administering an ArcIMS site from the command line

In a text editor, create the ADMINCMD xml file.

Create a batch or script file for launching the ADMINCMD xml file.

Windows: The batch file contains one line.

<jre directory>/java com.esri.aims.admincore.cmd.Exec http://mymachine.domain.com Username Password file filename

Where:

<jre directory> is the location of the ArcIMS JRE. The location on Windows is <ArcGIS Installation Directory>\ArcIMS\Jre\Bin. The exception is if you pointed to a different JRE during the installation of ArcIMS. If the directory path has spaces, you must use quotes, for example, "C:\Program Files\ArcGIS\ArcIMS\Jre\bin\java".
http://mymachine.domain.com is the host machine. This is the machine where your Web server resides. The machine name may be case sensitive.
Username and Password are the user name and password for ArcIMS administration.
Filename is the full pathname and name of the ADMINCMD xml file, for example, c:\arcims\axl\admincmd.xml. Be sure to include the parameter "file" before the filename.

The above command can also be typed on the command line in lieu of using the batch file.

UNIX or Linux: A script file is used containting the following lines. In the following example, note that the line beginning with "java -cp" is all one line:

#!/bin/csh
setenv JARHOME $AIMSHOME/Manager/lib
setenv AIMSHOST $argv[1]
java -cp $JARHOME/jaxp.jar:$JARHOME/parser.jar:$JARHOME/esri_mo10.jar: $JARHOME/esri_mo10res.jar:$JARHOME/arcims_admincore.jar:$JARHOME/arcims_admin.jar: $JARHOME/jcert.jar:$JARHOME/jnet.jar:$JARHOME/jsse.jar:$JARHOME/arcims_resadmin.jar com.esri.aims.admincore.cmd.Exec http://$AIMSHOST Username Password file $argv[2]

Where:

$argv[1] is the hostname.
$argv[2] is the name of the ADMINCMD xml file, for example, admincmd.xml. Be sure to include the parameter "file" before $argv[2]
Username and Password are the username and password for ArcIMS adminstration.

Run the batch file or script.

Retrieving ArcIMS site information

At the command prompt, type the following command:

<jre directory>/java com.esri.aims.admincore.cmd.Exec http://mymachine.domain.com Username Password cmd <COMMAND>

Where:
- <jre directory> is the location of the ArcIMS JRE. The location on Windows is <ArcGIS Install Directory>\ArcIMS\Jre\Bin. The exception is if you pointed to a different JRE during the installation of ArcIMS. On Windows, if the directory path has spaces, you must use quotes, for example, "C:\Program Files\ArcGIS\ArcIMS\Jre\bin\java".
- http://mymachine.domain.com is the host machine. This is the machine where your Web server resides.
- Username and Password are the user name and password for ArcIMS administration.
- <COMMAND> is one of the available key words: SERVER, PSERVER, VSERVER, MONITOR, SAVE, STATS, SERVERSTATS, and VSERVERSTATS. Be sure to include the parameter "cmd" before the command.

Troubleshooting

A NoClassDefFoundError is given

The ArcIMS jar files must be included in the JRE bin directory you are referencing: jaxp.jar, parser.jar, esri_mo10.jar, esri_mo10res.jar, arcims_admincore.jar, arcims_admin.jar, jcert.jar, jnet.jar, jsse.jar, arcims_resadmin.jar. These jar files can be found in the following locations:

Windows: <ArcIMS install location>\ArcIMS\Jre\Lib\Ext
UNIX and Linux: $AIMSHOME/lib/ext.

Search code: @admin_command