dassmonarch Externals Routine Calling Sequences

$outcome=$dm->apply_external_to_host($host_name, $external_name, $modified);
$outcome=$dm->apply_external_to_hostservice($host_name, $service_name, $external_name, $modified);
$outcome=$dm->assign_external_to_hostprofile($hostprofile_name, $external_name);
$outcome=$dm->assign_external_to_service($service_name, $external_name);
     clone free external
$external_id=$dm->create_external($external_name, $description, $type, $content);
$outcome=$dm->delete_external($external_name);
$e_ref=$dm->get_external($external_name);
$external_id=$dm->get_externalid($external_name);
$external_name=$dm->get_externalname($external_id);
$e_ref=$dm->get_host_external($host_name, $external_name);
$e_ref=$dm->get_hostservice_external($host_name, $service_name, $external_name);
$external_names=$dm->list_externals($type);
$external_names=$dm->list_host_externals($host_name);
$external_names=$dm->list_hostprofile_externals($hostprofile_name);
$hostprofile_names=$dm->list_hostprofiles_with_external($external_name);
$host_names=$dm->list_hosts_with_external($external_name);
$external_names=$dm->list_hostservice_externals($host_name, $service_name);
$hostservices=$dm->list_hostservices_with_external($external_name);
$external_names=$dm->list_service_externals($service_name);
$service_names=$dm->list_services_with_external($external_name);
$outcome=$dm->modify_external($external_name, $description, $content);
$outcome=$dm->modify_host_external($host_name, $external_name, $content, $modified);
$outcome=$dm->modify_hostservice_external($host_name, $service_name, $external_name, $content, $modified);
$outcome=$dm->propagate_external($external_name, $replace);
$outcome=$dm->remove_external_from_host($host_name, $external_name);
$outcome=$dm->remove_external_from_hostprofile($hostprofile_name, $external_name);
$outcome=$dm->remove_external_from_hostservice($host_name, $service_name, $external_name);
$outcome=$dm->remove_external_from_service($service_name, $external_name);
$outcome=$dm->rename_external($old_external_name, $new_external_name);

NAME

apply_external_to_host - apply (copy) free host external to host

SYNOPSIS

    $outcome = $dm->apply_external_to_host($host_name, $external_name,
	$modified);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Apply the specified free host external to the specified host. If the external was not previously applied to this host, either through applying a host profile, or directly in some other action, create the separate applied host external. If the external was previously applied to this host, ignore its existing "modified" flag and overwrite the applied external content with that from the free host external. In either case, set the "modified" flag of the resulting applied host external according to the value of the $modified parameter.

$modified is a boolean flag, indicating whether or not this applied external is to be marked as having been modified since it was first copied from the associated free external.

RETURN VALUE

$outcome will be true if the applying the external succeeded, false otherwise.

ERRORS

Failure can occur because of reasons such as:

NOTES

This routine ignores the existing value of the applied external's "modified" flag. If you need to pay attention to that value, fetch the applied external details (get_host_external()), look at the flag, and decide whether to call the apply_external_to_host() routine.

The propagate_external() routine also has use in copying the content of free externals to already-applied externals in bulk, optionally paying attention to their respective "modified" flags.


NAME

apply_external_to_hostservice - apply (copy) free service external to host service

SYNOPSIS

    $outcome = $dm->apply_external_to_hostservice($host_name,
	$service_name, $external_name, $modified);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Apply the specified free service external to the specified host service. If the external was not previously applied to this host service, either through a generic service when that service was initially added to the host, or directly in some later action, create the separate applied service external. If the external was previously applied to this host service, ignore its existing "modified" flag and overwrite the applied external content with that from the free service external. In either case, set the "modified" flag of the resulting applied service external according to the value of the $modified parameter.

$modified is a boolean flag, indicating whether or not this applied external is to be marked as having been modified since it was first copied from the associated free external.

RETURN VALUE

