How To Promote

NOTE: The following process assumes you have the EME installed on your test and production
machines. If this is not the case, see The Ab Initio Environment.
1. Developers create a sandbox and check it into the DEV datastore. They work on the
project files in the sandbox, checking in and checking out their source files to build
features and fix bugs.
Finally, the development group asserts that a project is ready to be tested. The group tags the
project they want to be tested.
2. Developers get their projects ready for promotion to testing: they make sure the project
parameters are used correctly, the graphs are deployed, and dependency information is
current. See "Preparing a project for promotion".
3. You run air object save to create a portable-interchange-format file (or save file) of the
QA-ready version of the project. See "Saving a project".
4. You run air object load to load the interchange file of the QA-ready project to the TEST
datastore. See "Loading a save file into another datastore".
5. You validate the promoted project in the TEST datastore by performing a number of
safety checks (to catch as many promotion errors as possible and ensure that the
promotion process does not introduce errors into either the project being promoted or
projects that have previously been promoted). See "Validating the promotion".
6. The QA engineers check out the QA-ready version of the project to their sandboxes and
report bugs to Development.
7. The Development team fixes the bugs and checks the project into the DEV datastore.
8. You tag the project in the DEV datastore, save the incremental changes using air object
save -since, and update the TEST datastore using air object load. See "Saving
modifications to a project" and "Loading a save file into another datastore".
9. The Test group checks out the new version and begins a new round of testing to verify
the bug fixes. The Test group verifies the fixes.
10. Repeat Steps 7-9 until the Test group declares the project sound and deems a version
ready for Production.
11. You use air object save to create a save file of the production-ready project based on the
last tag.
12. You promote the production-ready project to the PROD datastore using air object load.
13. You validate the promotion.
14. The Production team checks out and runs the project. If bugs are found, the Development
team fixes them.
Prerequisites
It is essential that you read the following chapters to understand the concepts in this chapter:
 "Sandbox parameters and other attributes"
"Managing versions"
"Dependency analysis"

Who can administer the EME datastore?

The following users have administrative privileges to the EME datastore:
The user who owns the physical files. Initially this is the user who created the datastore
(through air repository create).
The user who is the operating system administrator. On Unix this is the root user. On
Windows this is any member of the Administrators group.
An EME user who is a member of the eme-root group, which is automatically set up when
the datastore is created.
Identifying the datastore owner
To identify which user is the owner of the data files, run the ls command on the datastore's error
log file:
ls -l $AB_AIR_ROOT.errlog
The output might look like this:
-rw-r--r-- 1 ronb staff 0 2005-07-09 13:19 /disk1/data/eme/myeme.errlog
Identifying EME administrators
To identify whether you are an EME administrator, run air diag show-control with the -admin
option.
To see which users are in the eme-root group, run air system group show at the command line,
specifying the -verbose option:
air system group show eme-root -verbose
The output might be:
name gid membership
---- --- ----------
eme-root 99998 contained in:
contains: ronb, mkatz, pmoss
Changing the owner of the datastore
You can change the EME administrator by changing the owner of the physical files using the air
repository chown command. You must be root to change the datastore owner.
 To change the owner of the datastore:
2. Shut down the datastore:
air repository shutdown
3. Change ownership of the EME files:
air repository chown asmith
3. Restart the datastore:
air repository start
Alternatively, the current EME administrator can add a user to the eme-root group in the
datastore. In addition to the owner of the data files, all members of the eme-root group are
considered EME administrators. You can add a user to a group from the command line, using air
system group add-user.
For example, to make user mkatz a member of the eme-root group, run air system group add-user
at the command line, as follows:
air system group add-user mkatz eme-root
Maintenance tasks
The EME administrator is responsible for ongoing maintenance of the datastore. See "Ongoing
datastore maintenance tasks".

3. VERSION CONTROL

About datastore version numbers

Introduction
Versioning is an important feature of the EME. It allows you to:
Revert to earlier versions of a file, project, or datastore and manipulate specific versions of a
project or files.
Compare different versions of a graph in the EME Web Interface to Technical Metadata,
highlighting differences between them. For more information, see "Viewing and
comparing versions".
Package releases for promotion to another datastore.
Almost every object in a datastore is fully versioned. A full history of all versions of each
datastore object is kept, as shown in the following figure:
Version numbers
Each object in a datastore — a file, a graph, a directory, and so on — has a version number
associated with it.
Version numbers, which are integers, are global to the datastore. Therefore, whenever a single
file, graph, or project is checked into the datastore, the datastore increments its version number
and assigns the number to the newly checked-in item. The datastore retains previous versions of
the item as well.
The effect of this scheme is twofold:
Different items in the datastore have different version numbers.
There may be gaps in the version numbers at which a given object has changed.

Error! Hyperlink reference not valid.

Consider the following example:
4. Assume the current datastore version is 18 and you check in the file a-customers.dml to
the warehouse1 project. The datastore updates its number to 19 and assigns this version
number to the new copy of a-customers.dml.
5. Then you check in the file b-customers.dml to the warehouse2 project. Now, the datastore
increments its version number to 20 and assigns that number to b-customers.dml.
6. Finally, you check in the project warehouse1. The datastore updates its number to 21 and
assigns version number 21 to every checked-in file in the warehouse1 project, including
a-customers.dml if it was checked in.
Note that the most recent modified versions of a-customers.dml and b-customers.dml are
different — 20 and 21, respectively — and that a-customers.dml did not change at version 20,
just 19 and 21. If you request version 20 of this file, you will access the file's contents as they
existed at version 19.
What affects the version number
Checkin is the most common operation that updates the version number of the datastore.
However, any air utility commands that change (write) the datastore also update the datastore
version number.
What you will learn
You will learn about:
Accessing a particular version
 Determining which version is checked in or out
