t Next OLD

... PTPB

..

~ Length

I

I

I

~

I I I

+ Segment n

~r----"""T'""----'r---

From PTPB

t

Number

+ Segment 1

+ Segment 2 I

I

~

M u I t i-Level Messages

00000000 Number

+ Segment 1

+

I ^I

I I

I I

I t

~

Figure 12-25. Control Block Structures for PUTLINE Messages

12-50 TSOjE Guide to Writing a TMP or a CP

PUTLINE Message Line Processing

In addition to writing a message out to the terminal, the PUT LINE service routine provides the following additional functions for message line (INFOR) processing:

• Message identification stripping

• Text insertion

• Formatting only

• Second level informational chaining

Figure 12-26 shows the distribution of these PUTLINE service routine functions over the two output message types.

Message Types

Functions Single Level Multilevel

Message ID Stripping x x

Text Insertion x x

Formatting Only x

Second Level Informational Chaining x

Figure 12-26. PUTLINE Functions and Message Types

Stripping Message Identifiers: The user indicates whether or not he wants message identifiers displayed at the terminal. The use does this with the PROFILE command. (See TSOjE Command Language Reference and TSOjE

User's Guide.) If the terminal user indicates no message identifiers are to be displayed, the PUTLINE service routine strips them off the message before wri ting the message to the terminal.

A message identifier must be a variable-length character string, containing no leading or embedded blanks, must not exceed a maximum length of 255 characters, and must be terminated by a blank.

Messages without message identifiers must begin with a blank. A message beginning with a blank is handled by the PUTLINE service routine as a message that does not require message identifier stripping, regardless of what the user at the terminal has requested. If you do not provide a message identifier, and do not begin your message with a blank, the beginning of your message up to the first blank will be stripped off by the PUT LINE service routine if message identifier stripping is requested from the terminal. If the message segment does not contain at least one blank, PUTLINE will return a code of 12 (invalid parameters) in register 15, even if message ID stripping is not requested from the terminal.

The following examples show the effects of the PUTLINE message identifier stripping function.

If you provide message identifiers on your messages and the terminal user does not request message ID stripping, your message will appear at the terminal exactly as it appears here:

MESSAGEOOIO THIS IS A MESSAGE.

Chapter 12. Using the TSO I/O Service Routines for Terminal I/O 12-51

If the user at the terminal requests message ID stripping, the message will appear as:

THIS IS A MESSAGE.

If you do not want to use message identifiers on your output messages, begin your message with a blank. A message beginning with a blank is unaffected by a terminal user's request for message ID stripping and will appear as you wrote it, minus the blank.

Using the PUTLINE Text Insertion Function: The text insertion function of the PUTLINE service routine allows you to build or modify messages at the time you put them out to the terminal. With text insertion you can respond to different output message requirements with one basic message (the primary segment). You can insert text into this primary segment or add text to it, and thereby build an output message to meet the current processing situation.

To use text insertion you pass your messages to the PUTLINE service routine as a variable number of text segments -- from 1 to 255 segments are permissible.

Each segment may contain from 0 to 255 characters, however, the total number of characters in all the segments must not exceed 256. You must precede each of these text segments with a four-byte header: the first two bytes containing the length of the message, including the header, and the second two bytes containing an offset value. The offset value in the primary segment must be zero. The offset in any secondary segments may be from zero to the length of the primary

segment's text field. An offset of zero in a secondary segment implies that the segment is to be placed before the primary segment. An offset that is equal to the length of the primary segment's text field implies that the secondary segment is to be placed after the primary segment. An offset of n, where n represents a value greater than zero but less than the total length of the primary segment, implies that the segment is to be inserted after the nth byte of the primary segment.

PUTLINE places the secondary segment after that character, completes the message, and puts it out to the terminal.

If you specify an offset in a secondary segment, greater than the length of the primary segment, PUTLINE cannot handle the request and returns an error code of 12 (invalid parameters) in register 15. If the secondary segments do not appear in the OLD with their offsets in ascending order, PUTLINE returns an error code of 12 (invalid parameters) in register 15.

If you provide more than one secondary segment to be inserted into a primary segment, the offset fields on each of the secondary segments must indicate the position within the original primary segment at which you want them to appear.

PUTLINE determines the points of insertion by counting the characters of the original primary segment only. As an example, if you provided one primary and two secondary segments as shown:

2 bytes 2 bytes 28 bytes

32 0 PLEASE ENTER TO PROCESSING

9

I

13 17 CONTINUE

12-52 TSO/E Guide to Writing a TMP or a CP

~ EN

TV<

PUTLINE would place the first insert, TEXT, after the 13th character, and the second insert, CONTINUE, after the 17th character of the text field of the primary segment. After PUTLINE inserts the two text segments, the message would read:

PLEASE ENTER TEXT TO CONTINUE PROCESSING

The leading and trailing blanks are automatically stripped off before the message is written to the terminal.

Figure 12-27 is an example of the code required to make use of the text insertion feature of the PUTLINE service routine; it uses the text segments shown above.

Note that the operand INFOR, which indicates to the PUTLINE service routine that the text segments are to be processed as informational messages, requires an output line descriptor to point to the message segments. Only one output line descriptor (ONEOLD) is required to point to the 3 message segments because the