Automating cache creation and updates with geoprocessing

If you're working with a basemap that is unlikely to change, chances are you'll create the cache only once. You can use the ArcCatalog caching interface (namely, the Caching tab of the Service Properties) to create the cache. This is also an appropriate way to update the cache if your data does not change very often.

If your data changes often, you still may be able to use caching. The caching tools in ArcGIS Server 9.3 have been improved to give you more choice of which tiles get updated, thereby allowing you to cache datasets that would have required advanced scripting to update at 9.2. For example, you can

• Update the cache only for scale levels that have changed
• Automate cache maintenance with utilities such as Windows Task Scheduler
• Update only areas of the cache that fall within the boundaries of a feature class

The way to automate the caching process is to write scripts that use the Server Tools in ArcToolbox. On Linux/Solaris, the caching scripts are already created for you and installed with ArcGIS Server SOC component under <ArcGIS Server Installation directory>/arcgis/java/tools/caching. This help topic lists the tools available to you and contains some examples to help you get started writing scripts. It also describes migration of scripts from ArcGIS Server 9.2 to 9.3.

Caching tools

The Server Tools toolbox contains tools for both map caching and globe caching.

Map caching tools

The following tools are included for map caching. The tools reflect the pattern of creating the tiling scheme and filling the cache with tiles.

• Create Map Server Cache - Initializes the cache and sets the tiling scheme. This tool does not create any tiles. To create the tiles, use Manage Map Server Cache Tiles.
• Manage Map Server Cache Tiles - Creates new tiles, replaces old tiles, or deletes tiles from the cache.
• Manage Map Server Cache Scales - Adds or removes scales from an existing cache.
• Delete Map Server Cache - Deletes all cache tiles and the cache's folder structure.

A common scripting workflow is to use Create Map Server Cache to create a new empty cache, then use Manage Map Server Cache Tiles to fill the cache with tiles and periodically run updates.

A tool for standardizing map caches

If you'll be building many map caches to use in your organization, it's recommended that you use the same tiling scheme for each. Using a standard tiling scheme allows for a more efficient overlay of your caches.

The tiling scheme you choose might be the same tiling scheme used by online mapping services such as ArcGIS Online, Google Maps, or Bing Maps, or it may be a tiling scheme used only in your organization. Your choice of tiling scheme may be influenced by cartographic standards or practices in your organization. For example, if all your maps are required to use the polar stereographic projection, you will not be able to use the ArcGIS Online, Google Maps, or Bing Maps tiling schemes; you will need to create your own tiling scheme.

The Generate Map Server Cache Tiling Scheme tool in the Server Tools toolbox can help you create one tiling scheme to share throughout your organization. This tool creates an XML tiling scheme file. You can place this tiling scheme file in a shared location and reference it when you run Create Map Server Cache.

Globe caching tools

The following tools are included for globe caching.

• Manage Globe Server Cache Tiles - Creates new tiles, replaces old tiles, or deletes tiles from a globe cache
• Delete Globe Server Cache - Deletes the cache

Notice there are only two tools for working with globe caches. By nature, all globe services have a cache that is automatically created when you start the service. This cache uses a built-in tiling scheme that is the same for all globe services. Therefore, there are no tools for creating a new globe cache or tiling scheme.

You can use Manage Globe Server Cache Tiles to completely fill the cache with tiles, or you can use it to cache only selected areas and levels of detail.

Using the tools in scripts

Although you can manually open the caching tools from ArcToolbox, it's more efficient to write a geoprocessing script that contains one or more tools that you want to run. You can then schedule this script to run automatically.

Scripting example: Updating a map cache

If your data changes frequently, scripting is the recommended way to update your cache. You can create a Python script that runs the update tool. You can write the Python inside of Notepad, or you can use a development environment such as IDLE or PythonWin.

The script does not have to be complex. It just needs to define the parameters for the tool and run it. The following Python script runs the Manage Map Server Cache Tiles tool to re-create an entire cache:

