Cache generation and updates on Linux/Solaris

For ArcGIS Server on Linux/Solaris, map and globe service caches are created using scriptable geoprocessing tools. Several scripts are installed with ArcGIS Server to help you manage caches from the command line. These scripts use the Server tools from ArcToolbox.

Caching scripts

The caching scripts are located in the <ArcGIS Server Installation directory>/server10.0/java/tools/caching directory.

Map caching scripts

Globe caching scripts

Running the scripts

Following are some guidelines for successfully creating/updating a map or globe cache using these tools.

The ArcGIS Server Object Container (SOC) process runs as the ArcGIS Server installation owner. By default, this user is not a member of the agsadmin group. Only members of the agsadmin group can create empty contexts on the server and successfully run the map caching tools.

The ArcGIS Server installation owner needs to be added with the group agsadmin. You can use the following steps to accomplish this in Manager:

  1. Log in to ArcGIS Server Manager.
  2. Click the GIS Server tab.
  3. Click the Local GIS Users link on the left-hand side.
  4. Click the Add Users link.
  5. Give the user the name 'ags' and set the group as 'agsadmin' (assuming you have chosen ags as the ArcGIS Server installation owner).
  6. Click Save.
  1. Ensure that enough space is available in the cache directory. If not, change the default cache directory to a location where enough space is available.
  2. If it's a multi-machine deployment, ensure that the ArcSOC process has write access to the cache location.

Now, you are ready to run the script(s) to create/update the cache from the command line; as the ArcGIS installation owner, run from the location <ArcGIS Server Installation directory>/server10.0/java/tools/caching. The script will prompt you to choose from the list of variables or to enter a value for a given parameter.

As described earlier, there are two steps in generating a map cache, (1) setting map cache properties and (2) creating/updating map cache tiles. Map cache properties can be set either using ArcGIS Manager (navigate to the Manage Services panel, select a map service, and choose the Caching tab) or by executing the CreateMapServerCache script.

Script: CreateMapServerCache

  1. Domain: For ArcGIS Server on on Unix, enter the fully qualified hostname.
  2. Username/Password: Type in the user name/password used to connect to ArcGIS Server Manager. The default is admin/admin.
  3. server_name: Type in the name of either the host machine where ArcGIS Server is installed or the ArcGIS SOM machine hosting the service to be cached.
  4. object_name: This gives you a list of map services currently running that meet the requirements of the script being executed. For example, if the cache tiling schema for a map service is not configured, it will not be listed in the options for the ManageMapServerCacheTiles script, even if the service is running.
  5. data_frame: This lists the names of data frames available for a given map service. Press the ENTER key to accept the default data frame.
  6. out_folder—Server Cache Directory: Select the cache directory where you want the cache data to reside. If you want to add a directory other than the one provided in the list, you will have to add a new cache directory in ArcGIS Manager.
  7. tiling_scheme_type—Tiling Scheme: It defines the cache properties such as number of scales and their value.
    • [New] * default: Creates a new tiling scheme.

    • Predefined: This is used to maintain a standard tiling scheme across an organization or to have a tiling scheme compatible with existing online services such as ArcGIS Online/Bing Maps/Google Earth.

  8. tiling_schema: This option becomes available only when using a predefined tiling scheme type, and it requires the path to the tiling scheme.
  9. scales_type—Scales:
    • [Standard] * default: When chosen, the script suggests scale values for a given number of scales, based on the full extent of the map and its resolution.
    • Custom: When chosen, you need to enter a list of custom scale values for the given map data, based on the best display settings.
  10. num_of_scales: This option is available when the standard scale type is chosen. Enter the number of scales for zooming in cache levels. In general, you should limit the number of suggested scales you request to 20 or fewer.
  11. dpi—Dots (Pixels) Per Inch: Choose higher values for clearer resolution. The default value of 96 is usually sufficient unless you are working primarily on a network where the majority of your client machines have a different dpi setting.
  12. tile_width and tile_height—Tile Width & Tile Height (in pixels): Choosing a smaller tile width and height may improve performance of the application requesting tiles from the cache, as less data will need to be transferred. However, smaller tile size results in a larger cache size and longer creation time.
  13. map_or_layers—Cache Type: It is an advanced cache setting.
    • [Fused]* default: All the layers in the map are included in one fused image and must be turned on and off together.
    • Multi_layer: Set of cached images for each layer which can be enabled or disabled by the user. This option is disabled for .msd-based map services.
  14. tile_origin: Tiling origin in map units.
  15. levels: This option is available if the 'scales_type' is set as 'Custom'. Enter the list of custom scale values separated by semi-colons.
  16. layers: This option is available if the 'map_or_layers' variable is set to 'Multilayer'. Enter the list of layer separated by semi-colons for which the cache needs to be generated
  17. Antialiasing:
    • [None]* default
    • Antialiasing: Choose it to smooth the edges of labels and lines for improved display quality.
  18. cache_format—Cache Tile Image Format: [Png8, Png24, Png32, JPEG, Mixed] Choose the output image format used to create the cache tiles. The image format determines the cache size on disk, image quality, and the ability to support background transparency. Raster data is best served with JPEG or MIXED image format.
  19. tile_compression_quality: Compression is supported only for JPEG format. Enter a value between 1 and 100 for the JPEG compression quality. The default value is 75 for JPEG tile format and zero for other formats. Choosing a higher value will result in a larger file size with a higher-quality image, while choosing a lower value will result in a smaller file size with a lower-quality image. When using JPEG or MIXED with vector maps, use a high compression quality value (such as 90) to reduce blurring of lines and text.
  20. storage_format—Cache Tiles storage format:
    • Compact: Groups cache tiles for more efficient storage and mobility
    • Exploded: Stores each tile as a single file.
  21. use_local_cache_dir-—Local cache directories on the server:Choose whether bundle files should be written into a local directory on the server when creating a compact cache, instead of being written directly into the shared cache directory. If you choose this option, the bundle files will be copied into the shared cache directory as they are completed. This option improves performance when multiple machines are working on the caching job.
    • [True]* This is the default value when cache storage format is "Compact". Tiles stored in bundles are written into a local cache directory, then copied into the shared cache directory as bundles are completed. Note: This option is not available when storage format is "Exploded".
    • False: Tiles are written directly into the shared cache directory. This is the only valid option when the storage format is "Exploded".

