1. Developer's Guide
  2. Shared Libraries

3 Shared Libraries

This chapter contains information on the ASAP libraries that are shared by the provisioning (upstream) interface and the downstream interface. This chapter consists of the following sections:

Control Configuration Interface

This section describes the functions for the Control subsystem.

The Control subsystem supports static table configuration. Use functions instead of SQL insert scripts to interface with the static configuration database tables.

The function-based interface reduces the dependency between administrators who configure the system and product developers who need to make changes to the static tables to support new functionality.

Note:

If you invoke an CSP_del_* function without parameters, all rows in the table are deleted.

If you invoke the CSP_list_* functions without parameters, all rows are listed.

Interface Definitions

This section lists the syntax, descriptions, parameters, and results for Control configuration actions.

CSP_db_admin

This function purges all performance data that have been stored for more than a specified number of days. The default value of a_days is 3 days if it is not provided.

For more information about using functions, see "Oracle Examples."

Affected tables:

  • tbl_alarm_log

  • tbl_event_log

  • tbl_process_info

Table 3-1 CSP_db_admin Parameters

Name Description Req'd (I)nput/(O)utput

days

Specifies the age (in days) of log data to delete. All data older than the specified number of days is deleted.

Yes

I
CSP_del_alarm

This function deletes a system alarm code from tbl_system_alarm.

For more information about using functions, see "Oracle Examples."

Table 3-2 CSP_del_alarm Parameters

Name Description Req'd (I)nput/(O)utput

alarm_code

System alarm code identifier.

No

I
CSP_del_appl

This function deletes ASAP application registration information from the Control database (tbl_appl_proc).

For more information about using functions, see "Oracle Examples."

Table 3-3 CSP_del_appl Parameters

Name Description Req'd (I)nput/(O)utput

appl_cd

Logical name of the ASAP application server.

No

I
CSP_del_center

This function deletes an alarm center definition from the control database (tbl_alarm_center).

For more information about using functions, see "Oracle Examples."

Table 3-4 CSP_del_center Parameters

Name Description Req'd (I)nput/(O)utput

alarm_center

The alarm center to be deleted.

No

I
CSP_del_code

This function deletes an administration system code from the database (tbl_code_list).

For more information about using functions, see "Oracle Examples."

Table 3-5 CSP_del_code Parameters

Name Description Req'd (I)nput/(O)utput

code_type

Type of code. For example: “DB": database script related entry.

No

I

code

The code.

No

I

value

Value of the code.

No

I
CSP_del_component

This function deletes an ASAP component from tbl_component.

For more information about using functions, see "Oracle Examples."

Table 3-6 CSP_del_component Parameters

Name Description Req'd (I)nput/(O)utput

territory

The ASAP territory.

No

I

system

The ASAP system.

No

I

component

The ASAP component.

No

I
CSP_del_db_thresh

This function deletes a database threshold definition from tbl_db_threshold.

For more information about using functions, see "Oracle Examples."

Table 3-7 CSP_del_db_thresh Parameters

Name Description Req'd (I)nput/(O)utput

asap_sys

The ASAP environment (“TEST", “PROD", etc.).

No

I

db_name

The database name.

No

I
CSP_del_event

This function deletes an ASAP event type from the database (tbl_event_type).

For more information about using functions, see "Oracle Examples."

Table 3-8 CSP_del_event Parameters

Name Description Req'd (I)nput/(O)utput

event_type

The event type. For example, “ABNORMAL", “SYS_ERR", etc.

No

I
CSP_del_fs_thresh

This function deletes a file system threshold definition from tbl_fs_threshold.

For more information about using functions, see "Oracle Examples."

Table 3-9 CSP_del_fs_thresh Parameters

Name Description Req'd (I)nput/(O)utput

asap_sys

The ASAP environment (TEST, PROD, etc.).

No

I

file_system

The UNIX file system for which the threshold definition is to be deleted.

No

I
CSP_del_listener

This function deletes a listener entry from tbl_listeners.

For more information about using functions, see "Oracle Examples."

Table 3-10 CSP_del_listeners Parameters

Name Description Req'd (I)nput/(O)utput

srv_name

