Service configuration files

Release 9.3 E-mail This Topic Printable Version Give Us Feedback

The properties of service configurations are maintained in a file for each configuration in the GIS server's cfg directory. When you add a new service configuration to the GIS server, a new configuration file is automatically created. When a configuration is deleted, its configuration file is deleted from the cfg directory.

The name of a service configuration file follows the pattern <configuration name>.<service type>.cfg. For example, the map service Redlands would have the name Redlands.MapServer.cfg.

It's possible to add a configuration to the GIS server by manually creating a configuration file in the cfg directory, and it's possible to delete a configuration by deleting its file from the cfg directory. In both cases, the new or deleted configuration will not be recognized by the server until the server object manager (SOM) is restarted. If the SOM encounters a corrupted configuration file, the SOM will log a warning and ignore the configuration.

If you edit a service configuration file manually, you must also restart the SOM for the changes to take effect.

Service configuration tags

The following are the tags, their meanings, and example values in a service configuration file:

<Description>

An optional string that is the description of the service configuration.

<Properties>

The list of properties of the service configuration. The subtags are properties specific to the service configuration type. The following table lists which Properties subtags each type of service supports. The table is followed by a description of each tag in alphabetical order.
Properties subtags in service configuration file, by service type
MapServer GeocodeServer GeodataServer GlobeServer GPServer
FilePath Locator FilePath FilePath MapFile
SupportedImageReturnTypes LocatorWorkspacePath OutputDir MaxRecordCount DataFrame
MaxRecordCount LocatorWorkspaceConnectionString VirtualOutputDir MaxBufferCount Toolbox
MaxBufferCount SuggestedBatchSize MaxRecordCount CacheDir JobsDirectory
MaxImageWidth MaxBatchSize SOMCacheDir JobsVirtualDirectory
MaxImageHeight MaxResultSize ClientCachingAllowed ExecutionType
OutputDir OutputDir
VirtualOutputDir VirtualOutputDir
CacheDir MaximumRecords
IsCached LocalJobsDirectory
CacheOnDemand
IgnoreCache
SOMCacheDir
ConnectionCheckInterval
SchemaLockingEnabled

<CacheDir>

MapServer, GlobeServer

A string that represents the path to a location on the file system where the map or globe cache is stored. For globe services, the path should always end with \GlobeCache.

<CacheOnDemand>

MapServer

A Boolean tag specifying whether cache tiles should be created on demand and added to the server cache directory as users navigate the map. A value of true means that tiles will be added on demand. The default value is false.

Learn more about on-demand caching.

<ClientCachingAllowed>

MapServer, GlobeServer

A Boolean tag specifying whether client applications can locally cache tiles from this service. The default is true. Set this value to false if you anticipate that your cache will be updated often and you don't want clients to have to clear their cache to see the updates.

<ConnectionCheckInterval>

MapServer

An integer representing the number of seconds the service will wait before checking if ArcSDE servers that have become unavailable are once again available. Once the ArcSDE server is available, the service instance will be replaced to repair the connection to the ArcSDE server. By default, this property is not included in the .cfg file and this time is set to 300 seconds. You can add this tag to the .cfg file to modify this time. You can disable this behavior by specifying a value of 0.

<DataFrame>

GPServer

A string representing the name of the data frame containing the tool layer associated with the geoprocessing service. This tag is not used when the geoprocessing service is associated with a toolbox only.

<ExecutionType>

GPServer

A string that denotes whether geoprocessing jobs will be run in a synchronous or asynchronous manner.

<FilePath>

MapServer, GeodataServer, GlobeServer

A string representing a path to the document that the service configuration will serve. For GeodataServer, this is the path to the .sde file containing the .sde connection information, or it can represent a path to a personal geodatabase.

<IgnoreCache>

MapServer

A Boolean tag specifying whether the cache should be used. A value of true means that the map will be rendered dynamically instead of using the cache. You might use this setting if you had previously created the cache but changed the map and want users to immediately see the edits. This also gives you a chance to see how the service looks before updating or re-creating your cache.

You will see slower performance when you set this tag to true because the server must draw the map on each request.

<IsCached>

MapServer

A Boolean tag specifying whether this service has a cache of pre-rendered tiles on disk. The service is considered cached if a tiling scheme and cache directory have been defined. Services do not have a cache until you create one, so by default this tag is false.

