Index Page DLA Required Reading

## Table of Contents

       DLA Required Reading
          Abstract
          Intended audience
          Related Documents
          Introduction
       DLA Files
          DLA File Structure
             The DLA File Record
             DLA Comment Area
             DLA Format Version
             DLA Forward and Backward Pointers
             DLA Segment Descriptors
          DLA Segment Layout
       DLA Functions
             Summary of DLA Mnemonics
             Summary of DAS Mnemonics
             Summary of Calling Sequences
       Appendix A: Revision History
             2017 APR 03 by N. J. Bachman

Top

# DLA Required Reading

Last revised on 2017 APR 03 by N. J. Bachman.

Top

## Abstract

The ``Doubly Linked Array'' (DLA) SPICE file format enables data in a DAS file to be treated as a doubly linked list of virtual arrays, where each virtual array may contain integer, double precision, and character components.

Top

## Intended audience

This document is intended primarily for SPICE users who wish to gain a detailed understanding of the DLA format, particularly users who wish to create DSK files and sophisticated SPICE users who wish to create their own DLA-based file formats.

It may also be of interest to SPICE users who wish to access the segment-oriented functions of the DSK subsystem; however, such users may find adequate guidance in the code examples provided in API documentation of those DSK functions and of the DLA functions referenced by DSK documentation.

Users of DSK files can find documentation of the DSK interface functions in the DSK Required Reading file, dsk.req.

Top

## Related Documents

The following documents pertinent to DLA usage are included in the SPICE Toolkit:

`--` DAS Required Reading

`--` DSK Required Reading

`--` Convert User's Guide

`--` COMMNT User's Guide

Top

## Introduction

The SPICE Doubly Linked Array (DLA) subsystem consists of a Fortran 77 direct access file format and a set of functions that make it convenient to create, read, annotate, and transport files having this format. The same DLA file format is used by all language versions of SPICE.

The DLA file format is an instance of the DAS architecture. DLA files enable user application software to view the data in a DAS file as a doubly linked list of virtual arrays, usually called ``segments,'' where each segment may contain character, double precision, and integer components.

DLA segments provide a mechanism for grouping related data. For example, in the SPICE DSK format, which is a specialization of the DLA format, data are grouped into segments; each DSK segment is a DLA segment as well. DSK segments contain data representing shapes of extended objects. Such representations may use both integer and double precision data. For example, in DSK data type 2, segments contain double precision numbers that represent the vertex coordinates of triangular plates, and integers that indicate which vertices belong to each plate.

DLA files may be thought of as a functional generalization of DAF files: DAF arrays contain only double precision data; DLA segments contain data of multiple types. However, there are some differences that prevent either format from being a special case of the other:

`--` DLA is based on the DAS low-level architecture

`--` DAS access methods differ from DAF methods

`--` DLA descriptors contain only segment location and size information; DAF descriptors contain both location information and information describing segment contents.

Applications can locate DLA segments by means of forward or backward linear searches. DLA functions are provided to start a forward or backward search, and to find the next or previous segment relative to a given segment.

In the CSPICE Toolkit, functionality that makes use of DLA segments' data is provided by higher-level code, as is the case for the DSK subsystem.

Top

# DLA Files

This chapter discusses details of the DLA file format.

Top

## DLA File Structure

DLA files are a special case of DAS files; they inherit all of the characteristics of DAS files. DAS files, once they have been written, are normally ``segregated,'' meaning that the character, double precision, and integer records of a DAS file form three contiguous components of the respective data types. See the DAS Required Reading, das.req, for details.

The underlying DAS architecture, in its segregated form, is:

            File component          Record count
            ==============          ============

       +------------------------+
       |      file record       |   ( 1 )
       +------------------------+
       |    reserved records    |   ( variable )
       +------------------------+
       |    comment records     |
       |                        |   ( variable )
       |                        |
       +------------------------+
       | first data directory   |   ( 1 )
       +------------------------+
       | character data records |
       |                        |   ( variable )
       |                        |
       +------------------------+
       |   d.p. data records    |
       |                        |   ( variable )
       |                        |
       +------------------------+
       |  integer data records  |
       |                        |   ( variable )
       |                        |
       +------------------------+

