Entities are symbolic names that are used to insert text into a file.

>>-<!ENTITY--+---+--entity-name--+-SYSTEM--+------------+--+---->
             '-%-'               |         '-"filespec"-'  |   
                                 '-| Entity text options |-'   

>-->-----------------------------------------------------------><

Entity text options

|--+-------+--+-------+--+---------+--+-----------+--+-----+--+------+--"entity-text"--|
   '-CDATA-'  '-SPACE-'  '-REPLACE-'  '-COPIES(n)-'  '-X2C-'  '-ATTR-'                  

ENTITY

Indicates this is an entity declaration.

%

Indicates a parameter entity declaration, which must be followed by at least one space.

entity-name

The name of the entity. It must follow these rules:

• Length
  • 1-8 for file embed entity names
  • 1-8 for parameter entity names
  • 1-17 for other entity names
• The first character must be A-Z, a-z, @, #, or $.
• Remaining characters, if any, can be A-Z, a-z, @, #, $, or 0-9.

  When an entity name is more than 8 bytes in length, one or more of the remaining characters must be an underscore.

• Entity names are case-sensitive.
• The entity name for a parameter entity can be specified as a variable name (that is, %&varname;). The resolved name must follow the parameter entity naming rules.

CDATA

Indicates that any delimiter characters in entity-text are not interpreted as delimiters. This allows you to define entities with tags in entity-text that are not interpreted as tags.

For example the entity-text "<panel>" is not interpreted as the PANEL tag if the CDATA keyword is used.

The effect of CDATA is to delay substitution of the variable until all other text manipulation is completed. For example, you should use CDATA to specify an entity-text string of blanks as normal text processing removes leading and trailing blanks from text strings.

Note: CDATA cannot be used with parameter entities.

SPACE

Indicates that entity-text which spans multiple DTL source file records is formatted like the <p> tag. (Leading and trailing blanks on entity-text lines are compressed to a single blank character.) In addition, multiple blanks between words of entity-text are compressed to a single blank character.

REPLACE

Indicates that the current entity-text is to replace any previous definition of the same entity name.

COPIES(n)

Indicates that the entity-text is to be expanded by repeating the provided text n times. For example, including COPIES(5) as a keyword with the text specified as "*" causes the entity text to be processed as "*****".

X2C

Indicates that the specified hex format entity-text is to be converted to character format. Non-valid hex values are processed as a regular entity character string.

ATTR

Indicates that the specified entity-text is a CUA text attribute. Valid values are: CH, CT, DT, ET, FP, NT, PIN, PT, SAC, SI, WASL, and WT. These values are converted to their corresponding attribute byte. Non-valid attribute codes are processed as a regular entity character string.

"entity-text"

The text associated with the entity reference. The text must be enclosed in single or double quotes. The length of the entity-text must be less than or equal to 253 bytes.

SYSTEM

Indicates this entity refers to an external file.

"filespec"

The name of the file the entity refers to. The name must be enclosed in single or double quotes. If this is not specified, it defaults to the name of the entity.

The SYSTEM parameter can optionally be followed by the file name for the included file. The file name for MVS™ is a member name for a file provided on the invocation panel or specified as "DTLGML" entries in the ISPDTLC profile.