ArcSDE Services

Please be sure to read the book Managing ArcSDE Application Servers if you have not already done so. You should also read chapter 4 of Understanding ArcSDE to understand the configuration choices between using an ArcSDE server (application server) and using direct connections.

An ArcSDE service is a single iomgr (I/O manager) connected to a single DBMS database. It is possible to start multiple giomgrs and connect each of them to a separate database. For Oracle 8i and SQL Server, you may also start multiple giomgrs on the same database if needed. Each Oracle 806, Informix and DB2 instance exists within its own memory space and executable environment and connects to its own database. ArcSDE instances may share the same executable programs, but require their own home directories.

Starting an ArcSDE service spawns the giomgr background process which establishes a single connection to the DBMS database. The giomgr process always connects to the DBMS database through the ‘sde’ user. After the giomgr process establishes the connection, it attempts to lock the ‘sde’ user’s VERSION table. If the giomgr process is unable to lock the table, it disconnects and issues an error stating that another giomgr process has already connected to this database. Thus a one-to-one relationship between the ArcSDE instance and the DBMS database must exist. Instances have unique names and home directories.

Once giomgr starts, it listens on the port number assigned to the service for ArcSDE client connection requests. When a connection request is received, the giomgr verifies the user and password and spawns a gsrvr process and assigns it a new port number to communicate on.

The services.sde file

The services.sde file contains the unique instance name and the network port number and protocol on which the giomgr accepts connection requests to the instance. By default the services.sde file instance name is esri_sde with a 5151 port number using a TCP/IP protocol.

#

# ESRI SDE Remote Protocol

#

esri_sde           5151/tcp

The system services file must contain a service name that matches the instance name in the  services.sde file in the etc subdirectory of the ArcSDE home directory. When the connection is started, the system services file is searched for a service name that matches the instance name in the services.sde file. If a match is not found, an error is returned.

Location of system services file

UNIX® (all platforms)                                   /etc/services

Windows NT™      C:\winnt\system32\drivers\etc\services

Windows XP or 2003 C:\windows\system32\drivers\etc\services

 

The system services file contains many services names at least one of which must match your sde instance name. The service name must be entered into the services file on both the ArcSDE server and the client machines. You may use the NIS (Network Information Service) /etc/services file if you are running yellow pages, in which case you don’t have to redundantly update the client and server /etc/services files.

Here is an example from an UNIX /etc/services file that contains two ArcSDE instances:

esri_sde     5151/tcp    sde      # SDE default instance iomgr port.

esri_sde2    5153/tcp    sde2     # SDE instance # 2 iomgr port.

This defines two instance names: esri_sde and esri_sde2.

Each instance has its own home directory with the instance name in the services.sde file.

Clients and services

The service argument of the SE_connection_create function accepts the instance directly unless it is NULL. In that case, it uses the instance defined in the SDEINSTANCE variable. If the SE_connection_create instance argument is NULL and SDEINSTANCE is undefined, the instance name defaults to ‘esri_sde’.

NOTE: The term "instance" and "service" are synonymous. The term instance is a legacy term from SDE 2. The term "service" is the more current name and is used in concepts discussions. However, many functions and ArcSDE administration commands still have references to "instance".

The example below creates a connection to the ‘sdedev’ instance.

CHAR server[30] = "elvis";

CHAR instance[30] = "sdedev";

CHAR username[30] = "businessmap";

CHAR password[30] = "mapserver";

SE_ERROR error;

SE_CONNECTION connect;

SE_connection_create(server, instance, NULL, username, password, error, connect);

or

setenv SDEINSTANCE sdedev

CHAR server[30] = "elvis";

CHAR username[30] = "businessmap";

CHAR password[30] = "mapserver";

SE_ERROR error;

SE_CONNECTION connect;

SE_connection_create(server, NULL, NULL, username, password, error, connect);

Instance functions

Function Name

Function Description

SE_instance_configuration

Returns an ArcSDE configuration.

SE_instance_control

Controls the state of the connected instance.

SE_instance_free_locks

Frees memory allocated for a list of instance locks.

SE_instance_free_state_locks

Frees memory allocated for a list of state locks held by the specified instance.

SE_instance_free_statistics

Frees memory allocated for a list of instance statistics.

SE_instance_free_table_locks

Frees memory allocated for a list of table locks held by the specified instance.

SE_instance_free_users

Frees memory allocated for a list of instance users.

SE_instance_free_variables

Frees memory allocated for a list of environment variables.

SE_instance_free_version_locks

Frees memory allocated for a list of version locks held by the specified instance.

SE_instance_get_locks

Returns a list of locks in use on a specified ArcSDE instance.

SE_instance_get_objectlocks

Returns a list of object locks in use on a specified instance.

SE_instance_get_statistics

Gets statistics on the specified ArcSDE instance.

SE_instance_get_state_locks

Returns a list of state locks in use on a specified instance.

SE_instance_get_table_locks

Returns a list of table locks in use on a specified instance.

SE_instance_get_users

Gets the users of the specified ArcSDE instance.

SE_instance_get_variables

Gets the environment variables of the specified ArcSDE instance.

SE_instance_get_version_locks

Returns a list of version locks in use on a specified instance.

SE_instance_start

Starts an ArcSDE instance on the current node.

SE_instance_status

Gets status information on an ArcSDE instance.