$outcome will be true if the applying the external succeeded, false otherwise.

ERRORS

Failure can occur because of reasons such as:

NOTES

This routine ignores the existing value of the applied external's "modified" flag. If you need to pay attention to that value, fetch the applied external details (get_hostservice_external()), look at the flag, and decide whether to call the apply_external_to_hostservice() routine.

The propagate_external() routine also has use in copying the content of free externals to already-applied externals in bulk, optionally paying attention to their respective "modified" flags.


NAME

assign_external_to_hostprofile - assign external to host profile

SYNOPSIS

    $outcome = $dm->assign_external_to_hostprofile($hostprofile_name,
	$external_name);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Assign the specified free external to the specified host profile.

RETURN VALUE

$outcome will be true if the assignment succeeded, false otherwise.

ERRORS

Failure can occur because of reasons such as:


NAME

assign_external_to_service - assign external to generic service

SYNOPSIS

    $outcome = $dm->assign_external_to_service($service_name, $external_name);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Assign the specified free external to the specified generic service.

RETURN VALUE

$outcome will be true if the assignment succeeded, false otherwise.

ERRORS

Failure can occur because of reasons such as:


NAME

clone free external

SYNOPSIS

You can clone an existing free host or service external using the following code:

    $e_ref = $dm->get_external($old_external_name);
    if ( not defined $e_ref ) {
	## error ...
    }
    else {
	$description = $e_ref->{description};
	$content     = $e_ref->{display};
	## If you're going to clone an existing external, you may want to change
	## the description, and you almost certainly want to change the content.
	## You may as well do so now.
	$description = ...;
	$content     = ...;
	$external_id = $dm->create_external( $new_external_name,
	    $description, $e_ref->{type}, $content );
	if ( !$external_id ) {
	    ## error ...
	}
	else {
	    ## continue processing with the new external
	}
    }

DESCRIPTION

We don't supply any routines to clone free or applied externals, as it makes little sense to do so when you can build whatever you need out of the primitives that we do already supply. This entry gives example code to create a modified copy of a free external.


NAME

create_external - create free host or service external

SYNOPSIS

    $external_id = $dm->create_external($external_name, $description,
	$type, $content);

    if (! $external_id) {
        ## error ...
    }
    else {
        ## continue processing with the new external
    }

DESCRIPTION

This routine creates and stores a new free host or service external.

$external_name is the name of the new external. It must not match the name of any existing external. Host and service externals share the same namespace; a host external cannot share the same name with a service external.

$description is a very brief (50 characters max) commentary about the external. In the current version of Monarch, this value is stored but not displayed in the UI. That will likely change in a future release. An undefined value can be passed as $description, which will mean that no description is recorded for this external.

$type is either 'host' or 'service'.

$content is the body of the external, consisting of a series of newline-terminated lines joined into one concatenated string.

RETURN VALUE

If the creation succeeded, $external_id is the Monarch internal identifier of the newly created external, expressed as a positive integer. If the creation failed, $external_id is 0.

ERRORS

Failure can occur because of reasons such as:

NOTES

Single-newline line termination is recommended even when externals are targeted for Windows platforms (e.g., Windows GDMA), both to make the editing of such externals consistent in the Monarch UI and to make GDMA processing consistent across platforms. If you need to view a file containing such line termination on a Windows platform, use WordPad to do so, not NotePad, so this type of line termination is recognized and the line breaks will be honored in the text display.

The recommended object name constraints are to limit externals names to alphanumerics plus these five characters:

	@ - . _ %

BUGS

This routine currently does no validation of the external name to ensure that it follows our intended Monarch object name constraints.

There is a race condition in detection of whether an external name is already in use, that will not be completely blocked until we put a unique index on the externals.name column. Until then, it is up to the application designer to ensure that no two applications try to create or rename externals at the same time.


NAME

delete_external - delete both free external and all applied copies

