Version 4.2.6 for Mainframes
 —  Programming Guide  —

Parameters to Influence the Output of Fields

This document discusses the use of those Natural profile and/or session parameters which you can use to control the output format of fields.

The following topics are covered:

See also Output Reports and Workfiles (in the Operations documentation) for an overview of the Natural profile parameters that control various standard attributes used during the creation of Natural reports.


Overview of Field-Output-Relevant Parameters

Natural provides several profile and/or session parameters you can use to control the format in which fields are output:

Parameter Function
LC, IC and TC With these session parameters, you can specify characters that are to be displayed before or after a field or before a field value.
AL and NL With these session parameters, you can increase or reduce the output length of fields.
DL With this session parameter, you can specify the default output length for an alphanumeric map field of format U.
SG With this session parameter, you can determine whether negative values are to be displayed with or without a minus sign.
IS With this session parameter, you can suppress the display of subsequent identical field values.
ZP With this profile and session parameter, you can determine whether field values of 0 are to be displayed or not.
ES With this session parameter, you can suppress the display of empty lines generated by a DISPLAY or WRITE statement.

These parameters are discussed below.

Top of page

Leading Characters - LC Parameter

With the session parameter LC, you can specify leading characters that are to be displayed immediately before a field that is output with a DISPLAY statement. The width of the output column is enlarged accordingly. You can specify 1 to 10 characters.

By default, values are displayed left-justified in alphanumeric fields and right-justified in numeric fields. (These defaults can be changed with the AD parameter; see the Parameter Reference). When a leading character is specified for an alphanumeric field, the character is therefore displayed immediately before the field value; for a numeric field, a number of spaces may occur between the leading character and the field value.

The LC parameter can be used with the following statements:

It can be set at statement level and at element level.

Top of page

Insertion Characters - IC Parameter

With the session parameter IC, you specify the characters to be inserted in the column immediately preceding the value of a field that is output with a DISPLAY statement. You can specify 1 to 10 characters.

For a numeric field, the insertion characters will be placed immediately before the first significant digit that is output, with no intervening spaces between the specified character and the field value. For alphanumeric fields, the effect of the IC parameter is the same as that of the LC parameter.

The parameters LC and IC cannot both be applied to one field.

The IC parameter can be used with the following statements:

It can be set at statement level and at element level.

Top of page

Trailing Characters - TC Parameter

With the session parameter TC, you can specify trailing characters that are to be displayed immediately to the right of a field that is output with a DISPLAY statement. The width of the output column is enlarged accordingly. You can specify 1 to 10 characters.

The TC parameter can be used with the following statements:

It can be set at statement level and at element level.

Top of page

Output Length - AL and NL Parameters

With the session parameter AL, you can specify the output length for an alphanumeric field; with the NL parameter, you can specify the output length for a numeric field. This determines the length of a field as it will be output, which may be shorter or longer than the actual length of the field (as defined in the DDM for a database field, or in the DEFINE DATA statement for a user-defined variable).

Both parameters can be used with the following statements:

They can be set at statement level and at element level.

Note:
If an edit mask is specified, it overrides an NL or AL specification. Edit masks are described in Edit Masks - EM Parameter.

Top of page

Display Length for Output - DL Parameter

Note:
You should use the Web I/O Interface to make use of the full functionality of the DL parameter. When using the terminal emulation, it is not possible, for example, to scroll in a field when the value defined with DL is smaller than the field length.

With the session parameter DL, you can specify the display length for a field of format A or U, since the display width of a Unicode string can be twice the length of the string, and the user must be able to display the whole string. The default will be the length, for example, for a format/length U10, the display length can be 10 to 20, whereas the default length (when DL is not specified) is 10.

This session parameter can be used with the following statements:

It can be set at statement level and at element level.

The difference between the session parameters AL and DL is that AL defines the data length of a field whereas DL defines the number of columns which are used on the screen for displaying the field. The user can scroll in input fields to view the entire content of a field if the value specified with the DL session parameter is less than the length of the field data.

Using the DL parameter with a length that is smaller than the length of the field is only recommended with the Web I/O Interface. When running Natural in a terminal emulation, scrolling in a field is not possible and so the effect is the same as using the AL parameter. Moreover, when changing the field contents, all characters which are beyond the display length will be lost.

Note:
DL is allowed for A-format fields as well. In conjunction with the Web I/O Interface, this would allow making the edit control size smaller than the content of a field.