Displaying the versions of an object or datastore
Finding the current version number of an object
Finding the current version of a datastore
Comparing two versions of a datastore
Reverting to an earlier version
Making objects nonversioned

Accessing a particular version

air utility commands You can run any air utility command against a specific version of the
datastore — just specify the -version version argument to the command. The version is specified
as an integer or as a tag. For the complete syntax of the -version argument, see "Command-line
syntax of air commands".
The air project files command lists information about each file in a project, including the version
in the datastore (-versions) as well as the version and time that you checked in or out (-verbose).

For example, to see the list of files in the lesson project and the version of each:
air project files /Projects/lesson -versions \
-basedir /u/work/mysandbox
The output, excerpted here, might be as follows:

Status EME Path MIME Type E Sandbox

M
E

Current mp/JoinCustomers.mp application/x-abinitio/graph 11 117

7

Stale run/Graph2.ksh text/x-shell.ksh 12 120

7

Finding The Current Version

To see the current version number of an object, use the air object ls command (shortcut air ls)
with the -ld argument.
For example, to see the domain and current version number of the JoinCustomers graph, type:
air object ls -ld /Projects/lesson/mp/JoinCustomers.mp
The following display shows that the graph is currently at version 29 (shown in bold).
-rw-rw---- jon 163872 000000134.000000029 mimeobj: JoinCustomers

GOOD EXAPLE ABOUT VERSION

Consider the following example:

7. Assume the current datastore version is 18 and you check in the file a-customers.dml to
the warehouse1 project. The datastore updates its number to 19 and assigns this version
number to the new copy of a-customers.dml.
8. Then you check in the file b-customers.dml to the warehouse2 project. Now, the datastore
increments its version number to 20 and assigns that number to b-customers.dml.
9. Finally, you check in the project warehouse1. The datastore updates its number to 21 and
assigns version number 21 to every checked-in file in the warehouse1 project, including
a-customers.dml if it was checked in.
Note that the most recent modified versions of a-customers.dml and b-customers.dml are
different — 20 and 21, respectively — and that a-customers.dml did not change at version 20,
just 19 and 21. If you request version 20 of this file, you will access the file's contents as they
existed at version 19.

EME datastore
An EME datastore is a specific instance of the EME: the term denotes the specific EME storage
that you are currently connected to through the GDE.
Obviously, many such datastore instances can reside in an environment in which the EME has
been installed. But you can only be connected to one datastore at a time: this is determined by
your GDE's current EME datastore settings, reached through Project > EME Datastore Settings
in the GDE main menu (on the command line the connection is specified by the value of
AB_AIR_ROOT, or by specifying the -root argument to individual commands). You can change
this setting and use a different datastore, but you can use only one datastore at a time in the GDE.
Source control
From the application developer's perspective, the primary use of the EME datastore is as an area
in which Ab Initio files are kept under source control.
The next section describes what this involves.

Creating a patch release from a branch

The major application of branching is to help you efficiently generate a patch release of software
— a small release of bug fixes that repair flaws in a major release. To accomplish this goal, we
recommend that you use the procedure that follows.

To create a patch release from a branch:

10. When your Development team asserts that a project is ready to be tested, the project
leader should tag the project and create a save file based on the tag in the source
datastore. Then the project leader should load the save file into the datastore reserved for
the Test team. Assume that the project is called Projects/lesson. Note that the tag is a
combination of the date and the project name:
export AB_AIR_ROOT=dev_eme
air tag create 2005_06_07_LESSON_TAG1 /Projects/lesson
air object save LESSON_TAG1.save -from-tag 2005_06_07_LESSON_TAG1
In test_eme, the datastore for the Test team:
export AB_AIR_ROOT=test_eme
air object load LESSON_TAG1.save
4. The Development team continues to work on the main branch, building and checking in
graphs needed for a different major release. Meanwhile, the Test team finds that a few
relatively small changes need to be made to the release they are testing; the testing team
notifies the Development team.
5. The EME administrator creates a branch in the Development datastore starting from the
previously created project tag, 2005_06_07_LESSON_TAG1. The branch is a virtual
copy of the parent branch.
air branch create branch1 -from-version 6_07_2005_LESSON_TAG1
4. The developers connect to branch1, check out the project from the branch into a sandbox,
make the suggested bug fixes, and check them back into branch1.
5. Later, when the Development team asserts that the fixes are ready to be tested, the project
leader tags only the modified files on the branch:
export AB_AIR_ROOT=dev_eme
export AB_AIR_BRANCH=branch1
air tag create 2005_06_14_LESSON_TAG2 /Projects/lesson
6. The EME administrator creates a save file containing only the modified files:
air object save LESSON_TAG2.save \
-from-tag 2005_06_14_LESSON_TAG2
7. The administrator loads them into the Test datastore:
export AB_AIR_ROOT=test_eme
air object load LESSON_TAG2.save
As problems arise, repeat the procedure from Step 4 on until the Test group asserts that the entire
project in the Test datastore is ready to be promoted to Production.