Data Lines

A data line is the simplest type of output processed by the PUTLINE service routine. It is simply a line of text to be written to the terminal. PUTLINE does not format the line or process it in any way; it merely writes the line, as it appears, out to the terminal. Use the DATA operand on the PUTLINE macro instruction to indicate that the output line is a data line.

There are two kinds of data lines, single line data and multiline data; each is handled differently by the PUTLINE service routine.

Single Line Data: Single line data is one contiguous character string that PUTLINE places out to the terminal as one logical line. If the line of data you provide exceeds the terminal line length, the PUTLINE service routine segments the line and puts it out as several terminal lines. PUTLINE accepts single line data in the format shown in Figure 1.
Figure 1. PUTLINE Single Line Data Format

You must precede your line of data with a 4-byte header field. The first two bytes contain the length of the output line, including the header; the second two bytes are reserved for offsets and are set to zero for data lines.

Pass the address of the output line to the PUTLINE service routine by coding the beginning address of the four-byte header as the OUTPUT operand address in either the list or the execute form of the macro instruction. When the macro instruction expands, it places this data line address into the second word of the PUTLINE parameter block.

Figure 1 is an example of the code that could be used to write a single line of data to the terminal using the PUTLINE macro instruction. Note that the execute form of the PUTLINE macro instruction is used in this example to construct the input/output parameter list, and that the TERMPUT operands are not coded in either the list or the execute form of the macro instruction; the default values will be assumed by the PUTLINE service routine.
Multiline Data: Multiline data is a chain of single lines. Each line of data is processed by the PUTLINE service routine exactly as if it were single line data. Each element of the chain, however, begins a new line to the terminal. By specifying multiline data (MULTLIN) in the PUTLINE macro instruction, you can put out several variable-length, non-contiguous lines at the terminal with one execution of the macro instruction. PUTLINE accepts multiline data in a format similar to that of single line data except that each line is prefaced with a fullword forward chain pointer. Figure 2 shows the format of PUTLINE multiline data.
Figure 2. PUTLINE Multiline Data Format

Each of the forward-chain pointers points to the next data line to be written to the terminal. The forward-chain pointer in the last data line contains zeros. In the case of multiline data, you pass the address of the output line to the PUTLINE service routine by coding the beginning address of the first forward-chain pointer as the OUTPUT operand address in either the list or the execute form of the macro instruction. When the macro instruction expands, it places this multiline data address into the second word of the PUTLINE parameter block.

Figure 2 is an example of the code required to write multiple lines of data to the terminal using the PUTLINE macro instruction.

Note that the programmer has built his own IOPL rather than build it with the execute form of the PUTLINE macro instruction. Note also the use of the IOPL and CPPL DSECTs (generated by the IKJIOPL and IKJCPPL macro instructions). These provide an easy method of accessing the fields within the IOPL and the CPPL, and they protect your code from changes made to the control blocks.