SYNOPSIS

    $outcome = $dm->delete_external($external_name);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Delete a free host or service external, as well as all associated applied copies, whether or not their respective "modified" flags are set.

RETURN VALUE

$outcome will be true if the deletion succeeded, false otherwise.

ERRORS

Failure can occur because of reasons such as:

NOTES

Before you perform this destructive action, you might wish to call the appropriate pair of the following routines:

	$dm->list_hostprofiles_with_external($external_name);
	$dm->list_hosts_with_external       ($external_name);

	$dm->list_services_with_external    ($external_name);
	$dm->list_hostservices_with_external($external_name);

to provide a user warning if applied externals exist.

The deletion will likely succeed if the external does not exist, since all that matters is that it no longer exists.


NAME

get_external - get free external (either host external or service external; retrieve all content and metadata)

SYNOPSIS

    $e_ref = $dm->get_external($external_name);

    if ( not defined $e_ref ) {
        ## serious internal failure ...
    }
    elsif (not %$e_ref) {
        ## external not found ...
    }
    else {
	$external_id   = $e_ref->{external_id};
	$external_name = $e_ref->{name};
	$description   = $e_ref->{description};
	$type          = $e_ref->{type};
	$content       = $e_ref->{display};
    }

DESCRIPTION

Find all the details of the specified free external.

$e_ref->{external_id} is the Monarch internal identifier of the indicated external ($external_name), expressed as a positive integer.

$e_ref->{name} is the same external name that you searched with.

$e_ref->{description} is a very brief (50 characters max) commentary about the external.

$e_ref->{type} is either 'host' or 'service'.

$e_ref->{display} is the content of the external, generally consisting of a series of newline-terminated lines joined into one concatenated string.

RETURN VALUE

If the search succeeded and found the named external, $e_ref is a hashref referring to the details of that external. If the search succeeded and failed to find the external, $e_ref is a hashref pointing to an empty hash. If the search failed (e.g., because of a database error), $e_ref is undefined.

ERRORS

Failure can occur because of reasons such as:

NOTES

We return different values (reference to empty hash vs. undefined) for different types of search failure so the caller can distinguish between a failure that happened because the external did not exist (which might be the situation being probed for) and a failure that happened because database access was not successful. The application-logic response in these two cases should generally be very different.

BUGS

Because it requires improved support from the underlying Monarch code, this routine is only safe to use with GWMEE 6.7 or later.


NAME

get_externalid - find external ID (given an external name)

SYNOPSIS

    $external_id = $dm->get_externalid($external_name);

    if (not defined $external_id) {
        ## serious internal failure ...
    }
    elsif (! $external_id) {
        ## external not found ...
    }
    else {
        ## continue processing with the found external
    }

DESCRIPTION

Find the Monarch internal identifier of the specified external.

RETURN VALUE

If the search succeeded, $external_id is the Monarch internal identifier of the indicated external ($external_name), expressed as a positive integer. If the search ran to completion but came up empty, $external_id is 0. If the search failed (e.g., because of a database error), $external_id is undefined.

ERRORS

Failure can occur because of reasons such as:

NOTES

We return different values (0 vs. undefined) for different types of search failure so the caller can distinguish between a failure that happened because the external did not exist (which might be the situation being probed for) and a failure that happened because database access was not successful. The application-logic response in these two cases should generally be very different.

BUGS

Because it requires improved support from the underlying Monarch code, this routine is only safe to use with GWMEE 6.7 or later.


NAME

get_externalname - find external name (given an external ID)

SYNOPSIS

    $external_name = $dm->get_externalname($external_id);

    if (not defined $external_name) {
        ## error ...
    }
    else {
        ## continue processing with the found external
    }

DESCRIPTION

Find the name of the specified external ($external_id).

RETURN VALUE

If the search succeeded, $external_name is the name of the found external. If the search failed, $external_name is undefined.

ERRORS

