Defining a mapping layout

Restriction: This section applies to debugging OS/390 C/C++ programs only.

Defining a mapping layout is a two step process. In the first step you create the layout XML file. In the second step you add it to the master UserViews.XML file.

The example below defines the layout for the following C language structure on OS/390:

typedef struct {
  char char_val;
  unsigned short ushort_val;
  short short_val;
  unsigned long ulong_val;
  long long_val;
  char string_val[32];
} _test;

Creating the layout XML file

The XML file format is defined in the layout.dtd document type definition (DTD) file as follows:

<?xml version="1.0" encoding="ISO-8859-1"?>
  <!ELEMENT LAYOUT (FIELD)+>
  <!ATTLIST LAYOUT Header CDATA #REQUIRED View CDATA #IMPLIED length CDATA #REQUIRED numOfCells CDATA #IMPLIED fontsize CDATA #IMPLIED>
  <!ELEMENT FIELD (FIELD)*>
  <!ATTLIST FIELD
     Header CDATA #REQUIRED
     Type (16_BIT_INT|16_BIT_UINT|16_BIT_HINT|32_BIT_INT|32_BIT_UINT|32_BIT_HINT|32_BIT_FLOAT|64_BIT_INT|64_BIT_FLOAT|CHARACTER|HEX|ASCII|EBCDIC|STRUCTURE|PADDING|BIT|BITMASK|MAP) #REQUIRED
     length CDATA #REQUIRED
     layout CDATA #IMPLIED>

This means that the XML layout file would specify first a header (title) and the total length of the layout followed by a list of sub-elements (FIELD) described by a header (name), length and primitive type which is used to determine the default representation of that sub-element.

There are also special sub-element types:

STRUCTURE introduces a nested structure; the sub-element has no value
PADDING used to define a block of bytes that does not need to be specifically laid out
BITMASK used to define a bitmasked sub-element. Its sub-elements represent bits, groups, or bits defined by the BIT type.

The XML file describing a tree view of the _test structure and conforming to this format is:

<?xml version="1.0"?>
<!DOCTYPE LAYOUT SYSTEM "Layout.dtd" >
  <LAYOUT Header = "A Layout" length="17">
  <FIELD Header = "char_val" Type = "CHARACTER" length = "1" > </FIELD>
  <FIELD Header = "ushort_val" Type = "16_BIT_UINT" length = "2" > </FIELD>
  <FIELD Header = "short_val" Type = "16_BIT_INT" length = "2" > </FIELD>
  <FIELD Header = "ulong_val" Type = "32_BIT_UINT" length = "4" > </FIELD>
  <FIELD Header = "long_val" Type = "32_BIT_INT" length = "4" > </FIELD>
  <FIELD Header = "string_val" Type = "ASCII" length = "32"> </FIELD>
</LAYOUT>

The XML file describing a table, or cell, view of the _test structure and conforming to this format is:

<?xml version="1.0"?>
<!DOCTYPE LAYOUT SYSTEM "Layout.dtd" >
  <LAYOUT Header = "A Layout" View="CellView" length="17" numofCells="6" fontsize="12">
  <FIELD Header = "char_val" Type = "CHARACTER"length = "1" > </FIELD>
  <FIELD Header = "ushort_val" Type = "16_BIT_UINT"length = "2" > </FIELD>
  <FIELD Header = "short_val" Type = "16_BIT_INT"length = "2" > </FIELD>
  <FIELD Header = "ulong_val" Type = "32_BIT_UINT"length = "4" > </FIELD>
  <FIELD Header = "long_val" Type = "32_BIT_INT"length = "4" > </FIELD>
  <FIELD Header = "string_val" Type = "ASCII" length= "32"> </FIELD>
</LAYOUT>

Note: The <!DOCTYPE LAYOUT SYSTEM "Layout.dtd" > line specifies which DTD file is used to parse the contents of this file. If the Layout.DTD file is situated in a different location then the full path to that location must be specified.

Defining padding fields

If you decide to ignore the long_val field but want to show the string_val type in the layout, the XML file will look like:

  <FIELD Header = "short_val" Type = "16_BIT_INT" length = "2" > </FIELD>
  <FIELD Header = "ulong_val" Type = "32_BIT_UINT" length = "4" > </FIELD>
  <FIELD Header = "" Type = "PADDING" length = "4" > </FIELD>
  <FIELD Header = "string_val" Type = "ASCII" length = "32"> </FIELD>

The initial purpose for defining the PADDING sub-elements is to deal with byte aligned structures but it can also be used to skip a data area that does not need to be detailed in the layout.

Defining structures

The following piece of XML shows the usage of STRUCTURE fields for mapping nested structures. A structure top element does not have an associated value and it can be expanded to show its sub-elements. While the length of the STRUCTURE field is added to the total size of the XML layout, the included field sizes are intended for display only. For example, the following structure would only mean 344 bytes out of the total layout size.