Example:

DEFINE DATA LOCAL
1    #U1 (U10)
1    #U2 (U10)
END-DEFINE
*
#U1 := U'latintxt00'
#U2 := U'graphics/u2.gif'
*
INPUT (AD=M) #U1 #U2
END

The above program produces the following output where the content of the field #U2 is incomplete:

#U1 latintxt00 #U2 graphics/u2-incomplete.gif

When the session parameter DL is used with the field #U2 and is specified accordingly, the content of this field will be displayed correctly:

DEFINE DATA LOCAL
1    #U1 (U10)
1    #U2 (U10)
END-DEFINE
*
#U1 := U'latintxt00'
#U2 := U'graphics/u2.gif'
*
INPUT (AD=M) #U1 #U2 (DL=20)
END

Result:

#U1 latintxt00 #U2 graphics/u2.gif

Top of page

Sign Position - SG Parameter

With the session parameter SG, you can determine whether or not a sign position is to be allocated for numeric fields.

The SG parameter can be used with the following statements:

It can be set at both statement level and element level.

Note:
If an edit mask is specified, it overrides an SG specification. Edit masks are described in Edit Masks - EM Parameter.

Example Program without Parameters

** Example 'FORMAX03': FORMAT (without FORMAT and compare with FORMAX04)
************************************************************************
DEFINE DATA LOCAL
1 VIEWEMP VIEW OF EMPLOYEES
  2 NAME
  2 FIRST-NAME
  2 SALARY (1:1)
  2 BONUS  (1:1,1:1)
END-DEFINE
*
READ (5) VIEWEMP BY NAME STARTING FROM 'JONES'
  DISPLAY NAME
          FIRST-NAME
          SALARY (1:1)
          BONUS  (1:1,1:1)
END-READ
END

The above program contains no parameter settings and produces the following output:

  Page      1                                                  04-11-11  11:11:11  
                                                                                 
          NAME              FIRST-NAME        ANNUAL     BONUS   
                                              SALARY             
  -------------------- -------------------- ---------- ----------
                                                                 
  JONES                VIRGINIA                  46000       9000
  JONES                MARSHA                    50000          0
  JONES                ROBERT                    31000          0
  JONES                LILLY                     24000          0
  JONES                EDWARD                    37600          0

Example Program with Parameters AL, NL, LC, IC and TC

In this example, the session parameters AL, NL, LC, IC and TC are used.

** Example 'FORMAX04': FORMAT (with parameters AL, NL, LC, TC, IC and
**                     compare with FORMAX03)
************************************************************************
DEFINE DATA LOCAL
1 VIEWEMP VIEW OF EMPLOYEES
  2 NAME
  2 FIRST-NAME
  2 SALARY (1:1)
  2 BONUS  (1:1,1:1)
END-DEFINE
*
FORMAT AL=10 NL=6
*
READ (5) VIEWEMP BY NAME STARTING FROM 'JONES'
  DISPLAY NAME            (LC=*)
          FIRST-NAME      (TC=*)
          SALARY (1:1)    (IC=$)
          BONUS (1:1,1:1) (LC=>)
END-READ
END

The above program produces the following output. Compare the layout of this output with that of the previous program to see the effect of the individual parameters:

  Page      1                                                  04-11-11  11:11:11  
                                                                                 
     NAME     FIRST-NAME   ANNUAL   BONUS  
                           SALARY          
  ----------- ----------- -------- --------
                                           
  *JONES      VIRGINIA  *   $46000 >   9000
  *JONES      MARSHA    *   $50000 >      0
  *JONES      ROBERT    *   $31000 >      0
  *JONES      LILLY     *   $24000 >      0
  *JONES      EDWARD    *   $37600 >      0

As you can see in the above example, any output length you specify with the AL or NL parameter does not include any characters specified with the LC, IC and TC parameters: the width of the NAME column, for example, is 11 characters - 10 for the field value (AL=10) plus 1 leading character.

The width of the SALARY and BONUS columns is 8 characters - 6 for the field value (NL=6), plus 1 leading/inserted character, plus 1 sign position (because SG=ON applies).

Top of page

Identical Suppress - IS Parameter

With the session parameter IS, you can suppress the display of identical information in successive lines created by a WRITE or DISPLAY statement.

The IS parameter can be specified

The effect of the parameter IS=ON can be suspended for one record by using the statement SUSPEND IDENTICAL SUPPRESS; see the Statements documentation for details.

