BuildForge Help

.load

.load [-o] [-e] [-v] [-j] [<relative_path>/]<filename>
.load -r|-p <registername>
.load -s `<command name>`

The .load command loads a project from an XML file and adds the steps of the loaded project to the current project, after the step that executed the .load command, allowing a project to dynamically create and load steps at run time. Using options, you can cause the .load command to draw its data from a register or from the output of a command.

To write an XML file for a .load command, start with an export file from an existing project to give you the appropriate basic structure. You can also create a project within the system, then export it to use it in a .load command. This topic includes sample XML code.

The steps loaded by a .load command can contain references to inlined or chained projects. By default, the system looks for the definitions of inlined projects within the XML file, and loads their steps; see the -e option below for a way to have the system get the inlined project definition from the database. For pass chained or fail chained projects, the system always looks for the project definition in the database.

Multiple Projects in XML Files

Because the system exports inlined projects along with their calling projects, an XML file may contain several projects. The .load command executes the project that is labelled primary in the file. This project has attribute primary="1" on its <project> element.

Command Options and Parameters

The simplest command form is .load <filename>. You can include an optional path name (relative to the job directory) in front of the filename. For example, the command
.load ../../project.xml

loads the file project.xml from the server directory (the directory that contains the project and job directories), assuming that the step's path property is "/" (the default).

Note: When a normal step launches an inlined project, the system goes to the database to the get the current definition for that project; when a step that is imported by .load command launches an inlined project, the system looks inside the XML file for the definition of the inlined project. See the description of the -e option below for a way to avoid this situation.
The command has the following options:
-r or -p
These options cause the system to load steps from a register. Use the command line with these options.
.load -r|-p <registername>
The -r option loads steps from an ordinary register, while the -p option loads steps from a project register. You can build up data in a register in earlier steps in your project, then load the steps from the register with this command.
-s
This option causes the system to run a command and use the output of that command as the data to load. Use the command line
.load -s `<command name>`
-e
When the -e option is set, the system gets inlined projects from the database instead of from the loaded XML file. It treats the value of chainID as a reference to a project ID within the database. This enables your XML file to reference the latest version of an inlined project, instead of the one in the XML file, or to reference a project that is not included in the XML file.
-o
Use the -o option to disable inlined projects within the XML file. When this option is used, the system ignores any inlined projects within the main project. A step that contains a reference to an inlined project executes its command but then ignores its inline.
-j
Use the -j option if the last set of steps in the XML file are threaded and the steps following the .load command are also threaded. The -j option turns the last threaded step into a join step. Otherwise, the threaded steps become part of the threaded block of steps following the .load command.

Sample XML

The following example shows an XML file to use with the .load command. The XML was created by exporting a project named HelloWorldPlusInline.

Note the following details of the example XML:
  • The XML contains two <project> elements.
  • The first project in the XML is the primary project; it has the attributes name="HelloWorldPlusInline" and primary="1" .
  • The second project in the XML is called Sleepytime and has the attribute primary="0" to indicate that it is not primary.
  • The first step of the HelloWorldPlusInline is a step named EchoHelloWorld which contains an echo command and a chainID attribute. The chainID attribute has a value of 2, indicating that the system should inline the project with the ID 2, which is the Sleepytime project.
    Note: Ignore the step attribute inline; it is a deprecated attribute that is no longer used. All steps have this attribute with a value of N. To determine if a step has an inlined project, look for the attribute chainID . The value of chainID refers to the ID of a project. By default, the system looks for the inlined project within the XML file, but if you use the -e option in your .load command, the system treats the value as project ID within the database. This allows you to create your own .load files without having to include inlined projects within them.
  • Each project has an id attribute. This ID value is the same as the project's ID in the database. You can get a list of project IDs by executing the following command from your installation directory.
    bfexport -l 
<?xml version="1.0" encoding="UTF-8"?>

<buildforge schema="7.000301" comment="">
  <project access="6" active="Y" name="HelloWorldPlusInline" primary="1" selectorId="Choose_local" maxthread="0" increment="Y" tagsync="0" buildclass="Production" sticky="N" envId="0" tag="BUILD_$B" id="19" exclusive="0">
    <tagvar autoincrement="Y" name="B" id="1">2</tagvar>
    <step absolute="N" failwait="N" selectorId="" dir="/" broadcast="N" timeout="300" id="1" passwait="N" inline="N" threadable="N" chainId="2" access="6" active="Y" passnotify="0" description="EchoHelloWorld" onfail=" " failnotify="0" envId="0">
      <command>echo Hello World</command>
    </step>
    <step absolute="N" failwait="N" selectorId="" dir="/" broadcast="N" timeout="300" id="2" passwait="N" inline="N" threadable="N" access="6" active="Y" passnotify="0" description="export proj to build and server folders" onfail=" " failnotify="0" envId="0">
      <command>.export $BF_PROJECTNAME_PHYS.xml
copy /Y $BF_PROJECTNAME_PHYS.xml ..\..</command>
    </step>
  </project>
  <project access="6" active="Y" name="Sleepytime" primary="0" selectorId="Choose_local" maxthread="0" increment="Y" tagsync="0" buildclass="Production" sticky="N" envId="0" tag="SLEEP_$B" id="2" exclusive="0">
    <tagvar autoincrement="Y" name="B" id="1">21</tagvar>
    <step absolute="N" failwait="N" selectorId="" dir="/" broadcast="N" timeout="300" id="1" passwait="N" inline="N" threadable="N" access="6" active="Y" passnotify="0" description="Sleep, perchance to dream" onfail=" " failnotify="0" envId="0">
      <command>.sleep 0</command>
    </step>
  </project>
  <class maxdays="0" access="1" entranceprojectId="1" name="Production" keepfiles="B" deletechangedata="N" purgeprojectId="2" exitProjectId="5" candidates="AnyBuild " maxbuilds="0"></class>
  <selector operator="" required="" access="6" value="" name="Choose_local" selectorId="" property=""></selector>
</buildforge>