Name of the server that starts a socket listener. The SARM must start a socket listener to receive incoming Java SRP requests.

For a Java-enabled NEP, this is the name of the NEP ($NEP).

For the Java SRP, this column contains the SARM name.

Yes

I

listener_name

The name of the listener thread.

For a Java-enabled NEP, the listener name describes the listener in the Java process that accepts interpreter requests from the C process. This listener name must always be $NEP_jlistener.

For the Java SRP, observe the naming convention of “<Java SRP application name>_jsrplistener". This column is used by the Java SRP to retrieve the listener configurations.

Yes

I
CSP_del_nvp

This function deletes a name/value pair from the database (tbl_name_value_pair).

For more information about using functions, see "Oracle Examples."

Table 3-11 CSP_del_nvp Parameters

Name Description Req'd (I)nput/(O)utput

name

Name of the name/value pair.

No

I
CSP_get_listener

This function lists listener entries associated with an NEP (tbl_listeners).

For more information about using functions, see "Oracle Examples."

Table 3-12 CSP_get_listener Parameters

Name Description Req'd (I)nput/(O)utput

srv_name

Name of the server that starts a socket listener. The SARM must start a socket listener to receive incoming Java SRP requests.

For a Java-enabled NEP, this is the name of the NEP ($NEP).

For the Java SRP, this column contains the SARM name.

Yes

I
CSP_list_alarm

This function lists system alarms contained in tbl_system_alarm.

For more information about using functions, see "Oracle Examples."

Table 3-13 CSP_list_alarm Parameters

Name Description Req'd (I)nput/(O)utput

RC1

Oracle Database Ref Cursor.

Yes

I/O

alarm_code

System alarm code.

No

I

Table 3-14 CSP_list_alarm Results

Name Datatype Description

alarm_code

TYP_code

The alarm code.

description

TYP_desc

Brief description of the system alarm.

alarm_level

TYP_alarm_level

Level of the alarm.

escalation_code

TYP_code

Escalation code of the alarm.

escalation_time

TYP_time

Escalation time.

auto_clear

TYP_yes_no

Determines whether the alarm must be automatically cleared.

route#_period

TYP_short

Interval in minutes for the alarm to be sent to the alarm center.

# can be a number between 1 and 5 to designate up to five routings.

route#_start

TYP_time

Daily start time in minutes after midnight.

# can be a number between 1 and 5 to designate up to five routings.

route#_end

TYP_time

Daily end time in minutes after midnight.

# can be a number between 1 and 5 to designate up to five routings.

route#_center

TYP_code

Alarm center to route alarm to.

# can be a number between 1 and 5 to designate up to five routings.
CSP_list_appl

This function lists ASAP application registration information for the specified appl_cd or all applications from the Control database (tbl_appl_proc).

For more information about using functions, see "Oracle Examples."

Table 3-15 CSP_list_appl Parameters

Name Description Req'd (I)nput/(O)utput

RC1

Oracle Database Ref Cursor.

Yes

I/O

appl_cd

The logical name of the ASAP application server.

No

I

Table 3-16 CSP_list_appl Results

Name Datatype Description

start_seq

TYP_start_seq

Controls the sequence in which the applications are started. For example, certain client applications may be required to start before server applications, and other client applications after the server applications.

appl_type

TYP_appl_type

Specifies whether the ASAP application is an application server or a client application. Specify:

  • S – For server

  • C – For client

  • M – For primary control server

  • R – For remote secondary control server

appl_cd

TYP_code

ASAP logical client/server name, for example, SARM, NEP01, NEP02.

control_svr

TYP_code

The logical ASAP application control server that spawns this application and monitors its behavior.

description

TYP_desc

Brief description of the ASAP application.

diag_file

TYP_unix_file

The name of the diagnostics logfile to which diagnostic messages are written. This file is created in the $LOGDIR directory under a dated directory, for example, in the $LOGDIR/yymmdd format.

auto_start

TYP_yesno

An autostart flag that determines if the application is to be started automatically when ASAP starts.

program

varchar(40)

The name of the UNIX program that runs to start the ASAP application. The UNIX program must reside in the $PROGRAMS directory and be executable.

