Script Error Handling

Even if you validate each of your commands individually before adding them to your script, errors can still occur when you execute the script. If your scripting environment handles XML parsing, consider using the global XML output option ({–outputformat | -o} xml) to address these errors programmatically.

The Oracle FS CLI returns errors under the following conditions: command execution errors, command errors, and fatal errors. The Oracle FS CLI returns XML output for command execution errors only.

Command execution errors

The <ErrorList> indicates a command execution error. The following list describes some common conditions that can cause command execution errors:

The object specified in the command does not exist.
The subcommand in the command is incorrect.
The option in the command is incorrect.
The state of the object of the command or the state of the Oracle FS System prohibits running the command.

The following code sample displays the general format of an XML command execution error message:

<?xml version="1.0"?>
<CLIResponse>
  <ResponseHeader>
    <ClientData>FSCLI</ClientData>
  </ResponseHeader>
<ErrorList>
  <ErrorInformation>
<ErrorCode>error-code-name</ErrorCode>
<ErrorMessage>customer facing error message</ErrorMessage>
  </ErrorInformation>
</ErrorList>
<Status>failed</Status>
</CLIResponse>

Note: An error message can contain multiple <ErrorList>…</ErrorList> sections and <ErrorInformation>…</ErrorInformation> sections.

Command errors

In the case where the actual Oracle FS CLI command is wrong, Oracle FS CLI does not generate XML-formatted response even if you specify XML output. The following code sample displays the general format of a command error message.

    <?xml   version="1.0"?>
    Error: Unrecognizable Command: "bad-command-name"!
     Issue "fscli help" for command list.
    Command Failed

Fatal errors

A fatal error is any error that causes the program to abort. The following list summarizes some scenarios that can cause fatal errors:

network connectivity issues (for example, a communication issue between the Oracle FS CLI client and the Pilot)
communication between the Oracle FS CLI client and the Oracle FS System disconnects abruptly during data transmission, causing corruption in the response received
infrastructure errors (for example, file permission issues)

Fatal errors do not return an XML-formatted response even when requested using the global XML output option ({–outputformat | -o} xml). The following code sample displays the general format of a fatal error message.

An unexpected error occurred on the OracleFS System.
         Command Failed.

Important! Always check the exit code before attempting to parse the response.

List of Common Exit Codes

An exit code is a one-character code that the Oracle FS System returns when there is an error either in the request sent by your script or in the response sent by the Oracle FS System.

The following table summarizes the exit codes that might be returned, their descriptions, and whether they return an XML response.

Table 1 List of common exit codes
Exit code	Description	Returns an XML response?
0	Command succeeded.	Yes, if specified.
1	Unexpected or fatal errors.	No.
2	Command errors, for example, incorrect or misspelled options or incorrect Oracle FS System IP addresses or DNS names.	Yes‑For example, if you mistype an option name, the Oracle FS System returns XML.
		No‑For example, if you fail to connect to the Oracle FS System because of a bad IP address in the command line, the Oracle FS System does not return XML.
3	Command execution errors, for example, trying to modify a LUN that does not exist.	Yes.

Use the following guidelines when checking Oracle FS System exit codes.

Exit code zero (0): Parse XML response for an <ErrorList> tag if the command is one listed in the Special considerations for other FSCLI requests table below.
Exit code two (2) or three (3): Parse XML response for an <ErrorList> tag if the error is not a fatal error.
Exit code one (1): Do not parse the error as responses are not XML-formatted for fatal errors.

Additional Considerations

For -list type subcommands used with other options, the command fails unless all subcommands and options execute.

The following table lists the special consideration for the -list type commands when used with other options.

Table 2 Special considerations for -list type commands
Command	Description
-list type commands (for example system -list)	If you specify the -system command using the -list subcommand with any other options, the command fails unless all subcommands and options execute. You can avoid this situation if, instead of using the command system -list or the command system -list -details, use the system -list -status.

Some FSCLI requests issue multiple commands on the Pilot. For example, when adding a LUN and mapping the LUN to a host, the first request, creating a LUN, might succeed but the second request, mapping the LUN to a host, might fail. In this example, FSCLI returns a successful exit code zero (0) because the LUN was created but also an <ErrorList> tag (in the XML-formatted output) and a message explaining that the mapping request failed. Therefore, you must check for an <ErrorList> tag even if the overall status is exit code zero (0) to ensure that the entire command succeeded.

In this scenario, you should not retry the command as it will fail, because you are trying to recreate an object that already exists. You can avoid this situation by, instead of creating a LUN with the mapping in one command, first create a LUN, and then if the create a LUN command succeeds, then map the LUN using the LUN modify command.

The following table lists the set of commands that returns a successful exit code zero (0) upon creating an object, but which also might display an error message if a subsequent request fails.

Table 3 Special considerations for other FSCLI requests
Command	Description
clone_lun -add	If you include mapping options in your request to create a Clone LUN, FSCLI creates the Clone LUN first and then attempts the mapping. If the creation succeeds, the FSCLI reports successful execution of the command even if the subsequent mapping attempt fails.
clone_lun -copy	If you include mapping options in your request to create a copy of a Clone LUN, FSCLI creates the copy first and then attempts the mapping. If the creation succeeds, the FSCLI reports successful execution of the command even if the subsequent mapping attempt fails.
lun -add	If you include mapping options in your request to create a LUN, FSCLI creates the LUN first and then attempts the mapping. If the creation succeeds, the FSCLI reports successful execution of the command even if the subsequent mapping attempt fails.
lun -copy	If you include mapping options in your request to create a LUN copy, FSCLI creates the copy first and then attempts the mapping. If the creation succeeds, the FSCLI reports successful execution of the command even if the subsequent mapping attempt fails.
nfs_export -add	If you create an nfs_export using any of the options to set access, permissions or squash values, then FSCLI creates the export first, followed by the creation of an NFS host entry to configure the client access. If the creation attempt succeeds, the FSCLI reports successful execution of the command, even if the subsequent attempt to configure client access fails.
san_host -add san_host -modify	If you specify the -associateGroup option with a request to add a SAN host or modify an existing SAN host, FSCLI creates or modifies the SAN host first, followed by the request to associate that SAN host to a group. If the creation or modification succeeds, then the FSCLI reports successful execution of the command, even if the subsequent association fails.