LIST—write lines to the list data set

The LIST service allows a dialog to write data lines directly (without using print commands or utilities) to the ISPF list data set. You specify the name of the dialog variable containing the data to be written on the LIST service request. The amount of data that can be written with one LIST request is one or more lines totaling up to 32 767 bytes, the maximum size of the dialog variable.

The list data set, if allocated, is normally processed when you exit ISPF. A LIST command is available to allow you to process the list data set without exiting ISPF.

Command invocation format


>>-ISPEXEC--LIST--BUFNAME(dialog-variable-name)----------------->

                                   .-SINGLE-.   
>--LINELEN(line-length)--+------+--+-DOUBLE-+------------------->
                         '-PAGE-'  '-TRIPLE-'   

>--+----------+--+----+----------------------------------------><
   '-OVERSTRK-'  '-CC-'

Call invocation format


>>-CALL--ISPEXEC--(buf-len,--buffer);--------------------------><


>>-CALL--ISPLINK--('LISTbbbb'--,--dialog-variable-name,--------->

                                    .-'SINGLEbb'-.   
>--line-length--,-+-'PAGEbbbb'-+--,-+-'b'--------+-------------->
                  '-'b'--------'    +-'DOUBLEbb'-+   
                                    '-'TRIPLEbb'-'   

>--,-+-'OVERSTRK'-+--,-+-'NObbbbbb'-+-);-----------------------><
     '-'b'--------'    '-'b'--------'

Parameters

dialog-variable-name: Specifies the name of the dialog variable that contains the text (32,767 bytes maximum) to be written to the list data set.
line-length: Specifies the length of each line in the buffer being passed to ISPF. ISPF truncates these lines if the line-length specified is greater than the truncation value in system variable ZLSTTRUN. The line-length must have an unsigned integer value and, for a call, must be a fullword fixed integer.
PAGE: Specifies that the first data line of this LIST service request is to be written to the list data set preceded by a page eject carriage control character. The spacing of the remaining lines is determined by the SINGLE, DOUBLE, or TRIPLE keyword specified. PAGE is ignored if the CC keyword is specified.
SINGLE: Specifies that each line of data is to be written to the list data set preceded by a single space carriage control character. SINGLE is the default line spacing keyword value. SINGLE is ignored if the CC keyword is specified.
DOUBLE: Specifies that each line of data is to be written to the list data set preceded by a double space carriage control character. DOUBLE is ignored if the CC keyword is specified.
TRIPLE: Specifies that each line of data is to be written to the list data set preceded by a triple space carriage control character. TRIPLE is ignored if the CC keyword is specified.
OVERSTRK: Specifies that each line of data is to be written with overstrikes. That is, the line is first written with the line spacing specified, then written again with the line spacing suppressed. This allows a dialog to request text highlighting on printed output. OVERSTRK is ignored if the CC keyword is specified.
CC: Specifies that carriage control is to be provided by the dialog as the first byte of each data line. Specifying CC nullifies specification of the PAGE, SINGLE, DOUBLE, TRIPLE, or OVERSTRK keyword. If CC is specified, the value specified for line-length should include one byte for the carriage control character.
buf-len: Specifies a fullword fixed binary integer containing the length of "buffer".
buffer: Specifies a buffer containing the name of the service and its parameters in the same form as they would appear in an ISPEXEC call for a command procedure.

Return codes

These return codes are possible:

0: Normal completion.
8: Maximum line length or data set LRECL exceeded; data has been truncated.
12: Specified dialog variable not found.
20: Severe error.

Formatting data to be written to the list data set

ISPF writes data to the list data set exactly as received in the dialog variable, which acts as the data buffer. The dialog must provide any data formatting or centering before passing the data to ISPF. The length of each data line passed to ISPF is the value of the line-length parameter specified on the LIST service request. If the line-length value is greater than or equal to the length of the passed data, ISPF writes the data as a single line in the list data set. If the line-length value is less than the length of the passed data, ISPF writes the data in multiple lines. If the line-length value specified is zero and CC is not specified, ISPF writes one blank line to the list data set. If CC is specified, the line length specified must be at least one (to accommodate the carriage control character); otherwise, a severe error results.