Failure can occur because of reasons such as:

NOTES

We do not distinguish lookup failures from database-access failures in the return value from this routine, primarily because you should have only gotten an $external_id from some previous call to another routine, so its value should be valid and there is little reason for application logic to distinguish different types of failure here.


NAME

get_host_external - get applied host external (content and metadata of the individual separate copy)

SYNOPSIS

    $e_ref = $dm->get_host_external($host_name, $external_name);

    if ( not defined $e_ref ) {
        ## serious internal failure ...
    }
    elsif (not %$e_ref) {
        ## external not found ...
    }
    else {
	$external_id = $e_ref->{external_id};
	$host_id     = $e_ref->{host_id};
	$content     = $e_ref->{data};
	$modified    = $e_ref->{modified};
    }

DESCRIPTION

Find all details of the specified applied host external.

$e_ref->{external_id} is the Monarch internal identifier of the indicated external ($external_name), expressed as a positive integer.

$e_ref->{host_id} is the Monarch internal identifier of the specified host ($host_name), expressed as a positive integer.

$e_ref->{data} is the content of the external, generally consisting of a series of newline-terminated lines joined into one concatenated string.

$e_ref->{modified} is an integer acting as a boolean flag, indicating whether or not this applied external has been marked as having been modified since it was first copied from the associated free external.

RETURN VALUE

If the search succeeded and found the named host external, $e_ref is a hashref referring to the details of that external. If the search succeeded and failed to find the external, $e_ref is a hashref pointing to an empty hash. If the search failed (e.g., because of a database error), $e_ref is undefined.

ERRORS

Failure can occur because of reasons such as:


NAME

get_hostservice_external - get applied service external (conent and metadata of the individual separate copy)

SYNOPSIS

    $e_ref = $dm->get_hostservice_external($host_name, $service_name,
	$external_name);

    if ( not defined $e_ref ) {
        ## serious internal failure ...
    }
    elsif (not %$e_ref) {
        ## external not found ...
    }
    else {
	$external_id = $e_ref->{external_id};
	$host_id     = $e_ref->{host_id};
	$service_id  = $e_ref->{service_id};
	$content     = $e_ref->{data};
	$modified    = $e_ref->{modified};
    }

DESCRIPTION

Find all details of the specified applied service external.

$e_ref->{external_id} is the Monarch internal identifier of the indicated external ($external_name), expressed as a positive integer.

$e_ref->{host_id} is the Monarch internal identifier of the specified $host_name, expressed as a positive integer.

$e_ref->{service_id} is the Monarch internal identifier of the specified host service (combination of $host_name and $service_name), expressed as a positive integer.

$e_ref->{data} is the content of the external, generally consisting of a series of newline-terminated lines joined into one concatenated string.

$e_ref->{modified} is an integer acting as a boolean flag, indicating whether or not this applied external has been marked as having been modified since it was first copied from the associated free external.

RETURN VALUE

If the search succeeded and found the named service external, $e_ref is a hashref referring to the details of that external. If the search succeeded and failed to find the external, $e_ref is a hashref pointing to an empty hash. If the search failed (e.g., because of a database error), $e_ref is undefined.

ERRORS

Failure can occur because of reasons such as:


NAME

list_externals - list free externals (either host externals or service externals)

SYNOPSIS

    $external_names = $dm->list_externals($type);

    if (not defined $external_names) {
	## error ...
    }
    else {
	foreach my $external_name (@$external_names) {
	    ## processing
	}
    }

DESCRIPTION

List all free externals of the given type.

$type is either 'host' or 'service'.

RETURN VALUE

$external_names will be defined as an arrayref if the search succeeded (even if no externals were found), and undefined if the search failed due to some kind of error. Upon success, the array will list the relevant externals, in arbitrary order.

ERRORS

Failure can occur because of reasons such as:


NAME

list_host_externals - list externals applied to host

