Previous:Shell Command Sequencing Main Index Next:Text Output

#### Shell Command Return Actions

`Pre_Scene_Return=`s | Set pre scene return actions
`Pre_Frame_Return=`s | Set pre frame return actions
`Post_Scene_Return=`s | Set post scene return actions
`Post_Frame_Return=`s | Set post frame return actions
`User_Abort_Return=`s | Set user abort return actions
`Fatal_Error_Return=`s | Set fatal return actions

Note that no `+` or `-` switches are available for these options. They cannot be used from the command line. They may only be used from INI files.

Most operating systems allow application programs to return an error code if something goes wrong. When POV-Ray executes a shell command it can make use of this error code returned from the shell process and take some appropriate action if the code is zero or non-zero. POV-Ray itself returns such codes. It returns 0 for success, 1 for fatal error and 2 for user abort.

The actions are designated by a single letter in the different `..._Return`=s options. The possible actions are:

`I` | ignore the code
`S` | skip one step
`A` | all steps skipped
`Q` | quit POV-Ray immediately
`U` | generate a user abort in POV-Ray
`F` | generate a fatal error in POV-Ray

For example if your `Pre_Frame_Command` calls a program which generates your height field data and that utility fails then it will return a non-zero code. We would probably want POV-Ray to abort as well. The option `Pre_Frame_Return=F` will cause POV-Ray to do a fatal abort if the `Pre_Frame_Command` returns a non-zero code.

Sometimes a non-zero code from the external process is a good thing. Suppose you want to test if a frame has already been rendered. You could use the `S` action to skip this frame if the file is already rendered. Most utilities report an error if the file is not found. For example the command...

     pkzip -V myscene mysce012.tga

tells pkzip you want to view the catalog of `myscene.zip` for the file `mysce012.tga`. If the file isn't in the archive `pkzip` returns a non-zero code.

However we want to skip if the file is found. Therefore we need to reverse the action so it skips on zero and doesn't skip on non-zero. To reverse the zero vs. non-zero triggering of an action precede it with a "`-`" sign (note a "`!`" will also work since it is used in many programming languages as a negate operator).

`Pre_Frame_Return=S` will skip if the code shows error (non-zero) and will proceed normally on no error (zero). `Pre_Frame_Return=-S` will skip if there is no error (zero) and will proceed normally if there is an error (non-zero).

The default for all shells is `I` which means that the return action is ignored no matter what. POV-Ray simply proceeds with whatever it was doing before the shell command. The other actions depend upon the context. You may want to refer back to the animation loop sequence chart in the previous section "Shell Command Sequencing". The action for each shell is as follows.

On return from any `User_Abort_Command` if there is an action triggered...

and you have specified... | ... then POV-Ray will..
`F` | Then turn this user abort into a fatal error. Do the `Fatal_Error_Command`, if any. Exit POV-Ray with error code 1.
`S`, `A`, `Q`, or `U` | Then proceed with the user abort. Exit POV-Ray with error code 2.

On return from any `Fatal_Error_Command` then POV-Ray will proceed with the fatal error no matter what. It will exit POV-Ray with error code 1.

On return from any `Pre_Scene_Command`, `Pre_Frame_Command`, `Post_Frame_Command` or `Post_Scene_Commands` if there is an action triggered...

...and you have specified... | ... then POV-Ray will...
`F` | ...turn this user abort into a fatal error. Do the `Fatal_Error_Command`, if any. Exit POV-Ray with error code 1.
`U` | ...generate a user abort. Do the `User_Abort_Command`, if any. Exit POV-Ray with an error code 2.
`Q` | ..quit POV-Ray immediately. Acts as though POV-Ray never really ran. Do no further shells, (not even a `Post_Scene_Command`) and exit POV-Ray with an error code 0.

On return from a `Pre_Scene_Command` if there is an action triggered...

...and you have specified... | ... then POV-Ray will...
`S` | ...skip rendering all frames. Acts as though the scene completed all frames normally. Do not do any `Pre_Frame_Command` or `Post_Frame_Commands`. Do the `Post_Scene_Command`, if any. Exit POV-Ray with error code 0. On the earlier chart this means skip step #4.
`A` | ...skip all scene activity. Works exactly like `Q` quit. On the earlier chart this means skip to step #6. Acts as though POV-Ray never really ran. Do no further shells, (not even a `Post_Scene_Command`) and exit POV-Ray with an error code 0.

On return from a `Pre_Frame_Command` if there is an action triggered...

...and you have specified... | ... then POV-Ray will...
`S` | ...skip only this frame. Acts as though this frame never existed. Do not do the `Post_Frame_Command`. Proceed with the next frame. On the earlier chart this means skip steps (4b) and (4c) but loop back as needed in (4d).
`A` | ...skip rendering this frame and all remaining frames. Acts as though the scene completed all frames normally. Do not do any further `Post_Frame_Commands`. Do the `Post_Scene_Command`, if any. Exit POV-Ray with error code 0. On the earlier chart this means skip the rest of step (4) and proceed at step (5).

On return from a `Post_Frame_Command` if there is an action triggered...

...and you have specified... | ... then POV-Ray will...
`S` or `A` | ...skip all remaining frames. Acts as though the scene completed all frames normally. Do not do any further `Post_Frame_Commands`. Do the `Post_Scene_Command`, if any. Exit POV-Ray with error code 0. On the earlier chart this means skip the rest of step (4) and proceed at step (5).

On return from any `Post_Scene_Command` if there is an action triggered and you have specified `S` or `A` then no special action occurs. This is the same as `I` for this shell command.

Previous:Shell Command Sequencing Main Index Next:Text Output