Overview | Package | File
| generated with STAXDoc v1.0.4

# test_ospl.xml

Function Summary
`Initialise` | This function must be called first in all functions or jobs.
`GetEnv` | Gets an environment value from a TestNode
`patch_release_dot_com` | Check that the release.
`InitialiseNode` | Initialise required data values of a particular TestNode within the current TestRun This will query the node for system variables and determine the required environment variables for a particular OSPL_HOME on that Node.
`StartOSPL` | Starts OpenSplice on a node.
`OSPLIsRunning` | Checks to see if OpenSplice is (already / now) running on a Node
`StopOSPL` | Stop OpenSplice on a TestNode.
`RetrieveProcessLog` | Manually retrieves process's logs.
`RunProcess` | Runs a Process on a TestNode 'synchronously'.
`RunOSPLStart` | Starts OpenSplice on a node.
`RunOSPLStop` | Stops OpenSplice on a node.
`SpawnProcess` | Asynchronously spawns a process without waiting for it to complete and returns the handle to the user & stores it on the passed Process.
`CheckProcessComplete` | Check an asynchronously started process has completed successfully with return code 0.
`PASS-if-0` | This function checks if a value is 0.

STAX Function Details

## Initialise

This function must be called first in all functions or jobs. It initialises variables, does various STAX and STAF jiggery pokery, and sets up the Python import path and imports the test classes module.

This function does not allow any arguments

The scope of this funcion is global rather than local so variables created here are all effectively exported. To avoid conflicts with variables in jobs prefix all used in local working with init_* and try and keep them to a min to avoid debugger clutter.

## GetEnv

Gets an environment value from a TestNode

This function takes a list of arguments
Name | Description | Required | Private | Default | Properties
--- | --- | --- | --- | --- | ---
the_node | Which TestNode to request the variable from | Yes | No | N/A |
the_variable_name | The env variable name required. | Yes | No | N/A |

Returns the variable value or empty string if it can't be resoved on the box.

## patch_release_dot_com

Check that the release.com script on posix platforms has had the @@INSTALLDIR@@ token removed and is executable.

This function takes a list of arguments
Name | Description | Required | Private | Default | Properties
--- | --- | --- | --- | --- | ---
the_node | Which TestNode to do the check on | Yes | No | N/A |
the_ospl_home | Optionally specify / override the OSPL_HOME to check. If not supplied use the value set globaslly for this node within this run. | No | No | '' |

Will replace the token and apply the permission if not.

## InitialiseNode

Initialise required data values of a particular TestNode within the current TestRun This will query the node for system variables and determine the required environment variables for a particular OSPL_HOME on that Node.

This function takes a single argument
Name | Description | Required | Private | Default | Properties
--- | --- | --- | --- | --- | ---
the_node | The TestNode that should be initialised | Yes | No | N/A |

This only needs doing opnce per TestNode but it shouldn't do any harm if it's repeated. Other than contributing to general patience trying.

## StartOSPL

Starts OpenSplice on a node. Optionally with a specific domain config.

This function takes a list of arguments
Name | Description | Required | Private | Default | Properties
--- | --- | --- | --- | --- | ---
the_node | Which TestNode instance to start OSPL on | Yes | No | N/A |
the_scenario | The TestScenario being run. | Yes | No | N/A |
ospl_conf_file | The file 'URL' of the OSPL config file. Note - this is not a real URL (i.e. it must be machine local on the target machine, not a path on your machine or the STAX controller). If not specified then OSPL is started with the default file as specified by the env property. | No | No | '' |
ospl_work_dir | A directory to start OSPL in. If you're not using default test locations it's important to set this if you want to be able to retrieve the ospl logs. | No | No | '' |

Returns a STAXResult of 0 on successful start or if the splice daemon was already running.

## OSPLIsRunning

Checks to see if OpenSplice is (already / now) running on a Node

This function takes a list of arguments
Name | Description | Required | Private | Default | Properties
--- | --- | --- | --- | --- | ---
the_node | Which node to check | Yes | No | N/A |
ospl_conf_file | The file 'URL' of the OSPL config file. Note - this is not a real URL (i.e. it must be machine local on the target machine, not a path on your machine or the STAX controller). If not specified then OSPL is started with the default file as specified by the env property. | No | No | '' |

Calls ospl list for the specified doamin URI and returns true if the result is > 0.