List data set characteristics affect the LIST service

The dialog user can specify the logical record length (LRECL) and maximum line length values for the list data set by using SETTINGS option 0. ISPF uses these two values in determining where truncation of lines written to the list data set is to occur.

The value in system variable ZLSTTRUN defines where ISPF is to truncate lines written to the list data set. This value is not directly alterable by the dialog. The value in ZLSTTRUN is the lesser of:

LRECL minus 1 (fixed-record format data sets) or LRECL minus 5 (variable-record format data sets)
The logical record length can be established for the list data set before the ISPF session (by preallocating the data set), or, if that is not the case, it can be specified on SETTINGS option 0.
LINE LENGTH - Default value specified on SETTINGS option 0.

Controlling line spacing, page eject, and highlighting

Line spacing and page ejects can be under control of either the dialog or ISPF. If the dialog specifies CC on the LIST service request, the dialog controls all carriage functions, using the first byte of each line passed to ISPF as a carriage-control character. Therefore, when CC is specified on the LIST service request, ISPF ignores any SINGLE, DOUBLE, TRIPLE, PAGE, and OVERSTRK keywords.

ISPF causes an automatic page eject (regardless of CC keyword status) for a LIST service request that causes information to be written to a list data set for the first time in the session.

How ISPF controls printer functions (CC not specified)

When the dialog does not specify CC on the LIST service request, ISPF appends a carriage control byte ahead of each line to be written to the list data set.

The dialog can include the SINGLE, DOUBLE, or TRIPLE keyword on the LIST service request to tell ISPF how lines are to be spaced when written to the list data set. Single spacing is the default value. The dialog can also specify, along with the line spacing keyword, the OVERSTRK keyword on the LIST service to cause highlighting.

The optional PAGE keyword on the LIST request tells ISPF that the first line written by this request is to include a page eject control character. Thereafter, page ejects are caused by:

ISPF providing the page eject carriage control when the lines-per-page value (1 to 999) in system variable ZLSTLPP is reached, or
The dialog specifying the PAGE keyword on a subsequent LIST service request.

How the dialog controls printer functions (CC specified)

When the dialog specifies CC on the LIST service request, ISPF ignores any other printer control keywords. ISPF then relies on the dialog to supply the printer control information as the first byte of each line in the data buffer to be written. ISPF does not check the validity of the characters included for carriage control.

Using system variables ZLSTNUML and ZLSTLPP

ZLSTNUML: This 4-byte shared pool variable contains the number of lines that have been written to the current page in the list data set. If the list data set is not open the value in ZLSTNUML is zero.
ZLSTNUML is set by ISPF and is not directly alterable by a dialog.
ZLSTLPP: This 4-byte shared pool variable contains the value that specifies what the maximum number of lines per page written to the list data set is to be.
You can set the value in ZLSTLPP (lines-per-page) by using SETTINGS option 0. ZLSTLPP is not directly alterable by a dialog.

Dialogs that provide carriage control characters can test variables ZLSTNUML and ZLSTLPP for values to determine when printing should begin on a new page.

The ANSI-defined carriage control characters in the chart shown are recognized by the LIST service for updating (incrementing the number of page line spaces used) the value of ZLSTNUML. If the dialog passes any other carriage control character along with the CC keyword, the character is written to the list data set, but does not affect the value of ZLSTNUML.

The carriage control characters, whether supplied to ISPF with each line to be printed or supplied by ISPF, cause the actions listed in the chart shown:

  Character    Action (before printing)   ZLSTNUML is
  blank          Space 1 line          Incremented 1
  0              Space 2 lines              "      2
  -              Space 3 lines              "      3
  +              Suppress spacing      Not changed
  1              Skip to line 1        Set to 1
                   on new page