Compare the output of the following two example programs to see the effect of the IS parameter. In the second one, the display of identical values in the NAME field is suppressed.

Example Program without IS Parameter

** Example 'FORMAX05': FORMAT (without parameter IS
**                     and compare with FORMAX06)
************************************************************************
DEFINE DATA LOCAL
1 VIEWEMP VIEW OF EMPLOYEES
  2 NAME
  2 FIRST-NAME
END-DEFINE
*
READ (3) VIEWEMP BY NAME STARTING FROM 'JONES'
  DISPLAY NAME FIRST-NAME
END-READ
END

The above program produces the following output:

  Page      1                                                  04-11-11  11:11:11  
                                                                                 
          NAME              FIRST-NAME     
  -------------------- --------------------
                                           
  JONES                VIRGINIA            
  JONES                MARSHA              
  JONES                ROBERT             

Example Program with IS Parameter

** Example 'FORMAX06': FORMAT (with parameter IS
**                     and compare with FORMAX05)
************************************************************************
DEFINE DATA LOCAL
1 VIEWEMP VIEW OF EMPLOYEES
  2 NAME
  2 FIRST-NAME
END-DEFINE
*
FORMAT IS=ON
*
READ (3) VIEWEMP BY NAME STARTING FROM 'JONES'
  DISPLAY NAME FIRST-NAME
END-READ
END

The above program produces the following output:

Page      1                                                 04-11-11  11:54:01  
                                                                                
        NAME              FIRST-NAME     
-------------------- --------------------
                                           
JONES                VIRGINIA            
                     MARSHA              
                     ROBERT             

Top of page

Zero Printing - ZP Parameter

With the profile and session parameter ZP, you determine how a field value of zero is to be displayed.

The ZP parameter can be specified

Compare the output of the following two example programs to see the effect of the parameters ZP and ES.

Top of page

Empty Line Suppression - ES Parameter

With the session parameter ES, you can suppress the output of empty lines created by a DISPLAY or WRITE statement.

The ES parameter can be specified

Note:
To achieve empty suppression for numeric values, in addition to ES=ON the parameter ZP=OFF must also be set for the fields concerned in order to have null values turned into blanks and thus not output either.

Compare the output of the following two example programs to see the effect of the parameters ZP and ES.

Example Program without Parameters ZP and ES

** Example 'FORMAX07': FORMAT (without parameter ES and ZP
**                     and compare with FORMAX08)
************************************************************************
DEFINE DATA LOCAL
1 VIEWEMP VIEW OF EMPLOYEES
  2 NAME
  2 FIRST-NAME
  2 BONUS (1:2,1:1)
END-DEFINE
*
READ (4) VIEWEMP BY NAME STARTING FROM 'JONES'
  DISPLAY NAME FIRST-NAME BONUS (1:2,1:1)
END-READ
END

The above program produces the following output:

Page      1                                                  04-11-11  11:58:23
                                                                               
        NAME              FIRST-NAME        BONUS
-------------------- -------------------- ----------
                                           
JONES                VIRGINIA                   9000
                                                6750
JONES                MARSHA                        0
                                                   0
JONES                ROBERT                        0
                                                   0
JONES                LILLY                         0
                                                   0

Example Program with Parameters ZP and ES

** Example 'FORMAX08': FORMAT (with parameters ES and ZP
**                     and compare with FORMAX07)
************************************************************************
DEFINE DATA LOCAL
1 VIEWEMP VIEW OF EMPLOYEES
  2 NAME
  2 FIRST-NAME
  2 BONUS (1:2,1:1)
END-DEFINE
*
FORMAT ES=ON
*
READ (4) VIEWEMP BY NAME STARTING FROM 'JONES'
  DISPLAY NAME FIRST-NAME BONUS (1:2,1:1)(ZP=OFF)
END-READ
END

The above program produces the following output:

Page      1                                                  04-11-11  11:59:09
                                                                               
        NAME              FIRST-NAME        BONUS
-------------------- -------------------- ----------
                                           
JONES                VIRGINIA                   9000
                                                6750
JONES                MARSHA
JONES                ROBERT
JONES                LILLY

Top of page

Further Examples of Field-Output-Relevant Parameters

For further examples of the parameters LC, IC, TC, AL, NL, IS, ZP and ES, and the SUSPEND IDENTICAL SUPPRESS statement, see the following example programs:

Top of page