SYNOPSIS

    $external_names = $dm->list_host_externals($host_name);

    if (not defined $external_names) {
	## error ...
    }
    else {
	foreach my $external_name (@$external_names) {
	    ## processing
	}
    }

DESCRIPTION

Find the names of all host externals currently applied to the specified host.

RETURN VALUE

$external_names will be defined as an arrayref if the search succeeded (even if no externals were found), and undefined if the search failed due to some kind of error. Upon success, the array will list the relevant host externals, in arbitrary order.

ERRORS

Failure can occur because of reasons such as:


NAME

list_hostprofile_externals - list externals assigned to a specified host profile

SYNOPSIS

    $external_names = $dm->list_hostprofile_externals($hostprofile_name);

    if (not defined $external_names) {
	## error ...
    }
    else {
	foreach my $external_name (@$external_names) {
	    ## processing
	}
    }

DESCRIPTION

List all host externals that are assigned to the given host profile.

RETURN VALUE

$external_names will be defined as an arrayref if the search succeeded (even if no externals were found), and undefined if the search failed due to some kind of error. Upon success, the array will list the relevant host externals, in arbitrary order.

ERRORS

Failure can occur because of reasons such as:


NAME

list_hostprofiles_with_external - list host profiles with assigned external

SYNOPSIS

    $hostprofile_names = $dm->list_hostprofiles_with_external($external_name);

    if (not defined $hostprofile_names) {
	## error ...
    }
    else {
	foreach my $hostprofile_name (@$hostprofile_names) {
	    ## processing
	}
    }

DESCRIPTION

List all host profiles that have the given host external assigned to them.

RETURN VALUE

$hostprofile_names will be defined as an arrayref if the search succeeded (even if no host profiles were found), and undefined if the search failed due to some kind of error. Upon success, the array will list the relevant host profiles, in arbitrary order.

ERRORS

Failure can occur because of reasons such as:


NAME

list_hosts_with_external - list hosts with applied external

SYNOPSIS

    $host_names = $dm->list_hosts_with_external($external_name);

    if (not defined $host_names) {
	## error ...
    }
    else {
	foreach my $host_name (@$host_names) {
	    ## processing
	}
    }

DESCRIPTION

List all hosts that have the given host external assigned to them.

RETURN VALUE

$host_names will be defined as an arrayref if the search succeeded (even if no hosts were found), and undefined if the search failed due to some kind of error. Upon success, the array will list the relevant hosts, in arbitrary order.

ERRORS

Failure can occur because of reasons such as:


NAME

list_hostservice_externals - list externals applied to host service

SYNOPSIS

    $external_names = $dm->list_hostservice_externals($host_name, $service_name);

    if (not defined $external_names) {
	## error ...
    }
    else {
	foreach my $external_name (@$external_names) {
	    ## processing
	}
    }

DESCRIPTION

Find the names of all service externals currently applied to the specified host service.

RETURN VALUE

$external_names will be defined as an arrayref if the search succeeded (even if no externals were found), and undefined if the search failed due to some kind of error. Upon success, the array will list the relevant service externals, in arbitrary order.

ERRORS

Failure can occur because of reasons such as:


NAME

list_hostservices_with_external - list host services with applied external

SYNOPSIS

    $hostservices = $dm->list_hostservices_with_external($external_name);

    if (not defined $hostservices) {
	## error ...
    }
    else {
	foreach my $host_name (keys %$hostservices) {
	    my $service_names = $hostservices{$host_name};
	    foreach my $service_name (@$service_names) {
		## processing
	    }
	}
    }

DESCRIPTION

List all host services that have the given service external assigned to them.

RETURN VALUE

$hostservices will be defined as a hashref if the search succeeded (even if no host services were found), and undefined if the search failed due to some kind of error. Upon success, each key of the hash will be the name of a host that has at least one service with the specified service external applied, and the corresponding hash value will be an arrayref referring to an array listing tho relevant services on that host, in arbitrary order.

