TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Introduction


Command Calling Conventions

All commands are accessible from the UNIX shell through the Apex command interpreter. To execute a command, type:

Although all command specifications show options preceding arguments, they can be interspersed. All options are processed before any arguments and apply to the entire operation.

For example, to create a subsystem, type:

The command interpreter will have exit status "1" if any errors or negative messages were emitted during execution, otherwise the exit status would be "0". Note that if there is partial success (for example, a combination of positive and negative or error messages), the error status would be "1".

Commands are also generally available through the simple command name. Thus, you can also create a subsystem using the command:


Command Output Conventions

Output Message Kinds

Output messages from Apex commands are typically preceded by the current time and by a three character prefix which specifies the kind of message that is being emitted. For example, warning and error messages are identified by the prefixes "!!!" and "***"respectively. The complete set of message prefixes are provided in Table 1.

Table 1 Apex Output Message Kinds
Kind
Prefix
Meaning
Text
no prefix
normal command output text; used by commands that generate reports
Auxiliary
:::
extra output; often used to echo command line
Debug
???
Rational diagnostic output
Note
---
supplemental information; often used to report the start of a major step
Positive
+++
a major step was successful
Negative
++*
a major step failed
Not_Required
++-
a major step was skipped (goal was already achieved)
Position
>>>
a location to which subsequent messages refer
Warning
!!!
a minor problem
Error
***
a significant problem which will likely cause a major step to fail
System_Error
**%
a significant problem caused by a system failure
Internal_Error
&&&
a significant problem caused by an internal failure
Exception
%%%
an unexpected exception was encountered
Continuation
...
a continuation of the previous message
Sharp
###
user defined
Dollar
$$$
user defined
At
@@@
user defined

An example of command output is shown below. In this typical example, auxiliary messages are used to echo the command line and denote completion, a positive message announces the successful completion of the operation for one object, an error message describes the reason for a failure and a negative message announces that the operation was unsuccessful for the object involved in the error.

Output Filtering

Command output may be filtered on the basis of the message kind. For example, filters can be set so that only warning and error messages are emitted. The output filter for a command is changed by setting the -output_filter option (alias: -of). The option is used to specify the kinds of messages that will be reported. Message kinds not specified are not reported, however text messages (i.e., messages with no prefix) are always shown.

The value of the -output_filter option is a sequence of tokens separated by spaces or the `+' character in which each token is either the name of a message kind (for example, error), a three character message prefix (for example., "***"), or one of the special tokens given in Table 2.

Table 2 Special Output Filter Tokens
Token
Meaning
none
show no kinds
all
all kinds, except for debug
errors
Negative+Error+Internal_Error+Exception
progress
errors+Positive
warnings
progress+Warning

The special tokens provide a short-hand for common sets of message kinds which are often used together.

The default value of -output_filter is all. The default value of -output_filter may be changed by setting the APEX_OUTPUT_FILTER environment variable.

Symbolic Link Usage

Use symbolic links to files and directories to navigate to objects through the GUI. However, using symbolic links as arguments to Apex commands is not supported unless the symbolic link has been created by Apex to manage remote storage for subsystems or views. Applying Apex commands to symbolic links that were not created by Apex will have unpredictable results.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS