J002 Using sample writers

Sample writers help you to insert samples of various data types (integers, float, arrays, structs, text,...) into your defined signals.

---

---

To insert samples into a defined signal you need to perform the following steps:

• Acquire writers for the signals you want to fill   
• Open the writers
• Optionally add enumeration and member information
• Write samples
• Close the writers

See 02 Signal Basics for more about signals.

---

---

Getting the writer for a signal

Usually when defining a signal (optional "createWriter" parameter is set to true), a writer is created in background. To get the writer, just use the getWriter method. In the other case you need to create the writer explicitly with createWriter.

---

Interface

ISamplesWriter getWriter(Signal signal);
ISamplesWriter createWriter(Signal signal);
ISamplesWriter createWriter(Signal signal, ProcessType processType, 
	SignalType signalType, SignalDescriptor signalDescriptor, IDomainBase domainBase);

---

Examples

// Java (reader derived from IRecordGenerator, ISingleDomainRecordGenerator)
Scope signals = addScope(null, "External Signals");
Signal clk = addSignal(signals, "Clk", "", 
	ProcessType.Discrete, SignalType.Logic, SignalDescriptor.DEFAULT);
ILogicSamplesWriter writer = (ILogicSamplesWriter) getWriter(clk);
// JavaScript (recJs, scripted reader,..)
var signals = generator.addScope(null, "External Signals");
var clk = generator.addSignal(signals, "Clk", "",
	ProcessType.Discrete, SignalType.Logic, SignalDescriptor.DEFAULT);
var writer <:ILogicSamplesWriter:> = generator.getWriter(clk);

The writer object depends on the signal type. The writer could be of type:

• Logic: ILogicSamplesWriter
• Float, FloatArray: IFloatSamplesWriter
• Integer, IntegerArray: IIntegerSamplesWriter
• Struct: IStructSamplesWriter
• Event, EventArray: IEventSamplesWriter
• Text, TextArray: ITextSamplesWriter
• Binary: IBinarySamplesWriter

Open JavaDoc Reference

---

Opening and closing writers

If you are using a ISingleDomainRecordGenerator, you can open and close all signals at one. In case multiple domain (IRecordGenerator) you need to open and close all used writers manually.
Signals may be discrete or continuous. Discrete means that each sample can be at any position of the given domain base with the restriction:

position(sample(idx)) <= position(sample(idx+1))

Continuous signal have a start, end and rate indicator. Therefor the position of each sample is definite. Discrete signal just have start and end indicators. Each sample contains the delta position to its predecessor.

• start,end: Domain position as a multiple of its domain base (e.g. domain base=1ms; units = 100; -> domain value = 100ms).
• rate: Domain distance as a multiple of its domain base.

---

Interface

// ISingleDomainRecordGenerator
void open(long start);
void open(long start, long rate);
void close(long end);
// ISamplesWriter
boolean open(long start);
boolean open(long start, long rate, ... ); 	// ignore the additional parameters 
    										// (set to 0 or null)
void close(long end);

---

Examples

// Java (reader derived from IRecordGenerator, ISingleDomainRecordGenerator)
initRecord("my record",TimeBase.ns);
open(0);
// write ...
close(1000); // at 1 us
// JavaScript (recJs, scripted reader,..)
generator.initRecord("my record",TimeBase.ns);
generator.open(0);
// write ...
generator.close(1000); // at 1 us

---

---

Legend: Setting enumeration values and defining array members

The legend of a signal contains information like string representations of enumeration value and member information of arrays and struct signals.

• enumerationGroup: Enumeration group, 0 for global enumeration.
• label: String representation of the enumeration.
• id: Index/Id of the member.
• name: Name of the member
• content Content description of the member, or null.
• format Format specifier defining how to render the value (e.g. ISample.FORMAT_DECIMAL).

---

Interface

// ISamplesWriter
boolean setEnum(int enumerationGroup, String label, int value);
boolean setMember(int id, String name, String content, int format);

---

Examples

// Java (reader derived from IRecordGenerator, ISingleDomainRecordGenerator)
writer.setEnum(Enumeration.ENUM_GLOBAL,"yes",1);
writer.setMember(0,"x",null,ISample.FORMAT_DEFAULT);
// JavaScript (recJs, scripted reader,..)
writer.setEnum(Enumeration.ENUM_GLOBAL,"yes",1);
writer.setMember(0,"x",null,ISample.FORMAT_DEFAULT);

For the enumerationGroup group you may choose one of the following values. ENUM_GLOBAL is used for normal enumerations. You may choose ENUM_MEMBER_0 + member id for enumeration that are only valid for one member (array or struct member).
A member is defined by its id (index in case of arrays), a member name, an optional content information and the format descriptor (describes the textual representation of the value).

public static final int ENUM_MIN = 0; 
public static final int ENUM_GLOBAL = 0;
public static final int ENUM_ASSOC_TARGET = 1;
public static final int ENUM_ASSOC_STYLE = 2;
public static final int ENUM_LABEL_STYLE = 3;
public static final int ENUM_MEMBER_0 = 8;
public static final int ENUM_MAX = Short.MAX_VALUE;

---

---

Writing samples

The interface to write a samples depends on the signal type (see above overview of sample writer interfaces).

• units: Domain position as a multiple of its domain base (e.g. domain base=1ms; units = 100; -> domain value = 100ms). Consecutive calls need to pass a value greater or equal.
• conflict: If set to true, impulse will use conflict color (usually red) to paint the sample. Meaning of "conflict" is use-case depended.

---

Interface

// ISamplesWriter
boolean write(long units, boolean conflict, ... value ... );

---

Examples

// Java (reader derived from IRecordGenerator, ISingleDomainRecordGenerator)
Signal val = addSignal(signals, "val", "", ProcessType.Discrete, SignalType.Float, 
	SignalDescriptor.DEFAULT);
IFloatSamplesWriter writer = (IFloatSamplesWriter) getWriter(val);
generator.open(0);
writer.write(500,false,4.5);
close(1000); // at 1 us
// JavaScript (recJs, scripted reader,..)
var val = generator.addSignal(signals, "val", "", ProcessType.Discrete, 
	SignalType.Float, SignalDescriptor.DEFAULT); 
var writer <:IFloatSamplesWriter:> = generator.getWriter(val);
generator.open(0);
writer.write(1000,false,4.5);
generator.close(1000); // at 1 us

The next chapters (J03 ... ) will cover the usage of the different writer interfaces.

---