ERRORS

Failure can occur because of reasons such as:


NAME

list_service_externals - list externals assigned to a specified generic service

SYNOPSIS

    $external_names = $dm->list_service_externals($service_name);

    if (not defined $external_names) {
	## error ...
    }
    else {
	foreach my $external_name (@$external_names) {
	    ## processing
	}
    }

DESCRIPTION

List all service externals that are assigned to the given generic service.

RETURN VALUE

$external_names will be defined as an arrayref if the search succeeded (even if no externals were found), and undefined if the search failed due to some kind of error. Upon success, the array will list the relevant service externals, in arbitrary order.

ERRORS

Failure can occur because of reasons such as:


NAME

list_services_with_external - list generic services with assigned external

SYNOPSIS

    $service_names = $dm->list_services_with_external($external_name);

    if (not defined $service_names) {
	## error ...
    }
    else {
	foreach my $service_name (@$service_names) {
	    ## processing
	}
    }

DESCRIPTION

List all generic services that have the given service external assigned to them.

RETURN VALUE

$service_names will be defined as an arrayref if the search succeeded (even if no generic services were found), and undefined if the search failed due to some kind of error. Upon success, the array will list the relevant generic services, in arbitrary order.

ERRORS

Failure can occur because of reasons such as:


NAME

modify_external - modify free external (change content and/or metadata)

SYNOPSIS

    $outcome = $dm->modify_external($external_name, $description, $content);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Change the content and/or metadata (description) of a free external.

If $description is defined, its value will replace the existing external description.

If $content is defined, its value will replace the existing free external content.

RETURN VALUE

$outcome will be true if the modification succeeded, false otherwise. If both $description and $content are undefined, the modification will vacuously succeed.

ERRORS

Failure can occur because of reasons such as:

NOTES

To change the name of an external, use the separate rename_external() function.

There is no mechanism provided to change a defined description in the database to an undefined description. If you want to destroy an existing description without providing a useful replacement, an empty string will serve that purpose.

It is not possible to change the type of a free external from 'host' to 'service' or vice versa, as that would cause too much disruption.


NAME

modify_host_external - modify applied host external

SYNOPSIS

    $outcome = $dm->modify_host_external($host_name, $external_name,
	$content, $modified);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Change the content and/or metadata ("modified" flag) of an applied host external.

If $content is defined, its value will replace the existing applied external content.

If $modified is defined, its value will be used as a boolean flag to replace the existing "modified" flag accordingly.

RETURN VALUE

$outcome will be true if the modification succeeded, false otherwise. If both $content and $modified are undefined, the modification will vacuously succeed.

NOTES

You can change the $modified flag for an applied host external whether or not its content is different from the free host external from which it was originally copied. This allows you to control the freezing and unfreezing of the content with respect to the actions of propagate_external(), no matter whether you want to allow or prevent overwriting of local customizations, or simply want to lock the originally copied value.

ERRORS

Failure can occur because of reasons such as:


NAME

modify_hostservice_external - modify applied service external

SYNOPSIS

    $outcome = $dm->modify_hostservice_external($host_name, $service_name,
	$external_name, $content, $modified);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Change the content and/or metadata ("modified" flag) of an applied service external.

If $content is defined, its value will replace the existing applied external content.

If $modified is defined, its value will be used as a boolean flag to replace the existing "modified" flag accordingly.

RETURN VALUE

$outcome will be true if the modification succeeded, false otherwise. If both $content and $modified are undefined, the modification will vacuously succeed.

NOTES

You can change the $modified flag for an applied service external whether or not its content is different from the free service external from which it was originally copied. This allows you to control the freezing and unfreezing of the content with respect to the actions of propagate_external(), no matter whether you want to allow or prevent overwriting of local customizations, or simply want to lock the originally copied value.

ERRORS

Failure can occur because of reasons such as:


