NAME

BuildForge::Services::DBO::EnvironmentEntry


SYNOPSIS

        use BuildForge::Services;
        $conn = new BuildForge::Services::Connection($hostname);
        $token = $conn->authUser($user, $pass);
        
        $entry = new BuildForge::Services::DBO::EnvironmentEntry($conn);
        # Getter / setter functions
        $environmentGroupId = $entry->getEnvGroupId();
        $ordinal = $entry->getEntryOrdinal();
        $name = $entry->getEntryName();
        $value = $entry->getEntryValue();
        $action = $entry->getAction();
        $mode = $entry->getMode();
        $envGroup = $entry->getParent();
        $entry->setEntryName('PROP_NAME');
        $entry->setEntryValue('New Value');
        $entry->setAction(ENUM_ENVIRONMENTENTRY_ACTION->APPEND);
        $entry->setMode(ENUM_ENVIRONMENTENTRY_MODE->READ_ONLY);
        $entry->update();
        
        # Entry creation, modification, and deletion.
        $envGroup = BuildForge::Services::DBO::Environment->findByName($conn, 'EnvironmentName');
        $newentry = new BuildForge::Services::DBO::EnvironmentEntry($conn);
        $newentry->setEntryName('VARIABLE_NAME');
        $newentry->setEntryValue('Value');
        $envGroup->addEnvironmentEntry($var);
        $newentry->setEntryValue('New Value');
        $newentry->update();
        
        $newentry2 = $newentry->clone();
        $envGroup->addEnvironmentEntry($newentry2);
        
        $newentry->moveTo(2);
        $newentry->delete();
                
        $conn->logout;
        $conn->close;


DESCRIPTION

EnvironmentEntry allows you to create and modify environment variables inside of an Environment. To create the environment variables in the database, see the Environment->addEnvironmentEntry() function.


METHODS

new BuildForge::Services::DBO::EnvironmentEntry(connection, {environment}, {EnvEntryParamsHashRef})

Returns a new instance of an EnvironmentEntry object.

connection

A connected BuildForge::Services::Connection object.

environment

This should be undef or not passed - it is only used internally.

EnvEntryParamsHashRef

An optional reference to a hash containing any or all of the following fields.

entryName

The name of the environment variable.

entryValue

The value of the environment variable, defaulting to none.

action

The variable's action. This may be any of:

SET

The default. Will cause the variable to be set to its value.

SET_IF_NOT_SET

Will cause the variable to be set to the value if the variable value has not already been set.

APPEND

Causes the variable value to be appended to the previous value separated by a system-specific path delimiter (':' for Unix systems, ';' for Windows systems).

PREPEND

Causes the variable value to be prepended to the previous value separated by a system-specific path delimiter (':' for Unix systems, ';' for Windows systems).

CLEAR

Sets the variable's value to the empty string. The entryValue will be disregarded.

UNSET

Deletes the variable from the variable list. This differs from clearing it in that the former will print nothing when the variable is printed and the latter will (normally) print the variable name.

HIDDEN

Makes this variable a hidden variable. Hidden variables do not appear in the list of variables output by step results.

mode

Affects what happens when a project is kicked off with the variable in the project's environment. This may be any of:

NORMAL

The default. The variable acts normally.

MUST_CHANGE

The project cannot be quickstarted, and when the build is kicked off, the value of the variable must change.

READ_ONLY

When the project build is being kicked off, the value of the variable cannot be changed.

REQUIRED

The project cannot be quickstarted if the variable has no initial value, and when the build is kicked off, the value of the variable cannot be empty.

SUPPRESS_DISPLAY

The variable is not displayed in the project environment variable list on the project start page.

$variable->clone()

A copy of the EnvironmentEntry object is returned without affecting the database. To save the copy to an environment group, $environment->addEnvironmentEntry($copy) must be run on the copy.

$variable->update()

Updates the variable settings in the database.

$variable->moveTo(index)

Moves the variable within its parent environment group.

index

The new location of the variable. 0 moves it to the first position, 1 to the second position, etc.

$variable->delete()

Deletes the variable from the database.

$variable->getParent()

Returns the BuildForge::Services::DBO::Environment object for the environment group this variable belongs to.

$variable->getEnvGroupId()

Returns the environment group ID for the environment group this variable belongs to.

$variable->getEntryOrdinal()

Returns the ordinal for the position of the variable in the variable list. 1 means it's the first variable, 2 means it's the second, etc.

$variable->getEntryName()

Returns the variable name.

$variable->getEntryValue()

Returns the variable value.

$variable->getAction()

Returns the variable action which controls how the variable value is set. This may be any of 'SET', 'SET_IF_NOT_SET', 'APPEND', 'PREPEND', 'CLEAR', 'UNSET', or 'HIDDEN'.

$variable->getMode()

Returns the variable mode which controls how the variable behaves when it is in an environment group that is connected to a project and a build of that project is kicked off.

$variable->setEntryName(name)

Sets the name of the variable. $variable->update() must be run before changes are replicated in the database.

name

The new name for the variable.

$variable->setEntryValue(value)

Sets the value of the variable. $variable->update() must be run before changes are replicated in the database.

value

The new variable value.

$variable->setAction(action)

Sets the variable action which controls how the variable value is set. $variable->update() must be run before changes are replicated in the database.

action

May be any of:

SET

Will cause the variable to be set to its value.

SET_IF_NOT_SET

Will cause the variable to be set to the value if the variable value has not already been set.

APPEND

Causes the variable value to be appended to the previous value separated by a system-specific path delimiter (':' for Unix systems, ';' for Windows systems).

PREPEND

Causes the variable value to be prepended to the previous value separated by a system-specific path delimiter (':' for Unix systems, ';' for Windows systems).

CLEAR

Sets the variable's value to the empty string. The entryValue will be disregarded.

UNSET

Deletes the variable from the variable list. This differs from clearing it in that the former will print nothing when the variable is printed and the latter will (normally) print the variable name.

HIDDEN

Makes this variable a hidden variable. Hidden variables do not appear in the list of variables output by step results.

$variable->setMode(mode)

Sets the variable mode which controls how the variable behaves when it is in an environment group that is connected to a project and a build of that project is kicked off. $variable->update() must be run before changes are replicated in the database.

mode

May be any of:

NORMAL

The default. The variable acts normally.

MUST_CHANGE

The project cannot be quickstarted, and when the build is kicked off, the value of the variable must change.

READ_ONLY

When the project build is being kicked off, the value of the variable cannot be changed.

REQUIRED

The project cannot be quickstarted if the variable has no initial value, and when the build is kicked off, the value of the variable cannot be empty.

SUPPRESS_DISPLAY

The variable is not displayed in the project environment variable list on the project start page.


COPYRIGHT

Copyright (c)2006-2007 International Business Machines, Inc. All rights reserved.