Help for Foxhound 5.0.5516a

Table of Contents [RisingRoad]

search engine by freefind advanced

10. Monitor Sessions API

10.1 Introduction
10.2 Stored Procedure Calls 10.3 Web Service Requests

create_or_replace_connection_string createOrReplaceConnectionString Create or change a named connection string to be used by Foxhound to connect to a target database

delete_connection_string deleteConnectionString Delete a named connection string from the Foxhound database

start_monitor_session startMonitorSession Use a named connection string to start a Foxhound Database Monitor sampling session

stop_monitor_session stopMonitorSession Issue an asynchronous request to stop a Foxhound Database Monitor sampling session

delete_monitor_session deleteMonitorSession Delete a Foxhound Database Monitor sampling session from the Foxhound database.

disable_enforce_sample_schedule disableEnforceSampleSchedule Disable (uncheck) the Enforce the Sample Schedule option for a Database Monitor sampling session

enable_enforce_sample_schedule enableEnforceSampleSchedule Enable (check) the Enforce the Sample Schedule option for a Database Monitor sampling session

set_database_authentication setDatabaseAuthentication Create, set or delete the DATABASE_AUTHENTICATION option to run Foxhound on the SQL Anywhere OEM Edition

turn_off_ping_only_sampling turnOffPingOnlySampling Disable (uncheck) the Perform Ping-Only Sampling option for a Database Monitor sampling session

turn_on_ping_only_sampling turnOnPingOnlySampling Enable (check) the Perform Ping-Only Sampling option for a Database Monitor sampling session

Foxhound 5 ť 10. Monitor Sessions API

10.1 Introduction

The Foxhound Monitor Sessions API is a new feature that allows users to integrate their application with Foxhound and allow it to perform some operations available in Foxhound.

It provides the capability to create and delete target database connection strings, and to start, stop and delete Foxhound Database Monitor sampling sessions. This integration can be used to automate these operations rather than use the Foxhound GUI.

Two REST interfaces are provided: stored procedure CALL and SELECT statements (for ISQL, etc) and HTTP web service requests (for XMLHttpRequest, etc). Responses are provided as single-row-single-column result sets consisting of 'OK' or an error message string.

Foxhound 5 ť 10. Monitor Sessions API

10.2 Stored Procedure Calls

create_or_replace_connection_string Create or change a named connection string to be used by Foxhound to connect to a target database

delete_connection_string Delete a named connection string from the Foxhound database

start_monitor_session Use a named connection string to start a Foxhound Database Monitor sampling session

stop_monitor_session Issue an asynchronous request to stop a Foxhound Database Monitor sampling session

delete_monitor_session Delete a Foxhound Database Monitor sampling session from the Foxhound database.

disable_enforce_sample_schedule Disable (uncheck) the Enforce the Sample Schedule option for a Database Monitor sampling session

enable_enforce_sample_schedule Enable (check) the Enforce the Sample Schedule option for a Database Monitor sampling session

set_database_authentication Create, set or delete the DATABASE_AUTHENTICATION option to run Foxhound on the SQL Anywhere OEM Edition

turn_off_ping_only_sampling Disable (uncheck) the Perform Ping-Only Sampling option for a Database Monitor sampling session

turn_on_ping_only_sampling Enable (check) the Perform Ping-Only Sampling option for a Database Monitor sampling session

The SQL Anywhere user id ADMIN and password SQL can be used to connect to the foxhound5.db database to execute API stored procedure calls:
-c "ENG=foxhound5; DBN=f; UID=ADMIN; PWD=SQL; DRIVER=SQL Anywhere 17;"
The shortcut Start - Foxhound5 - 11 Admin Update via ISQL is provided to launch ISQL.
You can change the password, but you don't have to:
ALTER USER ADMIN IDENTIFIED BY 'tHe Qu!cK bR^Wn Fo#'; 
Administrative Tip: The ADMIN user id can do everything ADHOC can do, plus more, and it can see all the same Foxhound database views and other objects that the ADHOC user id can see. For more information about the ADHOC user id see 8. Adhoc Queries.
Administrative Tip: The shortcut 11 Admin Update via ISQL always prompts for the password, so you don't have the change the underlying Windows command file after changing the password.

Foxhound 5 ť 10. Monitor Sessions API ť 10.2 Stored Procedure Calls

create_or_replace_connection_string Stored Procedure

Create a new connection string to be used by Foxhound to connect to a target database if the connection string name doesn't already exist, or update an existing connection string if the name does exist.
Procedure Definition
CREATE PROCEDURE create_or_replace_connection_string ( 
   IN @connection_string_name      VARCHAR ( 128 ),
   IN @connection_string           LONG VARCHAR )
   RESULT ( @result LONG VARCHAR )
Parameters

@connection_string_name
A required non-empty VARCHAR ( 128 ) connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

@connection_string
A required non-empty LONG VARCHAR connection string that will be stored as-is.

Returns
This procedure returns a single-row result set consisting of a single LONG VARCHAR column which contains 'OK' if the call succeeded or an error message if there was a problem.
Remarks
This procedure roughly corresponds to the Save button on the String tab of the Foxhound Menu page.
If necessary this procedure will insert a new row in the adhoc view connection_string; no corresponding row will be inserted into the sampling_options adhoc view yet.
A connection string created with this procedure will not be immediately visible in the Foxhound GUI; i.e., you will have to refresh the Foxhound Menu page to see the new connection string in the "Choose a connection string:" dropdown on the String tab.
This procedure does not check the connection string for correctness; that won't happen until Foxhound uses it to make a connection to the target database.
If the Foxhound Database Monitor is already connected to the target database when this procedure updates the connection string that was used, the current connection won't be affected. That won't happen until Foxhound reconnects; e.g., when you stop and start the sampling session.
Examples
-- 1. Successful call

SELECT * FROM create_or_replace_connection_string ( 
                 'API test ddd17', 
                 'ENG=ddd17; DBN=ddd17; UID=dba; PWD=sql; DRIVER=SQL Anywhere 17;' ); 

@result
'OK'

-- 2. Unsuccessful call

SELECT * FROM create_or_replace_connection_string ( 
                 'API test ddd17 (offline)', 
                 'ENG=ddd17; DBN=ddd17; UID=dba; PWD=sql; DRIVER=SQL Anywhere 17;' ); 

@result
'DIAG 2021-06-06 15:32:19.411 API create_or_replace_connection_string ERROR: The "(offline)" suffix is not supported by this API.'

-- 3. Adhoc query

SELECT connection_string_name, connection_string
  FROM connection_string
 WHERE connection_string_name LIKE 'API test%';
 ORDER BY connection_string_name;

connection_string_name,connection_string
'API test ddd17','ENG=ddd17; DBN=ddd17; UID=dba; PWD=sql; DRIVER=SQL Anywhere 17;'
Related Information
Adhoc Views: connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.

Foxhound 5 ť 10. Monitor Sessions API ť 10.2 Stored Procedure Calls

delete_connection_string Stored Procedure

Delete an existing named connection string from the Foxhound database.
Procedure Definition
CREATE PROCEDURE delete_connection_string (  
   IN @connection_string_name      VARCHAR ( 128 ) )
   RESULT ( @result LONG VARCHAR )
Parameter

@connection_string_name
A required non-empty VARCHAR ( 128 ) connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This procedure returns a single-row result set consisting of a single LONG VARCHAR column which contains 'OK' if the call succeeded or an error message if there was a problem.
Remarks
This procedure roughly corresponds to the Delete button on the String tab of the Foxhound Menu page.
If successful, this procedure deletes one row from the adhoc view connection_string.
A connection string deleted with this procedure will not immediately disappear from the Foxhound GUI; i.e., you will have to refresh the Foxhound Menu page to see the new connection string disappear from the "Choose a connection string:" dropdown on the String tab.
This procedure will not delete a connection string that was used to start a Database Monitor sampling session that still exists, even if that sampling session has been stopped.
Examples
-- 1. Successful call

SELECT * FROM delete_connection_string ( 'API test ddd17' ); 

@result
'OK'

-- 2. Unsuccessful calls

SELECT * FROM delete_connection_string ( 'API test ddd17' ); 

@result
'DIAG 2021-06-07 11:18:27.337 API delete_connection_string ERROR: The connection string does not exist.'

SELECT * FROM delete_connection_string ( 'test (DSN)' ); 