# This script updates a map cache containing changing data




# Any line that begins with a pound sign is a comment and will not be executed




# These lines are used to access ArcGIS geoprocessing tools

import arcgisscripting

gp = arcgisscripting.create()




# Here is where you define the input parameter values for the update tool. 

# Empty quotes take the default value.

server_name = "MyServer"

object_name = "Precipitation"

data_frame = "Layers"

layers = ""

constraining_extent = ""

scales = "128000;64000;32000;16000"

update_mode = "Recreate All Tiles"

thread_count = "2"

antialiasing = "NONE"

update_feature_class = ""

ignore_status = ""




# These lines run the update tool

try:

    print 'Starting Cache Update'

    gp.ManageMapServerCacheTiles(server_name, object_name, data_frame, layers, scales, update_mode, constraining_extent, thread_count,  antialiasing, update_feature_class, ignore_status)

    print 'Finished Cache Update'

# If there's a failure, these lines get the messages

except:

    gp.AddMessage(gp.GetMessages(2))

    print gp.GetMessages(2)

It's important to use the correct syntax for all the input parameters. You can find instructions and examples for each parameter of each tool in the Geoprocessing Tool Reference of the ArcGIS Desktop Help. For example, here is the reference topic for the Manage Map Server Cache Tiles tool used above: Manage Map Server Cache Tiles (Server).

If you're new to Python, these resources can help you learn more:

• An overview of writing geoprocessing scripts - The ArcGIS Desktop Help contains an introduction to Python scripting, starting with this topic.
• Exporting a model - If you've created models in ModelBuilder, you can export them to Python to see what the corresponding script looks like.

Scheduling your script to run on a regular basis

You can save your script as a Python script file (.py). Double-clicking the script in Windows Explorer will cause the script to run. This is useful for testing, but in most cases you'll want to schedule the script to run automatically on a regular basis.

Your operating system contains utilities that help you schedule tasks such as running a script. In Windows you can use Tasks Scheduler or the schtasks command. You'll need to provide the location of the script file, how often you want it to run, and the name and password that the task will run as. For more information on scheduling tasks, see the following resources:

• Scheduling geoprocessing scripts to run at prescribed times
• Schedule a new task (Microsoft documentation)
• Schtasks command line reference (Microsoft documentation)

Note for Linux users

On Linux, before running Python scripts for working with the cache, you must execute the command source /arcgis/servercore/.Server/init_server.sh as described in Viewing and Managing Network Ports on Linux/Solaris

Migrating from ArcGIS Server 9.2 to 9.3

If you used the Server Tools toolbox with ArcGIS Server 9.2, you'll notice some changes at 9.3. Some tools from ArcGIS Server 9.2 have been deprecated. They are included with the software so that your existing scripts will continue to run, but you cannot add them to the toolbox and they are not available through the command line. You can only use them in a scripting environment.

This table shows the deprecated tools and their replacements in 9.3:

• Generate Map Server Cache - This tool initialized the map cache, set the tiling scheme, and created all the tiles in the cache. At 9.3, use Create Map Server Cache to initialize the cache and set the tiling scheme. Then use Manage Map Server Cache Tiles to create some or all of the tiles for the cache.
• Update Map Server Cache - This tool created, replaced, or deleted tiles from a map cache. At 9.3, use Manage Map Server Cache Tiles, which can do the same things with more flexibility for updating only selected areas of the cache.
• Generate Globe Server Cache - This tool generated all tiles in a globe cache. At 9.3, use Manage Globe Server Cache Tiles to create some or all of the tiles for the globe cache.

Note: The order of parameters has changed in some of the new tools. For example, in ManageMapServerCacheTiles constraining_extent is a now a required parameter that immediately follows update_mode in the parameter list. Always consult the latest geoprocessing tool reference documentation when updating your scripts.