using-the-asynchronous-system-exec.adoc

Using the Asynchronous System Exec

Welcome to the docs on how to use the Asynchronous System Exec library. Let’s dive in!

Library Overview

The Asynchronous System Exec API consists of a single class serenial.io-ase.lvlib:ase.lvclass

If you installed the library from VIPM then the ASE palette can be found in Functions >> Connectivity (alongside LabVIEW’s System Exec). If you haven’t installed via VIPM then you can use the class structure to find the API calls.

Figure 1. The VIPM-Installed Palette

Figure 2. The ase Class

Minimal Example

The absolutely most minimal example for the library consists of three VIs - Lookup Executable Path.vi, Start Call.vi and Conclude Call.vi.

These are the most important VIs to lets start here!

The code shown below will locate the PING.exe executable on the system’s PATH environmental-variable and call it asynchronously, passing it the arguments -n 5 127.0.0.1.

PING.exe will self-terminate after performing the specified five ping-operations of IP address 127.0.0.1 so the only other VI that must be called is Conclude Call.vi; This will wait for the ping executable to finish, clean up any internal resources and return the executable’s exit code.

Figure 3. A minimal example of using the Library

Please note the following;

• Not all executables will self-terminate! You might have to either send the termination signal using Send Terminate.vi or indicate via some other method, perhaps writing to or closing the Standard Input, that you want the executable to finish and exit.

• The ASE Handle inputs and outputs for library calls is by-reference i.e. you perform operations on the instance pointed to by the handle. This means that the ASE Handle wire can be branched without creating copies of the instance.

• If no Event References are passed to Start Call.vi then any data on the Standard Output or Standard Error is safely and silently discarded.

and finally

Warning

You must ensure that Conclude Call.vi is used when you have finished with the Asynchronous System Exec instance to guarantee all internal resources are de-allocated.

The Flexibility of Asynchronicity

You might be thinking - Huh, you said the library was asynchronous but we still have to wait at Conclude Call.vi? - Well, yes! That is true so lets see what else we can do.

The Wait on Call.vi allows for us to wait for the executable to exit but with a timeout specified in milliseconds. The VI is non-blocking so multiple calls to Wait on Call.vi will execute simultaneously.

In fact, Wait on Call.vi and Conclude Call.vi will not block any API calls so we can be flexible in how we structure our applications. This is illustrated with the example below;

Figure 4. Using the Wait-on-Call feature

What will happen when we run this example?

1. Start Call.vi launches the Windows Command Prompt asynchronously.

2. The execution will then split along three asynchronous branches A,B and C.

3. Branches A and B will wait on Conclude Call.vi and Wait on Call.vi respectively.

4. The Wait on Call.vi on branch C will wait for 200ms then Write to StdIn.vi followed by Send Terminate.vi will be called, the latter triggering the Command Prompt executable to exit.

5. After the Command Prompt has exited, Conclude Call.vi and Wait on Call.vi of branches A and B will complete and everything will resynchronize at the `Merge Errors`node.

Asynchronous Executable Events

Why are you holding out on me? Show me how to handle the Standard Output and Error already! - Certainly and kudos on your eagerness.

If you are interested in accessing the events generated by the executable then provide Start Call.vi with valid User Event References for any or all of the Standard Output, Standard Error and Did Exit events as shown in the code below.

Figure 5. Using User Events to access the Standard Output and Standard Error Data

Note	Ensure that you have already performed the "event registration" step before calling Start Call.vi to ensure that no events are missed

The VIs Create Event References.vi and Destroy Event References.vi are provided for convenience and it is safe memory-wise if only some of the registered events have an Event Case associated with them so long as the Event Structure is repeatedly executing in a loop or similar structure. These "unhandled" events will be silently discarded by LabVIEW when the Event Structure runs.

Configuration

The existing documentation has sofar described the behaviour with the default configuration options.

Figure 6. The Configuration Type-Def Cluster

Specification of an Event Identifier String

This identifier string is provided with each event allowing for the originator of an event to be easily identified when multiple Asynchronous System Exec events share the same Event References and Event Case Structure.

Specifying a unique value for each call of Start Call.vi provides an identifier to distinguish the source of events.

If you would like to see an alternative method to achieve something similar without using the ID string - take a look at this note

Figure 7. Using the ID-Configuration Parameter as an Event Identifier String for Event Aggregation

Custom Event Stream Split Character-Match Regular Expression

By default, the Standard Output and Standard Error streams are split on a newline character (\n) but this behavior can be changed to any valid PERL regular expression. For example, the expression [0-9] would split the stream on any numeric character.

Custom Windows Encoding Options

LabVIEW on Windows doesn’t have unicode enabled or well supported so the option is provided to convert unicode characters to characters that are supported according to the Window’s code page using the Window’s API’s WideCharToMultibyte call internally. This setting is ignored on Linux and the UTF-8 encoded data is always passed out to the LabVIEW code.