@result
'DIAG 2021-06-07 11:23:32.822 API delete_connection_string ERROR: The "(DSN)" suffix is not supported by this API.'

CALL create_or_replace_connection_string ( 'dummy', 'dummy' );
CALL start_monitor_session ( 'dummy' ); 
SELECT * FROM delete_connection_string ( 'dummy' ); 

@result
'DIAG 2021-06-07 16:07:34.406 API delete_connection_string ERROR: Delete the monitor session before the connection string.'
Related Information
Adhoc Views: connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.

Foxhound 5 ť 10. Monitor Sessions API ť 10.2 Stored Procedure Calls

start_monitor_session Stored Procedure

Use an existing named connection string to create and start a new Foxhound Database Monitor sampling session, or to start an existing sampling session that uses the named connection string but is currently stopped.
Procedure Definition
CREATE PROCEDURE start_monitor_session ( 
   IN @connection_string_name      VARCHAR ( 128 ) )
   RESULT ( @result LONG VARCHAR )
Parameter

@connection_string_name
A required non-empty VARCHAR ( 128 ) connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This procedure returns a single-row result set consisting of a single LONG VARCHAR column which contains 'OK' if the call succeeded or an error message if there was a problem.
Remarks
This procedure roughly corresponds to the Monitor Database button on the String tab of the Foxhound Menu page.
If necessary this procedure will insert a new row in the adhoc view sampling_options, establishing a one-to-one correspondence between the new sampling_options.sampling_id value and the existing connection_string.connection_string_name value.
This procedure will return an error message if the sampling session has already been started, or if a Monitor Options - Sample Schedule is actively controlling when this monitor session is started and stopped.
This procedure will return 'OK' if the sampling session was successfully started even if Foxhound can't connect to the target database using the named connection string. The sampling session will continue to run and Foxhound will keep trying to connect indefinitely.
Examples
-- 1. Successful call

SELECT * FROM start_monitor_session ( 'API test ddd17' ); 

@result
'OK'

-- 2. Unsuccessful call

SELECT * FROM start_monitor_session ( 'API test ddd17' ); 

@result
'DIAG 2021-06-07 11:29:41.009 API start_monitor_session ERROR: The monitor session is already starting or running.'

-- 3. Adhoc query

SELECT sampling_id, selected_name, sampling_should_be_running, connected_ok, connection_status_message
  FROM sampling_options
 WHERE selected_name LIKE 'API test%'
 ORDER BY selected_name;

-- When the monitor session is running and sampling is successful:

sampling_id,selected_name,sampling_should_be_running,connected_ok,connection_status_message
29,'API test ddd17','Y','Y','Sampling OK'

-- When the monitor session is running but Foxhound can't connect:

sampling_id,selected_name,sampling_should_be_running,connected_ok,connection_status_message
29,'API test ddd17','Y','N','Database server not found'
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API ť 10.2 Stored Procedure Calls

stop_monitor_session Stored Procedure

Issue an asynchronous request to stop the Database Monitor sampling session that is using the named connection string and is currently started.
Procedure Definition
CREATE PROCEDURE stop_monitor_session ( 
   IN @connection_string_name      VARCHAR ( 128 ) )
   RESULT ( @result LONG VARCHAR )
Parameter

@connection_string_name
A required non-empty VARCHAR ( 128 ) connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This procedure returns a single-row result set consisting of a single LONG VARCHAR column which contains 'OK' if the call succeeded or an error message if there was a problem.
Remarks
This procedure roughly corresponds to the Stop Sampling button on the Monitor page, and to the Start or Cancel link on the Monitor tab of the Foxhound Menu page.
This procedure will return an error message if the sampling session has already been stopped, or if a Monitor Options - Sample Schedule is actively controlling when this monitor session is started and stopped.
This procedure will return 'OK' if Foxhound accepts the request to stop the sampling session even if that request is not immediately satisfied. This delay is usually very short, but a long delay may cause a subsequent call to delete_monitor_session to fail.
The term "asynchronous request" refers to Foxhound's internal process, which is separate from requesting the corresponding web service stopMonitorSession via XMLHttpRequest with async: true.
Examples
-- 1. Successful call

SELECT * FROM stop_monitor_session ( 'API test ddd17' ); 

@result
'OK'

-- 2. Unsuccessful call

SELECT * FROM stop_monitor_session ( 'API test ddd17' ); 

@result
'DIAG 2021-06-07 12:08:20.360 API stop_monitor_session ERROR: The monitor session is currently stopped or stopping.'

-- 3. Adhoc query

SELECT sampling_id, selected_name, sampling_should_be_running, connected_ok, connection_status_message
  FROM sampling_options
 WHERE selected_name LIKE 'API test%'
 ORDER BY selected_name;

sampling_id,selected_name,sampling_should_be_running,connected_ok,connection_status_message
29,'API test ddd17','N','N','Sampling stopped'
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API ť 10.2 Stored Procedure Calls

delete_monitor_session Stored Procedure

Delete the Database Monitor sampling session that was created for the named connection string and is currently stopped.
Procedure Definition
CREATE PROCEDURE delete_monitor_session (
   IN @connection_string_name      VARCHAR ( 128 ) )
   RESULT ( @result LONG VARCHAR )
Parameter

@connection_string_name
A required non-empty VARCHAR ( 128 ) connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This procedure returns a single-row result set consisting of a single LONG VARCHAR column which contains 'OK' if the call succeeded or an error message if there was a problem.
Remarks
This procedure roughly corresponds to the Delete link on the Monitor tab of the Foxhound Menu page.
If successful, this procedure deletes one row from the adhoc view sampling_options plus related rows in all the child adhoc views. Note that child rows in the actual base tables supporting the adhoc views ping_log, sample_connection, sample_detail, sample_header and server_message are not deleted until the Foxhound purge runs, but that's ok because the CREATE VIEW statements contain a WHERE EXISTS predicate to exclude the "orphan" rows.
This procedure will return an error message if the sampling session has not stopped.
Examples
-- 1. Successful call

SELECT * FROM delete_monitor_session ( 'API test ddd17' ); 

@result
'OK'

-- 2. Unsuccessful call

SELECT * FROM delete_monitor_session ( 'API test ddd17' ); 

@result
'DIAG 2021-06-07 13:45:18.489 API delete_monitor_session ERROR: The monitor session is currently running, starting, or taking more than 5 seconds to stop.'
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API ť 10.2 Stored Procedure Calls

disable_enforce_sample_schedule Stored Procedure

Disable (uncheck) the Enforce the Sample Schedule option for the Database Monitor sampling session that was created for the named connection string.
Procedure Definition
CREATE PROCEDURE disable_enforce_sample_schedule (
   IN @connection_string_name      VARCHAR ( 128 ) )
   RESULT ( @result LONG VARCHAR )
Parameter

@connection_string_name
A required non-empty VARCHAR ( 128 ) connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This procedure returns a single-row result set consisting of a single LONG VARCHAR column which contains 'OK' if the call succeeded or an error message if there was a problem.
Remarks
This procedure roughly corresponds to selecting a target database on the Monitor Options page, unchecking Enforce the Sample Schedule in section 5. Sample Schedule, then clicking Save.
This procedure is stateless. No history of calls is maintained. Each call will proceed regardless of whether the sample schedule was previously enabled or disabled. The sample schedule will be disabled after the call, and the procedure does not return an error message it was already disabled.
A common reason to call this procedure is to stop these other API procedures from returning the error message "A Sample Schedule is in effect": start_monitor_session, stop_monitor_session, and delete_monitor_session.
To undo the effect of this procedure, see enable_enforce_sample_schedule.
Administrative Tip: These two procedures (enable_enforce_sample_schedule and disable_enforce_sample_schedule) have no effect on

whether or not the Sample Schedule actually affects the target database, or

whether or not calls to start_monitor_session, stop_monitor_session or delete_monitor_session will work

unless the separate Global Overrides - Enable Schedules option is also checked.
Examples
-- 1. A change to user credentials that won't go into effect until Foxhound reconnects

SELECT * FROM create_or_replace_connection_string ( -- change the password
                 'API test ddd17', 
                 'ENG=ddd17; DBN=ddd17; UID=dba; PWD=NeWpAsSwOrd; DRIVER=SQL Anywhere 17;' ); 
@result
'OK'

-- 2. Unsuccessful call to stop the monitor session 