diag_level

TYP_diag_level

The diagnostic level of the ASAP application. The diagnostic level is used to determine whether or not to log diagnostic information based on the diagnostic level of the ASC_diag() API function call.

isactive

TYP_yesno

A yes/no flag denoting whether the ASAP server is currently active.

last_start

datetime

The last start date and time of the ASAP server.

last_halt

datetime

The last halt or terminate date and time of the ASAP server.

last_abnormal

datetime

The last abnormal termination of the Control server.

svr_type

varchar(8)

This field defines the type of server.
CSP_list_center

This function lists alarm center definitions from the control database (tbl_alarm_center).

For more information about using functions, see "Oracle Examples."

Table 3-17 CSP_list_center Parameters

Name Description Req'd (I)nput/(O)utput

RC1

Oracle Database Ref Cursor.

Yes

I/O

alarm_center

The alarm center to be deleted.

No

I

Table 3-18 CSP_list_center Results

Name Datatype Description

alarm_center

TYP_code

The unique code representing the alarm center.

control_prog

TYP_unix_file

The program to be run to communicate the alarm to the alarm center.

description

TYP_desc

Brief description of the alarm center.

opt#_type

TYP_option

First option to the control program, where # represents a value between 1 and 5.

opt#_value

TYP_opt_value

Argument to the first option, where # represents a value between 1 and 5.
CSP_list_code

This function lists Administration System code(s) from tbl_code_list.

If you invoke the function without any parameters, all rows in the table are listed.

For more information about using functions, see "Oracle Examples."

Table 3-19 CSP_list_code Parameters

Name Description Req'd (I)nput/(O)utput

RC1

Oracle Database Ref Cursor.

Yes

I/O

code_type

Type of code. For example, DB for a database script related entry.

No

I

code

The code entry.

No

I

value

Value of the code.

No

I

Table 3-20 CSP_list_code Results

Name Datatype Description

code_type

TYP_code_type

Type of code.

code

TYP_code_text

Type of code.

value

TYP_code_value

Parameter value associated with the label.

code_desc

TYP_desc

Brief description of the code.

parm#

TYP_code_parm

General purpose parameter, where # represents a value between 1 and 4.
CSP_list_component

This function lists ASAP components contained in tbl_component.

If you invoke the function without any parameters, all rows in the table are listed.

For more information about using functions, see "Oracle Examples."

Table 3-21 CSP_list_component Parameters

Name Description Req'd (I)nput/(O)utput

RC1

Oracle Database Ref Cursor.

Yes

I/O

territory

Identifies the ASAP territory.

No

I

system

Identifies the ASAP system.

No

I

component

Identifies the ASAP component.

No

I

Table 3-22 CSP_list_component Results

Name Datatype Description

territory

varchar(20)

ASAP territory.

system

varchar(20)

ASAP system.

component

varchar(40)

ASAP component.
CSP_list_db_thresh

This function lists database threshold definition(s) contained in tbl_db_threshold.

If you invoke the function without any parameters, all rows in the table are listed.

For more information about using functions, see "Oracle Examples."

Table 3-23 CSP_list_db_thresh Parameters

Name Description Req'd (I)nput/(O)utput

RC1

Oracle Database Ref Cursor.

Yes

I/O

asap_sys

The ASAP environment (for example, TEST, PROD etc.)

No

I

db_name

Database name.

No

I

Table 3-24 CSP_list_db_thresh Results

Name Datatype Description

asap_sys

TYP_code

ASAP environment.

db_name

varchar(80) TYP_desc

Database name.

data_threshold

int

Database threshold, in Mb.

tran_threshold

int

Transaction log threshold.

data_event

TYP_code

Event issued if the database threshold is exceeded.

tran_event

TYP_code

Event to be issued if the transaction log threshold is exceeded.
CSP_list_event

This function lists ASAP event definitions contained in tbl_event_type.

If you invoke the function without any parameters, all rows in the table are listed.

For more information about using functions, see "Oracle Examples."

Table 3-25 CSP_list_event Parameters

Name Description Req'd (I)nput/(O)utput

RC1

Oracle Database Ref Cursor.

Yes

I/O

event_type