How carriage control characters affect truncation

ISPF counts only data characters, not the carriage-control character, in calculating the point at which truncation is to occur. A dialog can determine what the truncation value is by querying system variable ZLSTTRUN in the shared variable pool.

The carriage-control byte must be taken into account when calculating where truncation will occur. For example, assume that the truncation value in ZLSTTRUN is 79, indicating that a maximum of 79 characters per list data set line, not including carriage-control, are allowed. Also, assume the dialog passes a line of 80 characters to be written to the list data set. Truncation is as follows:

If the dialog has specified the CC (carriage-control) keyword on the LIST request, the first byte in the line passed to ISPF is the carriage-control character, followed by 79 data characters. Because ISPF does not count the carriage-control character as one of the truncation value (79), no truncation occurs.
If the dialog has not specified the CC keyword, ISPF appends the carriage-control byte ahead of the line of 80 data characters passed by the dialog. In this case, the truncation value of 79 causes one data character to be truncated.

Examples

Example 1

Using three LIST service requests, write three lines, containing the text 'Line 1', 'Line 2', and 'Line 3' respectively, to the list data set. The text is to start at the top of a new page, and be double spaced.

In preparation:

Set dialog variable LINE1 to the value 'Line 1'
Set dialog variable LINE2 to the value 'Line 2'
Set dialog variable LINE3 to the value 'Line 3'

Then issue:

ISPEXEC LIST BUFNAME(LINE1) LINELEN(6) PAGE
ISPEXEC LIST BUFNAME(LINE2) LINELEN(6) DOUBLE
ISPEXEC LIST BUFNAME(LINE3) LINELEN(6) DOUBLE

or alternately

Set variable LEN to 6 and issue:

CALL ISPLINK ('LIST    ','LINE1 ',LEN,'PAGE    ');
CALL ISPLINK ('LIST    ','LINE2 ',LEN,' ','DOUBLE  ');
CALL ISPLINK ('LIST    ','LINE3 ',LEN,' ','DOUBLE  ');

Example 2

Write the same three lines as in Example 1, but with one LIST service request.

In preparation, set dialog variable LSTTEXT to the value:

   'Line 1Line 2Line 3'

Then issue:

ISPEXEC LIST BUFNAME(LSTTEXT) LINELEN(6) PAGE DOUBLE

or alternately

Set variable LEN to 6 and issue:

CALL ISPLINK ('LIST    ','LSTTEXT ',LEN,'PAGE    ','DOUBLE  ');

Example 3

Write the same three lines as in the previous examples, but with the carriage control characters being passed to ISPF.

In preparation, set dialog variable LSTTEXT to the value:

   '1Line 10Line 20Line 3'

The characters '1' and '0' preceding the word 'Line' in LSTTEXT are carriage control characters for page eject and double space respectively.

Then issue:

ISPEXEC LIST BUFNAME(LSTTEXT) LINELEN(7) CC

or alternately

Set variable LEN to 7 and issue:

CALL ISPLINK ('LIST    ','LSTTEXT ',LEN,' ',' ',' ','CC      ');

Note that the line-length value has been increased by one to account for the carriage control byte.

Example 4

Print the same three lines as in Example 3. This time, assume that ZLSTTRUN has a value of 5. In preparation, set up conditions to cause the value of ZLSTTRUN to be 5. This value is the lesser of:

The logical record length of the list data set minus one (fixed format) or the record length minus five (variable format).
The value specified for list data set line length using SETTINGS option 0.

LSTTEXT is set the same way, and the LIST request issued the same way, as for Example 3. The difference in data written to the list data set for Example 4 compared to Example 3 illustrates the truncation:

  Example 3     Example 4
1Line 1        1Line

0Line 2        0Line

0Line 3        0Line