## StopOSPL

Stop OpenSplice on a TestNode. Optionally with a specific domain config or stop the default instance otherwise.

This function takes a list of arguments
Name | Description | Required | Private | Default | Properties
--- | --- | --- | --- | --- | ---
the_node | Which TestNode instance to stop OSPL on | Yes | No | N/A |
the_scenario | The TestScenario being run currently. | Yes | No | N/A |
ospl_conf_file | The file 'URL' of the OSPL config file. Note - this is not a real URL (i.e. it must be machine local on the target machine, not a path on your machine or the STAX controller box). If not specified then OSPL is started with the default file as specified by the OSPL_URI env property over there. | No | No | '' |
ospl_work_dir | A directory to start OSPL in. If you're not using default test locations for some reason it's important to set this if you want to be able to retrieve the ospl logs. | No | No | '' |

Returns a STAXResult of 0 on successful stop or if the splice daemon had already stopped running. Throws and exception otherwise.

## RetrieveProcessLog

Manually retrieves process's logs.

This function takes a list of arguments
Name | Description | Required | Private | Default | Properties
--- | --- | --- | --- | --- | ---
the_process | The Process instance that we need the logs for | Yes | No | N/A |

Retrieves the stdout & stdin output file created by the process from the remote machine back to the monitoring node.

## RunProcess

Runs a Process on a TestNode 'synchronously'. Process should be expected to complete within a reasonable time. Will timeout otherwise. Optional timeout can be specified.

This function takes a list of arguments
Name | Description | Required | Private | Default | Properties
--- | --- | --- | --- | --- | ---
the_process | The Process instance thatshould be run | Yes | No | N/A |
the_timeout | A timeout to wait for the process to complete. | No | No | '60s' |

Will return Process return code on successful completion. Will throw an exception if it times out or cannot be run for some reason.

## RunOSPLStart

Starts OpenSplice on a node.

This function takes a list of arguments
Name | Description | Required | Private | Default | Properties
--- | --- | --- | --- | --- | ---
location | The STAF URL of the machine of which you wish to start Vortex OpenSplice on | No | No | 'local' |
test_directory | Set a working directory where OSPL will be started. This is done to ensure the logs go somewhere logical. If this is not set to they'll end up whereever STAF was started from. | No | No | '' |
ospl_conf_file | The file 'URL' of the OSPL config file. Note - this is not a real URL (i.e. it must be machine local on the target machine). If not specified then OSPL is started with the default file as specified by the env property. | No | No | '' |

## RunOSPLStop

Stops OpenSplice on a node. Note 'ospl -a stop' is not supported as it is evil. If you want to do that go spawn yourself a process.

This function takes a list of arguments
Name | Description | Required | Private | Default | Properties
--- | --- | --- | --- | --- | ---
location | The STAF daemon URI of the machine of which you wish to stop a Vortex OpenSplice domain on. | No | No | 'local' |
ospl_conf_file | The optional file 'URL' of the OSPL domain config file. Note - this is not a real URL (i.e. it must be machine local). If not specified then OSPL is started with the default file as specified by the OSPL_URI env property. | No | No | '' |

## SpawnProcess

Asynchronously spawns a process without waiting for it to complete and returns the handle to the user & stores it on the passed Process.

This function takes a list of arguments
Name | Description | Required | Private | Default | Properties
--- | --- | --- | --- | --- | ---
the_process | The command of the process you want to start. | Yes | No | N/A |

Will throw an exception if the process fails to start.

## CheckProcessComplete

Check an asynchronously started process has completed successfully with return code 0. Terminate it if it hasn't.

This function takes a list of arguments
Name | Description | Required | Private | Default | Properties
--- | --- | --- | --- | --- | ---
the_process | The Process instance you want to check and stop. | Yes | No | N/A |

Will record an error and return the process RC if it hadn't terminated itself and returned 0. Will free handle resources in at all possible. Will only throw exception if the STAF service cannot be contacted.

## PASS-if-0

This function checks if a value is 0. If 0, it sets the testcase status result to 'pass'; otherwise, it sets it to 'fail' and sends a message to the STAXMonitor.

This function takes a single argument
Name | Description | Required | Private | Default | Properties
--- | --- | --- | --- | --- | ---
value | Value to compare with 0 | Yes | No | N/A |