create()

Create a PATROL instance.

Syntax
Parameters
Description
Example

Syntax

create(instance,[label],[state],[description],[parent])

Parameters

Parameter	Definition
instance	path to the instance being created The instance parameter is validated using the following rules: instance is composed of name segments separated by a slash instance may start with a slash , but not end with a slash instance may not contain empty segments instance may not contain unprintable characters instance may not contain whitespace other than the space character instance may contain spaces within a segment but not at the beginning or end of a segment
label	optional text string that is used for instance identification and icon specification If no icon is specified in the label, then the label appears below the instance's icon. If an icon is specified in the label, then the label is split into two components--the label string that will appear under the instance's icon, and the name of the icon to be used. Default instance
state	optional state of the instance assigned at its creationValid Values OFFLINE OK WARN ALARM Default NONE Note Typically you should create an instance in the OK state. Using any other state causes PATROL to suspend the parameters that the instance may have. Also, the PATROL Console does not display the icon of the instance until the instance has a valid state.
description	optional text string that can be used to introduce the newly created instance The text string must be enclosed in double quotation marks. The text string is recorded in the Event Description of the State Change Event in the Event Manager.Default NULL string
parent	optional text string that specifies the parent to which the created instance will belong If no parent is specified, instance will not have a parent. If parent is "/", instance is displayed in the PATROL Main window.

Description

The create() function creates the PATROL application instance with the identifier instance.

If label is specified, it is the label that the PATROL Console displays beneath the instance's icon. The default label is the instance name.

The format of the label string is as follows:

"instance_name" | ":instance_name:icon_base_name"

In both cases, the instance_name will be used as the label for the icon. The icon_base_name specifies the two icons which will be used to show the states of the instance. In the Console, the two icons which are used will be icon_base_name_ok and icon_base_name_warn. The suffix and format are defined by the Console according to the PSL rules, so you do not have to specify the file extension in the label string. If the _ok or _warn icon, or both, is not found, the console will use the icon defined in the APPLICATION class.

Note

The Unix Console uses .xpm icon files, and the Windows Console uses .bmp icon files.

If parent is specified, parent will be the parent instance of instance. Thus,

The container for parent on the PATROL Console will contain instance.
When parent is destroyed, instance will also be destroyed.
If instance is allowed to propagate its state, and is in ALARM, the combined state of parent will also be in ALARM.

The create() function returns instance if it creates the instance or the NULL string, if the instance already exists or an error occurs. If the instance parameter syntax is invalid, the create() function sets the errno variable to 96 indicating E_PSL_BAD_FUNCTION_PARAMETER.

Since the PATROL Agent and Console do not share a single hierarchy of application, instance, and parameter, it is possible for a new application instance icon to be missing on the console. When an instance is created with the create() function and a parent instance is specified, the instance ID of the parent instance is stored in the application instance structure on the agent. This guarantees the existence of the parent instance in the agent namespace, but not necessarily on the console.

When the application instance is sent to the console, the agent includes the parent instance ID, which allows the console to determine where the icon should be located.

The icon will be misplaced or not displayed in the following circumstances:

The parent instance exists in the agent namespace but does not have an icon in the console. The parent instance won't have an icon in the following circumstances:
- parent instance is in the VOID state
- KM to which the parent instance belongs is not loaded on the console
- console has not asked the agent for the status of the parent instance yet
The parent instance has been destroyed.
- KM destroyed the instance via PSL
- developer is downloading a new version of the KM to the agent
  
  When using the create() function, it is good practice to check if a parent instance exists and is not in a VOID state before the instance is created.

Example

The following examples highlight the usage of the create() function.

Create an instance with a label, state, and description:

# This instance is created in OK condition and thus displayed.
create(name, "martin", OK,"User logged in");

Create an instance with no optional parameters:

# This instance is created but not displayed.
create("Secret_object");

Create an instance with an Initial "OK" state:

# This instance is created with the default label.
create(name, "",OK);

Create an instance with a label:

# This example creates the root instance of the FILESYSTEM
# application. The label "root" appears under the instance's icon.
create("/FILESYSTEM/root", "root", OK);

Create an instance with a label and specified icons:

# This example creates the root instance of the FILESYSTEM
# application with the label "root" appearing under the
# instance’s icon. The icons that will be
# used for the instance are root_icon_ok.xpm and
# root_icon_warn.xpm (for the 3.2 Unix Console).
#
create("/FILESYSTEM/root", ":root:root_icon", OK);