The DLA format presents a higher-level view of the DAS architecture. For most purposes, DLA files can be thought of as having the following logical components:

       +----------------------------+
       |       file record          |
       +----------------------------+
       |       comment area         |
       |                            |
       |                            |
       +----------------------------+
       | DLA format version         |
       +----------------------------+
       | DLA forward and backward   |
       | pointers                   |
       +----------------------------+
       | DLA descriptors            |
       +----------------------------+
       | first virtual DLA segment  |
       +----------------------------+
       | second virtual DLA segment |
       |                            |
       |                            |
       +----------------------------+
                  ...
       +----------------------------+
       | last virtual DLA segment   |
       |                            |
       +----------------------------+

The diagram above does not show the physical order of the segments, since segment data are distributed across the character, double precision, and integer records of the file, and since DLA descriptors are interleaved with DLA segments' integer components.

Details of these components are discussed below.

Top

### The DLA File Record

In a DLA file, the file record conforms to the DAS file record format. See the DAS Required Reading, das.req, for a complete description of this format. Within the file record, the ID word has the format

       DAS/xxxx

where the pattern

       xxxx

represents up to four printing characters identifying the file type. For example, in DSK files, the ID word is

       DAS/DSK

In general the portion of the ID word indicating file type need not indicate explicitly that the file is a DLA file. That fact can be derived from the file type string if the type is known to the SPICE system.

Top

### DLA Comment Area

All properties of the DLA comment area are inherited from the DAS architecture. DAS functions are used to access the comment area programmatically. The SPICE COMMNT utility can access the DLA comment area interactively.

Top

### DLA Format Version

The first member of a DLA file's integer address space is a parameter indicating the format version of the file. The primary purpose of this parameter is to indicate that the file is a DLA file. If the format is updated, this version will allow SPICE software to identify the version and access the file appropriately.

SPICE identifies DLA files using a combination of three attributes:

`1.` The file architecture, which must be DAS

`2.` The file type, which must be recognized as one derived from the DLA format, for example DSK

`3.` The DLA format version

Top

### DLA Forward and Backward Pointers

The segments of a DLA file are organized as a doubly linked list. The DLA file contains pointers to data structures called ``segment descriptors,'' which are associated with segments, at the head and tail of the list. These pointers are used to initiate forward and backward searches.

Top

### DLA Segment Descriptors

A DLA ``segment descriptor,'' or simply ``descriptor,'' is a small array of integers that indicate the sizes and addresses of the components of a corresponding DLA segment. A DLA descriptor also contains integers that act as forward and backward pointers to other DLA descriptors in the DLA file's doubly linked segment list.

DLA descriptors are also data structures used as input and output arguments of DLA functions. They are also used extensively as arguments to DSK functions; the DSK subsystem is currently the only other SPICE subsystem where they're used. In the Fortran, IDL, and MATLAB SPICE Toolkits, DLA descriptors are implemented as arrays. In the CSPICE Toolkit, DLA descriptors are implemented by the structure SpiceDLADescr.

The DLA segment descriptor members are:

       +---------------+
       | BACKWARD PTR  | Linked list backward pointer
       +---------------+
       | FORWARD PTR   | Linked list forward pointer
       +---------------+
       | BASE INT ADDR | Base DAS integer address
       +---------------+
       | INT COMP SIZE | Size of integer segment component
       +---------------+
       | BASE DP ADDR  | Base DAS d.p. address
       +---------------+
       | DP COMP SIZE  | Size of d.p. segment component
       +---------------+
       | BASE CHR ADDR | Base DAS character address
       +---------------+
       | CHR COMP SIZE | Size of character segment component
       +---------------+

The ``base address'' of a segment component of a given data type is the address, in the DAS address space of that type, preceding the first element of that component. All DAS addresses are 1-based.

The general form of the doubly linked list layout in DAS integer address space is:

                     +------------------------------+
                     |  Pointer to first descriptor | ----+
                     +------------------------------+     |
       +-------------|  Pointer to last descriptor  |     |
       |             +------------------------------+     |
       |                                                  |
       |             +------------------------------+     |
       |  NULL <---- |  Backward pointer            | <---+ First node
       |       +---> |                              |
       |       |     +------------------------------+
       |       |     |  Forward pointer             | ----+
       |       |     +------------------------------+     |
       |       |     |  Rest of DLA Descriptor 1    |     |
       |       |     +------------------------------+     |
       |       |     |  Segment 1 integer component |     |
       |       |     +------------------------------+     |
       |       +---- |  Backward pointer            | <---+ Second node
       |       +---> |                              |
       |       |     +------------------------------+
       |       |     |  Forward pointer             | ----+
       |       |     +------------------------------+     |
       |       |     |  Rest of DLA Descriptor 2    |     |
       |       |     +------------------------------+     |
       |       |     |  Segment 2 integer component |     |
       |       |     +------------------------------+     |
       |  pointer from third node                     <---+ Third node
       |                            .
       |                            .
       |                            .
       |  pointer to node N-1                  pointer from node N-1
       |       |                                          |
       |       |     +------------------------------+     |
       +--->   +---- |  Backward pointer            | <---+ Final (Nth) node
                     +------------------------------+
                     |  Forward pointer             | ----> NULL
                     +------------------------------+
                     |  Rest of DLA Descriptor N    |
                     +------------------------------+
                     |  Segment N integer component |
                     +------------------------------+

