[ Intro | Pubs | RunInfo | Workbook | Software | SLACVX | Search ]

The SLD Event Display Additions Manual

Adding Relations

To define new relations among data in the SLD event display system, you generally just need to add a DSPUSRR bank. (If the data being related is connected in some very obscure way, it may be necessary to write a new "relations routine," but for most cases, the existing eight generic relations routines can do the job.)

In discussing relations, a key concept is the PARENT. A display object's parent is the Jazelle bank that contains the data from which the object was drawn. For example, the draw routine PHDTNUM draws numbers at the end of tracks based on the PHTRK banks. So each number's parent is the relevant PHTRK bank. The draw routine DSPDMCT draws monte carlo tracks based on the MCPART banks. So each track's parent is the relevant MCPART bank.

When the DSPUSRT constants are set up, the name of the parent bank is stored in PATH. Then, when the draw routine is called, each object gets the pointer to its parent bank stored into DSPOBJ%(PARENT). Thus, when it comes time to do relations, for each object the display system has the parent bank's name and pointer. (Parent and path gets a little more complicated for "repeat block objects." See "Repeat Block Objects in the SLD Event Display System" for details.)

A DSPUSRR bank is simply a way of defining how one can get from the parent of one object type to the parent of its related object type. For example, the third DSPUSRR bank in PHUDSP CONSTANT defines how one relates PHPARTs to PHTRKs.

The Contents of DSPUSRR

• ACTION (optional, defaults to patch) is usually PATCH. This means that the new relations will be merged into any other relations already established. If you instead specify action as REPLACE, any previously defined relations will be deleted.
• OBJNAM1 and OBJNAM2 are the two objects that are to be related. These should correspond to the IDENTs in the DSPUSRT blocks.
• RELNAME should be a unique identifier for this relation definition.
• RELTYPE should be one of the above eight generic relations types.
  The existing eight generic relations types are as follows:
  • SIMPTR, for SIMple PoinTeR relation, handles cases in which a simple pointer connects the two parents. It looks for a pointer called ARG(1) in the parent bank of OBJNAM1.
  • BLKPTR, for BLocK PoinTeR relation, handles cases in which a pointer in a block connects the two parents. It looks for a pointer called ARG(2) in a block called ARG(1) in the parent bank of OBJNAM1.
  • RELTAB, for RELational TABle, handles cases in which a relational table connects the two parents. It looks for keys called ARG(3) and ARG(2) in a relational table bank called ARG(1).
  • PRLLID, for PaRaLLel ID, handles cases in which the two parents have the same bank ID. It needs no additional arguments.
  • SAMEOBJ, for SAMe OBJect relation, handles cases in which the two objects have the exact same parent. It needs no additional arguments.
  • SIMKEY, for SIMple KEY relation, handles cases in which a simple key connects the parents. It looks for a key called ARG(1) in the parent bank of OBJNAM1.
  • SIMIND, for SIMple INDex relation, handles cases in which an index connects the two parents. It looks for an index called ARG(1) in the parent bank of OBJNAM1.
  • BLKSIN, for BLocK Single INdex relation, handles cases in which object 1 is a "repeat block object." See "Repeat Block Objects in the SLD Event Display System" for details.

  The way in which your two objects are connected can probably be handled by one of the above eight generic relations. But if this is not the case, you will have to write a new relations routine. The structure of such routines can vary greatly. The names of the routines that do the generic relations can be found in DSPRELT CONSTANT (look at RELATER). Take these routines as your examples and consider getting help from TONYJ. Once the routine is written, include it in DSPREFS PREPMNLB and make a new bank for it in DSPRELT CONSTANT.

• NADDARG is the number of additional arguments to come (may be zero). It depends on the RELTYPE (just discussed). For each of these arguments, provide one ADDARG block containing one ARG string.

When you run your job, pull in your new relations by issuing the IDA command DSP USERDATA followed by the filename of the file that contains the DSPUSRR banks.

For each DSP USERDATA statement, you should get a message telling you that the relation names have been loaded. If you then do DSP SHOW RELations, you should see your new relation names. If your new relations definitions don't appear, check whether you've correctly spelled the constant file name.

If DSP SHOW RELations shows your new relation definitions, you have succeeded. You may do the new relations via a DSP REL command. If you are using the display in 3D interactive mode, you can do the new relations from the data selection menu.

If you get into trouble, check that PARENT has been properly set in the draw routines and that PATH has been correctly defined in the DSPUSRT constants.