Script: ManageMapServerCacheTile

  1. layers: This option is available if the 'map_or_layers' variable is set to 'Multilayers' in the cache schema. Enter the list of layer separated by semi-colons for which the cache tiles needs to be generated/updated.
  2. levels: Scales provides the ability to pick scales from the list of given scales for any of the following tools: ManageMapServerCacheTiles, ExportMapServerCache, or ImportMapServerCache.
  3. update_mode—Update Mode:
    • Recreate Empty Tiles: Use when you want to ensure that the cache is created for the missing tiles. Note: This takes longer to complete for large cache jobs, as it checks the folders of your cache and creates any tiles that are missing, ensuring the quality of the cache created.
    • Recreate All Tiles: Use when creating a cache for the first time or when you want to discard the existing cache and create a new cache based on an updated map service.
    • Delete Tiles: Deletes the existing cache tiles while retaining the cache schema.
  4. constraining_extent—Update Extent: If you want to create tiles for a rectangular area in your map, you can change the default update extent and enter a custom rectangular extent; this can be useful when building caches for a test area.
  5. thread_count—Number of Map Server Instances
  6. update_feature_class—Update cache using Feature Class extents: Provide the path to the directory where the feature class exists to spatially constrain tile creation to the boundaries of a feature class, avoiding empty or uninteresting areas. This also makes caching jobs easier to manage and track.
  7. ignore_status:
    • Track Completion status: Used to mark which features have had tiles created over their areas. A cached field is added to the feature class against which you are caching. When tiles have been created for the extent of a feature, that feature's Cached field is marked Yes. The fields can be viewed by opening the feature class table in ArcCatalog.
    • [Ignore Completion Status Field] *default : Doesn't add or update Cached field.
  8. Antialiasing: This is a read-only in this tool. It is based on the value that you set on the Caching tab of the Service Properties dialog box.

Follow the directions as the script guides you through the cache generation/update process.

When the process is finished, the output is located in the cache location. The default cache location is <ArcGIS Server Installation directory>/server/serverdir/arcgiscache.

Script: ManageMapServerCacheScales

levels: Lets you define the set of scales, adding or deleting scales as necessary to update your cache schema. Provide the updated list of scale values by entering scale values separated by semicolons.

Script: GenerateMapServerCacheTilingScheme

  1. map_document: Provide the path to the map document based on where you want to create the new cache tiling scheme.
  2. tiling_schema: Provide the path where you would like to store the output tiling scheme. Make sure to append the name of the new schema with an .xml extension.
  3. cache_levels: Enter the number of scales the new tiling schema should have.
  4. levels: By default, the script suggests corresponding scale values for the given number of cache levels, based on map extents. You can choose to select the suggested values or define your own custom scale values by entering the new values separated by semicolons.

