Configuring Users Using the Services API

Go Up to Invoking Service Tasks with isc_service_start( )

You can use the Services API to display, add, delete, and modify users. This corresponds to the functionality of the command-line tool gsec.

Listing Valid Users in the Security Database Using the Services API

The following table lists arguments to isc_action_svc_display_user:

Services API display users arguments

Argument	Purpose	Argument length	Argument value
isc_spb_sec_username	Specify a single user by name for which the Services Manager should return information.	2 bytes + string	String

To request the Services Manager to return information for all users in the InterBase security database (admin.ib by default), omit the isc_spb_sec_username argument.

You can retrieve the information that the server manager returns by using isc_service_query() with the cluster identifier isc_info_svc_get_users. See the example on the page Server configuration properties.

Adding a User to the Security Database Using the Services API

You can create a new user in the InterBase security database using the cluster identifier isc_action_svc_add_user. The first argument in the cluster must be isc_spb_sec_username. The following table lists arguments to this cluster:

Services API arguments for isc_action_svc_add_user

Argument	Purpose	Argument length	Argument value
isc_spb_sec_username	User name to create; maximum 31 characters; mandatory argument, must be the first parameter	2 byte length + string	String
isc_spb_sec_password	Password for the user; maximum 31 characters, only first 8 characters are significant; mandatory argument	2 byte length + string	String
isc_spb_sec_firstname	Optional first name of the person using this user name	2 byte length + string	String
isc_spb_sec_middlename	Optional middle name of the person using this user name	2 byte length + string	String
isc_spb_sec_lastname	Optional last name of the person using this user name	2 byte length + string	String
isc_spb_sec_userid	Optional user ID number, defined in /etc/passwd, to assign to the user; reserved for future implementation	4 bytes	Unsigned long
isc_spb_sec_groupid	Optional group ID number, defined in /etc/group, to assign to the user; reserved for future implementation	4 bytes	Unsigned long
isc_spb_sec_groupname	Optional group name, as defined in /etc/group, to assign to the user; reserved for future implementation	2 byte length + string	String
isc_spb_sql_role_name	Optional SQL role to adopt when administering users (reserved for future use)	2 byte length + string	String

Removing a User from the Security Database Using the Services API

You can create a new user in the InterBase security database (admin.ib by default) using the cluster identifier isc_action_svc_delete_user. The following table lists arguments to this cluster:

Services API remove user arguments

Argument	Purpose	Argument length	Argument value
isc_spb_sec_username	Name of user to delete; mandatory argument, must be the first parameter.	2 byte length + string	String
isc_spb_sql_role_name	Optional SQL role to adopt when administering users (reserved for future use).	2 byte length + string	String

If you remove a user entry from the InterBase security database (admin.ib by default), no one can log in to any database on that server using that name. You must create a new entry for that name using isc_action_svc_add_user.

Modifying a User in the Security Database Using the Services API

You can create a new user in the InterBase security database (admin.ib by default) using the cluster identifier isc_action_svc_modify_user.

The arguments you can use in this cluster are the same as those you can use with isc_action_svc_add_user. You cannot change a user name, only associated properties of that user entry. Only properties you specify change. To remove a property, specify zero for the length and data of the property. The first argument in the cluster must be isc_spb_sec_username.

Deprecated Use of Older User Functions Using the Services API

The API functions isc_add_user(), isc_delete_user(), and isc_modify_user() are made obsolete by the introduction of the InterBase Services API. The new Services API functions are preferred over the older user configuration functions because they provide a consistent services mechanism, interface, and set of messages. It is recommended that you use the Services API functions instead of the obsolete user configuration functions. The isc_xxxx_user() functions are still present in InterBase for backward compatibility, but they are likely to be removed from the product in a future release.

Advance To:

• Administering Software Activation Certificates