Event type. For example, the core uses some of the following event types: ABNORMAL, SYS_ERR, etc.

No

I

Table 3-26 CSP_list_event Results

Name Datatype Description

event_type

TYP_event

The event type. The core module includes some of the following event types: ABNORMAL, SYS_ERR, etc.

description

varchar(40) TYP_desc

Brief description of the event.

alarm_code

TYP_code

The alarm code associated with the event.

alarm_action

TYP_alarm_action

Specifies whether the alarm is enabled or disabled.
CSP_list_fs_thresh

This function lists file system threshold definitions contained in tbl_fs_threshold.

If you invoke the function without any parameters, all rows in the table are listed.

For more information about using functions, see "Oracle Examples."

Table 3-27 CSP_list_fs_thresh Parameters

Name Description Req'd (I)nput/(O)utput

RC1

Oracle Database Ref Cursor.

Yes

I/O

asap_sys

The ASAP environment (TEST, PROD, etc.).

No

I

file_system

The UNIX file system for which the threshold definition is to be deleted.

No

I

Table 3-28 CSP_list_fs_thresh Results

Name Datatype Description

asap_sys

TYP_code

The ASAP environment.

file_system

varchar(100) TYP_desc

File system name.

full_threshold

int

File system full threshold.

full_event

TYP_code

Event to be generated if the full threshold is exceeded.
CSP_list_nvp

This function lists name/value pairs from the database (tbl_name_value_pair).

If you invoke the function without any parameters, all rows in the table are deleted.

For more information about using functions, see "Oracle Examples."

Table 3-29 CSP_list_nvp Parameters

Name Description Req'd (I)nput/(O)utput

RC1

Oracle Database Ref Cursor.

Yes

I/O

name

Name of the name-value pair.

No

I

Table 3-30 CSP_list_nvp Results

Name Datatype Description

name

varchar(40)

Name of the parameter.

value

int

Parameter value associated with the label.
CSP_new_alarm

This function defines a system alarm which may be generated by ASAP system events. This includes the start time, interval, and end time for the alarm.

This function populates tbl_system_alarm.

Example:

The following example creates an alarm for the abnormal termination of an application process to the ADMINPGR center that is continuous on a five minute period any time of the day, type the following:

var retval number;
exec :retval := CSP_new_alarm ('ABNORMAL', 'Abnormal process termination', 'CRITICAL', '',NULL, 'N', 5, 0, 1440, 'ADMINPGR');

print retval;

For more information about using functions, see "Oracle Examples."

Table 3-31 CSP_new_alarm Parameters

Name Description Req'd (I)nput/(O)utput

RC1

Oracle Database Ref Cursor.

Yes

I/O

alarm_code

System alarm code.

Yes

I

description

Brief description of the system alarm.

Yes

I

alarm_level

The level of the alarm, for example, MAJOR, MINOR, CRITICAL.

Yes

I

escalation_code

The escalation code for the alarm if the alarm is not corrected within the escalation time (defined next).

Yes

I

escalation_time

Time after the alarm was raised that the escalation of the alarm must take place.

Yes

I

auto_clear

Flag that determines if the alarm should be automatically cleared upon generation.

Yes

I

route#_period

Interval in minutes for the alarm to be sent to the alarm center, where # represents a value between 1 and 5.