Script: ExportMapServerCache and ImportMapServerCache

  1. target_cache_path: Enter the path to the folder where you would like to export selected cache data. Make sure the folder exists and the ArcSOC has write access to it.
  2. storage_format_type: Provides the option to choose the storage format type of the exported cache. It can be different from the parent cache. Note: The Import Map Server Cache tool picks up the storage format of the destination folder by default.
  3. export_extent/import_extent: Provides the option to export/import only the part of the cached data inside the given extent. Enter the custom rectangular extent to export or import cache data.
  4. levels: Provides the ability to pick scales from the list of given scales for export/import.
  5. export_feature_class/import_feature_class: Provides the ability to spatially constrain cache tile export to the boundaries of a feature class, avoiding uninteresting areas. Enter the path to the directory where the feature class exists.
  6. source_cache_dataset: Provides the path to the layer file inside the folder from which you would like to import cache data. For example, /net/plotemy/arcgiscache/sandiego/Layers.

Script: ManageGlobeServerCacheTiles

  1. in_layers: Select the layers to include in the layer cache.
    1. Level From — Select the level-of-detail scale you would like to begin caching the layer. If the smallest and largest level-of-detail scales are used for the minimum and maximum, a full cache will be built for the layer.
    2. Level_To — Select the level-of-detail scale you would like to begin caching the layer. If the smallest and largest level-of-detail scales are used for the minimum and maximum, a full cache will be built for the layer

To automate Cache generation from command line

To fully script Cache tools without user interaction, run the following code as ArcGIS install owner from command line. Enter the values for the parameters described above, in the order shown.

CreateMapServerCache .sh

./CreateMapServerCache.sh -u <username> -d <hostname> -p <passwd> -args <server_name> <object_name> 
<out_folder> <tiling_scheme_type> <scales_type> <num_of_scales> <dpi> <tile_width> <tile_height> 
<data_frame> <map_or_layers> <tiling_schema> <tile_origin> <'levels;customScale1'>  
<'layers;multiLayer1'> <antialiasing> <cache_format> <tile_compression_quality> <storage_format> 
<use_local_cache_dir>

For example: To generate cache using New Tiling scheme Type & Standard scales

./CreateMapServerCache.sh  -u admin -d hostname -p admin -args myserver Rainfall Layers 
/path/to/arcgiscache/ NEW STANDARD 4 96 512 512 FUSED '#' '-400 400' '#' '#' 
ANTIALIASING MIXED 75 Compact True

Note: 1. Based on the chosen parameters, the depended properties will get enabled or disabled.
2. To enter default values or null values use # sign inside quotes.For example '#'
3. To enter multiple values for a parameter separate each value using semicolon (;)
4. Use single quotes('') when providing values that require a semi-colon(;) or a space as a 
separator. For example:	'scale1;scale2', 'layer1;layer2'

ManageMapServerCache.sh.

./ManageMapServerCacheTiles.sh -u <username> -d <hostname> -p <passwd> -args <server_name> <object_name> 
<data_frame> <'layers;multiLayer1'> <'levels;levels'> <update_mode> <constraining_extent> <thread_count> 
<Antialiasing> <update_feature_class> <ignore_status>

For example:

./ManageMapServerCacheTiles.sh -u ags -d hostname -p ags -args myserver Rainfall Layers '#' 
'64000000;32000000' 'Recreate Empty Tiles' 
'-183.780014728684 16.3007091216187 -61.4068546696843 74.030308030969' 5 NONE 
/path/to/feature_class IGNORE_COMPLETION_STATUS_FIELD

To Schedule a cache script to run at prescribed times

# 1. Set the environment variable to point to an editor of choice (the example below uses vi)
					EDITOR=/usr/bin/vi;  export EDITOR

# 2. Bring up the crontab in the editor using the command
					crontab -e

# 3. Add a line to crontab
#	<min> <hour> <day of month> <month> <day of week> <script to be executed>

# Allowed values
# <0-60> <0-23> <1-31> <1-12> <0-6> </path/to/customised_ManageMapServerCache.sh>

0   10   *   *  	0 	 /path/to/customised_Cache.sh  # To run every Sunday at 10 AM
0   18   *   *   *   /path/to/updatecache.sh       # To run every day at 6 PM
0    0   1   *   *   /path/to/updatecache.sh       # To run at midnight on the first of every month

# 4. Save and exit the editor
# 5. Verify that the cron job has been added to the list of cron tasks
					crontab -l

Note: Do not use statements following '#' sign, these are comments for understanding the commands.

Copyright © 1995-2011 Esri. All rights reserved.
3/6/2012