NxLibCommand

class NxLibCommand

This class simplifies the execution of NxLib commands. The parameters() and result() functions provide access to the corresponding parameter and result nodes of the tree. The execute() method starts the command by writing the command name to the tree and allows for synchronous and asynchronous command execution. The wait() method waits for commands executing asynchronously.

Public Functions

inline explicit NxLibCommand(std::string const &_commandName, std::string const nodeName = "")
Parameters

  • _commandName – Name of the command to execute. This can be overwritten by the execute() methods.

  • nodeName – Name of the execution slot the command should run in. By default the class will create a temporary slot used only by this instance of NxLibCommand, which is automatically deleted in the destructor.

inline NxLibItem const &slot() const

The slot returns the NxLibItem the NxLibCommand is running on.

Returns

NxLibItem the command runs on.

inline const NxLibItem parameters() const

The command’s parameters , that will be fetched before the command executes.

Returns

NxLibItem, in which the parameters are stored.

inline void rememberParameters(bool remember = true)

Remember parameters across command executions in this slot by setting the persistent parameters node.

As documented, command parameters are cleared when the command is finished executing. This is disadventageous in case a command is executed multiple times with (mostly) identical parameters.

Parameters

remember – If true, parameters are kept across command execution. If false, parameters are reset during command execution.

inline const NxLibItem status() const

The command’s status node.

Returns

NxLibItem, in which the command status gets published.

inline const NxLibItem result() const

The command’s result node after the command finishes.

Returns

NxLibItem, in which the results are stored.

inline void cancel(bool _wait = true) const

Cancels the current current command. Only works on commands, that support the Break command.

Parameters

_wait – If true, the function waits until execution of the command is finished. If set to true, the function will also throw an NxLibException if the command finished with an error.

inline void cancel(int *returnCode, bool _wait = true) const

Cancels the current execution of the command.

Parameters

  • returnCode – The error code of the cancel operation.

  • _wait – If true, the function waits until execution of the command is finished. If set to true, the function will also throw an NxLibException if the command finished with an error.

inline void execute(bool _wait = true) const

Executes the current command.

Parameters

_wait – If true, the function waits until execution of the command is finished. If set to true, the function will also throw an NxLibException if the command finished with an error.

inline void execute(int *returnCode, bool _wait = true) const

Executes the current command.

Parameters

  • returnCode – The error code of the execution.

  • _wait – If true, the function waits until execution of the command is finished. If set to true, the function will also throw an NxLibException if the command finished with an error.

inline void execute(char const *_commandName, bool _wait = true) const

Executes the command with the given name.

Parameters

  • _commandName – Name of the command to execute. This overwrites the command name from the constructor.

  • _wait – If true, the function waits until execution of the command is finished. If set to true, the function will also throw an NxLibException if the command finished with an error.

inline void execute(int *returnCode, char const *_commandName, bool _wait = true) const

Executes the command with the given name.

Parameters

  • returnCode – The error code of the execution.

  • _commandName – Name of the command to execute. This overwrites the command name from the constructor.

  • _wait – If true, the function waits until execution of the command is finished. If set to true, the function will also throw an NxLibException if the command finished with an error.

inline void execute(std::string const &_commandName, bool _wait = true) const

Executes the command with the given name.

Parameters

  • _commandName – Name of the command to execute. This overwrites the command name from the constructor.

  • _wait – If true, the function waits until execution of the command is finished. If set to true, the function will also throw an NxLibException if the command finished with an error.

inline void execute(int *returnCode, std::string const &_commandName, bool _wait = true) const

Executes the command with the given name.

Parameters

  • returnCode – The error code of execution.

  • _commandName – Name of the command to execute. This overwrites the command name from the constructor.

  • _wait – If true, the function waits until execution of the command is finished. If set to true, the function will also throw an NxLibException if the command finished with an error.

inline void executeAsync() const

Start asynchronous execution of the current command.

This function is equivalent to execute(returnCode, false).

inline void executeAsync(int *returnCode) const

Start asynchronous execution of the current command.

This function is equivalent to execute(returnCode, false).

Parameters

returnCode – The error code of starting the execution.

inline void executeAsync(std::string const &_commandName) const

Start asynchronous execution of the command with the given name.

This function is equivalent to execute(_commandName, false).

Parameters

_commandName – Name of the command to execute. This overwrites the command name from the constructor.

inline void executeAsync(int *returnCode, std::string const &_commandName) const

Start asynchronous execution of the command with the given name.

This function is equivalent to execute(returnCode, _commandName, false).

Parameters

  • returnCode – The error code of starting the execution.

  • _commandName – Name of the command to execute. This overwrites the command name from the constructor.

inline bool finished() const

Checks whether the command execution has already finished.

Returns

true, when NxLib is not currently executing a command in slot(), i.e. the command node is Null. Otherwise false.

inline bool finished(int *returnCode) const

Checks whether the command execution has already finished.

Parameters

returnCode – The API return code .

Returns

true, when NxLib is not currently executing a command in slot(), i.e. the command node is Null. Otherwise false.

inline void wait(int *returnCode) const

Waits for the command execution to finish.

command.executeAsync(&returnCode);
if (returnCode == NxLibOperationSucceeded) {
  command.wait(&returnCode);
}
is equivalent to 
command.execute(&returnCode);

Parameters

returnCode – The API return code .

inline void wait() const

Waits for the command execution to finish. The function will throw an NxLibException if the command finished with an error.

command.executeAsync();
command.wait();
is equivalent to 
command.execute();

inline void assertSuccessful() const

Checks whether the previous command execution is finished and was successful and throws an NxLibException if not.

inline bool successful() const

Checks whether the previous command execution was successful.

Returns

true, when the previous NxLib command execution was successful, i.e. there is no ErrorSymbol node under the Result node. Otherwise false.

inline bool successful(int *returnCode) const

Checks whether the previous command execution was successful.

Parameters

returnCode – The API return code .

Returns

true, when the previous NxLib command execution was successful, i.e. there is no ErrorSymbol node under the Result node. Otherwise false.

Public Members

std::string commandName

Name of the command to execute.