Purpose

Basic Syntax: DDL for TDDES Keywords

DDL was devised ab initio as a flexible language extensible to other missions. Its flexibility and terseness do, however, make it easier to gain an understanding by specific example rather than by general exposition.

A typical string of DDL is a concatenation of tokens (denoted by single letters) with assigned values (enclosed in square brackets). For example, the TDDES2 keyword in science array files is used to describe the data in the second column. In the case of the SB_500us_50_249_2s PCA configuration, the value of TDDES2 is a DDL string which looks like this:

D[0~4] & E[X1L^X1R^X2L^X2R^X3L^X3R] & C[50~249] & T[0.0;0.00048828125;4096]

1. D - for Detector (PCU in this case)
2. E - for detector Element (xenon anode in this case)
3. C - for detector Channel
4. T - for Time

These tokens have values enclosed in square brackets and are concatenated with DDL's & symbol which means AND.

Let's look at the token values:

1. D[0~4] means that events were selected from PCU0-4 (DDL's ~ symbol delimits an accumulation range).

2. E[X1L^X1R^X2L^X2R^X3L^X3R] means that each event came from only one of the six xenon anodes (DDL's ^ symbol means EOR - exclusive or).

3. C[50~249] means that events were selected from channels 50-249.

4. T[0.0;0.00048828125;4096] means that each accumulation contains 4096 time-steps, 0.00048828125 seconds wide, with 0 offset.

It should be clear from this example that the meaning of a particular DDL string depends on context to some extent. We could associate the token D[0~4] with PCU0-4 because the file contains RXTE PCA data. In fact, this information is contained in the TDDES keyword, the value in this case being O[XTE] & I[PCA] (O and I are the Observatory and Instrument tokens, respectively).

DDL For Science Event Data

When used for TDDES keywords, DDL enumerates and describes selection criteria as used by the on-board electronics. When used for science event data - specifically for the TEVTB2 keyword - DDL describes how the data are structured in the file. Although DDL does not change meaning with usage, it is advisable to bear this distinction in mind when looking at a DDL string.

In general, when DDL is used for event words, each token corresponds to pieces of the event word template. The size (in bits) of each piece follows the token, enclosed in curly brackets. For example, D[0:4]{3} means that three bits are used to identify one of the five PCU (i.e., 000 for PCU0, 001 for PCU1, 010 for PCU2 etc). In this way, event word templates can be straightforwardly built up from various tokens. However, there are two necessary additions which complicate the template somewhat and which require additional explanation: M-tokens ("markers") and Z-tokens ("enumerators").

• M-tokens: RXTE science event files are not wholly filled with valid events: some rows contain error flags. Since these "non-events" do not have the same bit structure as the events, alternative event words must be used. DDL marks these alternatives by means of M-tokens.

  In the context of RXTE event words, M-tokens can be thought of as prefixes which distinguish alternative DDL strings. Thus the TEVTB2 keyword may consist of several alternative DDL strings, each prefixed by an M-token. By examining the M-token of a given row, software can tell which alternative event word template describes the structure of the row.

  M-tokens work like this. The M-token M[127]{8} means: The first 8 bits are used as a marker: if its value is 127 (01111111), then the immediately following template is the one that applies to the row. Similarly, the M-token M[4]{8} means: The first 8 bits are used as a marker: if its value is 4 (00000100), then the immediately following template is the one that applies to the row. By convention, the first marker in a string identifies a valid event. Its form is M[1]{1}, and, unlike the others in the string, it begins with 1. In practice, when software encounters a 1 in the very first bit of a row, it assumes the "event" template and doesn't interpret the rest of the string as a marker.

  Now let's look at an example - the TEVTB2 keyword for the E_1us_1M_0_1s configuration. For clarity, the M-tokens are emboldened and rearranged on the page to be at the beginning of each line:

  (M[1]{1},D[0:4]{3},T[0.0:0.00390625;9.5367431640625e-07]{12})
  (M[127]{8},S[One5]{5},S[FirstFlag]{1},S[SpillFlag]{1},S[Zero1]{1})
  (M[1]{8},S[LostEvents0]{8})
  (M[2]{8},S[LostEvents1]{8})
  (M[4]{8},S[Zero]{7},S[Spillage]{1})^
  (M[8]{8},S[Zero]{5},S[ModeSpecific]{3})
  

  The meaning should now be clear, but please note the following, additional points about M-tokens:
  • M-tokens and their associated DDL sub-strings are enclosed in parentheses, e.g. (M[8]{8},S[Zero]{5},S[ModeSpecific]{3}).

  • The sub-strings in this example are concatenated with DDL's ^ symbol, meaning EOR (exclusive or) and denoting that each string is an exclusive alternative.

• Z-tokens: The best way to explain Z-tokens in the RXTE context is by example. Let's consider a PCA configuration that offers PCU and anode ID. Based on the above, the corresponding DDL tokens in the TEVTB2 keyword would be:

  D[0:4]{3},E[X1L^X1R^X2L^X2R^X3L^X3R]{6}
  

  where, say, 100100000 would mean an event occurred in the X1L anode of PCU4. But given that there are 30 possible combinations of PCU and anode, using a total of nine bits is perhaps excessive. The purpose of Z-tokens is to enumerate these 30 combinations in a systematic way, making it easier for software to identify anode and PCU combinations - and saving disk space.

  The way Z-tokens are used is simple. In general:

  Z[A0, A1, A2... AN-1]{M}
  

  means that M bits are reserved in the template to enumerate a list of N items, where N is not greater than 2**M. In our example, the list items are the thirty combinations of PCU and anode:

Z[D[0]&E[X1L],D[0]&E[X1R],D[0]&E[X2L],D[0]&E[X2R],D[0]&E[X3L],D[0]&E[X3R],
  D[1]&E[X1L],D[1]&E[X1R],D[1]&E[X2L],D[1]&E[X2R],D[1]&E[X3L],D[1]&E[X3R],
  D[2]&E[X1L],D[2]&E[X1R],D[2]&E[X2L],D[2]&E[X2R],D[2]&E[X3L],D[2]&E[X3R],
  D[3]&E[X1L],D[3]&E[X1R],D[3]&E[X2L],D[3]&E[X2R],D[3]&E[X3L],D[3]&E[X3R],
  D[4]&E[X1L],D[4]&E[X1R],D[4]&E[X2L],D[4]&E[X2R],D[4]&E[X3L],D[4]&E[X3R]]
{5}