While this diagram shows the presence of multiple segments, a DLA file need not contain more than one segment. It is valid, but usually not useful, for a DLA file to have no segments.

Top

## DLA Segment Layout

The data populating a DLA file are stored in the file's segments.

The segments of a DLA file consist of components in the respective DAS character, double precision, and integer address spaces. The components occupy contiguous address ranges in the respective address spaces.

The general form of the DLA segment layout is:

       Character space   Double precision space   Integer space

       +-------------+   +--------------------+
       |Segment 1    |   |Segment 1           |  +------------+
       |character    |   |double precision    |  |Segment 1   |
       |component    |   |component           |  |integer     |
       +-------------+   |                    |  |component   |
       |Segment 2    |   |                    |  |            |
       |character    |   +--------------------+  |            |
       |component    |   |Segment 2           |  +------------+
       |             |   |double precision    |
       +-------------+   |component           |  +------------+
                         +--------------------+  |Segment 2   |
                                                 |integer     |
                                                 |component   |
                                                 +------------+
            ...                   ...                 ...

In the diagram above, the first integer segment component is displaced downward slightly to indicate that the first component starts at an integer address greater than 1: that component is preceded by other information. DLA descriptors lie between consecutively numbered integer components, so those components are not contiguous.

Any of the segment components may be empty, but the DAS integer address space is never empty.

In a segregated DLA file, all segment components of a given type are stored sequentially in the DAS address space of that type.

Top

# DLA Functions

Access to DLA files is provided by DLA functions and functions of the SPICE DAS subsystem.

In all languages supported by SPICE, the DLA subsystem provides functions for traversing DLA segment lists. Although the term is somewhat inaccurate, this is usually referred to as ``searching'' the lists.

Functions of the DAS subsystem enable applications to open a DLA file for read access, close a DLA file, and extract comments from a DLA file's comment area.

In the Fortran and C SPICE Toolkits, DAS functions can open an existing DLA file for write access and delete or write to a DLA file's comment area.

In the Fortran SPICE Toolkit, DLA functions are provided to open a new DLA file and to start and finish new DLA segments. DAS functions are provided to write data to DLA segments, read data from DLA segments, and update data in existing DLA segments.

Top

### Summary of DLA Mnemonics

All of the API functions in the DLA family have names beginning with the letters ``dla,'' followed by a two- or three-character mnemonic and the suffix ``_c.'' For example, the function that starts a forward search through the segment descriptor list in a DLA file is named dlabfs_c. The following is a list of CSPICE DLA mnemonics and translations, in alphabetical order.

       bbs  Begin backward search
       bfs  Begin forward search
       fns  Find next segment
       fps  Find previous segment

Top

### Summary of DAS Mnemonics

The DAS functions whose mnemonics are listed below serve as part of the CSPICE DLA system's interface.

       ac   Add comments from buffer to file
       cls  Close file
       dc   Delete comments from file
       ec   Extract comments from file
       opr  Open file for read access
       opw  Open file for write access

Top

### Summary of Calling Sequences

Calling sequences of the DLA family of functions are given below. Functions are grouped according to function.

The following functions are intended for use by both CSPICE users' application programs and by CSPICE functions.

Opening and closing files:

       dascls_c ( handle )
       dasopr_c ( fname, handle )
       dasopw_c ( fname, handle )

Searching for segments:

       dlabbs_c ( handle, descr, found )
       dlafns_c ( handle, descr, nxtdsc, found )
       dlafps_c ( handle, descr, prvdsc, found )
       dlabfs_c ( handle, descr, found )

Accessing the comment area:

       dasac_c ( handle, n, buffer )
       dasdc_c ( handle )
       dasec_c ( handle, bufsiz, n, buffer, done )

Top

# Appendix A: Revision History

Top

### 2017 APR 03 by N. J. Bachman

Initial release.