Introduction

air commands are a set of shell commands that allow Technical Repository administrators
and others to create, manage, annotate, back up, and promote technical repositories. Some
shell commands have user-interface equivalents in Ab Initio client applications such as the
Technical Repository Management Console and the GDE.

This chapter covers the following topics:

 Command-line syntax of air commands

 Commands

o Command groups
o Running commands in batch mode
o Deprecated or disabled commands
o Commands with repeatable arguments

 Specifying object names as arguments

 Commands that are branch-specific or repository-wide
 Commands that are local or remote
 Command aliases
 Command return status codes
 What do you want to do?

Command-line syntax of air commands

Running air commands in a mixed environment
When running air commands in a mixed environment — for example, the Co>Operating
System installation (AB_HOME) is Version 2.15, and the technical repository software
installation (AB_AIR_HOME) is Version 3.1 — you must set AB_AIR_HOME in your
environment to the path of the Co>Operating System. For example:

export AB_AIR_HOME=/usr/local/abinitio-V-3-1-6

This is often done by specifying this path in your Korn shell .profile script.
Requirement for running air commands
To run an air command you must set the path to the technical repository you are acting on.
You can set the path in the environment before running an air command using the
configuration variable AB_AIR_ROOT. All commands run in this way will act on the
repository set in the environment. You can also set the path on a per-command basis using
the -root root argument to the air utility. The -root argument has precedence over a setting
made in the environment. For more information, see “-root”.
Syntax
All air commands have the following command-line syntax:

air [-root root]

[-version version | tag-name | date]
[-branch branch-name]
[-search-index]
[-remote]
[-user user-name]
command arguments

Note that tag-name can be the name of a tag or an rtag (an old-style tag).

All air commands can include the optional arguments -root and -version.

-root
-root root specifies the path to the root of the technical repository. In most cases you should
use an absolute pathname — for example, /disk3/data/repo.

Typically, you specify the repository path by setting the configuration

variable AB_AIR_ROOT. For example, to set the root of the my_eme repository and then
execute the air ls command, you could type at the prompt:

export AB_AIR_ROOT=/disk3/data/my_eme
air ls -l

Alternatively, you can specify the repository name on the command line. For example:

air -root /disk3/data/eme ls -l

The technical repository root can be the URL of a remote file — for
example, //host/projects/warehouse/eme. A remote host can be specified if the repository
and the Co>Operating System are installed on that host and your environment is configured
to allow access to that host by way of the Co>Operating System.
-version
-version version, -version tag-name, and -version date specify the technical repository
version number, tag, or date to be used by the air command.

NOTA:

Do not use -version for commands that write to the technical repository, because versions
of the repository older than the current version are read-only, and the command will fail.

Version name or number

If you specify a version number, the air command operates on the technical repository as it
existed at that version. The version number can be an integer or a name. For example, to
run air object cat to display the contents of the record format file account.dml at version
125, type:

air -version 125 object cat /Projects/warehouse/dml/account.dml

You can also specify the version by setting the AB_AIR_VERSION configuration variable.
For example, to show version 125 of account.dml, type at the command line:

export AB_AIR_VERSION=125
air object cat /Projects/warehouse/dml/account.dml

Assuming that version 125 has been labeled QA-ready, you could alternatively specify the
preceding command as:

air -version QA-ready object cat /Projects/warehouse/dml/account.dml

If you specify a version number that does not exist for a particular object, the object is
shown as it existed at that version number. For example, assume a given object has three
versions — 5, 12, and 20. You run air cat on that object and specify the version number
as -version 15. Since the contents of the object did not change between versions 12 and 15,
you will see the object as it was checked in at version 12:

air -version 15 object cat /Projects/warehouse/dml/account.dml

If you specify 0 as the version number, it indicates the tip.

Tag name
A tag is a symbolic name that you can associate with specific versions of objects. If you
specify a tag name, the air command operates on the technical repository using the versions
of the objects associated with the tag. The version at which an object is accessed is
determined as follows:

 If the object is in the tag, the object is accessed at the version specified in the tag.
 If the object is not in the tag, the object is accessed at the version at which the tag
was last modified.

For example, the following figure shows mytag. It contains two objects — obj1, tagged at
version 20, and obj2, tagged at version 27. The object obj3 is not included in mytag.

Running air -version mytag object cat obj1 shows the contents of obj1 at version 20, the
version at which it was tagged. However, running the same command on obj3 will show the
contents of obj3 at version 30, the version at which the tag was last modified.
date
The version can be specified as a date and time at which an air command is to access the
technical repository. The version of the repository as of the specified date and time is used.
If there are multiple versions at this date and time, the latest version is used by
the air command you issue.

Specify the date in the format "YYYY-MM-DD HH:MM:SS" or "YYYY-MM-DD". If you

do not specify a time, the version at midnight is used — in other words, "YYYY-MM-DD
00:00:00".

Time is expressed as local time and in 24-hour format.

For example, to see details about graph.mp as of 1:03 p.m. and 5 seconds on May 11, 2016,
type:

air -version "2016-05-11 13:03:05" ls /Projects/myproj/mp/graph.mp

air object field-lineage /Projects/rbank/adjustments/mp/adjustments.mp@@2016-11-14-Branch
-branch
-branch name runs the air command on the specified branch. If you don’t specify -branch,
the command operates on the main branch, which is main. The value of -branch on the
command line overrides other settings in the environment (such as AB_AIR_BRANCH).

For example, assume that the name of the main branch has been changed to dev_eme and
has two child branches: branch1 and branch2 — as shown in the following figure:

With AB_AIR_ROOT set to dev_eme, you can run a command (such as air ls) on any
branch without changing the repository location setting. You need only specify -
branch followed by a branch name:

air -branch branch1 ls

air -branch branch2 ls

You can also specify the branch by setting the AB_AIR_BRANCH configuration variable.
To set the branch to branch1, for example, before you run an air command, type at the
command line:

export AB_AIR_BRANCH=branch1

Shortcut

You can specify a branch name in the path argument of any air command by
entering @@ (double at sign) characters followed by the branch name. The @@ notation is
position-independent; you can place it anywhere after the air command. This shortcut can
be useful when performing dependency analysis or a repository unload — for example:

air object field-lineage /Projects/rbank/adjustments/mp/adjustments.mp@@2016-11-14-Branch

For more detailed information about branching, see “Creating and managing release
branches” in the Technical Repository Guide to Version Control. For a table of branch-
specific commands, see “Commands that are branch-specific or repository-wide”.
-search-index
-search-index runs the air command on the search index technical repository that is
associated with the repository pointed to by AB_AIR_ROOT. You do not need to know the
actual name of the search index. For example, instead of:

air -root dev_eme_si repository destroy

you may invoke the following, assuming AB_AIR_ROOT is set to dev_eme:

air -search-index repository destroy

-remote
-remote specifies that the air utility should start the Technical Repository server remotely
even if a direct connection is possible. Alternatively, you can obtain this behavior by setting
the AB_AIR_USE_LOCAL_STORAGE configuration variable to false.
-user
-user user-name specifies the name of the user running the command. Only the Technical
Repository administrator can use this option. Alternatively, you can obtain this behavior by
setting the AB_AIR_USER configuration variable.

Commands
This topic describes the following:

 Command groups
 Running commands in batch mode
 Deprecated or disabled commands
 Commands with repeatable arguments

Command groups
The air utility commands consist of these main groups:

Command group Description

air annotation Assigns, removes, and describes annotation values, comments, and
commands descriptions.
air batch commands Executes multiple air utility commands in a single batch.
Command group Description
air branch Administers technical repository software branches.
commands
air category Manages the creation, modification, and deletion of categories and
commands views; creates and manages a persistent metadata cache.
air display command Displays the structure or contents of repository objects.
air dump commands Generates human-readable reports of repository data structures.
air env command Lists or deletes sandbox log files to assist with archiving or
reclaiming disk space.
air help command Displays online documentation about individual and groups
of air commands.
air lock commands Sets, releases, breaks, and resets file locks.
air object commands Manipulates objects and directories in the technical repository,
displays and controls permissions to objects, saves objects to a
portable save file and loads them into a technical repository.
air project Creates and manipulates projects and project parameters, runs
commands dependency analysis, sets an object’s MIME type, updates the
sandbox from the technical repository (checkout), and updates the
repository from the sandbox (checkin).
air promote Moves objects within a technical repository or from one technical
commands repository to another (promotion) and saves/loads a history of the
operation.
air purge commands Permanently removes old objects from the technical repository.
air reposit Populates the technical repository with files (HTML, DML, dataset,
commands text, MIME) from the filesystem.
(deprecated)
air repository Operates on the storage system of the technical repository rather than
commands on its content: changes file permissions and ownership, checks
referential integrity, adds data files, performs backups,
enables/disables user authentication, and starts and shuts down the
Technical Repository server.
air sandbox Creates and manages sandboxes: displays differences between
commands sandboxes; creates parameter sets, executes a graph, updates graphs,
and displays information.
air system Installs, administers, and displays systems objects and administers
commands user accounts.
air tag commands Creates and manipulates tags: freezes tags, lists differences between
tags, lists tags, removes an object from a tag, renames a tag.
Running commands in batch mode
Batch mode causes air commands to be accumulated in a temporary file and then executed
as a group. For most commands batch mode is transactional — an all-or-nothing
proposition. That is, commands in the batch are committed only once — when the entire
batch succeeds — rather than as a series of intermediate commits. Because the number of
processes is reduced, batch mode is much faster than nonbatch mode when large numbers
of objects are being created, modified, or deleted.

However, when a single command in the batch fails, most of the time the entire batch
operation terminates, rolling back the commands that were written to the temporary file.
The only exceptions are air commands that affect locks, users, groups, and permissions;
these commands take effect immediately, even if the batch operation fails.
Enabling and disabling batch mode
To enable the batch mode execution of air commands, set the value
of AB_AIR_BATCH to true in the environment (not in a configuration file).

To begin accumulating air commands, specify air batch begin. Then include within the
batch sequence the commands you want to run in batch mode. Finally, specify air batch
end, which begins execution of the batched commands and produces output and errors, if
any. See “air batch commands”.

Note that the air commands executed when air batch end is run are collected in a temporary
file called .air-batch-commands in the current working directory. To specify a filename
other than the default, set AB_AIR_BATCH_FILE rather than AB_AIR_BATCH.
Set AB_AIR_BATCH_FILE in the environment, specifying the filename of your choice.

Here is an example of using batched commands:

export AB_AIR_BATCH=true
air batch begin
air rm /Projects/myproj/mp/graph1.mp
air rm /Projects/myproj/mp/graph2.mp
air batch end

Be sure to disable batch mode when the batch operation is done by doing one of the
following:

 Unset AB_AIR_BATCH or by set AB_AIR_BATCH to false.

 Unset AB_AIR_BATCH_FILE.

Certain commands cannot be batched

Certain commands, like air project import, cannot be batched. They run and commit,
regardless of whether they run in batch mode. Also, you cannot batch any commands that
take their arguments from standard input. See “Commands with repeatable arguments”.
Deprecated or disabled commands
Some commands and arguments have been deprecated, removed, or disabled. Deprecated
commands and arguments are obsolete and have been retained for backward compatibility
with older versions of the air utility. For a list of deprecated and removed commands and
arguments, see the Release Notes for the repository version you are running.
Commands with repeatable arguments
Although many air commands require you to supply the name of an object as an argument
(see “Specifying object names as arguments”), some air object and air project commands
have repeatable arguments that specify filenames, full technical repository paths, graphs,
and so on. These commands can take those arguments from the shell’s standard input rather
than from the command line. This strategy overcomes the platform-dependent limitations
on command length.

The commands with repeatable arguments are:

 air object save

 air project analyze-dependencies
 air project export
 air project import
 air project resolve-conflicts

For each of these commands you can specify the repeatable argument (such as -files), then
a single hyphen. The values for that argument are read from the shell’s standard input. The
format of the standard input file is a list of names, one per line.

If the assignment values are in a separate file, follow the hyphen by a left angle bracket (<)
and then the name of the file with the input data. For example, instead of listing at the
command line all the files to be imported by air project import, place the filenames
in import-list.txt:

air project import ... -files - < import-list.txt

NOTA:

You cannot use this feature within batch sequences starting with air begin batch.

Related topics

 Command groups
 Running commands in batch mode
 Deprecated or disabled commands

Specifying object names as arguments

The technical repository includes directory objects that provide names for other objects,
including other directories. You access these objects using Unix-like names. For
example, /a/b refers to object b in directory a.
Pathnames must begin with /, /~, or @
As is the case with Unix filesystems, a single object can be specified by multiple names, as
shown in the examples. A pathname must begin with one of these special characters:

 / (slash)
 /~abinitio (slash, tilde, and abinitio)
 @ (at sign)

After that, you separate elements of the path with / .

Rarely, name conflicts can arise for which you must specify a disambiguating
prefix between path elements.

Pathnames that begin with /

You almost always specify a name as a path beginning with a slash ( / ).

Refer to the following figure as you study the examples below:

Example 1

The name of the graph, mygraph.mp, in the project1 project is:

/Projects/project1/mp/mygraph.mp

Example 2
The name of the FILTER BY EXPRESSION component within mygraph can be accessed as:

/Projects/project1/mp/mygraph.mp/'Filter by Expression'

Note that quotes are required for embedded spaces within a pathname. Wildcards are not
supported in pathnames.
Pathnames that begin with /~abinitio
A pathname can begin with /~abinitio (a slash, a tilde (~), and abinitio). abinitio is the home
directory for Co>Operating System objects.

NOTA:

In the technical repository, /~ab_home is equivalent to /~abinitio.

Example

/~abinitio/2.14.7/Projects/root/components/Transform/Filter_by_Expression.mpc

Pathnames that begin with @

Every object has an object identifier, or OID. You can specify an OID as an argument to
an air command. OIDs often appear in error messages or in the output of
many air commands, such as air dump details. Use the OID as an argument when a
command’s output displays the OID.

An OID has the following form: @domain-number . objnum . version

Variable Description
domain- A unique number automatically assigned to a domain by the technical
number repository. To find an object’s domain number, run the air dump details or air
object ls -ld command.

A domain is a unit of storage in the repository. It consists of a group of related

objects. For example, a graph domain includes objects corresponding to the
graph’s components, flows, layouts, record formats, packages, fields,
dependencies, and so on. A domain includes all versions of the objects. In most
cases, a domain corresponds to a single file that is checked in to and out of a
repository.
objnum A unique number identifying an object within a domain. It is assigned by the
technical repository.
version Optional. A repository version number. The most current version of the
repository is specified by 0.
Example

The OID @123.45.62 means version 62 of object 45 within domain 123.

The root directory of the technical repository has the OID of @1.1.0 (or just @1.1). To
specify version 30 of common-customers.dml in project1, you can specify the OID relative
to the repository root plus the path to the object:

@1.1.30/Projects/project1/dml/common-customers.dml

Shortcut
A shortcut to the full OID specification of an object is one of these formats:

@version / object-pathOR @ tag / object-path

Examples

Specify version 30 of common-customers.dml in project1 as:

@30/Projects/project1/dml/common-customers.dml

If you want to see which version of an object is in a certain tag, use the @tag / object-
path specification.

Specify the version of common-customers.dml in project1 that is included in tag1 as:

@tag1/Projects/project1/dml/common-customers.dml

Examples of different ways to refer to a single object

The following examples illustrate some possible names for the FILTER BY
EXPRESSION component:

 /Projects/project1/mp/mygraph.mp/'Filter by Expression'
 /~abinitio/2.14.7/Projects/root/components/Transform/Filter_by_Expression.mpc
 @74.7.0
 @8.7.0/Transform/Filter by Expression

Specify a prefix to disambiguate names

Very rarely, name conflicts can arise. For example, it is possible that a graph could contain
a layout and a component having the same name. In this situation, specify a disambiguating
prefix between path elements.

These are the disambiguating prefixes:

Prefix Description
!name Annotation
d!name Element of a directory
f!name Flow in a graph
l!name Layout in a graph
m!name Metadata (record format) in a graph
v!name Component (also called vertex) in a graph
legend!number Legend in a graph
p!name Port of a component
e!name Element of a package
f!name Field of a record
Example 1

You can express /Projects/myeme/mp/mygraph.mp as:

/d!Projects/d!myeme/d!mp/d!graph.mp

Example 2

To access the value of the home_email record annotation rule:

/foo/bar/Mitzi/ann!email_info/ann!home_email

Example 3

To display the details of the PROJECT_DIR parameter of the warehouse project:

air details /Projects/warehouse/!PROJECT_DIR

Commands that are branch-specific or

repository-wide
The air commands operate either on a single branch or on the entire technical repository.
Generally speaking, the air commands that typical technical repository users are likely to
run are branch-specific — that is, the commands act only on a single branch, and the
objects acted upon have independent values on that branch.

In the case of purely administrative repository objects that cannot be specified by a

repository path (rpath), some are branch-specific and others are repository-wide. Typically,
those administrative objects that are useful to the average user (such as lock objects) are
branch-specific. In order to support developers who want to edit the same graph but on
different branches, the lock objects on different branches are independent. For procedural
information on using a branch, see “Connecting to a branch” in the Technical Repository
Guide to Version Control.

The following table identifies which air commands operate on a single branch or across the
technical repository:

Command(s) Behavior
air annotation group Branch-specific
air batch group Not applicable; use air batch commands only
with branch-specific commands
air branch group Branch-specific except for air branch creators
air branch creators Repository-wide; adminstrators only
air category group Branch-specific
air display group Branch-specific
air dump annotations Branch-specific

air dump arule

air dump category

air dump details

air dump domain-sizes

air dump domains

air dump internal

air dump objects

air dump files Repository-wide
air env manage-logs Branch-specific
air help group Not applicable
air lock group Branch-specific
air promote group Branch-specific
air purge object Repository-wide
Rest of air object group Branch-specific
Command(s) Behavior
air project group Branch-specific
air reposit group Branch-specific
air repository check-relations and air Branch-specific; administrators only
repository options
air repository trigger group Repository-wide
Rest of air repository group Repository-wide; administrators only
air sandbox merge Not applicable
air sandbox revert Branch-specific
air sandbox find-t3ext Branch-specific
air sandbox status Not applicable; external to technical repository
air system export users-and-groups Repository-wide; all of these pertain only to
users, groups, or the schema
air system import users-and-groups

air system install schema

air system group commands

air system show commands

air system user commands

Rest of air system install commands Branch-specific
air tag group Branch-specific

Commands that are local or remote

A few air commands only operate on a local technical repository. You cannot run these
commands remotely. In general, all air repository commands should be run locally;
other air commands can be run locally or remotely. For performance reasons, we
recommend that you run commands locally if they match at least one of the following
criteria:

 Transfer significant amounts of data (for example, when loading a large save file).
 Make several trips to and back from the technical repository (for example, when
unloading a large category such as a graph).
 The connection between the technical repository client and server is slow or has
high latency.

The following table identifies which air commands require a local technical repository:

Command(s) Location
air repository access-mode Local or remote
Command(s) Location
air repository backup Local or remote (if remote, the backup file is written
locally)
air repository check referential- Local or remote
integrity
air repository chmod Local or remote
air repository compress-diffs Local or remote
air repository convert-storage- Local
format
air repository create Local
air repository create-image Local
air repository destroy Local
air repository load-from-image Local
air repository online-backup cancel Local

air repository online-backup dump

air repository online-backup extract

air repository online-backup

monitor

air repository online-backup restore

air repository online-backup

schedule

air repository online-backup start

air repository online-backup verify

air repository rename Local
air repository restart Local
air repository revert Local or remote
air repository show Local or remote
air repository show-server Local or remote
air repository shutdown Local
air repository version-info Local or remote
Command aliases
The following (in alphabetical order) are the aliases for the air utility commands:
Full command Alias
air batch begin air begin-batch
air batch echo air echo
air batch end air end-batch
air display internal air show
air dump annotations air annotation dump
air dump arule air arule dump
air dump category air category dump
air dump details air details
air object access air access
air object cat air cat
air object changed air changed
air object chmod air chmod
air object chown air chown
air object cp air cp
air object load air load
air object ls air ls
air object mkdir air mkdir
air object mv air mv
air object poll-for-change air poll-for-change
air object rm air rm
air object save air save
air object versions air versions
air promote list air promote ls
air promote show-save-info air promote show-toc
air repository check referential-integrity air repository check-ri
air repository create-image air create-image
air repository load-from-image air load-from-image
air repository online-backup cancel air backup-cancel
air repository online-backup dump air backup-dump
air repository online-backup extract air backup-extract
air repository online-backup monitor air backup-monitor
air repository online-backup restore air backup-restore
air repository online-backup start air backup-start
air repository online-backup verify air backup-verify
air repository version-info air version-info
air repository tag air rtag
air sandbox run ab-run
air tag change-version air tag cv
air tag list air tag ls
Command return status codes
This section lists the return codes that the air commands can generate. Understanding these
codes can be useful for creating scripts that determine whether a command succeeded,
generated warnings, or failed.

Status
Meaning
code
0 The command succeeded
1 The command returned an error
2 The command returned a non-fatal warning

What do you want to do?

This section lists the air commands that help the Technical Repository
administrator and developer/project leader perform common tasks.
Administrator tasks
The following table lists the key Technical Repository administrator’s tasks and the
relevant air commands:

Task Command
Add data files to a technical repository air repository add-data-file
Back up a technical repository while it is active air repository online-backup
start
Back up a technical repository while it is shut down air repository backup
Change permissions on the technical repository air repository chmod
Copy a project to another technical repository air object save followed by air
(called promotion) object load
Rename a project air object mv
Move a technical repository to a different host air repository create-
image followed by air
repository load-from-image
Create a technical repository air repository create
Create a tag on a technical repository air repository tag
Create users and groups for a technical repository air system user create, air
system group create
Delete (purge) all repository objects as of a particular air purge repository
version
Delete (purge) individual repository objects at all versions air purge object
Enable or disable repository-based user authentication, file air repository options
Task Command
permissions, and auditing of air commands
Purge old, unwanted objects from the entire technical air purge repository
repository
Purge all versions of specific objects air purge object
Purge unwanted jobs from the technical repository air purge jobs
Reset a user’s lock air lock reset
Set a lock in the technical repository (object is not editable air lock set
in the sandbox)
Show whether file permissions, user authentication, and air repository options
auditing are enabled.
Show list of domains, their paths and sizes air dump domain-sizes
Show contents of a given domain air dump domain
Show information about the technical repository, including air repository show
the number of domains, connections, and branches; the
technical repository version and storage format
Show information about the current Technical Repository air repository show-server
server or all servers on the current machine
Developer and project leader tasks
The following table lists developer and project leader tasks and the relevant air commands:

Task Command
Add files to a project’s list of files air project add
Create a tag on a project air project import (during
checkin)
Create a tag on one or more objects air tag create
Check a sandbox or one of its files into a technical repository air project import
Check a project, graph, or file out from a sandbox air project export
Change the permission on an object in the technical repository air object chmod (or air
chmod)
Change the ownership of an object in the technical repository air object chown (or air
chown)
Delete the current version of an object from the directory but air object rm (or air rm)
leave it in the technical repository
Modify or reset a project’s attributes — for example, air project modify, air
extension list or common-project list project default
Set a lock in the sandbox (locked object is editable; air sandbox lock
permissions are modified in the sandbox)
Set an object’s MIME type air project set-type
Show directory contents air object ls (or air ls)
Show a project’s common projects air project show-common
Task Command
Show the state, path, MIME type and version of sandbox and air project files
project files
Show the files an object in a project depends on air project get-required-files
Show the files that are referenced by files in a sandbox air sandbox get-required-
files
Show a project’s attributes (for example, parameters, air project show
extension list, base directory)
Show all domains that have changed after a particular version air object changed
Show version numbers (and tags) of a given object air object versions (or air
versions)
Show internal details about an object, including its domain air dump details (or air
number and all its relationships details)
Show all objects that use a particular target object air object referencing-files
Show a list of objects in a given domain air dump objects
Show state of objects in a sandbox air sandbox status
Show top-level directory of a sandbox air sandbox find
Validate that a continuous graph will run correctly air sandbox validate-graph

air annotation commands

The air annotation commands display annotation rules and values. The following table
summarizes the air annotation group of commands. For information about command
syntax, see “Command-line syntax of air commands”.

Command Description
air annotation See air dump annotations.
dump
air annotation Runs an element-descriptor against an object and returns the path to the
eval values described by the view-descriptor on the object.
air annotation eval
Returns the path to the values described by a view-descriptor on an object. This command
is branch-specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.

Syntax
air annotation eval rpath element-descriptor
Argument Description
rpath Path to a repository object. The object must be a member of a category.
element- Specifies a view-element’s element-descriptor that is associated with the
descriptor object specified by rpath.
Usage
An element-descriptor is the portion of the view element that describes the values
associated with category members.

The command returns nothing if the object is not a member of a category.

Example
You want the rendered DF-Details view to show the steward responsible for a given data
file — that is, the value of the steward reference rule. The following figure presents this
situation:

You can express this view-element using the walk action:

air category add-view-element "Data Files" "DF-Details"\

-simple "Steward" "walk ('steward', 'Steward')"

To test the above view-element, run air annotation eval against a member of the Data
Files category — for example, the customers data file — and specify the view descriptor
beginning with the walk action:

air annotation eval /Projects/sales/dat/customers.dat \

"walk ('steward', 'Steward')"

Note that the walk action begins from the category on which the view is being defined.
The command should return /sg/Eric Smith.

air batch begin

Starts the accumulation of air utility commands for batch-mode execution.

The commands that are run in batch must all operate on the same repository and branch.
For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air batch begin
Usage
To enable batch mode, you must either set AB_AIR_BATCH to true or
set AB_AIR_BATCH_FILE to name a file to be used for collecting air commands.

For more information, see “Running commands in batch mode”.

Alias
The alias for this command is air begin-batch.
Example
Here is an example of using batched commands:

export AB_AIR_BATCH=true
air batch begin
air mkdir /lesson
...
more air commands
...
air batch end

air batch echo

Displays one or more messages during batch-mode execution.

The commands that are run in batch must all operate on the same repository and branch.
For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air batch echo arg ...
Argument Description
arg ... One or more strings that you want to be displayed during the batch run.
Alias
The alias for this command is air echo.
air batch end
Runs all accumulated air utility commands in batch mode and produces output of any
errors.

The commands that are run in batch must all operate on the same repository and branch.
For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air batch end -trace
Argument Description
-trace If specified, the queued-up commands are displayed as they are executed.
Alias
The alias for this command is air end-batch.

air branch commands

The air branch commands administer technical repository software branches. For
information about branches, see “Creating and managing release branches” in
the Technical Repository Guide to Version Control. For information about command
syntax, see “Command-line syntax of air commands”.

The following table summarizes the air branch commands:

Command Description
air branch create Creates a new branch.
air branch creators Adds, displays, or removes users and groups from the permissions list
that controls the ability of non-administrator users to create branches.
air branch delete Permanently deletes objects on a branch.
air branch freeze Freezes or unfreezes a branch or displays the status of a frozen branch.
air branch list Displays information about the objects and/or domains in a branch.
air branch modify Changes the name and title of the branch.
Command Description
air branch Changes the access permissions on one or more branches for the
permissions specified users or groups.
air branch show- Displays the access permissions for the specified branch or for all
permissions branches.
air branch create
Creates a new branch with the name new-branch-name from an existing branch (its parent
branch). For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air branch create new-branch-name
-from-branch parent-branch-name
[ -from-version parent-branch-version | tag ]
[ -title title] [ -quiet ]
Argument Description
new-branch-name Name of the new branch.
-from-branch parent-branch- Specifies the parent branch of the new branch new-branch-
name name. If omitted, creates a branch from main (the main
branch).
-from-version parent-branch If specified, the new branch is created from the specified
-version | tag version or tag. If omitted, the new branch is created from the
current version of the technical repository. See “Usage”
(next).
-title title If specified, gives a brief description (string) of the purpose
of the branch.
-quiet If specified, suppresses information about the newly created
branch.
Usage
You must have Technical Repository administrator privileges to run this command.

A valid branch name is limited to 50 characters. The name must contain alphanumeric
characters (a-z, A-Z, 0-9), hyphens, periods, and underscores; cannot consist of only digits;
and must be unique in the technical repository.

You may specify the versions of the objects from the parent branch in several ways:

 Specify a repository-wide version number.

  Specify a repository-wide tag (a symbolic name), such as one created by air
repository tag. These tags are called rtags. (For more information, see “Kinds of
tags” in the Technical Repository Guide to Version Control.)
 Specify a full tag (often called a vtag), such as one created by air tag create. A full
tag defines a collection of objects and the specific versions of those objects that you
want tagged.

The value of -title is limited to 150 bytes, which might be fewer than 150 characters,
depending on the character encoding you use. The title is visible in the GDE.

If the new branch is created from a tag, it contains all the objects at the tag version, with the
exception that the tagged objects exist in the new branch at the version specified in the tag.

For example, suppose you create a tag foo at version 100 of the technical repository. The
tag specifies version 80 of the bar.mp graph and version 90 of abc.dml. Then you create a
branch at tag foo. The new branch contains all the objects in the repository at version 100,
except for bar.mp and abc.dml, which will be at version 80 and version 90, respectively.
Example
To create a branch called mybranch off the latest version of the main branch and title
it Branch for Patch Release 3.3.2.14, enter the following:

export AB_AIR_ROOT=dev_eme
air branch create mybranch -title “Branch for Patch Release 3.3.2.14”

air branch creators

Adds, displays, or removes names of users or groups to the list that controls who can create
a branch in a technical repository. This command is repository-wide. For information about
the arguments common to all air commands, see “Command-line syntax of air commands”.

NOTA:

This command requires technical repository storage format 18 or higher. You must have
Technical Repository administrator privileges to run this command.

Syntax
air branch creators
{[-add | -remove ] user-list } ...
[-quiet ]
[-show ]
Argument Description
-add | -remove Adds or removes the users or groups specified by user-list to the
access control list — thereby granting or denying the ability to
create branches. You can omit -add if it is the first argument, and
supply only the username.
user-list | group A list of users or groups for which you want to add or remove the
=group-name ability to create branches. Separate multiple users with a space.
Specify groups as group=group-name.
-quiet Does not display the list of creators after the command executes.
-show Displays the list of creators after the command executes. The
default.
Usage
You cannot add or remove a Technical Repository administrator from this list. Once you
have added a user or group to the access control list, you can refine their access permissions
on objects on the branch by using the air branch permissions command.
Example
The following command adds two users, user_sue and user_ravi, and the group lead-
developers to the access list — thereby granting them permission to create branches. The
example also removes user_pete from the list. This example illustrates that the -
add argument can be omitted if the first value (in this case, user_sue) is intended as an add:

air branch creators user_sue group=lead-developers -remove user_pete -add user_ravi

Related topics

 air branch permissions

 air branch show-permissions

air branch delete

Permanently deletes every object on the specified branch and eliminates administrative
information that is associated with this branch. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.

NOTA:

To run this command, you must have Technical Repository administrator privileges or —
for storage format 18 and higher — control access on the branch that you want to delete.
Syntax
air branch delete branch-name ... [-no-confirm]
Argument Description
branch-name Name of the branch to be removed. You can enter multiple branch names
separated by a space.
-no-confirm If this argument is specified, the command is executed without prompting
for confirmation.
Usage
 Co>Operating System Version 3.0.5 and later support multiple branch deletion. To
delete multiple branches simultaneously, separate the branch names by a space.
Co>Operating System Version 3.3.2 and later support user deletion of branches as
appropriate.
 You cannot delete the main branch of development or a branch that has child
branches.
 This command allows you to reclaim the disk space and the branch ID number.

air branch freeze

Freezes or unfreezes a branch or displays the status of a frozen branch. For information
about the arguments common to air commands, see “Command-line syntax of air
commands”.

NOTA:

To run this command, you must have Technical Repository administrator privileges or —
for storage format 18 and higher — control access on the branch that you want to freeze.

Syntax
air branch freeze branch-name
{-freeze|-unfreeze|-admin |-status}
Argument Description
branch-name Name of the branch to be frozen or unfrozen. You can
enter multiple branch names separated by a space.

You do not need to enter the -branch argument for the

first branch name that you specify.
-freeze |-unfreeze |-admin |-status You must choose one of the following:

 -freeze makes the branch read-only by all users.

 -unfreeze makes the branch writable by all
Argument Description
users.
 -admin makes the branch writable by the
Technical Repository administrator but read-
only by all other users.
 -status displays the status of the
branch: frozen means that the branch is read-
only, admin means that the branch is writable
only by Technical Repository administrators,
and open means that the branch is writable by
all users.

Usage
A frozen branch is one that is read-only. A branch can be frozen to all users, to all users
except the Technical Repository administrator, or to some users as indicated through the
control access list created with the air branch creators command.
air branch list
Displays information about the objects and/or domains in the specified branch or all
branches, either in a one-line record for each branch or in a DML-parsable format. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air branch list
[branch-name]
[-tabular | -record | -dml]
[-domains-versions]
[-children]
Argument Description
branch-name Optional. Name of the branch that you want to view information
about. If omitted, displays information for all branches, one
branch per line.
-tabular | -record | -dml Optional. If specified, describes the format of the output. Choose
one of these:

 -tabular (default) is a table format, one object per row,

fields space-separated and aligned with column headings.
 -record is a record format, one per line, fields separated by
a vertical bar.
 -dml outputs the DML for the -record output format.
Argument Description
-domains-versions Optional. If specified, gives more detailed information about
which versions of which objects (labeled by domain number) are
used in branching from the parent branch.

Applies only to branches where a full tag was used.

-children Optional. If specified, displays the child branches of branch-
name instead of branch-name itself.
Usage
You must have Technical Repository administrator privileges to run this command.

Be aware that the -domains-versions option may generate millions of pairs of numbers if
full tags were used and cover large portions of the technical repository. It may also take
many minutes to process.

The branch ID in the output is an internal, automatically assigned identification number.

The ID of the main branch is 0.
Example
Running air branch list for branch release1 might yield the following tabular output. It
shows that release1 was created from version 51 (the FROM_VERSION column) on
the main branch and that the version when air branch create was run (the created column)
was 80:

NAME FROM FROM_VERSION CREATED CREATION TIME ID

main None 51 51 2016-05-07 15:48:06 1

release1 main 51 80 2016-07-09 17:10:12 1
release2 main 82 85 2016-08-01 20:10:23 1

The value in the FROM_VERSION column is the value of the -from-version argument
when air branch create was executed. The value in the CREATION_TIME column is the
time when the version number in the CREATED column was created.

air branch modify

Allows you to change the title, name, and owner of a branch. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.

NOTA:
To run this command, you must have Technical Repository administrator privileges or —
for storage format 18 and higher — control access on the branch that you want to modify.

Syntax
air branch modify
branch-name
[-title title]
[-name name]
[-owner owner]
Argument Description
branch-name Name of an existing branch that you want to modify.
-title title Supplies a new title (a brief description of the branch’s purpose).
-name name Specifies a new name for the branch. See Usage information below.
-owner owner Specifies the owner of the branch. The branch owner can modify or delete a
branch, as well as change its access permissions. To use this argument, the
technical repository must be at storage format 18 or higher.
Usage
The value of -title is limited to 150 bytes, which might be fewer than 150 characters,
depending on the character encoding you use.

The branch ID number cannot be changed.

If you change the branch name, any sandboxes attached to this branch must be detached
and then checked out again using the new branch name. For this reason, we do not
recommend changing the names of branches.
air branch permissions
Changes the access permissions on one or more branches for the specified users or groups.
For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.

NOTA:

This command requires storage format 18 and higher. To run this command, you must have
Technical Repository administrator privileges or control access to the branch whose
permissions you want to modify.

Syntax
air branch permissions {[-branch] branch-name ...
 {permissions user-list} ... }
[-quiet]

Argument Description
-branch branch-name Specifies the name of one or more branches whose access
permissions you want to modify. To enter multiple branch names,
you must precede each name by the -branch argument. You do not
need to enter the -branch argument for the first branch name value
that you specify.
permissions Specifies whether the user or group can read, write, or modify
objects on the branch, as follows:

 +read — Grants the user or group read access to objects on

the branch.
 -read — Denies the user or group read access to objects on
the branch.
 +write — Grants the user or group write access to objects
on the branch.
 -write — Denies the user or group write access to objects
on the branch.
 +control — Grants the user or group the ability to modify,
delete, and freeze the branch, and to change its permissions.
 -control — Denies the user or group the ability to modify,
delete, and freeze the branch, or to change its permissions.

The highest permission assigned to a user or group applies to it. For

example, if you specify both +read and +write, the more
privileged +write permission will apply.
user-list | group A list of users or groups whose branch permissions you want to
=group-name change. Separate multiple users with a space. Specify groups
as group=group-name.
-quiet Does not display the new permissions for the modified branches.
Usage
The default permissions are that only a Technical Repository administrator or the owner of
a branch can modify or delete it. All other added users have write access to the branch. You
can display the current permissions for specific or all users and groups by using the air
branch show-permissions command.
Examples
This example assigns control permissions on the branch dev-branch1 to the user test-user. It
also assigns write access to all the users contained in the group dev-group14, as follows:
air branch permissions dev-branch1 +control test-user group=dev-group14

This example removes control permissions on the branch dev-branch1 from the user test-
user, and removes write access from the user user2 on the branch dev-branch12, as follows:

air branch permissions dev-branch1 -control test-user -branch dev-branch12 -write user2

The user user2 will now have no access to the branch dev-branch12. If you want them to
have read access instead, you must specifically grant it.

Related topics

 air branch creators

 air branch show-permissions

air branch show-permissions

Displays the access permissions for the specified branch or for all branches in the technical
repository. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.

NOTA:

To run this command, you must have Technical Repository administrator privileges or —
for storage format 18 and higher — control access on the branch that you want to delete.

Syntax
air branch show-permissions {branch-name ... | -all}
Argument Description
branch-name ... Specifies the name of the branch whose permissions you want to show.
You can enter multiple branch names separated by a space.
-all Specifies that you want to show permissions on all of the branches. This is
the default.
Example
This example displays the permissions for the branches release-4-0-2 and release-4-1-1, as
follows:
air branch show-permissions release-4-0-2 release-4-1-1

Related topics

 air branch creators

 air branch permissions

air category commands

The air category commands display information about a category and lists category
members. For more information about categories, see “Technical Repository schema
reference” in the Technical Repository Administrator’s Guide.

The following table summarizes the air category commands. For information about
command syntax, see “Command-line syntax of air commands”.

Command Description
air category dump See air dump category.
air category list- Displays the members of a given category.
members
air category dump
This command is an alias for air dump category.
air category list-members
Displays the members of the specified category. This command is branch-specific. For
information about the arguments that are common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air category list-members [-m] category [filter-rpath ...]
Argument Description
-m Writes the command output in new-line delimited machine-readable format to
standard output. The output does not include indentation or any header and
trailer information, such as the total number of members shown.
category Name of an existing category.
filter- Lists only members that are contained within the specified repository locations.
rpath ...
Examples
To see a list of members in the package category, type:

air category list-members package

The output might be similar to the following:

/Projects/program_datasets/dml/format.dml
/Projects/pr14567/run/output_file.dml
/Projects/pr14567/dml/purchases.dml
/Projects/pr14567/dml/output_file.dml
/abinitio/categories/package has 4 members.

The following example uses the -m argument to print the members of the package category
in machine-readable form. It does not contain indentations nor the summary line that are
shown in the previous example.

air category list-members -m package

/Users/bawana/component-ref/data/daily_cust_report.dat/metadata/type
/Users/bawana/component-ref/data/cust_purchases.dat/metadata/type
/Users/bawana/component-ref/data/report3.dat.dataset/metadata/type
/Users/bawana/component-ref/data/report2.dat.dataset/metadata/type
...

The following example shows machine-readable output for the package category that is
limited to only the /Projects/error_arch/dml repository location:

air category list-members -m package /Projects/error_arch/dml

/Projects/error_arch/dml/simple_reformat_make_error.dml
/Projects/error_arch/dml/simple_reformat_out.dml
/Projects/error_arch/dml/simple_reformat_output_for_error.dml

air display command

The air display command displays the structure or contents of a repository object. The
following table summarizes the air display group of commands. For information about
command syntax, see “Command-line syntax of air commands”.
Command Description
air display internal Displays the structure of a repository object in text.
air display internal
Displays the structure of a repository object in text form. This command is branch-specific.
For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air display internal rpath
Argument Description
rpath Path to the repository object whose structure you want to display.
See “Specifying object names as arguments”.
Usage
This command produces a very detailed listing. It is included so that Ab Initio staff can
troubleshoot problems.
Alias
The alias for this command is air show.

air dump commands

The air dump commands produce human-readable reports of repository data structures. The
following table summarizes the air dump commands. For information about command
syntax, see “Command-line syntax of air commands”.

Command Description
air dump Displays all annotation rules and values (if any) for a category
annotations member.
air dump arule Displays information about the specified annotation rule.
air dump category Displays information about the specified category.
air dump details Displays a single repository object.
air dump domain Display the contents of a given domain, optionally, as of a specific
version.
air dump domain- Displays a list of domains and their paths in the technical repository,
sizes sorted by size.
air dump domains Reports storage usage per domain.
air dump files Lists storage usage per data file.
air dump internal Displays the technical repository contents.
Command Description
air dump objects Prints a listing of objects in a domain.
air dump annotations
Displays all annotation rules and values (if any) for a member object of a category. This
command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.

NOTA:

This command is primarily for use by Ab Initio personnel.

Syntax
air dump annotations [-reverse] rpath [-as_xml [-complete] ] [-category
category]
Argument Description
-reverse Displays all the objects that have the specified object, rpath, as
an annotation value.
rpath Path to a repository object whose annotation rules and values you
want to display.
-as_xml [-complete] Formats the object specified by rpath as XML. When the
optional -complete is specified, also displays in XML all the
objects that reference rpath or are referenced by rpath.
-category category Retrieves the annotation rules and values for category.
Usage
The output displays “permission denied” if you do not have permission to view an
annotation rule.

Because you can set annotation rule permissions on an individual category, specifying
different values of category may allow you to view different information about an object.

You can control the display of the date and time values by setting
the AB_ARULE_USE_LOCAL_TIME configuration variable.

The -category category optional argument has no effect on the set of objects returned when
you specify -as_xml -complete.

For information about annotations rules and annotation values, see “Technical Repository
schema reference” in the Technical Repository Administrator’s Guide.
Alias
The alias for this command is air annotation dump.
Example
To display the annotation rules and values for graph1, type the following:

air dump annotations /Projects/myproject/mp/graph1.mp

If graph1 is a member of the Application category and if Application is based on the built-
in graph category, this command displays all the rules and values for graph1 and then all
the rules and values for Application.

For example, you might see the following output. These annotation rules are single-valued.
If no value follows the name of the annotation rule name, as in the version rule, the value is
unset:

graph: -----------------------------------
oid: 0232.1.0
name: /Projects/myproject/mp/graph.mp
comment:
description: Accounts Receivable App
display_name: My Graph
CreatedBy: S Finkel
CreationDate: 3/1/2016 16:19:10
ModifiedBy: S Finkel
ModifiedDate: 5/2/2016 14:20:07
categoryOID: 0052.1.1
path: /Projects/myproject/mp/graph1.mp
author: Ab Initio Software Corp
version:
Application : ----------------------------
business_area: Finance
steward:

air dump arule

Displays information about the specified annotation rule. This command is branch-specific.
For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air dump arule arule
Argumen
Description
t
arule Name of an existing annotation rule.
Usage
For all annotation rules, the output displays the rule’s display name, default value, whether
it can be edited, and whether it takes a single value or multiple values.

For choice rules, the output also displays the rule’s choice list, whether values can be added
to the choice list, and whether users must choose values from a predefined list.

For reference rules, the output also displays the name of the rule’s target category.

In the output, 1 means yes and 0 means no.

For information about annotations rules and annotation values, see “Technical Repository
schema reference” in the Technical Repository Administrator’s Guide.
Alias
The alias for this command is air arule dump.
Examples
Displaying information about the abbreviation rule
To display information about the abbreviation rule, type the following:

air arule dump abbreviation

The following output shows that abbreviation is a string rule, has no default value, can be
edited, but cannot take multiple concurrent values:

/abinitio/annotation rules/abbreviation
string rule ------------------
display name: abbreviation
default value:
datatype: STRING
can edit: 1
multi-value: 0
revert-on-edit: 0

Displaying information about the ApprovalStatus rule

To display information about the ApprovalStatus rule, type the following:
air arule dump ApprovalStatus

The following output shows that Approval_Status is a choice rule whose name is displayed
as Approval Status. It has no default value, can be edited, and can take only one value
chosen from a predefined list (approved, pending, initial load, and defaulted). Users cannot
add choices to the list.

/abinitio/annotation rules/ApprovalStatus
choice rule ------------------
display name: ApprovalStatus
default value:
datatype: STRING
can edit: 1
multi-value: 0
revert-on-edit: 0
in_list: 1
add_choice: 0
choices: Pending
Approved
Other

air dump category

Displays information about the specified category, including its technical repository
location, its parent category, the repository location of its members, its annotation rules,
and its views and constituent view-elements. This command is branch-specific. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air dump category category
[-no-member-locations]
[-parent]
[-view-names]
[-rules]
[-locations]
[-views view-name ... ]
Argument Description
category Name of an existing category.
-no-member- Displays the count of member locations instead of listing the actual
locations locations. Useful when showing information on subrecords, which may
produce extensive output.
-parent Displays the parent of the specified category.
-view-names Displays the names of the views of the specified category.
-rules Displays the annotation rules of the specified category.
-locations Displays the member locations of the specified category.
-views view- Displays the definition of view-name. Separate multiple view names with
name ... spaces. If omitted, all views defined on the specified category are shown.
Usage
For general information about categories, see “Technical Repository schema reference” in
the Technical Repository Administrator’s Guide.
Alias
The alias for this command is air category dump.
Examples
Displaying a graph’s annotation rules and parent category
To see only the graph’s annotation rules and parent category, type the following:

air dump category graph -rules -parent

Displaying all information about a category

To see all information about the graph category, do not specify the
arguments -parent, -view-names, -rules, -locations, or -views. Instead, specify just the
category name:

air dump category graph

The resulting display is similar to the following:

/abinitio/categories/graph
Parent category -------------------:
object (base category)
 Member locations ------------------:
Inherit via rule------------------:
usedAsComponentByOID
Inherited Annotation Rules --------:
oid (via object)
path (via object)
name (via object)
comment (via object)
description (via object)
display_name (via object)
created_by (via object)
creation_date (via object)
modified_by (via object)
modification_date (via object)
projectOID (via object)
categoryOID (via object)
DOCOID (via object)
Annotation Rules ------------------:
author: not required, don't inherit values
version: not required, don't inherit values
datasetsReadOID: not required, don't inherit values
datasetsWrittenOID: not required, don't inherit values
usedAsComponentByOID: not required, don't inherit values
Annotation Rules Referencing ‘graph’ ---:
graph.usedAsComponentByOID
vertex.graphOID
flow.graphOID
job.graphOID
job.versionedGraphOID
SFD Application.prototypeGraphOID
Views -----------------------------:'details' [bin-style
: none, icon : ''] elements:
Project: (simple) /|graph/.projectOID/>
+index -display-contents -vertical-
layout -no-wrap -hide-label
Comment: (simple) /|graph/.comment/>
+index -display-contents -vertical-
layout -no-wrap -hide-label
Last Modified On: (simple) /|graph/.modification_date/>
+index -display-contents -vertical-
layout -no-wrap -hide-label
Last Modified By: (simple) /|graph/.modified_by/>
+index -display-contents -vertical-
layout -no-wrap -hide-label
Components: (view) /<vertex/.graphOID/| list
-index -auto-show +can-toggle
Jobs: (view) /<job/.graphOID/| list
-index -auto-show +can-toggle
Lookups Used: (view) /<vertex/.graphOID/|/|vertex/
 .lookupsUsedOID/> list
-index -auto-show +can-toggle
Datasets Read: (view) /|graph/.datasetsReadOID/> read-list
-index +auto-show +can-toggle
Datasets Written: (view) /|graph/.datasetsWrittenOID/> written-list
-index +auto-show +can-toggle
Tags: (view) inv_walk("taggedObjectsOID", "tag") list
-index -auto-show +can-toggle
'list' [bin-style : none, icon : ''] elements:
Name: (simple) /|graph/.name/>
+index -display-contents -vertical-layout
-no-wrap -hide-label
Project: (simple) /|graph/.projectOID/>
+index -display-contents -vertical-layout
-no-wrap -hide-label
Description: (simple) /|graph/.description/>
+index -display-contents -vertical-layout
-no-wrap -hide-label

In this example, note the following:

 Parent category displays the name of the category from which graph is derived
— object.
 Member locations displays the technical repository location of the objects that are
members of graph.
 Inherited Annotation Rules displays those rules inherited from the parent categories.
 Annotation Rules displays those rules that are local to the dumped category, graph.
 Annotation Rules Reference category displays the annotation rules of other
categories that refer to this category.
 Views displays the names and definitions (view-elements) of the views defined
on graph.

air dump domain-sizes

Displays a list of domains and their paths in the technical repository, sorted by size. This
command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air dump domain-sizes
[-single domain-number] [-quiet]
[-storage] [-versions] [-no-names] [-no sort]
 [-m] [-dml]
Argument Description
-single domain- Displays information only for the specified domain, domain-number.
number
-quiet Does not display progress reports to stderr.
-storage Displays the total storage used for the domain.
-versions Displays the number of versions of the domain.
-no-names Does not display the names or paths of the domains.
-no sort Does not sort the domains by size.
-m Writes the command output in machine-readable format to standard
output.
-dml Displays the current record format for domain sizes. Exits without
displaying domain size output. For machine-readable output, you can
run the command with the -m option. (All other arguments are ignored.)
The record format is useful for processing output in a graph.
See “Usage”.
Deprecated arguments
In Version 2.16.1, -verbose, -entities, and -relations have been removed.
Usage
Orphan domains, such as 239 and 350 (as shown in the example, “Displaying the sizes of
all domains”), are identified by the domain OID. The message <not found> means the
domain has been removed.

You can use the DML record format in a graph to analyze domains you are interested in.
For example, you can write a graph that uses the object name or domain number to
compare a technical repository at three different points in time: this week, last week, and
two weeks ago. The graph could return information on the domains that grew the most or
ones that were removed.
Examples
Displaying the sizes of all domains
Here is an excerpt of output of air dump domain-sizes:

Total size: 4122488 bytes

size domain path
---- ------ ----
103600 35 /abinitio
102548 34 <XXGschema>
102308 33 <XXGschema>
42828 82 /abinitio/default/.mp-map/documentation
32440 113 /abinitio/default/.mp-map/partial-sort
26260 429 /Projects/sample/dat/consumer-info
25860 431 /Groups/world
24300 426 /Projects/sample/dat/b-customers
20316 68 /abinitio/default/.mp-map/db-runsql
18868 430 /Projects/sample/dat/joined-customer-data
17824 428 /Projects/sample/dat/common-customers
15868 425 /Projects/sample/dat/a-transactions
15504 103 /abinitio/default/.mp-map/load-level-partition
15388 123 /abinitio/default/.mp-map/roundrobin-partition
15120 131 /abinitio/default/.mp-map/select-transform
14456 101 /abinitio/default/.mp-map/interleave
14180 121 /abinitio/default/.mp-map/rollup-transform
14060 129 /abinitio/default/.mp-map/scan-transform
13928 80 /abinitio/default/components/Transform/1.3
8672 260 /abinitio/examples/datasets/fixed
8612 263 /abinitio/examples/datasets/unix-text
8236 76 /abinitio/default/.mp-map/db_old_update
8060 257 /abinitio/examples/datasets/delimited
7900 265 /Users
7620 45 /abinitio/default/components/Transform
7296 72 /abinitio/default/.mp-map/m_dbload
7240 111 /abinitio/default/.mp-map/normalize-transform
7228 48 /abinitio/default/components/Miscellaneous
6776 145 /abinitio/categories/dataelement
6596 152 /abinitio/categories/flow_summary
6344 174 /abinitio/annotation rules/_value
6296 173 /abinitio/annotation rules/categoryOID
6284 168 /abinitio/annotation rules/display_name
6284 169 /abinitio/annotation rules/created_by
6284 171 /abinitio/annotation rules/modified_by
6284 172 /abinitio/annotation rules/modification_date
5540 149 /abinitio/categories/job
...
5504 354 /abinitio/categories/Database
5344 397 /Projects/sample/.repository-state
5188 151 /abinitio/categories/vertex_summary
5136 153 /abinitio/categories/category
4960 144 /abinitio/categories/dataset
...
4952 361 /abinitio/categories/Column
4908 142 /abinitio/categories/mimeobj
4792 277 /abinitio/reports/XXGgraph/dml_detail
4728 158 /abinitio/categories/type
4612 239 @239.1.0
4612 350 @350.1.0
4556 387 /abinitio/rule_types/FLOAT
4548 157 /abinitio/categories/package
4544 160 /abinitio/categories/transform
4544 163 /abinitio/annotation rules/oid
4504 143 /abinitio/categories/database
3628 433 <not found>

Displaying the size of a single domain

This example shows how to display the size of a single domain:

air dump domain-sizes -single 1904

size current domain class path

---- ------- ------ ----- ----
64,452 376 1904 <unknown> @1904.1.0

Displaying a domain’s DML record

This example shows how to display machine-readable output of the domain’s DML record:

air dump domain-sizes -m -dml

record
decimal(' ') domain;
decimal(' ') total_size;
decimal(' ') current_size;
decimal(' ') storage_size;
decimal(' ') num_versions;
string(' ') class_name;
string('\n') path;
end

Syntax
air dump domains
air dump files
Displays a listing of the storage usage for each data file. This command is repository-wide.
For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air dump files
Example
Running air dump files on the mart project yields the following output:

-rw------- 1 matt 8976768 Mar 3 11:01 mart.dat.000

-rw------- 1 matt 9175820 Mar 3 12:45 mart.dat.001
-rw------- 1 matt 8946280 Mar 3 11:01 mart.dat.002
...

air dump internal

Displays a text report on or a summary of the contents of the specified technical repository.
This command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air dump internal [-no-detail] domain [-info]
Argument Description
-no-detail Suppresses details about entities.
domain Specifies the name or numeric identifier of the domain to be displayed.
-info Displays summary information about the specified domain (the number of
entities and relations and size) rather than the full text report.
air dump objects
Prints a listing of all objects in the specified domain. This command is branch-specific. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air dump objects [-path rpath | -domain domain-number]
Argument Description
-path rpath Path to the repository object, or object ID. See “Specifying object
names as arguments”. If omitted, a listing of all objects is displayed.
-domain domain- A 32-bit unsigned number that is automatically assigned by the
number technical repository. If omitted, a listing of objects in all domains is
displayed.
Usage
To find the domain number of an object, run air dump details.

air env commands

The air env commands manage logs and similar files. The following table summarizes
the air env group of commands. For information about command syntax, see “Command-
line syntax of air commands”.

Command Description
air env create-env- Creates, in advance, empty environment operations log files for a
logs specified number of months.
air env manage- Lists or deletes sandbox log files to assist with archiving or reclaiming
logs disk space.
air env create-env-logs
Creates, in advance, empty environment operations log files in $
{AI_ENV_LOG_HOME} for the number of months that you specify. The files are
named environment_operations_YYYY_MM.log, and will later be populated with
administrative, source control, job start, and job end events. This command is branch-
specific.
Syntax
air env create-env-logs [-months num_months]
Argument Description
-months num_months Specifies the number of months to create empty log files for, starting
with the current month. The default is 3; that is, the current month
plus two additional months.
Usage
By default, monthly environment logs are automatically created and owned by the user who
creates the first job each month. For some installations this can cause permissions problems
for other users who try to view the files. To avoid that issue, use this command to create
logs in advance for a specified number of months in the future — those log files will then
be owned by the appropriate user account (usually an Ab Initio Environment
administrator).

If a file already exists, the command ignores it. For example, if it is February 2015 and the
value of num_months is 2, and environment_operations_2015_02.log file already exists, the
command will create only environment_operations_2015_03.log. It will not attempt to
create environment_operations_2015_02.log because that file already exists.
There is no limit on the number of months that you can enter. If you do not reissue this
command when the number of chronological months specified is reached, log generation
reverts to the default behavior — that is, the log file is created and owned by the user who
first runs a job in a given month.
air env manage-logs
Lists or deletes sandbox log files to assist with archiving or reclaiming disk space.
Technical repository administrators can use this command to identify and then archive or
remove log files that accumulate in the AI_ADMIN directory or one of its subdirectories. It
can also be used by graph developers to archive or remove logs in one or more sandboxes.
You can use pattern matching or dates, including date ranges, to locate log files.

This command is branch-specific. For information about the arguments common to

all air commands, see “Command-line syntax of air commands”. For more information on
the AI_ADMIN directory, see ““admin subdirectory”” in the Co>Operating
System Administrator’s Guide and Reference.
Syntax
air env manage-logs { -delete | -list }
[-force]
[-before date | -days-old days-old]
[-after date]
[-proj path | -sand-root path | -files-below path]
[-log-dir name]
[-filename graph | pset| plan]
Argument Description
-delete | -list Specifies whether to display a list to stdout or delete log files. The
command searches in the current directory, unless a path is
specified through additional command arguments. For more
information on using the -list argument for archiving files,
see “Archiving files”.
-force Deletes any read-only files. This argument is ignored except
when used with the -delete argument.
-before date | -days-old Limits the list or deletion as follows:
days-old
 -before — Limits the list or deletion to logs created before
the date supplied. Specify a date in this format:

YYYY-MM-DD

 -days-old — Locates files created since the specified

number of days that have passed before today.
Argument Description
-after date Limits the list or deletion to logs created after the date supplied.
Use with the -before argument to create a date range.
-proj path | -sand-root p Specifies a project, filesystem directory, or sandbox to search as
ath | -files-below path follows:

 -proj — Specifies a sandbox path. Useful for graph

developers.
 -sand-root — Specifies a filesystem directory and all
sandboxes found under that directory. If no sandboxes are
found, the command displays an informational message.
Useful for graph developers.
 -files-below — Specifies a filesystem directory and
searches for log files in the directory and any
subdirectories. Useful for technical repository
administrators who may not know the names of all the
relevant sandboxes.

When no argument is used, the default is to search upward until a

sandbox is found. If no sandbox is found, the command generates
an error.
-log-dir name Limits which files will be listed or deleted. The default is to
process all log files. This argument supports the following values:

 error — Files in error directories.

 log — Files in log directories.
 parameter — Files in pset directories. If -files-below is
used, this value includes .pset and .penv files.
 summary — Files in the summary directories.
 tracking — Files in the tracking directories. These
directories may be specified by configuration variables.
If -files-below is used, this value includes .tracking, .dom,
and .xml files

The presence of the -files-below argument influences the search

method that the command uses. For more information,
see “Usage”.

NOTA:

This argument does not include the $

{AI_ENV_LOG_HOME}/environment_operations_YYYY_MM.lo
g files, even if you provide the log value.
-filename graph | pset | Specifies what to list or delete by matching the pattern that you
plan provide, as follows:
Argument Description

 graph — An Ab Initio graph

 pset — An input parameter set file
 plan — A Conduct>It plan

For more information on pattern matching, see “File searching

details”.
Usage
Use of the -files-below argument influences how the filesystem is searched. Because this
argument targets the specified filesystem directory, it can be useful for removing or
deleting files when you do not know the names of the sandboxes the directory contains.

NOTA:

If you have previously overridden the default definition of

the AI_LOG_PREFIX abenv project parameter, using this command will cause
unpredictable results.

File searching details

This command searches for files matching the following AI_LOG_PREFIX abenv project
parameter pattern:

graphname_filedate_processID

The -files-below argument creates a list of files — for display or deletion — based on the
project parameter pattern. The list includes the following file extensions:

 .dom — Conduct>It files

 .err — Error logs
 .log — Process logs
 .pset — Input parameter set files
 .penv — Parameter archive files
 .sum — Deployed graph summary report files
 .tracking — Graph job tracking files
 .xml — XML files used by the Control>Center.
 ${AI_ENV_LOG_HOME}/environment_operations_YYYY_MM.log —
Administrative and source control events, job start and end events

The -proj, -sand-root, and default arguments create a list of files based on the project
parameter pattern. The list includes these file locations and extensions:

 $AI_ADMIN_TRACKING/${AI_LOG_PREFIX}.dom — Conduct>It files

  $AI_ADMIN_ERROR/${AI_LOG_PREFIX}.err — Error logs
 $AI_ADMIN_LOG/${AI_LOG_PREFIX}.log — Process logs
 $AI_ADMIN_PARAM/${AI_LOG_PREFIX}.pset — Input parameter set files
 $AI_ADMIN_PARAM/${AI_LOG_PREFIX}.penv — Parameter archive files
 $AI_ADMIN_SUMMARY/${AI_LOG_PREFIX}.sum — Deployed graph summary
files
 $AI_ADMIN_TRACKING/${AI_LOG_PREFIX}.tracking — Raw tracking files
 $AI_ADMIN_TRACKING/${AI_LOG_PREFIX}.xml — XML files
 ${AI_ENV_LOG}/environment_operations_YYYY_MM.log — Administrative and
source control events, job start and end events

NOTA:

The command resolves parameters in the context of each sandbox.

Archiving files
The -list argument displays full absolute filenames to stdout. You can use grep, pipe, or
other standard input commands with tar or gzip to archive the actual files.

air help command

air help displays online documentation for individual air commands and groups
of air commands. For information about command syntax, see “Command-line syntax of air
commands”.

Command Description
air help Displays online documentation for air commands.
air help
Displays documentation for commands.
Syntax
air help [command]
Argument Description
command Optional. The name of a group of commands or a specific
command.
Top-level help command
Typing air help without command produces output that explains the options that apply to
all air commands. For information about these options, see “Command-line syntax of air
commands”.
Using air help on a group of commands
The air help command allows you to drill down into groups of related commands. Specify a
group name, like object or project, as command.
Example
To see all the commands in the air object group, type:

air help object

You see a description of air object and a list of all object commands and their parameters:

air object - Manipulates EME technical repository objects

This group of commands is used to manipulate objects and

directories of objects.

The following commands are available:

air object access <rpath> {r|w|x|f}

air object cat <rpath>
air object changed [rpath ...]
[-root1 <eme1>] [-branch1 <branch1>] [-version1 <v1>|<tag1>]
[-root2 <eme2>] [-branch2 <branch2>] [-version2 <v2>|<tag2>]
[-show-all] [-tagged-only]
[-diff [-terse | -verbose] [-ignore-param-order] [-text]
[-ignore-dep-analysis] [-original-format]]
[-m] [-dml]
.
.
.
air object versions [-quiet | -no-tags | -checkins | -no-tags -checkins]
[-descending | -ascending]
[-user <username> [-user <username2>...]]
[-branch <branchname> [-branch <branchname2>...]]
[-versions-only]
[<rpath>]
[<version-range>]

Using air help on a specific command

You can also display documentation for a specific command within a group. Specify a
specific command name as command.
Example
To display documentation for the air object cp command, type:

air help object cp

You should see:

Usage: air object cp <rpath1> <rpath2>

Copies the object at <rpath1> in the repository to <rpath2>, retaining

links to any other objects it references. If <rpath2> exists, it is
overwritten.

rpath1 Path to a repository object, or object ID, to be

copied. <rpath1> cannot be a directory.

rpath2 New repository path for the copied object.

Notes
To copy a directory, consider using air object save and air object load
with the -relocate option.

Deprecated arguments
-R was deprecated in Version 2.14.

air lock commands

The air lock commands manage locks to prevent file collision. They allow you to set and
release locks on repository objects, break other users’ locks, and see a listing of all current
locks. Although locking and unlocking are normally handled in the GDE, the air
lock commands are available for administrative intervention — when, for example, a lock
must be broken. For information about locking in the GDE, see “Bloquear y editar
archivos” in the Guía para desarrolladores de grafos. For information about locking in the
Technical Repository Management Console (TRMC), see the description of the Locks
tab in the TRMC Help. For information about troubleshooting lock problems,
see “Troubleshooting locking problems” in the Technical Repository Guide to Version
Control.

The following table summarizes the air lock group of commands. For information about
command syntax, see “Command-line syntax of air commands”.
Command Description
air lock break Breaks a lock.
air lock release Releases a lock.
air lock reset Resets a broken lock.
air lock set Sets or modifies a lock.
air lock show Displays a listing of all locks.

The following diagram illustrates all the actions you or other users can take to lock and
unlock objects or break locks:

NOTA:

We recommend using the GDE rather than the lock commands to perform these locking
operations. These commands are intended for administering locks when intervention is
required. For information on basic sandbox locking, see “air sandbox lock”.

air lock break

Breaks a user’s lock on a given repository object, on all the objects in a project, or on all
locks. This command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air lock break
{[[-object object] [-project project] [-user username] ...] |
-all}
[-quiet]
Argument Description
-object object -object object is the path to or ID of the object whose lock you want to
break. See “Specifying object names as arguments”. To specify multiple
sets of objects, repeat the -object clause.
-project project -project project is the path to the project whose locks you want to break.
This argument will find all the locked files in a project and attempt to
break them. To specify multiple projects, repeat the -project clause.
Argument Description
-user username -user username is the username of a valid user. To specify multiple users,
repeat the -user clause.
-all -all breaks all locks across the current repository branch.
-quiet Suppresses a count of the number of locks broken.
Usage
The command arguments accumulate; they do not act as filters. In the following example,
using the -project and -user arguments will attempt to break all the locks in
project dev_proj and all the locks owned by user Alberto:

air lock break -project dev_project -user Alberto

Normally any user can break a lock. The user whose lock was broken does not own a
working lock anymore. If you break your own lock, the command releases (removes) the
lock, just as if you had run air lock release.

If a lock was created in unbreakable mode — that is, with the -unbreakable option to air
lock set — only the Technical Repository administrator or the lock owner can break it.
Note that when a lock owner runs air lock break on an unbreakable lock, this command
actually releases the lock.
air lock release
Unlocks a lock on a single object, on all objects in a project, or on all objects in all projects
within a technical repository. This command is branch-specific. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.

NOTA:

This command does not affect broken locks. To remove broken locks, use air lock reset.

Syntax
air lock release
[-user username...]
{[-object object] ... | [-project project] ... | [-all] }
[-quiet]
Argument Description
-user username Releases all locks belonging to specified user.
Valid only for the Technical Repository
administrator.
Argument Description
-object object | -project project | -all You must choose one of the following:

 -object object is the path to or ID of the object

whose lock you want to unlock.
See “Specifying object names as arguments”.
To specify multiple sets of objects, repeat
the -object clause.
 -project project is the path to the project
whose locks you want to unlock. To specify
multiple projects, repeat the -project clause.
 -all unlocks all broken locks in the technical
repository. Specifying -all without explicitly
specifying -user or -everyone will reset only
the locks owned by the current user.

-quiet Suppresses a count of the number of locks released.

Usage
You must be the Technical Repository administrator or the lock owner to release a lock. If
a lock was created in unbreakable mode — that is, with the -unbreakable argument to air
lock set — only the Technical Repository administrator can break it.
Example
You’re done working on all your files. To release the locks on all the files you had locked,
type the following:

air lock release -all

air lock reset

Removes broken locks completely that belong to a given user or all users or on a specific
object, or all broken locks in all projects to which you have access. Only a Technical
Repository administrator can reset other users’ locks. This command is branch-specific. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.

NOTA:

This command only affects broken locks. To remove locks, use air lock release. To break
locks, use air lock break.
Syntax
air lock reset
[-user username |-everyone]
{ [-object object] ... | [-project project] ... | [-all] }
[-quiet]
Argument Description
-user username Removes a broken lock belonging to user username or to all users
| -everyone (-everyone). Default is the current user.
-object object ... Required. You must choose one or more of the following. Default is -
| -projectproject ...| - all.
all
 -object object is the path to or OID of the object whose lock
you want to reset. See “Specifying object names as
arguments”. To specify multiple objects, repeat the -
object clause.
 -project project is the path to the project whose locks you
want to reset. To specify multiple projects, repeat
the -project clause.
 -all resets all locks in the technical repository to which you
have access.

NOTA:

Technical Repository administrators: If you specify -all without

explicitly specifying -user or -everyone only your locks will be reset.

NOTA:

If you omit both the -object and -project options, the default behavior
is -all.
-quiet Suppresses the printing of a count of locks reset.
Usage
You must specify at least one option. You can specify -object and -project at the same time.

The -object, -project, and -all options generate a list of locks from which
the -user or -everyone options determine which locks to reset.

Broken locks provide a record that the lock was broken by a different user than the owner.
Examples
Following are examples for administrators and non-administrators.
Removing all broken locks for a user
You are a Technical Repository Administrator. To remove all broken locks owned by
user dave_rb, type the following:

air lock reset -user dave_rb

Removing all broken locks in the repository

You are a Technical Repository Administrator. To remove all broken locks in the technical
repository, type the following:

air lock reset -everyone

However, to remove your own broken locks, type the following:

air lock reset -all

Resetting all your broken locks

You are a non-administrative user. Other users have broken the locks on five files that you
were working on. To reset all your broken locks, type the following:

air lock reset -all

Resetting all your broken locks in a specific project

You are a non-administrative user. To reset all your broken locks in a project, type the
following:

air lock reset -project /Projects/myproj

Related topics

 “Interrumpir y restablecer un bloqueo” in the Guía para desarrolladores de grafos

air lock set

Sets or modifies a lock on one or more repository objects You can specify multiple sets of
objects by repeating the -object clause. This command is branch-specific. For information
about the arguments common to all air commands, see “Command-line syntax of air
commands”.
Syntax
air lock set [-force]
[-breakable | -unbreakable]
[-auto-release |-manual-release]
[-modify attribute ...]
-object object ...
Argument Description
-force Breaks another user’s lock, if necessary, and sets a lock that
belongs to you.
-breakable | -unbreakable Specifies whether other users can break this lock. Default
is -breakable.

NOTA:

Technical Repository administrators can always break a lock.

-auto-release | -manual- You may specify one of the following choices. Default
release is -auto-release.

 -auto-release means the lock is automatically released

after the file is checked in.
 -manual-release means the lock persists after the file is
checked in, until it is explicitly broken or released.

-modify attribute ... Modifies the breakability and release attributes of an existing
lock. attribute can be -breakable or -unbreakable, and -auto-
release or -manual-release. For example, to make an existing
breakable lock unbreakable, specify -modify unbreakable.
See “Deprecated arguments” (below).
-object object ... The path to or ID of the object for which you want to set a
lock. See “Specifying object names as arguments”. To specify
multiple sets of objects, repeat the -object clause.
Deprecated arguments
These arguments are deprecated in Version 2.15:

 -unbreakable is deprecated and has been replaced by -breakable and -unbreakable.

 -persistent is deprecated and has been replaced by -auto-release and -manual-
release.
This argument is deprecated in Version 3.1.3:

 -project is deprecated and has no replacement.

Usage
You must be the Technical Repository Administrator or the lock owner to modify a lock.

You can use this command to refresh a lock that was previously set.
Example
Setting persistent locks
Persistent locks can only be broken by the Technical Repository Administrator or the lock
owner. To set locks that persist after checkin on
the JoinCustomers and LoadJoinedCustomers graphs in the lesson project:

air lock set -unbreakable -manual-release \

-object /Projects/lesson/mp/JoinCustomers.mp \
-object /Projects/lesson/mp/LoadJoinedCustomers.mp

air lock show

Displays a listing of locks for a given user, object, project, or all locks in the technical
repository. This command is branch-specific. For information about the arguments common
to all air commands, see “Command-line syntax of air commands”.
Syntax
air lock show { [-user username] ... | [-object object]... | [-project
project] ... | [-all] }
Argument Description
-user username You must choose one of the following:
| -object object
| -project project | -all  -user username is a valid username of the user whose
locks you want to display.
 -object object is the path to or ID of the object whose lock
you want to display. For more information,
see “Specifying object names as arguments”. To specify
multiple sets of objects, repeat the -object clause.
 -project project is the path to or ID of a project whose
associated file locks you want to display. For more
information, see “Specifying object names as arguments”.
To specify multiple projects, repeat the -project clause.
Argument Description
 -all displays all locks (file and process locks) in the
technical repository.

Usage
The display lists the path, username, time, and status of the lock — such as locked, broken,
manual release, and unbreakable. The path can be a typical repository path or an object ID
beginning with @ (for a description, see “Pathnames that begin with @”).

The display is ordered according to the arguments you specify. For example, if you specify
two users and a project argument, the display lists all the locks owned by the first user, then
all the locks owned by the second user, and finally all the locks in the project.

Here is sample output from the air lock show command:

Path User Time Status

/Projects/lesson/mp/JoinCustomers.mp dave_rb Thu Feb 22 13:45:06 2016 locked
@473.1.0 dave_rb Mon Feb 12 19:02:05 2016 locked
@474.1.0 dave_rb Mon Feb 12 19:06:33 2016 locked
manual release

Example
To display all the locks in the technical repository, type the following:

air lock show -all

air object commands

The air object commands manipulate objects and directories in the technical repository and
control permission to access objects.

The following table summarizes the air object commands. For information about command
syntax, see “Command-line syntax of air commands”.

Command Description
air object access Tests whether you can read, write, execute, or see the existence of a
particular object.
air object cat Writes an object to stdout (standard output).
air object changed Identifies which objects have changed.
Command Description
air object chmod Changes the permissions of a repository object.
air object chown Changes the ownership of a repository object.
air object cp Copies an object.
air object dataset Sets various properties of an EME dataset in the technical
repository, and removes orphaned datasets.
air object dataset- Returns objects and their dataset associations.
associations
air object This command has been deprecated. Use air purge object or air
delete (deprecated) object rm instead.
air object field- Outputs a text description of field lineage for a graph or for the
lineage graph instance associated with an input pset.
air object info Displays information about directory objects, objects without names,
and the root of the technical repository.
air object This command has been deprecated.
ln (deprecated)
air object load Loads objects from a portable interchange format file into a
technical repository.
air object ls Displays information about the objects in a technical repository
directory.
air object mkdir Creates a directory.
air object mv Renames an object.
air object poll-for- Monitors the technical repository for changes to a specified set of
change objects that are under source control. When changes to those objects
are detected during a polling interval, executes a user-specified
script or command.
air object referencing- Displays the paths to all objects that use a target object.
files
air object requires Creates a list of additional files that will be promoted when you load
a save file created through air object save.
air object revert This command is no longer available. Use air object save and air
object load instead.
air object rm Removes a directory entry.
air object rollback Makes the specified version the current version in the technical
repository or restores a removed object.
air object rollback- Identifies objects that were modified at a specified version, finds
version their prior versions and stores those at the current version.
air object save Saves repository objects to a save file in portable-interchange-
format.
air object search grep Searches a technical repository for files containing the specified
search string.
air object search Searches one or more technical repository paths for a given
parameter parameter name.
Command Description
air object set-acl Sets or modifies the ACL (access control list) permissions on one or
more specified objects. Use to provide a finer level of control on
objects and directories than Unix or users and groups permissions
provide.
air object show-acl Displays the ACL permissions for one or more specified objects.
air object show- Displays permissions for objects in a technical repository.
permissions
air object uses This command has been renamed to air object referencing-files.
(The former name is still supported.)

air object versions Lists all version numbers for a given object.

air object access

Tests whether you can read, write, execute, or see the existence of the specified object,
given your permissions and the current state of the technical repository being accessed
as rpath. The command returns either 1 (for true) or 0 (for false). This command is branch-
specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air object access rpath [ r | w | x | f ]
Argument Description
rpath Path to a repository object, or object ID. See “Specifying object names as
arguments”.
r Tests whether or not you can read the specified object.
w Tests whether or not you can write the specified object.
x Tests whether or not you can execute the specified object.
f Tests whether or not you can see the existence of the specified object, rpath.
Returns 0 if you don’t have permissions to determine the object’s existence or if
it doesn’t exist.
NOTA:

If the object cannot be accessed for any reason, the command returns 0.

Alias
The alias for this command is air access.
air object cat
Writes the literal contents of a repository object to standard output. This command
is branch-specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air object cat rpath
Argument Description
rpath Path to a repository object, or object ID. See “Specifying object names as
arguments”.
Usage
Use this command for binary objects as well as objects with a text representation — such as
MIME objects, text files, and .dml and .xfr files. The command fails if rpath’s target cannot
be converted to text or does not exist. Compare with air display internal.
Example
To see the record format in a-customers.dml, type:

air object cat /Projects/lesson/dml/a-customers.dml

The command displays:

record
decimal(8) custid;
string(10) fname;
string(12) lname, place;
decimal(5) building_num;
decimal(1) preferred;
end("\n")

Alias
The alias for this command is air cat.

air object changed

Compares two branches or versions of a single technical repository or two repositories, and
identifies which objects have changed. Optionally, describes the differences between
modified objects. This command is branch-specific. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air object changed [ rpath ... ]
[ -root1 eme1 ] [ -branch1 branch1 ] [ -version1 v1 | tag1
| timestamp ]
[ -root2 eme2 ] [ -branch2 branch2 ] [ -version2 v2 | tag2
| timestamp ]
[ -show-all ]
[ -tagged-only ]
[ -diff [ -terse | -verbose ] [ -ignore-param-order ] [ -text ]
[ -ignore-dep-analysis ] [ -original-format ] ]
[ -files-with-diff [ -terse | -verbose ] ]
[ -m ] [ -dml ]
Argument Description
rpath Specifies the technical repository path of one or more
objects to compare. If you specify a directory for rpath,
all objects in the directory and its subdirectories are
compared.

If no path is specified, you must specify a tag as a source

version (-version1 v1) or a target version (-version2 v2);
in this case, the tag’s objects are compared.

rpath is required if you do not specify any other

arguments.
-root1 eme1 Path to the source technical repository. If not specified,
defaults to the value of AB_AIR_ROOT.
-branch1 branch1 Branch name branch1 of the first branch to compare. If
not specified, defaults to the value of AB_AIR_BRANCH.
Specify main for the main branch.
-version1 v1 | tag1| timestamp Starting version v1, tag tag1, or date or time timestamp.
If not specified, defaults to the latest version.
See “Interaction of rpath and -version arguments” for
more details. The timestamp format is: “YYYY-MM-DD
HH:MM:SS”. The dashes in the date and the enclosing
quotations are required.
-root2 eme2 Path to the target technical repository. If not specified,
defaults to the value of AB_AIR_ROOT.
Argument Description
-branch2 branch2 Branch name branch2 of the second branch to compare.
If not specified, defaults to the value
of AB_AIR_BRANCH. Specify main for the main branch.
-version2 v2 | tag2 | timestamp Ending version v2, tag name tag2, or date or
time timestamp. If not specified, defaults to the latest
version. The timestamp format is: “YYYY-MM-DD
HH:MM:SS”. The dashes in the date and the enclosing
quotations are required.
-show-all Lists all objects that are compared, even if they have not
changed.
-tagged-only Changes the behavior of the command if you specify tags
as the values of -version1 and -version2, and you specify
an object to compare (rpath). If -tagged-only is specified,
the object is considered added or removed if it is not in
both tags.

For more information, see “Interaction of rpath and

-version arguments”.
-diff Displays differencing text of modified objects inline.
(The text is presented in the same style as that of air
sandbox diff.) When objects cannot be differenced, the
reason is displayed, together with the label “diff
unavailable.”

With the -diff argument, you can also

specify -terse or -verbose, -ignore-param-order, and -text.
-terse | -verbose Valid with the -diff or -files-with-diff arguments. Affects
graph differencing text only. You can choose one of the
following:

 -terse specifies that graph differencing text shows

only differences that might affect the running of
graphs, such as a change to the value of a
parameter.
 -verbose specifies that graph differencing text
shows all changes to graphs, including minor
ones, such as a change to the x,y coordinates of a
component.

-ignore-param-order Valid with -diff and for graphs only. Does not display
differences in the order of graph or component
parameters.
-text Valid with -diff. Forces text differencing, regardless of
the type of the files.
Argument Description
-ignore-dep-analysis Valid for graphs only. Does not show differences in
parameters that are used only for dependency analysis;
for example, it ignores
the eme_dataset_location parameter,
the doc_transform parameter, and the technical repository
value for any parameter dependent
on AB_PARAMETER_ENV.
-original-format Valid with -diff and for graphs and plans only. Shows
changes due to differences in the graph or plan’s file
format. For example, this argument can be useful in rare
cases when you want to compare two graphs that were
saved to a different format by using the GDE Save
As menu item.
-files-with-diff Reports only files that have associated differencing text.
You can specify either the -terse argument or
the -verbose argument with -files-with-diff.

You can use this argument to filter out changes that you
are not interested in. For an example, see “Comparing the
latest versions of a project on two different branches in
the same technical repository”.
-m Writes the command’s output in machine-readable format
to standard output. You can process the output in a graph
using the record format produced by the -dml option.
-dml Displays the record format of the command's output with
the -diff and -m options, and exits without running. This
option is useful if you want to pass command output to a
graph for processing.
Usage
This command reports the changes only in objects that are checked in to and out of
projects. In particular, it does not report changes in objects such as datasets.
Output
The command outputs the list of files that have been added, removed, or changed between
the source and target as follows:

Code
Description
(meaning)
A (Added) The file exists in the target but not in the source.
R (Removed) The file exists in the source but not in the target.
M (Modified) The file is different in the source and the target.
S (Same) The file is the same in the source and the target.
Code
Description
(meaning)
U (Unknown) The difference could not be determined. Occurs due to permission errors
or when an object cannot be checked out.
N (No object) The specified object does not exist in either the source or the target.

For a description of the output when you specify the -diff argument, see “Output” of air
sandbox diff.
Interaction of rpath and -version arguments
When you specify a tag to the -version arguments, the behavior of this command changes,
depending on whether you specify objects to compare. See the following two cases.

Case 1 If you specify a tag to the -version argument, but you do not specify objects to
compare, the command compares only the objects in the tag. If an object is not in the
source tag but is in the target tag, it is considered “added,” even if it existed in the technical
repository at the time that the source tag was created. Conversely, if the object is in the
source tag but is not in the target tag, it is considered “removed,” even if it existed in the
repository at the time that the target tag was created.

Case 2 If you specify an object to compare and you specify a tag to

the -version arguments, the behavior of the command depends on whether you
specify -tagged-only.

 If you do not specify -tagged-only, the tag is used to determine the version of the
object to compare (see “-version” for a description of how object versions are
determined from a tag). In this case, the object is considered “added” or “removed”
only if it was actually added or removed from the technical repository between the
times at which the tags were last modified.
 If you specify -tagged-only, the command behaves as in Case 1: objects are
considered added or removed solely based on whether they exist in both tags.

Examples
Comparing a specific technical repository version with the
latest version from the same repository and branch:
The following command determines the differences between technical repository
version 4849 and the latest version of the same repository and branch:

air object changed /Projects/myproj -version1 4849

The output shows among other things that transform.xfr and mygraph.mp have not changed
between version 4849 and the latest version, whereas records.dml was added after version
4849 and .air-project-parameters has been modified:

A dml/records.dml
S xfr/transform.xfr
S mp/mygraph.mp
M .air-project-parameters

Note the following:

 To identify the changes in different versions of the project parameters file, you must
specify the path to the project as rpath or specify the name of a tag that has been
applied to a project or graph.
 To see the actual changes that have occurred in a modified file — for example, the
project parameters file — specify the -diff argument.

Comparing the latest versions of a project on two different

branches in the same technical repository
The following command determines the differences between the latest versions of
the myproj project on two different branches in the same technical repository — release-
20150428 and main:

air object changed /Projects/myproj \

-branch1 release-20150428 -branch2 main
A dml/stuff.dml
M mp/output_data.mp
M mp/process_data.mp

Since the repository versions were not specified, they are assumed to be the value
of AB_AIR_ROOT. Since the versions were not specified, they are assumed to be the
current version.

If, in the example above, the only change in a graph process_data.mp was a moved
component, you can use the -files-with-diff argument to filter out that component — for
example:

air object changed /Projects/myproj \

-branch1 release-20150428 -branch2 main -files-with-diff
 A dml/stuff.dml
M mp/output_data.mp

Comparing objects in a specific tag with the latest versions

of those same objects
The following command determines the differences between the objects in the
tag mytag and the same objects as of the latest version:

air object changed -version1 mytag

Comparing a specific version of project with the latest

version of the same project
The following command determines the differences between myproj as it existed at 3:42 on
10 October 2012 and the same project as of the latest version:

air object changed /Projects/myproj -version1 2012-10-10 03:42:15

Alias
The alias for this command is air changed.

air object chmod

Changes the permissions and inheritance settings of one or more repository objects. You
may set one of these, two of these, or all of these in a single execution of the command.
This command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air object chmod [-Rf ]
{[ + | - ] [permissions] | [+inherit | -inherit]}
rpath [rpath2 ...]
Argument Description
-R Recursively traverses subdirectories of rpath.
-f Tries to continue even if the operation fails for one or more rpaths.
[+ Specify permissions as an octal number, using standard Unix
| -] permissions
Argument Description
conventions.

If the octal permissions number is preceded by a “+”, it means add (OR)

in the specified bits with the existing bits. If preceded by a “-”, it means
clear the given bits from the existing bits.
+inherit | -inherit An alternative to the octal notation, +inherit means that future objects
created in the directory specified by rpath will automatically inherit the
ownership and the permission bits of the directory at creation time.
rpath [rpath2...] Path to a repository object, or object ID. See “Specifying object names
as arguments”. You can specify multiple rpaths.
Usage
Prior to using this command, the Technical Repository administrator must run the air
repository options +access-control command.

Only the Technical Repository administrator or the owner of the specified object can
execute air object chmod.

The permissions argument must be specified in octal notation, using standard Unix
conventions. For information about using octal numbers for permissions, see “Setting
technical repository permissions on objects” in the Technical Repository Administrator’s
Guide.

To display current permissions for particular objects, use air object ls.

You can combine keywords and octal representation at the command line.
Example
To make the JoinCustomers.mp file readable by all users and writable by you alone, enter
the following (this results in a permissions setting of -rw-r--r--):

air object chmod 644 /Projects/lesson/mp/JoinCustomers.mp

Alias
The alias for this command is air chmod.

air object chown

Changes the ownership and/or group of one or more repository objects. Only the Technical
Repository administrator can perform this operation. This command is branch-specific. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air object chown [-Rf]
{user.group | user | .group} rpath...
Argument Description
-R Optional. Recurses into rpaths if they refer to a directory.
-f Optional. Tries to continue even if the operation fails for one or more rpaths.
user New owner expressed as a valid username. If omitted, the owner is not
changed.
.group New group name, preceded by a period. If omitted, the group is not changed.
rpath Path to a repository directory or object, or object ID, whose ownership or group
you want to change. See “Specifying object names as arguments”. You can
specify multiple paths.
Usage
Prior to using this command, the Technical Repository administrator must run the air
repository options +access-control command.
Example
To make user buxbaumi the owner of the JoinCustomers.mp file, enter the following:

air object chown buxbaumi /Projects/lesson/mp/JoinCustomers.mp

Alias
The alias for this command is air chown.

air object cp
Creates a copy of the object known as rpath1 in a location within the technical repository.
This command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air object cp rpath1 rpath2
Argument Description
rpath1 Path to the repository object to be copied. See “Specifying object names as
arguments”.
Argument Description
rpath2 New technical repository path for the copied object.
Deprecated arguments
-R was deprecated in Version 2.14.
Usage
Files with the same name will be overwritten.
Alias
The alias for this command is air cp.
air object dataset
Changes various properties of an EME dataset in the technical repository, as follows:

 Sets the user-managed property for an analysis-only dataset, such that dependency
analysis cannot update the dataset’s metadata.
 Registers an EME dataset in the dataset registry.
 Removes orphaned EME datasets. An orphaned EME dataset is one that has no
associations: no graphs read data from it or write data to it. As part of your regular
technical repository maintenance tasks, we recommend removing orphaned datasets
periodically.

This command is branch-specific. For information about the arguments common to

all air commands, see “Command-line syntax of air commands”.
Syntax
air object dataset [ -R ] rpath
[ -show ]
[ -discover | -user-managed ]
[ -register ]
[ -remove-orphans [ -dry-run ] ]
Argument Description
-R Applies the command recursively to all datasets in the rpath.
rpath Path to a directory or dataset in the technical repository.
-show Displays the value of the dataset’s user-managed setting —
either Discovered or User-managed.
-discover | - Specifies whether dependency analysis updates a dataset’s metadata.
user-managed
 -discover means that dependency analysis updates the dataset’s
metadata.
 -user-managed means that dependency analysis does not update the
dataset's metadata.

-register Enters the specified dataset into the dataset registry. Useful for setting up
cross-project lineage for table datasets.
-remove- Removes orphaned datasets from the specified rpath. Orphaned datasets are
orphans those that have no associations; that is, no graphs read from or write to
them. If a dataset is user-managed, this command does not remove it.
(Reusable datasets are user-managed; therefore, this command does not
remove them.)
-dry-run Lists the orphaned datasets found at the specified rpath but makes no
changes to the technical repository.
Usage
Dependency analysis normally updates an EME dataset with the record format it finds in
the graph. When you specify -user-managed, dependency analysis does not change the
record format or any other aspect of the dataset.

The setting on the dataset overrides the setting on a graph component, which is controlled
through the Create/update EME dataset during dependency analysis checkbox in the
GDE.

For more information about the -register option and the dataset registry, see “Linaje para
conjuntos de datos de tabla” in the Co>Operating System Guía para desarrolladores de
grafos.

Related topics

 Dataset association and creation

 air object dataset-associations
 Linaje para conjuntos de datos de tabla

air object dataset-associations

Reports the dataset dependencies (associations) of a dataset — the graphs that read from or
write to the specified dataset. This command can also be used with graphs and psets to list
the datasets associated with a graph. The information that the command displays is similar
to the tabular view of the Dataset Lineage viewer. (For more information, see “Ver linaje
de los conjuntos de datos en el ventana del GDE” in the Co>Operating System Guía para
desarrolladores de grafos.)

This command is branch-specific. For information about the arguments common to

all air commands, see “Command-line syntax of air commands”.
Syntax
air object dataset-associations [rpath ...]
[-downstream-limit n]
[-upstream-limit n]
[-project-only]
[-common-only]
[-m] [-dml]
Argument Description
rpath Path to a dataset, graph, or pset object in the technical repository. You
Argument Description
can specify multiple object paths or specify '-' to pass one or more paths
from standard input.
-downstream- Specifies the maximum number of downstream links to follow. Default
limit n is 1. To walk all (unlimited) links, set this value to -1.
-upstream-limit Specifies the maximum number of upstream links to follow. Default
n is 1. To walk all (unlimited) links, set this value to -1.
-project-only Reports only graphs and datasets within the project containing the object.
-common-only Reports only graphs and datasets within the project and its common
projects.
-m Writes the command output in machine-readable format to standard
output.
-dml Displays the current record format for the returned objects. For machine-
readable output, you can run the command with the -m option.
Example
The following command reports the dataset dependencies for the indicated dataset:

air object dataset-associations /Projects/tutorial/data/serial/main/b-customers.dat

Here is the command output:

/Projects/tutorial/mp/b-join.mp
reads /Projects/tutorial/data/serial/main/b-customers.dat from becket_customers:read
/Projects/tutorial/mp/mailing-list-improved.mp reads /Projects/tutorial/data/serial/main/b-
customers.dat
from becket_customers:read
/Projects/tutorial/mp/customers_b.pset reads /Projects/tutorial/data/serial/main/b-customers.dat
from Input_File:read

The output tells you which graph reads (or writes) the dataset, and from which component
and port. The first line indicates that the graph b-join.mp reads the current dataset from
the read port of the component becket_customers.

The following command reports the datasets associated with the indicated graph:

$ air object dataset-associations /Projects/test_prj/mp/in_out.mp

Here is the command output:

/Projects/test_prj/mp/in_out.mp reads /Projects/test_prj/data/serial/main/junk.dat from
Input_File:read
/Projects/test_prj/mp/in_out.mp writes /Projects/test_prj/data/serial/main/junked.dat from
Output_File:write

Related topics

 Dataset association and creation

 air object dataset

air object field-lineage

Outputs a text description of field lineage for a graph or for the graph instance associated
with an input pset. With the -cross-graph argument, the command will trace field lineage
across multiple graphs in the technical repository. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air object field-lineage rpath -dep var
[-upstream | -downstream]
[-statements], [-ports], [-datasets]
[-cross-graph depth]
[-wizard]
[-m]

air object field-lineage rpath

-all-outputs |
-all-inputs |
-outputs-to-inputs |
-inputs-to-outputs |
-datasets |
-vars
[-cross-graph depth]
Argument Description
rpath Specifies the path (in the technical repository) to the graph or input pset to
be analyzed.
-dep var Displays the dependencies for a particular component port, as identified
by the var argument. Optionally, you can limit the output to the
Argument Description
dependencies for a particular field. The var argument uses the following
form:

vertex/varinfo:port[:field]

vertex identifies a component (by its label in the GDE, if it has one, or by
its name), and port identifies a component port by name. To limit the
output to a particular field, specify the field. If you do not specify a field
name, then dependencies for all fields through the port are shown.

SUGERENCIA:

Use air object field-lineage rpath -vars to display a list of all possible
values for var in the graph.
-upstream | - Use with the -dep argument. Specifies the direction of the analysis. If you
downstream do not specify the direction, lineage for both directions is shown.
-statements, - Use with the -dep argument. Filters the output to show only the
ports, -datasets statements, ports, or datasets. (The default output shows all of these.) You
can use these options in combination.
-wizard The command output by default does not display the DML associated
with any transforms that are determined to affect field lineage. Use this
flag to add the text of the DML statement to the command output.
-m Produces DML-described (machine-readable) output. The record format
is in $AB_HOME/include/field-lineage.dml.
-cross-graph de Displays information about field lineage across any graph in the
pth repository that uses a common source or target dataset. For example, if
the graph specified by rpath writes Dataset A, then field lineage for any
graph that reads Dataset A is shown.

The depth argument specifies across how many graphs the analysis should
extend. The default depth is 1 (current graph only). A value of -
1 indicates no limit — the entire repository is included in the analysis.
-all-outputs Displays the upstream dependencies for all fields in the graph’s output
datasets.
-all-inputs Displays the downstream dependencies for all fields in the graph’s input
datasets.
-outputs-to- For every output field in the graph, lists all the input fields that have data
inputs dependencies on that output field.
-inputs-to- For every input field in the graph, lists all the output fields that have data
outputs dependencies on that input field.
-datasets Lists the datasets read or written by the graph.
-vars Lists all the analysis variables (essentially, component ports) in the graph.
This output is helpful in determining the appropriate value for var before
Argument Description
you run air object field-lineage with the -dep var argument.
Usage
This command analyzes a graph or graph instance (identified by an input pset) in the
technical repository. The object to be analyzed must be checked in. To analyze a graph that
is not checked in, use air sandbox field-lineage.

NOTA:

This command does not display dependency analysis warnings. Check for warnings by
running air project analyze-dependencies before using this command.

Examples
The following command displays the field lineage for the pending_interest field through
the read port of a dataset component called Pending_Interest:

air object field-lineage /Projects/rbank/adjustments/mp/adjustments.mp -dep

Pending_Interest/varinfo:read:pending_interest

The following command displays the upstream dependencies for all the fields in the graph’s
output dataset:

air object field-lineage /Projects/rbank/adjustments/mp/adjustments.mp -all-outputs

The following command adds cross-graph lineage (with a scope of the entire technical
repository) to the previous example:

air object field-lineage /Projects/rbank/adjustments/mp/adjustments.mp -all-outputs -cross-graph -1

The following command lists the datasets read or written by the graph:

air object field-lineage /Projects/rbank/adjustments/mp/adjustments.mp -datasets

Related topics

 Linaje de campos
 air sandbox field-lineage
  air project analyze-dependencies

air object info

Displays the same information as the air object ls command. Use air object info for
directory objects, objects without names, or for the root ( / ) of the technical repository. This
command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air object info [-lguAdcaf] rpath
Parameter Description
-l If specified, produces a long listing in which each line includes special
information, permissions, owner, size of current version, object class, and
name.

Some special information is shown as a character at the beginning of each

output line:

 - means the entry is an object without a sticky bit.

 S means the entry is an object with a sticky bit.
 d means the entry is a directory without a sticky bit.
 D means the entry is a directory with a sticky bit.

The nonversioned bit is indicated in the executable (X) field of the Other
group, as follows:

 - means the entry is versioned and is not executable by the Other group.
 x means the entry is versioned and is executable by the Other group.
 n means the entry is nonversioned and is not executable by the Other
group.
 N means the entry is nonversioned and is executable by the Other
group.

You can append g, u, A, d, c, and a to -l.

g If -l is also specified, g includes the group in the long listing.
u If -l is also specified, u includes the owner uid in the long listing.
If -g and -u are both specified, the group gid is also displayed.
A Default. If -l is also specified, A includes the combined size of all versions in
the long listing as well as the size of the current version.
d If -l is also specified, d includes domain and version numbers in the long
listing.
c If -l is also specified, c includes the number of entities and relationships in each
Parameter Description
domain.
a If -l is also specified, a includes all versions of the specified object.
-f Can be specified as a standalone argument or with -l. Displays the path to the
specified object.
rpath Path to a repository directory or its object ID. See “Specifying object names as
arguments”.

air object load

Loads objects from a portable interchange format file (a save file) that was created through
the air object save command. By default, the command loads the objects to the repository
location corresponding to the ones in which they were saved. The command also performs
dependency analysis by default.

The command also loads the save promotion history associated with the save file, records a
history of the load promotion in the target repository, and saves a promotion history file for
subsequent loading into the source repository. The command can load either compressed or
uncompressed save files.

This command is branch-specific. For information about the arguments common to

all air commands, see “Command-line syntax of air commands”.

NOTA:

We recommend using air promote load, except when promoting business metadata for
Express>It. The air promote load command has fewer arguments and is easier to use. It is
similar to running air object load -history-file -analyze.

Syntax
air object load [-table-of-contents] filename
[-history-file history-filename]
[-relocate source-path target-path] ...
[-no-since-verify]
[-no-tag | -tag tagname]
[-comment comment]
[-quiet]
[-load-permissions]
[-analyze | -no-analyze]
Argument Description
-table-of-contents Displays a listing of filename’s contents, including the explicitly
saved objects, saved referenced objects, and tag information. No
loading occurs. For more information on the listing,
see “Understanding the contents”. For an example, see “Viewing
the contents of the save file”.
filename Standard Unix filename of the file storing the objects you want to
load. If filename is -, the data is read from standard input.
-history-file history-file Path to a history file to create. After the load operation is done,
name you should load this file into the source technical repository, even
if the load operation failed.
-relocate source-path Causes the objects in the save file to be loaded to different
target-path locations. All paths beginning with source-path are loaded
at target-path.

If not specified, the objects are loaded into the location specified
by source-path.

This option can also apply to partial paths — parent directories or

projects — not just the objects being loaded.

You can use multiple -relocate clauses.

-no-since-verify Skips verification of the existence of tags used in save files
created using the -since option of air object save. This option was
previously called -force.
-no-tag | -tag tagname You may choose one of these:

 -no-tag means the loaded objects are not tagged, even

if filename (created by air object save) contains a tag.
 -tag tagname overrides the tag name stored in filename and
uses tagname instead. If filename does not contain a
tag, tagname is ignored.

-comment comment Specifies a comment to be associated with the object.

-quiet Suppresses some informational messages during the load
operation — in particular, messages about external references.
-load-permissions If specified, sets the permissions on the loaded objects to match
those in the source repository. By default, the command does not
apply permissions from the source repository.
-analyze | -no-analyze You may choose one of these:

 -analyze — Default. Performs dependency analysis on the

loaded objects.
 -no-analyze — Does not perform dependency analysis on
Argument Description
the loaded objects. Use to override the default behavior.

Usage
The save file must have been created by air object save or air promote save. If the -exact-
tag or -from-tag options were used with either command, a promotion history is also
created. For more information, see “Promotion history”.

You can also use air object load to load purged jobs back into the technical repository from
which they were purged. The archive file containing the purged jobs is created by air purge
jobs. air object load will fail if the objects referred to in the archive file have been removed
from the repository.

When using air object save, make sure that AB_AIR_ROOT points to the target repository,
or use the -root option (see -root) to specify the repository root explicitly.

The repository resolves external references in the saved file by pointing to the latest version
of all external references. Therefore, it is possible for version conflicts to occur in the
destination repository when you load common projects.

When a tag was created using the air tag create -exact option (which includes only objects
specified in its path and no dependent objects), air object load treats migrated tags the same
way.

air object load can handle both gzip-compressed data as well as data compressed by
the compress utility.

Progress messages are written to standard output. To change the default behavior,
set AB_AIR_SAVE_LOAD_LOG_TO_STDERR to true.
Understanding the contents
When you use air object load with the -table-of-contents argument, it displays a listing of
the specified filename’s contents so that you can view the file’s contents before you
actually load it in a separate step. The following are the fields that the output might include:

 Objects — All objects in the portable interchange format file.

 Exported objects — The objects explicitly identified to save by tag or object name.
This list will be identical to the Objects list if you created the save file using air
promote save or air object save -exact, which use an exact tag match.
 Included objects — Any required files that were found whether specified directly or
not.
 Miscellaneous information — Information that describes how the tag was created.

For sample output, see “Viewing the contents of the save file”.
Promotion history
If the Technical Repository administrator has enabled the Require Promotion History
option (air repository options +require-promotion-history), any errors encountered while
creating the promotion history will cause the load operation to fail.

The promotion history file created by air object load contains the history of a load
promotion into the target technical repository. It includes information about the options
used while loading as well as any errors or warnings encountered.

The promotion history file is assigned a random name and is written

to /abinitio/promotions/load. To find the name of the promotion history, run air promote
list.

We strongly recommend that you specify a load promotion history file. After the load
operation is done, run air promote load-history-file history-filename to load that file into the
source technical repository, even if the load operation failed. This guarantees that the
record of promotion histories in the source and target repositories are synchronized. Note
that history-filename is not the same as the randomly assigned name written to the target
repository; rather it is a name you assign to the file.
Examples
Resolving common project references
In this example, you save version 100 of a project and the same version of its associated
common project common_proj. Meanwhile, another user loads the project at version 120,
which also includes the same common project common_proj at version 120. When you try
to load version 100 of common project common_proj, the Technical Repository software
resolves the reference to common project common_proj to version 120 in the destination
repository.
Viewing the contents of the save file
To see which files will be loaded in the target repository, enter:

air object load /tmp/mysave.save -table-of-contents

The output shows the explicitly saved project (/proj) and the objects saved as a result of
saving the project. Also note the tag information. The file was created through the tag tag1,
which will be created automatically in the target repository unless you specify -no-tag to air
object load.

Objects:
 /proj
/proj/.air-project-parameters
/proj/.project-end.ksh
/proj/.project-start.ksh
/proj/.repository-state
/proj/db
/proj/dml
/proj/dml/cust_01.dml
/proj/dml/cust_02.dml
/proj/mp
/proj/mp/customers.mp
/proj/mp/billing.mp
/proj/plan
/proj/pset
/proj/resource
/proj/run
/proj/xfr
Exported objects:
/proj
Miscellaneous information:
From tag "tag1"
Create tag "tag1"

Deprecated arguments
-force has been deprecated in Version 2.15.
Alias
The alias for this command is air load.

air object ls
Displays a listing of a technical repository directory. The default listing format has a header
line plus one line per element of the directory. Each line ends with the object’s class and
name. This command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air object ls [-RlguAdcafC] rpath
Parameter Description
-R If specified, produces a recursive listing of the directory and its subdirectories.
-l Produces a long listing in which each line includes special information
(see “Usage”), permissions, owner, size, object class, and name.
Parameter Description

You can append g, A, d, c, a , and f to -l.

g When -l is also specified, g includes the group name in the long listing. To list
the group gid, add the u parameter.
u When -l is also specified, u includes the owner uid in the long listing.
A When -l is also specified, A includes both the size of the current version of an
object and the combined size of all versions in the long listing. This is a wizard
option and is not typically used.
d This parameter lists internal versions such as tagging (backward relations) and
dependency analysis dataset association assignments (forward relations and
annotations).When -l is also specified, d includes domain and version numbers
in the long listing. This is a wizard option and is not typically used.
c When -l is also specified, c includes the number of entities and relationships in
each domain. This is a wizard option and is not typically used.
a When -l is also specified, a includes all domain versions of the specified object.
This is a wizard option and is not typically used.
-f Can be specified as a standalone argument or with -l. Displays the path to the
specified object.
-C When -l is also specified, C includes the latest version at which the specified
object was checked into a project, along with a time stamp. If the object is not
under source control, the command shows the last modification version and
time stamp.
rpath Path to a repository directory object or an object ID. If omitted, the listing starts
at the repository root ( / ). See “Specifying object names as arguments”.
Usage
The special information output by the long listing (-l) is shown as a character at the
beginning of each output line, as follows:

 - means the entry is an object without a sticky bit.

 S means the entry is an object with a sticky bit.
 d means the entry is a directory without a sticky bit.
 D means the entry is a directory with a sticky bit.

In the long listing, the nonversioned bit is indicated in the executable (X) field of the Other
group, as follows:

 - means the entry is versioned and is not executable by the Other group.
 x means the entry is versioned and is executable by the Other group.
 n means the entry is nonversioned and is not executable by the Other group.
 N means the entry is nonversioned and is executable by the Other group.

NOTA:
If there is an ACL on the object, permissions show ACL instead of owner and group
permissions. For example:

-*ACL**--- jon 163872 000000134.000000009 mimeobj: JoinCustomers.mp

When you add a file to a directory with a sticky bit, the file takes on the permissions of the
parent. For information about permissions and changing permissions, see air object chmod.

This command does not display information about objects that have been removed by air
object rm or deleted by the deprecated air object delete command.

For more information, see “Displaying permissions, ownership, and related information”.
Object types
The following table lists common object classes that you might see after issuing the air
object ls command; it is not an exhaustive list:

Object class Repository file

annotationrul Class that defines objects in /abinitio/annotation rules. Describes categories
e and annotations.
appconf Application configuration (.appconf file) in the appconf directory.
apptempl Application template (.apptempl file) in the apptempl directory.
Compound control (.compctrl file) in the apptempl/compctrl directory.
bcategory Class that defines objects in /abinitio/categories.
bzrule Class for Express>It standalone rulesets.
bzruleset Class for Express>It standalone business rules.
category Class that, along with annotation rules, describe the types of data objects in
the schema for Ab Initio categories. Defines the object schema
in /abinitio/categories.
choicerule Subclass of annotationrules.
dataset Dataset, such as a .dat object file in the data directory.
directory Technical repository directory object.
graph Graph or linked subgraph, such as an .mp object file in the mp directory.
Dynamic subgraph, such as an .mp file in the components directory.
Parameter set, such as a .pset file in the pset directory.
job Class for a reposited job for graph tracking.
mimeobj Container class for text files and other objects. Common examples include
the following:
Project script files, such as a .ksh file.
Sandbox ruleset, such as an .rset file in the rset/sandbox-ruleset-
name directory.
Object class Repository file
Rule, such as a .rule file in the rset/sandbox-ruleset-name directory.
Database configuration file, such as a .dbc file in the db directory.
XML file (for template style definitions), Microsoft Excel spreadsheet
(.xls file), or any file not explicitly categorized in its own object class.
package Class for all transform (.xfr) and data format (.dml) files
parameterset Reposited non-graph or non-plan parameter set (.pset), such as
a .project.pset and .sandbox.pset file.
plan Conduct>It plan (.plan file), typically found in the plan directory.
Parameter set (.pset file), typically found in the pset directory.
planjob Class for a reposited job from a Conduct>It plan.
planrun Class for a reposited run associated with a job for a Conduct>It plan.
project Technical repository project object.
promotion Promotion history objects.
rinfo Class for .repository-state file objects in a technical repository project.
textpackage Transform package (.xfr file), typically found in the rset/sandbox-ruleset-
name directory or the xfr directory.
type DML record format (.dml file), typically found in the dml directory.
vtag Technical repository tag, typically found in /abinitio/tags.
xmlobject XML file object.
Example
To display 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 in domain 134 and is currently at version 9.
The owner and the group can read and write the file:

-rw-rw---- jon 163872 000000134.000000009 mimeobj: JoinCustomers.mp

If an ACL is on the object, the permissions appear as the following:

-*ACL**--- jon 163872 000000134.000000009 mimeobj: JoinCustomers.mp

Alias
The alias for this command is air ls.
air object mkdir
Creates a technical repository directory and if it is within a project, adds it to the project
files list. Parent directories are created as necessary. This command is branch-specific. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air object mkdir [-q] [-no-project-add] rpath
Argument Description
-q Suppresses error if rpath exists.
-no-project-add If the new directory is in a project, the directory is not added to the
containing project's file list.
rpath Path of the directory you want to create.
Usage
The command fails if rpath exists.
Alias
The alias for this command is air mkdir.

air object mv
Renames the object rpath to rpath_mv. This command is branch-specific. For information
about the arguments common to all air commands, see “Command-line syntax of air
commands”.
Syntax
air object mv rpath rpath_mv
Argument Description
rpath Path to the repository object you want to rename. See “Specifying object names
as arguments”.
rpath_mv New name for the object rpath.
Usage
This command fails if rpath does not exist or if rpath_mv exists.

Both rpath and rpath_mv must refer to directories or files in directories, such as record
format (.dml) files or projects.
You can use this command to rename — in essence, relocate — entire projects.
Parameterized references to the original project will resolve properly to the renamed
project.

The older tagged versions of a renamed object remain intact at the original location;
existing tags continue to point to the original name (location) of the object.
Alias
The alias for this command is air mv.

air object poll-for-change

Monitors the technical repository for changes to a specified set of objects that are under
source control. When changes to those objects are detected during a polling interval, the
command executes a user-specified script or command. For information on using repository
trigger commands, see “air repository trigger commands”.

Note the following about repository format versions:

 To use this command, you must have repository format version 15 or higher.
 To use the -tags option, you must have repository format version 17 or higher.

Syntax
air object poll-for-change -cmd script
[ -state-file filename ]
[ -poll-interval t ]
[ -poll-limit n ]
[ -watch-list paths ] | [ -watch-file filename ]
[ -tags ]
[ -keep-connection ]
[ -exit-on-change ]
[ -batch ]
[ -verbose ]
Argument Description
-cmd script Specifies a command file. The file must be a script or other program that
expects arguments in the form of one or more space-delimited version
numbers. For more information, see “Usage” and “Examples”.
-state-file filenam Specifies a file that contains the start time of the polling. When this
e argument is specified, the state file is updated by the command program.
This means that, for example, you can monitor a repository for a day
Argument Description
and then stop. When you resume monitoring again, the state file will
contain date and time information from your previous session so that
you can resume where you left off.

If you specify a file that is not present, the command will create it.

For an example of how to format the start date, see “Usage”.

-poll-interval t Specifies in seconds the time to wait between polls. The default
is 60 seconds.
-poll-limit n Specifies the number of poll intervals to iterate before the polling
program stops. The default is 0, which means that the command will
poll continuously.
-watch-list paths | You can specify either or both of these arguments:
-watch-file filena
me  -watch-list — Specifies a space-separated list of paths to watch.
If a project is specified, the command monitors all objects in that
project.
 -watch-file — Specifies a file containing the objects to monitor.
The objects must be placed one object per line.

-tags Monitors updates to tags. Requires repository format version 17 or

higher.
-keep-connection By default, the command does not maintain a connection to the
repository during the poll interval specified by the -poll-
interval argument. Use this argument to override the default behavior.
We recommend that you set this argument if your polling time is less
than 1 minute.
-exit-on-change Stops polling when the first change is detected.
-batch Passes to a script all version numbers with changes that were detected
during a single poll iteration. By default, the script is executed once for
every version encountered. For an example, see “Examples”.
-verbose Prints verbose command output, including poll count messages.
SUGERENCIA:

The alias for this command is air poll-for-change.

Usage
The script or program that is passed with the -cmd argument must take an input argument in
the form of “repository_version_number ” — for example, 303 followed by a space.

The optional state file should specify the start date and time in this format: YYYY-MM-DD
HH24:MM:SS — for example, 2017-06-05 13:50:29.
If you specify an object to monitor that isn’t under source control, this air command will
generate an error similar to the following:

---------------------------------------------------------------
path (or contents): Object is not under source code control

The immediate usefulness of any output that the command generates depends on the
program that you pass to the -cmd argument. The resulting output can be highly descriptive
and complete, or it may provide only the version numbers for changes, which you can then
use to obtain more information or share with others. The choice will depend on your
environment and application requirements. For examples, see “Generating useful output”.

If you run air object poll-for-change -cmd with the -tags argument and also specify a file
that is under source control using -watch-list path, for example, script will run if either tags
or objects change. You do not need to have a change to both a tag and an object
for script to run — either one invokes the script.
Examples
Following are a series of examples that illustrate how to use the repository object polling
feature. Unless stated otherwise, these examples use a command file, poll-cmd.ksh, which
contains a repository version number as an argument. The file contents are the following
(note that there is a required space after the version number parameter $1):

#! /bin/ksh
air version-info $1 > for_mailing
mail -f for_mailing -u team_admin

In this example, the output of the command is mailed to an administrator.

Polling with a watch list and no state file
This example uses the poll-cmd.ksh command file to supply a version number, in this
case, 3. The command alias air poll-for-change polls the project /Project/proj1 in 2-second
intervals for a total of 20 polls before terminating. Using the -verbose argument,
the air command writes the polling output to the file poll-output.txt. The full command is
the following:

air poll-for-change -cmd poll-cmd.ksh -poll-interval 2 -watch-list /Projects/proj1 -poll-limit 20 -

verbose > verbose.txt

While the command was polling the project, two new objects were checked in. The
contents of the command’s resulting output file are the following:
cat poll-output.txt
changes in 2 versions detected.
9 2017-06-05 15:54:51 main ktomlinsoni
1 Command(s):
air:project:import air project import /Projects/proj1/dml/a1.txt -basedir
/u/mkatz/sandbox/dml
1 Object(s):
A /Projects/proj1/dml/a1.txt
10 2017-06-05 15:54:57 main ktomlinsoni
1 Command(s):
air:project:import air project import /Projects/proj1/dml/b1.txt -basedir
/u/mkatz/sandbox/dml
1 Object(s):
A /Projects/proj1/dml/b1.txt
Polling loop 1 completed.
Polling loop 2 completed.
Polling loop 3 completed.
...
Polling loop 20 completed.

In this example, two DML files were checked in representing repository versions 9 and 10.
Messages for each successful polling interval are shown when you use the verbose mode.

Using batch monitoring

The -batch argument assembles repository versions representing changes to the objects that
you are monitoring and passes them to the script or program associated with the -
cmd argument as a group. It runs the script or program only once for a polling interval,
instead of once for each version.

air poll-for-change -cmd batch-cmd.ksh -poll-interval 4 -state-file state_file -batch -watch-list

/Projects/proj1 -verbose > poll-output.txt

The output file for this command shows that there were four changes made to the
monitored project /Projects/proj1. Versions 24 and 25 were passed as a batch to the
command script batch-cmd.ksh, as follows:

cat poll-output.txt
changes in 4 versions detected.
./batch-cmd.ksh 24 25
Polling loop 1 completed.
Polling loop 2 completed.
...
Polling loop 8 completed.
Polling loop 9 completed.
changes in 1 versions detected.
./batch-cmd.ksh 33
Polling loop 10 completed.
Polling loop 11 completed.
...
Polling loop 19 completed.
Polling loop 20 completed.
[1] + Done air poll-for-change -cmd batch-cmd.ksh -state-file temp_state_file -batch -
watch-
list /Projects/proj1 -poll-limit 20 -verbose > poll-output.txt
host$ cat temp_echo.ksh

Specifying multiple projects with a watch file

This example shows how to use a watch file with the -watch-file argument to specify
multiple paths to monitor. For this example, the contents of the command file my-
cmd.ksh are the following:

#! /bin/ksh
echo $0 $1 $2

The contents of the input file watch-file are /Projects/proj1 and /Projects/proj3, each on a
separate line, as follows:

/Projects/proj1
/Projects/proj3

The full command is the following:

air poll-for-change -cmd my-cmd.ksh -poll-interval 2 -state-file state_file -watch-file

watch-file -verbose

While the command was polling, the following changes were made to the specified
projects:

air project import /Projects/proj1/dml/a1.dml -basedir /u/mkatz/sandbox1/dml

air project import /Projects/proj1/dml/d1.dml -basedir /u/mkatz/sandbox1/dml
air project import /Projects/proj3/dml/dirA/a2.dml -basedir /u/mkatz/sandbox2/dml

The command’s output is the following:

changes in 2 versions detected.

./my-cmd.ksh 18
./my-cmd.ksh 19
Polling loop 1 completed.
Polling loop 2 completed.

The versions displayed with the air repository version-info command show the following
changes:

air repository version-info 18 19

18 2017-06-05 16:40:52 main ktomlinsoni
1 Command(s):
air:project:import air project import /Projects/proj1/dml/a1.dml -basedir
/u/mkatz/sandbox/dml
1 Object(s):
A /Projects/proj1/dml/c1.dml
19 2017-06-05 16:40:57 main ktomlinsoni
1 Command(s):
air:project:import air project import /Projects/proj1/dml/d1.dml -basedir
/u/mkatz/sandbox/dml
1 Object(s):
A /Projects/proj1/dml/d1.dml

(The checkin to the /Projects/proj3 project, which was also being monitored, occurred
outside of the polling period shown.)

Specifying a branch
To establish monitoring on a branch, you can use the -branch argument that is available to
all air commands. In the following example, the command monitors changes on branch2 for
a series of projects that are listed in my-watch-file:

air -branch branch2 poll-for-change -cmd version_details.ksh -keep-connection

-watch-file my-watch-file
Generating useful output
You can program the intended actions in the script or program that you pass to the -
cmd argument. Your script or program determines whether your output is descriptive of
repository changes captured by the command or shows only the version numbers, which
you or another can use later to explore the details further. This topic shows two simple
input scripts that illustrate two possibilities.

The first script, poll-details.ksh, contains the following:

#! /bin/ksh
air version-info $1

Within the script, the parameter $1, which will hold the version number, is followed by a
space, as the air command requires. The air poll-for-change command passes to the script
the version number at which a change was detected for an object being monitored. The
script then runs the air repository version-info command with the version number that was
passed to it. The air repository version-info command provides robust output information
about the repository changes. The following sample output shows that while the script was
running, several checkins occurred:

air poll-for-change -cmd poll_details.ksh -poll-interval 2 -state-file temp_state_file -watch-file

temp-watch-file -poll-limit 2 -verbose > polling-output.txt
...
air reposit text -string "test2" /Projects/proj1/dml/a1.txt
air reposit text -string "test3" /Projects/proj3/dml/dirA/a2.txt
...
cat polling-output.txt
changes in 4 versions detected.
38 2017-06-06 16:57:23 main ktomlinsoni
1 Command(s):
air:project:import air project import /Projects/proj1/dml/notfound.txt -basedir
/u/mkatz/sandbox/dml
1 Object(s):
A /Projects/proj1/dml/notfound.txt
39 2017-06-06 16:57:29 main ktomlinsoni
1 Command(s):
air:project:import air project import /Projects/proj1/mp/a7.mp -basedir
/u/mkatz/sandbox/dml
1 Object(s):
A /Projects/proj1/mp/a7.mp
40 2017-06-06 16:57:34 main ktomlinsoni
1 Command(s):
 air:project:import air project import /Projects/proj1/dml/foundagain.txt -basedir
/u/mkatz/sandbox/dml
1 Object(s):
M /Projects/proj1/dml/foundagain.txt
41 2017-06-06 17:11:02 main ktomlinsoni
1 Command(s):
air:project:import air project import /Projects/proj1/mp/a14.mp -basedir
/u/mkatz/sandbox/dml
1 Object(s):
A /Projects/proj1/mp/a14.mp
Polling loop 1 completed.
changes in 1 versions detected.
46 2017-06-07 12:20:06 main ktomlinsoni
1 Command(s):
air:project:import air project import /Projects/proj1/dml/a1.txt -basedir
/u/mkatz/sandbox/dml
1 Object(s):
M /Projects/proj1/dml/a1.txt
Polling loop 2 completed.

The second script, poll-echo.ksh, contains the following:

#! /bin/ksh
echo $0 $1 $2

The air poll-for-change command passes as parameters to the script, one, two, or three
version numbers at which changes were detected. The script then prints the output to
standard IO. In this case, each time the script is run, the command appears in the output
with the version number used, as follows:

air poll-for-change -cmd poll_echo.ksh -poll-interval 2 -state-file

temp_state_file -watch-file temp-watch-file -poll-limit 2 -verbose
...
air reposit text -string "test2" /Projects/proj1/dml/a1.txt
air reposit text -string "test3" /Projects/proj3/dml/dirA/a2.txt
...
cat polling-output.txt
changes in 2 versions detected.
./my-cmd.ksh 47
./my-cmd.ksh 48
Polling loop 1 completed.
Polling loop 2 completed.
You can use the air repository version-info command to investigate the changes as is shown
in the example “Specifying multiple projects with a watch file”.
Polling for a new tag
This example shows the creation of a script that air poll-for-change runs. Within the script,
the parameter $1 is the version number that air poll-for-change produces.

The input script temp_details.ksh contains the following details:

! /bin/ksh
air version-info \$1 -all-objects

Within the script, the parameter $1, which will hold the version number, is followed by a
space, as the air command requires. The air poll-for-change command passes to the script
the version number at which a change was detected for an object being monitored. The
script then runs the “air repository version-info” command with the version number that
was passed to it.

The following command polls for a new tag:

air poll-for-change -cmd temp_details.ksh -poll-interval 2 -keep-connection -state-file

temp_state_file -tags -poll-limit 2 -verbose > temp-test-output.txt &
sleep 12

The following sample output shows the results for polling when the -tags argument is used.
The output shows that while the script was running, a change in 1 version was found:

changes in 1 versions detected.

25 ** main *
1 Command(s):
air:tag:create air tag create tagZ /Projects/proj1
3 Object(s):
M /abinitio/tags
A /abinitio/tags/tagZ
M*

air object referencing-files

Displays the paths to all objects (top-level objects and subobjects) that use the specified
target object. This command is branch-specific. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.

NOTA:

This command was formerly called air object uses, and it still works as an alias.

Syntax
air object referencing-files rpath
[ -top-level ]
[ -single-column ]
Argument Description
rpath Path to the target repository object.

-top-level Displays a single-column list of only the top-level objects that use
the target object. If omitted, the display shows subobjects as well.
-single-column Displays the full paths to all objects that use the target object rpath.
The display is a single column. If omitted, the display is two
columns.
Usage
Before running this command you must successfully run dependency analysis on all objects
that use rpath (the target object). Before analysis, the information required by this
command is not stored in the technical repository. See “Análisis de dependencias” in the
Co>Operating System Guía para desarrolladores de grafos.

By default, the output display is two tab-separated columns: the top-level source object,
followed by the using subobject (for example, a port within a graph). If there is no
subobject, the second column is empty.
Alias
The alias for (and former name of) this command is air object uses.
air object requires
Creates, modifies, or clears a list of additional files that are considered required by the
graph and will be promoted with the graph when you load a save file created through air
object save. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air object requires rpath
 { -add rpath ...[ -force ] | -remove rpath ... | -clear } [
-show ]
Argument Description
rpath Full path to a graph that requires other files to be promoted
with it. If the graph is in a project, the path should be
parameterized so that it is valid in both the filesystem and the
technical repository. Note that you must place single quotes
around rpath to avoid having the parameterized expression
interpreted by the shell.
-add rpath ... [-force] Choose one of the following:
| -remove rpath ... | -clear
 -add rpath — adds one or more files to the list of
additional files required by the graph. If the file does
not exist, use the -force option.

-force — adds entries to the list of required files, even

if they do not exist. Also allows you to change the
required files list on objects that are not graphs (but
this is not recommended).

You must use -force with a plan.

 -remove rpath — removes one or more files from the

list of additional files required by the graph. You can
remove only the files you have explicitly added, not
files automatically determined by the system.
 -clear — removes explicitly added files from the list
of additional required files.

-show Displays the list of additional required files after you have
added or removed files.
Usage
Ordinarily, when you promote (air promote save or air object save), check in (air project
import), or check out (air project export) a graph or plan, the system automatically
determines which files need to be transferred with the graph or plan for it to run. However,
there are times where you must manually inform the system about other files that should be
promoted or checked in and out with the graph or plan. For example, the start script for a
graph might reference a shell script, which means that the shell script must be promoted
into production along with the graph itself.

The air object requires command creates a required_files parameter for the graph and sets
its value to the list of required files created by the command. To see the parameter in the
GDE, check out the graph. You can also edit this parameter in the GDE to change the list of
required files. Alternatively, you can create a required_files parameter directly in the GDE
and specify one or more required files. To specify multiple files, separate them with a
newline.

Before promoting or checking a graph or plan in or out, run air project get-required-files to
display the list of files that will be transferred along with it. If the list is incomplete or
incorrect, run the air object requires command to add files to or remove files from the list of
required files.
Example
To promote a shell script referenced in the start script for the JoinCustomers graph and
display the list of explicitly added files, type:

air object requires /Projects/warehouse/mp/JoinCustomers.mp \

-add '$RUN/JoinCustomersStart.ksh' -show

Alias
The alias for this command is air requires.

air object rm
Marks the specified object as removed from the current version of the technical repository.
It also removes objects from projects. This command is branch-specific. For information
about the arguments common to all air commands, see “Command-line syntax of air
commands”.
Syntax
air object rm [-f] [-r] [-no-project-remove] rpath
Argument Description
-f Suppresses error if rpath does not exist.
-r Recursively removes the subdirectories of rpath.
-no-project- Removes the object without removing it from source code control.
remove
rpath Path to the directory entry, or object ID, you want to remove.
See “Specifying object names as arguments”.
Usage
This command removes the specified object from the directory at the current version, but
older versions of the object remain in the technical repository. For example, running air
ls on the object shows that the object is not present at the current version.

Nonversioned objects, such as jobs, are removed completely, and their space is recovered.
You can access an object that has been removed by air object rm through commands that
specify a version of the repository in which the object did exist. At earlier versions of the
repository the specified object and its relationships are still present. For example,
running air ls with the -version option will show the object at the specified version.

To eliminate older versions of a removed object, run air purge object, specifying the
domain number of the object. air object purge deletes all versions of an object.
Alias
The alias for this command is air rm.

air object rollback

Makes the specified version the current version in the technical repository. Use to back out
changes such as a destabilizing change or a version that was mistakenly checked in. This
command can also be used to restore a deleted object. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air object rollback [-dry-run]
[-ignore-missing]
-to-version version rpath {rpath...}
Argument Description
-dry-run Reports any changes or errors that would occur if the rollback operation
were tried, but does not actually perform the rollback.
-ignore-missing Overrides missing object reference errors if the objects being rolled back
reference additional objects that are not present at the current version.
These references may be critical; use this option with care. For more
information, see “Usage”.
-to-version versi Specifies the version to use as the current version. Enter a numeric
on version, a repository-wide tag (or rtag such as those created by air
repository tag), or a date/time. Tags such as those created by the air
tag create command are not supported.
rpath ... Specifies the path to the earlier objects that you want to rollback to. To
roll back a removed object, see “Usage”.
Usage
To restore a deleted object to the latest version prior to its removal, you specify the path to
the object, as follows:

air object rollback rpath

To restore an older version than the one prior to removal, you must specify the version
number at which it was deleted, as follows:

air object rollback @1.1.version-number/rpath

To roll back multiple rpaths, you must specify the -to-version argument, as follows:

air object rollback -to-version version @1.1.version-number/rpath

Identifying versions
In some cases, you may not want to replace a removed object just prior to the removed one.
You can use the air object versions command or the Technical Repository Management
Console (TRMC) Versions tab to identify the desired version number. For example, you
can use the tab to browse for the repository path of the directory that contains the deletion.
Alternatively, if the user who deleted the object is known, you can filter the view by
specifying the username and then search those versions.

To roll back to a previously removed object, enter the following syntax for the value
of rpath:

air object rollback -to-version version @1.1.version-number/rpath

In the syntax above, @1.1 denotes domain 1 (which is the root directory) and object 1.
From this starting position, the command uses version-number and rpath to identify the
correct object. For an example, see “Restoring a removed object” in the Examples.
Identifying domain numbers
To identify a domain number if needed, run the following command. The domain number
will appear in the output:

air details @1.1.version-number/rpath

Once you have the domain number, you can enter the following:

air details @1.1.version-number/rpath

For more information, see “air dump details”.

 Rolling back common projects and sandbox objects
If a project references a common project that is removed in the current version, this
command generates an error and will fail. You will get the same error for an annotation that
references an object that is outside the project that has been removed. To continue with the
rollback in these cases, use the -ignore-missing argument. You may want to use this option
to temporarily investigate the earlier version by rolling back to this version in your
sandbox. However, as a best practice, we do not recommend using this option without first
determining whether removing the referenced objects will be an issue. Do not use the -
ignore-missing argument in any scripts, where potential issues can easily be overlooked.

To rollback an object to a sandbox, use air sandbox rollback.

Examples
Rolling back objects
To roll back an entire project to an earlier version:

 Enter the following:

air object rollback -to-version 633 /Projects/Test4

To roll back an object to an earlier version:

 Enter the following:

air object rollback -to-version 633 /Projects/Test4/.project.pset /Projects/Test4/xfr

To roll back all objects in a directory to an earlier version:

 Enter the following:

air object rollback -to-version 633 /Projects/Test4/xfr

Restoring a removed object

To restore a specific version of a removed object:

 Enter the following:

air object rollback -to-version 492 @1.1.492/Projects/sandbox-demo/mp/graph1.mp

 This example uses the @domain.object.version notation in front of the path to specify the
exact version in which the object existed — 1.1.492.
Overriding missing reference object errors
This example use the project /Projects/als5, whose referenced common
project /Projects/my_common and annotation /Annotation_Values/anno_4 have been
moved to different directories in the most current version. If you try to roll back to
version 17, the command will generate an error similar to the following:

Command Failed: air object rollback -to-version

17 /Projects/als5
----------------------------------------------------------------
The following referenced objects are not present at the current
version.Consider rolling back:
[/Annotation_Values/anno_4, /Projects/my_common]

Using the -ignore-missing argument overrides the error and proceeds with the rollback
despite the missing files. Because this argument removes files, before using this command,
investigate whether removing the files will cause a problem.

To override missing reference errors:

 Enter the following:

air object rollback -to-version 17 -ignore-missing /Projects/als5

air object rollback-version

Restores modified objects to a state prior to their promotion or checkin. This command
identifies objects that were modified at the specified repository version, finds
their prior versions, and rolls back the promotion or checkin to that prior version. If the
objects were added at the specified version, then the command removes them at the current
version. Use this command to back out promotions, checkins, or other unintended version
level changes. You can also exclude specific objects from the version rollback. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air object rollback-version
 [-dry-run]
[-exclude rpath { -exclude rpath ... } ]
[-force]
version
Argument Description
-dry-run Reports any changes or errors that would occur if the rollback operation were
tried, but does not actually perform the rollback.
-exclude Specifies the paths of objects that should not be rolled back.
-force Ignores conflicts. By default, the command reports a conflict error if an object
that was updated at the specified version was also modified later. Use this
argument to ignore the error and continue the rollback.
version Specifies the version of the objects that you want to rollback. The value can be
a numeric version, a tag name, or an rtag name (which was created with the air
repository create command). For more information, see “Usage”.
Usage
Use this command when you want to back out a specific incorrect checkin, a flawed
promotion, or other unintended repository change. You specify the version at which the
error occurred in order for the command to revert to the prior version. If the value
of version is the name of a tag, then the tag must tag objects at a single version. (This
would be the case with a tag that was created by promotion or a checkin.) When you run
this command, it removes the tag, which can be useful when you are rolling back a
promotion.

NOTA:

This command works on versions or promotion tags only. This command rolls back the
version at which the tag was created; it does not roll back the actual checkin.

Example
This example uses the /Projects/Provolone sandbox as an illustration of the air object
rollback-version command. :

This example of a dry run tests a rollback to version 1543 erroneous checkins made to the
repository at version 1544. In doing so, the test run uncovers the fact that a user checked in
the vendor-xform.xfr file after the erroneous version 1544. This creates a potential file
conflict that should be investigated. If appropriate, as shown in this example, the file can be
exclude from the rollback:

air object rollback-version -dry-run 1544

Rollback: Conflict with update to @1.1.1544/Projects/Provolone/dml/vendor.dml at version 1545
Command Failed: air object rollback-version -dry-run 1544
----------------------------------------------------------------
Conflict: the following objects were updated after the rollback version.
Consider excluding:
[@1.1.1544/Projects/PRs/PR116457/dml/vendor.dml]
air object rollback-version -dry-run -exclude /Projects/Provolone/dml/vendor.dml 1544
Rollback: Excluding @1.1.1544/Projects/Provolone/dml/vendor.dml

Usage
This command is used with air object load to:

 Promote projects to another technical repository. For a complete description of

using air object save and air object load to promote projects, see “Promoting
applications” the Technical Repository Guide to Version Control.

When using air object save, make sure that AB_AIR_ROOT points to the source repository,
or use the -root option (see -root) to specify the repository root explicitly.

Unlike air promote save, air object save does not compress the contents of the save file.
This is for compatibility reasons.

NOTA:

To back out changes to the current version of a technical repository by restoring earlier
versions of modified or removed objects, use air object rollback. For more information, see
that command in this Reference and “Restoring an earlier version” the Technical
Repository Guide to Version Control.

Standard input and standard output

This command accepts - (instead of rpath) to read paths from standard input.
See “Commands with repeatable arguments”.

It writes progress messages to standard output, unless you specified - as filename. To

change the default behavior, set AB_AIR_SAVE_LOAD_LOG_TO_STDERR to true.
Overriding which files are saved by default
By default, the command saves the specified object and all its required objects within the
same project, but not in common projects. For example, the .dml and .xfr files associated
with a graph are included automatically in filename if they are in the same project as the
graph. If they reside in a common project, however, they are included only if you specify
the -include common clause.
By default, the command does not save objects in /abinitio. If you need to promote the
objects in /abinitio, you must explicitly save the root project or a file in it.

Other files associated with a graph — for example, scripts invoked by start and end scripts
— are not ordinarily saved. You must specify these files in
the -include rpath or -external erpath clause.

Common project record formats are referenced by graph parameters; there is no physical
link from graphs to record formats in common projects. As a result, the command does not
consider these external references (and does not show them in the output). The only
exception is when the command saves a dataset that points to a record format in a common
project. (In versions lower than Version 2.14 common project record formats were stored as
relations; air object save saved these as external references, which were shown in the
output.)
Using the -exact tag and -from-tag options
As of Version 2.15, we recommend using the -exact-tag argument, as this functionality is
consistent with that of the Technical Repository Management Console.

If you tag a project or a graph, the parameters file (.air-project-parameters or .project.pset)

is automatically included in the tag. In this case, there is no need to specify
the -settings argument. If you want to promote only a project’s parameters, just tag the
parameters file and specify the -exact tag tag argument to air object save.

You can use both the -from-tag and rpath arguments in the same specification. You can
specify only one -from-tag option at the command line. Note that if you specify -from-
tag tag, the project parameters will not be saved even if the tag includes the parameters file.
We recommend that you use -exact tag tag instead.
Creating and displaying the promotion history
If you use the -exact-tag or the -from-tag options, this command creates a promotion
history. To display the promotion history created by air object save, run air promote list.

If the Technical Repository administrator has enabled the Require Promotion History
option (air repository options +require-promotion-history), any errors encountered while
creating the promotion history will cause the save operation to fail.
Interobject references
The -include and -external options determine how interobject references are handled, such
as those between a graph and its .dml or .xfr file. You can either include the referenced
objects in filename using the -include option, or create an external reference to the
referenced object using the -external option. The external reference is resolved
when filename is loaded.
-exclude has a higher precedence than -include and -external. Thus, if an object is both
excluded and included, it is excluded from the save file. The -settings option is independent
of these other three.
Promoting modifications
Once you have promoted a project, use air tag create and air save to promote only those
objects that have changed since you last tagged and saved them; you do not need to keep
track of which objects have changed. First retag the modified project (assume it’s
called myproject and today’s date is December 15, 2016):

air tag create myproject-2016-12-15-release /Projects/myproject

Next save the project in a save file, but this time use the -from-tag or -exact-tag arguments
with the -since tag option to save only those objects that have changed since you checked in
your modifications and tagged the project as myproject-2016-12-02-release:

air object save mysave.save \

-exact-tag myproject-2016-12-15-release \
-since myproject-2016-12-02-release

Loading the save file

You can subsequently promote the objects in the save file, filename, to another technical
repository by running air object load or air promote load. If you try to load an object saved
in an out-of-date format, air object load displays an error message specifying which format
should have been used.
Examples
Saving an entire project
To save the entire lesson project, which uses the common common project, to
the myproj.save file, type:

air object save myproj.save /Projects/lesson/ \

-external /Projects/common

Saving tagged objects

You use air tag create to create a tag mystuff for project1, graph1.mp, and foo.dml. Then to
save these tagged objects in the myfile.save file, type:
air object save myproj.save -from-tag mystuff

Alias
The alias for this command is air save.

air object search grep

Searches a technical repository for files that contain the specified search string and returns
the repository path for each file that contains a match. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air object search grep repository-path [search-string]
[[ -mime-type mime-type] [-name name] ...]
[-exact]
[-verbose]
Argument Description
repository-path Specifies the file or directory that you want to search in the technical
repository.
search-string Specifies the string that you want to search for. Results returned for a
search string without additional arguments can include matches for both
file names and file content.
-mime-type mime Specifies a MIME type object to search for. The project that contains the
-type object determines its MIME type. For more information, see “Project
files list” and “Usage”.
-name name ... Searches only in directories and files whose names contain the specified
string. You can specify multiple names to search by repeating the -
name argument.
-exact Overrides the default behavior and requires case-sensitive matching.
-verbose Reports the objects whose names and contents are being searched,
regardless of whether a match is found.
Usage
By default, matching is not case-sensitive.

Searches are faster when you filter the files by name or MIME type, because fewer object
contents must be examined.
Examples
In the following example, the air command searches for the java_release_handle function in
all objects found under the /Projects/hadoop repository project path:

air object search grep /Projects/hadoop java_release_handle

The following example uses the MIME type argument to search for
the java_release_handle function in all transform files and graphs found in
the /Projects/hadoop repository project path:

air object search grep /Projects/hadoop java_release_handle -mime-type xfr -mime-type graph

Related topics

 air object search parameter

 air sandbox search parameter

air object search parameter

Searches one or more technical repository paths for a given parameter name. Based on the
arguments that you supply, the command can return parameter declarations and definitions,
as well as references to the parameter. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air object search parameter repository-path [repository-path ...]
parameter-name
[-declaration-pset decl-pset]
[-decl -def -ref -all]
[-required]
[-m]
Argument Description
repository-path Specifies one or more repository paths to a graph, plan, or pset file, or
directory that you want to search. If the value of repository-path is a
directory, the command recursively searches all objects in repository-
path or its subdirectories.
parameter- Specifies the name of the parameter that you want to search for. This
name argument must be placed after all path specifications.
-declaration- Filters the results to show only the objects that match the parameter-
pset name declaration in the specified pset. When this argument is included,
Argument Description
the command ignores definitions, references, and so on that have the same
name, but that are for a different declaration.
-decl -def -ref - Limits or filters the results. Use one or more of these arguments as
all follows:

 -decl — Displays any declarations of parameter-name.

 -def — Displays any definitions of parameter-name.
 -ref — Displays any references to parameter-name.
 -all — The default. Displays any matching declarations,
definitions, or references. This is the equivalent to setting -decl -
def -ref.

-required Also searches for matches in all files that are required by respository-
path. This argument is equivalent to the air sandbox get-required-
files path command.
-m Displays any results in a concise, machine-readable format without
headers.
Usage
When you run the air object search parameter command, note the following:

 Matching is case-sensitive for both the parameter name and the optional pset.
 If no matches are found, the command generates a warning that no matches were
found.
 If the repository-path specifies a directory and the command finds no matching
graphs, plans, psets, and so on, then the command issues a warning that no objects
were found.

Examples
In the following example, the air command searches for the FOO parameter in all objects
under the /Projects/hadoop project:

air object search parameter /Projects/hadoop FOO

In the following example, the air command searches for the FOO parameter in a single
graph:

air object search parameter /Projects/hadoop/mp/one_graph.mp FOO

In the following example, the air command searches for the FOO parameter in a single
graph, as well as in all files that graph requires. It filters the result to show only matches
that are references:

air object search parameter /Projects/hadoop/mp/one_graph.mp FOO -required -ref

In the following example, the air command searches the specified project and all required
files for references to the BAR parameter that are declared in .project.pset:

air object search parameter /Project/hadoop BAR -required -ref -declpset

/Project/hadoop/.project.pset

Related topics

 air object search grep

 air sandbox search parameter

air object set-acl

Sets or modifies the ACL (access control list) permissions on one or more specified objects.
Use to provide a finer level of control on objects and directories than Unix or users and
groups permissions provide. This command is object-specific rather than branch- or
repository-specific. You must be an administrator or owner to use this command. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.

NOTA:

This feature requires Co>Operating System Version 3.3.3 or later and technical repository
format 19 or higher. Some earlier versions of the Co>Operating System offered a group of
undocumented and unsupported air acl commands. These have been removed.

Syntax
air object set-acl [ -R ] path [ -exact ] [ -readonly ]
[ -remove-all | { permission user-list ... } ... ]
Parameter Description
-R Sets the ACL for the rpath object that follows. If that object is a directory,
recursively sets the ACLs on any objects contained in that directory.
path Specifies the repository path to an object or directory in the repository.
Parameter Description
-exact By default, all changes to ACLs modify the existing permissions. When
specified, the ACL permissions will conform to the exact specifications that
you supply to the command.
-readonly Removes write permissions from the specified object. Users or groups who
have write access lose write access and gain read access.
-remove-all Removes all ACLs from the object, restoring the normal Unix-style
permissions.
permission Specifies the ACL permissions to apply to the specified objects. You can enter
the following:

 +read — The user or group can view the value of the specified object.
 -read — The user or group cannot view the value of the specified
object.
 +write — The user or group can edit the values of the specified object.
 -write — The user or group cannot edit the value of the specified
object.

NOTA:

There is no concept of execute permission in the technical repository.

user-list Specifies a list of users or groups to which you want to apply ACL permissions. Specify
group names as group=group_name. Separate multiple users or groups with a space.

SUGERENCIA:

The alias for this command is air set-acl.

Usage
 Permissions are additive. Users and groups are given the maximum permissions
assigned to them.
 You cannot use the -exact argument with -read or -write. In this case, the command
ignores the permissions values because you cannot perform a subtractive override.
 To view ACLs, use the air object show-acl command, the Technical Repository
Management Console, or the Technical Repository Web Interface.
 To remove all permissions on an object, rendering it inaccessible, enter the
following command without specifying any permissions:

air object set-acl path -exact

 When you remove ACLs on an object using the -remove-all option, the object
reverts to Unix-style permissions. You must then use air object chmod if you want
to set special permissions on the object.
  If an object has a sticky bit set and you add ACL permissions, the ACL permissions
will be inherited. If you add a new object to a directory, it will inherit the ACL
permissions.
 If you run the air object chmod command against an object that has ACL
permissions, the command will work. However, the Co>Operating System ignores
the bits affected by the chmod command when ACLs are present.

Examples
These examples show some useful applications for the air object set-acl command.
Applying ACLs recursively on a directory and adding a user
This example applies ACL permissions to a directory and applies the ACLs recursively to
the objects that the directory contains. The /Projects/proj4CT/dml directory is restricted to
read-write access for the owner, cotesti. The following command adds the
user ktomlinsoni and grants her write permissions; air object show-acl confirms the change:

air object set-acl /Projects/proj4CT/dml -R +write ktomlinsoni

air object show-acl /Projects/proj4CT/dml
+write cotesti ktomlinsoni

Restoring Unix-style permissions

This example sets ACL permissions and then uses the -remove-all argument to remove
them and restore the Unix-style permissions. First, it grants read access to the
groups staff and world, respectively. The administrator, ktomlinsoni retains write access:

air object set-acl /Projects/proj3 +read group=staff group=world

air show-acl /Projects/proj3
+read group=staff group=world +write ktomlinsoni

After you use the air set-acl command with the -remove-all argument, the air show-
acl command shows the original Unix-like permissions. The message from mode bits in the
output indicates that the permissions shown are no longer ACL permissions:

air set-acl /Projects/proj3 -remove-all

air show-acl /Projects/proj3
(from mode bits) +read group=world +write group=staff ktomlinsoni
Using the -exact argument
This example compares the default ACL permissions behavior that the air object set-
acl command produces with the results that you get when you specify the -exact argument.
The -exact argument applies only the permissions that you supply to it, rather than first
building upon any prior ACLs or Unix-style permissions. Therefore, some permissions can
be removed when -exact is specified.

1. Starting permissions

At the start of this example, the two projects have owner read and write permissions, and
group read and write permissions, while the group other (world) has only read permissions.
The following air object show-acl command illustrates this:

air object show-acl /Projects/proj0 /Projects/proj1

(from mode bits) +read group=world +write group=staff ktomlinsoni
(from mode bits) +read group=world +write group=staff ktomlinsoni

The (from mode bits) message in the command output indicates that these permissions
are not ACL permissions.

2. Adding ACLs with and without the -exact argument

Next, we add ACL permissions to /Project/proj0 and /Project/proj1. The first command
assigns ACLs to two users, cfordi and jfilreiso, for the project /Project/proj0.

air object set-acl -R /Projects/proj0 +write cfordi -write jfilreiso

The second command assigns the same ACLs to the one of the users of the
project /Project/proj1. However, this command includes the -exact argument, which applies
the permissions literally, rather than modifying the prior Unix-style permissions:

air object set-acl -R -exact /Projects/proj1 +write cfordi

In the -exact argument example, the -write argument was not included for the user jfilreiso.
This is because subtractive arguments can’t be used with the -exact argument. Had the
subtractive argument been provided, the command would have simply ignored it.

3. Resulting permissions
Looking again at the resulting ACL permissions shows that the first command just
modified the existing permissions, while the command with the -
exact argument removed the existing staff and world group permissions because they were
not specified in the air command, as follows:

air object show-acl /Projects/proj0

+read group=world +write group=staff cfordi ktomlinsoni
air object show-acl /Projects/proj1
+write cfordi

air object show-acl

Displays the ACL permissions for one or more specified objects. This command is object-
specific rather than branch- or repository-specific. You must be an administrator or owner
to use this command. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.

NOTA:

This feature requires Co>Operating System Version 3.3.3 or higher and technical
repository format 19 or higher.

Syntax
air object show-acl [ -R ] path ...
Parameter Description
-R Displays the ACL permissions for the specified rpath object. If that object is a
directory, recursively displays the ACLs on any objects contained in that
directory.
path Specifies the repository path to an object or directory in the repository.
Separate multiple paths with a space.
SUGERENCIA:

The alias for this command is air show-acl.

Usage
The output of this command is formatted so that it matches the syntax expected by the air
object set-acl command. It is possible to pass this command’s output to air object set-acl if
you want.
If you run this command against an object that uses Unix-style permissions — rather than
ACL permissions — the permission list will be preceded by the text (from mode bits).

If the ACL access on an object prohibits access to all users, the command will display (no
access).
Example
This example shows that the transform /Projects/proj4CT/xfr/shift-40.xfr has write ACL
permissions. This permission is available to all users in the group staff and to the
user cotesti, as follows:

air object show-acl /Projects/proj4CT/xfr/shift-40.xfr

+write group=staff cotest

air object show-permissions

Displays permissions for objects in a technical repository. This command is branch-
specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air object show-permissions [ -R ] { rpath }
Argument Description
-R Optional. Displays the permissions for the specified rpath object. If that object
is a directory, recursively displays the permissions on any objects contained in
that directory.
rpath Specifies the repository path to an object or directory in the repository.
Usage
Use this command to see permissions on the repository root (/). If you run air ls /, the
contents of the repository root directory are returned but not the permissions on the
directory.

Related topics

 air object ls
 “Displaying permissions, ownership, and related information”

Example
To see the permissions on all the objects contained within /Data, type:
air object show-permissions -R /Data

The output resembles the following:

These are the permissions for everything in /Data

Object: /Data
staff +read -write
world +read -write
mkatz +read +write
Object: /Data/mime1
staff +read -write
world +read -write
mkatz +read +write
Object: /Data/SubTwo
staff +read -write
world +read -write
mkatz +read +write
Object: /Data/SubTwo/mime4
staff +read -write
world +read -write
mkatz +read +write
Object: /Data/SubOne
staff +read -write
world +read -write
mkatz +read +write

air object versions

Displays the versions and tags for a single object or an entire technical repository. The
display includes version number, date, user, tag, and comments; as well as analysis
versions. This command is branch-specific. For information about the arguments common
to all air commands, see “Command-line syntax of air commands”.

NOTA:

To get the most use out of this command, we recommend that you use it with the -versions-
only argument to pass output to the air repository version-info command. For an example,
see “Version numbers output to air repository command” (below) and the air
repository documentation. This argument requires a storage format 15 or higher technical
repository.

Syntax
air object versions
[-quiet | [-no-tags] | [-checkins | -internal]]
[-descending | -ascending]
[-user username [-user username ...]]
[-branch branch [-branch branch ...]]
[-rtags-only]
[-m]
[-versions-only]
[-show-branches]
[rpath] | [-rpath-filter filter ...]
[version-range]
Argument Description
-quiet | -no-tags | -checkins | - You can specify one of the following:
internal
 -quiet lists only versions that are tagged or have
associated comments. If omitted, displays all
versions and tags for the object rpath or, if rpath is
omitted, for the entire technical repository.
 -no-tags lists all distinct versions of rpath but no
tag information.
 -checkins lists only those versions at which the file
was checked into a project. Changes that do not
affect the source code are not listed, for example,
changes made by dependency analysis. This is the
default behavior if rpath or -rpath-filter specifies an
object under source control.

To display all distinct versions that are checked

into a project, use this argument with the -no-
tags argument.

 -internal lists all distinct versions of files including

those that do not affect source control, such as
version changes made by dependency analysis.
This is the default if you do not specify an rpath or
if its value is not under source control.

For more information on these arguments and their default

behaviors, see “Usage”.
-descending | -ascending You can specify one of the following:

 -descending sorts the display with the most recent

Argument Description

version first.
 -ascending (default) sorts the display with the
earliest version first.

-user username You can specify one or more technical repository user IDs
to limit the output of this command. If the user ID is not in
the technical repository or the currently connected branch,
the command issues a User “username” not
found message.
-branch branch You can specify one or more branches to limit the output
of this command. If the branch is not in the technical
repository or the currently connected branch, the command
issues a Branch not found, branch name given
was branch message. When connected to a branch, you
can specify main as the value of branch to retrieve parent
information in the repository’s hierarchy. If the returned
result for a specific branch is empty, it means the branch
contains no new checked in objects.

NOTA:

This feature requires a storage format 15 or higher

technical repository.
-rtags-only This argument lists only those versions that are assigned
names by air repository tag.
-m Writes the command output in new-line delimited
machine-readable format to standard output. The output
does not include indentation or any header and trailer
information, such as the total number of members shown.
You can process the output in a graph. The DML format is
described in $AB_HOME/include/tr_versions.dml
-versions-only This argument limits the output to only version numbers,
each on a separate line. You can use this argument to pipe
the version numbers to air repository version-info. See
the “Version numbers output to air repository
command” example below.

NOTA:

This feature requires a storage format 15 or higher

technical repository.
-show-branches Displays an additional column containing the name of the
branch that each version is associated with. Default if you
Argument Description
specify -m.
rpath | -rpath-filter filter You can specify one or the other:

 rpath is a path to a repository object. If specified

without any other options, lists all versions of the
object.

If both rpath, -rpath-filter, and version-range are

omitted, all versions in the technical repository are
displayed. If both arguments are specified, version-
range applies to the specified rpath.

 -rpath-filter filter lists all versions of objects under

the specified (directory or project) repository
path filter.

NOTA:

Only changes on the current repository branch,

specified by AB_AIR_BRANCH, are considered.
Additional filtering with the -branch argument is
not supported.
version-range version-range can be -version, -from and/or -to, or -last:

 -version version-number specifies a single version.

 -from version-or-date specifies the first version to
display. It may be combined with -to. Specify a
date in the format "YYYY-MM-DD HH:MM:SS"
or "YYYY-MM-DD". This range is inclusive of the
specified version.
 -to version-or-date specifies the last version to
display. It may be combined with -from. Specify a
date in the format "YYYY-MM-DD HH:MM:SS"
or "YYYY-MM-DD". This range is inclusive of the
specified version.
 -last number specifies the number of most recent
versions to display.

If rpath, -rpath-filter, and version-range are omitted, all

versions in the technical repository are displayed.

If rpath or -rpath-filter and version-range are

specified, version-range applies to the
specified rpath. version-range filters other criteria such
as -rpath-filter or rpath.
Usage
The following default behaviors apply for rpath and -rpath-filter:

 If the object that you specify by rpath is under source control or you specify -rpath-
filter, by default this command displays source control-only versions and omits
internal versions such as those created by dependency analysis.
 If the object that you specify by rpath is not under source control, by default, this
command displays internal versions.
 If you do not specify rpath or -rpath-filter, then this command displays versions for
all objects in the repository — including internal versions.
 If the current version of the object that you specify by rpath was removed, this
command displays information for the versions prior to its removal.

The -check-ins argument was deprecated in Co>Operating System Version 3.3.2. It

displayed versions for all objects, including files that did not affect source control such as
dependency analysis.
Examples
Default arguments
When no arguments are specified, you see all versions of the graph — tagged and
untagged:

air object versions /Projects/lesson/mp/JoinCustomers.mp

The output might look like the following, showing the untagged versions 737 and 747 also:

Version Date User Tag Comment

737 2015-05-13 11:54:02 asmith
738 2015-05-16 14:55:50 asmith tag1
738 2015-05-16 14:55:50 asmith tag2
738 2015-05-16 14:55:50 asmith tag3
747 2015-05-16 15:10:40 asmith
748 2015-05-16 15:10:56 asmith tag4

Removed object
If the object specified by rpath has been removed, this command displays the historical
information associated with the object and a note stating that the object has been removed,
as follows:
air versions /dir1/A
Versions of @1.1.18/dir1/A [NOTE - Object has been removed]
Version Date User Tag Comment
16 2014-12-02 14:11:42 rsmith
17 2014-12-02 14:11:50 rsmith
18 2014-12-02 14:11:56 rsmith
19 2014-12-02 14:14:48 rsmith

Revision history of tagged object

To see the revision history of the tagged versions of graph JoinCustomers.mp, specify:

air object versions -quiet /Projects/lesson/mp/JoinCustomers.mp

The output might look like the following. Note that when -quiet is specified, the command
displays only tagged versions of the graph. You see version 738 three times, because it has
three different tags at that version.

Version Date User Tag Comment

738 2015-05-16 14:55:50 asmith tag1
738 2015-05-16 14:55:50 asmith tag2
738 2015-05-16 14:55:50 asmith tag3
748 2015-05-16 15:10:56 asmith tag4

Suppress tag information

Specify -no-tags to display only distinct versions of the object without tag information:

air object versions -no-tags /Projects/lesson/mp/JoinCustomers.mp

The output shows only four versions:

Version Date User Tag Comment

737 2015-05-13 11:54:02 asmith
738 2015-05-16 14:55:50 asmith
747 2015-05-16 15:10:40 asmith
748 2015-05-16 15:10:56 asmith
Single version
Specify a single version number to display information about that version:

air object versions -version 747

The output shows the date, users, tag, and comment for that version:

Version Date User Tag Comment

747 2015-11-10 22:48:55 asmith

Filter by user and branch

When connected to a branch, specify main to also retrieve parent information. This
command example further limits the output to the user ktomlinsonini.

air object versions -notags -user ktomlinsonini -branch main

Version numbers output to air repository command

This example first passes only the versions numbers for technical repository
versions 5 through 10 as output to the air repository version-info command:

air versions -from 5 -to 10 -versions-only | air repository version-info -commands -

5 2013-04-16 10:16:34 main ipahker
Objects
6 2013-04-16 10:16:37 main ipahker
Objects
8 2013-10-02 12:26:31 main ipahker
Objects
A /proj/.project.pset
A /proj/.project-start.ksh
A /proj/.project-end.ksh
A /proj/db
A /proj/dml
A /proj/mp
A /proj/plan
A /proj/resource
A /proj/run
A /proj/xfr
9 2016-05-05 13:36:48 main ipahker
Objects
10 2016-05-05 13:43:59 main ipahker
Commands
air:reposit:text air reposit text -string test /proj/test1
Objects
A /proj/test1

Modified object versions

This example shows changes to versions 20 and 22 underneath the path /Projects/foo, by
having imported foo-sand and moved agraph.mp from /Projects/bar to /Projects/foo. This
example also has changes to version 21, but those are underneath the path /Projects/bar.

air project import /Projects/foo -basedir foo-sand -auto-add -comment "check in changes to
/Projects/foo" # version 20
air project import /Projects/bar -basedir bar-sand -auto-add -comment "check in changes to
/Projects/bar" # version 21
air mv /Projects/bar/mp/agraph.mp /Projects/foo/agraph.mp # version 22
air object versions -rpath-filter /Projects/foo -from 20
Checkins
Version Date User Tag Comment
20 2017-10-10 13:29:54 bob checked in changes to /Projects/foo
22 2017-10-13 10:15:43 bob

The output of the command air versions -rpath-filter /Projects/foo -from 20 shows
versions 20 and 22, the versions that had changes to objects underneath the
path /Projects/foo from version 20 onward.
Alias
The alias for this command is air versions.

air project commands

The air project commands manage technical repository projects in a variety of ways,
including creation and modification.

The following table summarizes the air project commands. For information about command
syntax, see “Command-line syntax of air commands”.

Command Description
air project add Explicitly adds a file to a project.
air project Performs dependency analysis on the specified graphs or all graphs in a
analyze- project.
Command Description
dependencies
air project clone Copies settings of a project to a new project.
air project Converts a project to Format 3. See also the air sandbox
convert convert command.
air project create Creates a technical repository project.
(deprecated)
This command has been deprecated. Use the create-project script instead
of this command.
air project Sets a project setting to its default value.
default
air project eval Evaluates the value of the specified project parameter.
air project Updates a sandbox from the technical repository; this process is
export called checkout.
air project files Displays file types and timestamps.
air project find Finds objects within a project.
air project find- Searches for the specified text in graphs, plans, psets, text and other files
text in a project.

air project get- Finds files that are used by another file.
required-files
air project Updates the technical repository from the filesystem.
import
air project Manages the contents of the repository-wide project extensions list.
manage-
extensions
air project map- Shows the result of URL mapping.
url
air project mkdir Creates a new directory in the specified project.

This command has been deprecated. Create the directory in a sandbox

and check it into the project instead. Alternatively, use the air object
mkdir command.
air project Changes project settings.
modify
air project notag Specifies objects that you do not want to promote.
air project Adds or deletes a project parameter, or changes its value.
parameter
Because this command directly modifies files in the repository, we do not
recommend that you use it. Use air sandbox parameter or air project
eval instead.
air project Removes files in a project from the technical repository.
remove
(deprecated) This command has been deprecated. Use air rm or “air sandbox
Command Description

remove” instead.
air project reset Clears a project setting.
air project Resolves sandbox/repository conflicts.
resolve-conflicts
air project revert This command is no longer available. Use air project export and air
project import instead.
air project set- Ensures that file will be marked executable when it is exported.
executable
air project set- Sets an object's MIME type.
type
air project show Displays project settings.
air project show- Displays the specified project’s common projects.
common
air project Updates the project’s extension list to include all the current built-in
update- extensions.
extensions
air project Computes the repository version for object moves and removes that were
update-files made using software versions prior to Co>Operating System Version
3.3.2, and stores that repository version as an entry in the project files list.
Use to improve save file creation and promotion performance.

air project add

Manually adds one or more files to a technical repository project’s internal list of files. It
does not check in the files. This command is branch-specific. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air project add [-q] project-name relative-path ...
Argument Description
-q Suppresses error if relative-path already exists in the project.
project-name Name of the project to which you want to add files.
relative- Relative path of the file to be added. You can add multiple files.
path ...
Usage
When you check in a sandbox at the command line, a file in the sandbox will be checked in
only if (1) it is listed in the project’s list of project files and (2) it has a MIME type listed in
the project’s extension list.
If a file in the sandbox is not on the project list, you can use this command to add that file
to the list before you begin the sandbox checkin. This behavior contrasts with air project
import with the -auto-add parameter, which adds all files in the sandbox to the project list
(if they are not currently on it) and then checks them in. air project add gives you the
flexibility to add only the files you want.

The MIME type for each object is determined by the project’s extension list. Run air
project show to see the current extension list. If the file you’ve added does not have a
recognized MIME type, run air project set-type to modify the extension list.

air project analyze-dependencies

Performs error checking and/or dependency analysis on the specified graphs, on all graphs
in the project, or on all graphs in the specified directory.

This command is branch-specific. For information about the arguments common to

all air commands, see “Command-line syntax of air commands”.
Syntax
air project analyze-dependencies repository-path
[file ... ]
[-check | -complexity | -complexity-details]
[-analysis-extensions]
[-verbose]
[-referencing-files]
[-field-warning]
[-comment comment]
[-nodiscover-datasets]
[-rollup-errors| -individual-rollup-errors | -parsable-errors | -
legacy-errors]
[-max-warnings [-all | num-of-warnings]]
[-cache file ]
Argument Description
repository-path Path to the project whose contents you want to analyze. By default,
all files in the project are analyzed.

Optionally, if you want to analyze a single file, you can instead

specify its full path. The file must be in a project.
file ... Specifies one or more project-relative paths to files that you want to
analyze. If you specify a directory, all files contained in that
Argument Description
directory are analyzed. You can specify "-" to pass the paths on
standard input. (You can only specify the file argument if repository-
path refers to a project.)
-check | -complexity | You can specify one of these:
-complexity-details
 -check checks the graph for errors, but dependency analysis
information is not stored in the technical repository.
 -complexity computes and displays the graph’s complexity as
an integer. For more information, see “Graph
complexity” below.
 -complexity-details displays the measure of overall
complexity and topologic complexity of the graph, as well as
the complexity of each component and its transform
functions. For more information, see “Graph
complexity” below.

-analysis-extensions In addition to dependency analysis, runs user-defined validation tests

and aggregation routines in the context of the technical repository,
against the project specified by repository-path.

The extensions must reside in the current project (or any of its
common projects) at the path /xfr/vld/filename.xfr. Only extensions
identified with the eme keyword in the activation file
(/xfr/vld/activation-file.act) are run. For more information,
see “Complementos de validación y validación de grafos” in
the Guía para desarrolladores de grafos.

Instead of using this argument, you can configure validation

extensions to always run automatically whenever you run
dependency analysis. Set the configuration
variable AB_AIR_FORCE_ANALYSIS_EXTENSIONS to True.
-verbose Displays a detailed report of what is analyzed and why.
-referencing-files Analyzes all files in the repository that reference an object being
analyzed. For example, use this option to do the following:

 Analyze all the psets for a generic graph

 Analyze all the graphs or psets that use a particular record
format (.dml file)

-field-warning Warns when a component or transform causes dependency analysis

to assume that all the output fields depend on all the input fields.
-comment comment Specifies a comment to apply to the technical repository if it is
changed as a result of the analysis.
-nodiscover-datasets By default, datasets are automatically discovered for graphs. This
Argument Description
option disables this feature.
-rollup-errors | -indivi Controls the presentation of dependency analysis warnings. You can
dual-rollup-errors | -p choose one:
arsable-errors | -legac
y-errors  -rollup-errors (default) specifies that errors are grouped by
specific error message. If multiple objects are analyzed, the
grouping is across all objects.
 -individual-rollup-errors specifies that errors are grouped by
specific error message. The messages for each object are
grouped together.
 -parsable-errors specifies that errors messages are presented
in a format that can be processed programmatically (by an
Ab Initio graph, for example). For more information on the
record format, see “Usage” below.
 -legacy-errors specifies that error messages are presented for
each object in the format used by previous versions.

-max-warnings [-all | If -rollup-errors or -individual-rollup-errors is specified, controls the

num-warnings] number of locations that are displayed for each error. To see all
errors, set it -all or set num-warnings to 0.

If omitted, the value of -max-warnings is the value of the

configuration variable AB_AIR_ANALYSIS_MAX_WARNINGS,
which defaults to 3.
-cache file Specifies the path to the analysis cache file. If graphs have not
changed since they were last analyzed and added to the cache, the
command does not analyze them. Instead, it gets their analysis
warnings from the cache.
Usage
This command accepts -files - instead of -file file to read multiple files from standard input.
See “Commands with repeatable arguments”.

If you want to process error messages programmatically, the DML record format for the
output of the -parsable-errors option can be found
at $AB_HOME/include/analysis_warning.dml.

If the command succeeds with nonfatal errors (warnings), the command exits with status
code 2.

The -cache argument supports the gen_da_report.plan utility that is included in

the da_utils sandbox. If you use this plan to analyze and report on checked-in projects, you
may notice some performance improvements.
For more information about dependency analysis, see “Análisis de dependencias” in the
Co>Operating System Guía para desarrolladores de grafos.
Graph complexity
Graph complexity is computed by examining the topology of the graph (the number and
type of flows, the number of inputs and outputs, and the number of possible independent
data flow paths through the graph), the components used, and the complexity of the graph's
DML transform functions. The resulting number is placed on a logarithmic scale.

In general, a graph with a complexity of 60 or greater should be considered a very complex

graph, and a graph with a complexity of 75 or greater is an extremely complex graph.

A graph that cannot be analyzed (either due to errors or due to the setting of the analysis
level) reports a complexity of 0.

For more information about graph complexity, see “Evaluar la complejidad de grafos” in
the Co>Operating System Guía para desarrolladores de grafos.
Example
To determine the complexity of all graphs in the ws-con-up project.

air project analyze-dependencies /Projects/ws-con-up \

-complexity-details -verbose

An excerpt of the output (below) shows, for example, that the overall complexity of the
first graph is 9, while the topological complexity (relating to graph layout and flows) is 1.
The integers following the graph’s components — NORMALIZE and ROLLUP — indicate
the component’s inherent complexity (ROLLUP is inherently more complex
than NORMALIZE) and the complexity of its transformation, respectively:

/Projects/ws-con-up/comp/UpdateableTransactionsByNameLogic.mp 9 Topological:
1
Normalize 1 0
Rollup 3 0

/Projects/ws-con-up/comp/UpdateableTransactionsLogic.mp 9 Topological:
1
Normalize 1 0
Rollup 3 0

Shortcut
The shortcut for this command is air analyze.
air project clone
Copies the settings, but not the content, of the specified project to a new project. Settings
include the project parameters, the extension list, common projects, and the start and end
scripts. This command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air project clone source-project dest-project
Argument Description
source- Path to the project whose settings you want to copy — for
project example, /Projects/lesson.
dest-project Path to the project into which you want to copy the settings — for
example, /Projects/myproject.
Usage
You may be planning to build several projects that are very similar to one another; for
example, they will all use the same project parameters. Rather than create each project
separately, we recommend that you set up a project template containing your preferred
settings and then use air project clone to create new, skeletal projects from this single
template.
Example
To copy the settings of the lesson project into a new project called myproject, type:

air project clone /Projects/lesson /Projects/myproject

air project convert

Converts a project to Format 3. This command is branch-specific. For information about
the arguments common to all air commands, see “Command-line syntax of air commands”.

PRECAUCIÓN:

The air sandbox convert command is preferred. It allows you to test your applications after
converting them but before committing the changes to the technical repository. For advice
about converting large numbers of projects, please contact Departamento de soporte técnico
de Ab Initio.
Syntax
air project convert {project-name | -all} [-dry-run]
Argument Description
project-name | -all Choose one of the following:

 project-name specifies the name of the project to be converted.

 -all specifies that all projects in the technical repository should
be converted.

-dry-run Reports the results of the specified conversion but does not actually
perform the conversion. The technical repository remains unchanged.
Related topics

 air sandbox convert

 Planning for sandbox upgrades from Format 2

air project create (deprecated)

Use the create-project script instead of this command, or create a project by creating a
sandbox in the GDE and checking it in.

Creates a new project and specifies various project attributes, including its location
parameter name, a project parameter prefix, included common projects, and additional
entries in the extension list. This command is branch-specific. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.

PRECAUCIÓN:

This air command creates projects that are unrelated to an Entorno de Ab Initio. As a best
practice, use the create-project script or create the project in the GDE. These methods
create a new project in an Entorno de Ab Initio.

Syntax
air project create project-name
[-location location]
[-formatn]
[-prefix prefix]
[-common [ parm-name] common-path [parm-name] common-
path ...]
[-extension pattern type [pattern type] ...]
 [-nodefault]
Argument Description
project-name Name of the project to be created, for
example, /Projects/warehouse.
-location location Name of the project parameter that specifies the location
of the project. The default is PROJECT_DIR.

For more information, see “Parámetros por defecto de

sandbox” in the Co>Operating System Graph
Developer’s Guide.
-format n Specifies the format of the new project. If this argument
is omitted, the value is taken from that
of AB_AIR_PROJECT_FORMAT, which defaults
to 3 (Version 2.16).

If you set the value to 2, the format for Versions 2.11

through 2.15 is used. Format 1 (Versions 2.10 and
earlier) is obsolete.
-prefix prefix Prefix for the default project parameters created
automatically when you create a project (see “Prefijos
para los parámetros de sandbox” in the Co>Operating
System Guía para desarrolladores de grafos). For
example, COMMON_ would be a reasonable parameter
prefix for a common project.
-common [parm-name] common- Attaches the new project to an existing common project
path [parm-name] common-path (specified as a path) by adding a project parameter with
... the specified parameter name parm-name. You can
specify multiple common project names. If parm-name is
not specified, the command automatically generates it.
-extension pattern type [pattern Adds an entry to the extension list, which associates a
type] ... file-extension pattern, expressed as a string, with a
MIME type. For example:

-extension ‘*.txt’ text/plain

You can specify multiple pairs of patterns and MIME

types. For more information, see “Sample extension
list” in the Technical Repository Administrator’s Guide.
-nodefault Creates an empty directory list and extension list (that is,
without default values) and suppresses the creation of the
default project parameters.
Usage
If you intend to reference a common project within the project you are creating, you must
create the common project first.

The-basedir basedir clause to air project create has been deprecated.

Use -location location instead. The -location argument actually creates a location
parameter.

If you need to change any project attributes after you have created the project, run air
project modify.
Example
To create a project called test that has a location parameter of PROJECT_DIR, prefixes all
parameters with AI_, and contains a common project, type:

air project create /Projects/test -location \

PROJECT_DIR -common /Projects/common -prefix AI_

air project default

Restores the default values of a project’s extension list or project parameters or both. This
command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air project default project-name
{[-extensions] | [-parameters] | [-all]}
[-location location]
[-prefix prefix]
Argument Description
project-name Project name, such as /Projects/warehouse for the
warehouse project.
-extensions | -parameters |-all Choose one of the following:

 -extensions restores the default extension list.

See “Sample extension list” in the Technical
Repository Guide to Version Control.
 -parameters restores the default parameters
(see “Parámetros por defecto de sandbox” in the
Co>Operating System Guía para desarrolladores
de grafos).
Argument Description
 -all (default) restores the default extension list and
project parameters.

-location location Name of the project parameter that specifies the location of
the project — for example: -location PROJECT_DIR.
-prefix prefix Specifies a prefix for the set of predefined project
parameters — for example, -prefix COMMON_.
Usage
The extensions argument restores the default extension list for a specific project only. To
reset the extensions system-wide use air project manage-extensions with
the reset argument.
Example
To restore the lesson project’s default extension list but not the project parameters, type:

air project default /Projects/lesson -extensions

air project eval

Evaluates the value of the specified project parameter and optionally provides bindings for
dependent parameters. Typically, use this command to evaluate a dependent parameter
when its associated choice parameter has a specific value (other than the default). Doing so
is useful for troubleshooting purposes. This command is branch-specific. For information
about the arguments common to all air commands, see “Command-line syntax of air
commands”.
Syntax
air project eval project-path [sub-object]
[-details [-v]]
{parameter [-expression | -type] }
[-eval-expression expression [-position parameter]]
[assoc-parameter=value ...]
Argument Description
project-path Specifies the project name of the graph, plan, pset, or project file
that contains the parameter that you want to evaluate or override.
sub-object Indicates the path to a sub-object such as a graph or subgraph
component or a plan task that contains the parameter that you
want to evaluate.
-details -v Recursively resolves any parameters referenced by the parameter
Argument Description
argument. This is equivalent to the tree view that the Resolution
Details dialog of the GDE displays. If the -v argument is used, the
command prints the data in a verbose, machine-readable form.
parameter Specifies the parameter that you want to evaluate.
-expression | -type Depending on the argument that you supply, displays the
parameter’s unresolved value or its type. You cannot use either
argument with the -eval-expression argument.

NOTA:

You cannot use the -expression argument with the -

details or parameter=value arguments.
-eval-expression expres Evaluates the specified expression. You can enter any expression
sion that would be valid in a parameter definition.
-position parameter Resolves the expression at the optional position of the named
parameter.
assoc-parameter=value Specifies one or more parameters and their respective override
... values. You can use these overrides when evaluating a parameter
to see what the results would be.
Usage
If the supplied parameter doesn’t exist, the command returns an error.

For more information on dependent parameters, see “Parámetros dependientes” in the

Co>Operating System Parameter Reference.
Examples
Project parameter evaluation
To evaluate the parameter MFS in the myproj project, enter the following:

air project eval /Projects/myproj MFS

Dependent parameter evaluation

In the next example, MFS is a parameter that is dependent on the STAGE choice
parameter. To evaluate the MFS dependent parameter when the STAGE choice parameter
value is set to Development (as opposed to its default value), enter the following parameter-
value pair:

air project eval /Projects/myproj MFS STAGE=Development

Component parameter evaluation
To evaluate the Layout parameter for a ROLLUP component found in a graph, enter the
following:

air project eval /Projects/myproj/pset/example.mp Rollup Layout

To evaluate the Layout parameter for a ROLLUP component found in a graph with an input
pset, enter the following:

air sandbox eval /Projects/myproj/pset/example.pset Rollup Layout

Related topics

 air sandbox eval

air project export

Copies (or checks out) one or more projects or files from a technical repository to a
sandbox. The sandbox directory (or directories) is created if necessary. This command
is branch-specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air project export project-path
-basedir sandbox-root-dir
[ -dry-run ]
[ -quiet ]
[ -force ]
[ -merge ] [ -leave-unresolved ]
[ -no-read-only ]
[ -find-required-files]
[ -required-common-files]
[ -files relative-rpath ... ]
[ -from-tag tag ]
[ -parameters ]
[ -set parm-name value ] ...
 [ -common common-rpath common-sandbox] [-relative-
common ] ...
[ -export-commons ]
[ -exclude project ] ...
[ -published-eme published-name ]
[ -config config-pset ]
[ -skip-unreadable ]
Argument Description
project-path Specifies a single project to export or the directory tree
whose projects you want to export. If project-path is a
repository directory tree, all projects within that directory
will be checked out to a sandbox rooted at -basedir.

Projects whose names are in the format project-

name/project are exported to a sandbox having the
name basedir/project.
-basedir sandbox-root-dir Specifies an existing or new sandbox. The path must be
local.
-dry-run Generates diagnostics but does not change the filesystem or
technical repository.
-quiet Suppresses the printing of some progress messages.
-force Does not check for technical repository conflicts. The export
succeeds, overwriting changes made in the filesystem if
necessary.
-merge Performs automatic merging of files that have been modified
in both the repository and the sandbox and are therefore in a
conflict state. For more information on the files that this
argument generates and how to resolve conflicts,
see “Merge”.
-leave-unresolved Leaves the merge file as a .conflict. file when the -
merge argument is specified and the automatic merge is
successful (that is, generates no conflicts). Using this
argument requires that you manually inspect and resolve the
file.
-no-read-only Specifies that the checked-out files should be made writable.
Normally, exported files are not writable until air sandbox
lock has been issued.
-find-required-files Specifies that the list of checked-out files should include
those required by the files named in the -files argument.
Only required files in the local project are included.

This option is incompatible with a multiproject export

described in “Usage”.
Argument Description
-required-common- files Similar to -find-required-files, but also includes required
files in common projects.

This option is incompatible with a multiproject export

described in “Usage”.
-files relative-rpath ... If one or more files are specified with the -files option, then
only those files — and not related files — are checked out.
Specify project-relative paths — for
example, mp/JoinCustomers.mp. By default, all files in a
project are checked out.

This option is incompatible with a multiproject export

described in “Usage”.
-from-tag tag Only the files listed in tag are checked out and they are
exported at their version in the tag.

You can additionally specify -files relative-rpath ... to

further restrict the files that are checked out. If you specify a
file that does not exist in the tag, the command generates an
error.

If the sandbox specified by -basedir sandbox-root-dir does

not exist, the parameter files of project-path are exported. If
the parameter files are not in tag, the command checks them
out at the default version of the tag.

NOTA:

If you want to check out a project at a specific version, use

the air -version version project export command. However,
we typically don’t recommend that you use the air -version
project export command with tags because doing so can
check out objects that are not in the tag and it will check out
objects at the tag’s default version. The default version is the
version that the air command -version argument uses to
access objects that are not explicitly listed in the tag. This
may check out objects at unexpected or incompatible
versions. For more information, see “air tag default-
version”.
-parameters Specifies that project parameters file (.air-project-
parameters or .project.pset) are checked out and that project
scripts (.project.ksh and ab_project_setup.ksh) are
generated. If omitted, the parameters file is copied to a new
sandbox.
-set parm-name value Binds an existing project parameter, parm-name, to value in
Argument Description
the sandbox. You can specify multiple -set clauses. The -
set option does not work with dependent parameters.

This option is incompatible with a multiproject export

described in “Usage”.
-common common-rpath Sets up links between root-dir (of -basedir root-dir above) to
common-sandbox [-relative- the common sandbox common-sandbox for the common
common] project. common-rpath can be a single sandbox or a
directory tree.

If common-rpath is a repository directory, it will be scanned

for projects. If a project is found, such as common-
rpath/xxx, the sandbox for the project is assumed to be
located at common-sandbox/xxx.

You can specify multiple -common clauses. However, if a

project is specified in multiple -common clauses, the last
project specification trumps all those preceding it.

If -relative-common is also specified, links the common

project to the relative location of the common sandbox.
Storing relative paths to common sandboxes allows you to
move a set of sandboxes to a new location without needing
to change the common sandbox references.

NOTA:

The GDE does not currently support relative paths to

common projects.

See -export-commons and “Usage”.

-export-commons Causes common projects to be automatically checked out.

Specify the sandbox location for the common projects in

the -common clause if any of the following is true:

 project-path is a directory tree and the common

projects reside in a different tree
 project-path is a single project
 You want to override the location of a common
sandbox

Do not specify the -common clause with -export-

commons if one of the following is true:
Argument Description

 project-path is a directory tree and the common

projects are located in that tree (thus, you are not
overriding the location of common projects)
 You are updating an existing set of sandboxes (since
the sandboxes know the location of the common
projects)

-exclude project Excludes the specified project from export. This option is
valid only for multiproject exports (described
in “Usage” below). You can specify multiple -
exclude clauses.
-published-eme published- Specifies the name of a "published" technical repository to
name associate with the sandbox specified by -base-dir root-dir.
(To be published, a technical repository must be specified as
one of the values of
the AB_EME_REPOSITORIES configuration variable.)
-config config-pset Configures a Format 3 sandbox to use the configuration
parameter set config-pset. The value is stored
in .sandbox.pset.

NOTA:

The Co>Operating System stores configuration parameter

sets in the root directory, that is, the same directory that
contains .sandbox.pset. and .project.pset. You do not need to
add a path to config-pset.
-skip-unreadable Excludes from the checkout any objects that are unreadable
to the current user. If a sandbox contains a checked out file
that then becomes unreadable in the technical repository, the
file will be removed from the sandbox because the reader
does not have access to it. However, if the file in the
sandbox was modified, the command will issue a conflict
error so that the user can save the changes.

By default, the checkout will fail with an error if the project

contains any unreadable files.
Usage
Use this command to do the following:

 Create a new sandbox from scratch or to update an existing sandbox with files from
the technical repository.
  Merge files that have been modified in both the repository and the sandbox. For
example, this command is useful when one developer modifies and checks in a file
that was previously locked and modified by another developer. For more
information, see “Merge”.

NOTA:

To back out changes to the current version of a technical repository by restoring earlier
versions of modified or removed objects, use air object rollback. For more information, see
the description of that command in this Technical Repository Web Interface and
review “Restoring an earlier version” in the Technical Repository Guide to Version
Control.

Multiproject export
By default a single project is copied to a sandbox. In addition, the air project
export command supports multiproject export. You export multiple projects by
specifying project-path as a directory tree or by specifying the -export-commons option.

With multiproject export, the command identifies the location for a sandbox through either
(1) a combination of project-name and -basedir sandbox-root-dir or (2)
the -common clause. In either case you specify a repository directory tree or a filesystem
(sandbox) directory tree. So any project repository-tree/project-name in the directory tree
will have a possible sandbox location at sandbox/project-name.

When project-name and the -common clause specify conflicting locations for a sandbox,
the command chooses the more specific location of the two. This might occur
when project-name specifies a specific project and the -common clause specifies a
directory containing the specific project — or, conversely, when project-name specifies a
directory tree and the -common clause specifies a specific location.

Consider the following code:

air project export /Projects/foo/bar -basedir /u/disk1/private-bar \

-common /Projects public -export-commons

In the above example, the -common clause applies to the entire /Projects tree in which
the bar project resides, whereas the -basedir clause applies only to a single
project /Projects/foo/bar. Since the -basedir clause is more specific, the command chooses
the value of the -basedir clause as the sandbox location for /Projects/foo/bar.
Common projects
Common projects must be exported before or with their client projects. For example, the
following generates an error if the commonA and commonB projects have not already been
exported:

air project export /Projects/clientproj -basedir /u/disk1 \

-common commonA /u/disk1/commonAsand \
-common commonB /u/disk1/commonBsand

The preceding command would have succeeded if -export-commons had been specified, as
shown below. The command below exports the common projects (-export-commons) and
sets up links between the client sandbox and the common sandboxes:

air project export /Projects/clientproj -basedir /u/disk1 \

-export-commons \
-common commonA /u/disk1/commonAsand \
-common commonB /u/disk1/commonBsand

Understanding checkout errors for unspecified common projects

When you check out a project hierarchy, each project should be checked out only once.
When you use the -common argument, the air project export command performs a full walk
over both the project hierarchy and the sandbox hierarchy that you specified with the -
common argument. This full walk ensures that the command checks out each project only
once. The walk process can involve projects that you did not specify to be checked out.
Therefore, an air project export command (or an equivalent TRMC checkout) can fail and
generate an error message for a project that you did not specify — if that project includes
the project that you were trying to check out. To illustrate this, a user tries to check out her
company project /Projects/company/company_pub. For convenience she includes the -
common argument to export other associated common sandboxes. Because of the
argument, the command examines all projects under /Projects and determines their sandbox
path. A project that is not being checked out, but that includes a project being checked out,
can result in an error. In the following example, /Projects/company/bi/bi_pub is such a
project:

air project export /Projects/company/company_pub -basedir

/user/janedoe/sand/company/company_pub -common /Projects /absand -common /Projects/two
/absand/two -export-commons
Command Failed: air project export /Projects/company/company_pub -basedir
/user/janedoe/sand/company/company_pub/ -common /Projects /absand -common /Projects/two
/absand/two -export-commons
----------------------------------------------------------------
Project /Projects/company/bi/bi_pub sandbox /absand/company/bi/bi_pub has common project
parameter
/Projects/company/company_pub set to /absand/company/company_pub,
but another sandbox has that common sandbox set to /user/janedoe/sand/company/company_pub
$ air project show-common /Projects/company/company_pub
/abinitio/default/Projects/abenv
/Projects/stdenv

To resolve this error, explicitly specify the common project using multiple or more specific
values for the -common argument as highlighted in the following example:

air project export /Projects/company/company_pub -basedir

/user/janedoe/sand/company/company_pub -common /Projects/stdenv /absand/stdenv -common
/Projects/two /absand/two -export-commons

Overriding the location of a sandbox

You can use the -common clause to override the location of a sandbox. For example, to
check out all projects under the /Projects directory tree into a personal sandbox
(/u/disk1/mysandbox) but force stdenv to be checked out into a different shared location:

air project export /Projects -basedir /u/disk1/mysandbox \

-common /Projects/stdenv /u/disk1/shared-stdenv

Examples
These examples show how to use the air project export command with several of it most
popular arguments.
Checking out a project to a new sandbox
To check out the lesson project to a new sandbox and create all necessary subdirectories:

air project export /Projects/lesson -basedir /u/devsand/newsand

Checking out a file to an existing sandbox (despite conflicts)

To check out only the JoinCustomers graph from the lesson project to an existing sandbox
and have it succeed even if a conflict exists, type the following. The graph will be exported,
but not the related transform and record format files.
air project export /Projects/lesson \
-basedir /u/devsandbox/mysandbox -force \
-files mp/JoinCustomers.mp

Checking out a file with required files at specific tag versions

The tag mytag has been applied to JoinCustomers and its required files. To check out
the JoinCustomers graph and its required files at the versions in the tag, type the following:

air project export /Projects/lesson \

-basedir /u/devsandbox/mysandbox \
-find-required-files \
-files mp/JoinCustomers.mp \
-from-tag mytag

Note that all the files specified by -files and -find-required-files must exist in the tag. If not,
the checkout fails.
Checking out a project with a choice parameter
This example assumes that the lesson project has a choice parameter called STAGE that
has Production as one of the allowed values:

air project export /Projects/lesson \

-basedir /path-to-sandbox/temp-sb \
-parameters -set STAGE Production

Checking out all projects to a sandbox

To check out all projects to the sandbox at /u/devsand/mysand:

air project export /Projects -basedir /u/devsand/mysand

Checking out a project and all of its common projects

To check out a single project Projects/xxx/yyy and all its common projects into a single
directory tree:

air project export /Projects/xxx/yyy -basedir /u/disk1/mysand/xxx/yyy \

-export-commons -common /Projects /u/disk1/mysand/
Updating a project and all common projects dependent on it
To update a single project and all the common projects it depends on, assuming you have
current sandboxes:

air project export /Projects/xxx/yyy -basedir sandbox/xxx/yyy \

-export-commons

Checking out a project but excluding specific common

projects
To export /Projects/myproj to sandboxA, all of its commons except stdenv to sandboxB,
and exclude stdenv:

air project export /Projects/myproj -basedir sandboxA \

-export-commons -common /Projects sandboxB \
-exclude /Projects/stdenv

Checking out a private project and setting links to common

sandboxes
Assume that the technical repository location /Project/my_company/ contains two public
projects — pub_c1 and pub_c2, stdenv — and a private project, aproj. Assume also that the
corresponding sandboxes are located at /disk1/pub_sand (which contains pub_c1, pub_c2,
and stdenv) and disk1/private_sand/mysand (which contains aproj). In order to check out
the private project, aproj, to /disk1/private_sand/mysand and set up links to (but not check
out) all the necessary common sandboxes:

air project export /Projects/my_company/aproj \

-basedir /disk1/private_sand/mysand \
-common /Projects/my_company /disk1/pub_sand

Merging file revisions

A developer, Jan, checks out a file to her sandbox /disk1/mysand from the technical
repository location /Project/my_company and locks it. Another developer, Tom, breaks the
lock on that same file and then checks in revisions that fix a bug. Jan can use the following
command to combine her revisions with the bug fix revisions that Tom made:
air project export /Project/disk1/ -basedir /disk1/mysand -merge

Related topics

 air sandbox export -merge

 air sandbox integrate
 air sandbox merge
 air sandbox resolve

air project files

Displays information about all files or specific files currently in a technical repository
project. This is referred to as the project files list. This command is branch-specific. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air project files project-name
[-basedir basedir]
[-all | -files filename ...]
[-verbose]
[-source]
[-versions]
[-tags]
Argument Description
project-name Name of the project whose files you want to list.
-basedir basedir Path to your sandbox directory. If specified, file states are displayed.
If omitted, the output includes only the technical
repository timestamp and version.

For an easy way to display the objects that have changed in your
sandbox, see “Shortcut” (below).
-all | -files filename You may choose one of the following:
...
 -all shows information about all files in the project, including
those that have been removed, are marked as Ignore, or are
missing but are in a NULL state.
 -files filename ... shows information about the specified file(s)
in the project.

If you omit arguments, the command shows information only about

current project files.
Argument Description
-verbose Displays timestamp-related information (which may be useful in
diagnosing problems with source code control) and
the executable attribute if the file is executable.
-source Displays checkin information, including the user, repository, branch,
and version of the latest object checkin. This information is
transferred through promotions.
-versions Shows the version in the technical repository. If a sandbox is specified
(-basedir), the sandbox file’s version number is also displayed. If the
file has changed since the last checkin, that information is noted in the
output.
-tags Shows the name of the tag recorded in the sandbox for the last checkin
or checkout of the specified files.
Usage
For each file in the project, air project files lists one or more lines of output. With no
options specified, the first line lists the technical repository path and MIME type of the file.

The project files list keeps track of every file in a project under source control. For more
information about the project files list, see “Project files list” in the Technical Repository
Guide to Version Control.
File states
If -basedir is specified, one of these states is also listed:

State Description
Current The technical repository and the sandbox are in sync. Current is
displayed only if -all is specified.
Stale The technical repository contains changes that are not present in the
sandbox.
Modified The sandbox contains changes that are not present in the technical
repository.
Conflict The sandbox and the technical repository have both changed.
Unresolved Sandbox contains a conflict file, indicating an unresolved conflict.
Ignore File is not subject to source code control. Ignore is displayed only if -
all is specified.
Removed File is marked for removal from the technical repository but has not yet
been removed from the sandbox.
Error Status information cannot be obtained, due to some system or
permissions error.
Null Information about the file is known to the project, but the file is present
in neither the project nor the filesystem. This situation can occur when,
for example, you have run air project set-type on a file but then failed to
State Description
import the file into the project.
New File exists in the sandbox but has never been checked in.
PendingRemove File has been removed from the sandbox and will be removed from the
technical repository at checkin time. This state derives from running air
sandbox remove.
PendingAdd File has been added to the sandbox and will be checked into the technical
repository at checkin time. This state derives from running air sandbox
add.

For information about the states of files in the technical repository and sandbox,
see “Iconos de estado de la Vista de sandbox” in the Co>Operating System Guía para
desarrolladores de grafos.
Timestamps
If -verbose is specified, the versions of the file in the sandbox and technical repository are
displayed. Viewing this display can be helpful in diagnosing problems with the source code
control system. There are five types of timestamp entries:

Timestamp type Description

R Timestamps stored in the technical repository. Repository timestamps
consist of a date/time, a size (indicated by S=), and a repository version
(indicated by V=).
F Timestamps derived from the filesystem. Filesystem timestamps (F)
consist of a time, a size (indicated by S=), and CRC hashcode (indicated
by C=).
RS Snapshots of the repository timestamps, stored in the .sandbox-state file
at checkin or checkout time.
FS Snapshots of the filesystem timestamps, stored in the .sandbox-state file
at checkin or checkout time.
L Timestamp for each file lock shows when the file was locked and by
whom as well as the lock state (for example, broken).

The technical repository uses timestamps to identify checkin and checkout conflicts:

 If the R and RS timestamps differ, the file has changed in the technical repository
since the last checkout, and is marked stale.
 If the F and the FS timestamps differ, the file has changed in the filesystem since
the last checkout, and is marked modified.
 If a file is both Modified and Stale, there is a conflict on that file.

Due to the possibility of its having been “touched” inadvertently, a file is not considered to
have changed in the filesystem if only the timestamp has changed; either the CRC or the
size must also be different for the file to be considered changed.
If a file is merely “touched” in the filesystem, air project files may mistakenly determine
that the file has been truly changed, leading to a spurious state of Modified or Conflict.
Executable attribute
Use the -verbose option to verify whether a specific file is marked as executable. You will
see the executable attribute following the timestamp information, as in:

run/JoinCustomers.ksh text/x-shell.ksh R 2015-09-09 17:28:23 S= 16003 V= 93 executable

If the file is not executable, no attribute appears. To change the file

from executable to nonexecutable, or vice versa, run air project set-executable.
Examples
Showing file states
The following example shows file states including removed, ignored, or NULL files.

air project files /Projects/myproj -basedir . -all

Ignore .air-lock abinitio-control-file
Current .project-end.ksh text/x-shell.ksh
Current .project-start.ksh text/x-shell.ksh
Ignore .project.ksh abinitio-generated
Current .project.pset text/x-abinitio-pset
Ignore .sandbox-state.1314242580.2505 abinitio-control-file
Ignore .sandbox.pset abinitio-control-file
Ignore ab_project_setup.ksh abinitio-generated
...

Showing version numbers

To list all the files and their versions in sandbox1 associated with the proj project, type:

air project files /Projects/proj -basedir sandbox1 -all -versions

Here is an excerpt of sample output:

Status Repository Path Mime Type Repository Sandbox

Current .air-project- text.x-abinitio- 108 108
parameters parameters
Current mp/Graph1.mp application/x-abinitio- 108 113
 graph
Current run/Graph1.ksh text/x-shell.ksh 113 113
Stale run/Graph2.ksh text/x-shell.ksh 127

Conflict file.txt text/plain 141 136

(modified)
Modified Graph4.mp application/x-abinitio- 137 137
graph (modified)
Modified run/Graph4.ksh text/x-shell.ksh 137 137
(modified)
Current mp directory

Current run directory

Stale run/Graph3.ksh text/x-shell.ksh 131 <none>

Shortcut
To display the objects that have changed in your sandbox, you can enter air sandbox files.
This command is a shortcut for the air project files project -basedir sandbox command.

air project find

Lists the files in a project, optionally filtered by either MIME type or name, and displays
their project-relative paths. This command is branch-specific. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air project find project-name
[-type type-pattern | -name name-pattern]
Argument Description
project-name The name of the project whose objects you want to find.
-type type-pattern | -name Specifies how files are filtered. You can choose one:
name-pattern
 -type type-pattern filters objects by MIME type. The
filter can select either a single object class, such as a
graph, or a set of MIME types, such
as text/plain or text/*).
Argument Description
 -name name-pattern filters objects by name, expressed
as a string. The filter supports wildcards.

Example
To list all transform files, type one of the following:

 air project find /Projects/lesson -name '*.xfr'

 air project find /Projects/lesson -type text/x-abinitio-xfr

The output of either command is:

xfr/JoinCustomers-A-Aggregate.xfr
xfr/JoinCustomers-A-Join.xfr xfr/JoinCustomers-B-Aggregate.xfr xfr/
JoinCustomers-B-Join.xfr xfr/JoinCustomers-C-Reformat.xfr xfr/
JoinCustomers-Final-Join.xfr

air project find-text

Searches for the specified text in graphs, plans, psets, text, and other files in a technical
repository project. This command is branch-specific. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.

NOTA:

If you want to search and replace text in a sandbox, use the air sandbox find-text command.

Syntax
air project find-text
[ -regex | [ -exact] [ -ignore-case ] ]
[ -file-limit limit ] [ -result-limit limit ]
[[ -object-type type ] ... ]
[[ -attribute attribute ] ... ]
[[ -task-type type ] ... ]
[[ -path-filter filter ] ... ]
[[ -component-type type ] ... ]
[[ -component-label label ] ... ]
 [[ -task-label label ] ... ] [ -param name ]
[ -all-file-types ] [ -linked [ -all-linked ] ]
[ -external ] [ -m ]
query path [ path ... ]
Argument Description
query The text that you want to search for.

For more information, as well as how to search for values that contain
hyphens, see “Usage”.
path The repository path to an object or directory that you want to search
for. If the path is a directory, the command recursively searches any
subdirectories. You can search subobjects in graphs or plans, such as a
subgraph within a top-level graph or a task within a plan.

NOTA:

You must use an actual path to specify a pathname. The air command
cannot resolve project variables.

For more information, as well as how to search for values that contain
hyphens, see “Usage”.
-regex | -exact - The -regex argument specifies that query is a regular expression. You
ignore-case cannot combine it with either of the following arguments.

The -exact argument specifies that query must match the entire text field in
the repository. The text field can be a graph legend, a parameter
expression, the contents of an entire text file, and so on.

The -ignore-case argument specifies that the command treats the value
of query as case-insensitive when matching it against the repository.
-file-limit limit Limits the number of files that the command will search. If the value
of limit is reached, the command displays a message.
-result-limit limit Specifies how many results to return. If the value of limit is reached,
the command stops and displays a message.
-object-type type By default, searches all object types. If you specify -object-type and
are searching only graphs and plans, use this argument to limit the
search to the specified type. The type can be one of the following:

 graph — For top-level graphs and embedded subgraphs.

 linked-subgraph
 graph-interface
 component
 plan — For top-level plans and subplans.
 task
Argument Description
 legend — For graphs and plan legends.

You can specify multiple types.

-attribute attribute By default, searches all attributes. If you specify the -
attribute argument, the command searches for the following object
attributes, as specified:

 name — The object’s display name.

 author
 comment
 param-name
 param-expression — Unresolved expressions.
 param-choice — The choices in choice parameters.
 param-dml-type — DML parameter type expressions.
 param-description
 pset-prototype — The path of a pset’s prototype. This pset
chain path was created using the air sandbox pset -
prototype command or by using the GDE.
 pset-base — The path of a pset’s base. This pset chain path
was created using the air sandbox pset -base command or by
using the GDE.
 shared-catalog — The path to graph’s shared lookup catalogs.
For more information, see “Graph Settings: Catalog category”.

You can specify multiple attributes.

-task-type type By default, searches all types of plan tasks. The value of type can be
one of the following:

 graph — Graph tasks.

 program — Program tasks.
 plan — Plan tasks, not including subplans.
 conditional
 signal-event
 wait-for-event
 wait-for-file

You can specify multiple tasks.

-path-filter filter Searches only files with paths that match filter. This argument
supports wildcard pattern matching (globbing) and it is case-
insensitive. For example, the value of filter can be *.mp if you want to
search for all graphs.

You can specify multiple path filters.

-component-type ty Searches only components of the specified type. The value
pe of type must be a component’s prototype path. This argument supports
Argument Description
wildcard pattern matching (globbing) — for
example, */Filter_by_Expression.mpc. The value can also be a custom
component. The argument is case-insensitive.

You can specify multiple component types.

-component-label la Searches only components whose label matches the specified value.
bel This argument supports wildcard pattern matching (globbing) and is
case-insensitive.

You can specify multiple component labels.

-task-label label Searches only tasks whose label matches the specified value. This
argument supports wildcard pattern matching (globbing) and is case-
insensitive.

You can specify multiple task labels.

-param name Searches only parameters whose name matches the specified value.
This argument supports wildcard pattern matching (globbing) and is
case-sensitive.

You can specify multiple parameters.

-all-file-types By default, only searches Ab Initio file types such
as .mp, .plan, .pset, .dml, and text files. If you specify the -all-file-
types argument, the command searches files of all types.
-linked By default, searches fields of linked subgraph objects, such as their
parameters, but it doesn’t recurse into them. By default, air project
find-text only recurses into subgraphs that can be viewed in the GDE.
That is, the command recurses when the Permit View property is
enabled on the Description tab of a subgraph’s Properties dialog.

If you specify the -linked argument, the command searches graphs and
recurses into saved instances of linked subgraphs.
-all-linked Use with the -linked argument. Recurses into linked subgraphs even if
they aren’t viewable in the GDE. That is, the command recurses into a
linked subgraph even when the Permit View property is disabled on
the Description tab of the subgraph’s Properties dialog.
-external By default, searches attributes or parameters that you can edit directly.
Examples of things that can’t be edited directly include the names and
default values for parameters in components, and input parameters on
linked subgraph instances. By default, searches only user-defined
comments for components, not their built-in or source comments
(displayed on the Description tab in the Properties dialog).

If you specify the -external argument, the command

searches all attributes for all visible parameters in the GDE
Argument Description

Parameters Editor for the current objects. Use this argument to search
values in component or subgraph prototypes. If there is no user-
defined comment at the subgraph, component, or task instance, the
command searches in the component’s built-in or source text
(displayed on the Description tab in the Properties dialog).
-m Writes the command output in machine-readable format to standard
output. The DML record format for the output is located
at $AB_HOME/include/air-find-text.dml.
Usage
 To search for a subobject in a graph or plan, use the following pattern for path:

path/object

For example, if you want to search the subgraph My_Subgraph that is located in the
graph my_graph, specify the path as follows:

host/disk1/sand/my_graph.mp/My_Subgraph

 If the value of query or path starts with a hyphen (-), then you must place two
hyphens surrounded by a leading and a trailing space (that is, " -- ") after the last
argument and before query. For example, to identify -region as the query value and
not a command argument that starts with a hyphen, enter the following:

air project find-text -- -region client-services.mp

 By default, this command searches only Ab Initio file types such

as .mp, .plan, .pset, .dml, and text files. If you specify the -all-file-types argument,
the command searches files of all types.
 To specify multiple arguments, where supported, repeat the argument name
followed by its value. The following example, searches for the term foo within
both FILTER BY EXPESSION and INPUT FILE components by repeating the -
component-type argument and value pair:

air sandbox find-text foo -component-type */Filter_by_Expression.mpc -component-type

*/Input_File.mpc
  The -object-type argument provides another level of granularity for searching with
the air project find-text command. If you want to search for the fields of a graph or a
subgraph object (such as their display names), use the -object-type argument with a
value of graph.

Note, however, that this command does not search inside the graph or subgraph’s
contents. For example, suppose that you have a graph graph.mp, which contains an
embedded subgraph My Subgraph. The subgraph, in turn, contains an INPUT
FILE component My Input File. If you run the following command with a value
of My for the -graph argument, the command will return the result of the display
name My Subgraph. It will not return a result for the My Input File component that
the subgraph contains:

air project find-text -object-type graph My graph.mp

 The command’s results substitute a space for new lines found in the matched
content. For example, if the output from a match would normally appear as the
number one followed by a newline, then the number two, the command results
would show the number one, a space, and then the number two. The source data is
untouched.

Examples
To search for the string west-region in the graph client-services.mp, enter the following in a
shell session:

air project find-text west-region client-services.mp

To search for exact matches of void(1) in the embedded record formats of the read ports
of INPUT FILE components in all graphs located in the project my_project, enter the
following:

air project find-text -exact -attribute param-expression -path-filter '*.mp' -component-type

'*/Input_File.mdc' -param read_metadata 'void(1)' my_project

air project get-required-files

Finds and displays the files in a project that the specified objects depend on. This command
is branch-specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air project get-required-files project-name [-force] [object-relative-path ...]
Argument Description
project-name Name of the project.
-force Causes the command to continue even after an error is encountered. In this
case the output may produce a possibly incomplete set of required files.
object- Relative path to one or more objects in project-name whose required files
relative-path you want to find. If omitted, displays the required files for all objects in the
project.
Usage
Errors in graphs may cause the command to report an incomplete set of required files. To
be sure that you get a complete set of required files, you should make sure that your graphs
analyze without errors.

Normally, if an error is encountered during analysis (for example, if a required file cannot
be found or a URL contains an invalid parameter), the command aborts with a diagnostic
error message. Specifying -force overrides this behavior.

If the set of required files is incomplete for other reasons — for example, a required file is
not automatically detected by the system — you can manually add files by running air
object requires.
Example
To find out what files the graph Unload-B-Tables depends on, type:

air project get-required-files /Projects/lesson \

mp/Unload-B-tables.mp

The output is:

/Projects/lesson db/B-database/transactions.cfg
/Projects/lesson db/B-database/customers.cfg
/Projects/common xfr/cust_trans_join.xfr

air project import

Copies sandbox files into an existing technical repository project. This process is
called checkin. This command is branch-specific. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air project import project-path
-basedir basedir
[-dry-run] [-fast-dry-run]
[-force] [-lock] [-retry]
[-auto-add] [-add-files file ...]
[-create] [-no-read-only]
[-files relative-rpath ...]
[-find-required-files]
[-tag tag-name [-move-tag] {-tag-all |-tag-project|-tag-
exact}]
[-comment comment]
[-published-eme published-name]
[-noanalysis] [-nodiscover-datasets]
[-rollup-errors | -parsable errors | -legacy-errors | -
individual-rollup-errors]
[-max-warnings [ all | num-warnings]]
[-import-commons] [-quiet]
Argument Description
project-path Path to the project to which you want to check in files.
-basedir basedir Path to the sandbox. The default sandbox is the value of the
environment variable named by the project’s location
parameter.
-dry-run Generates diagnostics but does not change the sandbox or
technical repository.
-fast-dry-run Determines the files to be checked in but does no further error
checking. It makes no changes to the sandbox or technical
repository.
-force Does not check for technical repository conflicts. The
command succeeds even if changes made in the repository are
overwritten. It also forces the checkin of removed or ignored
files specified by -files. You can also use this option to force
checkin and tagging, even on out-of-date sandboxes.

If -force is not specified and you have conflicts, the command

fails. See “Usage”.
Argument Description
-lock Causes the command to retain your locks on files in the
project, and locks newly imported and modified files. By
default, the command unlocks files after importing.
-retry If the import transaction conflicts with another transaction
while updating the technical repository, the software will retry
the transaction. For more information on retries,
see AB_AIR_COMMIT_RETRIES and AB_AIR_COMMIT_
BACKOFF.
-auto-add Specifies all new files in the sandbox to be automatically added
to an existing technical repository project.
-add-files file ... Checks in one or more sandbox files you specify, along with
the other files that the command determines should be
imported. You can specify - to pass the file list on standard
input. This option is incompatible with the -files option.
-create Causes the project to be created before the checkin. The
location parameter and prefix are determined from the
sandbox.
-no-read-only Causes the checked-in files to be left writable, if they were
writable before. Normally, files are not made writable after
import until an air sandbox lock command is issued.
-files relative-rpath ... If you specify one or more files to the -files option, only those
files (and not related files) are checked in. Specify project-
relative paths — for example, mp/ABC.mp. If the directory
does not exist, the command will create it. You can
specify - to pass the multiple files on standard input.

If omitted, all files in a project are checked in. This option is

incompatible with the -add-files option.
-find-required-files Also checks in any files required by the files being checked in.
These required files are imported only if they reside in project-
path. See “Usage” below.
-tag tag-name Applies the tag tag-name to the project after the checkin
completes. However, if you specify -files, the tag is applied
only to those files. The command fails if tag-name already
exists unless you also specify -move-tag.

If specified, you must also specify one of these: -tag-all, -tag-

project, or -tag-exact.
-move-tag If tag-name already exists, the tag is applied to the latest
version of each checked-in object.
-tag-all | -tag-project | -tag- If you specify -tag tag-name, you must also specify one of
exact these:

 -tag-all includes all required objects of the checked-in

Argument Description

objects in the tag tag-name, even if they are in a

common project.
 -tag-project includes only required objects in the same
project as the checked-in objects in the tag tag-name.
 -tag-exact includes only the checked-in objects in the
tag tag-name.

-comment comment Associates a comment with the checkin.

-published-eme published- Specifies the name of a "published" technical repository to
name associate with the sandbox specified by -basedir root-dir. (To
be published, a technical repository must be specified as one of
the values of the AB_EME_REPOSITORIES configuration
variable.)
-noanalysis By default, dependency analysis is performed during checkin.
This option disables this feature.
-nodiscover-datasets Disables automatic dataset creation and update for graphs and
graph instances.
-rollup-errors | -parsable Controls the display of dependency analysis warnings. You can
errors | -legacy-errors | -ind choose one of the following:
ividual-rollup-errors
 -rollup-errors (default) means that errors are grouped
by error message. If multiple objects are analyzed, the
group is across all objects.
 -parsable errors means error messages are presented in
a format that can be processed programmatically (for
example, by an Ab Initio graph). For more information,
see “Processing error messages” below.
 -legacy-errors means that errors for each object are
presented in a format used by earlier versions.
 -individual-rollup-errors means that errors are grouped
by error message. The messages for each object are
grouped together.

-max-warnings [ all | num- If -rollup-errors or -individual-rollup-errors is specified,

warnings] controls the number of locations that are displayed for each
error. Set num-warnings to 0 or specify all to see all errors. If
omitted, the value of -max-warnings is the value of the
configuration
variable AB_AIR_ANALYSIS_MAX_WARNINGS, which
defaults to 3.
-import-commons Imports the common projects for the current project. If the
project doesn’t exist, and this argument is specified, creates the
project in the same technical repository directory as the
Argument Description
specified project.
-quiet Suppresses the printing of some progress messages.
Usage
What you can check in
Use air project import to check in the following:

 All files that need to be checked in to a technical repository project, optionally

creating the project
 Only the files that you specify
 Files that you specify as well as the files the command determines need to be
checked in
 All new sandbox files
 Files required by the files that are going to be checked in

By default, the command performs dependency analysis (including dataset creation and
update) and leaves the imported files unlocked, in a read-only state. The command
maintains existing file permissions. Various parameters are available to disable the
command’s default behaviors.

The command holds a lock on the project when it performs dependency analysis. You can
choose to have the command wait until it can obtain the lock before starting analysis, or
you can choose to have the command fail if it does not obtain the lock immediately.

Optionally, you can apply a tag and a comment to the checkin.

What to do first
To check in files required by a graph, specify the -find-required-files option. To see the list
of required files before checking them in, run air project get-required-files. Then, if the list
is incomplete or inaccurate, run air object requires to edit the list of required files. Finally,
run air project import.

Make sure the files that you want to check in are not locked by another user. The command
will not import such files.

If you want to make sure that new files in your sandbox are automatically checked in to the
technical repository, run air sandbox add on these files before running air project import.
The command will assign them a state of PendingAdd and place them on a list of files
awaiting addition. Running air project import will then check them in without your having
to explicitly specify these files.

Conversely, if you want to have files automatically removed from the technical repository
at checkin, then run air sandbox remove before running air project import. The command
will assign these files a state of PendingRemove and place them on a list of files awaiting
removal from the repository.

NOTA:

We recommend that you run the command with the -dry-run flag before doing the actual
import in order to validate the operation you are about to perform.

How the command works

The GDE uses the same underlying process as this command as the first step in checking in
a graph. The first time you check in a given project, it does the following:

 Scans the current sandbox or directory tree for files to bring into the technical
repository project. It matches each file against a filename pattern in the extension
list. If a file’s value in the extension list is not ignore, it imports the file.

On subsequent imports, the command also compares the timestamps of the

repository project files to those of their like-named counterparts in the filesystem. It
will reimport the files only if they are newer than the files in the repository.

 Uses the project parameters to determine the correct repository location for each file
that it decides to import.
 Synchronizes the filesystem and repository versions of the imported application so
that the repository can be refreshed from the filesystem, and vice versa.

Using the -force option

Use the -force and -files options to check in a file whose MIME type has been set
to ignore or removed. Once the file is checked in, its MIME type is changed to the default
type. For example, if you check in a removed Microsoft Excel file, calculations.xls, its
MIME type is changed from removed to application/vnt.ms-excel.

PRECAUCIÓN:

Use care when using the -force option on a sandbox. It causes everything in your sandbox
to be checked in, thereby overwriting everything in the technical repository whether or not
the files in your sandbox have changed.

By default, the import operation fails if it would overwrite objects that have been changed
in the repository since the last time the import command was invoked.
Input of multiple files
This command accepts -files - instead of relative-rpath to read multiple paths from standard
input. See “Commands with repeatable arguments”.
Processing error messages
If you want to process error messages programmatically, the DML record format for the
output of the -parsable-errors option can be found
at $AB_HOME/include/analysis_warning.dml.
Status code
If the command succeeds with nonfatal errors (warnings), the command returns status
code 2.
Command failure
If you tag a sandbox during checkin (using -tag-exact, -tag-project, or -tag-all) and that
sandbox contains a stale file, the checkin fails. Update the sandbox and run air project
import again.
Conflicts
For information on dealing with file conflicts, see air sandbox resolve.
Examples
Checking in all sandbox files to a new project
You want to check in all sandbox files into a new technical repository project, lesson:

air project import /Projects/lesson -basedir /u/mkatz/sandbox -create \

-auto-add

Checking in a graph and its required files

You want to check in the graph my-graph and its required files (its transforms and record
formats) into the lesson project:

air project import /Projects/lesson \

-basedir /u/mkatz/sandbox -files /mp/my-graph.mp \
-find-required-files

Checking in a graph and required files without dependency

analysis
You want to check in the graph my-graph and its required files into the lesson project, but
you want to do it quickly, without performing dependency analysis or discovering datasets:
air project import /Projects/lesson \
-basedir /u/mkatz/sandbox -files /mp/my-graph.mp \
-noanalysis -nodiscover-datasets -find-required-files

Checking in a file whose MIME type is usually ignored

You want to check in a file, mydml.dml, whose MIME type will not normally be checked
in, because you marked it as Ignore (never check in) in the Checkin Wizard. Its MIME
type is ignore. To check the file in, run air project import on the file with the -force option:

air project import /Projects/lesson \

-basedir /disk1/data/sand/mysand/lesson \
-force \
-files dml/mydml.dml

The -force option sets an appropriate MIME type for the file — text/x-abinitio-dml for a
record format file.

Syntax
air project manage-extensions
[-reset| -show |-from-system]
[-add pattern type ...]
[-remove pattern type ...]
[-file extension-file ...]
Argument Description
-reset | -show | - These arguments work as follows:
from-system
 reset — Clears the repository-wide extension list and replaces
it with the extension list from the Co>Operating System used
to run this command. For more information, see “Usage”.
 show — Prints a list of the current extensions and their MIME
mappings. The default.
 from-system — Adds to the current list all the built-in system
extensions from the Co>Operating System used to run this
command. For more information, see “Usage”.

-add pattern type Adds the specified pattern and MIME type pair to the repository-wide
extension list
Argument Description
-remove pattern Removes the specified pattern and MIME type pair from the
type repository-wide extension list
-file extension-file . Specifies the path to a file containing instructions for adding or
.. removing extension patterns and their MIME types. For the file
syntax, see “Usage” and “Examples”.
Usage
If you do not supply any arguments, the command prints the list of current extensions.

The -reset argument works system-wide. To reset the extensions for a specific project only,
use air project default with the -extensions argument.

The -from-system argument lets older clients use newer features. For example,
Co>Operating System Version 3.1.6 introduces a new transform extension *.tdml, and the
Version 3.1.5 client can support the transform, but doesn’t recognize the extension. You
can use the -from-system argument to add the extension and its MIME type mapping from
the Version 3.1.6 Co>Operating System. To do so, $AB_HOME must point to Version 3.1.6
when you run the air command.
Search order
The search order that a project uses to match an object and its MIME type during check in
is as follows:

1. The project extension list

2. The system extension list (that is, the repository-wide extensions)

3. The built-in extension list (that is, the extensions from the Co>Operating System in
use)

Extension-file syntax
Format the contents of the extension file as follows:

 You must place each extension specification on a separate line, as follows:

o To add an extension, specify pattern=type.

o To remove an extension, specify pattern.

 If the pattern contains spaces, you must enclose them in double-quotation marks.
 You can use empty lines to format the contents of this file; the command will ignore
empty lines.
 You can enter in-file comments by prefacing each comment line with the pound
character (#).
Examples
Adding and removing extensions
To add a specific file whose path contains spaces and map it to the text/plain MIME type,
enter the following:

air project manage-extensions -add "data/serial/SW region sales.txt" text/plain

To remove the video/mpeg MIME type that is mapped to the *.mpg pattern, enter the
following:

air project manage-extensions -remove *.mpg

Using an extension file
The following is a sample extension file that you can use with the -file argument:

# Changes to the repository extension list approved by TR-Admin-4.

#
# Add extensions

"data/serial/SW region sales.txt"=text/plain

*.mydml=text/x-abinitio-dml
*.myxfr=text/x-abinitio-xfr

# Remove extensions

*.mpg

air project map-url

Displays the location to which a URL is mapped by a project. This command is branch-
specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air project map-url project-name URL ...
Argument Description
project-name Name of the project.
URL ... Path(s) of the file(s) specified (which can contain a dollar sign).
Usage
The command performs dollar-sign substitution. See “Interpretación de las sustituciones $ y
${ }”. Note that the technical repository project definition is used, not the sandbox version.
Example
To display the location to which the project /Projects/myeme maps the
URL $DML/a-transactions.dml in the myeme project, type:

air project map-url /Projects/myeme ’$DML/a-transactions.dml’

The mapping might be:

/Projects/myeme/dml/a-transactions.dml

air project modify

Edits the specified project’s location parameter. Adds, edits, or removes one or more
existing entries in the project’s common-project list or extension list. For information about
the arguments common to all air commands, see “Command-line syntax of air commands”.

Syntax
air project modify project-name
[-location location-parameter]
[-common [parameter] common-path [[parameter]common-path
] ...]
[-extension pattern type [pattern type ...]
[-remove clause ...]
[-require-user-managed-datasets { true | false } ]
Argument Description
project-name Name of the project you want to modify — for
example, Projects/warehouse.
-location location-parameter Name of the project parameter that specifies the
location of the project — for example, -location
PROJECT_DIR. For more information,
see “Parámetros por defecto de sandbox” in the
Co>Operating System Guía para desarrolladores de
grafos.
Argument Description
-common parameter common- Adds the parameter reference parameter to an existing
path ... common project common-path from the specified
project project-name. You can specify multiple pairs of
common project parameters and common project paths.
If parameter is not specified, the command
automatically generates it. When you use this argument
with -remove, you can specify
either parameter or common-path.
-extension pattern type [pattern Adds or edits an entry in the extension list, which
type] ... associates the file-extension pattern pattern with a
MIME type. Express pattern as a string.

You can specify multiple pairs of file-extension

patterns and MIME types.

For an example of a default extension list, see “Sample

extension list” in the Technical Repository Guide to
Version Control.
-remove clause ... Removes an entry from the common project list or
extension list, depending on which clause you
specify. clause refers to
the -common and -extension clauses described above.

You can specify clause multiple times.

-require-user-managed-datasets { t Controls whether dependency analysis is permitted to
rue | false } create or update EME datasets in the project. The
options are as follows:

 -false allows dataset creation.

 -true prohibits dataset creation. Only preloaded
or reusable datasets may be created in the
project.

For more information, see “Conjuntos de datos

gestionados por el usuario” in the Co>Operating
System Guía para desarrolladores de grafos.
Usage
You cannot change the order of common projects at the command line. You must use the
GDE.

To remove all entries from the common project list or extension list, use air project reset.
To find out whether the project currently requires user-managed datasets, use the air project
show command.
Example
To add an entry to the extension list of *.txt and remove a common project from the client
project lesson:

air project modify /Projects/lesson -extension '*.txt' text/plain \

-remove -common MYCOMMON /Projects/mycommon

air project notag

Indicates whether to tag objects before creating or updating an object tag. When you use
this command to indicate an object you want to exclude from tagging, the object is stored in
the project-path/.no-tag-list file. An object in the no tag list will be excluded from tagging
unless it is identified as a primary object when you create the tag. For exceptions to this
command’s behavior, see “Usage”.

Use case

This command prevents the tagging of files, and therefore indirectly, it can also affect
promotion. You can use air project notag in a development technical repository to mark and
exclude test code that you do not want to migrate to your production repository. You can
also use this option to include the objects in a save file at a later time if desired — say, to
share with another developer or with support. See “Examples”.

This command is branch-specific. For information about the arguments common to

all air commands, see “Command-line syntax of air commands”.
Syntax
air project notag project-path -add | -remove object-path
air project notag project-path -show
Argument Description
project- Path to the project whose objects you want to exclude or reinclude from
path promotion.
-add | - Indicator whether to add or remove the specified object-path in the project-
remove path/.no-tag-list file. The air promote save (and air object save) commands
ignore objects in this file. For more information on this file, see “No tag list”.

 -add — places an object in the no tag list, thereby excluding it from the
save file.
Argument Description
 -remove — deletes an object from the no tag list, thereby reincluding it
in the save file.

object-path Relative path to the object you want to add or remove from the no tag list.
See “Details and exceptions” (below) for important information.
-show Displays the contents of the no tag list.
Usage
This command comes into use only when you are creating or updating a tag. The exclude or
include information is ignored for other repository actions. Additionally, there is no
enforced correspondence between other repository actions and the .no-tag-list file. For
example, if a directory is in the no tag file and you use air sandbox remove to delete the
directory from the repository, its path will still remain in the no tag file. You must remove
it from the list by separately issuing the air project nontag -remove command.

A sample workflow for using this command is:

 Run air project notag to include or exclude one or more objects from tagging.
 Run air tag or use the TRMC to tag the objects or update their tags. The contents of
the no tag list file determine what gets tagged.
 (Optional) Run air promote save or use the TRMC promotion feature to create a
save file based on the previously established tag.

Details and exceptions

If a primary object has notag set, then its required objects (secondary) won’t be tagged
unless you explicitly specify them in this command.

If a primary object is tagged, but its required objects have notag set, then the required
objects will not be tagged.

If a primary object is tagged, but its required objects have notag set and are also primary
objects themselves, then they will be tagged. However, their secondary objects will not be
tagged. If you want to tag those objects, you must specify them in this command. The
following TRMC Tags tab screen capture shows subDir, which is both a secondary object
to myDir and a primary object to secondaryObj:
 If subDir has no tag set, it will still be tagged because its primary object (myDir) is tagged,
and because subDir is itself a primary object. However, secondaryObj will not be tagged
unless you explicitly specify it.

Do not use the -from-tag argument with the deprecated air object save command. This
argument (compatible with older promotion implementations) ignores the notag feature.
Instead use the -exact-tag argument.
No tag list
All objects marked for exclusion are stored in the project-path/.no-tag-list file. You can
use air project notag or the View Contents feature of the TRMC Repository Explorer tab
to display the contents of this file. See “Viewing .no-tag-list contents”. Do not modify this
file manually. Use only this air command to add or remove objects.
Viewing .no-tag-list contents
To view the contents of the .no-tag-list file:

 Do one of the following:

o In a command session, enter air project notag project -show.
o In the TRMC Repository Explorer, select /project/.no-tag-list and
select View Contents from the context menu.

Examples
Excluding a directory from a project
In this example, a project’s sandbox contains a subdirectory mp/tools containing a
developer’s private utility scripts:

air ls proj/mp/tools
directory /proj/mp/tools/: 2 elements
mimeobj: cleanup.ksh
mimeobj: setup.ksh

To exclude this directory from tagging, run the air notag command with the -add argument.
The directory (and by default, its contents) will be added to the no tag list:

air project notag proj -add mp/tools

To confirm that the object was added to the no tag list, enter:
air project notag proj -show
mp/added_both.mp
.project.pset
mp/tools

Next, tag the project and if desired create a save file:

air tag create -exact -comment

"For production." Prod562 proj
air promote save productionV5-6-2.save Prod562 -comment "For production."
Export: /proj
...
Export: /proj/components
Export: /proj/pset
Export: /proj/resource
Export: /proj/plan
Export: /proj/mp
Export: /proj/db
Export: /proj/run
Export: /proj/xfr
Export: /proj/dml
...

The output shows that the mp/tools directory and its files were not included in the save file.
Including an object that otherwise would be excluded
In the “Excluding a directory from a project” example, the mp\tools directory was excluded
from tagging and therefore from a save file intended for production. However, the
production environment could benefit from a new script production-alert.ksh that is in
the mp\tools directory. To include the useful script while still excluding its parent directory
and the other files, specifically add the tag to the script (as is shown by the second -
add argument):

air tag create -all Prod563 -add proj -add proj/mp/tools/production-alert.ksh

Using the air lag ls command (or the TRMC) shows that the production-alert.ksh script was
tagged:

air tag ls -n Prod563

Prod563
(vtag) /proj
/proj
...
/proj/mp
/proj/mp/stale_locked.mp
/proj/mp/tools/production-alert.ksh
/proj/plan

The save file will now pickup the tagged file with the rest of the project, by-passing the
behavior specified in project-path/.no-tag-list.txt:

air promote save productionV5-6-2.save Prod562 -comment "For production."

Export: /proj
...
Export: /proj/components
Export: /proj/pset
Export: /proj/resource
Export: /proj/plan
Export: /proj/mp
Export: /proj/db
Export: /proj/mp/tools/production-alert.ksh

Related topics

 air object save

 air promote save
 air tag create
 “About tags” in the Technical Repository Guide to Version Control

air project remove (deprecated)

Use the alias air rm or “air sandbox remove” instead of this command.

Removes one or more files in a project from the technical repository, marking them
as removed. When the project is subsequently checked out, files marked removed are
deleted from the sandbox. This command is branch-specific. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air project remove [-q] [-r] project-path rpath ...
Argument Description
-q Suppresses error if rpath does not exist.
-r Specifies that the contents of directories be recursively removed. If this is not
specified, only empty directories can be removed.
Argument Description
project- Path to the project from which you want to remove a file.
path
rpath ... Path to one or more files you want to remove.
air project reset
Removes all entries from the list of common projects and the extension list, as well as all
project parameters, except the location parameter. This command is branch-specific. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air project reset project-path
[-common]
[-extensions]
[-parameters]
[-all]
Argument Description
project-path Path to the project you want to reset.
-common Removes all references to common projects.
-extensions Removes all entries from the extension list.
-parameters Removes all project parameters.
-all Removes all entries from the common projects list and the extension list, as
well as all project parameters.
air project resolve-conflicts
Resolves technical repository conflicts by adjusting timestamps and removing conflict files.
This command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air project resolve-conflicts project-path
[-basedir basedir]
{-keep-repository | -keep-sandbox}
[-unconflicted]
{-all | -files file ...}
Argument Description
project-path Path to the project.
-basedir Specifies the base directory of the sandbox. If specified,
temporarily overrides the normal root directory.
Argument Description
-keep-repository | -keep- Choose one of the following:
sandbox
 -keep-repository resolves the conflict in favor of the
technical repository.
 -keep-sandbox resolves the conflict in favor of the
sandbox.

-unconflicted Specifies that files that do not have a conflict are also affected.
This has the effect of discarding changes in the technical
repository or sandbox.
-all | -files file ... Choose one of the following.

 -all specifies that all files in the project be processed.

 -files file ... specifies files whose conflicts are to be
resolved. Use project-relative paths, such as dml/foo.dml.

Usage
This command copies the timestamp from the .conflict file to the .sandbox-state file.

If you specify -keep-sandbox, the command removes the .conflict file. If you specify -keep-
repository, the command renames the .conflict file to the source file. If you specify -all, all
files in the project will be processed. Otherwise, only the explicitly named files are
processed.

This operation adjusts timestamps only in the sandbox. To make the adjustments
permanent, follow this command with air project import.

This command accepts -files - instead of -file file to read multiple files from standard
input. See “Commands with repeatable arguments”.

air project set-executable

Ensures that a file will be marked executable when it is exported. Also, marks an
executable file as not executable. This command is branch-specific. For information about
the arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air project set-executable project-path relative-rpath [-not]
Argument Description
project-path Path to the project containing the file.
relative-rpath Relative path of the file within the project.
Argument Description
-not Specifies that an executable file be marked not executable.
Usage
Normally, executable is set based on the filesystem permissions on the imported file.
However, some filesystems, notably Windows, do not support execute permission. This
command ensures that files imported to such a host will export correctly to other hosts
where execute permission is supported.

To verify that the file has been marked executable, run air project files with
the -verbose option.
air project set-type
Overrides the MIME type assigned to a single repository object. This command is branch-
specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air project set-type project-path [-force] relative-path MIME-type
Argument Description
project-path Path to the project in which the object resides.
-force By default, you cannot set the type to an “internal" type, such as removed.
Use -force to override this restriction.
relative- Relative path to the object whose MIME type you want to change.
path
MIME-type Valid MIME type.
Usage
Setting the MIME type of a file to ignore causes the file to be ignored during import
(checkin) or export (checkout) processing. For a list of provided MIME types, see “Sample
extension list” in the Technical Repository Guide to Version Control.
Example
To ensure that both checkin and checkout ignore a specific file — for
example, /run/config.ksh in the test project — set the file’s MIME type to ignore:

air project set-type /Projects/test run/config.ksh ignore

air project show

Displays project attributes in human-readable form. This command is branch-specific. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air project show project-path [-effective-extensions]
Argument Description
project-path Path to the project whose attributes you want to display.
[-effective- Show only the project attributes for the effective extension list — that is,
extensions] the combination of project, repository, and built-in extensions used on
import.
Usage
The output can be quite long. You might want to pipe the output through
the more command.

The output has the following entries:

Output heading Description

Base Directory Name of the parameter that gets assigned to the sandbox directory
Common Projects Projects that are included in another project
Parameters Parameters of the project
Import map Import list (deprecated since Version 2.11)
File Types Extension list
Example
air project show MyProjectABC
Project /MyProjectABC
Base Directory : PROJECT_DIR

Common Projects : /Projects/abinitio_env/stdenv

Parameters :
PROJECT_DIR :
Environment :
PREFIX : AI
AI_BIN : $PROJECT_DIR/bin
AI_DML : $PROJECT_DIR/dml
AI_XFR : $PROJECT_DIR/xfr
AI_DB : $PROJECT_DIR/db
AI_SQL : $PROJECT_DIR/sql
AI_MP : $PROJECT_DIR/mp
AI_PLAN : $PROJECT_DIR/plan
AI_PSET : $PROJECT_DIR/pset
 ...
File Types :
#* = ignore
*~ = ignore
*ProxyDir = ignore
*ProxyFile* = ignore
AB-Proxy-*“ = ignore
*.rec = ignore
*.job = ignore
*.o = ignore
*.obj = ignore
...
*.dml = text/x-abinitio-dml
*.xfr = text/x-abinitio-xfr
*.mpc = text/x-abinitio-mpc
*.mdc = text/x-abinitio-mdc
*.cfg = text/x-abinitio-db-cfg
*.dbc = text/x-abinitio-db-dbc
*.ctl = text/x-abinitio-db-ctl
*.act = text/x-abinitio-activation
*.mp = application/x-abinitio-graph
...
*.cpp = text/plain
*.c = text/plain
*.h = text/plain
.project_names = text/plain
.project_names.local = ignore
...
*.wsdl = application/xml
.WORK = ignore
.WORK-serial = ignore
.WORK-parallel = ignore
*.config = text/x-abinitio-configuration
*.cat = text/x-abinitio-catalog
*.apptempl = application/x-abinitio-application-template
*.jobdef = application/x-abinitio-job-definition
*.cal = application/x-abinitio-calendar
...
.snapshot = ignore
*.csv = text/csv
*.ini = text/plain
.air-batch-commands = ignore
.*.swp = ignore

air project show-common

Displays a list of the specified project’s common projects. This command is branch-
specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air project show-common project-path [-exact [-param]]
Argument Description
project-path Path to the project for which you want to display the list of common
projects.
-exact [-param] The -exact argument lists only the common projects explicitly referenced
by project-path. If -param is also specified, the command displays the
common project path followed by a tab, and then the parameter name
associated with the common project.
Usage
The common project paths are listed one per line.

Common projects are listed in dependency order; projects later in the list may depend on
projects earlier in the list. This order reflects the order in which each project would need to
be loaded by air object load, for example.
air project update-extensions
Upgrades the project extension list to include all the current built-in and custom extensions.
Built-in extensions are the extensions known to the Co>Operating System version used to
issue the command. This command is branch-specific. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air project update-extensions [-reset | -override] project-path
Argument Description
-reset Removes the current contents of the extension list and replaces it with the
built-in extensions from the current Co>Operating System.
-override If an extension already exists in the project, replaces it with the built-in list’s
extension with the same pattern.
project- Specifies the path to the project that you want to update.
path
Usage
Run this command to update the list of file extensions recognized by the Technical
Repository. Typically you would run this command to update a project after installing a
new version of the Co>Operating System. Less commonly, you would run it to undo the
current file extensions list and restore the Co>Operating System version.

You must run this command on each project where you want to add the extensions. For
example, if you want to use the validate extensions feature introduced in Version 3.1.1
(which requires the .act extension), you must issue this command once for each project. For
more information on the validate extensions feature, see “Validación de grafos” in the
Co>Operating System Guía para desarrolladores de grafos.

For more information, see “Extension list” in the Technical Repository Guide to Version
Control.
Examples
To reset the extension list associated with /Projects/myproj, enter the following:

air project update-extensions -reset /Projects/myprog

To override the extension list associated with /Projects/myproj, enter the following:

air project update-extensions -override /Projects/myprog

air project update-files

Computes the repository version for object moves and removes, which were made using
software versions prior to Co>Operating System Version 3.3.2, and stores that repository
version as an entry in the project files list. Running this command improves performance
when creating save files and promoting them. This command is branch-specific. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”. For more information on the project files list, see “Project files list” in
the Technical Repository Guide to Version Control.
Syntax
air project update-files -removes [ -v ] [ -dry-run ] [ directory-path ]
Argument Description
-removes Computes and stores the version at which objects were removed or moved.
-v Displays each project and the number of version updates per project.
-dry-run Displays the effect of issuing the command without actually performing the
changes.
directory- Specifies the project or directory that contains the objects that you want to
path update. If you do not specify this value, the command processes all projects in
the branch.
Usage
We recommend that you run this command as part of the upgrade procedure when
upgrading from Co>Operating System Versions 3.3.1 and earlier. Although usually run
during an upgrade, it is safe to rerun this command if, for example, you want to update a
related directory path at a later time.
You can run this command anytime on Co>Operating System Versions 3.2.1 and lower.
For example, you can run it prior to a promotion and then retag your objects. The
Co>Operating System will issue a warning when it detects that an air object save action
would benefit from running this command.
Example
This example shows how many moved or removed objects will be updated when
this air command is run against the directory /Projects/legacy-build. The example directory
contains three projects:

air project update-files -removes -v -dry-run /Projects/legacy-build

Processing /Projects/legacy-build/2-16-5-Tutorial
Updated 1 file states of removed objects.
Processing /Projects/legacy-build/doc_projects_Examples
Updated 2 file states of removed objects.
Processing /Projects/legacy-build/doc_projects_example_tutorial
Updated 0 file states of removed objects.
3 removed object file states processed.

air promote commands

The air promote commands move objects from one technical repository to another
(promotion) or within a technical repository, and record a history of past promotions. For
more information about promotion and promotion histories, see “Promoting
applications” in the Technical Repository Guide to Version Control.

The following table summarizes the air promote commands. For information about
command syntax, see “Convenciones de la documentación”.

Command Description
air promote list Lists summary information about some or all promotion histories.
air promote load Loads objects from a save file into a target technical repository and
creates a promotion history.
air promote load- Loads a promotion history file.
history-file
air promote make- Searches for fixed issues in comments for object versions and then
comment aggregates the information on all fixed issues that are found.
air promote Removes a promotion history from the specified technical repository.
remove-history
air promote save Saves repository objects to a save file and records a history of the
promotion.
air promote show Displays information about the specified promotion history.
air promote show- Displays information about a save file.
Command Description
save-info
air promote list
Displays summary information about some or all promotion histories. This command
is branch-specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air promote list
[-load-only | -save-only]
[-from version-or-date]
[-to date]
[-last num]
[name]
[-tag tag]
[-user user]
[-tagged-object rpath]
[-full-search rpath]
Argument Description
-load-only | -save If omitted, the command displays both load and save promotion histories.
-only You can choose one:

 -load-only displays only histories of load promotions.

 -save-only displays only histories of save promotions.

-from version- Displays histories of promotions that occurred on or after the specified
or-date date. Specify the date in the format "YYYY-MM-DD HH:MM:SS" or
"YYYY-MM-DD".
-to date Displays histories of promotions that occurred on or before the specified
date. Specify the date in the format "YYYY-MM-DD HH:MM:SS" or
"YYYY-MM-DD".
-last num Integer. Displays only the num most recent promotion histories.
name Displays only the promotion histories of name name. Note that the name
was automatically generated during the promotion. Wildcards such as *
and ? are supported.
-tag tag Displays only the promotion histories of tag tag.
-user user Displays only the promotion histories created by user user.
-tagged-object rp Displays only the promotion histories that include the tagged object
ath specified by rpath. The object must exist in the current technical
repository.
Argument Description
-full-search rpat Searches all promotion histories for any that include the object specified
h by rpath. You can also specify a path that does not exist in the current
technical repository.
Usage
Use the command arguments to restrict the output. If no arguments are specified, the
command displays all promotion histories.

The -full-search argument causes relatively slow operation compared to -tagged-object.

Unlike -tagged-object, this argument searches all histories, including ones that do not
reference tags.
Example
Use several arguments together to restrict the output. For example, to show the histories of
all promotions made by Fred on or after May 6, 2016, and on or before May 10, 2016:

air promote list -from "2016-05-06" -to "2016-05-10" -user fred

The output might be something like this:

LOCAL TIME TYPE STATUS USER NAME

2016-05-06 10:46:10 save success fred 01210085170_Graph1
2016-05-10 14:44:05 load success fred 01210099445_Graph1

Shortcut
The shortcut for this command is air promote ls.
air promote load
Loads objects from a save file into a target technical repository, loads the save promotion
history from the source repository, records a load promotion history, and saves a promotion
history file with the name that you specify. By default, the command analyzes the files and
loads them to the same location as in the source repository. The command can load either
compressed or uncompressed save files. This command simplifies the promotion of
applications when compared to the air object load command. It is equivalent to running the
command air object load -history-file -analyze. Objects that you promote in a repository use
rules that are similar to Unix filesystem rules. Newly created objects are owned by the user
who created them. Modified objects retain their original ownership. To run this command,
the user must have write permission for the /abinitio/promotions/load location in the
technical repository.
NOTA:

To generate the promotion history, the save file must have been created by air promote
save or air object save with either the -exact-tag or the -from-tag options.

This command is branch-specific. For information about the arguments common to

all air commands, see “Command-line syntax of air commands”.
Syntax
air promote load filename
-history-file history-filename
[ -comment comment ]
[ -no-analyze ]
[ -rename-tag tag | -no-tag ]
[ -relocate path-in-source path-in-target ] ...
[ -dry-run ]
Argument Description
filename Name of the save file to load. The value of filename can be
a gzip-compressed file.
-history-file history-filen Path to a history file to create. You load this file into the source
ame repository.
-comment comment Specifies a comment to be associated with the history of this load
promotion.
-no-analyze If specified, dependency analysis is not performed on the loaded
objects.
-rename-tag tag | -no-tag By default, the tag in the save file is applied to the loaded objects
in the target repository. To override this behavior, you can
specify one of these:

 -rename-tag specifies that the tag tag should be applied to

the loaded objects, even if the save file contains a tag.
Useful for reloading into the same technical repository
you created the save file from.
 -no-tag specifies that the loaded objects should not be
tagged even if the save file contains a tag.

-relocate path-in-source Causes the objects in the save file to be loaded to different
path-in-target locations. All paths beginning with path-in-source are loaded
at path-in-target. You can specify multiple -relocate clauses.
-dry-run Reports diagnostics on the effect of running the command, but
does not actually perform the promotion.
Usage
The save file that you load must have been created by air promote save or air object
save with either the -exact-tag or the -from-tag options.

If the Technical Repository administrator has enabled the Require Promotion History
option (air repository options +require-promotion-history), any errors encountered while
creating the promotion history will cause the load operation to fail.

The promotion history file created by the air promote load command contains the history of
a load promotion into the target repository. It includes information about the options used
while loading, as well as any errors or warnings encountered.

The new load promotion history is assigned a random name and is written
to /abinitio/promotions/load. To find the name, run air promote list.

After the load operation is done, run the air promote load-history-file history-
filename command to load that file into the source repository, even if the load operation
failed. This guarantees that the promotion histories in the source and target repositories are
synchronized. Note that history-filename is not the same as the randomly assigned name
written to the target repository.
Example
To load the save file graph1.save and create the promotion history file history-graph1, enter
the following:

air promote load graph1.save \

-history-file history-graph1 \
-comment "load of graph1" \
-no-analyze \

The output might resemble this:

Apply tag: Graph1

Tagging: /Projects/test/mp/test1.mp
Import: /Projects/test/mp/test1.mp
Import: /Projects/test/dat/test7.dat
Import: /Projects/test/dat/test7out.dat
Import: /Projects/test/run/test1.ksh
Import: /Projects/test/dml/test7.dml
Import: /Projects/test/.project-start.ksh
Import: /Projects/test/.project-end.ksh
Import: /Projects/test/.air-project-parameters
Import: /Projects/test

air promote load-history-file

Loads a promotion history file created by either air promote load or air object load. This
command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air promote load-history-file history-filename
Argument Description
history- Path to a promotion history file to load. history-filename is the name you
filename specified to the -history-filename argument of air promote load or air object
load.
Usage
To keep track of promotions, run this command to load the promotion history
file name into the source repository in which the save file was created. This guarantees that
the promotion histories in the source and target repositories are synchronized. You can
delete the history file after loading it into the source repository.
air promote make-comment
Searches for fixed issues in comments on object versions and then aggregates the
information on all fixed issues that are found. This command then appends this information
to the tag comment to indicate which issues will be fixed when this tag is promoted.

This information can later be extracted (via air tag list-fixes) into the DML-described
format, as defined in $AB_HOME/include/fixes-info.dml, and used to trigger state
transitions in workflow systems.

This command is branch-specific. For information about the arguments common to

all air commands, see “Command-line syntax of air commands”.
Syntax
air promote make-comment
tag
[ -since since-tag | -since-previous ]
[ -dry-run ]
[ -no-header ]
[ -fixes-only ]
Argument Description
tag Required. Tag that has a comment that you want to extend with fix
information. This tag also determines which comments to search that are
associated with the specific versions.
-since since-tag | Enter one of the following:
-since-previous
Argument Description

 -since since-tag — Restricts the search to the checkin versions of

objects in tag since their version in since-tag. The start and end
range between the two tags is inclusive.

For more information, see “Specifying version comments to

search” in the air promote commands section.

 -since-previous — If the tag name contains version information in

the form name_Vmajor.minor, this command searches for a
previous version of the tag based on the version in the name.

The command then searches only the checkin versions of objects

in tag since their version in the previous tag found. The start and
end range between the two tags is inclusive.

For example, if the tag version is release_v1.1, -since-

previous would list all checkin versions since release_v1.0.

Use -since-previous if the checkin version of since-tag is not

known.

For details on the manner in which tag checkin versions are determined,
see the -since tag-or-version argument for air tag object-versions.
-dry-run Prints the results of the specified command but does not actually run the
command. The technical repository remains unchanged.
-no-header Does not prefix the comment with a header that describes the contents of
the aggregated comment. See the section “Examples” for an example of a
header.
-fixes-only Print only a newline-separated list of the issue IDs found. Implies -dry-
run.
Usage
air purge commands
The air purge commands purge and archive old versions of objects in a technical repository.
For more information about purging, see “Managing the size of a technical repository” in
the Technical Repository Administrator’s Guide.

The following table summarizes the air purge group of commands. For information about
command syntax, see “Convenciones de la documentación”.
Command Description
air purge cancel Terminates a currently running purge operation.
air purge jobs Permanently removes repository jobs.
air purge monitor Monitors a running purge, displaying the state of the purge and its
progress.
air purge object Permanently removes specific objects from a technical repository.
air purge Removes objects in a technical repository older than the specified
repository version, tag or date/time.
air purge cancel
Cancels a purge currently in progress. This command is repository-wide. For information
about the arguments common to all air commands, see “Command-line syntax of air
commands”.
Syntax
air purge cancel
Usage
Only a Technical Repository Administrator can use this command.

Note that there is a point of no return, after which a purge cannot be canceled.
air purge jobs
Permanently removes and optionally archives repository jobs. This command is branch-
specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air purge jobs {version-specifier | -number number | version-specifier -
number number}
{rpath ... | -all}
[-archive archive-file]
[-quiet]
[-force]
[-background]
[-dry-run]
Argument Description
version-specifier Purges jobs created before a particular version or date, specified as:

-version version | -date date | -days days

Argument Description

 -version version specifies a version number or tag. All jobs

created before this version are candidates for removal.
 -date date specifies a date and time in the format "YYYY-MM-
DD HH:MM:SS". All repository jobs created before this date
are candidates for removal.
 -days days specifies the number of days' worth of jobs to
keep. days is an integer. (See “Usage”.)

If version-specifier is omitted, you must specify -number number.

-number number Specifies the minimum number of jobs to retain for each graph, plan, or
input pset. number is an integer.

If number is omitted, the minimum is 0, meaning all jobs are candidates

for removal. If -number number is omitted, you must
specify version-specifier.
rpath ....| -all Specifies one or more paths or all paths as the starting point for job-
removal consideration.

 rpath is a directory or a graph, plan, or input pset. If rpath is

omitted, you must specify -all.
o If rpath is a directory, all repository jobs in the directory
and its subdirectories are considered for removal.
o If rpath is a graph, plan, or input pset, only jobs
associated with that graph, plan, or input pset are
considered.
 -all specifies that jobs at all technical repository paths are to be
considered for removal.

-archive archive- Creates the file archive-file in portable interchange format.

file
-quiet Turns off the display of information about the progress of the purge or
about the jobs being removed.
-force Turns off the prompt for confirmation of the purge.
-background Starts the purge, exits, and runs the purge in the background on the
Technical Repository server. The purge can be monitored with air purge
monitor or canceled with air purge cancel.
-dry-run Outputs the list of jobs to be purged, but doesn't actually execute the
purge.
air purge monitor
Monitors a running purge, displaying the state of the purge and its progress, as well as the
purge boundary. This command is repository-wide. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air purge monitor [-1] [-wait] [-boundary]
Argument Description
-1 Displays the current status, then exits.
-wait Silently monitors the purge, exiting when it completes successfully, fails, or is
canceled.
-boundary Displays the current purge boundary, then exits. If a purge is currently in
progress, it is noted in the output.
Usage
Only a Technical Repository Administrator can use this command.
air purge object
Permanently removes old objects from a technical repository. This command is repository-
wide. For information about the arguments common to all air commands, see “Command-
line syntax of air commands”.
Syntax
air purge object
[-quiet]
[-force]
[-background]
[-R]
rpath [...]
Argument Description
-quiet Turns off the display of purge progress information.
-force Turns off the prompt for confirmation of the purge.
-background Starts the purge, exits, and runs the purge in the background on the Technical
Repository server. The purge can be monitored with air purge monitor or
canceled with air purge cancel.
-R Recursively traverses subdirectories of rpath when rpath refers to a
directory. If -R is omitted, the directory you specify must be empty;
otherwise, the command fails.
rpath [...] Path to one or more objects or directories to be removed. Objects can be
specified as a technical repository path, OID, or domain number.
(See “Specifying object names as arguments”.) The entire domain containing
the object is removed.
Usage
Only a Technical Repository Administrator can use this command. For more information,
see “Purging individual objects” in the Technical Repository Administrator’s Guide.

After you have run air object rm, which removes only the current version of an object, you
can run air purge object to remove the remaining versions. When you run air purge object,
specify rpath as the object’s domain number.

To run this command from the Execute Command dialog (F8) of the TRMC, you must
specify -force; Execute Command does not support interactive operation.
Examples
Purging all versions of a graph
To purge all versions of the graph length-test.mp and run the command in the background,
type:

air purge object -background '/Projects/test/mp/length-test.mp'

Note that the job associated with this graph, if any, will also be purged.
Purging the domain of a graph
To purge the entire domain of graph length-test.mp, thereby purging all versions of all
objects associated with the graph, specify the graph’s domain number. (You can identify
the domain by running air object ls with the -ld arguments against the graph.) For example:

air purge object 1064

air purge repository

Permanently removes and archives nontagged repository objects older than the specified
version, or date/time. This command is repository-wide. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air purge repository
{-version version | -date date}
{-archive archive-file | -no-archive}
[-no-remove-jobs]
 [-no-remove-tags]
[-quiet]
[-force]
[-background]
Argument Description
-version version | -date date Specifies a version number or date and time that the
command uses to compute the purge boundary.
See “Usage” for a description.

You must specify -version or -date.

 -version specifies the version number of the requested

purge boundary.
 -date specifies a date and time in the format "YYYY-
MM-DD HH:MM:SS". The date and time are used to
compute a version number. The following date
specification chooses the lowest numbered version
created on or before May 21, 2016, at 1:45:34 PM.

-date "2016-05-21 13:45:34"

-archive archive-file | -no-ar You must specify -archive or -no-archive.

chive
 -archive creates the file archive-file, which can be
used to re-create a technical repository containing all
versions of all objects at and below the purge
boundary.
 -no-archive does not create an archive file.

-no-remove-jobs Does not remove jobs whose last change occurred below the
purge boundary.
-no-remove-tags Does not remove tags between the requested purge boundary
and the actual purge boundary.
-quiet Turns off the display of information about the progress of the
purge.
-force Turns off the prompt for confirmation of the purge.

NOTA:

You must specify -force when you run this command from
the Execute Command dialog (F8) of the TRMC; Execute
Command does not support interactive operation.
-background Starts the purge, exits, and runs the purge in the background
Argument Description
on the Technical Repository server. The purge can be
monitored with air purge monitor or canceled with air purge
cancel.
Usage
Only a Technical Repository Administrator can run this command.

For more information, see “Running the air purge repository command” in the Technical
Repository Administrator’s Guide.
Purge boundary
The purge boundary is the version below which objects can be removed from the technical
repository. For example, if the purge boundary is version 50, all objects at version 49 and
lower can be removed.

In general, versions of an object will be removed if they are below the purge boundary and
there is a newer version of the object. Conversely, an object below the purge boundary
will not be removed if it is the latest version of an object. Rather, its version is updated to
that of the purge boundary.

The command computes the purge boundary based on the version, tag, or date/time you
specify. However, it may lower the purge boundary if you choose to keep tags and/or jobs.

For more information, see “How the purge boundary controls which objects are removed”.
Tags
By default, this command purges all versions of objects that are referenced by tags if the
objects are below the specified purge boundary and the object version is not the latest
version, even if those versions are referenced by tags. If an object version referenced by a
tag is purged, the tag itself is also purged.

If you do want to automatically purge tags, use the -no-remove-tags option. The associated
graphs will not be purged, and all objects that are at the same version as the graphs will be
kept. This option has the effect of lowering the purge boundary to the version of the graph.
Therefore, all objects between the requested purge boundary and the actual purge boundary
are kept.

Tags make purging less effective. For this reason, we recommend that you remove old tags.

For more information, see “How tags affect the purge boundary”.
Jobs
Jobs can reference older versions of graphs. By default, if a graph is purged, the
corresponding job is also removed. Also, by default, all jobs older than the requested purge
boundary are removed, regardless of the actual purge boundary computed by preservation
of tags.

If you do want to automatically purge jobs, use the -no-remove-jobs option. The associated
graphs will not be purged, and all objects that are at the same version as the graphs will be
kept. This option has the effect of lowering the purge boundary to the version of the graph.
Therefore, all objects between the requested purge boundary and the actual purge boundary
are kept.

If you want to remove only jobs, run air purge jobs.

For more information, see “Jobs and the purge boundary”.

Archiving purged data
Once versions are purged from a technical repository, they are no longer accessible to you
from that repository.

However, if you specify the -archive archive-file argument, the Technical Repository server
writes the purged data to an archive file on the machine where the purge operation is
actually running, regardless of where you issued the command.

The archive file is a snapshot of the technical repository as of the purge boundary. It is a
repository image file that you can load using air repository load-from-image to re-create the
repository as it existed at the purge boundary. This may be useful if you later need to access
objects that were purged.

air reposit commands (deprecated)

The air reposit commands populate the technical repository with files in the filesystem. The
following table summarizes the air reposit commands. For information about command
syntax, see “Command-line syntax of air commands”.

These commands have been deprecated. Refer to each command description for the
replacement command(s) to use.

Command Description
air reposit dataset file Deprecated. Use the following instead: air sandbox dataset file.
(deprecated)
air reposit dbc Deprecated. Use the following instead: air sandbox dataset file to create a
(deprecated) file in the sandbox and then air sandbox import to check in the file.

air reposit dml Deprecated. Use the following instead: air sandbox dataset file to
(deprecated) create a file in the sandbox and then air sandbox import to check in
the file.
air reposit html Deprecated. Use the following instead: air sandbox dataset file to
(deprecated) create a file in the sandbox and then air sandbox import to check in
Command Description
the file.
air reposit mime Deprecated. Use the following instead: air sandbox dataset file to
(deprecated) create a file in the sandbox and then air sandbox import to check in
the file.
air reposit text Deprecated. Use the following instead: air sandbox dataset file to
(deprecated) create a file in the sandbox and then air sandbox import to check in
the file.
air reposit dataset file (deprecated)
Creates an analysis-only file dataset in the technical repository. This command is branch-
specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air reposit dataset file url rpath type-location [-expand] [-eme] [-discover
| -user-managed]
Argument Description
url Documentation property that you can specify with a file
location. url can be "", an empty string.
rpath Location in the technical repository where the dataset should be
created.
type-location Name of the dataset’s type in the filesystem — for example, an
imported .dml file. The type-location argument might also be a
file containing the record format for that dataset. If -eme is also
specified, type-location must be a technical repository path.
-expand Expands the metadata, creating an internal representation of the
record format (for example, to create dataelement instances).
-eme If specified, type-location must be a technical repository path.
-discover | -user-managed Controls whether dependency analysis will update the dataset’s
metadata. You can specify one of the following:

 Specify -discover to have dependency analysis update

the dataset’s metadata.
 Specify -user-managed (default) to have dependency
analysis not update the dataset’s metadata.

Usage
This command has been deprecated. Use the air sandbox dataset file command instead.

You can reposit a dataset under /Projects when it needs to be under source-code control or
when it is part of the project. Otherwise, you can reposit the dataset under /Metadata.
PRECAUCIÓN:

Under no circumstances should you reposit data into /abinitio.

air reposit dbc (deprecated)

Copies a database configuration (.dbc) file into a project, adding it to the project and setting
the appropriate MIME type. This command is branch-specific. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air reposit dbc dbc-file project-name
Argument Description
dbc-file Sandbox path to the database configuration file you want to reposit.
project-name Name of the project in which the database configuration file belongs.
Usage
This command has been deprecated. Use the following instead: air sandbox dataset file to
create a file in the sandbox and then air sandbox import to check in the file.

The database configuration file will be reposited under the db subdirectory of the specified
project with the same filename. If the file already exists at this location, it is replaced.

We recommend that you use air project import to get files into the technical repository.
air reposit dml (deprecated)
Checks in one or more record format (.dml) files to the technical repository and adds them
to the project. This command is branch-specific. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air reposit dml [-no-add] repository-location
[-basedir sandbox-location]
[-xfr filename ...] [-dml filename ...]
[-pkg filename ...] [-dir dir-name ...]
Argument Description
-no-add Specifies that files are not to be added to the project. If omitted,
files are added to the project only if the technical repository
location resides within a project.
repository-location Specifies the location in the technical repository to which the
files are copied.
-basedir sandbox-location Specifies the sandbox location. Default is the current working
Argument Description
directory.
-xfr filename ... Specifies one or more files containing either transforms or a
mixture of type and transform definitions.
-dml filename... Specifies one or more files containing DML type definitions.
-pkg filename... A synonym for -xfr -filename....
-dir dir-name... Specifies one or more directories to be recursively searched
for .xfr and .dml files to be imported.
Usage
This command has been deprecated. Use the following instead: air sandbox dataset file to
create a file in the sandbox and then air sandbox import to check in the file.

NOTA:

If you are repositing a record format file into a project, use air project import instead.

This command determines technical repository locations according to the following

algorithm:

1. All sandbox locations are converted to absolute paths.

2. sandbox-location is replaced with repository-location.

3. If the path does not begin with sandbox-location, the operation terminates.

air reposit html (deprecated)

Copies a text file to a technical repository, gives the file the MIME type text/html, and adds
the file to the project. This command is branch-specific. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.

NOTA:

If you are repositing an HTML file into a project, use air project import instead.

Syntax
air reposit html [-no-add] ilename rpath
Argument Description
-no-add Optional. Specifies that the files are not to be added to the project. If omitted,
the file is added to the project only if the technical repository location resides
within a project.
filename URL of the text file to be checked in to the technical repository.
Argument Description
rpath Path to the technical repository location where you want the files to be copied.
Usage
This command has been deprecated. Use the following instead: air sandbox dataset file to
create a file in the sandbox and then air sandbox import to check in the file.
air reposit mime (deprecated)
Copies a file to a technical repository, stores its contents as a MIME object having a
specified type, and adds the file to the project. This command is branch-specific. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.

NOTA:

If you are repositing a MIME object into a project, use air project import instead.

Syntax
air reposit mime [-no-add] MIME-type pathname rpath
Argument Description
-no-add Specifies that the files are not to be added to the project. If omitted, the file is
added to the project only if the technical repository location is within a project.
MIME- MIME type associated with the object. For information about MIME types,
type see “Sample extension list” in the Technical Repository Administrator’s Guide.
pathname Path to the file to be checked in to the technical repository.
rpath Path to the technical repository location where you want the file to be checked
in.
Usage
This command has been deprecated. Use the following instead: air sandbox dataset file to
create a file in the sandbox and then air sandbox import to check in the file.
air reposit text (deprecated)
Copies a text file or one or more text strings to a technical repository, assigns the item the
MIME type text/plain, and adds the item to the project. This command is branch-specific.
For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air reposit text [-no-add] {-string string [-string string] ... |
pathname} rpath
Argument Description
-no-add Specifies that the files are not to be added to the project. If
omitted, the file is added to the project only if the technical
repository location resides within a project.
-string string | pathname Choose one of the following:

 -string string is a text string. You may specify

multiple -string clauses.
 pathname is a path to the file.

rpath Path to the technical repository location where you want the file
or strings to be copied.
Usage
This command has been deprecated. Use the following instead: air sandbox dataset file to
create a file in the sandbox and then air sandbox import to check in the file.

This command is often used to put enterprise metadata into the technical repository —
specifically, non-built-in objects that you want to add to categories.

NOTA:

If you are repositing a text file into a project, use air project import instead.

air repository commands

The air repository commands operate on the storage system of the technical repository
rather than on its content. Most of these commands can only be executed by the Technical
Repository administrator.

The following table summarizes the air repository commands. For information about
command syntax, see “Command-line syntax of air commands”.

Command Description
air repository access- Controls the access of non-administrators to a technical
mode repository.
air repository add-data- Adds a new data file to a technical repository.
file
air repository backup Launches a backup program, first locking the technical
repository.
air repository check Inspects the repository disk data allocation and displays
allocation diagnostics.
air repository check data Inspects the data structures that describe a domain and displays
Command Description
diagnostics if the data allocation is corrupted.
air repository check Inspects the data structures that describe a domain and displays
domain diagnostics.
air repository check Checks referential integrity within a technical repository.
referential-integrity
air repository chmod Changes technical repository file permissions.
air repository chown Changes ownership of a technical repository.
air repository compress- Compresses differences in a repository after converting to storage
diffs format 16.
air repository Displays information about technical repository connections.
connections
air repository convert- Converts a technical repository from an older storage version
storage-format (format) to a newer storage version.
air repository create Creates an empty technical repository.
air repository create- Saves a technical repository in a portable text-based format.
image
air repository destroy Destroys a technical repository.
air repository load-from- Re-creates a technical repository from a saved image file.
image
air repository online- Cancels the currently running online-backup process.
backup cancel
air repository online- Displays internal information about an online-backup process.
backup dump
air repository online- Extracts one or more files from the specified set of online-backup
backup extract files.
air repository online- Displays status information about an in-progress online-backup
backup monitor process or about the last completed or failed online backup.
air repository online- Creates a technical repository from the specified set of online-
backup restore backup files.
air repository online- Schedules and manages automated online-backups.
backup schedule
air repository online- Starts an online-backup process on the machine hosting the
backup start technical repository.
air repository online- Does an integrity check on the specified set of backup files and
backup verify reports errors.
air repository options Turns technical repository user authentication on and off.
air repository rename Renames all the files in a technical repository.
air repository restart Shuts down and restarts the Technical Repository server process.
air repository revert Reverts to a previous version of a technical repository.
air repository show Displays information about the technical repository.
air repository show- Displays information about the Technical Repository server.
Command Description
server
air repository shutdown Shuts down the Technical Repository server process.
air repository start Starts the Technical Repository server process.
air repository tag Assigns a name to a technical repository version.
air repository trigger Creates, enables, and maintains trigger objects in a technical
commands repository.
air repository version- Prints, sets, or appends a comment for a specified repository
comment version.
air repository version- Displays detailed information about technical repository versions.
info
air repository version- Displays information on issues marked as fixed in the specified
list-fixes versions as described in the comment field.
air repository access-mode
Controls or displays the access of non-administrators to a technical repository. This
command is repository-wide. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air repository access-mode {-normal | -readonly | -deny | -status} [-
force]
Argument Description
-normal | -readonly | -deny | -status You must choose one of these:

 -normal means non-administrators have

default access.
 -readonly means non-administrators can read
the technical repository, but only Technical
Repository administrators can write to it.
 -deny means non-administrators cannot
connect to the technical repository.
 -status displays the current mode: Normal,
Read-only, or Deny.

-force When a mode change requires the Technical

Repository server process to be shut down, shutdown
occurs without prompting you for confirmation.
Usage
Only a Technical Repository Administrator can run this command. The access mode you
set persists until you explicitly change it.
This command shuts down and restarts the Technical Repository server only if the mode
changes from less restrictive to more restrictive. For example, changing from Normal to
Deny mode shuts down the server, but changing from Deny to Read-only mode does not.
air repository add-data-file
Adds data files to a technical repository in Version 2.14 format or later. This command
is repository-wide. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air repository add-data-file [-size size] [-count count]
Argument Description
-size size The value of size can be either 1024 or 8192. Default is 8192.
-count count The value of count is an integer representing the number of data files to add.
Default is 1.
Usage
You must run this command on the machine the technical repository resides on. In addition,
the Technical Repository client and the Technical Repository server process must be at the
same version.
air repository backup
Calls a user-supplied backup program, first shutting down the Technical Repository server,
which causes clients that are connected at the time to disconnect. After the backup is
complete, unlocks the technical repository. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.

NOTA:

When you run this command you must be in the top-level directory of the technical
repository that you want to back up.

Syntax
air repository backup [-file filename] [-abspath] {-backup-file filename
[-compress] | program args}
Argument Description
-file filename Specifies the path to the file in which to store the
names of all files to be backed up, one file per line.
-abspath Displays the absolute paths of the technical repository
files. If omitted, the filenames without their
containing directory are displayed.
Argument Description
-backup-file filename [-compress] Specify one of the following:
| program args
 -backup-file filename specifies the file in
which to write a backup in tar format.
Optionally -compress compresses (gzips) the
backup file.
 program args specifies the name of the
backup program and the arguments to that
program. If '{}' is specified, the names of all
technical repository files are substituted for {}
when the backup program is invoked.

Usage
You must run this command on the machine the technical repository resides on. In addition,
the Technical Repository client and the Technical Repository server process must be at the
same version.

We strongly recommend that you keep the repository shut down for short periods of time.
This means that using a tar command to mount a tape from within air repository backup, for
example, would not be optimal. Instead, use air repository backup to archive the repository
to one big file. Then, after the backup is done, run a separate command to back up the file
to tape.

Before the command begins the backup, it disconnects all currently connected clients.

The tar program does not work on all platforms with files larger than 2 GB. If your file will
be larger than this limit, use the -backup-file option or use Xtar, which is shipped with the
Co>Operating System.

Use gunzip to uncompress the backup file.

Compare this command with air repository online-backup start, which backs up the
technical repository while it is active.
Examples
To create a new tar file named eme-backup.tar and display the name of each technical
repository file, type:

air -root /disk3/data/eme repository backup \

tar cvf eme-backup.tar '{}'
To have the tar command take the list of files to be backed up from backup.lst and then
generate a tar file named eme-backup.tar, change (cd) to the technical repository directory
and type:

air repository backup -file backup.lst tar cvf \

eme-backup.tar -T backup.lst

To create a new tar file named eme-backup.tar, type:

air -root /disk3/data/eme repository backup \

-backup-file eme-backup.tar

air repository check allocation

Inspects the technical repository's disk data allocation and displays diagnostics if corruption
is found. This command is repository-wide. For information about the arguments common
to all air commands, see “Command-line syntax of air commands”.
Syntax
air repository check allocation
[-force]
[domain ...]
Argument Description
-force Shuts down the Technical Repository server process without prompting for
confirmation.
domain ... Specifies one or more domains to be checked. You can specify a domain as a
path or as an OID. See “Specifying object names as arguments”. If not
specified, all domains are checked.
Usage
This command shuts down the Technical Repository server and can only be run on the
machine on which the technical repository resides. Run this command weekly.

If you run this command automatically from a script, you must add the -force argument. If
you do not, the script will wait for confirmation at the shutdown prompt. This is
particularly true for scripts created prior to Version 3.1.6 (when this feature was
introduced) because these will stop running until you add the -force argument.
Diagnostic messages
If diagnostic messages are reported, contact Departamento de soporte técnico de Ab Initio
at +1 781-301-2100 or [email protected].
air repository check data
Inspects the data structures that describe a domain and displays diagnostics if the data in the
physical repository files is corrupted. This command is repository-wide. For information
about the arguments common to all air commands, see “Command-line syntax of air
commands”.
Syntax
air repository check data [ -force ] domain ...
Argument Description
-force Shuts down the technical repository server process without first prompting for
confirmation.
domain ... Specifies one or more domains to be checked. If you do not specify a domain,
the command checks all domains in the repository. You can specify a domain as
a path or as an objectID (OID). See “Specifying object names as arguments”.
Usage
This command shuts down the Technical Repository server and can only be run on the
machine that the technical repository resides on.

Run this command when you suspect that repository files may be corrupted. This can
happen, for example, when a repository is moved from one host to another by manually
copying the files, instead of using the proper online backup and image creation commands.

If this command displays diagnostic messages after you run it, it is likely that repository
files are corrupt and you will need to restore them from a repository backup. For assistance,
contact Departamento de soporte técnico de Ab Initio at [email protected] or +1 781-
301-2100.
Example
The following example checks a technical repository and reports that it found no data file
errors:

air repository check data

You are about to shut down the EME server process for /disk1/sand/cust12/EME/repo
Are you sure you want to do this (yes/no)? yes
Shutting down EME server
No errors found.

air repository check domain

Inspects the data structures that describe a domain and displays diagnostics if the data
structures are corrupted. This command is repository-wide. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.

Syntax
air repository check domain domain ...
Argument Description
domain ... Specifies one or more domains to be checked. You can specify a domain as a
path or as an OID. See “Specifying object names as arguments”.
Usage
This command shuts down the Technical Repository server and can only be run on the
machine that the technical repository resides on.

Run this command when you suspect that a domain may be corrupted — for example, you
have trouble accessing a specific domain.
air repository check referential-integrity
Checks referential integrity within the specified domains and displays a report of its
findings. You can check either the current versions of all domains or all versions of one or
more domains. Optionally, this command repairs the errors it finds in the current version.
This command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air repository check referential-integrity
[-quiet|-verbose]
[-R]
[-all]
[-repair-missing]
location...
Argument Description
-quiet | -verbose By default, the command displays a progress report (percentage
complete) and errors.

 If -quiet is specified, the command displays errors only.

 If -verbose is specified, the command reports what it is
examining.

-R If specified, recurses through subdirectories. To use -R,

Argument Description
specify location as a technical repository path or an OID.
-all If specified, checks the current version of all domains in the technical
repository.
-repair Attempts to fix referential integrity errors for the current version.
Referential integrity errors in past versions cannot be repaired.
-repair-missing Attempts to fix referential integrity errors caused by missing domains,
typically the result of a bad purge operation. If specified, the only other
meaningful argument to specify is -quiet.
location... Required if -all is not specified. One or more technical repository
domains specified as any of these:

 Repository path — For example, /Projects/myproj

 OID — For example, @32.1.0
 Domain number — For example, 32
 Domain and version — For example, 32.186

Usage
This process is likely to take a long time if -R is specified. If you are checking many
domains, use the -all option; the command is relatively fast.

Referential integrity errors in past versions of the technical repository can be detected but
not repaired. These errors will NOT affect use of the repository at the current version.

This command produces different output depending on whether you

specify -verbose, -quiet, or neither of these. For example, assume a repository has 40000
domains and no errors. Supplying -verbose produces output of 40000 lines. Supplying -
quiet produces no output. Supplying neither option produces a progress report of about 100
lines.
Example
To check the referential integrity of the current version of all domains in
the myeme technical repository (assuming AB_AIR_ROOT is set), type:

air repository check referential-integrity -quiet -all -repair

Alias
The alias for this command is air repository check-ri.
air repository chmod
Changes permissions on a technical repository. Fails if you do not own the repository. This
command is repository-wide. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air repository chmod permissions
Argument Description
permissions Permissions to be set expressed numerically — for example, 640.
Usage
For more information about changing permissions, see “Setting technical repository
permissions on objects” in the Technical Repository Administrator’s Guide.
Example
To make the technical repository readable by all users and writable only by you (the
administrator), type the following:

air repository chmod 644

air repository chown

Changes ownership of the technical repository’s datastore and, optionally, the group. This
command is repository-wide. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air repository chown user [: group]
Argument Description
user Valid username.
: group Valid group name. You must type the colon followed by a space.
Usage
The username can be changed only by root. The group name can be changed by root or by
the owner of the file, provided the owner is a member of group.
air repository compress-diffs
Compresses differences in the specified objects between technical repository storage format
version 16 and 15 or earlier. Run this command after converting an older storage format to
version 16 (introduced in Co>Operating System Version 3.1.4).

Storage format 16 introduces more compact version differencing on files that you check in.
For example, if you have a large DML file and change a single line in it, technical
repository storage formats 15 and earlier reposited the entire DML file. As of storage
format 16 and higher, the repository stores only the modified line. This command increases
the disk space that the repository uses; however, most of it is free space that is available for
reuse — potentially as much as 20–50 percent. To reclaim this space, use air repository
create-image followed by air repository load-from-image (see “Usage”).

NOTA:

The repository must be offline during this operation, which shuts down and compacts the
repository.

This command is repository-wide. For information about the arguments common to

all air commands, see “Command-line syntax of air commands”.
Syntax
air repository compress-diffs
[-quiet]
[-background]
[-R]
[rpath ...]
Argument Description
-quiet Suppresses the display of progress information.
-background Starts the compression in the background and then exits to the shell. You can
monitor the background process with the air purge monitor command.
-R When rpath refers to a directory, recursively traverses subdirectories
of rpath.
rpath ... Specifies one or more objects to be compressed. Objects can be specified as a
path, object ID, or domain number. If no rpath is specified, the entire
technical repository is processed.
Usage
This command does not shut down the technical repository; it runs in the background.
Because it uses the air purge command infrastructure, you cannot purge, delete branches, or
back up the repository until air repository compress-diffs finishes. For example, running
this command on a 30 GB technical repository may take about two hours.
 This command only works on a repository that uses storage format version 16 or later. You
cannot run it to save space on earlier storage formats, nor will running it multiple times
save additional space.

To compress object differences:

1. To convert to storage format 16, restart your technical repository, and run air
repository compress-diffs.

For procedure details, see “Restart the server and convert the storage format” in the
Technical Repository Release Notes.

2. To compress objects, enter the following:

air repository compress-diffs

To reclaim newly freed space for reuse:

1. After running the air repository compress-diffs command, save the contents of the
technical repository to an image file:

air repository create-image filename

NOTA:

This command shuts down the repository, so perform this procedure during a time
when the repository can be offline.

2. Load the saved image:

air repository load-from-image repository filename

air repository connections

Displays information about technical repository server connections. Use this command to
perform tasks such as monitoring a technical repository server under high load situations or
for identifying users who hold process locks. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air repository connections
 [-verbose]
[-m]
Argument Description
-verbose Displays additional output fields. For the list see, “Usage”.
-m Writes the command results in machine-readable output to standard output. The
DML that describes the output is located
in abinitio/default/Projects/root/dml/tr_connections.dml in the technical
repository.
Usage
For each connection to a technical repository, this command displays the following
information fields:

 Connection ID
 Technical repository username
 Server and middle tier or air command process IDs
 Middle tier or air command client hostname
 Connection start time
 Command line or client information

When the -verbose argument is used, the command displays the following additional fields:

 Remote procedure call count, repository branch, client process ID, username,
hostname, and software version
 Middle tier or air command client software version and server name
 Technical Repository server air-server process ID and its software version

Examples
The following example uses the command short cut to display basic information about a
repository:

air connections
ID User Name Server PID MT PID MT Host Start Time Client Application
-- --------- ---------- ------ ------- ---------- ------------------
22 rhaddlet 11626 11626 linux-l 2015-06-24 16:05:00.325 AIR
/disk1/sand/rhad/Xthick-air connections

The following example uses the command to display verbose information about the same
repository:
air connections -verbose
ID: 23 RPC count: 44 Start: 2015-06-24
16:05:18.125 Branch: Command: /disk1/sand/rhad/Xthick-air
connections -verbose
Client - PID: 11637 User: rhaddlet Version: 3.2.4.r21.0 Host: rhaddleton-l Application:
AIR MT - PID: 11637 Host: linux-l Version: MTS Name: Server
- PID: 11637 User: rhaddlet Version: 3.2.4.r21.0

Alias
The alias for this command is air connections.

air repository convert-storage-format

Converts a technical repository from an older storage format to a newer one. This command
is repository-wide. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air repository convert-storage-format
[-dry-run]
[-force]
[-repair]
[new-format]
Argument Description
-dry-run The conversion is not completed, but information is displayed about what
conversion would be attempted.
-force Converts the technical repository without prompting you for confirmation.
-repair Repairs the tag index in a repository that was converted to storage
format 17 using Co>Operating System Version 3.1.6. This option is valid only
if both the current storage format and the requested storage format are
format 17. It generates an error if used with any other format version numbers.
new- To see the valid values for new-format, run the command with -dry-run only.
format If new-format is omitted, the technical repository is converted to the newest
format.
Usage
Use this command with the -dry-run option to determine the current format of your
technical repository and to identify the latest format. If your repository is not in the latest
format, use air repository convert-storage-format to update the format. We recommend that
you allow the repository to choose the appropriate format for your operating system.
The value of n-ways depends on the size of your repository, the number of CPUs available,
the load you want to place on your machine, and other related factors. A value of 4 to 8
seems reasonable for most repositories.

You must run this command on the machine the technical repository resides on. In addition,
the Technical Repository client and the Technical Repository server process must be at the
same version. This operation is irreversible.
Example
To identify the current format without actually converting the technical repository, type:

air repository convert-storage-format -dry-run

The screen displays information about the current format, the newest format, and the
recommended format:

Current format: 15, Latest: 17, Recommended: 16, Chosen New Format: 16
dry run completed

If you then run the command without the new-format option (which lets the repository
choose the recommended version), the output would look something like this:

air repository convert-storage-format

Current format: 15, Latest: 17, Recommended: 16, Chosen New Format: 16
Starting conversion.
You are about to shut down your EME server and convert your EME technical
repository /disk1/sand/my/EME/repo from format 15 to new format 16.
This operation cannot be undone.
Are you sure you want to do this (yes/no)? yes
Conversion done.
New format is: 16

If you instead run the command and specify 17 as the new-format option, the output would
look something like this:

air repository convert-storage-format 17

Current format: 16, Latest: 17, Recommended: 16, Chosen New Format: 17
Starting conversion.
You are about to shut down your EME server and convert your EME technical
repository /disk1/sand/my/EME/repo from format 16 to new format 17.
This operation cannot be undone.
Are you sure you want to do this (yes/no)? yes
Conversion done.
New format is: 17

Related topics

 air repository show

 “Identifying the version and format information” in the Technical Repository
Administrator’s Guide

air repository create

Creates a technical repository and installs built-in components and Ab Initio projects (like
the Ab Initio Environment) into the new repository. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air repository create [repository-path] [-files nfiles]

Argument Description
repository- Filesystem pathname of the technical repository to be created. If not
path specified, defaults to the value of the AB_AIR_ROOT configuration variable
or the -root argument (see -root).
-files nfiles Number of data files to be created. The default value is 2. See “Usage
information” (below).
Usage
You need to create a directory in a filesystem having at least 50 GB of free disk space. By
default, the command automatically schedules online backups. These backups do not stop
the server; by default, the repository creates automatic backups on Wednesday at 2:00 AM.
To change the default values, see “air repository online-backup schedule”. To disable the
automatic backup feature, use air repository online-backup schedule -disable.

Failure to heed the following warnings may result in irrecoverable data loss.

ADVERTENCIA:

You must not choose an NFS-mounted filesystem.

ADVERTENCIA:
For a repository storing vital data, choose a reliable disk system, such as a mirrored/RAID
disk array.

ADVERTENCIA:

It is essential that you back up your technical repository using air repository online-backup
start or air repository backup.

There is an operating-system-dependent limit on how much data can be stored in each file.
The limit depends on how much of a process’s address space is available for memory-
mapped files. Half a gigabyte is a conservative estimate of this limit for most operating
systems. Thus, a technical repository built with the default of 64 data files should be
capable of growing to 32 GB.

When you create a repository, it contains a built-in group called eme-root. All users in this
group are recognized as Technical Repository administrators.

You must run air repository create on the same machine as the repository. In addition, the
Technical Repository client and the Technical Repository server process must be at the
same version. The command fails if the repository already exists or if you do not have
permission to create the required files.
Examples
To create a new technical repository called neweme that contains
the Projects and Users directories and other system objects, type:

air -root /disk1/data/neweme repository create

Alternatively, type:

export AB_AIR_ROOT=/disk1/data/neweme
air repository create

Alias
The alias for this command is air create-image.
air repository destroy
Destroys the technical repository, first prompting you for confirmation. This command
is repository-wide. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
ADVERTENCIA:

This operation is irrevocable.

Syntax
air repository destroy [-force]
Argument Description
-force Specifies not to prompt for confirmation before destroying the technical
repository.
Usage
The technical repository name is determined by the setting of
the AB_AIR_ROOT configuration variable or the -root option to the air utility. (For more
information, see -root.)

Only the owner can destroy a repository. The command fails if you do not own the
repository or if you do not confirm the action when prompted.

Also, before you can remove a repository, you must close the GDE if your repository
settings point to that repository and you must log out of the Technical Repository Web
Interface.

You must run this command on the machine the repository resides on. However, the
Technical Repository client and the Technical Repository server process do not have to be
at the same version.
air repository load-from-image
Creates a technical repository from a saved image file previously created by air repository
create-image. This command is repository-wide. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air repository load-from-image repository
filename
[-no-convert]
[-files nfiles]
[-parallel n-ways]
[-progress]
[-no-install-schema]
Argument Description
repository Path to the root of the technical repository to be created; the value
Argument Description
of AB_AIR_ROOT.
filename Name of the file storing the saved image of the technical repository.
See “Usage”.
-no-convert Specifies that the created technical repository should not be converted to the
latest repository storage.
-files nfiles Number of data files to be created. Default value is 2. See “Usage” for air
repository create.
-parallel n - When loading from versions lower than 2.14 to Version 2.14 (and higher),
ways allows the storage-level conversion to run n ways parallel on Unix and
Linux systems. n-ways must be an integer greater than 1.
-progress Displays information about the progress of the load operation, if available.
-no-install- If this argument is specified, the current object schema is not installed after
schema the load. (See air system install schema.)
Usage
If filename is specified as “-” (hyphen), the saved data is read from standard input. This is
useful for getting the data from some source other than an immediate file. For example, you
can use the following (from a shell) to restore from a compressed image file:

export AB_AIR_ROOT=full-path-to-repository-to-be-created
zcat filename.Z | air repository load-from-image $AB_AIR_ROOT "-"

Also, filename can be a gzipped or compressed file.

The value of n-ways depends on the size of your technical repository, the number of CPUs
available, the load you want to place on your machine, and other related factors. A value of
4 to 8 seems reasonable for most repositories.

You must run air repository load-from-image on the same machine as the repository resides
on. In addition, the Technical Repository client and the Technical Repository server process
must be at the same version.

If you run air repository create-image followed by air repository load-from-image on a

technical repository that has a lot of free space in its data files, the resulting repository will
be smaller, because the amount of free space has been reduced. However, if the original
repository has little free space, the resulting repository may be larger, since temporary
space is allocated during the load-from-image operation. This does not pose a problem, as
the free space will be used as you add objects to the repository.

SUGERENCIA:
To determine the amount of free space in a technical repository, run air repository
show with the -files option.

We recommend that you use the air repository online-backup commands for backup
purposes rather than air repository create-image.
Alias
The alias for this command is air load-from-image.
air repository online-backup cancel
Cancels a running online-backup process started by air repository online-backup start. This
command is repository-wide. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air repository online-backup cancel
Usage
You must be a Technical Repository Administrator to cancel a backup.
Alias
The alias for this command is air backup-cancel.

Syntax
air repository online-backup restore backup-name eme-root [ -quiet ] [
-no-start ]
Argument Description
backup- Absolute or relative path to the backup file(s). Backup files are named in the
name format backup-name.sequence-number.emeback, where sequence-
number starts at 1. You can specify either the full name of the backup (for
example, backup-name.sequence-number.emeback) or the backup-name.
eme-root Specifies the name of the new technical repository to be created from the
backup. eme-root must not already exist.
-quiet Does not display status messages during the process.
-no-start Does not start the Technical Repository server after the process has finished.
Usage
The new technical repository must be on a machine with the same architecture as the source
of the backup.
The command does not restore the contents of .audit, .audbak, .eme.errlog, and .errlog files.
The files exist in the new repository, but they are empty. To look at these files, use air
repository online-backup extract.

Alias
The alias for this command is air backup-restore.
air repository online-backup schedule
Schedules and manages automated online backups. Use this command to schedule an
online backup at a specified time and to enable or disable backups without having to stop
the Technical Repository server. This command is repository-wide. For information about
the arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air repository online-backup schedule
[-enable | -disable] [-name backup-name]
[[day@] HH:MM...]
Argument Description
[-enable | -disable] Enables or disables the specified automatic backup.
[-name backup- Provides the base name of the backup file. When the backup is created,
name] the command appends the date and time to the file name.
[ [day@]HH:MM .. Specifies the day and time for the backup to start. You can
.] specify day as a numeric or string as follows:

 0 or Sun for Sunday

 1 or Mon for Monday
 2 or Tue for Tuesday
 3 or Wed for Wednesday
 4 or Thu for Thursday
 5 or Fri for Friday
 6 or Sat for Saturday

The time specifier uses the 24-hour format. You can specify multiple
times. If you do not specify any day or time information, the command
schedules the backup for Wednesday at 02:00 AM.

For more information, see “Usage”.

Usage
The system keeps a maximum of two automated backups — when you start a third
automated backup, the oldest automatic backup is deleted.
 A new schedule replaces a prior schedule. The minimum interval between schedules is six
hours. The schedule is checked every five minutes, so your schedule may not start at the
exact time specified.

To display the current schedule, enter the command without any arguments, as follows:

air repository online-backup schedule

To create a daily schedule at a specific time, enter the command without specifying a day,
as follows:

air repository online-backup schedule 12:00

Examples
To schedule a daily backup at 3:00 AM, enter the following:

 Enter the following:

air repository online-backup schedule 03:00

To schedule a backup on Saturday at 11:45 PM, enter the following:

 Enter the following:

air repository online-backup schedule Sat@23:45

To specify multiple schedules, enter the following:

 Enter the following:

air repository online-backup schedule Mon@04:00 Wed@04:00 Sat@23:45

Alias
The alias for this command is air backup-schedule.

air repository restart

Shuts down and restarts the Technical Repository server process. This command
is repository-wide. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air repository restart
Usage
You must run air repository restart on the same machine as the technical repository.
However, the Technical Repository client and the Technical Repository server process do
not have to be at the same version. You must be a Technical Repository Administrator to
run this command.

The Technical Repository Administrator will need to restart the Technical Repository
server after any of these events:

 The repository is explicitly shut down with air repository shutdown.

 The host system is rebooted.
 Certain diagnostic commands are performed.
 A repository failure causes the Technical Repository server process to terminate.

For more information about the Technical Repository server process, see “Starting and
shutting down technical repository access” in the Technical Repository Administrator’s
Guide.
air repository revert
Reverts a technical repository and all the objects it contains to an older version. Shuts down
the repository before reverting it, and later restarts it. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.

PRECAUCIÓN:

This operation is irrevocable.

Syntax
air repository revert [-force] version
Argument Description
-force Shuts down the Technical Repository server process before the reversion
without prompting you for confirmation.
version Number (integer) or tag (string) of the version to which you want to revert the
technical repository. See “Usage”.
Usage
If you specify a tag as version, it must be a repository-wide tag representing the state of the
entire technical repository as of a particular version. This tag, known as an rtag, must have
been created by air repository tag. Note that rtags have been largely replaced by tags
(vtags), which allow you to assign a tag to specific versions of specific objects. The
versions can be different for each object.

The command fails if you do not confirm the action when prompted or if you are not the
owner of the repository (that is, the Unix owner of the operating system files making up the
repository).

This command does not revert nonversioned objects; nor does it revert usernames,
permissions, and other nonversioned control information.
air repository rename
Renames all files that make up a technical repository, such as the .errlog and the .ixd files.
This command is repository-wide. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air repository rename -force new-name
Argument Description
-force Shuts down the Technical Repository server process without prompting you for
confirmation.
new-name The new root name of the technical repository.
Usage
You must be the Technical Repository Administrator to run this command.

You must run this command on the machine that the technical repository resides on. In
addition, the Technical Repository client and the Technical Repository server process must
be at the same version. You cannot rename a repository across devices.

A side effect of renaming a project is that sandboxes that are checked out from the project
need to be detached from the project (air sandbox detach) and checked out from the
renamed project.

To rename the myeme technical repository to oureme, type:

air -root /disk1/data/eme/myeme repository rename /mount/abinitio/oureme

NOTA:

You should use a fully-qualified path for the value of the new-name argument. If you do
not, the renamed repository in the example above would be renamed to $PWD/oureme.
air repository restart
Shuts down and restarts the Technical Repository server process. This command
is repository-wide. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air repository restart
Usage
You must run air repository restart on the same machine as the technical repository.
However, the Technical Repository client and the Technical Repository server process do
not have to be at the same version. You must be a Technical Repository Administrator to
run this command.

The Technical Repository Administrator will need to restart the Technical Repository
server after any of these events:

 The repository is explicitly shut down with air repository shutdown.

 The host system is rebooted.
 Certain diagnostic commands are performed.
 A repository failure causes the Technical Repository server process to terminate.

For more information about the Technical Repository server process, see “Starting and
shutting down technical repository access” in the Technical Repository Administrator’s
Guide.

air repository revert

Reverts a technical repository and all the objects it contains to an older version. Shuts down
the repository before reverting it, and later restarts it. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.

PRECAUCIÓN:

This operation is irrevocable.

Syntax
air repository revert [-force] version
Argument Description
-force Shuts down the Technical Repository server process before the reversion
Argument Description
without prompting you for confirmation.
version Number (integer) or tag (string) of the version to which you want to revert the
technical repository. See “Usage”.
Usage
If you specify a tag as version, it must be a repository-wide tag representing the state of the
entire technical repository as of a particular version. This tag, known as an rtag, must have
been created by air repository tag. Note that rtags have been largely replaced by tags
(vtags), which allow you to assign a tag to specific versions of specific objects. The
versions can be different for each object.

The command fails if you do not confirm the action when prompted or if you are not the
owner of the repository (that is, the Unix owner of the operating system files making up the
repository).

This command does not revert nonversioned objects; nor does it revert usernames,
permissions, and other nonversioned control information.
air repository show
Displays one or more specific pieces of information about the technical repository. If no
arguments are specified, the command displays all the information. This command
is repository-wide. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air repository show
[-num-domains]
[-repository-version]
[-num-branches]
[-am-admin ]
[-num-connections]
[-storage-format]
[-files]
Argument Description
-num-domains Displays the number of domains in the technical repository.
-repository-version Displays the current repository-wide version number.
-num-branches Displays the number of branches in the repository.
-am-admin Displays whether the current user is a Technical Repository
administrator.
-num-connections Displays the number of open connections.
Argument Description
-storage-format Displays the storage format version of the repository.
-files Shows information about the size of and free space in the repository
files.

If only one option is specified, the output is not labeled. If more than one is specified, each
value is labeled. For example, if you do not specify any arguments, the list of output values
might look like this:

Domains: 1900
Versions: 16
Branches: 1
Admin.dat" [New File]
Connections: 1
Storage Architecture: 17
File Use% File Size Available
---- ----- --------- ---------
0 97 8306688 288768
1 100 75882496 8192

Related topics

 “Identifying the version and format information” in the Technical Repository

Administrator’s Guide

air repository show-server

Displays information about the Technical Repository server. This command is repository-
wide. For information about the arguments common to all air commands, see “Command-
line syntax of air commands”.
Syntax
air repository show-server [-local]
Argument Description
-local If this argument is specified, the command displays information about all
Technical Repository servers on this machine (see “Usage information”). The
information includes the technical repository path, the Technical Repository
server PID, the installation location of the Technical Repository server, and a
timestamp.

If this argument is omitted, the command displays information about the current
repository only.
Usage
When the Technical Repository server starts, it writes an entry to a file in AB_WORK_DIR.
The air repository show-server command queries that file to determine the list of running
Technical Repository servers. Note that if you change the value of AB_WORK_DIR, you
will not get the information you expect, as the command will list only the Technical
Repository servers started with the current setting of AB_WORK_DIR.

The command returns a non-zero exit status when the Technical Repository server is not
running. It does not start the Technical Repository server.

If you specify -local, the output shows the following about each Technical Repository
server on this machine:

 Path to the technical repository.

 Process ID of the Technical Repository server.
 AB_HOME (installation location) of the Technical Repository server.
 Timestamp — updated every five minutes, it provides a clear indication that the
server is still running.

See Running the command with the -local argument.

If you omit -local, the output shows the following information about the current technical
repository:

 Server ID — unique identifier; it changes each time a server is started.

 AB_HOME and version — installation location and version of the software running
the Technical Repository server.
 Connections — number of active repository connections.

See Running the command without the -local argument.

Examples
Running the command with the -local argument
Running the command with the -local argument produces the following output for all
servers running on this machine:

EME pid AB_HOME Timestamp

------------- --- ------------ -----------
/local/eme/ex1 20957 /local/install1/abinitio Tue Jan 30 19:43:03 2016
/local/eme/ex2 14561 /local/install2/abinitio Tue Jan 30 19:45:28 2016

Running the command without the -local argument

Running the command without the -local argument produces the following output for the
current technical repository:
Server ID: ed17320a-45bf688b-37cb
AB_HOME: /local/install/abinitio
Version: 3.3.4
Connections: 12

air repository shutdown

Shuts down the Technical Repository server process. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air repository shutdown [-quiet] [-force]
Argument Description
-quiet If this argument is specified, error messages are suppressed.
-force Performs an immediate shutdown, which will cause any connected clients to get
errors.
Usage
You must run this command on the machine the technical repository resides on. However,
the Technical Repository client and the Technical Repository server process do not have to
be at the same version. For more information about the Technical Repository server
process, see “Starting and shutting down technical repository access” in the Technical
Repository Administrator’s Guide.
air repository start
Starts the Technical Repository server process. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air repository start [ -override-running-server-check ]
Argument Description
-override-running-server-check If specified, causes the Technical Repository server to
start, even if the software has detected another server
accessing this technical repository.

See the Warning in the Usage section below before using

this argument. Use the air repository show-
server command to verify that another server
is not accessing the repository before using this
argument.
Usage
If the Technical Repository server is currently running on this machine, this command does
nothing.

If the server software detects that another repository server is running, this command does
not start the Technical Repository server. We recommend determining whether another
server is already accessing this repository using the air repository show-server command.

ADVERTENCIA:

Running more than one EME server on a repository will result in severe, unrecoverable
corruption of the repository. Do not override the startup by running air repository start with
the -override-running-server-check option unless you are certain that no other machine has
an EME server accessing the repository.

You can consider using the -override-running-server-check option if the technical

repository server process fails abnormally and the repository machine IP address has
changed so that it no longer matches the recorded IP address.

The Technical Repository Administrator must start the Technical Repository server
process, because the process must run as the Technical Repository Administrator. Also, the
startup process can take a significant amount of time for large repositories, as it performs
some recovery operations and consistency checks. Therefore, having the Technical
Repository administrator start this process can avoid unexpected timeouts by client
operations.

You must run this command on the machine the repository resides on. However, the
Technical Repository client and the Technical Repository server process do not have to be
at the same version.

For more information about the Technical Repository server process, see “Starting and
shutting down technical repository access” in the Technical Repository Administrator’s
Guide.
air repository tag
Assigns a tag (symbolic name) and optionally a comment to a given version of the entire
technical repository. You can use this command to assign a tag to a repository version and
then create a branch based on that tagged version. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air repository tag [-version version] tag [comment]
Argument Description
-version version Version number (integer) of the technical repository you want to tag.
Default is the current version.
tag Name, expressed as a string, of the technical repository version.
comment Brief description, expressed as a string, of the version you are tagging.
Usage
This command creates an rtag, a repository-wide tag representing the state of the entire
repository as of a particular version. The versions can be different for each object to which
the tag is applied.

You can see the tag and optional comment in the Technical Repository Web Interface.
When you display the repository, select the Versions checkbox. Click the Info button to
open a window displaying the tag, comment, username, and date. Also run air object
versions to see tagged versions of the repository.
Alias
The alias for this command is air rtag.

air repository trigger commands

The air repository trigger commands help you manage triggers in a technical repository.

A trigger is an object in the Technical Repository that contains firing criteria (an object
path, user, and branch or a tag) and a trigger script. The trigger script fires when a change
— a checkin or a tag — meets the firing criteria.

The following table summarizes the air repository trigger group of commands. For
information about command syntax, see “Command-line syntax of air commands”.

Command Description
air repository trigger create Creates and configures a trigger.
air repository trigger list Lists the triggers in a specified trigger group.
air repository trigger Updates the configuration of a trigger.
modify
air repository trigger Removes a trigger.
remove
air repository trigger show Displays the settings of a trigger.
air repository trigger start Starts the trigger associated with a trigger group.
air repository trigger status Displays a list of running trigger daemons on the current host.
air repository trigger stop Stops the trigger daemon process associated with a trigger
group.
air repository trigger create
Creates and configures a trigger.

A trigger daemon monitors the technical repository, checking the firing criteria of each of
its triggers against technical repository changes to determine if any trigger scripts need to
fire. Each change has the following attributes associated with it: objects, users, groups,
branches, and tags. These attributes are compared against the firing criteria. If the attributes
of a repository change meet all specified criteria, the trigger fires. This command
is repository-wide.

For information about the arguments common to all air commands, see “Using the Jira
issue integration solutions”.
Syntax
air repository trigger create trigger_id
[ -enable | -disable ]
[ -path rpath ... ]
[ -user user-name ... ]
[ -group usergroup-name ... ]
[ -branch branch-name ... ]
[ -tag tag-regex ... ]
[ -script script-contents ]
[ -script-file file-name ]
Argument Description
trigger_id Specifies the trigger name and trigger group for the trigger that you
want to create. The format of the trigger ID is group-name/trigger-
name. If group-name is not specified, the trigger is created in
the default group.

For more information, see “Usage”.

-enable | -disable A new trigger is disabled by default. Enter one of the following:

 -enable — Enables the trigger.

 -disable (default) — Disables the trigger.

-path rpath Specifies one or more objects as trigger-firing criteria. You can specify
an asterisk (*) for multiple objects.

If rpath is a directory, all objects under source control under rpath are
monitored.
Argument Description
NOTA:

An object needs to be under source control (that is, checked in) to be

monitored. It is not sufficient that an object be in a directory that is
being monitored.
-user user-name Specifies one or more users as trigger-firing criteria.

user-name is the user responsible for the repository change. If no users

are specified in the trigger, the trigger daemon will ignore user
information when determining whether the trigger should fire.
-group usergroup- Specifies one or more user groups as trigger-firing criteria.
name
usergroup-name is the repository user group associated with the user
who made the change. This argument is a convenient way to specify
multiple users.
-branch branch- Specifies one or more branches as trigger-firing criteria.
name
If a branch is not specified, the command defaults to main. To specify
all branches, enter an asterisk (*).
-tag tag-regex Specifies one or more tag expressions as trigger-firing criteria. You
can use a regular expression in tag-regex.
-script script- Specifies a script to store as part of a trigger. Typically, you use this
contents argument when the script is simple and can be typed directly in to the
command. If the script is more complicated, save it in a file and
specify it with the -script-file argument.

You can use certain trigger script variables in script-contents. For

more information, see “Usage”.

When the trigger fires, the trigger daemon executes the script.
-script-file file- Specifies the name of a script file to store as part of the trigger.
name
The script file must begin with the interpreter directive #! followed by
the script interpreter, such as #! /bin/ksh.

NOTA:

The script file is stored as part of the trigger when you issue the air
repository trigger create command. If you later change the script file,
you must update the trigger definition by using the air repository
trigger modify command.

You can use certain trigger script variables in the script. For more
Argument Description

information, see “Usage”.

When the trigger fires, the trigger daemon executes the script.
Usage
Each trigger belongs to a trigger group. Each trigger group is associated with one trigger
daemon instance.

NOTA:

In large repositories, you may want to have more than one trigger daemon so that you can
use different permissions or alternate trigger IDs. For more information, see air repository
trigger create in the air Command Reference.

NOTA:

Do not include a statement in your trigger script that would itself cause the trigger to fire,
such as a checkin in a directory that the trigger is monitoring.

The trigger daemon sets the following trigger script variables when it executes the trigger
script:

 AB_TRG_BRANCH — The branch associated with the version.

 AB_TRG_TAG_NAMES — The newline-separated names of tags that are being
monitored and that changed or were added by the update that caused the trigger to
fire.
 AB_TRG_TIME — The time that the trigger fired.
 AB_TRG_TRIGGER_ID — The identifier for the trigger that fired.
 AB_TRG_USER — The user who created the checkin that caused the trigger to fire.
 AB_TRG_VERSION — The version number that caused the trigger to fire.

You can use these variables in the trigger script that you specified with the -script or -
script-file argument. The trigger daemon will use these variables to convey information to
the running script.

If the name of an object that a trigger daemon is monitoring changes, the object continues
to be monitored; it is the same object internally, but with a new name.

If you want a trigger to fire for changes by users to objects in a specific path or for changes
by users to objects with a specific tag, create two triggers: one trigger that specifies the path
and another trigger that specifies the tag. In the following example, the
trigger AllProjectAChanges will fire for all changes in the dev branch by cforde in the
repository path /Projects/ProjectA. The trigger PatchTags monitors the same user and
branch firing criteria, but for a family of similarly named tags instead of a path.
air repository trigger create AllProjectAChanges -enable -path /Projects/ProjectA -user -cforde -
branch dev
air repository trigger create PatchTags -enable -user -cforde -branch dev -tag patchProjectA*

SUGERENCIA:

You can update the definition of a trigger by using air repository trigger modify.

Listing triggers in a repository

Triggers in the repository are stored in /abinitio/triggers. In addition to being able to list
triggers with the air repository trigger list and air repository trigger show commands, note
that you can access /abinitio/triggers to list trigger objects and possibly change the
permissions on them.

NOTA:

All trigger information is in the main branch.

There are several ways for you to access the trigger objects in a repository:

 Use the air repository trigger list command.

 Use the air ls command.
 Use the Technical Repository Management Console.
 Use the Technical Repository Web Interface.

To see a list of all trigger groups defined in a repository, use the following command:

air ls /abinitio/triggers

Each trigger is in a trigger group. The following example shows two trigger
groups, default and test_group:

air ls /abinitio/triggers
directory /abinitio/triggers/: 2 elements
directory: default
directory: test_group

To list all the triggers in a group, issue the following command:

air ls /abinitio/triggers/group-name

The following example shows one trigger in test_group, test_trigger:

air ls /abinitio/triggers/test_group
directory /abinitio/triggers/test_group/: 2 elements
mimeobj: .state
mimeobj: test_trigger

Alias
The alias for this command is air trigger create.
Example
The following command creates and enables a trigger named test_trigger in the trigger
group called test_group. A trigger daemon monitors all objects under source control in
the /Projects/test_parameters directory:

air repository trigger create test_group/test_trigger -enable -path /Projects/test_parameters -script-

file test_script

Related topics

 air repository trigger commands

Alias
The alias for this command is air trigger list.
Example
The following command lists the triggers in the group called test_group. It is not enabled
and therefore won’t fire:

air repository trigger list test_group

test_group/test_trigger Not Enabled

Related topics

 air repository trigger commands

air repository trigger modify
Updates the configuration of a trigger. You can add or remove objects, users, groups,
branches, and tags for a trigger to monitor. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air repository trigger modify trigger_id
[ -enable | -disable ]
[ -add-path rpath ] ...
[ -remove-path rpath ] ...
[ -add-user user-name ] ...
[ -remove-user user-name ] ...
[ -add-group usergroup-name ] ...
[ -remove-group usergroup-name ] ...
[ -add-branch branch-name ] ...
[ -remove-branch branch-name ] ...
[ -add-tag tag-regex ] ...
[ -remove-tag tag-regex ] ...
[ -script script-contents ]
[ -script-file file-name ]
[ -comment comment-string ]
Argument Description
trigger_id Specifies the group and name for the existing trigger that you want
to modify, as group-name/trigger-name.

If you do not specify a group, the command uses the default group.
-enable | -disable Enter one of the following:

 -enable — Enables the trigger.

 -disable —Disables the trigger.

If this argument is not specified, the existing state of the trigger is

maintained.
-add-path rpath Specifies an object to add to the list of objects as trigger-firing
criteria.

If rpath is a directory, all objects under source control

Argument Description

under rpath are monitored by the trigger daemon.

NOTA:

An object needs to be under source control (that is, checked in) for
a trigger daemon to monitor it. It is not sufficient that an object be
in a directory that a trigger daemon is monitoring.
-remove-path rpath Specifies an object to remove from the list of objects as trigger-
firing criteria.
-add-user user-name Specifies a user to add to the list of users as trigger-firing criteria.
-remove-user user- Specifies a user to remove from the list of users as trigger-firing
name criteria.
-add-group usergroup- Specifies a group of users to add to the list of user groups as
name trigger-firing criteria.
-remove-group usergro Specifies a group of users to remove from the list of user groups as
up-name trigger-firing criteria.
-add-branch branch- Specifies a branch to add to the list of branches as trigger-firing
name criteria.
-remove-branch branc Specifies a branch to remove from the list of branches as trigger-
h-name firing criteria.
-add-tag tag-regex Specifies a tag expression to add to the list of tags as trigger-firing
criteria. You can use a regular expression in tag-regex.
-remove-tag tag-regex Specifies a tag expression to remove from the list of tags as
trigger-firing criteria. You can use a regular expression in tag-
regex.
-script script-contents Specifies the contents of a script to store as part of a trigger.
Typically, you use this argument when the script is simple and can
be typed directly in to the command. If the script is more
complicated, save it in a file and specify it with the -script-
file argument.

You can use certain trigger script variables in script-contents. For

more information, see “Usage” in “air repository trigger create”.

When the trigger fires, the trigger daemon executes the contents of
the script.
-script-file file-name Specifies the name of a script file to store as part of a trigger.
When the trigger fires, the trigger daemon executes the script.

The script file must begin with the interpreter directive !# followed
by the script interpreter, such as #! /bin/ksh.
Argument Description

You can use certain trigger script variables in the script. For more
information, see “Usage” in “air repository trigger create”.

When the trigger fires, the trigger daemon executes the script.
-comment comment- Specifies a comment to associate with the trigger.
string
Usage
NOTA:

Do not include a statement in your trigger script that would itself cause the trigger to fire,
such as a checkin in a directory that the trigger is monitoring.

PRECAUCIÓN:

After updating a trigger that is running, you must stop its trigger daemon and then restart
the trigger daemon to pick up the changes. The trigger daemon maintains its state, so you
won’t lose any activity.

Alias
The alias for this command is air trigger modify.
Example
The following command adds the objects in Projects/test_project to the list of objects
that test_trigger monitors:

air repository trigger modify test_trigger -add-path /Projects/test_project

Related topics

 air repository trigger commands

air sandbox ab-compatibility

Displays or sets the AB_COMPATIBILITY value for a graph or plan. This configuration
variable specifies the version of the Co>Operating System whose behavior you want to
simulate (as nearly as possible) for backward-compatibility while running a later version.
For more information, see “Backward compatibility at runtime: The role of the
AB_COMPATIBILITY mechanism” in the Administrator’s Guide and Reference.
Syntax
air sandbox ab-compatibility file [-show] [-update] [-set version]
Argument Description
file Name of the graph or plan that you want this command to act on. This value
must refer to a filesystem path.
-show Prints the current value of AB_COMPATIBILITY, or if that configuration
variable is unset, displays <unset>. The default behavior if you don’t specify
any arguments.
-update Changes the value of AB_COMPATIBILITY to that of the current Co>Operating
System software. This argument is useful for ensuring that compatibility-based
changes made to a graph or plan at an older version will run properly at the
current version. For more information, see “Usage”.
-set versio Specifies the Co>Operating System version that you want to set the specified
n graph or plan’s AB_COMPATIBILITY value to.
Usage
The version change that you make to a plan or graph is persistent.

If you do not specify any arguments, the command displays the current version of the
object. To run this command with the -update or -set arguments, you must have write
permissions on the graph or plan. Therefore, you may need to lock the object before
running these commands.

NOTA:

The -update argument will update the value of AB_COMPATIBILITY to that of

the current Co>Operating System version, even if the AB_COMPATIBILITY setting of the
graph or plan is set to a newer version.

For the -set argument, you specify the value of the version by using the version point
syntax that the m_env -v command normally produces — for example, -set 3.2.1.
Examples
This example uses the command’s default behavior to show the Co>Operating System
version (AB_COMPATIBILITY setting) that is associated with the createPDF.mp graph:

air sandbox ab-compatibility $PROJECT_DIR/mp/createPDF.mp

3.2.0

This example sets the compatibility version of the createPDF.mp graph to an earlier
Co>Operating System version, Version 3.1.4. The second command confirms that the
change was made. The -show argument is optional:
air sandbox ab-compatibility $PROJECT_DIR/mp/createPDF.mp -set 3.1.4
air sandbox ab-compatibility $PROJECT_DIR/mp/createPDF.mp -show
3.1.4

This example updates the compatibility version of the createPDF.mp graph to the current
Co>Operating System version, Version 3.2.4; and confirms that the change was made:

air sandbox ab-compatibility $PROJECT_DIR/mp/createPDF.mp -update

air sandbox ab-compatibility $PROJECT_DIR/mp/createPDF.mp -show
3.2.4

air sandbox add

Marks the specified file for addition to the technical repository at the next checkin. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air sandbox add path [-type type]
Argument Description
path Path to the sandbox file you want to have checked in.
-type type Specifies the MIME type of the sandbox file. For example, the appropriate
MIME type for a record format file would be text/x-abinitio-dml. If this
argument is omitted, the command uses the extension list to assign a type.
Usage
You are permitted to add a sandbox file whose state is New, PendingAdd, Removed,
or Ignore. If the file already exists in the technical repository, the add operation fails.

The command assigns the file a state of PendingAdd. The file is then automatically added
to the repository the next time you check in the sandbox.

For a sample list of MIME types, see “Viewing the extension list”.

This command automatically sets the value of AB_AIR_ROOT based on the repository that
the sandbox is attached to. This means that you can run the command without the -
root argument or without having previously set the value of AB_AIR_ROOT.

To cancel a pending addition, run air sandbox revert on the file. The state of the file is
cleared, and the file will not be checked in the next time you run air project import or air
sandbox import.
air sandbox analysis-level
Displays or sets the level of dependency analysis used for a graph or an input pset (.pset)
file in a sandbox. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air sandbox analysis-level path
{-show | -set level}
Argument Description
path Specifies a filesystem path to an input pset (.pset) file or graph.

-show | -set level You must specify one of the following:

 -show displays the current level of dependency analysis.

 -set level changes the level of dependency analysis to one of
these:
o expand (default) performs full dependency analysis,
including the determination of file usage information
and the association of the graph or pset with datasets.
o ignore_sql_errors performs full dependency analysis
but ignores any SQL errors found in component
parameter definitions. This is useful if you have SQL
statements that cannot be parsed by the Ab Initio SQL
parser.
o link determines and stores referenced files, but does
not compute dataset or field lineage. The setting is
helpful because it allows the file to be listed as a
referencing file. For example, choosing this setting for
a linked subgraph allows you to see what graphs use
the linked subgraph. (See the air object referencing-
files command.)

The setting is appropriate for generic graphs, for linked

and dynamic subgraphs, and for utility or test graphs
for which lineage is not required. For more
information, see “Análisis de dependencias para grafos
genéricos” in the Co>Operating System Guía para
desarrolladores de grafos.

o none turns off dependency analysis in all cases. No

analysis is performed, and the graph is never listed as a
referencing file for other files in the project.

This setting is recommended only for objects for which

Argument Description

no lineage is required, such as graphs that are no

longer in use.
Usage
For background information about dependency analysis, see “Análisis de dependencias” in
the Co>Operating System Guía para desarrolladores de grafos.
Example
A generic graph has unbound input parameters, which will cause dependency analysis
errors. However, you want the graph’s associated parameter set analyzed with SQL errors
ignored. To change the analysis level
of mygraph.mp to link and mygraph.pset to ignore_sql_errors, type:

air sandbox analysis-level c:/eme/mysand/mp/mygraph.mp -set link

air sandbox analysis-level c:/eme/mysand/mp/mygraph.pset \
-set ignore_sql_errors

Related topics

 Especificar el nivel del análisis de dependencias

 air object referencing-files

air sandbox attach

Associates a sandbox with a project in a technical repository. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox attach
sandbox-path
project-path
[-published-eme published-name]
Argument Description
sandbox-path Path to an existing sandbox.
project-path Path to an existing project in the technical repository specified
by AB_AIR_ROOT.
-published-eme published- Specifies the name of a “published” technical repository to
name associate with the sandbox specified by the sandbox root
directory. (To be published, a technical repository must be
specified as one of the values of
Argument Description
the AB_EME_REPOSITORIES configuration variable.)
Usage
In addition to associating a sandbox with a project in a technical repository, air sandbox
attach attempts to update the source control attributes of the files in a sandbox, such as their
version number and timestamp information.

This command is useful when you change the location of the repository. In this case, run air
sandbox detach to disassociate the sandbox from the current repository, and then run air
sandbox attach to associate the sandbox with the repository at its new location.

air sandbox convert

Converts a sandbox to Format 3. Format 3 became the default format for new sandboxes
starting in Version 3.0 of the Co>Operating System. Previous sandbox formats are now
deprecated.

We recommend converting all remaining Format 2 sandboxes for projects under

development to Format 3. It is not necessary to convert Format 2 sandboxes that are
currently in production — the Co>Operating System will continue to run jobs from them.

For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air sandbox convert path
Argument Description
path Path to the sandbox to be converted.
Usage
This command converts a sandbox in the filesystem to Format 3. After conversion, we
recommend that you test the sandbox applications before checking in the changes.

When you check in the sandbox for the first time after conversion, the corresponding
technical repository project is converted to Format 3. Therefore, you should convert only
one sandbox for a particular project. Other sandboxes attached to the project will pick up
the changes subsequently, via checkout.

Related topics

 Planning for sandbox upgrades from Format 2

air sandbox create
Creates a sandbox in the specified path. The sandbox directory is created (if it does not
exist) and marked as a sandbox, with the built-in sandbox directories created. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.

PRECAUCIÓN:

This air command creates a sandbox that is not associated with an Entorno de Ab Initio As
a best practice, use the create-project script with the -sand-root argument or create the
sandbox in the GDE. These methods create the sandbox in an Entorno de Ab Initio.

Syntax
air sandbox create path
[-template path | -type {public | private}]
[-prefix prefix]
[-replace s1 s2]
[-location location]
[-nodirectories]
Argument Description
path Specifies a filesystem directory. If it does not
exist it is created.
-template path | -type {public | private} You may specify one of the following:

 -template path creates the sandbox from a

specified template sandbox at path. Do
not use -template with -prefix, -location,
and -nodirectories.
 -type {public | private} creates a project
of the specified type from the Ab Initio
Environment. Templates are located
based on the setting of
the AB_ENV_ROOT configuration
variable.

Do not specify -type with -location, or -

nodirectories. You can
specify -prefix when creating a project of
type public.
-prefix prefix Adds a prefix to the predefined sandbox
Argument Description
parameters (for example, DML and XFR).

NOTA:

The prefix is not applied to the location

parameter (-location location) and
the RUN parameter.
-replace s1 s2 When creating a sandbox from a template,
changes all occurrences of one string with
another string in all parameter names and
expressions.
-location location The name of a parameter that points to the
location of the project. Default
is PROJECT_DIR.
-nodirectories Does not create the built-in directories.
Usage
If you specify -prefix COMMON_, the predefined parameters are
named COMMON_DML, COMMON_XFR, and so on. For information on the predefined
parameters, see “Parámetros por defecto de sandbox” in the Co>Operating System Guía
para desarrolladores de grafos.

Running this command is equivalent to creating an empty project and exporting it. The
command creates built-in sandbox directories (for example, dml and mp) and a parameters
file (.sandbox.pset).

If you specify -type with public or private, you can create a sandbox in accordance with the
Ab Initio Environment.

The command fails if it finds that the path will create nested sandboxes. If path is already a
sandbox, the parameters are merged.

air sandbox dataset file

Creates or modifies a file reusable dataset (.fdset) in the sandbox. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox dataset file path
[-url path]
[-key value]
 [-metadata path | -metadata-string value]
[-comment comment]
[-attribute {name value | -remove name}]
[-custom-analysis-id value]
[-force]
[-no-auto-parameterize]
Argument Description
path Path to the file reusable dataset to create or
modify.
-url path Location of the physical data associated with this
reusable dataset. Uses PDL interpretation.
-key value Default key specifier for lookup mode.
-metadata path | -metadata-string value Choose one of the following:

 -metadata — Path expression for the

reusable dataset’s record format (for
example, the path to a .dml file). Uses
PDL interpretation.
 -metadata-string — Constant-interpreted
string containing the record format.

-comment comment Comment describing the reusable dataset.

-attribute {name value | -remove name} Sets the value for a reusable dataset attribute.
The value expression uses PDL interpretation.
You can use multiple -attribute clauses.

Use -remove to remove an attribute.

-custom-analysis-id value Value that overrides the dataset’s default analysis
identifier, which is computed from the repository
path. The Technical Repository and the Metadata
Hub use this information to identify equivalent
datasets.

To indicate that this dataset is equivalent to

another for dependency analysis, set this value to
the repository path of the other existing dataset.
The value expression can include project
parameters and uses PDL interpretation.

To restore the default, set this value to an empty

string.
-force Turns off validation of the reusable dataset. The
default behavior is to treat validation and
Argument Description
parameterization failures as errors.
-no-auto-parameterize Turns off automatic parameterization. The
default behavior is to attempt to parameterize
metadata paths that are not yet parameterized.
Use this argument only when you require an
absolute path for the metadata.
Usage
For more information about reusable datasets, see “Conjuntos de datos reutilizables” in the
Co>Operating System Guía para desarrolladores de grafos.
Examples
Creating a file reusable dataset
To create a file reusable dataset:

air sandbox dataset file data/serial/customers.dat.fdset \

-metadata '$AI_DML/customers.dml' -url '$AI_SERIAL/customers.dat'

Modifying a file reusable dataset

To change the URL for a file reusable dataset:

air sandbox dataset file data/serial/customers.dat.fdset \

-url '$AI_SERIAL/new_customers.dat'

air sandbox dataset prepare

For sandboxes created with Co>Operating System Version 3.0 and earlier. Prepares the
sandbox to hold reusable datasets. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox dataset prepare [path] [-force]
Argument Description
path Path to the sandbox to convert. If none is supplied, the current directory is used.
-force Ignores any validation errors, allowing the conversion to proceed.
Usage
If the target project is a public project, this command creates a synonym of
the PROJECT_DIR parameter for dataset-linked components to use, where the PREFIX is
the value of the abenv or stdenv PREFIX parameter.

With this command you should also run air project update-extensions. You need to run
these commands on projects that will contain reusable datasets. However, you do not need
to update projects that include such projects.

For more information about reusable datasets, see “Conjuntos de datos reutilizables” in the
Co>Operating System Guía para desarrolladores de grafos.
Example
air sandbox dataset prepare /disk1/sand/my_sandbox/my_common_project

air sandbox dataset table

Creates or modifies a table reusable dataset (.tdset). For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox dataset table path
[-table-spec value]
[-dbc path]
[-dbms value]
[-metadata path | -metadata-string value]
[-comment comment]
[-attribute {name value | -remove name}]
[custom-analysis-id value]
[-force]
[-no-auto-parameterize]
Argument Description
path Path to the table reusable dataset to create or
modify.
-table-spec value Required for creating a table reusable dataset;
optional otherwise. Name of the table.
Uses curly interpretation.
-dbc path Path expression for the database configuration
Argument Description
(.dbc) file. Uses PDL interpretation.
-dbms value Database type (string).
-metadata path | -metadata-string value Choose one of the following:

 -metadata — Path expression for the

reusable dataset’s record format (for
example, the path to a .dml file). Uses
PDL interpretation.
 -metadata-string — Constant-interpreted
string containing the record format.

-comment comment Comment describing the reusable dataset.

-attribute {name value | -remove name} Sets the value for a reusable dataset attribute.
The value expression uses PDL interpretation.
You can use multiple -attribute clauses.

Use -remove to remove an attribute.

-custom-analysis-id value Value that overrides the dataset’s default analysis
identifier, which is computed from the table-
spec. The Technical Repository and the Metadata
Hub use this information to identify equivalent
datasets.

The value should be a string in the following

format:

db:/db-name/schema-name/table-name

To restore the default, set this value to an empty

string.
-force Turns off validation of the reusable dataset. The
default behavior is to treat validation and
parameterization failures as errors.
-no-auto-parameterize Turns off automatic parameterization. The
default behavior is to attempt to parameterize
metadata paths that are not yet parameterized.
Use this argument only when you require an
absolute path for the metadata.
Usage
For more information about reusable datasets, see “Conjuntos de datos reutilizables” in the
Co>Operating System Guía para desarrolladores de grafos.
Examples
Creating a table reusable dataset
To create a table reusable dataset:

air sandbox dataset table tables/my_db/my-schema/my-table.tdset \

-dbc '$MY_COMMON_DB/my-db.dbc' \
-metadata '$MY_COMMON_DB/dml/my-table.dml' \
-table-spec my-schema.mytable -dbms oracle

Modifying a table reusable dataset

To change the table name for a reusable dataset:

air sandbox dataset table tables/my_db/my-schema/my-table.tdset \

-table-spec '${MY_SCHEMA}.mytable'

air sandbox detach

Detaches a sandbox from its associated project in a technical repository. For information
about the arguments common to all air commands, see “Command-line syntax of air
commands”.
Syntax
air sandbox detach [-q] [path]
Argumen
Description
t
-q Suppresses error if the sandbox directory does not exist.
path Path to the sandbox directory. Default is the current directory.
Usage
When you have detached a sandbox, you may migrate it by checking it in to a different
technical repository.

To reassociate a detached sandbox with its project, run air project import on the sandbox, or
check it in through the GDE.

The sandbox’s .air-sandbox-state file is retained to enable reattaching to the same technical
repository in a possible new location.
air sandbox diff
Displays the differences between two graphs, two plans, two text files, or two sandboxes.
For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air sandbox diff
{ path | path1 path2 | -version version path | -version
version1 -version version2 path }
[ -terse| -verbose ]
[ -ignore-param-order ]
[ -external-files ]
[ -ignore-dep-analysis ]
[ -text ]
[ -all [-no-diff] [-same ] ]
[ -original-format ]
[ -dml ]
[ -m ]
Argument Description
path Path to a file in the filesystem. Usually the file is in a sandbox, but it
isn’t required unless one of the files being compared is from the
technical repository.
-version version path Specifies the version of the object path to be used in the
comparison. version can be expressed as a version number, as a tag,
or as current (the current version of the technical repository). If you
omit this argument, the command compares object path against the
repository version from which the object was checked out.
-terse | -verbose Valid for graphs and plans. By default, the command shows all
changes that might affect execution, as well as such differences as
changes to comments and legends. To override the default, you can
choose one of the following:

 -terse shows only the differences that might affect the

running of the graph or plan, such as changes to parameter
values. -terse includes the functionality
of -ignore-dep-analysis.
 -verbose shows all changes to the graph or plan, including
minor differences, such as a changes to
the x and y coordinates of components and font information.

-ignore-param-order Valid for graphs and plans. Does not show differences in the order of
graph, plan, task, or component parameters.
-external-files Valid for graphs or plans only. If specified, also shows differences in
Argument Description
files referred to by graphs or plans, such as record format (.dml) and
transform (.xfr) files.
-ignore-dep-analysis Valid for graphs only. Does not show differences in parameters that
are used only for dependency analysis. See “Usage” (below).
-text Forces the two files to be treated as text, regardless of their actual
types.
-all [-no-diff] [-same] Compares all objects in the sandbox. By default, -all lists the files
as Modified, Added, or Removed (see “Output”), and includes the
comparison output of the pairs of files. By default, Same (up-to-
date) files are not displayed, nor are files marked ignore. However,
if -verbose is specified with -all, Same files and files
marked ignore are listed as well.

If -no-diff is specified with -all, no comparison output is displayed.

If -same is specified with -all, Same (unchanged) files are listed as
well.
-original-format Compares graphs or plans in their original file format. This argument
disables the default feature that upgrades graphs and plans to the
current graph or plan file format before comparing them. Use in rare
cases where you want to see differences caused by changes between
the original file formats. For example, this can be useful when
comparing graphs that were saved in the GDE using the Save
As menu item to save them to a different format. Valid only for
graphs and plans.
-dml Displays the record format for the machine-readable output when
you run the command with the -dml and -m arguments. Exits
without displaying differences. This argument is useful for
subsequently processing machine-readable output in another graph.
-m Writes the command output in machine-readable format to standard
output and suppresses carriage returns when run on Windows. You
can process the output in another graph.
Usage
The filename extension of the specified files determines the differencing method used:

 .mp invokes graph differencing

 .plan invokes plan differencing
 .dml, .xfr, and other files of MIME type text invoke text differencing

If the files are not found to be either graphs or text, or the types of the files do not match,
differencing does not occur. To force differencing (and have the files treated as text), use
the -text option.

The command allows you to compare:

  Two files in the filesystem
 A file in a sandbox and the same file in the repository, at the version at which the
file was checked out or at the current version
 A file in a sandbox and a specific version of the same file in the repository
 Two versions of a file in the repository

The -ignore-dep-analysis argument does not show differences in parameters that are used
solely for dependency analysis:

 When components are compared, the following parameters are

ignored: eme_dataset, eme_dataset_location, dataset_location, eme_index_location,
and doc_transform.
 Parameters of type eme_dataset_mapping are ignored.
 The :eme declared case of parameters dependent on the
internal AB_PARAMETER_ENV parameter are ignored.
 A parameter is ignored if it is changed to a dependent parameter, its value is
changed to AB_PARAMETER_ENV, and a :sandbox case is added and given the
original value of the parameter. The reason is that the only possible change is the
addition of a :eme case, which is inherently uninteresting.

The output format, described in “Output”, is subject to change. So do not write tools that
parse it into reports; they might not work in a subsequent version.
Examples
Comparing two graphs in the filesystem
To compare two graphs in the filesystem, specify the path to each graph. For example:

air sandbox diff /u/jdoe/sand/mp/Graph1.mp \

/u/jdoe/sand2/mp/Graph2.mp

Comparing sandbox and technical repository files

To compare a record format file in a sandbox with the same file in the technical repository,
at the version at which the file was checked out, specify a single path to the .dml file in the
sandbox. For example:

air sandbox diff temp-sand/dml/customers.dml

Comparing sandbox and technical repository graphs

To compare a graph in a sandbox with the same graph in the technical repository at the
current version, run the command as follows:
air sandbox diff -version current temp-sand/mp/my-graph.mp

Comparing a technical repository version and the sandbox

graph
To display differences between a specific technical repository version (tagged
at prod_version_Aug_2015) and the sandbox graph, use the -version argument. For
example:

air sandbox diff -version prod_version_Aug_2015 \

temp-sand/mp/MyGraph.mp

Comparing two technical repository versions of a file

To display differences between two specific technical repository versions of a transform
file, specify -version version twice followed by the path to the file in the sandbox. For
example:

air sandbox diff \

-version prod_version_Aug_2015 \
-version freds_untested_version \
temp-sand/xfr/transformA.xfr

Comparing two sandboxes

To compare all objects across two different sandboxes, specify the -all argument. For
example:

air sandbox diff Client1 Common1 -all

M /disk1/sand/ktomlinsoni/Client1/.project.pset
parameters:
'CL1_PARAM_1' deleted:
< type:
< string
< interpretation:
< pdl
< expression:
< cl1-param1-value
'CL1_PARAM_2' deleted:
< type:
< string
< interpretation:
< pdl
 < expression:
< cl1-param2-value
'CM1_PARAM_1' added:
> type:
> string
> interpretation:
> pdl
> expression:
> cm1-param1-value
'CM1_PARAM_2' added:
> type:
> string
> interpretation:
> pdl
> expression:
> cm1-param2-value
----------------

In this example, the -all argument shows the differences between a development
sandbox, Client1, and a common sandbox, Common1. The command found that parameters
within the .project.pset file changed.

Output
The command returns nothing if there are no differences to report. Otherwise, it returns
output that describes the type of difference — that is, an addition, modification, or deletion
— and the modified lines. The exact output depends upon whether the objects are graphs
and plans or text files. For more information, see “Graphs and plans” and “Text files”.

For comparisons of single objects, only differences are shown. Modified, added, or deleted
objects are displayed, with the amount of indentation indicating the level of nesting within
the larger object. When the command is executed on graphs or plans, the default is to show
all differences that might affect execution, as well as changes to comments and legends.

The first lines of the output show the pathnames to the two files being compared. The
output also shows the version number of each file when the comparison is between
different versions of the same file.

air sandbox diff can compare a sandbox and a technical repository, where the sandbox is
the source and the repository is the target. Or it can compare two versions of a repository or
two sandboxes, where the first specified is the source and the second is the target.

If -all is specified, the output is similar to that of air object changed; the command outputs
codes and a list of those files that exist only in the repository, exist only in the sandbox, or
have been modified. The following table describes each code:
Code
Description
(meaning)
N (New) The file exists in the target but not in the source.
D (Deleted) The file exists in the source but not in the target.
M (Modified) The file is different in the source and the target.
U (Unknown) The difference cannot be determined. Occurs due to permission errors or
when an object cannot be checked out.
A (Added) The file exists in the sandbox and has been marked for addition to the
repository at the next checkin, for example, by air sandbox add. (The file’s
state is PendingAdd.)

A appears only when the source is a sandbox and the target is a repository.
R (Removed) The file exists in the sandbox and has been marked for removal from the
sandbox and the repository at the next checkin, for example, by air sandbox
remove. (The file’s state is PendingRemove.)

R appears only when the source is a sandbox and the target is a repository.
S (Same) The file is the same in the source and the target. S appears only
when -version is specified with -all.
I (Ignore) The file exists under source control but is marked ignore. I appears only
when -version is specified with -all.
Graphs and plans
For graphs for plans, each difference is labeled with the object type (for example, graph)
and whether it is an addition, deletion, or change. Differences are denoted as follows:

 For an addition, the lines showing the value of the added object are prefixed with >.
 For a deletion, the lines showing the value of a deleted object are prefixed with <.
 For a change:

o The lines showing the value of the changed object in the first file are
prefixed with <.
o The lines showing the value of the changed object in the second file are
prefixed with >.
o The two groups of lines are separated by a dashed line.

 The amount of indentation indicates the level of nesting within the larger object.

Text files
For text files, each difference is a block of one or more lines. The position of the difference
within the text file is denoted by a compact label consisting of a number range, a single
letter, and another number range, as follows:
  The first number range shows the affected line numbers in the first file specified.
 The letter is c, d, or a, depending on whether the differences are changed lines,
deleted lines, or added lines, respectively.
 The second number range shows the affected line numbers in the second file
specified.

Example output for graphs

The air sandbox diff command compares the two specified graphs and returns a textual list
of the differences. The output begins with one or more title lines naming the object that has
been added, deleted, or changed. Indentation shows the object’s location within the graph’s
hierarchy. For example, the following shows that the max-core parameter within
the SORT component within graph1.mp has changed:

graph graph1.mp changed:

program component 'Sort' changed:
parameter 'max-core' changed:

For example, if you compare graph a.mp to graph b.mp, the output might show that the
value of the key parameter is {foo} in graph a.mp and {bar} in graph b.mp:

graph 'a.mp' changed:

program component 'Partition_by_Key' changed:
parameters:
'key' changed:
< {foo}
---
> {bar}

The following excerpted output shows that the SORT component has been deleted
from a.mp. Note that, for the sake of brevity, only some attributes and parameters are
displayed for added or deleted components. In this example only max-core is displayed for
the deleted SORT component, since it has a value different from the default value for this
parameter.

graph 'a.mp' changed:

.
.
program component 'Sort' deleted:
< displayname:
< Sort
< author:
 < Ab Initio Software
< version:
< Built-in
< parameters:
< 'max-core':
< Value:
< 201326592
< port 'in'.
< port 'out'.

The following output shows the addition of an all-to-all flow

from PARTITION_BY_KEY to SORT:

graph 'a.mp' changed:

.
.
flow from 'Partition_by_Key.out' to 'Sort.in' added:
> type:
> all-to-all

Example output for text

Suppose you have two versions of a record format file whose contents you want to
compare. The version in the technical repository is /Projects/main/dml/demographic.dml:

record
decimal(10) account_no = 0;
string("\307") firstname;
string("\307") lastname;
string("\307") address = "";
string("\307") city = "";
string(2) state;
decimal(5) zipcode;
decimal(8) ann_sal;
end

The other version of demographic.dml was modified in the sandbox temp-main:

record
decimal(10) account_no = 0;
string("\307") full_name = "";
string("\307") address = "";
 string("\307") city = "";
string(2) state;
decimal(5) zipcode;
string(10) home_phone;
string(10) work_phone;
decimal(8) ann_sal;
end

Running air sandbox diff against these two versions of demographic.dml:

air sandbox diff temp-main/dml/demographic.dml

produces the following output:

Diffing...
/Projects/main/dml/demographic.dml
temp-main/dml/demographic.dml
3,4c3
< string("\307") firstname;
< string("\307") lastname;
---
> string("\307") full_name = "";
8a9,10
string(10) home_phone;
string(10) work_phone;

In the example two differences were found:

 3,4c3 means lines 3 through 4 of the first file have been changed to line 3 of the
second file.
 8a9,10 means that an addition appears after line 8 of the first file, and that lines 9
through 10 of the second file are the two new phone number lines.

air sandbox eval

Evaluates and returns the value of the specified graph, plan, or project parameter.
Optionally, you can use this command to provide override choice values for dependent
parameters. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air sandbox eval sandbox-path [sub-object]
 [-details [-v]]
{ parameter [-expression | -type] |
[-eval-expression expression [-position parameter]}
[parameter=value ...]
Argument Description
sandbox-path Specifies the sandbox path of the graph, plan, pset, or project file
that contains the parameter that you want to evaluate or override.
sub-object Specifies the path to a sub-object that contains the parameter. A
sub-object can be a subgraph, graph component, or plan task.
-details -v Recursively resolves any parameters referenced by the parameter
argument. This is equivalent to the tree view in the
GDE Resolution Details dialog. If you use the -v argument, the
command prints verbose information.
parameter Specifies the name of the parameter that you want to evaluate.
-expression | -type Depending on the argument that you supply, displays the
parameter’s unresolved value or its type. You cannot use these
arguments with the -eval-expression argument.

NOTA:

You cannot use the -expression argument with the -

details argument or parameter=value override argument.
-eval-expression expres Evaluates the specified expression. You can enter any expression
sion that would be valid in a parameter definition.
-position parameter Resolves the expression at the position of the named parameter.
For more information and for an example of this argument,
see Expression evaluation.
parameter=value ... Specifies one or more parameters and their respective override
values. You can use these overrides when evaluating a parameter
to see what the results would be.

Values are interpreted as constant.

Usage
If the supplied parameter doesn’t exist, the command returns an error.

For more information on dependent parameters, see “Parámetros dependientes” in the

Co>Operating System Parameter Reference.
Expression evaluation
The -eval-expression argument lets you evaluate the value the specified graph, plan, or
project parameter. In the following example, the command evaluates
the MY_DATA_DIR and the MY_DATA_FILE parameters and returns their values:
air sandbox eval -eval-expression '${FILE_BASE}.${FILE_EXT}'
/disk1/sand/ktomlinsono/my_request/data/my_file.dat

When you specify the optional -position argument, the command evaluates the expression
as though it was located at the supplied position in the specified pset. The command then
returns its value based on that proposed position. A parameter’s position within a .pset file
indicates its scope. Parameters that are defined lower in the pset can reference parameters
that are defined higher in the same pset, as well as parameters defined in the parent and any
common projects. You must keep parameter scope in mind when using the -
position argument. For example, in a .pset, the MY_DATA_DIR parameter is defined prior
to the MY_DATA_FILE parameter. In the following example, the command evaluates
the MY_DATA_DIR parameter’s value as if it was located at the position of
the MY_DATA_FILE parameter. Due to scope, this command will succeed and return a
value because MY_DATA_DIR is defined first:

$ air sandbox eval -eval-expression '$MY_DATA_DIR' -position MY_DATA_FILE

/disk1/sand/ktomlinsono/my_request/data2

In contrast, the following example evaluates the MY_DATA_FILE parameter’s value as if

it was located at the position of the MY_DATA_DIR parameter. This command will fail
because the MY_DATA_DIR parameter cannot reference
the MY_DATA_FILE parameter. This is because MY_DATA_FILE is defined later in
the .pset and so its definition and value are unknown to the MY_DATA_DIR parameter, as
follows:

$ air sandbox eval -eval-expression '$MY_DATA_FILE' -position $MY_DATA_DIR

Command Failed: air sandbox eval -eval-expression $MY_DATA_FILE -position
$MY_DATA_DIR
----------------------------------------------------------------
The expression `$MY_DATA_FILE' cannot be evaluated at the position of parameter
`$MY_DATA_DIR' due to an error in `MY_DATA_FILE'.
The actual error is as follows:
Parameter:`$MY_DATA_FILE' referenced before being defined in
pset:`/disk1/sand/ktomlinsono/my_request/.project.pset'.

Examples
The following examples show how to use the air sandbox eval parameter.
Sandbox parameter evaluation
To evaluate the parameter MFS in the mysand sandbox, enter the following text:
air sandbox eval /u/disk1/mysand MFS

Dependent parameter evaluation

In this example, the MFS parameter is dependent on the choice parameter STAGE. To
override the default choice value for STAGE and resolve the MFS parameter using a value
of Development, enter the following text:

air sandbox eval /u/disk1/mysand MFS STAGE=Development

Component parameter evaluation

To evaluate the Layout parameter for a ROLLUP component found in a graph, enter the
following:

air sandbox eval /u/disk1/mysand/pset/input.mp Rollup Layout

To evaluate the Layout parameter for a ROLLUP component found in a graph with an input
pset, enter the following:

air sandbox eval /u/disk1/mysand/pset/input.pset Rollup Layout

Related topics

 air project eval

air sandbox export

Checks out a sandbox that is attached to a technical repository. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.

This command takes all the same arguments as air project export, with the exception
of -basedir and project-path. See the air project export command for more information.
Syntax
air sandbox export sandbox-path [arguments]
Argument Description
sandbox-path Specifies the path to the sandbox.
arguments All the arguments to air project export apply, except -basedir and project-
path.
Usage
The sandbox must be attached to a technical repository.

This command is more convenient to use than air project export, because it is not necessary
to specify the project, the repository, or the branch.

Related topics

 air project export -merge

 air sandbox integrate
 air sandbox merge
 air sandbox resolve

air sandbox field-lineage

Outputs a text description of field lineage for a graph or for the graph instance associated
with an input pset. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air sandbox field-lineage path -dep var
[-upstream | -downstream]
[-statements | -ports]
[-wizard]
[-m]

air sandbox field-lineage path

-all-outputs |
-all-inputs |
-outputs-to-inputs |
-inputs-to-outputs |
-datasets |
-vars
Argument Description
path Specifies the path to the graph or input pset to be analyzed.
-dep var Displays the dependencies for a particular component port, as identified
by the var argument. Optionally, you can limit the output to the
dependencies for a particular field. The var argument uses the following
Argument Description
form:

vertex/varinfo:port[:field]

vertex identifies a component (by its label in the GDE, if it has one, or by
its name), and port identifies a component port by name. To limit the
output to a particular field, specify the field. If you do not specify a field
name, then dependencies for all fields through the port are shown.

SUGERENCIA:

Use air sandbox field-lineage path -vars to display a list of all possible
values for var in the graph.
-upstream | - Use with the -dep argument. Specifies the direction of the analysis. If you
downstream do not specify the direction, lineage for both directions is shown.
-statements | - Use with the -dep argument. Filters the output to show only the statements
ports or ports. (The default output shows both.)
-wizard The command output by default does not display the DML associated
with any transforms that are determined to affect field lineage. Use this
flag to add the text of the DML statement to the command output.
-m Produces DML-described (machine-readable) output. The record format is
in $AB_HOME/include/field-lineage.dml.
-all-outputs Displays the upstream dependencies for all fields in the graph’s output
datasets.
-all-inputs Displays the downstream dependencies for all fields in the graph’s input
datasets.
-outputs-to- For every output field in the graph, lists all the input fields that have data
inputs dependencies on that output field.
-inputs-to- For every input field in the graph, lists all the output fields that have data
outputs dependencies on that input field.
-datasets Lists the datasets read or written by the graph.
-vars Lists all the analysis variables (essentially, component ports) in the graph.
This output is helpful in determining the appropriate value for var before
you run air sandbox field-lineage with the -dep var argument.
Usage
This command analyzes a graph or graph instance (identified by an input pset) in a
sandbox. Neither the sandbox nor the graph are required to be checked in. For example, you
can use this command to understand a graph’s field-level dependencies before checking it
in.

NOTA:
This command does not display dependency analysis warnings. Check for warnings by
running dependency analysis in the sandbox before using this command.

Examples
The following command displays the field lineage for the pending_interest field through
the read port of a dataset component called Pending_Interest:

air sandbox field-lineage /my_sandbox/rbank/adjustments/mp/adjustments.mp -dep

Pending_Interest/varinfo:read:pending_interest

The following command displays the upstream dependencies for all the fields in the graph’s
output dataset:

air sandbox field-lineage /my_sandbox/rbank/adjustments/mp/adjustments.mp -all-outputs

The following command lists the datasets read or written by the graph:

air sandbox field-lineage /my_sandbox/rbank/adjustments/mp/adjustments.mp -datasets

Related topics

 Linaje de campos
 air object field-lineage
 air project analyze-dependencies

air sandbox files

Displays the status of all files in a sandbox without the need to specify the project, branch,
or repository. This command takes the same arguments as air project files with
the -basedir argument and the project-path value. See the “air project files” command for
more information. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air sandbox files sandbox-path [ arguments ]
Argument Description
sandbox- Specifies the path to the sandbox.
path
arguments All the arguments to air project files apply, except for -basedir and project-
Argument Description
path — which you do not need to provide.
Usage
The sandbox must be attached to a technical repository.

This command is more convenient than the air project files project-path -
basedir sandbox command, because it is not necessary for you to specify the project, the
repository, or the branch.

air sandbox find

Identifies the root (top-level) of a sandbox. For information about the arguments common
to all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox find [path]
[-up|-down]
[-relative]
[-project]
Argument Description
path Specifies the directory in which to start looking. Default is the current
working directory.
-up | -down You can choose one:

 -up — (the default) Searches path and its containing directories for
the root directory of a sandbox. If found, displays the path of the
sandbox root directory.
 -down — Specifies a recursive downward search of the directory
specified by path and its subdirectories. Prints the paths for all
sandboxes found.

-relative Displays the relative path from the sandbox directory to path. This
argument works only if the command is searching up.
-project Displays the repository project the sandbox is associated with. This
argument works only if the command is searching up.
Usage
When invoked with -down, this command is similar to the Unix find command:
find path -name '.project.pset'

When invoked with -project, this command returns a blank for the project if it finds a
sandbox that is not attached to a project.

For an example of a script you can run to examine a large number of sandboxes located in
the current directory, see “Unattached sandbox” in the Technical Repository FAQs.
Examples
These examples assume that the current directory is /tmp/sand/mp. The search starts in
the mp directory.
Current directory
If you run the command without any arguments, it returns the current directory if it is a
sandbox. For example, the following command run in /tmp/sand/mp:

air sandbox find

returns:

/tmp/sand

Relative path
Running the command with only -relative:

air sandbox find -relative

returns the relative path to sand:

mp

Relative path and project, if any

Running the command with these arguments:
air sandbox find -relative -project

returns:

mp
/proj

air sandbox find-text

Searches for and optionally replaces the specified text in graphs, plans, psets, text and other
files in a sandbox. This command is branch-specific. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”. If you want to
search for text in a project, use the air project find-text command. (You cannot use the
project command to replace text.)
Syntax
air sandbox find-text
[ -replace replacement [ -dry-run ] [ -lock [ -break-locks ] ] [
-force ] |
[ -linked [ -all-linked ] ] [ -external ] ]
[ -regex | [ -exact ] [ -ignore-case ] ]
[ -file-limit limit ] [ -result-limit limit ]
[[ -object-type type ] ...]
[[ -attribute attribute ] ...]
[[ -task-type type] ... ]
[[ -path-filter filter] ... ]
[[ -component-type type] ... ]
[[ -component-label label] ... ]
[[ -task-label label] ... ] [ -param name ]
[ -all-file-types ] [ -m ]
query path [ path ... ]
Argument Description
query The text that you want to search for.

For more information, as well as how to search for values that

contain hyphens, see “Usage”.
path The filesystem path to an object or directory that you want to search
for. If the path is a directory, the command recursively searches any
subdirectories. You can search subobjects in graphs or plans, such as
a subgraph within a top-level graph or a task within a plan.

NOTA:

You must use an actual path to specify a pathname.

The air command cannot resolve project variables.

For more information, as well as how to search for values that

contain hyphens, see “Usage”.
-replace replacement Searches for matches and replaces any that it finds with the value
of replacement. You can use the -replace argument in embedded
subgraphs. However, the command doesn’t perform replacements in
linked or dynamic subgraphs; therefore, you cannot use it with the -
linked, -all-linked, or -external arguments.
-dry-run Displays the results of the command without actually performing the
replace. Recommended for first reviewing the proposed changes
before making actual changes to the sandbox objects.
-lock -break-locks Attempts to lock sandbox files before performing the replacement.
By default, skips the replacement if the lock fails.
-force
If you specify the -break-locks argument, breaks another user’s
locks so that the command can proceed with the specified
replacement. If the break lock attempt fails, the command skips that
replacement unless you also specify the -force argument.

If you specify the -force argument, the command attempts to

perform the replacement even if the lock fails. If files are write-
protected, the command tries to change the file permissions. This
command does not check to see whether files are stale (that is, older
than the repository version), before locking them.
-linked By default, searches fields of linked subgraph objects, such as their
parameters, but it doesn’t recurse into them. By default, air sandbox
find-text only recurses into subgraphs that can be viewed in the
GDE. That is, the command recurses into subgraphs when
the Permit View property is enabled on the Description tab of a
subgraph’s Properties dialog.
Argument Description

If you specify the -linked argument, the command recurses into

saved instances of linked subgraphs.
-all-linked Use with the -linked argument. Recurses into linked subgraphs even
if they aren’t viewable in the GDE. That is, the command recurses
into a linked subgraph even when the Permit View property is
disabled on the Description tab of the subgraph’s Properties dialog.
-external By default, searches attributes or parameters that you can edit
directly. Examples of items that can’t be edited directly include the
names and default values for parameters in components, and input
parameters on linked subgraph instances. By default, the command
searches only user-defined comments for components, not their
built-in or source comments (displayed on the Description tab in the
Properties dialog).

If you specify the -external argument, the command

searches all attributes for all visible parameters in the GDE
Parameters Editor for the current objects. Use this argument to
search values in component or subgraph prototypes. If there is no
user-defined comment at the subgraph, component, or task instance,
the command searches in the component’s built-in or source text
(displayed on the Description tab in the Properties dialog).
-regex | -exact - The -regex argument specifies that query is a regular expression.
ignore-case You cannot combine it with either of the following arguments.

The -exact argument specifies that query must match the entire text field
in the sandbox. The text field can be a graph legend, a parameter
expression, the contents of an entire text file, and so on.

The -ignore-case argument specifies that the command treats the

value of query as case-insensitive when matching it against the
sandbox.
-file-limit limit Limits the number of files that the command will search. If the value
of limit is reached, the command displays a message.
-result-limit limit Specifies how many results to return. If the value of limit is reached,
the command stops and displays a message.
-object-type type By default, searches all object types. If you specify -object-type and
are searching only graphs and plans, use this argument to limit the
search to the specified type. The type can be one of the following:

 graph — For top-level graphs and embedded subgraphs.

 linked-subgraph
 graph-interface
 component
Argument Description
 plan — For top-level plans and subplans.
 task
 legend — For graphs and plan legends.

You can specify multiple types. For more information on using this
argument, see “Usage”.
-attribute attribute By default, searches all attributes. If you specify the -
attribute argument, the command searches for the following object
attributes, as specified:

 name — The object’s display name.

 author
 comment
 param-name
 param-expression — Unresolved expressions.
 param-choice — choices in choice parameters.
 param-dml-type — DML parameter type expressions.
 param-description
 pset-prototype — The path of a pset’s prototype. This pset
chain path was created using the air sandbox pset -
prototype command or by using the GDE.
 pset-base — The path of a pset’s base. This pset chain path
was created using the air sandbox pset -base command or by
using the GDE.
 shared-catalog — The path to graph’s shared lookup
catalogs. For more information, see “Graph Settings: Catalog
category”.

You can specify multiple attributes.

-task-type type By default, searches all types of plan tasks. The value of type can be
one of the following:

 graph — For graph tasks.

 program — For program tasks.
 plan — For plan tasks, not including subplans.
 conditional
 signal-event
 wait-for-event
 wait-for-file

You can specify multiple tasks.

-path-filter filter Searches only files with paths that match filter. This argument
supports wildcard pattern matching (globbing) and it is case-
insensitive. For example, the value of filter can be *.mp if you want
Argument Description
to search all graphs.

You can specify multiple path filters.

-component-type type Searches only components of the specified type. The value
of type must be a component’s prototype path. This argument
supports wildcard pattern matching (globbing) — for
example, */Filter_by_Expression.mpc. The value can also be a
custom component. The argument is case-insensitive.

You can specify multiple component types.

-component-label lab Searches only components whose label matches the specified value.
el This argument supports wildcard pattern matching (globbing) and is
case-insensitive.

You can specify multiple component labels.

-task-label label Searches only tasks whose label matches the specified value. This
argument supports wildcard pattern matching (globbing) and is case-
insensitive.

You can specify multiple task labels.

-param name Searches only parameters whose name matches the specified value.
This argument supports wildcard pattern matching (globbing) and is
case-sensitive.

You can specify multiple parameters.

-all-file-types By default, only searches Ab Initio file types such
as .mp, .plan, .pset, .dml, and text files. If you specify the -all-file-
types argument, the command searches files of all types.
-m Writes the command output in machine-readable format to standard
output. The DML record format for the output is located
at $AB_HOME/include/air-find-text.dml.
Usage
 To search for a subobject in a graph or plan, use the following pattern for path:

path/object

For example, if you want to search the subgraph My_Subgraph that is located in the
graph my_graph, specify the path as follows:
 /disk1/sand/mp/my_graph.mp/My_Subgraph

 If the value of query or path starts with a hyphen (-), then you must place two
hyphens surrounded by a leading and a trailing space (that is, " -- ") after the last
argument and before query. For example, to identify -region as the query value and
not a command argument that starts with a hyphen, enter the following:

air sandbox find-text -- -region client-services.mp

 By default, this command searches only Ab Initio file types such

as .mp, .plan, .pset, .dml, and text files. If you specify the -all-file-types argument,
the command searches files of all types.
 To specify multiple arguments, where supported, repeat the argument name
followed by its value. The following example, searches for the term foo within
both FILTER BY EXPESSION and INPUT FILE components by repeating the -
component-type argument and value pair:

air sandbox find-text -component-type */Filter_by_Expression.mpc -component-type

*/Input_File.mpc

 The -object-type argument provides you another level of granularity for searching
with the air sandbox find-text command. For example, if you want to search for a
string in all graphs, use *.mp as the value of path. If you want to search for the
fields of a graph or a subgraph object (such as their display names), use the -object-
type argument with a value of graph.

Note, however, that this command does not search inside the graph or subgraph’s
contents. For example, suppose that you have a graph graph.mp, which contains an
embedded subgraph My Subgraph. The subgraph, in turn, contains an INPUT
FILE component My Input File. If you run the following command with a value
of My for the -graph argument, the command will return the result of the display
name My Subgraph. It will not return a result for the My Input File component that
the subgraph contains:

air sandbox find-text -object-type graph My graph.mp

 The command’s results substitute a space for new lines found in the matched
content. For example, if the output from a match would normally appear as the
number one followed by a newline, then the number two, the command results
 would show the number one, a space, and then the number two. The source data is
untouched.

NOTA:

Do not use this command to manually edit the eme_dataset_mapping parameter.

Always use the Parameters Editor in the GDE.

air sandbox get-required-files

Displays the set of files that are referenced by one or more files within a sandbox. Each line
of the output contains the project path and the relative filename separated by a tab
character. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air sandbox get-required-files [-force] path
Argument Description
-force Specifies that the command should continue even after an error is encountered
— for example, if a required file cannot be found or if a URL contains an
invalid parameter. In this case the output may be incomplete.
path Path to a file in a sandbox.
air sandbox import
Checks in a sandbox that is attached to a technical repository. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.

This command takes all the same arguments as air project import, with the exception
of -basedir and project-path. For more information, see the air project import command.
Syntax
air sandbox import sandbox-path
[-dry-run] [-fast-dry-run]
[-force] [-lock]
[-auto-add] [-add-files file ...]
[-no-read-only]
[-noanalysis] [-nodiscover-datasets]
[-files relative-rpath ...]
[-find-required-files]
[-tag tag-name [-move-tag] {-tag-all |-tag-project|-tag-exact}]
 [-comment comment]
[-published-eme published-name]
[-rollup-errors | -individual-rollup-errors | -parsable errors]
[-max-warnings [all | num-warnings]]
[-import-commons] [-quiet]
Argument Description
sandbox-path Specifies the path to the sandbox.
-dry-run Generates diagnostics but does not change the sandbox or
technical repository.
-fast-dry-run Determines the files to be checked in but does no further
error checking. It makes no changes to the sandbox or
technical repository.
-force Does not check for technical repository conflicts. The
command succeeds even if changes made in the repository
are overwritten. It also forces the checkout of removed or
ignored files specified by -files. You can also use this
argument to force checkin and tagging, even on out-of-
date sandboxes.

If -force is not specified and you have conflicts, the

command fails. See “Usage”.
-lock Causes the command to retain your locks on files in the
sandbox, and locks newly imported and modified files. By
default, the command unlocks files after importing.
-auto-add Specifies all new files in the sandbox to be automatically
added to an existing technical repository project.
-add-files file ... Checks in one or more sandbox files you specify, along
with the other files that the command determines should
be imported. You can specify - to pass the file list on
standard input. This argument is incompatible with
the -files argument.
-no-read-only Causes the checked-in files to be left writable, if they were
writable before. Normally, files are not made writable
after import until an air sandbox lock command is issued.
-noanalysis By default, dependency analysis is performed during
checkin. This argument disables this feature.
-nodiscover-datasets Disables automatic dataset creation and update for graphs
and graph instances.
-files relative-rpath ... If you specify one or more files to the -files argument,
only those files (and not related files) are checked in.
Specify project-relative paths — for
example, mp/ABC.mp. If the directory does not exist, the
command will create it. You can specify - to pass the
Argument Description
multiple files on standard input.

If omitted, all files in a project are checked in. This

argument is incompatible with the -add-files argument.
-find-required-files Also checks in any files required by the files being
checked in. These required files are imported only if they
reside in project-path. See “Usage”.
-tag tag-name Applies the tag tag-name to the project after the checkin is
completed. However, if you specify -files, the tag is
applied only to those files. The command fails if tag-
name already exists unless you also specify -move-tag.

If this argument is specified, you must also specify one of

these: -tag-all, -tag-project, or -tag-exact.
-move-tag If tag-name already exists, the tag is applied to the latest
version of each checked-in object.
-tag-all |-tag-project | -tag-exact If you specify -tag tag-name, you must also specify one of
these:

 -tag-all includes all required objects of the

checked-in objects in the tag tag-name, even if
they are in a common project.
 -tag-project includes only required objects in the
same project as the checked-in objects in the
tag tag-name.
 -tag-exact includes only the checked-in objects in
the tag tag-name.

-comment comment Associates a comment with the checkin.

-published-eme published-name Specifies the name of a “published” technical repository to
associate with the specified sandbox. (To be published, a
technical repository must be specified as one of the values
of the AB_EME_REPOSITORIES configuration
variable.)
-rollup-errors | -individual- Controls the display of dependency analysis warnings.
rollup-errors | -parsable errors You can choose one of the following:

 -rollup-errors (default) — Errors are grouped by

error message. If multiple objects are analyzed, the
group is across all objects.
 -individual-rollup-errors — Errors are grouped by
error message. The messages for each object are
grouped together.
Argument Description
 -parsable errors — Error messages are presented in
a format that can be processed programmatically
(for example, by an Ab Initio graph). For more
information, see “Usage”.

-max-warnings [all | num-warni If -rollup-errors or -individual-rollup-errors is specified,

ngs] controls the number of locations that are displayed for
each error. Set num-warnings to 0 or specify all to see all
errors. If omitted, the value of -max-warnings is the value
of the configuration
variable AB_AIR_ANALYSIS_MAX_WARNINGS,
which has a default value of 3.
-import-commons Imports the common projects for the current project. If the
project doesn’t exist, and this argument is specified,
creates the project in the same technical repository
directory as the specified project.
-quiet Suppresses the printing of some progress messages.
Usage
The sandbox must be attached to a technical repository.

This command is more convenient to use than air project import, because it is not necessary
to specify the project, the repository, or the branch.

If you want to process error messages programmatically, the DML record format for the
output of the -parsable-errors argument can be found
at $AB_HOME/include/analysis_warning.dml.

If a checkin validation is activated for a project and you are checking an object into that
project, your checkin must meet the commit policy of the checkin validation or it fails. For
example, if a checkin does not have a comment but the commit policy specifies that all
checkins must have one, the checkin fails. For more information, see “Managing commit
policies and automated actions” in the DevOps Guide.

air sandbox index commands

The air sandbox index commands let you create, manage, and report on a sandbox index. A
sandbox index caches information about the state of a specified sandbox at a specific time
— either when the sandbox index was created or the last time that the update command was
run.

If you run regular tests on graphs in your sandbox, you can use these commands to identify
only the graphs or required files that have changed. Knowing which graphs and required or
referencing files have changed allows you to streamline your testing efforts. You can also
use the air sandbox index commands to identify which files, required files, or referencing
files have changed so that you can run validation and analysis on only those files.

The following table summarizes the air sandbox index group of commands. For more
information about command syntax, see “Command-line syntax of air commands”.

Command Description
air sandbox index Adds the specified paths to the list of paths that the sandbox index
add file is watching.
air sandbox index Lists the call sites in a graph, transform, or parameter for the
call-sites specified DML function.
air sandbox index Creates a sandbox index that you can use to determine whether files
create in a particular sandbox, along with any required or referencing files,
are current or stale.
air sandbox index Lists all the function calls found under the indexed path that are made
function-calls by the specified DML function.
air sandbox index Lists all files that reference the specified file.
referencing-files
air sandbox index Removes the specified paths from the list of watched paths for the
remove sandbox index.
air sandbox index Lists all files that the specified file requires.
required-files
air sandbox index Prints information about the specified sandbox index file — in
show particular, its associated sandbox paths.
air sandbox index Indicates that the sandbox is out of date by listing files that have
show-stale changed or for which required or referenced files have changed.
air sandbox index Resets the time stamps and the list of the currently required and
update referenced files that the index stores.
air sandbox index Reports the validation status of the specified path.
validation-status
NOTA:

When set, the AB_SANDBOX_INDEX environment variable controls the default directory
where the sandbox index is created and maintained.

air sandbox index add

Adds the specified paths to the list of paths that the sandbox index file is watching. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.

NOTA:
This command does not index the files in the new paths that you specify. To index new
files in the paths that you are adding, use the air sandbox index update command.

Syntax
air sandbox index add
[ -index index ] path [ path ... ]
Command Description
-index inde Specifies the path to an existing sandbox index file. If you do not specify a
x value, defaults to the value of the AB_SANDBOX_INDEX configuration
variable.
path ... Specifies one or more file or directory paths to start indexing. Separate
multiple paths with a space.
Usage
After running the air sandbox index add command, you must run the air sandbox index
update command to index the new files found in the added paths.

To remove a path from the sandbox index, use the air sandbox index remove command.
Example
This example shows how to add an additional
path, /disk1/sand/ktomlinsoni/testing/sandbox2, to the index file proj004-idx. First, the air
sandbox index show command lists the watched paths and time that the sandbox index file
was created or updated:

air sandbox index show -index proj004-idx

Index is configured to check the following paths:
/disk1/sand/ktomlinsoni/testing/sandbox1
Index was last updated on 2018-11-07 17:50:05

The air sandbox index add command is used to add the additional
path, /disk1/sand/ktomlinsoni/testing/sandbox2. Running the air sandbox index
show command again, shows that the task was successful, as follows:

air sandbox index add -index proj004-index /disk1/sand/ktomlinson/testing/sandbox2

air sandbox index show -index proj004-idx

Index is configured to check the following paths:
/disk1/sand/ktomlinsoni/testing/sandbox1
/disk1/sand/ktomlinsoni/testing/sandbox2
Index was last updated on 2018-11-07 17:50:05
Related topics

 air sandbox index call-sites

 air sandbox index create
 air sandbox index function-calls
 air sandbox index referencing-files
 air sandbox index remove
 air sandbox index required-files
 air sandbox index show
 air sandbox index show-stale
 air sandbox index update
 air sandbox index validation-status
 AB_SANDBOX_INDEX_PARALLEL

air sandbox index call-sites

Lists the call sites in a graph, transform, or parameter for the specified DML function. The
call site is the location in the code where the function is called.
Syntax
air sandbox index call-sites
[ -index index ] [ -m ] function
Command Description
-index inde Specifies the path to the sandbox index. If you do not specify a value, the
x command defaults to the value of the AB_SANDBOX_INDEX configuration
variable.
-m Outputs the list of function calls in the format of $AB_HOME/include/call-
sites.dml.
function Specifies the name of the DML function whose call instances you want to list.
For more information on how to specify function names, see “Specifying
function names”.
Usage
This air command requires that you have previously run the air sandbox index
create command to set up a sandbox index. For more information, see “air sandbox index
create” and “air sandbox index update”.

You can set a default sandbox index path for this command using
the AB_SANDBOX_INDEX configuration variable.
Specifying function names
Function names can be unqualified, or you can qualify them by the name of the file or of
the parameter and its vertex in which they are defined.
You specify an unqualified function name as follows:

my_function

You specify a qualified function name as follows:

/path/transform.xfr:my_function

If a function is embedded in a parameter and its vertex, you specify the function name as
follows:

/path/my_graph.mp/vertex.parameter:my_function

An example of a vertex and parameter is REFORMAT.transform0. Here,

the REFORMAT component is the vertex, while its transform transform0 is the parameter.
Interpreting the command output
The air sandbox index call-sites command writes any resulting information on a single line.
The output contains three sections, each separated by a single space. The sections show the
object path; the full path to the object — including the line number in the code where the
function was found; and the statement containing the call site.

For readability, the sample output format that follows is divided into three lines
representing each type of information — one section per line. In actuality, these sections
are separated in the single-line output by a space where the continuation character (\) is
shown:

object-path-where-function-is-called \
full-path-of-the-object/vertex.parameter:line-number \
statement-with-call-site

Examples
The following example returns all call sites for a function func2 that the command finds in
the paths specified in the sandbox index file. You do not need to specify the -
index argument because the configuration variable AB_SANDBOX_INDEX was
previously set to the path to the file:
air sandbox index call-sites func2
/disk1/sand/test-sand/mp/customer-lists.mp Reformat.transform0
/disk1/sand/test-sand/mp/customer-lists.mp/Reformat.transform0:3 out.num :: func2(in.num)
/disk1/sand/test-sand/mp/customer-lists.mp Join.transform /disk1/sand/test-sand/xfr/foo.xfr:10
out.num :: func2(in.num)

In this example, the air sandbox index call-sites command found the function func2 in
a REFORMAT component. The line of code at which the function was found in the
transform transform0 was line 3. The command also found a call site for the function in a
transform in a JOIN component. However, the match was actually external to the customer-
lists.mp graph — it was found at line 10 in the transform file foo.xfr (that is, foo.xfr:10).
Note that when the path is a file, as it is here, the vertex.parameter syntax doesn’t apply.

This next example uses a fully qualified path to return only call sites to the
function func2 which is defined in the REFORMAT component transform, as follows:

air sandbox index call-sites $PWD/test-sand/mp/customer-lists.mp/Reformat.transform0:func2

/disk1/sand/test-sand/mp/customer-lists.mp Reformat.transform0
/disk1/sand/test-sand/mp/customer-lists.mp/Reformat.transform0:3 out.num :: func2(in.num)

Related topics

 air sandbox index add

 air sandbox index create
 air sandbox index function-calls
 air sandbox index referencing-files
 air sandbox index remove
 air sandbox index required-files
 air sandbox index show
 air sandbox index show-stale
 air sandbox index update
 air sandbox index validation-status

air sandbox index create

Creates a sandbox index file that you can use to determine whether files in a particular
sandbox, and any required or referencing files associated with that sandbox, are current or
stale. For information about the arguments common to all air commands, see “Command-
line syntax of air commands”.
Syntax
air sandbox index create
 [ -index index ] path [ path ... ]
Command Description
-index inde Specifies the path of the sandbox index file that you want to create. If you do
x not specify a value, the command defaults to the value of
the AB_SANDBOX_INDEX configuration variable.
path ... Specifies one or more file or directory paths that you want to associate with
the index. Separate multiple paths with a space.
Usage
The following usage details apply:

 As a best practice, we recommend that you use a naming convention to indicate that
this file is a sandbox index file. For example, you could name your index as
follows: sandbox-name-index.
 When you run this command to create an index file, all the files in the specified
sandbox paths are considered new files.
 If you specify only an index name and not a full path, this air command writes the
index file to the directory with the current focus.
 You cannot edit an index file. To see its contents, use the air sandbox index
show or air sandbox index show-stale commands. For additional commands for
managing an index file, see “air sandbox index commands”.
 To delete an index if it is no longer needed, use the Unix rm command.
 If this command process seems to run too slowly or uses too many cores, you can
use the AB_SANDBOX_INDEX_PARALLEL configuration variable to adjust the
number of subprocesses that the command creates.

Example
This example shows how you can create a sandbox index and then use the air sandbox
index show-stale command to identify and generate a list of stale files from the information
that the index stores. You can then use the DML-described output to control automated
testing by retesting only the graphs, referencing files, or referred files that have actually
changed since the last test.

The following command example creates an index file called proj004-index for the
sandbox /disk1/sand/testing-suite/sandbox1:

air sandbox index create -index proj004-index /disk1/sand/testing-suite/sandbox1

You can confirm that the index was created for the path that you intended by entering the
following command:
air sandbox index show -index proj004-index
Index is configured to check the following paths:
/disk1/sand/testing-suite/sandbox1
/disk1/sand/testing-suite/sandbox2

You can run the air sandbox index show-stale command on the sandboxes that you added to
the index when you created it. This command reports whether any objects have changed
since the index was created (or since it was last updated). Using the -m argument with
the air sandbox index show-stale command allows you to capture DML-described output
that you can use to control your automated testing suite.

Related topics

 air sandbox index add

 air sandbox index call-sites
 air sandbox index function-calls
 air sandbox index referencing-files
 air sandbox index remove
 air sandbox index required-files
 air sandbox index show
 air sandbox index show-stale
 air sandbox index update
 air sandbox index validation-status

air sandbox index function-calls

Lists all the function calls found under the indexed path that are made by the specified
DML function. Use to determine which graphs, transforms, or parameters contain the DML
function. This information can be useful if you want to determine the impact of making a
code change to the specified function. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox index function-calls
[ -index index ] [ -m ] function
Command Description
-index inde Specifies the path to the sandbox index. If you do not specify a value, the
x command defaults to the value of the AB_SANDBOX_INDEX configuration
variable.
-m Outputs the list of function calls in the format of $AB_HOME/include/call-
sites.dml.
Command Description
function Specifies the name of the DML function whose call instances you want to list.
For more information on how to specify function names, see “Specifying
function names”.
Usage
This air command requires that you have previously run the air sandbox index
create command to set up a sandbox index. For more information, see “air sandbox index
create” and “air sandbox index update”.

You can set a default sandbox index path for this command using
the AB_SANDBOX_INDEX configuration variable.
Specifying function names
Function names can be unqualified, or you can qualify them by the name of the file or of
the parameter and its vertex in which they are defined.

You specify an unqualified function name as follows:

my_function

You specify a qualified function name as follows:

/path/transform.xfr:my_function

If a function is embedded in a parameter and its vertex, you specify the function name as
follows:

/path/my_graph.mp/vertex.paramter:my_function

An example of a vertex and parameter is REFORMAT.transform0. Here,

the REFORMAT component is the vertex, while its transform transform0 is the parameter.
Interpreting the command output
The air sandbox index function-calls command writes any resulting information on a single
line. The output contains three sections, each separated by a single space. The sections
show the object path; the full path to the object — including the line number in the code
where the function was found; and the statement containing the call site.
For readability, the sample output format that follows is divided into three lines
representing each type of information — one section per line. In actuality, these sections
are separated in the single-line output by a space where the continuation character (\) is
shown:

object-path-where-function-appears \
full-path-of-the-object/vertex.parameter:line-number \
statement-with-function

Examples
The following example returns all function calls for a function func2 that the command
finds in the paths specified in the sandbox index file. You do not need to specify the -
index argument because the configuration variable AB_SANDBOX_INDEX was
previously set to the path to the file:

air sandbox index function-calls func2

/disk1/sand/test-sand/mp/customer-lists.mp Reformat.transform0
/disk1/sand/test-sand/mp/customer-lists.mp/Reformat.transform0:15 let y = cube(x);
/disk1/sand/test-sand/mp/customer-lists.mp Reformat.transform0
/disk1/sand/test-sand/mp/customer-lists.mp/Reformat.transform0:16 out :: helper_function(y)
/disk1/sand/test-sand/mp/customer-lists.mp Join.transform /disk1/sand/test-sand/xfr/foo.xfr:11 out ::
func1(x)

In this example, the air sandbox index function-calls command found the function func2 in
the transform transform0 in a REFORMAT component. The lines of code at which the
function was found were lines 15 and 16. The command also found a matching function
call in a transform in a JOIN component. However, the match was actually external to
the customer-lists.mp graph — it was found at line 11 in the transform file foo.xfr (that
is, foo.xfr:11). Note that when the path is a file, as it is here, the vertex.parameter syntax
doesn’t apply.

This next example uses a fully qualified path to return only function calls for the
function func2 that are found in the REFORMAT component transform, as follows:

air sandbox index function-calls $PWD/test-sand/mp/function-calls.mp/Reformat.transform0:func2

/disk1/sand/test-sand/mp/customer-lists.mp Reformat.transform0
/disk1/sand/test-sand/mp/customer-lists.mp/Reformat.transform0:15 let y = cube(x);
/disk1/sand/test-sand/mp/customer-lists.mp Reformat.transform0
/disk1/sand/test-sand/mp/customer-lists.mp/Reformat.transform0:16 out :: helper_function(y)

Related topics

 air sandbox index add

  air sandbox index call-sites
 air sandbox index create
 air sandbox index referencing-files
 air sandbox index remove
 air sandbox index required-files
 air sandbox index show
 air sandbox index show-stale
 air sandbox index update
 air sandbox index validation-status

air sandbox index referencing-files

Lists all files under the indexed paths that reference the specified file. For information
about the arguments common to all air commands, see “Command-line syntax of air
commands”.
Syntax
air sandbox index referencing-files
[ -index index ] file-path
Command Description
-index inde Specifies the path to the sandbox index. If you do not specify a value, the
x command defaults to the value of the AB_SANDBOX_INDEX configuration
variable.
file-path Specifies the filename for the file whose referencing files you want to list.
Usage
The following usage details apply:

 This air command requires that you have previously run the air sandbox index
create command to set up a sandbox index.
 The results shown in the output for this command will be accurate as of the last
update of the index.
 To determine when the index was last updated, enter the air sandbox index
show command.

Example
This example command and its output lists all the files that require the DML
file /sandbox1/dml/Multi_Sftp_Regional_Sales.dml, as follows:

air sandbox index referencing-files -index proj004-idx

/disk1/sand/test-suite/sandbox1/dml/Multi_Sftp_Regional_Sales.dml
Files referencing /disk1/sand/test-suite/sandbox1/dml/Multi_Sftp_Regional_Sales.dml:
/disk1/sand/test-suite/sandbox1/mp/Multi_SFTP_From_East.mp
/disk1/sand/test-suite/sandbox1/mp/Multi_SFTP_From_West.mp

Related topics

 air sandbox index add

 air sandbox index call-sites
 air sandbox index create
 air sandbox index function-calls
 air sandbox index remove
 air sandbox index required-files
 air sandbox index show
 air sandbox index show-stale
 air sandbox index update

air sandbox index create

Creates a sandbox index file that you can use to determine whether files in a particular
sandbox, and any required or referencing files associated with that sandbox, are current or
stale. For information about the arguments common to all air commands, see “Command-
line syntax of air commands”.
Syntax
air sandbox index create
[ -index index ] path [ path ... ]
Command Description
-index inde Specifies the path of the sandbox index file that you want to create. If you do
x not specify a value, the command defaults to the value of
the AB_SANDBOX_INDEX configuration variable.
path ... Specifies one or more file or directory paths that you want to associate with
the index. Separate multiple paths with a space.
Usage
The following usage details apply:

 As a best practice, we recommend that you use a naming convention to indicate that
this file is a sandbox index file. For example, you could name your index as
follows: sandbox-name-index.
 When you run this command to create an index file, all the files in the specified
sandbox paths are considered new files.
  If you specify only an index name and not a full path, this air command writes the
index file to the directory with the current focus.
 You cannot edit an index file. To see its contents, use the air sandbox index
show or air sandbox index show-stale commands. For additional commands for
managing an index file, see “air sandbox index commands”.
 To delete an index if it is no longer needed, use the Unix rm command.
 If this command process seems to run too slowly or uses too many cores, you can
use the AB_SANDBOX_INDEX_PARALLEL configuration variable to adjust the
number of subprocesses that the command creates.

Example
This example shows how you can create a sandbox index and then use the air sandbox
index show-stale command to identify and generate a list of stale files from the information
that the index stores. You can then use the DML-described output to control automated
testing by retesting only the graphs, referencing files, or referred files that have actually
changed since the last test.

The following command example creates an index file called proj004-index for the
sandbox /disk1/sand/testing-suite/sandbox1:

air sandbox index create -index proj004-index /disk1/sand/testing-suite/sandbox1

You can confirm that the index was created for the path that you intended by entering the
following command:

air sandbox index show -index proj004-index

Index is configured to check the following paths:
/disk1/sand/testing-suite/sandbox1
/disk1/sand/testing-suite/sandbox2

You can run the air sandbox index show-stale command on the sandboxes that you added to
the index when you created it. This command reports whether any objects have changed
since the index was created (or since it was last updated). Using the -m argument with
the air sandbox index show-stale command allows you to capture DML-described output
that you can use to control your automated testing suite.

Related topics

 air sandbox index add

 air sandbox index call-sites
 air sandbox index function-calls
 air sandbox index referencing-files
  air sandbox index remove
 air sandbox index required-files
 air sandbox index show
 air sandbox index show-stale
 air sandbox index update
 air sandbox index validation-status

air sandbox index remove

Removes the specified paths from the list of watched paths for the sandbox index. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air sandbox index remove
[ -index index ] path ...
Command Description
-index inde Specifies the path to the sandbox index file. If you do not specify a value, the
x command defaults to the value of the AB_SANDBOX_INDEX configuration
variable.
path Specifies the sandbox or directory path that you want to remove from the list
of watched paths. Note that you must separate multiple paths with a space.
Example
This example shows how to remove a path, /disk1/sand/ktomlinsoni/testing/sandbox1, from
being watched in an index file proj004-idx. First, the air sandbox index show command
lists the current contents of the index file:

air sandbox index show -index proj004-idx

Index is configured to check the following paths:
/disk1/sand/ktomlinsoni/testing/sandbox1
/disk1/sand/ktomlinsoni/testing/sandbox2
Index was last updated on 2018-11-07 17:50:05

The air sandbox index remove command is used to remove the

path, /disk1/sand/ktomlinsoni/testing/sandbox1, from the list of watched paths in the index.
Running the air sandbox index show command again, shows that the task was successful, as
follows:
air sandbox index remove -index proj004-idx /disk1/sand/ktomlinsoni/testing/sandbox1
[empty line indicating success]
air sandbox index show -index proj004-idx
Index is configured to check the following paths:
/disk1/sand/ktomlinsoin/testing/sandbox2
Index was last updated on 2018-11-07 17:50:05

Related topics

 air sandbox index add

 air sandbox index call-sites
 air sandbox index create
 air sandbox index function-calls
 air sandbox index required-files
 air sandbox index referencing-files
 air sandbox index show
 air sandbox index show-stale
 air sandbox index update

air sandbox index required-files

Lists all files that the specified file requires to run properly. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox index required-files
[ -index index ] path
Command Description
-index inde Specifies the path to the sandbox index file. If you do not specify a value, the
x command defaults to the value of the AB_SANDBOX_INDEX configuration
variable.
path Specifies the sandbox or directory path for which you want to list any required
files.
Usage
The following usage details apply:

 This air command requires that you have previously run the air sandbox index
create command to set up a sandbox index.
 The results shown in the output will be accurate as of the last update of the index.
 To determine when the index was last updated, enter the air sandbox index
show command.
Example
This example shows all the files that are required by the graph Multi_SFTP.mp found
within sandbox1.

air sandbox index required-files -index proj004-idx

/disk1/sand/test-suite/sandbox1/mp/Multi_SFTP.mp
Required files for /disk1/sand/test-suite/sandbox1/mp/Multi_SFTP.mp:
/disk1/sand/test-suite/sandbox1/.project.ksh
/disk1/sand/test-suite/sandbox1/run/Multi_SFTP.ksh
/disk1/sand/test-suite/sandbox1/.project-end.ksh
/disk1/sand/test-suite/sandbox1/ab_project_setup.ksh
/disk1/sand/test-suite/sandbox1/dml/Multi_Sftp_Regional_Sales.dml
/disk1/sand/test-suite/sandbox1/.sandbox.pset
/disk1/sand/test-suite/sandbox1/.project.pset
/disk1/sand/test-suite/sandbox1/.project-start.ksh

Related topics

 air sandbox index add

 air sandbox index call-sites
 air sandbox index create
 air sandbox index function-calls
 air sandbox index referencing-files
 air sandbox index remove
 air sandbox index show
 air sandbox index show-stale
 air sandbox index update
 air sandbox index validation-status

air sandbox index show

Prints information about the specified sandbox index. The information includes the paths
that are monitored for stale state and when the index was last updated. For information
about the arguments common to all air commands, see “Command-line syntax of air
commands”.
Syntax
air sandbox index show
[ -index index ]
Command Description
-index inde Specifies the path to the sandbox index. If you do not specify a value, the
x command defaults to the value of the AB_SANDBOX_INDEX configuration
Command Description
variable.
Usage
This air command requires that you have previously used the air sandbox index
create command to set up a sandbox index.
Example
The following example shows that the proj005-idx index is used to store change
information for the sandboxes sandbox1 and sandbox2:

air sandbox index show -index proj005-idx

Index is configured to check the following paths:
/disk1/sand/testing-suite/sandbox1
/disk1/sand/testing-suite/sandbox2
Index was last updated on 2018-11-07 17:50:05

Related topics

 air sandbox index add

 air sandbox index call-sites
 air sandbox index create
 air sandbox index function-calls
 air sandbox index referencing-files
 air sandbox index remove
 air sandbox index required-files
 air sandbox index show-stale
 air sandbox index update

air sandbox index show-stale

Lists files that have changed or for which required or referencing files have changed since
the last time that the air sandbox index update command was run. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox index show-stale
[ -index index ]
[ -m ]
[ -verbose ]
[ -update ]
Command Description
-index inde Specifies the path to the sandbox index. If you do not specify a value, the
x command defaults to the value of the AB_SANDBOX_INDEX configuration
variable.
-m Prints verbose results in a DML-described form that is defined
in $AB_HOME/include/stale-files.dml.
-verbose Prints verbose information for each stale file. The information includes
whether the file was added, modified, or deleted. It also lists any stale required
files. If you do not specify this argument, the default behavior displays a list of
newline-separated filenames, without specifying the reason why they are stale.
-update Updates the index while the stale files are computed and identified. Use this
argument to automatically run the equivalent of the air sandbox index
update command to reset the index cache.
Usage
The following usage details apply:

 This air command requires that you have previously run the air sandbox index
create command to set up a sandbox index.
 The command only reports on files and required files found in the specified sandbox
index path.
 The command determines that a file or a required file has changed if it was added,
modified, or deleted since the index was last updated.
 To determine when the index was last updated, use the air sandbox index
show command.

Example
The following example lists files that have changed since the last time that the air sandbox
index update command or the -update argument were run. The output shows that several
files — including .plan and .pset files — were added, and a required
file Multi_Sftp_Regional_Sales.dml was modified:

air sandbox index show-stale -index proj005-idx

/disk1/sand/test-suite/sandbox1/mp/MyFirstPlan.plan was modified.
/disk1/sand/test-suite/sandbox1/pset/Multi_SFTP.pset was added.
/disk1/sand/test-suite/sandbox1/xfr/sb1-new.xfr was added.
/disk1/sand/test-suite/sandbox2/dml/Multi_Sftp_Regional_Sales.dml was modified.
/disk1/sand/test-suite/sandbox2/mp/Multi_SFTP_To_Example.mp was modified.
/disk1/sand/test-suite/sandbox2/mp/Multi_SFTP_From_Example.mp was modified.
/disk1/sand/test-suite/sandbox2/mp/Multi_SFTP_From_Example2.mp the following required file(s)
were changed:
/disk1/sand/test-suite/sandbox2/dml/Multi_Sftp_Regional_Sales.dml
/disk1/sand/test-suite/sandbox2/xfr/sb2-new.xfr was added.
SUGERENCIA:

You can use this command with the -m argument to generate DML-described output. You
can use the command output to streamline and control automatic testing, so that you test
only files that have changed.

Related topics

 air sandbox index add

 air sandbox index call-sites
 air sandbox index create
 air sandbox index function-calls
 air sandbox index referencing-files
 air sandbox index remove
 air sandbox index required-files
 air sandbox index show
 air sandbox index update
 air sandbox index validation-status

air sandbox index update

Recomputes the timestamps and required files for all files in the paths specified by the
index. For information about the arguments common to all air commands, see “Command-
line syntax of air commands”.
Syntax
air sandbox index update
[ -index index ]

Command Description
-index inde Specifies the path to the sandbox index. If you do not specify a value, the
x command defaults to the value of the AB_SANDBOX_INDEX configuration
variable.
Usage
This air command requires that you have previously used the air sandbox index
create command to set up a sandbox index.

This command only reports files as stale if they or their required or referencing files
changed since you last ran this command. A file that is in a changed state has been added,
modified, or deleted.

Run this command after adding new watched paths to an index by using the air sandbox
index add command. Doing so initially indexes the objects found in the new watched paths.
If this command process seems to run too slowly or uses too many cores, you can use
the AB_SANDBOX_INDEX_PARALLEL configuration variable to adjust the number of
subprocesses that the command creates.
Example
The following examples first list files that have changed since the last time that the air
sandbox index update command or the air sandbox index show-stale -update command
argument were run. Next, the example uses the air sandbox index update command to reset
the index. This command clears the information that the index stores, thereby removing the
files that are currently flagged as stale. Any changes that you make to the sandbox after you
run this command will now appear as stale.

The following command output shows that several files changed since the last time that the
index proj005-idx was updated. The changes include a required file, the DML
record Multi_Sftp_Regional_Sales.dml:

air sandbox index show-stale -index proj005-idx

/disk1/sand/test-suite/sandbox1/mp/MyFirstPlan.plan was modified.
/disk1/sand/test-suite/sandbox1/pset/Multi_SFTP.pset was added.
/disk1/sand/test-suite/sandbox1/xfr/sb1-new.xfr was added.
/disk1/sand/test-suite/sandbox2/dml/Multi_Sftp_Regional_Sales.dml was modified.
/disk1/sand/test-suite/sandbox2/mp/Multi_SFTP_To_Example.mp was modified.
/disk1/sand/test-suite/sandbox2/mp/Multi_SFTP_From_Example.mp was modified.
/disk1/sand/test-suite/sandbox2/mp/Multi_SFTP_From_Example2.mp the following required file(s)
were changed:
/disk1/sand/test-suite/sandbox2/dml/Multi_Sftp_Regional_Sales.dml
/disk1/sand/test-suite/sandbox2/xfr/sb2-new.xfr was added.

The following update command recomputes the timestamp and other information in the
specified index:

air sandbox index update -index proj005-idx

After the update command is run, the air sandbox index show-stale command indicates by
its lack of output that the index contents have been reset — as follows:

air sandbox index show-stale -index proj005-idx

Related topics

 air sandbox index add

 air sandbox index call-sites
 air sandbox index create
  air sandbox index function-calls
 air sandbox index referencing-files
 air sandbox index remove
 air sandbox index required-files
 air sandbox index show
 air sandbox index show-stale
 air sandbox index validation-status
 AB_SANDBOX_INDEX_PARALLEL

air sandbox index validation-status

Reports the validation status of graphs and psets in the specified sandbox file or directory
path.

For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air sandbox index validation-status
[ -index index ] [ -m ] path ...
Argument Description
-index inde Specifies the path to the sandbox index file that you want to pull the validation
x status from. If you do not specify a value, defaults to the value of
the AB_SANDBOX_INDEX configuration variable.
-m Prints verbose results in a DML-described form that is defined
in $AB_HOME/include/stale-files.dml.
path ... Path to a sandbox file or directory to report the validation status for. If you
specify multiple paths, this argument behaves like the air sandbox validation-
graph command with the - flag specified reading in paths from stdin.
Usage
The following usage details apply:

 This air command requires that you have previously used the air sandbox index
create command to set up a sandbox index.
 This air command does not return any output if you specify a file that does not exist.
 Specify $PWD as the path if you want to specify the directory that you are in.

The command can return the following:

0 — Validation succeeded.

1 — Validation failed.
2 — validation succeeds but errors or warnings were found.

Validation can fail if the specified path does not have an index. If you specify the -
m argument, errors are sent to stdout instead of stderr, and the command always returns 0.

If this command returns errors for a graph or pset, the graph won’t run. You must correct
any errors identified in the error messages. For example, if you use an INPUT
FILE component instead of a valid subscriber to input data into a continuous graph, the
command displays an error message identifying the invalid component that you must
replace.
Example
The following example shows output generated from running the command on the
sandbox index proj004-index in the current directory, index-test.

The command reports an error with the application-test-004-beta.mp and also lists objects
that it does not validate.

air sandbox index validation-status -index proj004-index $PWD

/u/cforde/index-test/.sandbox.pset
Object at "/u/cforde/index-test/.sandbox.pset" is not a graph or a graph instance.

The error was:

The expression '${AI_SERIAL}/customers.dat' cannot be evaluated at the position of parameter
'eme_dataset_mapping' due to an error in 'AI_SERIAL'.
The actual error is as follows:
Parameter not found: AI_SERIAL

The actual error is as follows:

Parameter not found: AI_DML
Error processing parameter Layout: Parameter not found: AI_SERIAL

/u/cforde/index-test/mp/application-test-004.mp
/u/cforde/index-test/proj004-index
Object at "/u/cforde/index-test/proj004-index" is not a graph or a graph instance.

Related topics

 air sandbox index add

 air sandbox index call-sites
 air sandbox index create
 air sandbox index function-calls
 air sandbox index referencing-files
 air sandbox index remove
 air sandbox index required-files
 air sandbox index show
  air sandbox index show-stale
 air sandbox index update

ir sandbox info
Displays information about a sandbox or files within it. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox info [ -basic ] path ...
Argument Description
-basic Displays a subset of information — including the sandbox object’s full path,
full path to the repository root, branch name, any published repository name,
and its project name.

Use this argument to determine what sandbox a technical repository is attached

to without needing to actually connect to the repository.
path ... Path to a sandbox file or directory.
Usage
The information display for path includes the following:

 The sandbox information lists the object’s full path; object’s size; author; time of
creation, modification, and access; the latest version in the sandbox; and file
permissions.
 The technical repository information lists the published technical repository name,
the full path to the repository root, the branch name, and the project name.

If path is a file, the information lists the MIME type and size, the latest version in
the repository, the current file state (for example, current or modified), the tag (if
any) recorded in the sandbox for the last checkin or checkout, and the lock state. If
the file is locked, the display shows the lock owner and timestamp information.

NOTA:

Tag information is recorded on files only, not on directories. The sandbox directory
itself does not have tag information.

Example
The following example displays information about the specified sandbox — in this case,
the value indicated by the $PROJECT_DIR environment variable:
air sandbox info $PROJECT_DIR
Filesystem:
Path: /disk1/sand/ktomlinsoni/Providence
Size: 4096
Owner: ktomlinsoni
Modified: 2017-01-26 15:23:01
Permissions: drwxr-xr-x
EME Technical Repository:
Repository: file://docloc64/disk1/EME/docloceme
Branch: main
Published Name: docloceme_kt
Project: /Projects/PRs/Providence

The following example uses the optional -basic argument to display a subset of information
about same sandbox that was used in the previous example. This command can be used
without having to actually connect to the repository:

air sandbox info -basic $PROJECT_DIR

Filesystem:
Path: /disk1/sand/ktomlinsoni/Providence
EME Technical Repository:
Repository: file://docloc64/disk1/EME/docloceme
Branch: main
Published Name: docloceme_kt
Project: /Projects/PRs/Providence

air sandbox integrate

Merges the changes from a source project version in to a target sandbox using the specified
base project version as the original starting point. This command is branch-specific. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air sandbox integrate sandbox-path
[ -source-root source-root ]
[ -source-branch source-branch ]
[ -source-version source-version ]
[ -source-project source-project-path ]
[ -base-root base-root ]
 [ -base-branch base-branch ]
[ -base-version base-version ]
[ -base-project base-project-path ]
[ -no-lock ] [ -dry-run ]
[ -files file ... ]
[ -quiet ]
Argument Description
sandbox-path Specifies the target sandbox where the branch integration will take
place. If unspecified, the command uses the sandbox branch.
-source-rootsource- Specifies the root for the source project. Use with the -base-
root root argument to perform an integration across multiple repositories.
-source-branch sourc Specifies the branch for the source project. If this argument is
e-branch unspecified, the command uses the sandbox branch.
-source-version sour Specifies the version of the source project. If this argument is
ce-version unspecified, the command uses the latest version.
-source-project sour Specifies the location of the source project. If this argument is
ce-project-path unspecified, the command uses the sandbox project.
-base-root base-root Specifies the root for the common ancestor for the two files. Use with
the -source-root argument to perform an integration across multiple
repositories.
-base-branch base- Specifies the branch for the common ancestor for the two files. If this
branch argument is unspecified, the command uses the sandbox project.
-base-version base- Specifies the version of the common ancestor for the two project
version versions. If this argument is unspecified, the command uses the latest
version.
-base-project base- Specifies the location of the common ancestor for the source and
project-path target projects. If this argument is unspecified, the command uses the
sandbox project.
-no-lock Performs the instruction but without attempting to lock the files. Use
this argument to override the command’s default behavior, which is
to attempt to lock all files that are modified by the integration and
break locks that are held by others.
-dry-run Performs the integration but without writing any actual changes. Use
this argument to test what the integration would do. The command’s
output displays the projected results for the argument values that you
provided.
-files files Specifies a list of files to integrate. If this argument is unspecified, all
files are integrated by default. To read from standard input, specify a
hyphen (-) for the value of this argument.
-quiet Suppresses the display of the command’s progress information.
Usage
The following requirements and actions apply:

 The sandbox must be attached to an EME technical repository.

 All files in the sandbox specified by sandbox-path must be current.
 The integration operation will attempt to lock all files and will break any files that
are locked by others.
 This command attempts to integrate the projects regardless of whether the lock
attempt was successful or whether any files were previously locked.

NOTA:

Some files cannot be automatically merged — such as, MS Word documents, Express>It
templates, AppConf objects, and rulesets. You must manually merge these types of files.

Unresolved conflicts
If unresolved conflicts occur during the merge attempt, the integration writes specific files
in the sandbox based on the type of unresolved conflict that it encounters. The contents and
names of the files are dictated by the type of conflict that was found and its relationship to
the source or base files. The purpose of writing these files to the sandbox is to provide you
with easy access to information to help you determine how to manually resolve the
conflicts. For example, you can use the air commands or the GDE or TRMC client-based
viewing and differencing features to learn more about the contents of these files and how a
specific decision to merge them might affect them. The possible scenarios and their
resultant file are the following:

 If the integration operation determines that a merge is required but there is an

unresolved conflict, the integration operation leaves the sandbox
file unmodified and places the merged results in a new sandbox file. The file uses
the naming convention filename.conflict.extension — for
example, mygraph.conflict.mp.
 If the conflict is due to an addition and the target exists, the integration operation
places the contents of the source file in a sandbox file. The file uses the naming
convention filename._source_.extension — for example, mygraph._source_.mp.
 If the target doesn’t exist, the integration operation places the contents of the base
file in a sandbox file with the naming convention filename._base_.extension and it
also places the contents of the source file in a sandbox file with the naming
convention filename._source_.extension. Saving the base and source files to the
sandbox allows you to look at their contents to determine how to resolve the
conflict. You can also perform various differencing functions on the files — by
either using the air sandbox diff command or the Difference viewer in the GDE. For
more information on the latter, see “Difference Viewer”.

NOTA:
The Project > Integration main menu item in the GDE implements a subset of
this air command. The Integration Wizard is also available in the TRMC. For more
information, see “El Asistente para integraciones”.

Examples
The command in this example integrates the latest changes found on the
branch my_branch (the source) into the specified sandbox customer_tickets04 (the target).
The command automatically computes the base for the two branches whose objects are to
be integrated, as follows:

air sandbox integrate customer_tickets04 -source-branch my_branch

For an example workflow, see “Integration workflow and task examples using air
commands” in the Technical Repository Guide to Version Control.

In this example, the source is a remote repository. The command integrates the tip changes
in the source with the (current) repository since the tag base-version-tag was created. The
value of AB_AIR_ROOT for the source repository
is //remote-server/remote/repository/eme/eme:

# integrate-sand is the target and it is attached to the repository and branch

air project export /Projects/myproj -basedir integrate-sand

air sandbox integrate integrate-sand

-base-version base-version-tag
-source-root //remote-server/remote/repository/eme/eme

After running the air command, if there are any conflicts, you must use the GDE to resolve
them. For more information, see “Resolver archivos sin resolver con el software del
GDE” and “Integration workflow and task examples using air commands” in the Technical
Repository Guide to Version Control.

Related topics

 air project export -merge

 air sandbox export -merge
 air sandbox merge
 air sandbox resolve

air sandbox lock

Performs lock operations on sandbox objects. The default operation is -set (create a lock).
For information about the arguments common to all air commands, see “Command-line
syntax of air commands”. For information on administrative locking tasks, see “air lock
commands”.
Syntax
air sandbox lock {path | -parameters [sandbox-path]}
[-set | -release | -break | -reset]
[-nocheck]
[-force]
[-unbreakable]
[-manual-release]
Argument Description
path | -parameters [sandbox- You must specify one of the following:
path]
 path specifies the path to an object in a checked-in
sandbox. If the object is a graph, the run script
associated with the graph is also locked.
 -parameters specifies that the parameters file in the
current sandbox should be locked.

Specify sandbox-path if you are not in the sandbox

containing the parameters file you want to lock. If
omitted, defaults to current sandbox.
-set | -release | -break | -reset You may choose one of the following:

 -set locks a file in a sandbox. Makes the file in the

sandbox writable.
 -release releases the lock from a file in a sandbox.
Makes the file in the sandbox read-only.
 -break breaks another user’s lock on a file in your
sandbox. (After that, you can lock the file with air
sandbox lock -set.)
 -reset resets a lock broken by another user to
unlocked state.

-nocheck Valid if -set or -release is specified. Causes these

arguments to not do timestamp checking. (If omitted, -
set denies locks on old files and -release prevents the
release of locks on modified files.)
-force Valid if -set is specified. Breaks another user’s lock, if
necessary, before setting lock.
-unbreakable Valid if -set is specified. Sets the lock to be unbreakable
except by the Technical Repository administrator.
Argument Description
-manual-release Valid if -set is specified. Causes the lock to persist beyond
checkin until explicitly broken or released.
Usage
This command automatically sets the value of AB_AIR_ROOT based on the repository that
the sandbox is attached to. This means that you can run the command without the -
root argument or without having previously set the value of AB_AIR_ROOT.
Obsolete arguments
Support has been removed for -ignore-script in Version 2.15.

air sandbox merge

Merges three files — starting from a common base file — to combine changes made to the
source and target files and produce a merged result in the destination file. For information
about the arguments that are common to all air commands, see “Command-line syntax of
air commands”.
Syntax
air sandbox merge base source target destination
[ -nolegend ] [ -ignore-ws ]
[ -resolutions url | -b | -s | -t ]
[ -diffs ] [ - mdiff ] [ -rdiff ]

Argument Description
base Specifies the common ancestor for the merge.

You specify the path to a file, such as a graph, followed by one of the
following:

 -eme — The file path for the repository, which is the same
value as AB_AIR_ROOT.
 -eme=eme root — The file path to use as the repository root.

source The source of changes to be merged into target.

You specify the path to a file, such as a graph, followed by one of the
following:

 -eme — The file path for the repository, which is the same
value as AB_AIR_ROOT.
Argument Description
 -eme=eme root — The file path to use as the repository root.

target The target file of the merge.

You specify the path to a file, such as a graph, followed by one of the
following:

 -eme — The file path for the repository, which is the same
value as AB_AIR_ROOT.
 -eme=eme root — The file path to use as the repository root.

destination Where the merged file is written.

-resolutions url | -b | Specifies how to resolve conflicts that are detected as a result of the
-s | -t merge.

Specify one of the following:

 -resolutions url — Specifies the path to a file containing

explicit conflict resolution instructions. Although you can use
any file type for the resolution file, we recommend a text file
format.
 -b — Specifies that, if conflicts are detected, take the base
(original) version of the change.
 -s — Specifies that, if conflicts are detected, take the source
version of the change.
 -t — Specifies that, if conflicts are detected, take the target
version of the change.

-nolegend | -ignore- Controls merge options for summarizing conflicts in graphs or plans
ws and ignoring whitespace in text files or parameters.

Specify one or both of the following:

 -nolegend — After merging graphs or plans, do not insert a

legend summarizing any conflicts.
 -ignore-ws — Do not consider extra whitespace as significant
when merging text files or parameters.

-diffs | -mdiff | - Controls merge debugging print options. Specify one of the following:
rdiff
 -diffs — Prints the differences from base to source and
from base to target.
 -mdiff — Prints the difference after combining the differences
among base, source, and target.
Argument Description
 -rdiff — Prints the differences after applying conflict
resolution.

Usage
Use this command when you want to do your own custom merge or if you want to use
merge with a third-party SCM.

You do not need to specify a filename in the resolutions file for air sandbox merge.

You can run this command without having a project or a sandbox.

NOTA:

Some files cannot be automatically merged — such as Microsoft Word documents,

Express>It templates, AppConf objects, and rulesets. You must manually merge these types
of files.

How conflicts are handled during a merge operation

During the merge, this command outputs a list of conflicts. However, it does not produce a
standalone .conflict. file.

If there are text conflicts, air sandbox merge inserts markers into the merged file (see
the example below).

If there are structural conflicts, air sandbox merge puts the target change in the specified
merged file. A structural conflict is a conflict for which air sandbox merge cannot add a
marker in the file; for example, a conflict that arises from changing a component and then
deleting a component.

NOTA:

If running air sandbox merge generated conflict warnings, the merged .mp file will contain
a list of merge conflicts. You can view and address the merge conflicts in the GDE. The
GDE will prompt you to address any conflict notices, which you must do manually. For
detailed instructions, see “Resolver archivos sin resolver con el software del GDE” in the
Co>Operating System Graph Developer’s Guide.

Example
The following figure shows four versions of a file. The file starts as a common base file in
the technical repository. A developer changes the base file and checks it into the technical
repository, where it now resides as a source file. Another developer, Matty, changes the
base file and saves it to his sandbox, where it is now a target file. He runs the air sandbox
merge command, which combines the changes to the source and target files to produce a
merged file that resides in Matty’s sandbox.

The following example merges three graph files into one merged file, /tmp/x.mp.

air sandbox merge my_base.mp my_src.mp my_trgt.mp /tmp/x.mp

In the resulting command output, the merge attempt reveals that there are four text
conflicts:

Conflicts detected:
0:
Reformat.transform0:
<<<<<<< Source
out.aa:: in.aa;
out.b :: in.b;
||||||| Base
out.a :: in.a;
out.b :: in.b;
=======
out.aaa:: in.aaa;
out.bb:: in.bb;
>>>>>>> Target

1:
Reformat.transform0:
<<<<<<< Source
out.d:: in.d+1;
||||||| Base
out.d :: in.d;
=======
 out.d:: in.d+2;
>>>>>>> Target

2:
Reformat:
Base->Source
'transform0' changed:
interpretation:
< constant
---
> dollar_curly_substitution
flags:
< INTERP_literal
---
> INTERP_dollar_curly_substitution
expression:
3c3
< out.a :: in.a;
---
> out.aa:: in.aa;
6c6
< out.d :: in.d;
---
> out.d:: in.d+1;
Base->Target
'transform0' changed:
interpretation:
< constant
---
> pdl
flags:
< INTERP_literal
---
>
expression:
3,4c3,4
< out.a :: in.a;
< out.b :: in.b;
---
> out.aaa:: in.aaa;
> out.bb:: in.bb;
6c6
< out.d :: in.d;
---
> out.d:: in.d+2;

3:
 Input_File.read_metadata:
<<<<<<< Source
int aa;
int b;
||||||| Base
int a;
int b;
=======
int aaa;
int bb;
>>>>>>> Target

Section 2: in the preceding example uses text object difference indicators to mark conflicts.
For information about how to interpret text object difference indicators, see “For text
objects” in the Technical Repository Administrator’s Guide.

The developer can write a resolutions file x.resolution, with the following contents, which
specifies how to handle each conflict:

0: source
1: base
2: target
3: target

The developer can then run air sandbox merge again, but this time specify that the
resolutions file x.mp contains explicit instructions on how to resolve each conflict. This is
done with the -resolutions argument as follows:

air merge my_base.mp my_src.mp my_trgt.mp /tmp/x.mp -resolutions x.resolution

Alternatively, the developer could run air sandbox merge with one of the -t, -b, or -
s arguments to -resolutions and resolve all conflicts by specifying that the command should
take the target version, base version, or source version, respectively, of a conflicting
change.

Related topics

 air project export -merge

 air sandbox export -merge
 air sandbox integrate
 air sandbox resolve
air sandbox move
Moves a file in the sandbox to another location in the sandbox and moves the file in the
EME technical repository at the next checkin. This command is branch-specific. For
information about the arguments that are common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air sandbox move from_file to_file
Argument Description
from_file Path to the sandbox file that you want to move or rename.
to_file Path to the new location in the sandbox for the file that you want to move or
rename.
Usage
This command locks the specified from_file, assigns it the state of PendingRemove, and
moves it to the new location, where it is assigned the state of PendingAdd. At the next
checkin, the PendingRemove files are removed from the repository, and
the PendingAdd files are added.

This command automatically sets the value of AB_AIR_ROOT based on the repository that
the sandbox is attached to. This means that you can run the command without the -
root argument or without having previously set the value of AB_AIR_ROOT.

To undo a pending removal or pending add of a file, run air sandbox revert. Running that
command clears the file state and restores the removed file from the repository.
Example
To rename a graph from acc-procc.mp to account-processing.mp, enter the following:

air sandbox move /disk1/sand/jbpatel/accts/mp/acc-proc.mp /disk1/sand/jbpatel/accts/mp/account-

processing.mp

air sandbox package-for-support

Creates a Package for Support that can be used by Departamento de soporte técnico de Ab
Initio to resolve technical issues you may encounter. The Package for Support contains
information about the technical repository, and any sandboxes attached to it, the
Application Hub, and the Co>Operating System.
This command lets you create a package from a shell session in situations where an Ab
Initio client such as the GDE or TRMC is not available. You can also specify a particular
sandbox as the starting level of the package; otherwise this command generates a package
that is identical to one created with an Ab Initio client’s user-interface.
Syntax
air sandbox package-for-support path [path ...] [-name package_name]
Argument Description
path Specifies the path to an object in a sandbox or the path to the
sandbox itself. The path can either be relative to the directory where
the command is run or a full path.
-name package_name Name of the package file. The command adds the extension .tar.gz.
If you do not specify a filename, the default is sandbox-pfs.tar.gz. If
you do not you specify a path in package_name, the command
writes the tar file to the current directory.
Usage
You can specify a path to an object as a shortcut method for specifying the sandbox that
contains it. When given a sandbox object for path, the command searches for an associated
sandbox, datastore, and more and includes them in the package.
Example
This example uses a graph for the value of path. The command locates all of the relevant
files and creates a package file called pfs_04304_2.tar.gz.

air sandbox package-for-support Graph1.mp pfs_04304_2

Creating Package ... ... successfully created packaging directory

Packaging Sandbox files ...

Adding: /disk1/data/sandboxZ/.air-lock
Adding: /disk1/data/sandboxZ/.air-project-parameters
Adding: /disk1/data/sandboxZ/.air-sandbox-overrides
Adding: /disk1/data/sandboxZ/.project-end.ksh
Adding: /disk1/data/sandboxZ/.project-start.ksh
Adding: /disk1/data/sandboxZ/.project.ksh
Adding: /disk1/data/sandboxZ/.project.pset
Adding: /disk1/data/sandboxZ/ab_project_setup.ksh
Adding: /disk1/data/sandboxZ/.sandbox.pset
Adding: /disk1/data/sandboxZ/.sandbox-state.1233846213.1396
Adding: /disk1/data/sandboxZ/components
Adding: /disk1/data/sandboxZ/components/subgraph1.mp
Adding: /disk1/data/sandboxZ/dat
Adding: /disk1/data/sandboxZ/db
Adding: /disk1/data/sandboxZ/db/oracle.dbc
 Adding: /disk1/data/sandboxZ/dml
Adding: /disk1/data/sandboxZ/dml/a_type.dml
...
Adding: /disk1/data/sandboxZ/Graph1.mp
Adding: /disk1/data/sandboxZ/run/Graph1.ksh
Adding: /disk1/data/sandboxZ/mp
Adding: /disk1/data/sandboxZ/mp/condcomp-2-no-reformat.pset
Adding: /disk1/data/sandboxZ/mp/condcomp-2.mp
Adding: /disk1/data/sandboxZ/mp/condcomp-2-no-sort.pset
...
Adding: /disk1/data/sandboxZ/xfr/shared.xfr
...
Adding: /disk1/data/sandboxZ/plan
Adding: /disk1/data/sandboxZ/plan/gen-trash.plan
Adding: /disk1/data/sandboxZ/resource
Adding: /disk1/data/sandboxZ/run
Adding: /disk1/data/sandboxZ/xfr
Adding: /disk1/usr/local/abinitio-app-hub/include/error-V2-16.dml
Adding: /disk1/usr/local/abinitio-app-hub/include/log-V2-15-4.dml
Adding: /disk1/usr/local/abinitio-app-hub/include/error-info-type.dml
... Sandbox successfully packaged

Packaging Application Hub files ...

Adding: /disk1/usr/local/abinitio-app-hub/MANIFEST
Adding: /disk1/usr/local/abinitio-app-hub/config/abinitiorc
Adding: /u/rhaddleton/.abinitiorc
Adding: /disk1/usr/local/abinitio-app-hub/config/wrapper.ksh
Adding: ab-computer-info.txt
Adding: /disk1/usr/local/abinitio-app-hub/config/key.txt
Adding: env.out
...
... Application Hub files successfully packaged

Sandbox is not attached to a Technical Repository, TR files not packaged.

Creating archive ...

... Archive successfully created: pfs_04304_2.tar.gz

air sandbox parameter

Creates and manipulates parameters in a sandbox parameters file, a graph, a plan, or an
input pset (.pset) file. The default command adds or modifies a parameter; you can specify
a value, interpretation, and other parameter attributes.

Also declares or deletes a graph, plan, or project parameter. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
The syntax of air sandbox parameter takes one of these forms:

air sandbox parameter [ pset | sbox ] parameter [ interpretation ]

[value] [flag]
air sandbox parameter [ pset | sbox ] choice-parameter -choice
choice ...
air sandbox parameter [ pset | sbox ] dependent-parameter -dependent
choice-parameter
air sandbox parameter [ pset | sbox ] dependent-parameter -case choice
[interpretation] dependent-value
air sandbox parameter [ pset | sbox ] common-project-parameter -
common common-sbox-path [-relative-common]
air sandbox parameter [ pset | sbox ] parameter -comment comment-
value
air sandbox parameter [ pset | sbox ] parameter -type type-value
air sandbox parameter [ pset | sbox ] parameter -dml-type dml-type-
expression
air sandbox parameter [ pset | sbox ] -remove parameter
air sandbox parameter [ pset | sbox ] -expression parameter
Argument Description
pset | sbox Specifies the location of the parameter. If omitted, the
current sandbox’s parameters file is used.

 You can explicitly specify pset as -path path,

where path is the path to a .pset file, graph, or
plan. It does not have to reside in a sandbox.

NOTA:

Unless otherwise noted, we recommend using -

path instead of -basedir to explicitly specify the
parameter set that you want to modify.
However, if you use the -common argument,
you must use the -basedir syntax.

 You can explicitly

specify sbox as -basedir sbox-path,
where sbox-path is the path to the sandbox that
Argument Description

contains the parameters file to use. The default

is sbox-path/.project.pset.
 If you specify the optional -resolve-
from argument, then the command will resolve
the pset -path path as though it was located in
the specified sandbox. You can place this
argument any where in the command line
after -path pset.

parameter Name of the sandbox parameter to be operated on.

You can override a parameter in a common project.
Use the @ (at sign) notation to identify the parameter
location — for example:

PARAM@ instructs the software to search from the

current project upward through the chain of included
common projects until it encounters a parameter with
the name PARAM in a common project. It applies the
override value to that
parameter. PARAM@COMMON_PROJECT_PARA
M instructs the software to override the parameter
PARAM in the common project identified by the
parameter COMMON_PROJECT_PARAM.
interpretation Interpretation used for the value (value). You can
choose one of these:

 -constant — Use constant interpretation, where

no substitution occurs. You can use the -
literal value as a synonym for -constant.
 -pdl — Use Parameter Definition Language
(PDL) interpretation, a superset of the other
parameter interpretation options.
 -dollar — Use $ dollar substitution
interpretation.
 -curly — Use ${ } substitution interpretation.
 -ksh — (Deprecated interpretation) Use -pdl if
you need to enter Korn shell inline
computations.

Default is -pdl.

For more information, see “Interpretación de

parámetros” in the Co>Operating System Guía para
desarrolladores de grafos.
Argument Description
value Value to be applied to the parameter or dependent
case.
flag Choose one of the following parameter attribute flags:

 -required or -not-required (default)

 -export or -not-export (Format 3 default)
 -overridable or -not-overridable (default)

To allow a parameter to have a private value

specify the -overridable flag. This causes
the Overridable box to be checked in the GDE
Parameters Editor.

 -input (default) or -local. You can use the -

formal value as a synonym for -input. Both
values are equivalent to specifying
the Input parameter attribute in the GDE. For
more information, see Usage information.
 -kind kind

kind controls how the parameter value is set at

graph execution time. Possible values
for kind are keyword, environment, positional,
or implicit (default).

 -locator or -not-locator

o -locator means that the defined value is

a path to a file containing the parameter
value.
o -not-locator (default) means that the
defined value is the parameter value
itself, not a path to a file.

NOTA:

Specifying -locator is equivalent to

specifying File, and specifying -not-
locator is equivalent to
setting Embedded, for a
parameter’s Location attribute in the
GDE.

 -interpret-final-contents — Means that the

defined value is the contents of the file defined
Argument Description

by the parameter value.

 -not-interpret-file-contents — Means that the
defined value is not the contents of a file.

choice-parameter -choice choice ... Creates a choice parameter and its list of possible
choices.
dependent-parameter -dependent c Creates a dependent parameter that depends on the
hoice-parameter specified choice parameter.
dependent-parameter -case choice Sets the string value for the specified case
[interpretation] dependent-value (current choice) of a dependent parameter.
See interpretation above.
common-project-parameter -comm Creates or modifies the common sandbox parameter,
on common-sbox-path [ -relative- and sets its value to the path to the common sandbox.
common ]
If the -relative-common argument is also specified,
sets the relative path to the common sandbox. Storing
relative paths to common sandboxes allows you to
move a set of sandboxes to a new location without
needing to change the common sandbox references.

NOTA:

This argument requires that you use the -

basedir syntax. You cannot use the -path syntax if you
specify this argument. For more information,
see Usage information.
-comment comment-value Adds a comment to the new parameter.
-type type-value Specifies the type to assign to the new parameter.

Valid values are: boolean, collator (that is,

key), dbc, directory, float, layout, metadata, multidirec
tory, string, transform, and url.
-dml-type dml-type-expression Assigns to the new parameter a DML-described type
with the specified DML type expression. You can use
this argument with .pset files, graphs, or plans;
sandbox parameters are not supported.
-remove parameter Removes the specified parameter.
-expression parameter Displays the parameter’s unresolved value.

Usage
In Co>Operating System Version 3.2.5, the -eval argument was deprecated. Use the air
sandbox eval command instead to display the value of a sandbox, graph, plan, dependent
parameter, or expression.

In Co>Operating System Version 3.2.7, the -eval-expression argument was deprecated. Use
the air sandbox eval command instead to display the value of an expression.

The flag values -input and -local correspond to the GDE input and local settings,
respectively, of the parameter Input attribute. Input parameters receive their values as input
from users of the object that the parameters appear in. Local parameters contain values
determined by internal mechanisms or specified by developers; they are not accessible to
users. For more information, see “Parámetros de entrada y locales” in the Guía para
desarrolladores de grafos.
Specifying parameter sets and overriding common project
parameters
-path is preferred

We recommend using -path instead of -basedir to explicitly specify the parameter set you
want to modify. However, if you use the -common argument, you must use the -
basedir syntax.

Overriding common project parameters

To override a parameter in a common project, use the special @ (at sign) notation to
identify the parameter location:

 PARAM@ instructs the software to search from the current project upward through
the chain of included common projects until it encounters a parameter with the
name PARAM in a common project. It applies the override value to that parameter.
 PARAM@COMMON_PROJECT_PARAM instructs the software to override the
parameter PARAM in the common project identified by the
parameter COMMON_PROJECT_PARAM.

For example, the following invocation creates an override value

(/disk1/data/mkatz/xyz) in stdenv/.sandbox.pset that overrides the
parameter AI_ADMIN_PRIVATE_ROOT defined in the common sandbox
identified by the parameter ABENV:

air sandbox parameter -path stdenv/.sandbox.pset

AI_ADMIN_PRIVATE_ROOT@ABENV /disk1/data/mkatz/xyz

Examples
These examples show how to use the air sandbox parameter command with several of its
most popular arguments.
Creating an overridable parameter
To create a parameter named COUNT, set its value, and mark it as overridable, type:

air sandbox parameter COUNT 10 -overridable

Creating a parameter and assigning a type

To create a new DAT parameter in the current sandbox and give it a value, type:

air sandbox parameter DAT '/u/disk1/mysand/dat'

The default interpretation is -pdl. The default flags are -not-required, -

export, -not-overridable, -local, and -implicit.
Creating a choice parameter
To create a new choice parameter named STAGE, set its choices, and set its value, type:

air sandbox parameter STAGE -choice DEV TEST PROD

air sandbox parameter STAGE TEST

Creating a dependent parameter

To create a new dependent parameter named DATA that depends on STAGE, and set the
case values, type:

air sandbox parameter DATA -dependent STAGE

air sandbox parameter DATA -case DEV -dollar '$DEV_MFS'
air sandbox parameter DATA -case TEST -dollar-curly '${TEST_MFS}'
air sandbox parameter DATA -case PROD -literal '/disk1/mfs'

Creating a nested dependent parameter

You can create a parameter, dependent on a sandbox choice parameter, which will get an
automatically generated repository-dependent value.

To create a nested parameter UID that is dependent on the AI_PROMOTION parameter,

enter the following:
air sandbox parameter UID:sandbox -dependent AI_PROMOTION

To then set its value, enter the following:

air sandbox parameter UID:sandbox -case PROD path_to_sandbox_in_prod

Removing a parameter
To remove the COUNT parameter, enter:

air sandbox parameter /disk1/data/mkatz/xyz -remove COUNT

Displaying a parameter’s unresolved value

To display the unresolved value of the DAT parameter, enter the following:

air sandbox parameter -expression DAT

The result might be '$PROJECT_DIR/dat'.

Related topics

 air sandbox eval

air sandbox precompile-graph

Precompiles the DML (record formats and transforms) for the specified graph or input pset.
Precompiling a graph or pset often improves graph startup time. For more information,
see “Precompilar DML” in the Co>Operating System Guía para desarrolladores de grafos.

Before using this command, you must enable precompilation by setting

the AB_PRECOMPILED_DML_DIR configuration variable. We recommend that you set
it as an exported project or graph parameter.

This command creates and saves the precompiled DML but does not run the graph. (If you
do not use this command, the precompiled DML is instead created and saved the first time
you run a new or changed graph.)
For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air sandbox precompile-graph pset-path
[-silent|-verbose]
[-ignore-analysis-level]
[positional-input-value ...]
[input-parm-name value] ...
Argument Description
-silent | -verbose Determines the type of error messages displayed, as follows:

 -silent displays only errors and warnings.

 (default) displays all compiled function names, errors, and
warnings.
 -verbose displays all compilation steps including compiled
function names and their types, parsed DML packages, errors,
and warnings.

-ignore-analysis- Required when the top-level graph’s analysis level is set

level to None or Identify files used only. Temporarily resets the internal
analysis-level value so that the graph can be precompiled.
positional-input- Specifies the value for a graph parameter that is passed to the command
value ... positionally.
-input-parm-name Overrides the default value of -input-parm-name with that specified
value ... by value.
Usage
For Co>Operating System Version 3.2.7 and later, you can no longer run this command on
a graph that is set to run as a micrograph. Instead, you must use
the m_deploy_micrograph utility with the -precompile-dml argument.
Examples
Using an input pset and changing a default value
This example uses an input pset file and changes the value of MY_PARAMETER to 12:

air sandbox precompile-graph my_graph.pset -MY_PARAMETER 12

Displaying verbose output

This example prints all of the compilation steps in addition to any errors or warnings:
air sandbox precompile-graph my_graph.pset -verbose -MY_PARAMETER 12

Related topics

 air sandbox run

 AB_PRECOMPILED_DML_DIR
 Precompilar DML

air sandbox pset

Creates or modifies an input pset (.pset) file, such as a graph or plan instance. Also creates
and modifies parameter set chains. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox pset pset-path
[-prototype path]
[-print-prototypes path]
[-base path]
[-insert-base base-path]
[-replace-base base-path]
[-remove-base]
[-print-bases path]
[-split-runtime [-overwrite-existing]]
Argument Description
pset-path Path to the input pset (.pset) file to create or modify.
-prototype path Path to a prototype parameter set. This can be an input pset (.pset)
file or a file such as a graph or a plan that the specified pset-
path will override.
-print-prototypes path Displays the entire pset chain for a graph or plan that was created
by the -prototype argument. You can use this argument in a
command line script to display the full chain in order to identify
its prototype pset.
-base path Path to a base parameter set. Used for setting up configuration
parameter sets. You can also run it to restore a parameter set chain
should you need to. For more information, see “Fixing an invalid
configuration pset chain”.
-insert-base base-path Modifies the parameter set chain starting at pset-path by inserting
a base parameter set, base-path, as the base of pset-path. When
building up a chain, keep in mind that this argument adds the base
parameter set to the left-hand side of the chain or previous base.
Argument Description
For further explanation and an example,
see “Usage” and “Creating a parameter set chain”.
-replace-base base-path Modifies the parameter set chain starting at pset-path by replacing
the base of pset-path with base-path.
-remove-base Modifies the parameter set chain starting at pset-path by removing
the base of pset-path.
-print-bases path Displays the parameter set chain starting at pset-path.
-split-runtime [-overwri Creates a new .pset file that contains all the runtime-only
te-existing] parameters of the specified pset. The prototype of the
new .pset file is set to the specified pset.

The name of the new .pset file is in the format specified-pset-

name.input.pset. For example, if the pset name specified in pset-
path is G.pset, the newly created pset is called G.input.pset. If
there is already a .pset file with that name, the command warns
you. You can then specify -overwrite-existing to overwrite the
existing .pset file.
Usage
To generate an input pset file, first run this command. Then run air sandbox parameter to
add or modify parameter values.

When a sandbox is first created, it contains .sandbox.pset (the sandbox-based parameter

values set) and .project.pset (the repository-based parameter values set). This is the default
parameter set chain. In this simple case, .project.pset is the base for .sandbox.pset. You can
use the -base, -insert-base, and -replace-base arguments to add, remove, or change the base
parameter values sets in between .sandbox.pset and .project.pset. You can use the -
base argument to fix invalid parameter set chains. See the “Creating a parameter set
chain” and “Modifying a parameter set chain” examples below, as well as “Fixing an
invalid configuration pset chain”.

When using the -print-bases argument to display a parameter set chain, you will find an
input pset’s base file located immediately below it. For example:

air sandbox pset .sandbox.pset -print-bases

.sandbox.pset
one.pset
two.pset
.project.pset

In this example, reading from the repository-side or bottom, the bases in the chain are:

 .project.pset is the base for the two.pset file.

  two.pset is the base for one.pset file.
 one.pset is the base for the sandbox.pset file

For more information about .pset files, see “Archivos pset de entrada” in the Co>Operating
System Guía para desarrolladores de grafos.
Default behavior
If you do not provide any arguments, this command creates an empty file at pset-path.
If pset-path already exists, the command will do nothing.
Fixing an invalid configuration pset chain
A pset chain always starts with .sandbox.pset and must end in .project.pset. By default, the
pset chain is .sandbox/pset->.project.pset, while a configuration pset might look
like .sandbox.pset->config-pset ...->.project.pset. The following is an example of a
configuration pset:

.sandbox.pset
myconfig.pset
.project.pset

The air sandbox pset commands can modify a configuration pset chain. If you accidentally
remove the base with the -remove-base argument, the pset will become invalid. Attempts to
use it with an air sandbox pset command will generate an error similar to the following:

Command Failed: air sandbox pset .sandbox.pset -print-bases

----------------------------------------------------------------
Cannot load format 3 project: '<PWD>/sand'.

The error was:

Configuration psets chain for format 3 project: '<PWD>/sand/.sandbox.pset' is invalid
The last pset of the chain should be <path>/.project.pset.

<PWD>/sand/.sandbox.pset
<PWD>/sand/myconfig.pset

The last pset in the chain <PWD>/sand/myconfig.pset is empty or invalid.

You use the air sandbox pset -base argument to fix an invalid configuration pset. There are
various methods that you can use to fix it — two of which are described here. The first
method is to restore the default chain by making the .project.pset the base of
the .sandbox.pset. The second method is to make the .project.pset the base for the
configuration pset. To get back to the default pset chain, use the -base argument as follows
— shown along with the results:
air sandbox pset .sandbox.pset -base .project.pset
air sandbox pset .sandbox.pset -print-bases
.sandbox.pset
.project.pset

To instead make .project.pset the base of the configuration pset, enter the following:

air sandbox pset myconfig.pset -base .project.pset

air sandbox pset .sandbox.pset -print-bases
.sandbox.pset
myconfig.pset
.project.pset

Examples

In this example, reading from the repository-side or bottom, the bases in the chain are:

 .project.pset is the base for the two.pset file.

 two.pset is the base for one.pset file.
 one.pset is the base for the sandbox.pset file

For more information about .pset files, see “Archivos pset de entrada” in the Co>Operating
System Guía para desarrolladores de grafos.

Creating a graph instance pset

To create a graph instance file called graph1.pset based on the source graph mygraph.mp,
type:

air sandbox pset graph1.pset \

-prototype '$PROJECT_DIR/mp/mygraph.mp'

Using a different pset

To change a sandbox to use the configuration pset dev.pset:

air sandbox pset .sandbox.pset \

-base dev.pset
Creating a parameter set chain
The default parameter set chain looks like this:

air sandbox pset .sandbox.pset -print-bases

.sandbox.pset
.project.pset

To create a parameter set chain with three links one.pset, two.pset, three.pset, insert the left-
most parameter values set first, followed by the set that it will be the base to:

air sandbox pset .sandbox.pset -insert-base three.pset

air sandbox pset .sandbox.pset -insert-base two.pset
air sandbox pset .sandbox.pset -insert-base one.pset

Use the -print-bases argument to display the chain you just created:

air sandbox pset .sandbox.pset -print-bases

.sandbox.pset
one.pset
two.pset
three.pset
.project.pset

Modifying a parameter set chain

To insert a parameter values set between one.pset and two.pset:

air sandbox pset one.pset -insert-base two-and-half.pset

To confirm the change:

air sandbox pset .sandbox.pset -print-bases

.sandbox.pset
one.pset
two-and-half.pset
two.pset
three.pset
.project.pset
This makes two-and-half.pset the new base for one.pset. And two.pset automatically
becomes the new base for the inserted two-and-half.pset.
Removing a base in the chain
To remove two.pset, which due to the action of “Modifying a parameter set chain”, is now
the new base for two-and-half.pset:

air sandbox pset two-and-half.pset -remove-base

air sandbox pset .sandbox.pset -print-bases
.sandbox.pset
one.pset
two-and-half.pset
three.pset
.project.pset

Replacing a base in the chain

To replace two.pset with three.pset in this chain:

air sandbox pset .sandbox.pset -print-bases

.sandbox.pset
one.pset
two-and-half.pset
two.pset
.project.pset

Enter the following command and print out the results to confirm the substitution:

air sandbox pset two-and-half.pset -replace-base three.pset

air sandbox pset .sandbox.pset -print-bases
.sandbox.pset
one.pset
two-and-half.pset
three.pset
.project.pset

air sandbox remove

Removes a file from the sandbox and puts it on a list of files to be removed from the
technical repository at the next checkin. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox remove file [-force] [-no-delete]
Argument Description
file Path to the sandbox. Default is the current working directory.
-force Removes the file even if the file has been modified or exists only in the
sandbox.
-no-delete Prevents the file from being deleted from the sandbox; it locks the file and puts
it on a list of files to be removed at the next checkin.
Usage
The command locks the specified file before removing it from the sandbox. Once the file is
removed, it is assigned a sandbox state of PendingRemove. (For a list of all states, see “File
states”.) The file will be removed from the technical repository the next time you run air
project import or air sandbox import.

You are permitted to remove a file when its state is Current. You can also run air sandbox
remove to mark a file you’ve already removed from the sandbox but haven’t yet marked for
removal from the technical repository.

Specify -force to remove a file that has a state of Modified, PendingAdd, or New. For
example, if the specified file has been modified in the sandbox, you must specify -force; if
you do not, the command fails. Another example: if the specified file is only in the sandbox
(and not in the repository), you must specify -force to remove the file.

You can specify -no-delete to remove a file that has a state of New, PendingAdd,
or Modified.

You cannot remove a file that has a state of Conflict, Stale (cannot be locked), or Ignore, or
that is locked by another user.

This command automatically sets the value of AB_AIR_ROOT based on the repository that
the sandbox is attached to. This means that you can run the command without the -
root argument or without having previously set the value of AB_AIR_ROOT.

If you want to cancel a pending removal, run air sandbox revert on the file. The file is
restored to the sandbox and will not be removed from the repository the next time you
check in the sandbox.

air sandbox replace-subgraph

Replaces instances any top-level instances of a linked subgraph with the specified dynamic
subgraph. By default, this command is not recursive. It replaces only subgraphs that are at
the top-most level of the parent graph; it does not replace linked subgraphs that are nested
inside another subgraph.

To use this command you must have previously converted the linked subgraph to a
dynamic subgraph by using the GDE Convert to Dynamic Subgraph Wizard or a manual
process. For more information, see “Usage”. For information about the arguments common
to all air commands, see “Command-line syntax of air commands”.

PRECAUCIÓN:

Use this command in consultation with Departamento de soporte técnico de Ab Initio. After
running this command, you must test your graphs to ensure that they function as intended.

Syntax
air sandbox replace-subgraph
-graph-path filesystem_path.mp
-path-to-subgraph-source filesystem_path.mp
-implementation-path filesystem_path_impl.mp
[-interface-path filesystem_path.mgi]
[-port-name-change subgraph-port interface-port ...]
[-allow-overrides-of-non-interface-parameters]
[-walk-into-linked-subgraphs]
Argument Description
-graph-path filesystem_path Absolute path to the graph whose linked subgraphs you
want to replace with the specified subgraph.
-path-to-subgraph- Absolute path to the linked subgraph’s source file that you
source filesystem_path.mp want to replace in the sandbox — for
example, $PROJECT_DIR/components/subgr.mp.
-implementation-path filesyste Absolute path to the dynamic subgraph implementation
m_path_impl.mp that you want to use to replace the linked subgraph.
-interface-path filesystem_pat Absolute path to the graph interface that you want to use to
h.mgi replace the linked subgraph. This argument is currently not
necessary to use.
-port-name-change subgraph- Space-separated pairs describing the new current port
port interface-port ... name found in the graph and the existing interface port that
will replace it. For more information, see “Mapping
renamed ports”.
-allow-overrides-of- non- Indicator that preserves any overrides in parameters that do
interface- parameters not exist in the interface. The default is to ignore overrides
of parameters and issue a warning. For more information,
see “Handling subgraph parameters that were not added to
the graph interface”.
 Argument Description
-walk-into-linked- subgraphs Indicator that also modifies nested linked subgraphs. This
method does not modify the source file of the subgraph,
and so it is not recommended for any uses other than
testing. For more information and a discussion of best
practices, see “Updating nested subgraphs”.
Usage
You can use the GDE Convert to Dynamic Subgraph Wizard (or a more laborious manual
process) to convert a graph that is used as a linked subgraph to a dynamic subgraph. Doing
so creates the dynamic subgraph and the graph interface. This air command lets you
convert top-level instances of a given linked subgraph that are found in the specified parent
graph to a graph interface instance.

For more information, see “Subgrafos dinámicos e interfaces de grafo”.

Updating nested subgraphs
By default the air sandbox replace-subgraph command replaces only top-level instances of
a linked subgraph. When nested linked subgraphs are present, the command does not walk
through the nested lower levels. As a best practice, to replace all linked subgraphs in a
graph with a graph interface instance, we recommend that you use the following procedure:

To replace nested linked subgraphs

1. Starting with the innermost linked subgraphs, convert the source graphs to graph
interfaces, and continue these conversions as you move up and outward in the graph
hierarchy.

2. Using the GDE or the air sandbox update command, update any graph that contains
the linked subgraph. This command is recursive.

In addition to this procedure, the air sandbox replace-subgraph command has a -walk-into-
linked-subgraphs argument. When this argument is present, the air command searches for
and replaces any nested subgraphs. However, it does not update the source graph.
Therefore, if you use this argument for your replacement effort and the source graph
changes, you risk losing your changes on update. A case where you might want to use this
argument is in a temporary sandbox to test whether the changes that you intend will work
properly. However, for normal development we recommend that you follow the steps
described in “To replace nested linked subgraphs”.
Mapping renamed ports
When you convert a linked subgraph to a dynamic subgraph — either manually or by using
the Configure Ports page of the GDE wizard — you can change a subgraph’s port names.
You use the -port-name-change argument to indicate how to map the renamed ports to the
graph interface ports. This command maps the port names in the graph interface. For
example, say that a linked subgraph had a port in1. When the linked subgraph was
converted to a dynamic subgraph, the port name was changed to in01, which now appears
in the .mgi file. You can use this argument to indicate the change to make in the parent
graph as follows:

air sandbox replace-subgraph ...

-port-name-change in1 in01

Handling subgraph parameters that were not added to the

graph interface
When you use the Configure Graph Interface Parameters page of the GDE wizard, you can
suppress the presence of a parameter in the resulting graph interface. If you use air sandbox
replace-subgraph to replace a linked subgraph that contains a parameter override for a
parameter that was not included in the graph interface, the air command generates the
following warning:

Warning: by default, we don't preserve overrides of parameters

not present on the interface -- in this case, the parameters overridden are
In subgraph sg:
/user5/my_sand/top_level.mp/linked_sg/proto/sg[commn_input_file_format]These
overrides in the original graph are being ignored.

If you see this warning message, we recommend that you investigate the original parameter
override. There may have been an important reason that the parameter was hidden that you
might want to respond to.

To preserve the parameter overrides that were found in the original graph, use the -allow-
overrides-of-non-interface-parameters argument.
Example
Following is an example that replaces top-level instances of sg.mp linked subgraphs with
the sg_impl.mp dynamic implementation and its sg.mgi graph interface file:

air sandbox replace-subgraph -graph-path /disk1/sand/my_sand/mp/top_level.mp \

-path-to-subgraph-source /disk1/sand/my_sand/components/sg.mp \
-implementation-path /disk1/sand/my_sand/components/sg_impl.mp \
-port-name-change subgr_in1 intface_in1 subgr_out2 intface_out2

The command also renames the interface’s in and out ports.

Related topics
  Subgrafos dinámicos
 Asistente para subgrafos dinámicos

air sandbox resolve

Resolves the conflicts in a sandbox file that was left in an unresolved state by a merge or an
integrate action. You specify whether to use the edited .conflict. file, or the source, target,
or base file version to resolve the conflict. This command is branch-specific. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air sandbox resolve sandbox-file
[ -dry-run ] [ -force ]
[ -take-edited | -take-source | -take-target | -take-base ]
Argument Description
sandbox-file Specifies the file in the current sandbox whose unresolved
conflict state you want fix.
-dry-run Attempts to resolve the conflict based on the file choice that you
supply, but does not write the result to disk.

We recommend that you first use the -dry-run argument to

verify that you will get the results that you want.
-force Resolves the conflict in the manner that you specify — even if
the conflicts or conflict markers in the .conflict. file remain.
-take-edited After you make edits in the .conflict. file, resolves the conflicts
based on your edits. This is the most common choice for
resolving conflicts. For more information on merge rules and
editing the file, see “Usage”.

By default, the command will fail if any conflict markers remain

in the file. To override this behavior, use the -force argument.
-take-source Resolves the conflict by using the source file as the resolved
sandbox file.
-take-target Resolves the conflict by using the target file as the resolved
sandbox file.
-take-base rpath common Resolves the conflict by using the base file as the resolved
-sandbox-dir sandbox file.

This argument is rarely used unless it is necessary to restore

efforts to an earlier state.
Usage
When you try to merge a sandbox file or integrate two repository branches and the action
fails, the merge attempt writes a series of files to the sandbox. These file are written to the
sandbox so that you can edit, view, or compare them to determine how to resolve the
conflict. The files are the following:

 filename.conflict.extension — You can make edits in this file to indicate how to

resolve the conflicts, and then rerun air sandbox resolve with the -take-
edited argument.
 filename._source_.extension — A copy of the source file.
 filename._base_.extension — A copy of the base file.

There is no equivalently named filename._target_.extension file because the target file is

simply the file in the sandbox.

NOTA:

In contrast to when you work with air commands in a shell session, the GDE sandbox view
hides these four files (conflict, source, target, and base) from view. However, when you use
the Resolve dialog or specify a conflict resolution action, the interface selects the
appropriate file and uses it to resolve the conflict. If you use an editor or the Difference
viewer on a file, you will see the file’s full path name — for example, my-
graph._source_.mp.

Editing the .conflict. file

The .conflict. file may contain markers that indicate where the conflicts exist. You can edit
this file to indicate how you want to resolve the conflicts, and then use the air sandbox
resolve command to implement those resolutions.

In the example that follows, the integrate attempt reveals that transform0 in the source
object found on the repository branch is quite different from the target sandbox version and
the common parent base found in the repository. The sandbox and base version differ only
in the number value that is added to in.balance:

Reformat.transform0:
<<<<<<< Source
out.balance:: in.balance;
||||||| Base
out.balance:: if (in.customer_id=="4484401") in.balance + 200.00 else in.balance;
=======
out.balance:: if (in.customer_id=="4484401") in.balance + 400.00 else in.balance;
>>>>>>> Target
Using an editor, you remove the extraneous informational content of the .conflict. file,
leaving the correct resolutions in place. Using the transform0 example shown above, to
choose the transform version from the target file, you would remove all markers and leave
just the valid transform:

Reformat.transform0:
out.balance:: if (in.customer_id=="4484401") in.balance + 400.00 else in.balance;

After editing the .conflict. file, you rerun air sandbox resolve with the -take-
edited argument.

For more information, see “Resolver archivos sin resolver con el software del GDE” in
the Guía para desarrolladores de grafos.
Resolving conflicts when the .conflict. file has no markers
You can have a .conflict. file in your sandbox that doesn’t contain conflict markers. This is
because although changes to components, DML, and the like can be described in the file
with markers, changes that are related to structural differences (such as labels) cannot be
described with markers. When only structural differences are found, the .conflict. won’t
contain markers.

To see descriptions of these types of conflicts, you must consult the graph or pset file to
determine the manual changes that you want to make. The details are found in graph labels.
You can use air sandbox diff commands or GDE-based differencing tools to see how
choosing the source, target, or base file might affect your checkin. To resolve these types of
conflicts, you can either edit one of the files or use the appropriate air sandbox
resolve argument to indicate whether to use the source, target, or base file.

For more information, see “Resolver archivos sin resolver con el software del GDE” in
the Guía para desarrolladores de grafos.
Testing and validating
After you resolve all conflicts in the sandbox, you must test and validate your results. When
you are confident that your application works properly, you can check in the files.
Example
This command performs a dry run to show you the results of using the previously
edited .conflict. file:

air sandbox resolve -dry-run -take-edited

NOTA:
This air command is the equivalent of the GDE Resolve conflicts dialog that is accessible
from the GDE Sandbox View pane.

Related topics

 air project export -merge

 air sandbox export -merge
 air sandbox integrate
 air sandbox merge

air sandbox revert

Reverts one or more sandbox objects to their latest versions in the technical repository. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air sandbox revert
-basedir sandbox
path [...]
-latest
[-no-backup]
[-set name value] ...
[-common rpath common-sandbox-dir]...
[-lock]
Argument Description
-basedir sandbox Path to the sandbox. Default is the current working
directory.
path [...] One or more sandbox-relative paths of objects to be
reverted.
-latest Reverts the object from the latest version in the technical
repository. Reversion from a tag is not supported.
-no-backup Do not create a file with a .bak extension.

By default, the current file is renamed before reversion.

-set name value If a parameters file is reverted, sets the name parameter to
have value.

Optional for overridable parameters.

-common rpath common- If a parameters file is reverted, sets the path to the
Argument Description
sandbox-dir common sandbox.

Required if the project has a common project.

-lock Does not remove the lock on reverted files. If a file is
locked, it is also made writable.
Usage
When you revert a removed file (one whose state is PendingRemove based on having
run air sandbox remove), the file is checked out again. If the file in the sandbox is not
identical to the repository version of the file, the sandbox version will be made a backup
file (with a .bak file type).

When you revert an added file (one whose state is PendingAdd based on having run air
sandbox add), the file state is cleared. The file itself is untouched.

This command automatically sets the value of AB_AIR_ROOT based on the repository that
the sandbox is attached to. This means that you can run the command without the -
root argument or without having previously set the value of AB_AIR_ROOT.

air sandbox rollback

Rolls back an object in a sandbox to an earlier version of the object. If the disk path
specified isn’t a sandbox, the command creates one before copying the object. You can also
roll back a removed object. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox rollback
[project-name]
[-basedir sandbox ]
-version version
[-force]
[-files rpath {rpath...}]
Argument Description
project-name Path to the project associated with the objects that you want to roll back.
-basedir sandbox Path to the sandbox. The default is the current working directory. If you
do not specify a sandbox, the current working directory must be within
an existing sandbox. If you do specify a sandbox and it doesn’t exist, the
command will create it.
-version version The earlier version whose objects you want to roll back to and copy to
Argument Description
the sandbox. Specify a numeric version, a repository-wide tag
(or rtag such as those created by air repository tag), or a date/time.
-force By default, this command does not create an object if there is a conflict
with the objects in the sandbox or repository. Use -force to override this
check and proceed with the rollback. Doing so will overwrite changes
made in the files system if necessary.
-files rpath ... By default, all files in a project are rolled back. To override this
behavior, use this argument to specify individual files. The path that you
specify must be valid as of the current version. For the syntax for rolling
back a removed object, see “Usage”.
Usage
If the command encounters a potential sandbox or repository conflict, the command
generates an error and terminates the operation. To override this behavior (including
overwriting any changes made in the filesystem), use the -force argument.

Because the path that you specify must be valid as of the current version, to roll back to a
previously removed object, enter the following syntax for the value of rpath:

air sandbox rollback -version @1.1.version-number/rpath

In the syntax above, @1.1 denotes domain 1 (which is the root directory) and object 1.
From this starting position, the command uses version-number and rpath to identify the
correct object.

NOTA:

You can use the Technical Repository Management Console (TRMC) Versions tab to
identify the version number of removed objects. For example, you can use the tab to
browse for the repository path of the directory that contains the deletion, or if the user who
deleted the object is known, you can filter the view on the username and search those
versions.

To rollback an object to a technical repository, use air object rollback.

Examples
Rolling back an entire sandbox
To roll back an entire sandbox to version 492, enter the following:
air sandbox rollback -version 492

Creating a new sandbox and rolling back a project to it

To create a new sandbox restore and roll back the project /Projects/Dev4 to it, enter the
following:

air sandbox rollback /Projects/Dev4 -basedir /usr/sand/dev5/restore -version 671

Overriding a conflict
To override any conflict errors with the graph1.mp file, enter the following:

air sandbox rollback /Projects/Dev4 -force -version 671 -files

Projects/sandbox-state-demo/mp/graph1.mp

Restoring a removed object

To roll back a previously removed object, in this case version 492 of graph1.mp, enter the
following:

air sandbox rollback -version @1.1.492/Projects/sandbox-state-demo/mp/graph1.mp

air sandbox run

Runs a graph, graph task, or plan directly from the graph, task, plan file, or input
pset (.pset) file. Displays names and default values of graph or project input parameters, or
dumps the shell script to standard output — without actually running the graph. Also, use
for continuing a failed plan run, rolling back a failed plan run, and debugging a plan.

For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air sandbox run path
 [-resolve-from sandbox]
[-force-job]
[-script-only]
[-force-dynamic]
[-force-fold]
[-help-inputs]
[-yarn-estimate-only]
[positional-input-value ...]
[-input-parm-name value] ...
[plan-recovery-option]
[plan-debugging-options]
[other-plan-options]
Argument Description
path Path to a graph (.mp) file, graph task (.task), plan (.plan), plan recovery file
(.rec) or input pset (.pset) file for a graph, task, or plan.
-resolve-from Runs the pset path as though it was located in the specified sandbox.
sandbox
-force-job By default, does not create a job if the graph has been modified since the
last checkin or checkout. Use -force-job to override this check.
-script-only Dumps the generated Korn shell script to stdout but does not actually run
the graph.
-force-dynamic Uses dynamic script generation even if the graph settings are set to GDE
1.13-compatible script generation.
-force-fold Uses dynamic script generation (in Version 2.14) even if the graph settings
are set to GDE 1.13-compatible script generation. If you specify -force-
fold, dynamic script generation is automatically assumed and the
Co>Operating System component folding feature is enabled. For more
information, see “Agrupación de componentes” in the Co>Operating
System Guía para desarrolladores de grafos.
-help-inputs Displays the names and descriptions (if any) for all graph and project input
parameters but does not actually run the graph. Also displays command
syntax.
-yarn-estimate- Displays information about the YARN containers that will be requested in
only order to run the job under YARN. Does not actually run the job. To use this
argument, AB_CONTAINER_PROVIDER must be set to yarn, and YARN
must be accessible from the current host.

For more information about how YARN container requests are calculated,
see “Integrating with YARN on a Hadoop cluster” in the Co>Operating
System Hadoop Integration Guide.
positional- Value for a graph input parameter that is passed positionally.
Argument Description
input-value
-input-parm- Overrides the default value of parameter input-parm-
name value name with value. Valid only for parameters that have a Kind setting
of Keyword. You can specify multiple pairs of input parameter names and
values.
plan-recovery- Applies only to plans and is limited to one of the following recovery
option means:

 -remove-all removes the last incomplete job.

 -rollback-failures rolls back failed tasks and leaves the job for later
restart or removal.
 -rollback-failures-and-remove rolls back failed tasks and removes
the job.
 -continue-from-rec-file path rolls back the failed tasks of the plan
specified by the .rec file path and then continues the plan execution.

plan- Applies only to plans and should be used only if you intend to connect the
debugging- plan debugger to the running plan with the plan-debugger recfile command.
options
 path_in_plan specifies any element of a plan, such as a task,
method, subplan, or iteration, where / is the top-level plan.
 -break-before path_in_plan stops execution of the element before it
starts.
 -break-in path_in_plan stops execution of one of the following: a
method just before it spawns its script or executable; a task before it
starts its perform method; or a plan, subplan, or iteration before it
starts its body.
 -break-after path_in_plan stops execution of the element after it
finishes.
 -break-on-failure stops execution of every perform method that
fails.

For more information on using these options, see Debugging a plan from
the command line in the Conduct>It Guide and Reference.
other-plan- Miscellaneous parameters for plans. You may specify none or any number
options of these:

 -job-id id is a custom (user-defined) job ID that overrides the

automatically assigned ID. Must be specified to run concurrent
instances of a plan.
 -validate-only validates a plan and reports warnings and errors but
doesn’t run the plan.
 -skip-task task-name disables the specified task for this run. The
task must have failed or must not have been started in a previous
Argument Description
run. Otherwise, this argument has no effect.

You may specify this clause more than once. Express task-name as
a fully qualified name — for example:

/subplan/subsubplan/task-name

 -skip-tasks-in-file filename disables the tasks listed in the specified

file for this run. Separate task names in filename with newlines.
 -wait-for-restarts ensures that the containing plan or subplan
continues running when tasks fail, which allows for task restart.
 -wait-for-restarts-until-idle ensures that the containing plan or
subplan continues running when tasks fail, until the plan or subplan
finishes all other work and is now waiting for failed tasks to be
restarted.

Usage
This command is an alternative to running the script deployed from the GDE. The script is
deleted after the graph runs.

See the table below to find help topics relevant to air sandbox run:

Subject of interest Help topic to see

Plan recovery options About plan recovery options
Invoking a graph with air sandbox run Ejecutar un grafo desde la línea de comandos
Component folding Agrupación de componentes
Dynamic script generation Generación dinámica de scripts

Improving performance
If you need to improve performance at graph startup, consider using the air sandbox
precompile-graph command instead.
Example
To see a list of the graph and project input parameters to mygraph.mp, specify -help-inputs:

air sandbox run temp/mp/mygraph.mp -help-inputs

The output shows the parameter names and a brief description:

Keyword graph input parameters:
-REGION Sales region (0-9)
-FILTER_CONDITION Should we filter out any records
-OVERRIDDEN_AND_SHADOWED

Keyword project input parameters:

-CLIENT_KEYWORD_FORMAL

Obsolete arguments
As of Version 3.0.5, the -rollback-all argument is obsolete.
Alias
The alias for this command is ab-run.

air sandbox search parameter

Searches one or more paths in the indicated file system for a given parameter name. Based
on the arguments that you supply, the command can return parameter declarations and
definitions, as well as references to the parameter. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox search parameter path [sandbox-path ...] parameter-name
[-declaration-pset decl-pset]
[-decl -def -ref -all]
[-required]
[-m]
Argument Description
path Specifies one or more paths that you want to search. If the value of path is a
directory — rather than a sandbox — the command recursively searches all
objects in path or its subdirectories.
parameter- Specifies the name of the parameter that you want to search for. This
name argument must be placed after all path specifications.
-declaration- Filters the results to show only the objects that match the parameter name’s
pset declaration in the specified pset. When the argument is included, the
command ignores definitions, references, and so on that have the same name
but that are from a different declaration.
-decl -def -ref Limits or filters the results. Use one or more of these arguments as follows:
-all
 -decl — Displays any declarations of parameter-name.
Argument Description
 -def — Displays any definitions of parameter-name.
 -ref — Displays any references to parameter-name.
 -all — The default. Displays any matching declarations, definitions,
or references. This is the equivalent to setting -decl -def -ref.

-required Also searches for matches in all files that are required by sandbox-path. This
argument is equivalent to the air sandbox get-required-files path command.
-m Displays any results in a concise machine-readable format without headers.
You can find the DML that describes this output
at $AB_HOME/include/search_parameters.dml.
Usage
When you run the air sandbox search parameter command, note the following:

 Matching is case-sensitive for both the parameter name and the optional pset.
 If no matches are found, the command generates a warning that no matches were
found.
 If the sandbox-path specifies a directory and the command finds no matching
graphs, plans, psets, and so on, then the command issues a warning that no objects
were found.

Examples
In the following example, the air command searches for the FOO parameter in all files
under the /u/disk1/mysand/hadoop sandbox:

air sandbox search parameter /u/disk1/mysand/hadoop FOO

In the following example, the air command searches for the FOO parameter in a single
graph:

air sandbox search parameter /u/disk1/mysand/mp/one_graph.mp FOO

In the following example, the air command searches for the FOO parameter in a single
graph, as well as in all files that graph requires. It filters the result to show only matches
that are references:

air sandbox search parameter /u/disk1/mysand/mp/one_graph.mp FOO -required -ref

In the following example, the air command searches the specified sandbox and all required
files for references to the BAR parameter that are declared in .project.pset:

air sandbox search parameter /u/disk1/mysand/hadoop BAR -required -ref -declpset

/u/disk1/mysand/ hadoop/.project.pset

Related topics

 air object search grep

 air object search parameter

air sandbox show-common

Displays a list of the specified sandbox's common sandboxes. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox show-common [sandbox-path] [-exact] [-exact [-param]]
Argument Description
sandbox-path Path to the sandbox. If not specified, defaults to the current directory.
-exact Lists only those common sandboxes explicitly referenced by sandbox-
path.
-exact [-param] Lists only those common sandboxes explicitly referenced by sandbox-
path. If -param is specified with -exact, displays the common sandbox
path followed by the parameter name associated with the common
sandbox.
Usage
The common sandbox paths are listed one per line.

If -param is specified with -exact, the common sandbox path is followed by a tab and then
the sandbox’s associated parameter name.

Sandboxes are listed in the order in which they would need to be checked out. Sandboxes
later in the list may depend on sandboxes earlier in the list.

air sandbox status

Reports on the state of an object in a checked-in sandbox with respect to its associated
technical repository project. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox status fspath
Argumen
Description
t
fspath Full filesystem pathname to the object.
Usage
Sandbox state is one of the following:

State Description
Current The technical repository and the filesystem are in sync.
Stale The technical repository contains changes that are not present in the filesystem.
Modified The sandbox contains changes that are not present in the technical repository.
Conflict The sandbox and the technical repository have both been changed.
Unresolved The sandbox contains a conflict file, indicating an unresolved conflict.
Ignore The file is not subject to source code control.
Removed The file has been marked for removal but not yet removed from the sandbox.
New The file exists in the sandbox but has not been checked in to the technical
repository.
Error Status information could not be obtained, due to some system or permissions
error.

This command automatically sets the value of AB_AIR_ROOT based on the repository that
the sandbox is attached to. This means that you can run the command without the -
root argument or without having previously set the value of AB_AIR_ROOT.

air sandbox update

Takes a reusable component and updates every graph that uses (contains) it, as well as
graphs that use those graphs, recursively. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.

The actual graphs to be updated can be checked out from a technical repository or can
reside in a sandbox that is not associated with a repository.

ADVERTENCIA:

This command modifies the components in a graph and linked subgraphs. Those changes
may produce significant or unexpected changes. In addition, updates are recursive. We
recommend that you run this command with the -dry-run argument to view any warnings
and errors. Then after updating, test your graphs to ensure they function as intended.

Syntax
air sandbox update
path ...
{ -from component-path... | -all | -user-defined | -top-level-ai-
components-only }
[ -interface ]
[ -no-lock ]
[ -continue ]
[ -force ]
[ -dry-run ]
[ -no-check ]
[ -verbose ]
Argument Description
path ... An absolute or relative path to a graph in a sandbox (for
example, /disk1/sandbox1/mp/graph.mp) or an entire sandbox (for
example, /disk1/sandbox1). If you specify a sandbox, all graphs in
the sandbox are updated.

You can specify multiple graphs and/or sandboxes. Use a space to

separate path values.
-from component- You must choose one of the following:
path ... | -all | -user-
defined | -top-level-ai-  -from component-path — Specifies one or more paths to
components-only the source of the components that have been changed. All
uses of these components will be updated recursively.
 -all — Specifies that all components in every graph and
the graph itself will be updated recursively, including Ab
Initio components and connectors.
 -user-defined — Behaves the same as -all, except that
Ab Initio components and connectors are not updated.
 -top-level-ai-components-only — Updates only those
components in a graph that are Ab Initio components and
that are not contained in a linked subgraph.

-interface Updates dynamic subgraph implementations to conform to their

interfaces. This command is the equivalent to the GDE menu
item Edit > Dynamic Subgraph > Update to Match Graph
Interface.

NOTA:

This argument is required if you do not specify one of the

arguments in the preceding row.
Argument Description
-no-lock By default, the command tries to lock a checked-out graph that
needs updating and has not been locked. Specify -no-lock to
suppress this behavior.

NOTA:

The graph does not need to be checked out or associated with a

project in a technical repository.
-continue By default, when an error occurs, the command stops and does
not write any changes. If the -continue argument is specified, the
command writes all updated components that are not affected
(directly or indirectly) by any error.
-force By default, the command writes each updated graph in the format
in which it was read. This may not be possible when the graph has
been updated from a component that uses features in a newer
format. In such a case, the graph cannot be written, and an error
will be reported.

To override this behavior, specify the -force argument. The

command still attempts to write the graph in its original format,
but if this is not possible, it will write the graph in the format of
the current Co>Operating System version.
-dry-run Strongly recommended. All graphs are updated in memory, but by
default the results are not written to the filesystem. Use this
argument to see which errors and warnings are produced.
-no-check By default, the command does not update any component that it
considers up to date. To override the default behavior, specify
the -no-check argument. The command will then recursively
update all components specified by the -from, -all, or -user-
defined argument.
-verbose Reports every action taken by the command. If omitted, reports
only significant actions, such as components that were updated.
Usage
With each invocation, the air sandbox update command updates graphs checked out from
the technical repository or graphs in one or more sandboxes. It reports on every graph that
it updates.

We recommend that you lock all checked-out graphs. If a graph that needs to be updated
has not been locked and if the command cannot lock the graph or is instructed not to try to
lock it (with the -no-lock argument), the graph is not updated and the command generates
an error.
Recursion example
The following example shows how the command performs recursive updates. Assume that
you have specified three sandboxes.

The following figure shows the graphs and their sandbox sources. graphA is the containing
graph and has three reusable subgraphs: graphB, graphX2, and graphC.

Note that graphX actually occurs three times in graphA; it is the source
of graphX1 in graphB, graphX2 in graphA, and graphX3 in graphC.

Now suppose you modify graphX and want to update all graphs that use graphX, directly or
indirectly. You would invoke the command as follows:

air sandbox update \

/disk1/jdoe/work/sandbox1/mp/graphA.mp \
-from /disk1/jdoe/work/sandbox3/mp/graphX.mp

This command would:

1. Update graphB with the new version of graphX (which has the
name graphX1 inside graphB) and save the new version to the
file /disk1/jdoe/work/sandbox1/mp/graphB.mp
2. Update graphC with the new version of graphX (which has the
name graphX3 inside graphC) and save the new version to the
file /disk1/jdoe/work/sandbox2/mp/graphC.mp
3. Update graphA with the new versions of graphB, graphX2 (based on graphX),
and graphC and save the new version to the
file /disk1/jdoe/work/sandbox1/mp/graphA.mp
Note that even though graphB and graphC were not specified at the command line, they are
updated and written to the filesystem because they use the specified modified graphX.

Warnings and errors

Suppose that graphC was checked out from a technical repository but not locked and that it
could not be locked by air sandbox update, either because it was invoked with the -no-
lock argument or because it was locked by another user. In this case the command would
issue an error and would not update anything, even if it could have updated graphB.
Use the -dry-run argument
To see exactly what air sandbox update will do, we strongly recommend that you run the
command initially with the -dry-run argument. That way you can make corrections based
on the warnings and errors that the command reports before you actually do the update.

air sandbox validate-graph

Depending on the arguments, either validates a graph or parameter set or performs
dependency analysis on it. By default, this command validates dynamic subgraph
interfaces. This command can measure a graph’s complexity or whether it follows user-
defined graph development best practices. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air sandbox validate-graph path [ -continuous ]
[ [ -analysis [ -eme ] [ -field-warning ] ] |
[ -complexity | -complexity-details ]
[ -all ]
[ -rollup-errors | -m | -legacy-errors ]
[ -no-validation-extensions ]
[ -report-suppressions ]
[ -show-suppressed-validation-extension-errors ]
[ -interface-only ]
Argument Description
path Specifies a path to a graph or a parameter set in a sandbox.

 If you specify a graph name without the path, the

command defaults to the current directory.
 If you specify a parameter set, the command runs the
graph associated with the parameter set using the
Argument Description
values in the parameter set.

This argument must appear first. The optional arguments can

appear in any order.
-continuous Indicates a continuous graph. If you do not specify this
argument, then by default the command assumes that the
graph is a batch graph. This argument validates continuous
graphs rather than DML. It does not perform dependency
analysis unless you combine it with the -field-
warning argument. Note that this argument combination is
the only case where the air sandbox validate-
graph command performs both validation and dependency
analysis.
-analysis [-eme] [-field- Performs dependency analysis on the graph. You can specify
warning] the -analysis argument with the following optional
arguments:

 -eme — Performs a dry run of the dependency

analysis within the context of the technical
repository. It is similar to the output from using
the air sandbox import -dry-run -
validation arguments.
 -field-warning — Warns when a component or
transform causes dependency analysis to assume that
all the output fields depend on all the input fields.

-complexity | -complexity- Measures the graph’s complexity based on one of the

details following arguments:

 -complexity — Displays the overall complexity of

the graph.
 -complexity-details — Displays the measure of
overall complexity and topological complexity of the
graph, as well as the complexity of each component
and its transform functions.

For more information, see “Graph complexity” below.

-all Default. Performs a complete set of validation checks. You
can specify the -continuous or -analysis arguments if needed.
-rollup-errors | -m | -legacy- Controls the presentation of validation warnings. You can
errors choose one:

 -rollup-errors — Groups errors by error message.

 -m — Presents error messages to stdout in a format
Argument Description
that can be processed programmatically (by an Ab
Initio graph, for example). For more information on
the record format, see “Usage” below.
 -legacy-errors (default) — Presents error messages
individually.

-no-validation-extensions Overrides the default behavior and doesn’t run the user-
defined validation tests and aggregation routines. For more
information on the default behavior, see “Usage” below.
-report-suppressions Displays to stdout all validation checks that have been
suppressed — including user-defined validation extension
routines. This argument doesn’t perform any validation; it
only returns the names of any suppressed validation checks.
This argument supersedes other validation switches.

For more information, see the “Cuadro de diálogo Errores

suprimidos” in the GDE Dialog Reference.
-show-suppressed-validation- Displays to stdout all user-defined validation extension
extension-errors checks that have been suppressed from error reporting.
Unlike the -report-suppressions argument, this argument
performs validation checks and returns any errors. It
does not display the results of regular suppressed errors.
-interface-only Validates the consistency of dynamic subgraph interfaces for
the specified graph and any components in it. When you
specify this argument, the command only validates
interfaces. Interfaces are validated by default. Use this
command to prevent spurious warnings such as those that
can be generated by interface implementations that rely on
propagated metadata.
Usage
Depending on the arguments used, the air sandbox validate-graph command measures
either the degree of validation, analysis, or complexity of a graph.

Default behavior

By default, this air command runs graph validation against the graph or pset in the sandbox
specified by path. In addition, the default command runs any user-defined validation tests
and aggregation routines. The test file test-file .xfr, which describes the routines in DML,
must be located in a /xfr/vld/ directory placed in either a sandbox or common project.

To work, the user-defined validation routines must previously have been defined in an
activation file ../xfr/vld/activation-file.act. This feature is applied throughout the project
hierarchy.
Examples of simple tests include checking for hardcoded parameters and checking
component order to ensure best practices (for example, do not place
a REPLICATE component after a INPUT FILE component). An example of an aggregation
test is a test that looks for REFORMAT components that serve no purpose and can be
removed.

For more information on how to create and enable custom validation, see “Validación de
grafos” in the Co>Operating System Guía para desarrolladores de grafos.

Output messages

If validation succeeds, the command returns 0. If validation succeeds but errors or warnings
were found, the command returns 2. If validation fails, the command returns 1. For
example, validation can fail if the specified path isn’t a graph. If you specify the -
m argument, errors are sent to stdout instead of stderr, and the command always returns 0.

If this command returns errors for a graph, the graph won’t run. You must correct any
errors identified in the error messages. For example, if you use an INPUT FILE component
instead of a valid subscriber to input data into a continuous graph, the command displays an
error message identifying the invalid component that you must replace.

A graph that returns only warnings still runs, but the warning messages identify potential
difficulties. For example, the command displays a warning message if you set
the commit_level parameter for JMS SUBSCRIBE to non_transactional. This setting may
result in data loss or duplication of records, and you should use it only in nonrecoverable
graphs.

If you want to process error messages programmatically, the DML record format for the
output of the -m argument can be found at $AB_HOME/include/analysis_warning.dml.

The -parsable-errors argument has been deprecated. Use the -m argument instead.

The -strict argument has been deprecated. Improvements to the command make it
unnecessary.

For information about how to create valid continuous graphs, see “Introducción a los grafos
continuos” in the Manual del usuario de Continuous Flows.
Graph complexity
Graph complexity is computed by examining the topology of the graph (the number and
type of flows, the number of inputs and outputs, and the number of possible independent
data flow paths through the graph), the components used, and the complexity of the graph's
DML transform functions. The resulting number is placed on a logarithmic scale.

In general, a graph with a complexity of 60 or greater should be considered a very complex

graph, and a graph with a complexity of 75 or greater is an extremely complex graph.
A graph that cannot be analyzed (either due to errors or due to the setting of analysis_level)
reports a complexity of 0.

For more information about graph complexity, see “Evaluar la complejidad de grafos” in
the Co>Operating System Guía para desarrolladores de grafos.
Complexity example
To determine the complexity of wsCalc.mp, run the following command:

air sandbox validate-graph /disk3/sand/mp/wsCalc.mp -complexity-details

An excerpt of the output (below) shows, for example, that the overall complexity of the
first graph is 49, while the topological complexity (relating to graph layout and flows)
is 22. The integers following each graph’s six components indicate the component’s
inherent complexity and the complexity of its transform functions, respectively:

/disk3/sand/mp/wsCalc.mp 49 Topological: 22
Bad_DML_to_RPC_Request 2 7
Gather 0 0
Partition_by_SOAP_Action 1 0
RPC_Publish 5 0
RPC_Subscribe 5 0
SOAP_Operation_add.Business_Logic.Gather 0 0

air system commands

The air system commands install, administer, and display system objects in the technical
repository and administer all repository user accounts.

The following table summarizes the air system commands. For information about command
syntax, see “Command-line syntax of air commands”.

Command Description
air system configure- Configures the technical repository to use the Ab Initio
auth Authorization Gateway to control the assignment of users to
groups.
air system export Copies all technical repository user accounts and groups to a binary
users-and-groups file, for export to another technical repository.
air system group add- Adds a group to another group.
group
air system group add- Adds the specified user to the specified group.
user
Command Description
air system group Changes the name of the specified group.
change-name
air system group create Creates a group with the specified name.
air system group delete Deletes the group with the specified name.
air system group Removes a group from its container group.
remove-group
air system group Removes the specified user from the specified group.
remove-user
air system group show Displays a list of groups, optionally showing their membership.
air system import Creates the user accounts on the target technical repository from
users-and-groups the specified export file.
air system install Builds or rebuilds the built-in categories.
categories
air system install Updates the technical repository’s component definitions.
components
air system install Updates the meta model in the technical repository.
schema
air system show Displays schema differences between the current software version
schema and the schema that is stored in the Technical Repository.
air system show Shows the current schema version used by the client software.
version
air system user Changes the username for the specified user.
change-name
air system user Specifies a new clear password for the user.
change-password
air system user create Creates an account for the specified user.
air system user default- Sets the group to be used when the specified user creates new
group objects.
air system user delete Removes the user from the technical repository.
air system user disable Disables the account of the specified user.
air system user enable Enables the disabled account of the specified user.
air system user show Displays information about the account of a given user or of all
users.
air system user umask Sets the umask for the specified user.

air system configure-auth

Configures the technical repository to use the Ab Initio Authorization Gateway to control
the assignment of users to groups. When this command is used, you continue to maintain
groups, subgroups, and permissions on objects in the technical repository — the technical
repository integration does not use the Authorization Gateway for authentication. The
technical repository groups and equivalent Authorization Gateway roles are synchronized.
For information on synchronization, see “Synchronization between the Technical
Repository and the Authorization Gateway” in the Technical Repository Administrator’s
Guide. This command is repository-wide. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.

NOTA:

Before using this command, we strongly suggest that you familiarize yourself with the
topic “Using the Authorization Gateway” in the Technical Repository Administrator’s
Guide. It describes shared software terms, best practices, how to migrate an existing
technical repository, and how synchronization happens between the technical repository
and the Authorization Gateway. For more information on the Authorization Gateway,
see ????.

Syntax
air system configure-auth
[-enable | -disable]
[-username AG-user]
[-password AG-password | -prompt-password]
[-url AG-URL]
[-published-eme tr-name]
[-update-interval seconds]
[-update-bulk-interval seconds]
[-show]
Argument Description
-enable | -disable Enables or disables the use of the Authorization Gateway by the
technical repository. Assigns groups to users from mappings entered
in the Authorization Gateway. Enter one of the following:

 -enable — Configures the Authorization Gateway based on

the other arguments.
 -disable — Disables the current configuration.

-username AG-user Specifies the name of an Authorization Gateway administrator who

can update the Authorization Gateway database and who will be
associated with this technical repository configuration.
-password AG- Required with -username. Specifies whether the command will
password | -prompt- prompt for the administrator’s password on the command line (the
password default) or whether it will be provided inline in a script.
Argument Description

Enter one of the following:

 -password — Specifies the password of the Authorization

Gateway administrator. The password is entered inline for use
in scripts.
 -prompt-password — Prompts the user for the password of the
Authorization Gateway administrator at the command line.
This is more secure than using the -password argument,
because the password is not visible in the command line.

-url Specifies the URL to the Authorization Gateway that the repository
will use to manage the configuration.

NOTA:

In a single-sign-on (SSO) authentication environment, this may not

be the URL that a user would enter — particularly if that user is
behind a different firewall.
-published-eme tr- Specifies the name by which the repository will be known to the
name Authorization Gateway. The Authorization Gateway uses this
information to identify its roles with this particular product instance.
-update-interval sec Specifies, in seconds, the Authorization Gateway update interval.
onds When a user connects to the repository, the user’s groups are fetched
from the Authorization Gateway and stored in the repository if they
haven’t been fetched previously within the last interval. This setting
applies separately to each user. The default is 60 seconds.
-update-bulk- Specifies, in seconds, the Authorization Gateway update interval for a
interval seconds bulk update. The bulk update contains role information for all users
in the Authorization Gateway who have roles that correspond to
groups in the repository.

When a user connects to the repository, all user group information is

fetched from the Authorization Gateway and stored in the repository,
if the groups haven’t been fetched previously within the last interval.
This setting applies separately to each user. The default
is 600 seconds. For more information, see “Usage”.
-show Displays the current configuration settings, with the exception of the
password, to standard output. This is the default if you do not supply
any arguments.
Usage
This command lets you enable and then configure how the technical repository connects to
the specified Authorization Gateway. Instead of using air commands or the TRMC to
associate technical repository users with groups, you, an administrator, or your company’s
security personnel use the Authorization Gateway. In the Authorization Gateway, technical
repository groups become roles — a set of privileges that are granted to users. You still use
air commands or the TRMC to create groups and add groups to other groups, or rarely to
add users (if necessary). But you cannot use these methods to map users to groups or
remove users from groups. You must use the Authorization Gateway to assign users and
groups/roles. The repository is the system of record for technical repository groups; the
Authorization Gateway is the system of record for assigning users.

If the Authorization Gateway is enabled, the air system group add-user and air system
group remove-user commands and their TRMC equivalents become disabled. If you try to
issue these air commands, they will display an error message.

For more usage information, see “Using the Authorization Gateway” in the Technical
Repository Administrator’s Guide.
Synchronization
When a repository action is issued (that is, an air command, TRMC action, or Technical
Repository Web Interface log in), the technical repository copies its list of groups and
subgroups to the Authorization Gateway. The repository in turn retrieves and stores
information from the Authorization Gateway about which users are in which groups. This
ensures that the Authorization Gateway groups are synchronized with the technical
repository groups. Specifically, the interface requests and creates a report from the
Authorization Gateway that contains all Authorization Gateway users, their groups for this
technical repository instance, and their roles. If a user is in the report, and thus the
Authorization Gateway, but not in the technical repository, the synchronization process
adds the user and its related group membership. If a user is in the technical repository but
not in the report, then the synchronization removes its repository group membership.

The -update-interval argument regulates how often the Authorization Gateway is accessed
to update an individual user’s roles. For more information on how and when
synchronization is initiated, see “Synchronization between the Technical Repository and
the Authorization Gateway” in the Technical Repository Administrator’s Guide.

The -update-bulk-interval argument periodically retrieves all Authorization Gateway users

with their roles (called groups in the repository) from a specific Authorization Gateway
instance. During synchronization, if a retrieved user is found in the repository, the user’s
group membership is updated to match the Authorization Gateway. If the retrieved user is
not found in the repository, then the user is added to the repository along with its group
membership. If the user was not found in the Authorization Gateway but if found in the
technical repository, then the synchronization process removed that user and their
repository group membership from the repository. This synchronization process is
performed on all users found in the Authorization Gateway.
Specifying command arguments
Only the -update-interval , -update-bulk-interval , and -show arguments are truly optional.
However, you can issue any of the other arguments separately. For example, you can
preconfigure your technical repository and Authorization Gateway connection using any of
the arguments except the -enable argument. When you are ready to switch security to the
Authorization Gateway, you can issue air system configure-auth enable. At this point, all
the required arguments must have been previously set in order for enable to work.

Additionally, you can issue just the -urlargument if the Authorization Gateway path has
changed but you want to keep the other configuration settings.
Update interval arguments
When a user connects to the Authorization Gateway, the interface first checks that single
user against the Authorization Gateway using the -update-interval setting and the last stored
update time. The interface next performs the bulk check using the -update-bulk-
interval setting. Every user in the Authorization Gateway can have an update interval value;
however, there is only one update interval value for the bulk option. We recommend setting
the -update-bulk-interval argument value higher than -update-interval so that the command
doesn’t perform its bulk Authorization Gateway operation too often.

If a user connects to the Authorization Gateway who does not have a user record in the
technical repository, the Authorization Gateway processes the request immediately, without
waiting for the time interval set by the -update-interval argument.
Examples
This example enables a connection to an Authorization Gateway found on the
machine mhub-linux1

air system configure-auth -enable -url http://mhub-linux1:8080/AuthGateway

The following example shows the output of the -show argument, whose use on the
command line is optional. Previous to running it, an error had been generated. This
argument displays any prior errors in the output for informational purposes:

air system configure-auth -show

The Authorization Gateway has error:

Gateway failed:The Ab Initio Authorization Gateway reported an error:
RPC call returned error code of 302
The Ab Initio Authorization Gateway reported an error: No XML response.
Authorization Gateway configuration settings:
Enabled: False
Gateway Username: NOT
Password: (Configured but not shown)
URL: http://mhub-linux1:8080/AuthGateway
Published Technical Repository: test-EME
user sync delay: 1 second(s)

air system export users-and-groups

Copies all technical repository user accounts and groups to a binary file, for export to
another technical repository. This command is repository-wide. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air system export users-and-groups filename
Argument Description
filename Pathname of the file to which the user accounts and groups are written. Use - to
have the data written to standard output.
Usage
This file format is intended solely for subsequent import into another technical repository
using the inverse command air system export users-and-groups.

Related topics

 air system import users-and-groups

air system group add-group

Adds a group to another group. This command is repository-wide. For information about
the arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air system group add-group [-q] child-group parent-group
Argument Description
-q Suppresses error if the child group or the parent group do not exist.
child-group Name of an existing group to be added to another group.
parent-group Name of an existing group to which you want to add the group child-group.
Usage
An error results if either group does not exist.

Users in child-group are granted the permissions of parent-group, and they retain the
permissions of child-group. For more information on group permissions, see “Users and
groups” in the Technical Repository Administrator’s Guide.
Example
To add the Dev group to the Employees group, type:

air system group add-group Dev Employees

air system group add-user

Adds a user to a group. This command is repository-wide. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.

NOTA:

This air command is disabled if the Authorization Gateway is used for managing the
assignment of users to groups. In this case, you must use the Authorization Gateway to add
users to groups. For more information, see “Using the Authorization Gateway” in
the Technical Repository Administrator’s Guide.

Syntax
air system group add-user [-q] username group-name
Argument Description
-q Suppresses any errors if the user already exists in the group.
username Valid username.
group-name Name of an existing group.
Usage
The new group member is granted the access permissions of the group.
Example
To add user mkatz to the Managers group, type:
air system group add-user mkatz Managers

Related topics

 air system group remove-user

air system group change-name

Changes the name of the specified group. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air system group change-name group-name new-group-name
Argument Description
group-name Name of an existing group.
new-group-name New name for specified group group-name.
Usage
The permissions, membership, and other information associated with the gid (group ID) are
not modified.

air system group create

Creates a user group with the specified name. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air system group create group-name[-q] [-dry-run] [-gid]
Argument Description
group- Name for the new group.
name
-q No error is generated if the group already exists with a matching gid (group
ID).
-dry-run If this argument is specified, the operation does not actually take place; instead,
the technical repository displays an analysis of the effect of issuing the
command.
-gid If specified, requests that the group be granted this gid (group ID). If the gid is
in use or is over 268435455, the command displays an error. If not specified,
the technical repository assigns a gid.
Example
To create the Managers group, type:

air system group create Managers

air system group delete

Deletes a group from the technical repository. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air system group delete [-q] group-name
Argument Description
-q Suppresses error if the group does not exist.
group-name Name of the group to delete.
Usage
The gid (group ID) remains unassociated with any name. The command removes all users
from the specified group.

air system group remove-group

Removes a group from its container group. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air system group remove-group [-q] child-group parent-group
Argument Description
-q Suppresses error if the group is not in the container group.
child-group Name of the group to remove from another group.
parent-group Name of an existing group that contains child-group.
Usage
If child-group does not exist or is not a constituent group of parent-group, or if parent-
group does not exist, an error occurs.
Example
Assume that the Employees group comprises Dev, Doc, HR, and Finance. To
remove Dev from the Employees group, type:

air system group remove-group Dev Employees

air system group remove-user

Removes a user from a group. This command is repository-wide. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.

NOTA:

This air command is disabled if the Authorization Gateway is used for managing the
assignment of users to groups. In this case, you must use the Authorization Gateway to add
users to groups. For more information, see “Using the Authorization Gateway” in
the Technical Repository Administrator’s Guide.

Syntax
air system group remove-user [-q] username group-name
Argument Description
-q Suppresses any errors if the user is not in the group.
username Name of the account of the user to remove.
group-name Name of an existing group.
Usage
This command does not remove or disable the user’s account; it just removes the
permissions granted to the user by virtue of former membership in the specified group.

Related topics

 air system group add-user



air system group show

Displays a list of one or more groups, optionally showing the membership of the groups.
This command is repository-wide. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air system group show {group-name | -all} -verbose
Argument Description
group-name| -Choose one of the following:
all
 group-namemeans the name of an existing group.
 -allmeans a list of all groups.

-verbose Shows the membership of the group or groups.

NOTA:

If you are using the Authorization Gateway to manage user to group

assignments, the -verboseargument does not display user membership
information.
Example
Assume that the cats group contains users felix, tabitha, and sheba and that the dogs group
contains fido, lassie, and cleo. Both groups belongs to the animals group. To see the
membership of all groups, type:

air system group show -all -verbose

The output would be as follows:

group
-----
animals
contains: cats dogs
cats
is in: animals
contains: felix tabitha sheba
dogs
is in: animals
contains: fido lassie cleo

air system import users-and-groups

Creates user accounts on the target repository from the specified export file. The export file
was created by running air system export users-and-groups. This command is repository-
wide. For information about the arguments common to all air commands, see “Command-
line syntax of air commands”.
Syntax
air system import users-and-groups filename [-dry-run] [-keep-ids]
Argument Description
filename Pathname of the repository file produced by running air export users-and-
groups. You may use - to have the data read from standard input.
-dry-run If specified, the operation does not actually take place, but the technical
repository displays an analysis of the effect of issuing the command.
-keep-ids If specified, the incoming uid (user ID) or gid (group ID) is preserved; that
means if a conflict occurs, the user or group is not created.
Usage
This command accepts only the output from air system export users-and-groups. If a given
user or group already exists, a warning is issued and that user or group is not created.

By default, if a given user ID is already taken, a new user ID is created. However, if the -
keep-ids option is specified, the technical repository issues a warning and does not create
the user or group.

Related topics

 air system export users-and-groups

air system install categories

Builds or rebuilds the categories and annotation rules of the base schema. The categories
are stored in /abinitio/categories. The annotation rules are stored in /abinitio/annotation
rules. This command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air system install categories
air system install components
Installs the built-in components and Ab Initio projects (like the Ab Initio Environment) into
the technical repository. This command is branch-specific. You must run this command for
each branch of your technical repository.

For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air system install components

air system install schema

Installs a representation of the technical repository schema in the repository. This command
is repository-wide. Use this command if you are updating the Technical Repository
software and it displays an error message that indicates that the schema version in the
Technical Repository is out of date. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air system install schema [-replace]
Argument Description
-replace Replaces the entire schema. If omitted, the command examines the existing
schema, finds entries that are not present in the schema being installed, and
merges them into the new schema.

air system show schema

Displays schema differences between the current version of the Technical Repository
software and the schema that is stored in the technical repository. This command
is repository-wide. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air system show schema [-diff ] [-version version]
Argument Description
-diff Displays schema differences between the current version of the Technical
Repository software and the schema that is stored in the technical
repository.
-version version Version number (integer) of the technical repository whose schema you
want to print. If not specified, defaults to the current version.
Usage
If no options are specified, -diff is assumed.

If the output indicates that there are entries missing from the technical repository, Ab Initio
recommends that you run air system install schema.
Examples
This example output shows that there are no differences between the current software
version and the schema:

The EME schema and the software's schema are identical

Diff completed

This example output shows that there are differences between the current software version
and the schema that is stored in the technical repository. To resolve the differences issue,
run air system install schema.

The EME schema has objects that the software version doesn't:
2035065001 XXGbzlookup_results_bzvarset
XXGbzconfig
XXGbzlookup

2035015007 XXGbzlookup_results_bzvarset
XXGbzconfig
XXGbzlookup

2035009002 XXGbzlookup_results_bzvarset
XXGbzconfig
XXGbzlookup

Diff completed

air system show version

Displays the current version of the schema being used by the technical repository. This
information is useful for Departamento de soporte técnico de Ab Initio. This command
is repository-wide. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air system show version

air system user change-name

Changes the username for the specified user. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air system user change-name old-username new-username
Argument Description
old-username Valid existing username.
new-username New username for this user.
Usage
A name is a set of alphanumeric characters. Spaces are allowed, but you must use quotes on
the command line around multiword usernames.

Other attributes of the user account, including password and permissions, are not modified,
nor is object ownership.

NOTA:

Since the search index entries may contain the old username, you should rebuild the search
index after executing this command.

air system user change-password

Specifies a new clear password for the user. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air system user change-password username
[-clear-password clear-password] [-none] [-insecure-
encryption]
Argument Description
username Valid username.
-clear-password clea Encrypts and sets the password for this user.
r-password
-none Does not require the user to enter a password.

-insecure-encryption For namespace authentication, allows you to override the more secure
default SHA-256 cryptographic hash function and use the less secure DES
instead. SHA-256 is the default for Co>Operating System Version 3.2.5 and
higher.

NOTA:

Use this argument for backward compatibility only if you cannot

upgrade a client such as Express>It or aiw to Version 3.2.5 or higher.
Argument Description

Do not use it for any other purpose.

Usage
If neither -clear-password nor -none is specified, you must type a password at the command
prompt Enter repository password. The password is not displayed on the screen and is
automatically encrypted.

air system user create

Creates an account for a user. This command is repository-wide. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air system user create
username
[-q]
[-dry-run]
[-uid uid-number]
[-group group-name] ...
[-clear-password clear-password]
[-crypted-password crypted-password] [-insecure-encryption]
[-umask [octal-umask | "none"]
Argument Description
username Valid username.
-q Suppresses the error message if a user already exists with the same
user ID that is specified by uid-number.
-dry-run Displays an analysis of what the effect of running this command
will be without actually running the command.
-uiduid-number Integer. Grants the specified user ID. If the user ID is in use or is
over 134217728, the command displays an error. If not specified,
the technical repository picks a unique integer for the value of uid-
number.
-group group-name Existing group. Adds user to this group. You can specify this clause
more than once. If the group does not exist, the command issues a
warning, but creates the account. When the user creates a new
object, it is assigned to the first group specified.
-clear-password clear- Password. Specify only if you do not specify -crypted-password.
password The password will be encrypted and set for this user. If not
Argument Description
specified, the password is set to ‘*’.
-crypted-password cry Encrypted password. Specify only if you do not specify -clear-
pted-password password.
-insecure-encryption For namespace authentication, allows you to override the more secure
default SHA-256 cryptographic hash function and use the less secure DES
instead. SHA-256 is the default for Co>Operating System Version 3.2.5
and higher.

NOTA:

Use this argument for backward compatibility only if you cannot

upgrade a client such as Express>It to Version 3.2.5 or higher. It
can also be used for aiw clients that cannot be upgraded to Version
3.2.5 or higher. (This client was deprecated in Version 3.3.1.) Do
not use this argument for any other purpose.
-umask [octal-umask | Sets the umask to be used for setting the default permissions on a
"none"] new object. Specify octal-umask as a three-digit octal number,
using standard Unix conventions. If set to the string "none," the
user's operating system umask is used as the default. If not
specified, the default is "none."
Usage
You must have administrative privileges to create a user account. A user account has these
attributes:

 Name A username is a set of alphanumeric characters. Spaces are allowed, but

you must use quotes on the command line around multiword usernames.
 uid If the user ID is in use, an error occurs. We recommend that you specify the
uid if you want the technical repository uid to match the Unix uid. Otherwise, let the
repository assign the uid.
 Group The group specified in the first -groupgroup-name clause is considered the
specified user’s default group. New objects created by this user will be assigned to
this group.
 Password If you have access to the contents of the passwd file on Unix, it may be
possible to create technical repository user accounts with the same passwords that
they have for their Unix accounts. It is useful to specify encrypted passwords in a
scripting environment when you are creating a large number of Unix users. To
accomplish this, supply the -crypted-password option. The encryption method must
match. The current method is 56-bit DES one-way encryption. This means that you
cannot encrypt a password with the m_password utility. You can however encrypt
the password with the Unix crypt command.
 You can create a password using either -clear-password or -crypted-password, but
not both. If no password is specified, the user cannot log in to the Technical
Repository Web Interface.

 umask As in Unix, the umask option sets the default permissions that files have
when a particular user create them. A umask is represented as a three-digit octal
number.

The umask (unmask) works by turning off read, write, and/or execute permission
for the owner, group, and other. For example, if you specify 246 as the value
of octal-umask, the 2 denies write permission to the owner of a newly created file,
the 4 denies read permission to the group associated with a newly created file, and
the 6 denies read and write permission to all other users.

If you omit -umask, the default permissions for new files created by this user are
those defined for his or her umask in the operating system.

After creating the user account, you can change the default permissions by
running air system user umask.

air system user default-group

Sets the default group to which a new object is assigned. The assignment is based on the
account of the specified user. This command is repository-wide. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air system user default-group username group-name
Argument Description
username Valid username.
group-name Name of an existing group to which user username belongs.
Usage
When a user creates an object, it is assigned to a default group, based on the account of the
user creating the object. The user must already be a member of the specified group. The
command fails if the group does not exist. You must be either a Technical Repository
administrator or the specified user to use this command.

This command applies only to existing users. For new users you can set the default group
when you create the user account. Specify the -group argument to air system user create.

To change the group to which an existing object is assigned, run air object chown.
air system user delete
Deletes the user from the technical repository. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air system user delete [-q] username
Argumen
Description
t
-q Suppresses error if the specified user does not exist.
username Valid username.
Usage
The uid (user ID) remains unassociated with any name. It removes the specified user from
all groups.
air system user disable
Disables the account of the specified user. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air system user disable username
Argumen
Description
t
username Valid username. Enclose the name in quotes.
Example
To disable the active user account of JaneDoe, type:

air system user disable ‘JaneDoe’

air system user enable

Enables the disabled account of the specified user. This command is repository-wide. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air system user enable username
Argumen
Description
t
username Valid username. Enclose the name in quotes.
Example
To enable the disabled user account of JaneDoe, type:

air system user enable ‘JaneDoe’

air system user show

Displays information about the account of a given user or of all users. This command
is repository-wide. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air system user show { username ... | -all } [ -direct-groups ]
Argument Description
username... Choose one of the following:
| -all
 username is a valid username; the output is for this repository user
only. You can enter multiple usernames.
 -all means the output is for all repository users.

NOTA:

If you are using the Authorization Gateway to manage user-to-group

assignments, the -all argument does not display group membership
information.
-direct-groups Name of an existing group to which username is a direct member. This
argument does not list the parent groups, if any exist.
Usage
The output includes a user’s name, uid, password, disabled status, umask, and group
memberships.

 Disabled status is either yes for disabled or no for enabled.

 If a user has a password, the command shows its hash algorithm; otherwise, *
means “no password” and NONE means “no password required.”
  If the umask column is empty, it means that the operating system umask is being
used. Otherwise, umask lists the user’s technical repository umask, such as 22. (For
information about umasks, see the “Usage” for air system user create.)
 The groups column lists all the groups (including parent groups) to which the user
belongs. The first group is the default group. (For information about the default
group, see the “Usage” for air system user create.) If you use the -direct-
groups argument, you only see the direct groups to which the user belongs.

Examples
The following command displays all users:

air system user show -all

In the resulting sample output, JaneDoe and JohnDeer are direct members of the child
group dev. The group staff is a parent group to dev.

name uid password disabled umask groups

JaneDoe 10016 * yes 22 dev, staff
JimAnchower 10015 * no -
JohnDeer 10013 * no 44 dev, staff
JoeBlue 10014 NONE no -
NoPwdUser 10012 * no -
MitziKatz 10017 (sha256) no -

The following command displays the direct groups for all users:

air system user show -all -direct-groups

In the resulting sample output, JaneDoe and JohnDeer are direct members of the group dev.
Unlike the previous example, staff is not in the output because it is the parent group of dev.

name uid password disabled umask groups

JaneDoe 10016 * yes 22 dev
JimAnchower 10015 * no -
JohnDeer 10013 * no 44 dev
JoeBlue 10014 NONE no -
NoPwdUser 10012 * no -
MitziKatz 10017 (sha256) no -
air system user umask
Sets the umask for the specified user. This command is repository-wide. For information
about the arguments common to all air commands, see “Command-line syntax of air
commands”.
Syntax
air system user umask username{-umask {octal-umask | "none"}
Argument Description
username Valid, existing username.
-umask {octal- Sets the umask to be used for setting the default permissions on a new
umask | "none"} object. Specify octal-umask as a three-digit octal number, using
standard Unix conventions. If set to the string "none", the user's
operating system umask is used as the default.
Usage
You must be either a Technical Repository administrator or the specified user to use this
command. This command applies only to existing users You can also set the umask when
you create a new user account. Specify the -umask argument to air system user create.

For information about umasks, see the “Usage” for air system user create.

NOTA:

This command applies only to existing users. You can also set the umask when you create a
new user account. Specify the -umask argument to air system user create.

Example
To deny all users — except the owner (JaneDoe) — read and write permission on files that
will be created by JaneDoe, type:

air system user umask ‘JaneDoe’ 066

NOTA:

66 is equivalent to 066.

air tag commands

The air tag commands create and manipulate tags at the command line. For more
information about managing tags at the command line, see “Creating and managing tags at
the command line” in the Technical Repository Guide to Version Control. (You can also
manage tags from the Technical Repository Management Console. For more information,
see “Creating and managing tags from the TRMC” in the Technical Repository Guide to
Version Control.) The following table summarizes the air tag commands. For information
about command syntax, see “Command-line syntax of air commands”.

Command Description
air tag change-version Changes the versions of the objects in a tag.
air tag combine Combines contents of one or more tags under a single tag.
air tag create Creates or modifies a tag.
air tag default-version Sets or displays the default version of a tag.
air tag delete Deletes a tag.
air tag diff Lists the differences between two tags.
air tag duplicate Creates a new tag from an existing tag.
air tag freeze Freezes a tag.
air tag import- Reads and checks in a configuration file.
configuration
air tag list Lists tags.
air tag list-fixes Displays information about issues marked as fixed in the comments
associated with the specified tags.
air tag ls Alias for air tag list.
air tag object-versions Lists the last checked in version for the specified tag.
air tag remove Removes an object from a tag.
air tag rename Renames a tag.
air tag save This command has been deprecated. Use air object save.
air tag tag- Tags objects specified by a configuration file.
configuration

air tag change-version

Changes the versions of objects in an existing tag. This command is branch-specific. For
information about the arguments common to all air commands, see “Command-line syntax
of air commands”.
Syntax
air tag change-version tag-name
{object ... | -all-primary}
[-version version]
[-exact]
[-exclude rpath ...]
Argument Description
tag-name Name of the tag to be modified.
object ... | - You must specify one of the following:
all-primary
 Path to a repository object whose version you want to
change. You may specify multiple objects.
 -all-primary specifies the tag’s primary objects. Their
versions will be changed.

-version version The new version to which the specified objects or all primary
objects are to be changed.

version can be specified as a version number or as a date/time

in the format "YYYY-MM-DD HH:MM:SS" or "YYYY-MM-
DD". version can be older or newer than the current version of
the objects in the tag.

If this argument is omitted, the objects are updated to the

current version of the technical repository.
-exact If the specified objects are primary objects in the tag, leaves
their secondary objects unchanged. If this argument is omitted,
the secondary objects are recomputed.

PRECAUCIÓN:

Omit this option at your own risk. It may result in a tag that
contains objects at different versions, which may not have been
tested together.
-exclude rpath ... If the -exact argument is not specified, the command ignores
the specified objects or objects contained in the specified
directories when it recomputes which secondary objects to tag.

Example
To update the dup2 tag on the test project to the current version of the technical repository
and have the secondary objects recomputed as well, type:

air tag change-version dup2 /Projects/test

Alias
The alias for this command is air tag cv.
air tag combine
Combines the objects tagged by one or more tags under a single tag. This command
is branch-specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air tag combine [-dry-run] [-create new-tag]
{[-latest] | [-list-order]}
tag1 tag2 ...
Argument Description
-dry-run Reports any errors that would occur if the operation were tried, but does
not actually perform the operation. We strongly recommend that you use
this option before using the -latest or -list-order arguments. For more
information, see those arguments.
-create new-tag Creates a tag called new-tag and tags all the specified objects with it.

If this argument is not specified, the objects specified by tag1 tag2 ... are
combined under tag1.
-latest | -list- Specifies how to resolve any version conflicts when two versions of the
order same object are specified in the tag list. To use either option listed below,
you must use the -create argument to create a new tag.

 -latest — Use the object with the latest version number found
among the supplied tags to resolve any conflicts.
 -list-order — Use the version of the object found in the left-most
tag in the list of tags to resolve any conflicts.

PRECAUCIÓN:

Before using one of these options, we recommend that you first run this
command with the -dry-run argument. It is important that you understand
what conflicts exist and what is the best way to resolve them, and that
you are confident that solving conflicts automatically is safe.
tag1 tag2 ... Tags specifying the objects that are to be combined under a new tag (or,
if -create was omitted, under tag1).
Usage
If version conflicts are detected among the specified objects, no modifications are made to
any tags. When conflicts arise, you can do one of the following:

 Restructure the command to resolve the conflicts and then reissue the air tag
combine command
  Use the-latest argument to resolve conflicts for you by taking the most recent
version
 Use the -list-order argument to resolve conflicts for you by taking the version in the
specified tag

To create a new tag called prod that has the same contents as an existing tag dev, use the -
create option to create prod and then specify dev as the only tag to “combine”:

air tag combine -create prod dev

To make a copy of an existing tag, use air tag duplicate.

Examples
In the following two examples, the new tag super-tag is created by combining the objects
in prod12, prod14, and prod16. Conflicts are automatically resolved in one of two ways.
Using the latest version to resolve conflicts
In this example, the command automatically resolves any object conflicts by adding the
most recent version of that object to the new tag:

air tag combine -create super-tag -latest prod12 prod14 prod16

If the tag prod 14 contains the latest version of my-graph.mp, it will be used instead of the
object in prod16.
Using a specific tagged version to resolve conflicts
In this example, the command automatically resolves any object conflicts by using the
version of that object found in the left-most tag.:

air tag combine -create super-tag -list-order prod14 prod12 prod16

If my-graph.mp exists in prod14, that tagged version is used even if a more recent version
exists in prod12 or prod16. If my-graph.mp exists in prod12 or prod16 but not in prod14,
the object in prod12 is used because it is the left-most tag in the list.

air tag create

Creates or modifies a tag. This command is branch-specific. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air tag create tag-name { rpath ... | -file object-list }
{ [ -project-only] | [-all-required ] | [ -exact ] }
[ -dry-run ]
[ -exclude rpath ... ]
[ -move | -add ]
[ -strict ]
[ -no-annotations ] [ -ignore-generated-by ]
[ -full-commons | -no-full-commons ]
[ -comment comment | -comment-file comment-filename
| -overwrite-comment { -comment comment
| -comment-file comment-filename } ]
[ -rtag { rtag-name | version } ]
Argument Description
tag-name Specifies the name of the tag to be
created or modified.
{ rpath ... | -file object-list } Specifies one or more repository
paths to the objects to be
tagged. rpath can be a project name.

If you tag a directory or project, all

objects in the directory or project are
recursively tagged. If you tag an
object, all the objects it depends on
are tagged unless -exact is specified.

Alternatively, the list of objects to be

tagged can be specified directly on
the command line, or as the contents
of a file: -file object-list. Specify the
full repository path to each object.
The file must reside on the
Application Hub host.
{[-project-only] | [-all-required] | [-exact]} Specifies which objects should be
tagged along with the primary object
(specified by rpath ... or -file file-
list). You must choose one of the
following:

 -project-only (or -p) —

Includes only required
Argument Description

objects in the same project(s)

as the object(s) specified
by rpath ... or -file object-
list.
 -all-required (or -all) —
Includes all objects required
by the object(s) to be tagged
(specified by rpath ...
or -file object-list).
 -exact (or -e) — Includes
only the objects specified
by rpath ... or -file object-
list. It does not tag objects
that these objects depend on.
If the object to be tagged is a
directory, the command
recursively tags its contents.

-dry-run Does not actually create or modify

the tag. Only indicates the errors that
would occur if the operation were to
be performed.
-exclude rpath ... Excludes the specified objects or the
objects contained in the specified
directories from the tag. The
command will ignore these objects
as it walks the directories to
determine which secondary objects
to tag.
-move | -add These options apply to existing tags,
as follows:

 -move is deprecated. Use air

tag change-version instead.

Moves the tag to the new

version of the object if the tag
already exists and an object is
already tagged with it.

 -add adds one or more

objects to the existing tag.

-strict Treats any warning situations

Argument Description
encountered during the discovery of
required objects as errors. For
example, if a record format (.dml)
file required by a graph were missing
or had syntax errors, this argument
would generate an error.
-no-annotations Specifies that the tag should not
include references to annotation
values.
-ignore-generated-by Ignores
the dataset category generatedByOI
D annotation rule when looking for
required files. For example, when
used, this argument will not tag the
ruleset that generated a transform.
-full-commons | -no-full-commons Controls whether all the objects in
common projects are included in the
new tag when common projects’
parameters are referenced by tagged
objects in a client project. You can
choose one of the following:

 -full-commons — All the

objects in common projects
will be added to the tag when
the client project itself is
tagged (rpath is a project).
 -no-full-commons — Only
the required objects in
common projects will be
added to the tag when the
client project itself is tagged
(rpath is a project).

If this argument is not specified, the

default behavior is determined by the
configuration
variable AB_AIR_TAG_FULL_CO
MMONS, which by default is set
to false (or -no-full-commons).

Note that these options have no

effect in either of the following
scenarios:
Argument Description

 If rpath is not a project.

 If you specify -exact.

-comment comment | -comment-file comment-filena To apply a comment to the tag, do

me | -overwrite-comment {-comment comment | -com not specify an object. You can
ment-file comment-filename} choose one of the following:

 -comment comment —
Specifies the text of a
comment to be associated
with the tag. Express the
comment as a string.
 comment-file comment-
filename — Specifies the
name of a file containing the
text of a comment to be
associated with the tag.
 -overwrite-comment with
either -comment comment
or -comment-file comment-fi
lename — Overwrites the
existing comment with the
new comment that you
specify.

-rtag {rtag-name | version} Retags objects to which an old-style

rtag has been applied. You must
choose one of the following:

 -rtag rtagname — Specifies

that the objects tagged by an
old-style tag, rtagname, be
tagged by tag-name.
 -rtag version — Specifies that
the objects as they existed in
version version be tagged
by tag-name.

Usage
A new tag name must begin with a letter and can be any length. Tag names cannot contain
forward slashes (“/”), NULLs, newlines, or tabs.
If the tag already exists, you can apply it to additional objects (-add). If -move is not
specified for an existing tag, the tag is not changed. Note that the granularity of the objects
to which you have attached a tag determines the granularity of the objects that you can
remove from the tag. In other words, you can only remove (using air tag remove) from a
tag an object that was specified as an object to some prior air tag create command.

By default, the command tags not only the specified object (called the primary object) but
also the objects on which the specified object depends — called the secondary objects. For
example, if you tag a graph (the most commonly tagged primary object), its record format
and transformation files are also tagged by default. To change this behavior,
use -exact or -project-only.

By default, the command does not include objects in /abinitio in the tag. If you need to tag
these objects, you must explicitly include them in the tag.

If modifying a tag requires the inclusion of different versions of an object, an error occurs
and the tag is not changed.

If tag validation is activated for a project that you are tagging, your tag must meet the
commit policies that are specified by the tag validation or tag creation will fail or generate a
warning. For example, if a developer creates a new tag that does not meet the tag naming
convention that a commit policy specifies, tag creation fails. For more information,
see “Managing commit policies and automated actions” in the DevOps Guide.
Examples
Tagging required files
This example adds the prod456_tag tag to the /Projects/production project and all its
required files:

air tag create prod456_tag /Projects/production -all-required

Tagging a specific file

This example adds the prod457_tag tag to only the POC project’s mp directory:

air tag create prod456_tag /Projects/customer/POC/mp -exact

Using a list of files

This example passes a file to the command that lists the two graph objects to be tagged:
air tag create prod458_tag -file tagfile

The tagfile file contains the following lines:

/Projects/test/mp/devo4.mp
/Projects/test/mp/devo5.mp

Deprecated arguments
-move is deprecated in Version 2.15. Use air tag change-version instead.

air tag default-version

Sets or displays the default version of a tag. The default version is the version that is used
to access objects that are not explicitly listed in the tag when you execute air commands
using air -version tag-name command (for example, air -version my_tag ls). If the default
version of a tag isn’t set, objects that are not listed in the tag are fetched at the most recent
modification version of the tag. This command is branch-specific. For information about
the arguments that are common to all air commands, see “Command-line syntax of air
commands”.
Syntax
air tag default-version tag-name {-set [version] | -show}
Argument Description
tag-name Specifies the name of the tag whose default version you want to set or display.
-set Sets the specified tag’s default version. If you specify 0, the version is unset. In
this case, the command will use the tag’s most recent modification version.
version Specifies the version that you want to use as the default version.
-show Shows the current default version of the tag.
Examples
Displaying the current default version
This command uses the -show argument to display the current default version (531) for
the kt_dev tag:

air tag default-version kt_dev -show

531
Setting the default version
This command uses the -set argument to change the default to version 494:

air tag default-version kt_dev -set 494

Rerunning the command with the -show argument confirms that the default version is
now 494:

air tag default-version kt_dev -show

494

Using the most recent version

The first command in the following example specifies the value 0 for the -set argument,
which uses the latest modification version. The second command confirms that the default
version is now 1245:

air tag default-version kt_tag -set 0

air tag default-version kt_tag -show
unset (using tag modification version: 1245)

air tag delete

Deletes a tag. This command is branch-specific. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air tag delete [-q] tag-name
Argumen
Description
t
-q Suppresses error if the tag does not exist.
tag-name Name of the tag you want to delete.
air tag diff
Lists the differences between the version and objects in two tags. This command is branch-
specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
NOTA:

This command compares the objects and version numbers in a tag — that is, which versions
are tagged — rather than whether tagged objects have changed between the two tags. To
identify which objects changed between two tags, use the air object changed command.

Syntax
air tag diff [-show-all] tag1 tag2
Argumen
Description
t
-show-all Also lists objects for which there are no differences.
tag1 tag2 Names of the two tags whose differences you want to display.
Example
To see the differences between tag-dir1 and tag-dir2, type the following:

air tag diff tag-dir1 tag-dir2

The output lists each tagged object where the version differs. The first specified tag (tag-
dir1) is V1, and the second (tag-dir1) is V2. In the output below, b.txt does not exist in tag-
dir1, so V1 is blank.

Object V1 V2
/dir/a.txt 308 310
/dir/b.txt 310

air tag duplicate

Creates a new tag from an existing tag, optionally updating the versions of the tag’s
primary objects to the current version of the technical repository and recomputing the tag’s
secondary objects. This command is branch-specific. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air tag duplicate tag-name new-tag-name
[-update-to-current]
[-comment comment | -comment-file comment-filename]
Argument Description
tag-name Name of an existing tag you want
to duplicate.
new-tag-name Name of the new tag.
-update-to-current Specifies that the new tag will
have all primary objects moved to
the current version and that all
secondary objects will be
recomputed at the current version.
-comment comment | -comment-file comment-filenam You may choose one of these:
e
 -comment comment specifi
es the text of a comment to
be associated with the tag.
Express the comment as a
string.
 comment-file comment-
filename specifies the name
of the file containing the
text of a comment to be
associated with the tag.

-exclude rpath ... If the -update-to-current argument

is present, the command ignores
the specified objects or any objects
contained in the specified
directories when it recomputes
which secondary objects to tag.
Usage
The command fails if the new tag name already exists.

The original comment is not duplicated from the original tag; however, you can specify a
new comment.

Compare this command with air tag change-version.

air tag freeze
Freezes a tag, so that you cannot add to, move, delete, or rename it. This command
is branch-specific. For information about the arguments common to all air commands,
see “Command-line syntax of air commands”.
Syntax
air tag freeze tag
Argumen
Description
t
tag Tag to be frozen.
Usage
PRECAUCIÓN:

A frozen tag cannot be unfrozen, so this command should be used with caution.

air tag import-configuration

Reads the contents of a configuration file in the filesystem and copies it into the technical
repository. This command is branch-specific. For information about the arguments common
to all air commands, see “Command-line syntax of air commands”.
Syntax
air tag import-configuration [-dry-run] config-file-fspath config-file-rpath
Argument Description
-dry-run Reports any errors that would occur if the command were run but does
not actually perform the checkin.
config-file-fspat Filesystem path to the configuration file whose contents are to copied
h into the technical repository.
config-file-rpath Repository path where the configuration is to be checked in. If the
directory specified does not exist, it is created.
Usage
The configuration file config-file-fspath should have a .config extension.

The configuration file config-file-fspath is checked for errors, but it is always imported —
whether or not it contains errors. Use -dry-run to identify errors before actually checking in
the configuration file.

Once you copy the configuration file into the technical repository, run air tag tag-
configuration to actually evaluate the configuration.

air tag import-configuration does not place the configuration file under source control. If
you want the file to be checked in to a project, use air project import with the sandbox file
specified to the -files argument.

For information about configuration file format and usage, see “Creating tag
configurations” in the Technical Repository Guide to Version Control.
Example
To copy my_config_file.config into the technical repository at /configs/, type the following:

air tag import-configuration \

c:/my_eme/config/my_config_file.config \
/configs/test_config_file.config

air tag list

Lists information about tags in the technical repository. This command is branch-specific.
For information about the arguments common to all air commands, see “Command-line
syntax of air commands”.
Syntax
air tag list [flags] [-from fromtime] [-to totime] [-user username] [tag
| object]
Argument Description
flags Possible flags are as follows:

 -l — Lists user and time information about the tag tag.

 -o — Lists all the tags on the object object.
 -c — Lists the comments on the tag tag.
 -p — Lists the primary tagged objects in the tag tag.
 -e — Lists everything tagged by the tag tag (at the domain level).
 -n — Lists only the names of the objects in the tag tag.

-from fromtime Restricts the output to all tags modified after the specified time (inclusive).
Can be combined with the -to argument to specify a range. For more
information, see “Examples”.
-to totime Restricts the output to all tags modified before the specified time
(inclusive). Can be combined with the -from argument to specify a range.
For more information, see “Examples”.
-user username Restricts the output to only tags modified by the specified user.
tag | object You may choose one of the following:

 tag — Specifies a tag whose information you want to list. If

omitted, all pertinent tags are listed.
 object — Specifies an object whose tag information you want to
list.

If omitted, the command displays all tags in the technical repository

(unless otherwise restricted by the filtering arguments).
Usage
When you use -o and -p together, the command displays only the tags in which object is a
primary object in a tag:

air tag list -o -p /Projects/lesson/mp/JoinCustomers.mp

You can use -from and -to singly, or in combination to specify a range. The arguments’
values are inclusive when retrieving the tag results.
Examples
The following example restricts the tags to those modified after 30 January 2013:

$ air tag ls -from 2013-01-30

Dev_branch_on_docloc64

The following example restricts the tags to those modified after 8:00 PM on 24 April 2011:

$air tag ls -from "2011-04-24 21:00:00"

My subbranch
Dev_branch_on_docloc64

Alias
The alias for this command is air tag ls.

air tag list-fixes

Displays information about issues marked as fixed in the comments associated with the
specified tags. This command extracts the information from tag comments created by air
promote make-comment or marked by air repository version-list-fixes. Information is
shown in DML-described format by default, as $AB_HOME/include/fixes-
info.dml describes.
Syntax
air tag list-fixes tag-name | tag-list ]
Argument Description
tag-name | tag- Required. Specifies a tag or a list of tags to be used.
list | -
If tag-list is -, the tag names are read from stdin.

The comments associated with the specified tag are searched for two
types of fixes:

 Lines that contain information on fixed issues produced by air

promote make-comment.
 Lines that match the regex defined in AB_FIXES_REGEX

Usage
This command can be used to search tags and determine which issues are marked as fixed
in the tag comment. This command extracts the aggregated comment from the tag that air
promote make-comment creates.

For more information about the promotion workflow, see “Conceptual workflow:
Promotion” in the DevOps Guide.
Example
Violet created /Projects/test-proj, exported it to her sandbox test-sand, and fixed bugs. She
checks in test-sand with a comment about the fixes to TEST-1 and TEST-2.

NOTA:

Most commands in this example can also be run from the Checkin Wizard.

air sandbox import test-sand -auto-add -comment "fixes TEST-1

fixes TEST-2"
1 mp/bar.mp application/x-abinitio-graph Add to Repository
1 mp/foo.mp application/x-abinitio-graph Add to Repository
Committed checkin as repository version 17.

Violet prepares to promote test-proj by creating a tag test_release_V1.3 on the project.

air tag create test_release_V1.3 /Projects/test-proj

She creates a comment on the new tag that aggregates information about the fixes
previously checked in.
air promote make-comment test_release_V1.3

She runs air tag list-fixes to extract the bug fix information from the tag comment and
display it.

air tag list-fixes test_release_V1.3

TEST-1|17|2018-04-16 21:04:42|vjay|0
TEST-2|17|2018-04-16 21:04:42|vjay|0

Violet notices that one fix, TEST-3, is missing. She runs air tag create with a
comment fixes TEST-3 to add the fix manually to the existing comment on the tag:

air tag create test_release_V1.3 -comment "fixes TEST-3"

She runs air tag list-fixes to confirm that all fixes are part of the project to be promoted.

air tag list-fixes test_release_V1.3

TEST-1|17|2018-04-16 21:04:42|vjay|0
TEST-2|17|2018-04-16 21:04:42|vjay|0
TEST-3|test_release_V1.3|||1

After promoting test-release-V1.3, Violet can run the same command to see the fixes that
were promoted to production and use that data to run Ab Initio Jira graphs or other
continuous integration software.

air tag ls
This command is an alias for air tag list.
air tag object-versions
On a per-object basis, lists the last checked-in version of objects for the specified tag. The
command displays the checkin timestamp and username for each version that it reports on.
You can change the default display to show all checked-in versions up to the version of the
specified tag or to show all versions since a given tag or version was created. This
command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air tag object-versions tag
[ -since tag-or-version ]
[ -all ]
[ -m ]
[ -versions-only ]
Argument Description
tag Specifies the tag that will determine which objects to report versions for. If
the tag name includes spaces, enclose it in quotations.
-since tag-or- Lists all the checkin versions and their objects from the
version specified tag or version up to the specified tag argument. Both the start and
end bounds are inclusive.
-all Lists all the checkin versions for each object in tag up to the last version
in tag. This argument is the equivalent of entering -since 1.
-m Displays the output in a machine-readable format. The associated DML is
located at $AB_HOME/include/tag_versions.dml.
-versions- Lists only the checkin version numbers associated with the tag and
only suppresses the object names. Use with all arguments except -m to limit the
output shown.
Usage
By default, this command reports only the last checked-in version for an object. To change
this behavior, use the -since argument to specify a range or the -all argument to specify all
versions up to the one specified by tag, inclusive.

This command reports object versions only up to and including the versions that are
indicated by the tag that you specify.

If there are no checkins to report for the specified tag or version number, the command
output shows only the column headers with no data.
Examples
The following air tag object-versions command example shows the default output for
the proj1-release-V2-0-1 tag. The output shows the individual objects and their repository
version numbers as of when the tag was created — in this case, repository version 283:

air tag object-versions proj1-release-V2-0-1

Checkin Tag
Version Date User Version Path
113 2017-06-09 16:01:31 kornstalk 283 /Projects/proj1/.project.pset
113 2017-06-09 16:01:31 kornstalk 283 /Projects/proj1/.project-start.ksh
113 2017-06-09 16:01:31 kornstalk 283 /Projects/proj1/.project-end.ksh
113 2017-06-09 16:01:31 kornstalk 283 /Projects/proj1/dml
 113 2017-06-09 16:01:31 kornstalk 283 /Projects/proj1/xfr
...
113 2017-06-09 16:01:31 kornstalk 283 /Projects/proj1/mp
113 2017-06-09 16:01:31 kornstalk 283 /Projects/proj1/plan
116 2017-06-09 16:12:43 kornstalk 283 /Projects/proj1/dml/object1a.dml
117 2017-06-09 16:12:55 kornstalk 283 /Projects/proj1/dml/object1b.dml
113 2017-06-09 16:01:31 kornstalk 283 /Projects/proj1/resource
113 2017-06-09 16:01:31 kornstalk 283 /Projects/proj1/pset
113 2017-06-09 16:01:31 kornstalk 283 /Projects/proj1/components

By contrast, the following example uses the same release tag but the output is restricted by
use of the -versions-only argument. When multiple objects share the same repository
version, that number is shown only once. You can pass this streamlined output to a
program:

air tag object-versions proj1-release-V2-0-1 -versions-only

113
116
117

The following example displays the objects that were checked in from the time that a beta
tag proj1-release-V2-0-1-beta was created to when the more recent proj1-release-V2-0-
1 tag was created. In this case, the output shows that two files were checked in between
those two release tags: overview.ksh and overview.mp.

air tag object-versions proj1-release-V2-0-1 -since proj1-release-V2-0-1-beta

Checkin Tag
Version Date User Version Path
248 2017-11-17 16:16:27 kornstalk 260 /Projects/proj1/run/overview.ksh
248 2017-11-17 16:16:27 kornstalk 260 /Projects/proj1/mp/overview.mp

The following example uses the -m argument to format the output since version 240 in a
DML-described format that lacks the headers. You can pass this information to a graph, a
utility such as m_dump, or another application, as shown below:

air tag object-versions base_integration -since 240 -m > out.txt

m_dump $AB_HOME/include/tag_versions.dml out.txt
Record 1:

[record
checkin_version "248"
 time "2017-11-17 16:16:27"
username "kornstalk"
tagged_version "260"
path "/Projects/proj1/run/overview.ksh"]

Record 2:

[record
checkin_version "248"
time "2017-11-17 16:16:27"
username "kornstalk"
tagged_version "260"
path "/Projects/proj1/mp/overview.mp"]

air tag remove

Removes the specified object from a tag. The object must have been previously tagged by
the air tag create command. This command is branch-specific. For information about the
arguments common to all air commands, see “Command-line syntax of air commands”.
Syntax
air tag remove [-q] tag-name object
Argument Description
-q Suppresses error if the tag does not reference the object.
tag-name Name of the tag from which you want to remove objects.
object Name of the object to remove from the tag. If object is a primary object, its
secondary objects are removed as well.
air tag rename
Renames a tag. This command is branch-specific. For information about the arguments
common to all air commands, see “Command-line syntax of air commands”.
Syntax
air tag rename tag-name new-name
Argument Description
tag-name Name of the tag whose name is to be changed.
new-name New name of the tag. An error occurs if this name already exists.
Usage
If a tag with the new name already exists, an error occurs.
air tag tag-configuration
Copies the configuration file to the technical repository, creates the specified tag, and
applies it to the list of objects in the tag configuration as well as to the configuration file
itself. This command is branch-specific. For information about the arguments common to
all air commands, see “Command-line syntax of air commands”.
Syntax
air tag tag-configuration
[-dry-run]
[-strict]
[-file config-file-fspath]
tag-name
config-file-rpath
Argument Description
-dry-run Reports conflicts that would occur if the command were run, but
does not actually perform the operation.
-strict If required objects are missing or have errors, the configuration is
not tagged.
-file config-file-fspat If specified, a configuration file in the filesystem to be copied to the
h technical repository location at config-file-rpath.

Do not specify this argument if the configuration file already exists

in the repository.
tag-name Name of a new tag that will be applied to the contents of the tag
configuration at config-file-rpath.
config-file-rpath Repository location of the configuration file from which the tag tag-
name will be created and applied.

If the configuration does not exist and -file is specified, config-file-

rpath is the repository location where config-file-fspath will be
copied.
Usage
The configuration file should have a .config extension.

This command also tags the configuration file itself with tag-name.

An error occurs if tag-name exists.

As an alternative to copying the configuration file as part of running this command, you can
copy the configuration file into the technical repository using air tag import-
configuration and later run air tag tag-configuration without
the -file config-file-fspath argument to evaluate the configuration.

For information on configuration file format and usage, see “Creating tag
configurations” in the Technical Repository Guide to Version Control.
Example
To copy the filesystem configuration file test_config_file.config to the technical repository
and apply the v2_config_tag, type the following:

air tag tag-configuration \

-file C:/eme-files/config/test_config_file.config v2_config_tag \
/configs/test_config_file.config