<FIELD Header = "MACHINE CHECK LOG OUT AREA" Type = "STRUCTURE" length = "344" >
    <FIELD  Header="reserved" Type="HEX" length="16"></FIELD>
    <FIELD Header="FLCSID" Type="HEX" length="4"></FIELD>
    <FIELD Header="FLCIOFP" Type="HEX" length="4"></FIELD>
    <FIELD Header="reserved" Type="HEX" length="20"></FIELD>
    <FIELD Header="FLCESAR" Type="HEX" length="4"></FIELD>
    <FIELD Header="FLCCTSA" Type="HEX" length="8"></FIELD>
    <FIELD Header="FLCCCSA" Type="HEX" length="8"></FIELD>
    <FIELD Header="FLCMCIC" Type="HEX" length="8"></FIELD>
    <FIELD Header="reserved" Type="HEX" length="8"></FIELD>
    <FIELD Header="FLCFSA" Type="HEX" length="4"></FIELD>
    <FIELD Header="reserved" Type="HEX" length="4"></FIELD>
    <FIELD Header="FLCFLA" Type="HEX" length="16"></FIELD>
    <FIELD Header="FLCRV110" Type="HEX" length="16"></FIELD>
    <FIELD Header="FLCARSAV" Type="STRUCTURE"length="64">
        <FIELD Header="AR0" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR1" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR2" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR3" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR4" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR5" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR6" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR7" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR8" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR9" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR10" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR11" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR12" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR13" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR14" Type="HEX" length="4"></FIELD>
        <FIELD Header="AR15" Type="HEX" length="4"></FIELD>
  </FIELD>
  <FIELD Header="FLCFPSAV" Type="HEX" length="32"></FIELD>
  <FIELD Header="" Type="PADDING" length="64"></FIELD>
  <FIELD Header="" Type="PADDING" length="64"></FIELD>
</FIELD>

Defining bitmask fields

The following XML piece is a sample for describing BITMASK fields. The length of the BITMASK is specified in bytes and it contains a set of BIT fields for which the length is specified in bits. The offset shown for the BIT fields is a bit offset within the BITMASK field. While the length of the bitmask field is added to the total size of the XML layout, the individual BIT field sizes are intended for display only.

<FIELD Header="byte_field" Type="BITMASK"length="2">
  <FIELD Header="hi_byte" Type="BIT" length="8"></FIELD>
  <FIELD Header="lo_byte" Type="BIT" length="8"></FIELD>
</FIELD>

Defining nested layouts

The MAP field type together with the optional layout field, let you describe nested layouts as in the following OS/390 DSA layout example:

<?xml version="1.0"?>
<!DOCTYPE LAYOUT SYSTEM "Layout.dtd" >
<LAYOUT Header = "DSA" length="72">
<FIELD Header = "FLAGS" Type = "HEX" length = "2"></FIELD>
<FIELD Header = "junk" Type = "HEX" length = "2"></FIELD>
<FIELD Header = "Back Chain" Type = "MAP" length = "4"layout="dsa.xml" ></FIELD>
<FIELD Header = "Forward Chain" Type = "MAP" length ="4" layout="dsa.xml" ></FIELD>
<FIELD Header = "R14" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R15" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R0" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R1" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R2" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R3" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R4" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R5" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R6" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R7" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R8" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R9" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R10" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R11" Type = "HEX" length = "4"></FIELD>
<FIELD Header = "R12" Type = "HEX" length = "4"></FIELD>
</LAYOUT>

This well-formed XML layout is stored in a file called DSA.XML. Since you know that fields 3 and 4 contain pointers to different DSA structures you add two nested layout definitions.

Note: The actual storage mapping for that layout is actually executed when you expand the layout element for the first time in order to prevent recursive layout expansions.

Adding the new layout file to the list of available layouts

Once the XML layout file is ready it must be made visible to the Distributed Debugger through the UserViews.XML file. The DTD for this file follows:

<?xml version="1.0" encoding="ISO-8859-1"?>
  <!ELEMENT CLASSES (CLASS)+>
  <!ATTLIST CLASSES Total CDATA #REQUIRED>
  <!ELEMENT CLASS EMPTY >
  <!ATTLIST CLASS Name CDATA #REQUIRED ActionLabel CDATA #REQUIRED>

It defines a list of XML layout file and label pairs. The XML layout file is the full path to the required layout file while the label is used when you select a storage mapping.

If you want to add the TestLayout.XML file to the UserViews.XML file, the final result looks like:

<?xml version="1.0"?>
<!DOCTYPE CLASSES SYSTEM "Classes.dtd" >
<CLASSES Total="2"> 
<CLASS Name = "OtherLayout.XML" ActionLabel = "other layout"></CLASS>
<CLASS Name = "TestLayout.XML" ActionLabel = "_test C structure"></CLASS>
</CLASSES>

Note: Specifying the .XML at the end of the XML layout file name is required.

Once the XML file is added to the UserViews.XML file it will be available from the Map Storage dialog.