Administration API (isc_service_start) - Functional Specification

Service: isc_action_svc_backup

Purpose: tell the server to initiate a database backup. The server must have file open access to the backup file being created.

Notes:

The username and password used to connect to the services manager will be used to connect to the database for backup. This helps add some degree of security for this operation. Only the SYSDBA user or the owner of the database will be able to backup a database.

To split the backup among many different files, specifiy isc_spb_bkp_file and isc_spb_bkp_length for each backup file to create. The very last file does not need to have a length specified. Any remaining information will spillover into the last file. This will allow the backup service to write to more than one backup file. Any spillover of information between files will continue to the last file. If the last file can not be written to, then an error will result.

Under normal circumstances, when backing up a database, the backup file will always be located on the server machine since the backup program can not open a file over a network connection. The backup process can create a remote file if the following conditions are true:

• The server is running on Windows NT
• The path to the backup file is specified as a UNC name
• The destination for the file is another Windows NT machine or machine which can be connected to via UNC naming conventions
• -OR- the destination drive is mounted via NFS (or some equivalent) on the machine running the InterBase server.

Service: isc_action_svc_restore

Purpose: tell the server to initiate a database restore. The server must have file open access to the backup file being restored

Notes:

The username and password used to connect to the services manager will be used to connect to the database for restore. This helps add some degree of security for this operation.

Only the SYSDBA or owner of a database may use `isc_spb_res_replac`e to overwrite an existing database

Service: isc_action_svc_repair

Purpose: tell the server to start repair options on the database specified

Notes:

When requesting information about limbo transactions, the response buffer will have the following format:

• Single database transaction being returned:

  isc_info_svc_limbo_trans
  isc_spb_single_tra_id
      <transaction id>
  

• Multiple database transaction being returned:

  isc_info_svc_limbo_trans
  isc_spb_multi_tra_id
  isc_spb_tra_host_site
    <length>
    <data>
  isc_spb_tra_id
    <transaction id>
  isc_spb_tra_state
    isc_spb_tra_state_limbo |
    isc_spb_tra_state_commit |
    isc_spb_tra_state_rollback |
    isc_spb_tra_state_unknown
  isc_spb_tra_remote_site
    <length>
    <data>
  isc_spb_tra_db_path
    <length>
    <data>
  isc_spb_tra_advise
    isc_spb_tra_advise_commit |
    isc_spb_tra_advise_rollback |
    isc_spb_tra_advise_unknown
  

Service: isc_action_svc_properties

Purpose: tells the server to change the database properties to the ones specified in the spb

Notes:

To turn off database sweeps, set the sweep interval to 0.

To force a database shutdown without waiting use isc_spb_prp_shutdown_db specifiy the number of seconds to wait as 0.

If using isc_spb_prp_deny_new_`(`attachments or transactions) with a time period, the shutdown will fail if there are still active transactions or attachments to the database.

Only the SYSDBA user or the owner of the database will be able to run this service on a particular database.

Service: isc_action_svc_db_stats

Purpose: tell the server to retrieve database statistics for the database specified

Notes:

Reading header information would normally not require that the server be running. However, in order to read the header information using this API, the server must be running as the logic for doing this is not in the client.

Only the SYSDBA user or the owner of the database will be able to run this service on a particular database.

Service: isc_action_svc_get_ib_log

Purpose: retrieve the interbase.log file from the server if the log file exists. An error is returned if the log file does not exist

Notes:

Prepares the contents of the interbase.log file to send to the client. If the log file does not exist then an error is returned during the call to isc_service_start.

Service: isc_action_svc_add_user

Purpose: tell the server to add the user specified to the security database

Notes:

When adding users to the security database, the only information required is the username and password and are restricted to ASCII characters. An error will result if either peice of information is missing.

The information for first name, middle, and last names are stored as Unicode FSS. If using unicode for this information, the length will need to reflect the number of bytes and not necessarilly the length of the string. The group name is also stored as ASCII.

