BuildForge Help

Special Case Variables

The system watches for some special environment variable names. When a step's environment contains one of these variables (either specifically or inherited from a project or server), the system performs actions. The following table describes these variables.

Variable

Contents

_CI_BUILD_DELETE

Set this variable to any value to delete the build and associated build data after the job runs. (The tag variable is reset to its initial value, prior to the deleted build, if no other project builds executed.)

_CI_BUILD_KEEP

Set this variable to any value to keep the build and associated build data after the job runs. For example, if your job includes an adaptor link and the adaptor step fails, the other project steps do not execute. You might want to keep a copy of the build records for the job, for example, for debugging.

_CLEARCASE_VIEWS

Specifies a list of ClearCase views to start before command execution. Set the value to a comma-separated list of views; for example, "View1,View2,View3".

_CLEARCASE_VOBS

Specifies a list of ClearCase VOBs to mount before command execution. Set the value to a comma-separated list of VOBs; for example, "\Vob1,\Vob2,\Vob3".

_CONTEXT_LOG_RANGE

Use this variable to limit log output to lines near filter matches. It takes a positive integer value, and causes the system to omit log output except for a range of lines around each filter string hit whose size is equal to the variable's value. For example, if you set the variable to 5, your logs will show only lines with filter matches, plus the 5 lines preceding and 5 lines following those matches.

_ERROR_THRESHOLD

Establishes the maximum numbers of errors (caught by the "Set Fail" filters you have defined) allowed. Using this variable, you can establish thresholds for individual steps and/or for a project, and either fail the step or project when the threshold value is met, or merely note the fact that the threshold was met in the job notes.

When you set the _ERROR_THRESHOLD variable for a project, you can use one of the following forms:

  • A value 5 or F5 indicates a maximum of 5 failures are allowed before failing the job.

  • A value like N7 indicates that the system should add a message to the job notes that the threshold was met when 7 errors occur.

When you use the variable in a step, the system counts the errors in the individual step. Additional forms are available:

  • A value like W9 indicates that after 9 errors, the step is put in a warning state, regardless of future errors caught by filters.

  • A value like C8 indicates that after 8 errors, the step is set to failure status, but any Clear Fail filter can clear the failure.

NOTE: The errors counted by this variable are defined as strings that match filters with Set Fail actions and which are assigned to steps in the project. Each string identified as a failure by a filter counts as one error toward the step total, and one toward the project total.

_EXITCODE_MAP

Specifies a list of numbers (separated by commas, spaces, semicolons, or colons) that the system should accept as indicators of step success. By default, an exit code of 0 indicates success; when this variable is specified, any values listed in it also indicate success.

_InterfaceLoggingLevel

Controls how much log data Build Forge logs when it runs an adaptor step. Create an environment variable (in your adaptor environment) with the name _InterfaceLoggingLevel. Assign it an integer value from 0 to 8. Logging levels are inclusive, for example, level 2 includes information from levels 1 and 0.
  • 0: Exec line plus server connection errors or cancel notification; nothing else
  • 1: Parsed commands (commands as they will be sent to the server)
  • 2: Unparsed commands (commands prior to having their local variables set)
  • 3: Build and environment variable SET lines
  • 4: Temp and internal variable SET lines
  • 5: Environment evaluations, e-mail group additions, BOM text logging lines
  • 6: Block & Sub-block start/end lines
  • 7: (Default logging level) Agent output that will be checked against match patterns, plus the lines that matched the patterns.
  • 8: All agent output

_LOG

Specifies a path name to create a copy of the command output in. Use this variable to save a copy of the job log on the server. If the file exists, the system appends to it.

_MAP

See Windows Mapped Drives for a discussion of how to use this variable.

_NO_PREPARSE_COMMAND

The system normally attempts to resolve the values of environment variables before sending commands to agents. When the _NO_PREPARSE_COMMAND variable is defined (with any value), the system sends variables to agents without resolving them. Use this variable to ensure that your operating system shell handles the variables.

_PRISM_DIR_POSTCMD

Used with plug-ins for IDEs. Specifies a command to be run on directories after the project step has executed. See Special Variables for Test Projects for more information.

_PRISM_DIR_PRECMD

Used with plug-ins for IDEs. Specifies a command to be run on directories before they are copied to the server for a project step. See Special Variables for Test Projects for more information.

_PRISM_FILE_POSTCMD

Used with plug-ins for IDEs. Specifies a command to be run on files after the project step has executed. See Special Variables for Test Projects for more information.

_PRISM_FILE_PRECMD

Used with plug-ins for IDEs. Specifies a command to be run on files before they are copied to the server for a project step. See Special Variables for Test Projects for more information.

_SUPPRESS_LOG_OUTPUT

When defined (with any value), causes the system to omit nearly all of the log output normally produced by the agent. Some Management Console log messages remain, and filter matches are also shown.

_TIMEOUT

A value that overrides the Timeout property for one or all of the steps in your project.

_TRAP

A string to be executed if the current step fails; the string can be set to the name of an executable file or command. NOTE: The output of the command is not returned to the console because the connection between the console and the agent is closed when the step fails; if you want to retain output from a command executed via _TRAP, have the command write its output to a file for later retrieval.

_USE_BFCREDS

When set to 1, the system uses the user's login credentials to log in to servers, rather than the credentials stored in the server authorization attached to server. The system uses the Management Console login credentials of the user who started the project to execute the commands in the project. You can set this variable for a single step, or for an entire project.
Note: If you are using LDAP/Active Directory authentication, the Store User Authentication Locally system setting must be set to Yes (its default value) for the _USE_BFCREDS function to work. When the setting is Yes, the system caches user authentication information in encrypted form, and can then access the user authentication information for use with _USE_BFCREDS.
Related concepts
Setting the Adaptor Log Level
Windows Mapped Drives