SELECT * FROM stop_monitor_session ( 'API test ddd17' ); -- step 1 of forcing Foxhound to reconnect
@result
'DIAG 2021-06-12 16:07:02.706 API stop_monitor_session ERROR: A Sample Schedule is in effect.'

-- 3. Successful calls to show the temporary disabling of a Sample Schedule

SELECT * FROM disable_enforce_sample_schedule ( 'API test ddd17' ); -- temporarily bypass scheduling
@result
'OK'

SELECT * FROM stop_monitor_session ( 'API test ddd17' );            -- step 1 of forcing Foxhound to reconnect  
@result
'OK'

SELECT * FROM start_monitor_session ( 'API test ddd17' );           -- step 2 of forcing Foxhound to reconnect  
@result
'OK'

SELECT * FROM enable_enforce_sample_schedule ( 'API test ddd17' );  -- restore scheduling
@result
'OK'

-- Adhoc Query

SELECT schedule.enforce_this_schedule            AS "Enforce the Sample Schedule",
       STRING ( sampling_options.sampling_id, 
                ' - ', 
                sampling_options.selected_name ) AS "For Target Database"
  FROM schedule
          INNER JOIN sampling_options
                  ON sampling_options.sampling_id = schedule.sampling_id
 WHERE schedule.criteria_set_type     = 'Target Specific' -- fixed value
   AND schedule.schedule_type         = 'Sample'          -- fixed value
   AND sampling_options.selected_tab  = '2'               -- fixed value
   AND sampling_options.selected_name = 'API test ddd17'; -- EDIT THIS

Enforce the Sample Schedule,For Target Database
'Y','14 - API test ddd17'
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API ť 10.2 Stored Procedure Calls

enable_enforce_sample_schedule Stored Procedure

Enable (check) the Enforce the Sample Schedule option for the Database Monitor sampling session that was created for the named connection string.
Procedure Definition
CREATE PROCEDURE enable_enforce_sample_schedule (
   IN @connection_string_name      VARCHAR ( 128 ) )
   RESULT ( @result LONG VARCHAR )
Parameter

@connection_string_name
A required non-empty VARCHAR ( 128 ) connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This procedure returns a single-row result set consisting of a single LONG VARCHAR column which contains 'OK' if the call succeeded or an error message if there was a problem.
Remarks
This procedure roughly corresponds to selecting a target database on the Monitor Options page, checking Enforce the Sample Schedule in section 5. Sample Schedule, then clicking Save.
This procedure is stateless. No history of calls is maintained. Each call will proceed regardless of whether the sample schedule was previously enabled or disabled. The sample schedule will be enabled after the call, and the procedure does not return an error message it was already enabled.
A common reason to call this procedure is to undo the effect of a previous call to disable_enforce_sample_schedule.
Administrative Tip: These two procedures (enable_enforce_sample_schedule and disable_enforce_sample_schedule) have no effect on

whether or not the Sample Schedule actually affects the target database, or

whether or not calls to start_monitor_session, stop_monitor_session or delete_monitor_session will work

unless the separate Global Overrides - Enable Schedules option is also checked.
Examples
-- 1. A change to user credentials that won't go into effect until Foxhound reconnects

SELECT * FROM create_or_replace_connection_string ( -- change the password
                 'API test ddd17', 
                 'ENG=ddd17; DBN=ddd17; UID=dba; PWD=NeWpAsSwOrd; DRIVER=SQL Anywhere 17;' ); 
@result
'OK'

-- 2. Unsuccessful call to stop the monitor session 

SELECT * FROM stop_monitor_session ( 'API test ddd17' ); -- step 1 of forcing Foxhound to reconnect
@result
'DIAG 2021-06-12 16:07:02.706 API stop_monitor_session ERROR: A Sample Schedule is in effect.'

-- 3. Successful calls to show the temporary disabling of a Sample Schedule

SELECT * FROM disable_enforce_sample_schedule ( 'API test ddd17' ); -- temporarily bypass scheduling
@result
'OK'

SELECT * FROM stop_monitor_session ( 'API test ddd17' );            -- step 1 of forcing Foxhound to reconnect  
@result
'OK'

SELECT * FROM start_monitor_session ( 'API test ddd17' );           -- step 2 of forcing Foxhound to reconnect  
@result
'OK'

SELECT * FROM enable_enforce_sample_schedule ( 'API test ddd17' );  -- restore scheduling
@result
'OK'

-- 4. Adhoc Query

SELECT schedule.enforce_this_schedule            AS "Enforce the Sample Schedule",
       STRING ( sampling_options.sampling_id, 
                ' - ', 
                sampling_options.selected_name ) AS "For Target Database"
  FROM schedule
          INNER JOIN sampling_options
                  ON sampling_options.sampling_id = schedule.sampling_id
 WHERE schedule.criteria_set_type     = 'Target Specific' -- fixed value
   AND schedule.schedule_type         = 'Sample'          -- fixed value
   AND sampling_options.selected_tab  = '2'               -- fixed value
   AND sampling_options.selected_name = 'API test ddd17'; -- EDIT THIS

Enforce the Sample Schedule,For Target Database
'Y','14 - API test ddd17'
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API ť 10.2 Stored Procedure Calls

set_database_authentication Stored Procedure

Create, set or delete the DATABASE_AUTHENTICATION option to run Foxhound on the SQL Anywhere OEM Edition.
Procedure Definition
CREATE PROCEDURE set_database_authentication (
   IN @database_authentication_string    LONG VARCHAR )
   RESULT ( @result LONG VARCHAR )
Parameter

@database_authentication_string
A required LONG VARCHAR string which may be NULL, empty or a database authentication string in the format Company=xxx;Application=yyy;Signature=ddd
This parameter is required but it may be the SQL literal NULL or a string variable containing the NULL value.

Returns
This procedure returns a single-row result set consisting of a single LONG VARCHAR column which contains 'OK' if the call succeeded or an error message if there was a problem.
Remarks
This procedure executes the SET OPTION PUBLIC.DATABASE_AUTHENTICATION statement on the Foxhound database, regardless of what edition of SQL Anywhere is being used.
A successful call

will insert or update the SYSOPTION.setting column WHERE "option" = 'database_authentication' with a non-NULL @database_authentication_string value, or

it will delete the SYSOPTION row WHERE "option" = 'database_authentication' if @database_authentication_string is NULL... because that's how SET OPTION works.

A non-NULL @database_authentication_string value is used as-is; this procedure does not check the format. In particular, the empty string is allowed, as well as all spaces, and leading and trailing spaces are OK.
You can effectively disable database authentication by executing a successful call with a NULL, empty or invalid string; the call will work but authentication won't.
This procedure satisfies requirement number 2 in the following list...
Requirements to Run a Database on the SQL Anywhere OEM Edition

Licence the server engine

Authenticate the database

Authenticate the connection

