System Debug Reference Manual > Chapter 2 User Interface

Data Types

	MPE documents
	Complete PDF
	Table of Contents
	Index

	E0201 Edition 4
	E0300 Edition 3 ♥
	E0692 Edition 3

Several data types are supported by System Debug. This section introduces each of the types by giving the mnemonics by which they are known, along with a description of the data which they represent.

Integer Types

Three sizes of signed and unsigned integers are supported:

S16: Signed 16-bit integer.
U16: Unsigned 16-bit integer.
S32: Signed 32-bit integer.
U32: Unsigned 32-bit integer.
S64: Signed 64-bit integer.

All of the signed types obey the properties of twos complement binary arithmetic. The type S64 has not been fully implemented, and it supports only those values in the range -2⁵²..2⁵² - 1. Other than this restriction, S64 values behave as if they consume 64 bits.

Boolean Type

Data of type BOOL may assume the values TRUE and FALSE. Integer values also are generally accepted where BOOLs are called for, and when this occurs, zero (0) is taken to be FALSE; all other values are TRUE.

String Types

The type STR is used to represent variable-length character (text) data. Strings quoted with single and double quotes (' and ") represent literal text. But strings quoted with the back-quote character (`) are sometimes interpreted as regular expressions, which are used to match other text. Refer to appendix A for a discussion of how patterns and regular expressions can be constructed for use in pattern matching.

Pointer Types

System Debug supports many different kinds of pointer types, but most are actually variations of the same theme. Pointers come in two sizes, long and short, and both may be interpreted quite differently depending on the current mode of System Debug.

The most frequently used pointer types are long pointer (LPTR) and short pointer (SPTR). An LPTR is simply a pair of 32-bit numbers separated by a dot, sometimes called a dotted pair. What the two numbers actually mean is unspecified by the type. Instead, the context in which the LPTR is used determines the meaning. An SPTR is just one 32-bit number, and it is often thought of as being the low-order (rightmost) part of an LPTR. When used in CM, both long and short pointer values are often range-checked to verify that they fit within 16 bits.

The remaining pointer types are variations of long pointers (that is, they are all dotted pairs). However, unlike LPTRs, they project an additional meaning on the dotted pair. Since the interpretation of pointers is heavily dependent on the mode of System Debug, the rest of this discussion deals with each mode individually.

Compatibility Mode Pointers

An LPTR in CM is usually a segment.offset. If a CM LPTR refers to data, then the segment number is the DST number of the addressed data segment, and the offset is the CM word offset from the beginning of the segment. If a CM LPTR refers to code, there are many possible interpretations of the segment number, and without additional information the LPTR is ambiguous. It is for this reason that the additional long pointer types exist. Their purpose is to differentiate LPTRs. Most users who work with CM code are probably familiar with the logical code segment numbers assigned by the Segmenter. The Segmenter's -PREP command assigns logical code segment numbers to program file segments, while the -ADDSL command assigns logical code segment numbers to SL file segments. These segment numbers always begin with zero (0) in each program or SL file. System Debug allows users to refer to loaded CM code using these logical code segment numbers through use of the following logical code pointer types:

PROG: Program file long pointer.
GRP: Group library file long pointer.
PUB: Public library file long pointer.
LGRP: Logon group library file long pointer.
LPUB: Logon public library file long pointer.
SYS: System library file long pointer.

Logon group and public libraries are loaded only by the CM LOADPROC intrinsic.

The above long pointer subtypes are by far the preferred choice for specifying code addresses. Since System Debug also displays CM code addresses logically, it usually is not necessary to refer to CM code segments by the CST/CSTX segment numbers assigned to them by the CM loader. However, low-level system debugging sometimes requires this method of addressing, and it is supported by the following absolute code pointer types:

CST: Absolute CST long pointer.
CSTX: Absolute CSTX long pointer.

CM program segments are assigned numbers in the CSTX, while CM SL segments are assigned numbers in the CST. CST and CSTX segment numbers start with 1. The following illustration depicts the relationships between CM logical code segment numbers and absolute ones.


   Logical              Absolute       Absolute             Logical
   System Library       CST            CSTX                 Program
   Segments             Segments       Segments             Segments

   +-------+           +--------+     +--------+           +--------+
   | SYS 0 |  ----->   | CST 1  |     | CSTX 1 |  <-----   | PROG 0 |
   |       |           | sys 0  |     | prog 0 |           |        |
   +-------+           +--------+     +--------+           +--------+
   | SYS 1 |  --+      | CST 2  |     | CSTX 2 |  <-----   | PROG 1 |
   |       |    |      | sys 5  |     | prog 1 |           |        |
   +-------+    |      +--------+     +--------+           +--------+
   | SYS 2 |    |      | CST 3  |     | CSTX 3 |  <-----   | PROG 2 |
   |       |    |      | sys 11 |     | prog 2 |           |        |
   +-------+    |      +--------+     +--------+           +--------+
   |       |    +-->   | CST 4  |     | CSTX 4 |  <-----   | PROG 3 |
   |       |           | sys 1  |     | prog 3 |           |        |
   +-------+           +--------+     +--------+           +--------+
   | SYS n |           | CST 5  |
   |       |           |        |
   +-------+           +--------+
                       | CST 6  |
                       |        |
                       +--------+
   Logical             |        |
   Group Library       |        |
   Segments            +--------+
                +-->   | CST 74 |
                |      | grp 0  |
   +-------+    |      +--------+
   | GRP 0 |  --+      | CST 75 |  <-+
   |       |           | grp 3  |    |
   +-------+           +--------+    |
   | GRP 1 |  ----->   | CST 76 |    |
   |       |           | grp 1  |    |
   +-------+           +--------+    |
   | GRP 2 |                         |
   |       |                         |
   +-------+                         |
   | GRP 3 |  -----------------------+
   |       |
   +-------+

Note that the following pairs specify the same segment:


    (logical)  PROG 1   <-->   CSTX 2   (absolute)
    (logical)  SYS  1   <-->   CST  4   (absolute)
    (logical)  GRP  3   <-->   CST  75  (absolute)

Native Mode Pointers

An LPTR in NM is usually a sid.offset virtual address. As such, NM LPTRs are unambiguous, even without some context of use. However, it is still useful to tag NM long pointers to code by using a type that expresses the code's logical origin. Thus, the following logical code pointer types are available for NM code addresses:

PROG: Program file long pointer.
GRP: Group library file long pointer.
PUB: Public library file long pointer.
SYS: System library file long pointer.
USER: User library file long pointer.
TRANS: Translated CM code long pointer.

Individual space IDs (SIDs) are assigned to each loaded NM program or library file by the NM loader. These numbers should be expected to be different each time the files are loaded. The LOADINFO command displays the relationships between loaded NM code files and their assigned SIDs.

Note the following differences between CM and NM logical code pointers. First, the CM types LGRP and LPUB do not exist for NM code, since addresses of this type are generated only by the CM LOADPROC intrinsic. Next, the types USER and TRANS are specific to NM. USER is a long pointer to a location in a user library file which was loaded by the XL= option of the RUN command. Since more than one such user library may be loaded, the type USER also includes the name of the user library file with which the long pointer is associated. Finally, the type TRANS is used to refer to a location in NM code which was translated from CM. Although the original CM code came from either a CM program file or one of the group, PUB or SYS SL files, the type TRANS gives no information about which one. A conversion function, NMTOCMNODE, can be used to convert NM TRANS addresses to CM logical code pointers, which reveal the originating CM code locations. Refer to appendix C for a discussion of CM object code translation node points and breakpoints in translated CM code. Finally, the types CST and CSTX do not apply to NM code. The analogous NM type is simply an NM LPTR.

Extended Address Types

The extended addres (EADDR) type is available for cases where the 32-bit offset part of a long pointer isn't large enough. An EADDR is a dotted pair, where the offset part to the right of the dot is 64 bits wide. An EADDR is effectively equivalent to an LPTR when it's offset part is representable in 32 bits. The secondary address (SADDR) type is a special form of EADDR, where the dotted pair is interpreted as a disk LDEV and disk byte offset. This is currently the only instance where an extended address is necessary.

Type Classes

All of the elementary data types introduced above are organized into type classes. These classes are particularly useful when defining parameters to functions and macros. By declaring a parameter to be of a particular type class, all actual values passed are automatically checked to be a member of the class.

The type tables below give the names of the type classes and show which elementary types belong to them.

Table 2-1 Type Table

Class		Type
`INT`		`S16`	Signed 16-bit integer.
`INT`		`U16`	Unsigned 16-bit integer.
`INT`		`S32`	Signed 32-bit integer.
`INT`		`U32`	Unsigned 32-bit integer.
`INT`		`S64`	Signed 64-bit integer.
`BOOL`		`BOOL`	Boolean.
`STR`		`STR`	Variable-length character string.
`PTR`		`SPTR`	Short pointer (offset).
`PTR`	`LONG`		Long pointer subclass. See table below.
`EADDR`		`EADDR`	Extended address.
`EADDR`		`SADDR`	Secondary address.

Table 2-2 Long Pointers

Class			Type
`LONG`			`LPTR`	Long pointer
`LONG`	`CPTR`			Code pointers
`LONG`	`CPTR`	`LCPTR`		Logical code pointers
`LONG`	`CPTR`	`LCPTR`	`PROG`	Program file
`LONG`	`CPTR`	`LCPTR`	`GRP`	Program group library
`LONG`	`CPTR`	`LCPTR`	`PUB`	Program account library
`LONG`	`CPTR`	`LCPTR`	`LGRP`	Logon group library
`LONG`	`CPTR`	`LCPTR`	`LPUB`	Logon account library
`LONG`	`CPTR`	`LCPTR`	`SYS`	System library: `SL`(CM), `NL`(NM)
`LONG`	`CPTR`	`LCPTR`	`USER`	User library (NM)
`LONG`	`CPTR`	`LCPTR`	`TRANS`	Translated object code (NM)
`LONG`	`CPTR`	`ACPTR`		Absolute Code Pointers
`LONG`	`CPTR`	`ACPTR`	`CST`	Absolute `CST` (CM only)
`LONG`	`CPTR`	`ACPTR`	`CSTX`	Absolute `CSTX` (CM only)

Command Line Overview

Literals