Output descriptors and text units

An output descriptor, which the system creates or deletes when you invoke dynamic output, includes one or more text units. Each text unit represents a set of SYSOUT processing options. Thus, the output descriptor represents all the SYSOUT processing options associated with an invocation of dynamic output.

To select particular SYSOUT processing options, you must code the corresponding text units. A text unit consists of at least four consecutive fields:

key:: A two-byte field that identifies the SYSOUT processing options.
count:: A two-byte field that specifies the number of length/value field pairs.
length:: A two-byte field that specifies the size of the value field.
value:: A variable length data field that qualifies the SYSOUT processing option.

Figure 1 shows a group of text units and the text unit pointers that reference them. The leftmost bit of the last pointer must be 1.

Figure 1. Text Units and Text Unit Pointers

For an invocation of dynamic output, the text unit keys must be unique. To be unique, a text unit cannot have the same key that another text unit has. If two or more text units have the same key, dynamic output returns a return code X'0C' and a reason code X'30E'.

A text unit can have one or more length/value field pairs. Each length/value field pair represents a SYSOUT processing option. The following example shows a text unit that has one value field:

DC XL2'0001'       KEY FOR BURST OPTION
DC XL2'0001'       COUNT OF VALUE FIELDS
DC XL2'0001'       LENGTH OF VALUE FIELD
DC XL1'02'         VALUE FIELD: BURST=YES

For some keys, the length/value field may be repeated. The following example shows a text unit that has two length/value fields:

DC XL2'0002'       KEY FOR 'CHARS' OPTION
DC XL2'0002'       COUNT OF VALUE FIELDS=2
DC XL2'0004'       LENGTH OF FIRST VALUE FIELD
DC CL4'TAB1'       FIRST VALUE FIELD
DC XL2'0004'       LENGTH OF SECOND VALUE FIELD
DC CL4'TAB9'       SECOND VALUE FIELD

If you need a DSECT to define text unit fields symbolically, use the IEFDOTUM mapping macro described in z/OS MVS Data Areas in the z/OS Internet library.