By default, only SYSDBA is allowed to add user information in the security database, however, no checks are made by this API to enforce this. It is strictly enforced at the database level. This would allow the SYSDBA to grant update privileges to those fields that can be updatable by end users.

Service: isc_action_svc_delete_user

Purpose: tell the sever to remove the user specified from the security database

Notes:

Once a user has been removed from the security database, you will need to create a new user record using isc_action_svc_add_user before that user can connect to the server.

By default, only SYSDBA is allowed to remove user information in the security database, however, no checks are made by this API to enforce this. It is strictly enforced at the database level. This would allow the SYSDBA to grant update priviledges to those fields that can be updatable by end users.

Service: isc_action_svc_modify_user

Purpose: tell the user to make modifications to the record in the security database specified by the username

Notes:

To modify a particular peice of user information, specify its parameter and the new information. To remove a peice of information, specify the parameter, 0 for length and 0 for data. Only information that has a corresponding parameter will be modified and the username will never be modified. For example, if you were to specify the password and groupname, only these two peices of information would be modified, firstname and lastname (for example) would not. To change a username, that user must be removed from the security database and then re-added.

By default, only SYSDBA is allowed to modify user information in the security database, however, no checks are made by this API to enforce this. It is strictly enforced at the database level. This would allow the SYSDBA to grant update priviledges to those fields that can be updatable by end users.

Service: isc_action_svc_display_users

Purpose: retrieves user information for all or the specified user

Notes:

If you want to retrieve information for all users, omit the parameter isc_spb_sec_username and send only the service action

Service: isc_action_svc_add_license

Purpose: convert the license ID and key to a valid license and add it to the server's license file.

Notes:

The server will need to be restarted if the license being added changes the server from a local server to a remote server. This is necessary because the listener threads are started and allocated once the server starts up. If the ID and key being added simply add user licenses to the server, no server restart is needed.

This service can also be used to add evaluation licenses. Evaluation licenses, however, can not be removed using the services manager or any other means.

Only the SYSDBA user can add licenses.

Service: isc_action_svc_remove_license

Purpose: tell the server to remove the license specified by the key

Notes:

The server will need to be restarted if the license being removed changes the server's state from a remote server to a local server. This is necessary because the listener threads will need to be shut down to complete the operation and cannot be shutdown while the server is in use. If the ID and key being removed simply removes user licenses to the server, no server restart is needed.

This service will not remove evaluation licenses.

Only the SYSDBA user can remove licenses.

Service: isc_action_svc_lock_stats (* IF TIME PERMITS - CURRENTLY NOT IN InterBase V6.0 *)

Purpose: tell the server to retrieve lock manager statistics from the server

Notes:

This feature is slated for 'IF TIME PERMITS' since the output of a lock print is very difficult for the user to understand. There is currently no time available to reformat the results to be easier to understand and is beyond the scope of this project.

For each of the above flags (isc_spb_lck_contents, summary, wait, and stats) a sample and seconds value can be specified. In these circumstances the service buffer would look like the following:

1.      ISC_ULONG    options = 0;
2.      options |= isc_lck_wait;
3.
4.      *spb++ = isc_spb_lck_secs;
5.      ADD_SPB_LENGTH (spb, 4);
6.      ADD_SPB_DATA (spb, 10);   /* take a sample every 10 seconds */
7.
8.      *spb++ = isc_spb_lck_sample;
9.      ADD_SPB_LENGTH (spb, 4);
10.     ADD_SPB_DATA (spb, 10);    /* take 10 samples */
11.
12.     *spb++ = isc_spb_options;
13.     ADD_SPB_DATA (spb, options);

It is important to note that all error information for these services must be retrieved by querying the service. The status vector for isc_service_query will consist of errors for any service that is currently running as well as for any query request made. Because of this fact, it is recommended that a call to isc_service_query that requests information about a running service (by specifying isc_info_svc_line or isc_info_svc_eof) not be mixed with a general service manager query (using isc_info_svc calls).