When you go into the authentication business SAP will give you three keys. The keys are all different but match each other and the publishing company & application names (i.e. they won't work with other keys):
an install key: you use this with dblic.exe -k to create OEM lic files (just like a normal install key).
a database key or signature: this is used once on a database to make it an Authenticated database which will work on the server created with the install key - the setting is persistent. This is done with a SET OPTION command; e.g.
SET OPTION PUBLIC.DATABASE_AUTHENTICATION='Company=xxx;Application=yyy;Signature=ddd'; 
The CALL to set_database_authentication() takes care of the SET OPTION PUBLIC.DATABASE_AUTHENTICATION, including the requirement to have the SET ANY SECURITY OPTION system privilege. That's because set_database_authentication was created inside the Foxhound database with SQL SECURITY DEFINER in effect, and the DEFINER user does have SET ANY SECURITY OPTION.
a connection key or signature: This is used by connections to the database. Each connection has a 30 second (or so) grace period to set a temporary Connection_authentication option; e.g.
SET TEMPORARY OPTION CONNECTION_AUTHENTICATION='Company=xxx;Application=yyy;Signature=ccc'
Administrative Tip: These requirements may apply to your applications' ability to connect to the Foxhound database, but they do not apply to Foxhound's ability to connect to target databases. Those are two separate issues. In fact, the Foxhound Database Monitor is able to connect to an authenticated target database running on the OEM Edition with no action on your part because it uses the remote server feature which is self-authenticating. In particular, you don't have to worry about the InitString connection parameter or the SET TEMPORARY OPTION CONNECTION_AUTHENTICATION statement when creating a connection string for your target database.
Examples
-- 1. Successful call to SET OPTION PUBLIC.DATABASE_AUTHENTICATION = @database_authentication_string 

SELECT * FROM set_database_authentication ( 'Company=xxx;Application=yyy;Signature=ddd' );

@result
'OK'

-- 2. Query to show the option has been successfully set

SELECT * FROM SYSOPTION WHERE "option" = 'database_authentication';

user_id,option,setting
2,'database_authentication','Company=xxx;Application=yyy;Signature=ddd'

-- 3. Query to show the current server edition and database authentication status

SELECT PROPERTY ( 'ServerEdition' ), DB_PROPERTY ( 'Authenticated' );

PROPERTY('ServerEdition'),DB_PROPERTY('Authenticated')
'Workgroup','No'

-- 4. Successful call to delete the option setting

SELECT * FROM set_database_authentication ( NULL );

@result
'OK'

-- 5. Query to show the option setting has been deleted

SELECT * FROM SYSOPTION WHERE "option" = 'database_authentication';

user_id,option,setting
[no rows]

Foxhound 5 ť 10. Monitor Sessions API ť 10.2 Stored Procedure Calls

turn_off_ping_only_sampling Stored Procedure

Disable (uncheck) the Perform Ping-Only Sampling option for the Database Monitor sampling session that was created for the named connection string.
Procedure Definition
CREATE PROCEDURE turn_off_ping_only_sampling (
   IN @connection_string_name      VARCHAR ( 128 ) )
   RESULT ( @result LONG VARCHAR )
Parameter

@connection_string_name
A required non-empty VARCHAR ( 128 ) connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This procedure returns a single-row result set consisting of a single LONG VARCHAR column which contains 'OK' if the call succeeded or an error message if there was a problem.
Remarks
This procedure roughly corresponds to selecting a target database on the Monitor Options page, unchecking Perform Ping-Only Sampling in section 16. Ping Settings, then clicking Save.
This procedure is stateless. No history of calls is maintained. Each call will proceed regardless of whether ping-only sampling previously turned on or off. Ping-only sampling will be turned off after the call, and the procedure does not return an error message it was already off.
One reason to call this procedure is to force Foxhound to reconnect to the target database when subsequently calling stop_monitor_session and start_monitor_session, and one reason to do that is to force Foxhound to refresh the SPs: YYY procedures on the target database. If Ping-Only Sampling is in effect, Foxhound will not refresh the SPs: YYY procedures when the monitor session is stopped and restarted because those procedures aren't required for Ping-Only Sampling (ok, it's a bug, but it's not getting fixed :)
To undo the effect of this procedure, see turn_on_ping_only_sampling.
Examples
-- 1. Successful calls to show the temporary disabling of Ping-Only Sampling

SELECT * FROM turn_off_ping_only_sampling ( 'API test ddd17' ); -- start gathering sample data
@result
'OK'

SELECT * FROM stop_monitor_session ( 'API test ddd17' );        -- step 1 of forcing Foxhound to reconnect  
@result
'OK'

SELECT * FROM start_monitor_session ( 'API test ddd17' );       -- step 2 of forcing Foxhound to reconnect  
@result
'OK'

SELECT * FROM turn_on_ping_only_sampling ( 'API test ddd17' );  -- return to Ping-Only sampling
@result
'OK'

-- 2. Adhoc Query

SELECT alerts_criteria.ping_only_sampling        AS "Perform Ping-Only Sampling",
       STRING ( sampling_options.sampling_id, 
                ' - ', 
                sampling_options.selected_name ) AS "For Target Database"
  FROM alerts_criteria
          INNER JOIN sampling_options
                  ON sampling_options.sampling_id = alerts_criteria.sampling_id
 WHERE alerts_criteria.criteria_set_type = 'Target Specific' -- fixed value
   AND sampling_options.selected_tab     = '2'               -- fixed value
   AND sampling_options.selected_name    = 'API test ddd17'; -- EDIT THIS

Perform Ping-Only Sampling,For Target Database
'Y','14 - API test ddd17'
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API ť 10.2 Stored Procedure Calls

turn_on_ping_only_sampling Stored Procedure

Enable (check) the "Perform Ping-Only Sampling" option for the Database Monitor sampling session that was created for the named connection string.
Procedure Definition
CREATE PROCEDURE turn_on_ping_only_sampling (
   IN @connection_string_name      VARCHAR ( 128 ) )
   RESULT ( @result LONG VARCHAR )
Parameter

@connection_string_name
A required non-empty VARCHAR ( 128 ) connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This procedure returns a single-row result set consisting of a single LONG VARCHAR column which contains 'OK' if the call succeeded or an error message if there was a problem.
Remarks
This procedure roughly corresponds to selecting a target database on the Monitor Options page, checking Perform Ping-Only Sampling in section 16. Ping Settings, then clicking Save.
This procedure is stateless. No history of calls is maintained. Each call will proceed regardless of whether ping-only sampling previously turned on or off. Ping-only sampling will be turned on after the call, and the procedure does not return an error message it was already on.
A common reason to call this procedure is to undo the effect of a previous call to turn_off_ping_only_sampling.
Examples
-- 1. Successful calls to show the temporary disabling of Ping-Only Sampling

SELECT * FROM turn_off_ping_only_sampling ( 'API test ddd17' ); -- start gathering sample data
@result
'OK'

SELECT * FROM stop_monitor_session ( 'API test ddd17' );        -- step 1 of forcing Foxhound to reconnect  
@result
'OK'

SELECT * FROM start_monitor_session ( 'API test ddd17' );       -- step 2 of forcing Foxhound to reconnect  
@result
'OK'

SELECT * FROM turn_on_ping_only_sampling ( 'API test ddd17' );  -- return to Ping-Only sampling
@result
'OK'

-- 2. Adhoc Query

SELECT alerts_criteria.ping_only_sampling        AS "Perform Ping-Only Sampling",
       STRING ( sampling_options.sampling_id, 
                ' - ', 
                sampling_options.selected_name ) AS "For Target Database"
  FROM alerts_criteria
          INNER JOIN sampling_options
                  ON sampling_options.sampling_id = alerts_criteria.sampling_id
 WHERE alerts_criteria.criteria_set_type = 'Target Specific' -- fixed value
   AND sampling_options.selected_tab     = '2'               -- fixed value
   AND sampling_options.selected_name    = 'API test ddd17'; -- EDIT THIS

Perform Ping-Only Sampling,For Target Database
'Y','14 - API test ddd17'
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API

10.3 Web Service Requests

createOrReplaceConnectionString Create or change a named connection string to be used by Foxhound to connect to a target database

deleteConnectionString Delete a named connection string from the Foxhound database

startMonitorSession Use a named connection string to start a Foxhound Database Monitor sampling session

stopMonitorSession Issue an asynchronous request to stop a Foxhound Database Monitor sampling session

deleteMonitorSession Delete a Foxhound Database Monitor sampling session from the Foxhound database.

disableEnforceSampleSchedule Disable (uncheck) the Enforce the Sample Schedule option for a Database Monitor sampling session

enableEnforceSampleSchedule Enable (check) the Enforce the Sample Schedule option for a Database Monitor sampling session

setDatabaseAuthentication Create, set or delete the DATABASE_AUTHENTICATION option to run Foxhound on the SQL Anywhere OEM Edition

turnOffPingOnlySampling Disable (uncheck) the Perform Ping-Only Sampling option for a Database Monitor sampling session

turnOnPingOnlySampling Enable (check) the Perform Ping-Only Sampling option for a Database Monitor sampling session

For sample code see Demo Monitor Sessions API.html in the Foxhound subfolder C:\ProgramData\RisingRoad\Foxhound5\scripts.

Foxhound 5 ť 10. Monitor Sessions API ť 10.3 Web Service Requests

createOrReplaceConnectionString Web Service

Create a new connection string to be used by Foxhound to connect to a target database if the connection string name doesn't already exist, or update an existing connection string if the name does exist.
Service Definition
CREATE SERVICE createOrReplaceConnectionString TYPE 'RAW' AUTHORIZATION OFF USER DBA
   AS CALL create_or_replace_connection_string ( :connectionStringName, :connectionString );
Parameters

connectionStringName
A required non-empty connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

connectionString
A required non-empty connection string that will be stored as-is.

Returns
This service returns a string containing 'OK' if the request succeeded or an error message if there was a problem.
Remarks
This service roughly corresponds to the Save button on the String tab of the Foxhound Menu page.
If necessary this service will insert a new row in the adhoc view connection_string; no corresponding row will be inserted into the sampling_options adhoc view yet.
A connection string created with this service will not be immediately visible in the Foxhound GUI; i.e., you will have to refresh the Foxhound Menu page to see the new connection string in the "Choose a connection string:" dropdown on the String tab.
This service does not check the connection string for correctness; that won't happen until Foxhound uses it to make a connection to the target database.
If the Foxhound Database Monitor is already connected to the target database when this service updates the connection string that was used, the current connection won't be affected. That won't happen until Foxhound reconnects; e.g., when you stop and start the sampling session.
Example
1. JavaScript  -  see Demo Monitor Sessions API.html in C:\ProgramData\RisingRoad\Foxhound5\scripts 

let createOrReplaceConnectionStringXHR = new XMLHttpRequest();
createOrReplaceConnectionStringXHR.onload = function() { 
   if ( createOrReplaceConnectionStringXHR.status === 200 ) {  
      document.getElementById ( 'createOrReplaceConnectionStringDiv' ).innerHTML = createOrReplaceConnectionStringXHR.responseText;
   } else {
      document.getElementById ( 'createOrReplaceConnectionStringDiv' ).innerHTML = 'HTTP status = ' + createOrReplaceConnectionStringXHR.status;
   }
};
function createOrReplaceConnectionString() {
   let requestUrl = 'http://localhost/createOrReplaceConnectionString'  
      + '?connectionStringName=' + document.getElementById ( 'connectionStringName' ).value
      + '&connectionString='     + document.getElementById ( 'connectionString' ).value;
   createOrReplaceConnectionStringXHR.open ( 'GET', requestUrl, true ); 
   createOrReplaceConnectionStringXHR.send();
};

2. CSS

div.response { font-family: "LUCIDA CONSOLE", "COURIER NEW", "COURIER", "monospace"; font-size: 1em; margin-left: 0.5em; }
span.blue-grey-button { background-color: #E6E6E6; color: blue; cursor: pointer; font-family: "VERDANA", "ARIAL", "HELVETICA", "SANS-SERIF"; font-size: 1em; 
                        margin-left: 0.1em; margin-right: 0.1em; padding-left: 0.3em; padding-right: 0.3em; text-decoration: none; }

3. HTML

<input id='connectionStringName' style='height: 1em; text-align: left; width: 20em;' type='text' value='ddd'>
<input id='connectionString' style='height: 1em; text-align: left; width: 50em;' type='text' value='ENG=ddd; DBN=ddd; UID=dba; PWD=sql; DRIVER=SQL Anywhere 17;'>
<span class='blue-grey-button' onClick='createOrReplaceConnectionString();'> createOrReplaceConnectionString </span>
<div class='response' id='createOrReplaceConnectionStringDiv' style='display: inline-block;'> </div> 
Related Information
Adhoc Views: connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.

Foxhound 5 ť 10. Monitor Sessions API ť 10.3 Web Service Requests

deleteConnectionString Web Service

Delete an existing named connection string from the Foxhound database.
Service Definition
CREATE SERVICE deleteConnectionString TYPE 'RAW' AUTHORIZATION OFF USER DBA
   AS CALL delete_connection_string ( :connectionStringName );
Parameter

connectionStringName
A required non-empty connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This service returns a string containing 'OK' if the request succeeded or an error message if there was a problem.
Remarks
This service roughly corresponds to the Delete button on the String tab of the Foxhound Menu page.
If successful, this service deletes one row from the adhoc view connection_string.
A connection string deleted with this service will not immediately disappear from the Foxhound GUI; i.e., you will have to refresh the Foxhound Menu page to see the new connection string disappear from the "Choose a connection string:" dropdown on the String tab.
This service will not delete a connection string that was used to start a Database Monitor sampling session that still exists, even if that sampling session has been stopped.
Example
1. JavaScript  -  see Demo Monitor Sessions API.html in C:\ProgramData\RisingRoad\Foxhound5\scripts 

let deleteConnectionStringXHR = new XMLHttpRequest();
deleteConnectionStringXHR.onload = function() { 
   if ( deleteConnectionStringXHR.status === 200 ) {  
      document.getElementById ( 'deleteConnectionStringDiv' ).innerHTML = deleteConnectionStringXHR.responseText;
   } else {
      document.getElementById ( 'deleteConnectionStringDiv' ).innerHTML = 'HTTP status = ' + deleteConnectionStringXHR.status;
   }
};
function deleteConnectionString() {
   let requestUrl = 'http://localhost/deleteConnectionString'  
      + '?connectionStringName=' + document.getElementById ( 'connectionStringName' ).value;
   deleteConnectionStringXHR.open ( 'GET', requestUrl, true ); 
   deleteConnectionStringXHR.send();
};

2. CSS

div.response { font-family: "LUCIDA CONSOLE", "COURIER NEW", "COURIER", "monospace"; font-size: 1em; margin-left: 0.5em; }
span.blue-grey-button { background-color: #E6E6E6; color: blue; cursor: pointer; font-family: "VERDANA", "ARIAL", "HELVETICA", "SANS-SERIF"; font-size: 1em; 
                        margin-left: 0.1em; margin-right: 0.1em; padding-left: 0.3em; padding-right: 0.3em; text-decoration: none; }

3. HTML

<input id='connectionStringName' style='height: 1em; text-align: left; width: 20em;' type='text' value='ddd'>
<span class='blue-grey-button' onClick='deleteConnectionString();'> deleteConnectionString </span>
<div class='response' id='deleteConnectionStringDiv' style='display: inline-block;'> </div> 
Related Information
Adhoc Views: connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.

Foxhound 5 ť 10. Monitor Sessions API ť 10.3 Web Service Requests

startMonitorSession Web Service

Use an existing named connection string to create and start a new Foxhound Database Monitor sampling session, or to start an existing sampling session that uses the named connection string but is currently stopped.
Service Definition
CREATE SERVICE startMonitorSession TYPE 'RAW' AUTHORIZATION OFF USER DBA
   AS CALL start_monitor_session ( :connectionStringName );
Parameter

connectionStringName
A required non-empty connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This service returns a string containing 'OK' if the request succeeded or an error message if there was a problem.
Remarks
This service roughly corresponds to the Monitor Database button on the String tab of the Foxhound Menu page.
If necessary this service will insert a new row in the adhoc view sampling_options, establishing a one-to-one correspondence between the new sampling_options.sampling_id value and the existing connection_string.connection_string_name value.
This service will return an error message if the sampling session has already been started, or if a Monitor Options - Sample Schedule is actively controlling when this monitor session is started and stopped.
This service will return 'OK' if the sampling session was successfully started even if Foxhound can't connect to the target database using the named connection string. The sampling session will continue to run and Foxhound will keep trying to connect indefinitely.
Example
1. JavaScript  -  see Demo Monitor Sessions API.html in C:\ProgramData\RisingRoad\Foxhound5\scripts 


let startMonitorSessionXHR = new XMLHttpRequest();
startMonitorSessionXHR.onload = function() { 
   if ( startMonitorSessionXHR.status === 200 ) {  
      document.getElementById ( 'startMonitorSessionDiv' ).innerHTML = startMonitorSessionXHR.responseText;
   } else {
      document.getElementById ( 'startMonitorSessionDiv' ).innerHTML = 'HTTP status = ' + startMonitorSessionXHR.status;
   }
};
function startMonitorSession() {
   let requestUrl = 'http://localhost/startMonitorSession'  
      + '?connectionStringName=' + document.getElementById ( 'connectionStringName' ).value;
   startMonitorSessionXHR.open ( 'GET', requestUrl, true ); 
   startMonitorSessionXHR.send();
};

2. CSS

div.response { font-family: "LUCIDA CONSOLE", "COURIER NEW", "COURIER", "monospace"; font-size: 1em; margin-left: 0.5em; }
span.blue-grey-button { background-color: #E6E6E6; color: blue; cursor: pointer; font-family: "VERDANA", "ARIAL", "HELVETICA", "SANS-SERIF"; font-size: 1em; 
                        margin-left: 0.1em; margin-right: 0.1em; padding-left: 0.3em; padding-right: 0.3em; text-decoration: none; }

3. HTML

<input id='connectionStringName' style='height: 1em; text-align: left; width: 20em;' type='text' value='ddd'>
<span class='blue-grey-button' onClick='startMonitorSession();'> startMonitorSession </span>
<div class='response' id='startMonitorSessionDiv' style='display: inline-block;'> </div> 
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API ť 10.3 Web Service Requests

stopMonitorSession Web Service

Issue an asynchronous request to stop the Database Monitor sampling session that is using the named connection string and is currently started.
Service Definition
CREATE SERVICE stopMonitorSession TYPE 'RAW' AUTHORIZATION OFF USER DBA
   AS CALL stop_monitor_session ( :connectionStringName );
Parameter

connectionStringName
A required non-empty connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This service returns a string containing 'OK' if the request succeeded or an error message if there was a problem.
Remarks
This service roughly corresponds to the Stop Sampling button on the Monitor page, and to the Start or Cancel link on the Monitor tab of the Foxhound Menu page.
This service will return an error message if the sampling session has already been stopped, or if a Monitor Options - Sample Schedule is actively controlling when this monitor session is started and stopped.
This service will return 'OK' if Foxhound accepts the request to stop the sampling session even if that request is not immediately satisfied. This delay is usually very short, but a long delay may cause a subsequent call to delete_monitor_session to fail.
The term "asynchronous request" refers to Foxhound's internal process, which is separate from requesting the service via XMLHttpRequest with async: true.
Example
1. JavaScript  -  see Demo Monitor Sessions API.html in C:\ProgramData\RisingRoad\Foxhound5\scripts 

let stopMonitorSessionXHR = new XMLHttpRequest();
stopMonitorSessionXHR.onload = function() { 
   if ( stopMonitorSessionXHR.status === 200 ) {  
      document.getElementById ( 'stopMonitorSessionDiv' ).innerHTML = stopMonitorSessionXHR.responseText;
   } else {
      document.getElementById ( 'stopMonitorSessionDiv' ).innerHTML = 'HTTP status = ' + stopMonitorSessionXHR.status;
   }
};
function stopMonitorSession() {
   let requestUrl = 'http://localhost/stopMonitorSession'  
      + '?connectionStringName=' + document.getElementById ( 'connectionStringName' ).value;
   stopMonitorSessionXHR.open ( 'GET', requestUrl, true ); 
   stopMonitorSessionXHR.send();
};

2. CSS

div.response { font-family: "LUCIDA CONSOLE", "COURIER NEW", "COURIER", "monospace"; font-size: 1em; margin-left: 0.5em; }
span.blue-grey-button { background-color: #E6E6E6; color: blue; cursor: pointer; font-family: "VERDANA", "ARIAL", "HELVETICA", "SANS-SERIF"; font-size: 1em; 
                        margin-left: 0.1em; margin-right: 0.1em; padding-left: 0.3em; padding-right: 0.3em; text-decoration: none; }

3. HTML

<input id='connectionStringName' style='height: 1em; text-align: left; width: 20em;' type='text' value='ddd'>
<span class='blue-grey-button' onClick='stopMonitorSession();'> stopMonitorSession </span>
<div class='response' id='stopMonitorSessionDiv' style='display: inline-block;'> </div> 
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API ť 10.3 Web Service Requests

deleteMonitorSession Web Service

Delete the Database Monitor sampling session that was created for the named connection string and is currently stopped.
Service Definition
CREATE SERVICE deleteMonitorSession TYPE 'RAW' AUTHORIZATION OFF USER DBA
   AS CALL delete_monitor_session ( :connectionStringName );
Parameter

connectionStringName
A required non-empty connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This service returns a string containing 'OK' if the request succeeded or an error message if there was a problem.
Remarks
This service roughly corresponds to the Delete link on the Monitor tab of the Foxhound Menu page.
If successful, this service deletes one row from the adhoc view sampling_options plus related rows in all the child adhoc views. Note that child rows in the actual base tables supporting the adhoc views ping_log, sample_connection, sample_detail, sample_header and server_message are not deleted until the Foxhound purge runs, but that's ok because the CREATE VIEW statements contain a WHERE EXISTS predicate to exclude the "orphan" rows.
This service will return an error message if the sampling session has not stopped.
Example
1. JavaScript  -  see Demo Monitor Sessions API.html in C:\ProgramData\RisingRoad\Foxhound5\scripts 

let deleteMonitorSessionXHR = new XMLHttpRequest();
deleteMonitorSessionXHR.onload = function() { 
   if ( deleteMonitorSessionXHR.status === 200 ) {  
      document.getElementById ( 'deleteMonitorSessionDiv' ).innerHTML = deleteMonitorSessionXHR.responseText;
   } else {
      document.getElementById ( 'deleteMonitorSessionDiv' ).innerHTML = 'HTTP status = ' + deleteMonitorSessionXHR.status;
   }
};
function deleteMonitorSession() {
   let requestUrl = 'http://localhost/deleteMonitorSession'  
      + '?connectionStringName=' + document.getElementById ( 'connectionStringName' ).value;
   deleteMonitorSessionXHR.open ( 'GET', requestUrl, true ); 
   deleteMonitorSessionXHR.send();
};

2. CSS

div.response { font-family: "LUCIDA CONSOLE", "COURIER NEW", "COURIER", "monospace"; font-size: 1em; margin-left: 0.5em; }
span.blue-grey-button { background-color: #E6E6E6; color: blue; cursor: pointer; font-family: "VERDANA", "ARIAL", "HELVETICA", "SANS-SERIF"; font-size: 1em; 
                        margin-left: 0.1em; margin-right: 0.1em; padding-left: 0.3em; padding-right: 0.3em; text-decoration: none; }

3. HTML

<input id='connectionStringName' style='height: 1em; text-align: left; width: 20em;' type='text' value='ddd'>
<span class='blue-grey-button' onClick='deleteMonitorSession();'> deleteMonitorSession </span>
<div class='response' id='deleteMonitorSessionDiv' style='display: inline-block;'> </div> 
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API ť 10.3 Web Service Requests

disableEnforceSampleSchedule Web Service

Disable (uncheck) the Enforce the Sample Schedule option for the Database Monitor sampling session that was created for the named connection string.
Service Definition
CREATE SERVICE disableEnforceSampleSchedule TYPE 'RAW' AUTHORIZATION OFF USER DBA
   AS CALL disable_enforce_sample_schedule ( :connectionStringName );
Parameter

connectionStringName
A required non-empty connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This service returns a string containing 'OK' if the request succeeded or an error message if there was a problem.
Remarks
This service roughly corresponds selecting a target database on the Monitor Options page, unchecking Enforce the Sample Schedule in section 5. Sample Schedule, then clicking Save.
This service is stateless. No history of requests is maintained. Each request will proceed regardless of whether the sample schedule was previously enabled or disabled. The sample schedule will be disabled after the request, and the service does not return an error message it was already disabled.
A common reason to request this service to stop these other API services from returning the error message "A Sample Schedule is in effect": startMonitorSession, stopMonitorSession, and deleteMonitorSession.
To undo the effect of this service, see enableEnforceSampleSchedule.
Examples
1. JavaScript  -  see Demo Monitor Sessions API.html in C:\ProgramData\RisingRoad\Foxhound5\scripts 

let disableEnforceSampleScheduleXHR = new XMLHttpRequest();
disableEnforceSampleScheduleXHR.onload = function() { 
   if ( disableEnforceSampleScheduleXHR.status === 200 ) {  
      document.getElementById ( 'disableEnforceSampleScheduleDiv' ).innerHTML = disableEnforceSampleScheduleXHR.responseText;
   } else {
      document.getElementById ( 'disableEnforceSampleScheduleDiv' ).innerHTML = 'HTTP status = ' + disableEnforceSampleScheduleXHR.status;
   }
};
function disableEnforceSampleSchedule() {
   let requestUrl = 'http://localhost/disableEnforceSampleSchedule'  
      + '?connectionStringName=' + document.getElementById ( 'connectionStringName' ).value;
   disableEnforceSampleScheduleXHR.open ( 'GET', requestUrl, true ); 
   disableEnforceSampleScheduleXHR.send();
};

2. CSS

div.response { font-family: "LUCIDA CONSOLE", "COURIER NEW", "COURIER", "monospace"; font-size: 1em; margin-left: 0.5em; }
span.blue-grey-button { background-color: #E6E6E6; color: blue; cursor: pointer; font-family: "VERDANA", "ARIAL", "HELVETICA", "SANS-SERIF"; font-size: 1em; 
                        margin-left: 0.1em; margin-right: 0.1em; padding-left: 0.3em; padding-right: 0.3em; text-decoration: none; }

3. HTML

<input id='connectionStringName' style='height: 1em; text-align: left; width: 20em;' type='text' value='ddd'>
<span class='blue-grey-button' onClick='disableEnforceSampleSchedule();'> disableEnforceSampleSchedule </span>
<div class='response' id='disableEnforceSampleScheduleDiv' style='display: inline-block;'> </div> 
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API ť 10.3 Web Service Requests

enableEnforceSampleSchedule Web Service

Enable (check) the "Enforce the Sample Schedule" option for the Database Monitor sampling session that was created for the named connection string.
Service Definition
CREATE SERVICE enableEnforceSampleSchedule TYPE 'RAW' AUTHORIZATION OFF USER DBA
   AS CALL enable_enforce_sample_schedule ( :connectionStringName );
Parameter

connectionStringName
A required non-empty connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This service returns a string containing 'OK' if the request succeeded or an error message if there was a problem.
Remarks
This service roughly corresponds selecting a target database on the Monitor Options page, checking Enforce the Sample Schedule in section 5. Sample Schedule, then clicking Save.
This service is stateless. No history of requests is maintained. Each request will proceed regardless of whether the sample schedule was previously enabled or disabled. The sample schedule will be enabled after the request, and the service does not return an error message it was already enabled.
A common reason to request this service is to undo the effect of a previous request to disableEnforceSampleSchedule.
Examples
1. JavaScript  -  see Demo Monitor Sessions API.html in C:\ProgramData\RisingRoad\Foxhound5\scripts 

let enableEnforceSampleScheduleXHR = new XMLHttpRequest();
enableEnforceSampleScheduleXHR.onload = function() { 
   if ( enableEnforceSampleScheduleXHR.status === 200 ) {  
      document.getElementById ( 'enableEnforceSampleScheduleDiv' ).innerHTML = enableEnforceSampleScheduleXHR.responseText;
   } else {
      document.getElementById ( 'enableEnforceSampleScheduleDiv' ).innerHTML = 'HTTP status = ' + enableEnforceSampleScheduleXHR.status;
   }
};
function enableEnforceSampleSchedule() {
   let requestUrl = 'http://localhost/enableEnforceSampleSchedule'  
      + '?connectionStringName=' + document.getElementById ( 'connectionStringName' ).value;
   enableEnforceSampleScheduleXHR.open ( 'GET', requestUrl, true ); 
   enableEnforceSampleScheduleXHR.send();
};

2. CSS

div.response { font-family: "LUCIDA CONSOLE", "COURIER NEW", "COURIER", "monospace"; font-size: 1em; margin-left: 0.5em; }
span.blue-grey-button { background-color: #E6E6E6; color: blue; cursor: pointer; font-family: "VERDANA", "ARIAL", "HELVETICA", "SANS-SERIF"; font-size: 1em; 
                        margin-left: 0.1em; margin-right: 0.1em; padding-left: 0.3em; padding-right: 0.3em; text-decoration: none; }

3. HTML

<input id='connectionStringName' style='height: 1em; text-align: left; width: 20em;' type='text' value='ddd'>
<span class='blue-grey-button' onClick='enableEnforceSampleSchedule();'> enableEnforceSampleSchedule </span>
<div class='response' id='enableEnforceSampleScheduleDiv' style='display: inline-block;'> </div> 
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API ť 10.3 Web Service Requests

setDatabaseAuthentication Web Service

Create, set or delete the DATABASE_AUTHENTICATION option to run Foxhound on the SQL Anywhere OEM Edition
Service Definition
CREATE SERVICE setDatabaseAuthentication TYPE 'RAW' AUTHORIZATION OFF USER DBA
   AS CALL set_database_authentication ( :databaseAuthenticationString );
Parameter

databaseAuthenticationString
An optional string which may be empty or a database authentication string in the format Company=xxx;Application=yyy;Signature=ddd
If no value is provided, a SQL NULL value is assumed.

Returns
This service returns a string containing 'OK' if the request succeeded or an error message if there was a problem.
Remarks
This service executes the SET OPTION PUBLIC.DATABASE_AUTHENTICATION statement on the Foxhound database, regardless of what edition of SQL Anywhere is being used.
A successful call

will insert or update the SYSOPTION.setting column WHERE "option" = 'database_authentication' with a provided databaseAuthenticationString value, or

it will delete the SYSOPTION row WHERE "option" = 'database_authentication' if databaseAuthenticationString is omitted... because SQL NULL assumed and that's how SET OPTION works.

A provided databaseAuthenticationString value is used as-is; this procedure does not check the format. In particular, the empty string is allowed, as well as all spaces, and leading and trailing spaces are OK.
You can effectively disable database authentication by executing a successful call with an omitted, empty or invalid string; the call will work but authentication won't.
This service satisfies requirement number 2 in the following list...
Requirements to Run a Database on the SQL Anywhere OEM Edition

Licence the server engine

Authenticate the database

Authenticate the connection

When you go into the authentication business SAP will give you three keys. The keys are all different but match each other and the publishing company & application names (i.e. they won't work with other keys):
an install key: you use this with dblic.exe -k to create OEM lic files (just like a normal install key).
a database key or signature: this is used once on a database to make it an Authenticated database which will work on the server created with the install key - the setting is persistent. This is done with a SET OPTION command; e.g.
SET OPTION PUBLIC.DATABASE_AUTHENTICATION='Company=xxx;Application=yyy;Signature=ddd'; 
A request to setDatabaseAuthentication takes care of the SET OPTION PUBLIC.DATABASE_AUTHENTICATION, including the requirement to have the SET ANY SECURITY OPTION system privilege. That's because setDatabaseAuthentication itself has SET ANY SECURITY OPTION.
a connection key or signature: This is used by connections to the database. Each connection has a 30 second (or so) grace period to set a temporary Connection_authentication option; e.g.
SET TEMPORARY OPTION CONNECTION_AUTHENTICATION='Company=xxx;Application=yyy;Signature=ccc'
Administrative Tip: These requirements may apply to your applications' ability to connect to the Foxhound database, but they do not apply to Foxhound's ability to connect to target databases. Those are two separate issues. In fact, the Foxhound Database Monitor is able to connect to an authenticated target database running on the OEM Edition with no action on your part because it uses the remote server feature which is self-authenticating. In particular, you don't have to worry about the InitString connection parameter or the SET TEMPORARY OPTION CONNECTION_AUTHENTICATION statement when creating a connection string for your target database.
Examples
1. JavaScript  -  see Demo Monitor Sessions API.html in C:\ProgramData\RisingRoad\Foxhound5\scripts 

let setDatabaseAuthenticationXHR = new XMLHttpRequest();
setDatabaseAuthenticationXHR.onload = function() { 
   if ( setDatabaseAuthenticationXHR.status === 200 ) {  
      document.getElementById ( 'setDatabaseAuthenticationDiv' ).innerHTML = setDatabaseAuthenticationXHR.responseText;
   } else {
      document.getElementById ( 'setDatabaseAuthenticationDiv' ).innerHTML = 'HTTP status = ' + setDatabaseAuthenticationXHR.status;
   }
};
function setDatabaseAuthentication() {
   let requestUrl = 'http://localhost/setDatabaseAuthentication'  
      + '?databaseAuthenticationString=' + document.getElementById ( 'databaseAuthenticationString' ).value;
   setDatabaseAuthenticationXHR.open ( 'GET', requestUrl, true ); 
   setDatabaseAuthenticationXHR.send();
};

2. CSS

div.response { font-family: "LUCIDA CONSOLE", "COURIER NEW", "COURIER", "monospace"; font-size: 1em; margin-left: 0.5em; }
span.blue-grey-button { background-color: #E6E6E6; color: blue; cursor: pointer; font-family: "VERDANA", "ARIAL", "HELVETICA", "SANS-SERIF"; font-size: 1em; 
                        margin-left: 0.1em; margin-right: 0.1em; padding-left: 0.3em; padding-right: 0.3em; text-decoration: none; }

3. HTML

<input id='databaseAuthenticationString' style='height: 1em; text-align: left; width: 50em;' type='text' value='Company=xxx;Application=yyy;Signature=ddd'>
<span class='blue-grey-button' onClick='setDatabaseAuthentication();'> setDatabaseAuthentication </span>
<div class='response' id='setDatabaseAuthenticationDiv' style='display: inline-block;'> </div> 

Foxhound 5 ť 10. Monitor Sessions API ť 10.3 Web Service Requests

turnOffPingOnlySampling Web Service

Disable (uncheck) the Perform Ping-Only Sampling option for the Database Monitor sampling session that was created for the named connection string.
Service Definition
CREATE SERVICE turnOffPingOnlySampling TYPE 'RAW' AUTHORIZATION OFF USER DBA
   AS CALL turn_off_ping_only_sampling ( :connectionStringName );
Parameter

connectionStringName
A required non-empty connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This service returns a string containing 'OK' if the request succeeded or an error message if there was a problem.
Remarks
This service roughly corresponds to selecting a target database on the Monitor Options page, unchecking Perform Ping-Only Sampling in section 16. Ping Settings, then clicking Save.
This service is stateless. No history of requests is maintained. Each request will proceed regardless of whether ping-only sampling previously turned on or off. Ping-only sampling will be turned off after the request, and the service does not return an error message it was already off.
One reason to request this service is to force Foxhound to reconnect to the target database when subsequently requesting stopMonitorSession and startMonitorSession, and one reason to do that is to force Foxhound to refresh the SPs: YYY procedures on the target database. If Ping-Only Sampling is in effect, Foxhound will not refresh the SPs: YYY procedures when the monitor session is stopped and restarted because those procedures aren't required for Ping-Only Sampling (ok, it's a bug, but it's not getting fixed :)
To undo the effect of this service, see turnOnPingOnlySampling.
Examples
1. JavaScript  -  see Demo Monitor Sessions API.html in C:\ProgramData\RisingRoad\Foxhound5\scripts 

let turnOffPingOnlySamplingXHR = new XMLHttpRequest();
turnOffPingOnlySamplingXHR.onload = function() { 
   if ( turnOffPingOnlySamplingXHR.status === 200 ) {  
      document.getElementById ( 'turnOffPingOnlySamplingDiv' ).innerHTML = turnOffPingOnlySamplingXHR.responseText;
   } else {
      document.getElementById ( 'turnOffPingOnlySamplingDiv' ).innerHTML = 'HTTP status = ' + turnOffPingOnlySamplingXHR.status;
   }
};
function turnOffPingOnlySampling() {
   let requestUrl = 'http://localhost/turnOffPingOnlySampling'  
      + '?connectionStringName=' + document.getElementById ( 'connectionStringName' ).value;
   turnOffPingOnlySamplingXHR.open ( 'GET', requestUrl, true ); 
   turnOffPingOnlySamplingXHR.send();
};

2. CSS

div.response { font-family: "LUCIDA CONSOLE", "COURIER NEW", "COURIER", "monospace"; font-size: 1em; margin-left: 0.5em; }
span.blue-grey-button { background-color: #E6E6E6; color: blue; cursor: pointer; font-family: "VERDANA", "ARIAL", "HELVETICA", "SANS-SERIF"; font-size: 1em; 
                        margin-left: 0.1em; margin-right: 0.1em; padding-left: 0.3em; padding-right: 0.3em; text-decoration: none; }

3. HTML

<input id='connectionStringName' style='height: 1em; text-align: left; width: 20em;' type='text' value='ddd'>
<span class='blue-grey-button' onClick='turnOffPingOnlySampling();'> turnOffPingOnlySampling </span>
<div class='response' id='turnOffPingOnlySamplingDiv' style='display: inline-block;'> </div> 
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API ť 10.3 Web Service Requests

turnOnPingOnlySampling Web Service

Enable (check) the "Perform Ping-Only Sampling" option for the Database Monitor sampling session that was created for the named connection string.
Service Definition
CREATE SERVICE turnOnPingOnlySampling TYPE 'RAW' AUTHORIZATION OFF USER DBA
   AS CALL turn_on_ping_only_sampling ( :connectionStringName );
Parameter

connectionStringName
A required non-empty connection string name that does not end with the special suffixes '(offline)' or '(DSN)'.

Returns
This service returns a string containing 'OK' if the request succeeded or an error message if there was a problem.
Remarks
This service roughly corresponds to selecting a target database on the Monitor Options page, checking Perform Ping-Only Sampling in section 16. Ping Settings, then clicking Save.
This service is stateless. No history of requests is maintained. Each request will proceed regardless of whether ping-only sampling previously turned on or off. Ping-only sampling will be turned on after the request, and the service does not return an error message it was already on.
A common reason to request this service is to undo the effect of a previous request to turnOffPingOnlySampling.
Examples
1. JavaScript  -  see Demo Monitor Sessions API.html in C:\ProgramData\RisingRoad\Foxhound5\scripts 

let turnOnPingOnlySamplingXHR = new XMLHttpRequest();
turnOnPingOnlySamplingXHR.onload = function() { 
   if ( turnOnPingOnlySamplingXHR.status === 200 ) {  
      document.getElementById ( 'turnOnPingOnlySamplingDiv' ).innerHTML = turnOnPingOnlySamplingXHR.responseText;
   } else {
      document.getElementById ( 'turnOnPingOnlySamplingDiv' ).innerHTML = 'HTTP status = ' + turnOnPingOnlySamplingXHR.status;
   }
};
function turnOnPingOnlySampling() {
   let requestUrl = 'http://localhost/turnOnPingOnlySampling'  
      + '?connectionStringName=' + document.getElementById ( 'connectionStringName' ).value;
   turnOnPingOnlySamplingXHR.open ( 'GET', requestUrl, true ); 
   turnOnPingOnlySamplingXHR.send();
};

2. CSS

div.response { font-family: "LUCIDA CONSOLE", "COURIER NEW", "COURIER", "monospace"; font-size: 1em; margin-left: 0.5em; }
span.blue-grey-button { background-color: #E6E6E6; color: blue; cursor: pointer; font-family: "VERDANA", "ARIAL", "HELVETICA", "SANS-SERIF"; font-size: 1em; 
                        margin-left: 0.1em; margin-right: 0.1em; padding-left: 0.3em; padding-right: 0.3em; text-decoration: none; }

3. HTML

<input id='connectionStringName' style='height: 1em; text-align: left; width: 20em;' type='text' value='ddd'>
<span class='blue-grey-button' onClick='turnOnPingOnlySampling();'> turnOnPingOnlySampling </span>
<div class='response' id='turnOnPingOnlySamplingDiv' style='display: inline-block;'> </div> 
Related Information
Adhoc Views - connection_string One row for each connection string displayed on the String tab of the Foxhound main menu.
Adhoc Views - sampling_options One row for each Foxhound Monitor target database, holding various options affecting how the Monitor behaves and information about the current status of the Monitor session.
Adhoc Queries - Sample sessions for all target databases

Foxhound 5 ť 10. Monitor Sessions API

10.1 Introduction
10.2 Stored Procedure Calls	10.3 Web Service Requests
create_or_replace_connection_string	createOrReplaceConnectionString	Create or change a named connection string to be used by Foxhound to connect to a target database
delete_connection_string	deleteConnectionString	Delete a named connection string from the Foxhound database
start_monitor_session	startMonitorSession	Use a named connection string to start a Foxhound Database Monitor sampling session
stop_monitor_session	stopMonitorSession	Issue an asynchronous request to stop a Foxhound Database Monitor sampling session
delete_monitor_session	deleteMonitorSession	Delete a Foxhound Database Monitor sampling session from the Foxhound database.
disable_enforce_sample_schedule	disableEnforceSampleSchedule	Disable (uncheck) the Enforce the Sample Schedule option for a Database Monitor sampling session
enable_enforce_sample_schedule	enableEnforceSampleSchedule	Enable (check) the Enforce the Sample Schedule option for a Database Monitor sampling session
set_database_authentication	setDatabaseAuthentication	Create, set or delete the DATABASE_AUTHENTICATION option to run Foxhound on the SQL Anywhere OEM Edition
turn_off_ping_only_sampling	turnOffPingOnlySampling	Disable (uncheck) the Perform Ping-Only Sampling option for a Database Monitor sampling session
turn_on_ping_only_sampling	turnOnPingOnlySampling	Enable (check) the Perform Ping-Only Sampling option for a Database Monitor sampling session