<JobsDirectory>

GPServer

A string representing the path to the server jobs directory associated with the service. Jobs directories are used by geoprocessing services for writing scratch and output data.

<JobsVirtualDirectory>

GPServer

A string that represents the URL of the virtual directory that points to the physical location specified in the <JobsDirectory> tag.

<LocalJobsDirectory>

GPServer

An optional property that points to a local path on disk where geoprocessing services can create a scratch workspace.

Geoprocessing services execute faster when the scratch workspace is at a local path. In distributed installations of ArcGIS Server, namely those that use multiple server object container (SOC) machines, you can improve the performance of geoprocessing services by creating a local jobs directory at an identical path on each SOC machine. Be sure to give the SOC account Read and Write access permissions to this directory.

To designate the location as a local jobs directory, add the <LocalJobsDirectory> tag to the service configuration file and restart the Server Object Manager service. (Example: <LocalJobsDirectory>C:\LocalJobs</LocalJobsDirectory>)

The LocalJobsDirectory is not necessarily the same directory as the Jobs Directory, which may still point at a UNC path. After execution, the scratch workspace is copied from the LocalJobsDirectory to the JobsDirectory where it is accessible by all clients.

<Locator>

GeocodeServer

A string that represents the name of the address locator for a GeocodeServer.

<LocatorWorkspaceConnectionString>

GeocodeServer

A string that contains parameters for a connection to a locator stored in a geodatabase.

<LocatorWorkspacePath>

GeocodeServer

A required string for file-based locators that represents the path to the location on disk where the locator file is stored.

<MapFile>

GPServer

A string representing the path to the map document containing the tool layers associated with the geoprocessing service. This tag is not used when the geoprocessing service is associated with a toolbox only.

<MaxBatchSize>

GeocodeServer

An integer that represents the maximum number of result records returned by the FindAddressCandidates method on a GeocodeServer.

<MaxBufferCount>

MapServer, GlobeServer

An integer that represents the maximum number of features that can be buffered by the service at draw time per layer.

<MaxImageHeight>

MapServer

An integer representing the maximum height (in pixels) of images the MapServer will export.

<MaxImageWidth>

MapServer

An integer representing the maximum width (in pixels) of images the MapServer will export.

<MaximumRecords>

GPServer

An integer representing the maximum number of records that will be returned by a geoprocessing job.

<MaxRecordCount>

MapServer, GeodataServer, GlobeServer

An integer that represents the maximum number of result records that can be returned by query, find, and identify operations on a map or globe service or by the TableSearch method on a geodata service.

<MaxResultSize>

GeocodeServer

An integer that represents the maximum number of result records returned by the FindAddressCandidates method on a GeocodeServer.

<OutputDir>

MapServer, GeodataServer, GPServer

A string that represents the path to a location on the file system to which the service will write its output. When you create a new service configuration, this property is copied from the server output directory path that you specified. If you want the service's output to be cleaned by the GIS server, this path should be a path to a server output directory.

<SchemaLockingEnabled>

MapServer

This is a Boolean tag that determines whether the map service will acquire schema locks for map layers that come from a geodatabase. By default, the locks are acquired, so this property is true. If the locks impede your workflow, you can add this tag and set it to false to disable schema locking.

Use caution when disabling schema locking. When the schema locks are not acquired, other users have the ability to alter the schema of the dataset, which could have unexpected effects for those who use the map service. You should only disable schema locking if your workflow explicitly requires it.

The SchemaLockingEnabled tag is not included in the service configuration file by default. You must explicitly add it and set it to false if you want to disable schema locking.

<SOMCacheDir>

MapServer, GlobeServer

A string representing the path to the server cache directory used by the service. Note that this tag only contains the path of the cache directory; the full path to the cache is specified in the <CacheDir> tag.

<SuggestedBatchSize>

GeocodeServer

An integer that represents the number of records that will be located at a time for batch geocoding.

<SupportedImageReturnTypes>

MapServer

Possible values are MIME or URL. Specifies whether images will be returned as MIME data or written to disk (MIME + URL). If you choose URL, you must have a server directory specified for the configuration.

<Toolbox>

GPServer

A string representing the path to the toolbox associated with the geoprocessing service. This tag is not used when the geoprocessing service is associated with a tool layer in a map document. In that event, the MapFile and DataFrame tags would be used.