NAME

propagate_external - propagate free external to applied externals

SYNOPSIS

    $outcome = $dm->propagate_external($external_name, $replace);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Copy the content of a free external to corresponding applied externals, optionally ignoring their individual "modified" (i.e., "I've been customized -- leave me alone") flags.

$replace is a boolean flag specifying whether the corresponding applied externals with their "modified" flag set should have their content overwritten.

If $replace is true, all the associated applied externals will have their content overwritten with the content of the free external, regardless of the existing states of their "modified" flags, and the "modified" flag for each such external will be reset to indicate that the applied external is once again an unmodified copy of the free external.

If $replace is false, only the associated applied externals that have their "modified" flag set to false will have their content overwritten with the content of the free external.

RETURN VALUE

$outcome will be true if the propagation succeeded, false otherwise.

ERRORS

Failure can occur because of reasons such as:

NOTES

The "modified" flag provides a primitive mechanism for locking applied externals against propagation of future changes from the free external. Setting this flag to a true value is most often done when the applied-external content is customized after the external is initially applied, but it can also be used simply to block changes even if the original free-external content is perfectly suitable in this context without any localization changes.


NAME

remove_external_from_host - remove external from host

SYNOPSIS

    $outcome = $dm->remove_external_from_host($host_name, $external_name);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Remove the specified applied host external from the specified host.

RETURN VALUE

$outcome will be true if the removal succeeded, false otherwise.

ERRORS

Failure can occur because of reasons such as:

NOTES

The removal will likely succeed if the external was not previously applied to the host, since all that matters is that the association no longer exists.


NAME

remove_external_from_hostprofile - remove external assignment from host profile

SYNOPSIS

    $outcome = $dm->remove_external_from_hostprofile($hostprofile_name,
	$external_name);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Remove the assignment of the specified host external from the specified host profile.

RETURN VALUE

$outcome will be true if the removal succeeded, false otherwise.

ERRORS

Failure can occur because of reasons such as:

NOTES

The removal will likely succeed if the external was not previously assigned to the host profile, since all that matters is that the association no longer exists.


NAME

remove_external_from_hostservice - remove external from host service

SYNOPSIS

    $outcome = $dm->remove_external_from_hostservice($host_name,
	$service_name, $external_name);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Remove the specified applied service external from the specified host service.

RETURN VALUE

$outcome will be true if the removal succeeded, false otherwise.

ERRORS

Failure can occur because of reasons such as:

NOTES

The removal will likely succeed if the service is not applied to the host, or if the external was not previously applied to the host service, since all that matters is that the association no longer exists.


NAME

remove_external_from_service - remove external assignment from generic service

SYNOPSIS

    $outcome = $dm->remove_external_from_service($service_name, $external_name);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Remove the assignment of the specified service external from the specified generic service.

RETURN VALUE

$outcome will be true if the removal succeeded, false otherwise.

ERRORS

Failure can occur because of reasons such as:

NOTES

The removal will likely succeed if the external was not previously applied to the generic service, since all that matters is that the association no longer exists.


NAME

rename_external - rename free external (either host external or service external)

SYNOPSIS

    $outcome = $dm->rename_external($old_external_name, $new_external_name);

    if (not $outcome) {
	## error ...
    }
    else {
        ## success; continue processing
    }

DESCRIPTION

Change the name of a free external. Since applied externals simply refer to the name of the free externals from which they were copied, this will change the names of all the associated applied externals as well.

RETURN VALUE

$outcome will be true if the rename succeeded, false otherwise.

ERRORS

Failure can occur because of reasons such as:

BUGS

This routine currently does no validation of the new external name to ensure that it follows our intended Monarch object name constraints.

There is a race condition in detection of whether an external name is already in use, that will not be completely blocked until we put a unique index on the externals.name column. Until then, it is up to the application designer to ensure that no two applications try to create or rename externals at the same time.