Yes (if # = 1), No (if # = 2 to 5)

I

route#_start

The daily start time in minutes since midnight for alarms to go to this alarm center, where # represents a value between 1 and 5.

Yes (if # = 1), No (if # = 2 to 5)

I

route#_end

The daily end time in minutes since midnight, where # represents a value between 1 and 5.

Yes (if # = 1), No (if # = 2 to 5)

I

route#_center

Alarm center to route alarm to, where # represents a value between 1 and 5.

Yes (if # = 1), No (if # = 2 to 5)

I
CSP_new_appl

This function defines a new ASAP client or server application in tbl_appl_proc.

For more information about using functions, see "Oracle Examples."

Table 3-32 CSP_new_appl Parameters

Name Description Req'd (I)nput/(O)utput

start_seq

Specifies the ASAP startup sequence. This determines the sequence in which applications are started.

Yes

I

appl_type

Specifies the ASAP application server:

  • S – For server

  • C – For client

  • M – For primary control server

  • R – For remote secondary control server

Yes

I

appl_cd

The logical ASAP application code, for example, SARM, NEP01, NEP02.

Yes

I

control_svr

Logical ASAP Control server.

Yes

I

auto_start

An autostart flag.

Yes

I

program

The name of the UNIX program to start the ASAP application.

Yes

I

diag_level

The diagnostic level of the ASAP application. This is used to determine whether or not to log certain diagnostic information based on the diagnostic level of the ASC_diag() API function call. See the associated rule for possible values.

Yes

I

diag_file

The name of the diagnostics file in which diagnostic messages are to be placed. This file is created in the $LOGDIR directory under a dated directory, for example, using the $LOGDIR/yymmdd format.

Yes

I

description

A description of the ASAP application.

Yes

I

svr_type

ASAP server type. Possible values include:

  • CTRL – Control server

  • MASTER – primary Control server (must be only one per system)

  • SARM – SARM server

  • SRP – SRP server

  • NEP – NEP server

  • OTHER

No

I

Example:

To configure ASAP to manage and monitor this processes, enter the following commands. This example assumes this processes is run automatically at startup and the Low level diagnostics are active. 

var retval number;
exec :retval := CSP_new_appl (4, 'S', 'NEPAXE', 'CONTROL2','Y', 'LOW', 'NEPAXE.diag', 'NEP for AXE Switches')

Once the control servers are started on their respective machines, you can start and shut down the application processes automatically from the primary system.

CSP_new_center

This function defines an alarm center to which alarm notifications are sent by the Control server. This function populates tbl_alarm_center.

Syntax:

var retval number;
exec :retval :=  CSP_new_center ('alarm_center', 'control_prog', ['description'], ...);

Example:

In the following example, admin.sh is the ADMIN center and adminpg is the ADMINPGR center. You must place the final versions of these programs in the ASAP programs directory and identify them using the environment variable $PROGRAMS. 

var retval number;
exec :retval :=  CSP_new_center ('ADMIN', 'admin.sh', 'General Admin. Center');

For more information about using functions, see "Oracle Examples."

Table 3-33 CSP_new_center Parameters

Name Description Req'd (I)nput/(O)utput

alarm_center

A unique code representing the alarm center.

Yes

I

control_prog

The program to be run to communicate the alarm to the alarm center.

Yes

I

description

A brief description of the alarm center or control program.

No

I

opt#_type

Option name to be passed to the control program, where # represents a value between 1 and 5.

No

I

opt#_value

Value of the option, where # represents a value between 1 and 5.

No

I
CSP_new_code

This function populates tbl_code_list with core or custom code used by ASAP. For instance, this function to identify codes that track the cartridges deployed within ASAP.

For more information about using functions, see "Oracle Examples."

Table 3-34 CSP_new_code Parameters

Name Description Req'd (I)nput/(O)utput

code_type

Type of code. For example, DB for database script related entry.

Yes

I

code

The code.

Yes

I

value

Value of the code.

Yes

I

code_desc

Brief description of the code.

No

I

parm#

General purpose parameter, where # can be a number between 1 and 4.

No

I
CSP_new_component

This function defines an ASAP component in a territory and adds it to database table tbl_component.

For more information about using functions, see "Oracle Examples."

Table 3-35 CSP_new_component Parameters

Name Description Req'd (I)nput/(O)utput

territory

Identifies the ASAP territory.

Yes

I

system

Identifies the ASAP system.

Yes

I

component

Identifies an ASAP system component within a territory and system. For example, SRP, SARM, etc.

Yes

I
CSP_new_db_thresh

This function defines database and/or transaction log thresholds to be used by the Control server, and writes the information to tbl_db_threshold. The Control server monitors the database/transaction log size and issues the appropriate data event/transaction event when the threshold is exceeded.

Syntax:

var retval number;
exec :retval :=  CSP_new_db_thresh ('asap_sys', 'db_name', 'db_threshold', 'tran_threshold', 'data_event', 'tran_event')

Example:

var retval number;
exec :retval :=  CSP_new_db_thresh ('PROD', 'SDB_P01_asap', 80, 20, 'DB2FULL', 'TRANFULL';

in this example, the database threshold is set to 80 percent. If the database becomes more than 80 percent full, the DB2FULL system event is issued. This command also sets the transaction log threshold for the database. When the transaction log for the database exceeds 20 MB, the TRANFULL system event is issued.

Database thresholds must be defined in the component table.

For more information about using functions, see "Oracle Examples."

Table 3-36 CSP_new_db_thresh Parameters

Name Description Req'd (I)nput/(O)utput

asap_sys

The ASAP environment (for example, TEST, PROD, etc.).

Yes

I

db_name

Database name.

Yes

I

db_threshold

Database threshold, in Mb.

Yes

I

tran_threshold

Transaction log threshold.

Yes

I

data_event

Data event.

Yes

I

tran_event

Transaction log event.

Yes

I
CSP_new_event

This function defines an “event type" within ASAP, and optionally, the associated “alarm code" that is associated with the event. System events can be generated when an error condition is encountered in ASAP. CSP_new_event populates tbl_event_type.

For more information about using functions, see "Oracle Examples."

Table 3-37 CSP_new_event Parameters

Name Description Req'd (I)nput/(O)utput

event_type

Event type. For example, the core uses some of the following event types: ABNORMAL, SYS_ERR, etc.

Yes

I

description

A brief description of the ASDL command.

No

I

alarm_code

The system alarm code associated with the event. If NULL, no alarm will be generated and only the database log entry will be created.

No

I

alarm_action

Specifies the alarm action, and may specify whether the alarm is presently enabled or disabled.

No

I

notify_aims

This is not currently implemented.

Syntax:

var retval number;
exec :retval :=  CSP_new_event ('event_type', ['description'], ['alarm_code'], [“alarm_action'];

Example:

The following example shows an ABNORMAL system event mapped to the ABNORMAL alarm.

var retval number;
exec :retval :=  CSP_new_event ('ABNORMAL', 'Abnormal Process Termination Event', 'ABNORMAL', 'E';
CSP_new_fs_thresh

This function defines a file system threshold to be used by the Control server. The Control server monitors the file system size and if the threshold is exceeded, the appropriate system event is generated. File system threshold information is stored in tbl_fs_threshold.

For more information about using functions, see "Oracle Examples."

CSP_new_listener

This function adds a listener entry to tbl_listeners. You must configure this table to allow the SARM to start up socket listeners for incoming SRP requests. As well, every Java-enabled NEP must maintain a dedicated connection to its JInterpreter.

For more information about using functions, see "Oracle Examples."

Table 3-38 CSP_new_listener Parameters

Name Description Req'd (I)nput/(O)utput

srv_name

Name of the server that starts a socket listener. The SARM must start a socket listener to receive incoming Java SRP requests.

For a Java-enabled NEP, this is the name of the NEP ($NEP).

For the Java SRP, this column contains the SARM name.

Yes

I

host_name

The host name or the IP address on which the server application resides.

For the JInterpreter, this value must always be localhost.

For the Java SRP, the host_name identifies the location of the SARM.

Yes

I

listener_name

The name of the listener thread.

For a Java-enabled NEP, the listener name describes the listener in the Java process that accepts interpreter requests from the C process. This listener name must always be $NEP_jlistener.

For the Java SRP, observe the naming convention of “<Java SRP application name>_jsrplistener". This column is used by the Java SRP to retrieve the listener configurations.

Yes

I

port

A free port on which the server can start the socket listener.

Yes

I
CSP_new_nvp

This function defines parameters (name value pairs) that are required to maintain the control database. Typical parameters include “audit trail window", “log retention window", etc. This information is stored in tbl_name_value_pair.

For more information about using functions, see "Oracle Examples."

Table 3-39 CSP_new_nvp Parameters

Name Description Req'd (I)nput/(O)utput

name

Name of the parameter.

Yes

I

value

Value of the parameter.

Yes

I

XML JMX Interface

For overview information on the JMX interface, refer to the ASAP Server Configuration Guide. For complete reference information on the JMX interface, refer to the ASAP Online Reference.