<VirtualGlobeCacheDir>

GlobeServer

A string that represents the URL of the virtual directory that points to the physical location specified in the <GlobeCacheDir> tag. For globe services only.

<VirtualOutputDir>

MapServer, GeodataServer, GPServer

A string that represents the URL of the virtual directory that points to the physical location specified in the <OutputDir> tag. When you create a new service configuration, this property is copied from the server directory's URL that you specify. For globe services only.

The following is an example of the <Properties> tag and some of its subtags for a MapServer configuration:

The following is an example of the <Properties> tag and some of its subtags for a GeocodeServer configuration whose locator is an ArcSDE locator:

<Extension>

The extension tag appears for each type of server object extension, or capability, that the configuration supports. The extension tag contains subtags that further describe the extension.

<TypeName>

The name of the type of server object extension. For example: MobileServer.

<Enabled>

A Boolean property that specifies whether the extension is enabled (true) for that configuration or not (false).

<Properties>

Some server object extensions may have unique properties that are detailed here in subtags.

<Info>

Some server object extensions can have Web access, which is determined by the WebEnabled and WebCapabilities tags inside a parent Info tag. The Info tag can appear beneath both the <ServerObjectConfiguration> and <Extension> tags.

<Recycling>

The list of recycling properties of the service configuration. This tag contains subtags <Start> and <Interval>.

Note: If the <Recycling> tag is missing or any of its subtags are invalid, recycling will be switched off for the configuration.

<StartTime>

A required string that represents the recycling start time, which is the first time at which recycling will occur for the service configuration. The time specified is in 24-hour notation. For example, to set the start time at 2:00 p.m., the StartTime property would be 14:00. The default is 00:00, meaning that recycling will happen for the first time at midnight.

<Interval>

A required integer that defines the time between recycling operations in seconds. For example, to recycle the configuration every hour, this property would be set to 3600. The default value is 86400, meaning recycling will happen once every 24 hours.

The following is an example of the <Recycling> tag and its subtags:

<Info>

This tag contains the WebEnabled and WebCapabilities subtags that describe the level of Web access for a service. This tag can appear beneath both the <ServerObjectConfiguration> and <Extension> tags.

<WebEnabled>

A Boolean property that describes whether clients will be able to access the service through HTTP. The default is true.

Note: This tag must have <Info> as a parent tag.

<WebCapabilities>

A comma-delimited string that contains the allowed operations for the service. Allowed operations describe what a client can do with a service. Specifically, they refer to the groups of methods from the service's Web Service Description Language (WSDL) that clients will be able to call. For a list of operations by service type, see "Limiting what users can do with a service" in the topic Tuning and configuring services. Note: This tag must have <Info> as a parent tag.

<IsPooled>

A required string indicating whether the services created by this configuration are pooled (true) or not pooled (false).

<MinInstances>

An integer specifying the minimum number of instances for the service's pool. The default is 0.

<MaxInstances>

An integer specifying the maximum number of service instances that can be running at any time. The default is 0.

<WaitTimeout>

An optional integer specifying the maximum amount of time in seconds allowed between a client's requesting a service and getting a service. The default is 60.

<IdleTimeout>

Time in seconds that a service instance is allowed to be idle before the instance is destroyed. This setting allows your service to return to the minimum number of instances after a period of time if none of the instances are in use. The default value is 1800.

<UsageTimeout>

An optional integer specifying the maximum amount of time in seconds a client can hold on to a service before it is automatically released. The default is 600.

<CleanupTimeout>

Time in seconds that a service instance should wait after a shutdown command for the purpose of allowing cleanup operations to finish.

<StartupTimeout>

Maximum time in seconds that the service startup can take before startup is considered a failure. Default is 300.

<Isolation>

A required string indicating if the configuration's service has high isolation (high) or low isolation (low).

<StartupType>

An optional string that specifies if the configuration is started by the SOM when the SOM starts, or if it needs to be manually started by an administrator. The valid values are automatic or manual. The default is automatic.

<InstancesPerContainer>

An integer representing how many instances of a service are allowed to run within one container process (ArcSOC.exe). When running in high isolation (see Isolation), this value defaults to 1 and should not be changed. When running in low isolation, this value defaults to 8 and can be set to any integer between 1 and 256.