TAA Tools
FMTLIN          FORMAT LINE                            TAACLPX

The Format Line tool accepts  a variable which is a string  of text and
returns it  in a separate  variable so that  it is formatted  to appear
on  multiple lines.   An option exists  to format the  line in the same
manner as system messages appear.

By default, the lines are formatted so that:

  **   A word is never split over two lines

  **   A line does not start with a blank

  **   Excess  blank  characters   (more  than  1)  between   non-blank
       characters are squeezed out.

  **   An extra  blank is inserted if  a period is followed  by a space
       such as at the end of a sentence.

For example if your string of text looks like:

      aaa bbbbb cccc    ddd ee fffffff gggg hhhh iii j kkkk

The return variable may look like:

      aaa bbbbb cccc ddd    ee fffffff gggg hhhh    iii j kkkk
      <----- Line 1 -------><------- Line 2 -------><--- Line 3 --..

FMTLIN  requires that you describe the length  of your lines.  You must
then extract (e.g.   substring) from the  return variable to match  the
length of your lines as specified on the command.

Unless special  formatting characters  are used (described  later) each
string  of data would  appear as a  single paragraph.   A straight left
edge would exist and a ragged right edge such as:


The input  string can  be  up to  9799 bytes  in  length.   The  output
string must be  declared as *CHAR  LEN(9999).  The maximum  line length
is 200 bytes.

The  following shows  a sample  of how  you would  use FMTLIN.   Assume
that  a  string  of text  is  placed  into the  variable  &INPUT.   The
variable  is  declared  as  1000  bytes  in  length,   but  the  INPLEN
parameter  on  FMTLIN  specifies  that  only the  first  300  bytes  be
formatted.   The  LINLEN parameter specifies  that the  lines should be
formatted into 60 byte sections.

The data that  is used  to fill the  variable &INPUT is  less than  100
bytes.   After FMTLIN, the CL  substring function is used  to substring
out two 60 byte lines.

             DCL        &INPUT *CHAR LEN(1000)
             DCL        &FMTLINES *CHAR LEN(9999)
             DCL        &MSG2 *CHAR LEN(60)
             CHGVAR     &INPUT ('This is what a normal line looks +
                          line after it is formatted by the +
                          FMTLIN TAA Tool.')
             FMTLIN     INPUT(&INPUT) INPLEN(300) LINLEN(60) +
             CHGVAR     &MSG2 %SST(&FMTLINES 1 60)
             SNDPGMMSG  MSG(&MSG2)
             CHGVAR     &MSG2 %SST(&FMTLINES 61 60)
             SNDPGMMSG  MSG(&MSG2)

Other formatting comments

There  are special  formatting  characters that  may be  placed  in the
text to control:

  **   Starting a new line

  **   Indenting a new line or an overflow line

  **   Causing extra spaces within a line

See the later discussion.

You can output  the text to a  display field that  may take up  several
lines.   If an 80  byte wide  display is used,  each line length  would
normally  be specified as  80.  You  would want  to start the  field at
position 1 of a line.

If  you have  some lead  in description followed  by a  long field such

       Text: ------------

You can specify a different length  of the first line (in this  case it
would  be  shorter  than the  the  other  lines).   See  the  FSTLINLEN

If  there are no blank spaces  within a line of output  (i.e.  one very
long word),  no error occurs  and the  line is  output as  best can  be

If the INPUT value  is all blanks, all blanks will exist  in the return

Building the string of text from data base records

Because  FMTLIN will squeeze out  blank spaces, it  makes it convenient
to build a string of text  from data base records (or array  elements).

Assume your  record length  is 80  and you  have a  variable number  of
records to be displayed or printed.

There are two methods of storing the data:

  **   As a single string.  A word may be split over two records.

  **   As separate  strings.  When  the data is entered,  place it into
       the  records so  that a  word is never  split over  a record and
       position 80  is always  blank.   When the  data is  concatenated
       together  (or  via  substring),  a  single  string  will  exist.
       Excess blanks are squeezed out.

Calling the CPP Directly

You  can  call the  CPP  directly from  a  HLL program.    For example,
assume you  want to print  the text  in a  block of  60 characters  per
line with a  maximum of 20 lines.   You would place the string  of text
into  the INPUT field which  is defined with  a length of  1000 in this
example.   The text  could come  from one  or more  data base  records,
array elements or be generated by the program.

     E                    DATA     9999  1
     IFMTLIN      DS
     I                                        19999 DATA
     C                     CALL 'TAACLPXC'                 FMTLIN CPP
     C                     PARM           INPUT            Input
     C                     PARM 1000      INPLEN  50       Input len
     C                     PARM 60        LINLEN  30       Line len
     C                     PARM           FMTLIN           Rtn var
     C                     PARM 60        FSTLIN  30       Fst ln len
     C                     PARM '*NO '    FMTCHR  4        Fmt option
     C                     Z-ADD1         DX      50       Inlz
     C                     DO   20                         Do 20 times
     C                     MOVEADATA,DX   LINE   60        Move a line
     C                     EXCPTDETAIL                     Print
     C                     ADD  60        DX               Bump
     C                     ENDDO                           Do 20 times

Formatting options

The  same  formatting  options as  used  for  system  messages  may  be
specified  (&N &P  &B).   These  have the  same meaning  as  the system
functions.   See the ADDMSGD description  of the SECLVL parameter.  You
must specify FMTCHAR(*IBM).

Special formatting options  may be placed  in the text  to cause a  new
line, indentation, and blank spaces.

To  cause the  FMTLIN command  to be  sensitive to  these  options, you
must  specify  FMTCHAR(*YES).   The  default  is *NO  which  causes the
special characters  to  appear in  the  output (no  special  formatting

The following are supported.

   .N            New  line  -  Successive  'new lines'  cause  a  blank
                 line.   An implicit '.N ' is  assumed at the beginning
                 of the output.

   .Bn           Blank spaces - the  'n' is a value  1-9.  If you  want
                 to  indent the  first  character of  a  new line,  use
                 '.Bn '  before the first  character to print.   If you
                 want  more  than  one  blank  between  words  within a
                 line, specify '.Bn '  where required.  If  you request
                 blanks that  pass the 'end  of line' point,  blanks do
                 not carry over to the next line.

   .In           Indentation  of overflow  lines -  the 'n' is  a value
                 1-9.   This does  not refer  to the  first  line of  a
                 'new line', but  any overflow lines in  the paragraph.
                 When  a '.N  ' is used  for a  new line,  the overflow
                 lines  indentation  is  reset  to  0.    If  you  want
                 several paragraphs  that  are all  indented the  same,
                 you  must  specify '.In  '  for  each paragraph  (i.e.
                 after each '.N ')

A  lower case entry is also  supported such as '.n  '.  You must follow
the entry with a blank.

Any invalid values  appear in  the output and  do not cause  formatting
such as:

    .n1        Does not end with a blank
    .b5x       Does not end with a blank
    .b&        The 'n' value is not 1-9
     I5        No leading '.'

The  following  describes  how  you  can  use  the  special  formatting
characters to achieve typical output requirements:

  1. Start a new line
      ------ Input ------          ---- Output ----
        xxxx .n yyyy zzzz          xxxx
                                   yyyy zzzz

              A  new line occurs  when the 'new line'  request is made.

  2. Cause a blank line
      ------ Input ------          ---- Output ----
        xxxx .n .n yyy             xxxx


              Two 'new lines' in succession cause a blank line.

  3. Indent the first line
      ------ Input ------          ---- Output ----
        .B5 -----...                    -----

              The first line  is indented  by 5 spaces  because of  the
              '.B5 '.

  4. Indent the overflow lines
      ------ Input ------        ---- Output ----
        .i3 -----...               ----------

              The overflow  lines are  indented 3  because of  the '.i3

  5. Cause 3 blanks between two fields
      ------ Input ------          ---- Output ----
        xxx .b3 yyy                xxx   yyy

              Three  spaces appear  between the  two fields  because of
              the '.b3  '.   The extra  space after  the xxx  value  is

  5. Indent a description
      ------ Input ------          ------ Output ------
        Bob: .b5 -----             Bob:     ---------
        .n .n Mary: .b4 ----                --------

                                   Mary:    --------

              To achieve  this format, you  must specify  the FSTLINLEN
              parameter larger  than LINLEN.  In the  example shown, it
              should  be 9 positions larger.   You must account for how
              many blanks  exist between  the colon and  the left  edge
              of the paragraphs.

FMTLIN escape messages you can monitor for

      TAA9895    The INPUT parameter may not be all blank

Escape messages from based on functions will be re-sent.

Command parameters                                    *CMD

   INPUT         The variable  to be formatted.   The variable  must be
                 between  20  and  9799  bytes  in  length.   The  data
                 should look  like a  single string  of  text.   Excess
                 blanks  between  words  are squeezed  out  (see  prior

   INPLEN        The length of the data to be formatted.

                 The  value does  not have  to  match the  actual data.
                 It  must   not  exceed   the  length   of  the   INPUT
                 parameter.   The length  must be  between 20 and  9799

                 You can  have a large  INPUT variable and  control how
                 much  of the  value should be  formatted by specifying
                 a  shorter  length.    If  you  have  a   large  INPUT
                 variable  that   is  rarely  filled,   specifying  the
                 length  of the variable  for INPLEN  causes the FMTLIN
                 tool to process excessive blanks.

                 No  error occurs  if  the  length  is  less  than  the
                 actual data supplied.  Truncation occurs.

   LINLEN        The length of  the lines to be formatted.   The length
                 must  be between 20 and  200 bytes.  This  is also the
                 length of the data that  you substring out to  provide
                 for a formatted line.

                 All line lengths  must be the same with  the exception
                 of the first line.  See the FSTLINLEN parameter.

   FMTLINES      The  formatted  lines returned  in  a  variable.   The
                 variable must be declared as *CHAR LEN(9999).

   FSTLINLEN     The  length of  the first line  to be  formatted.  The
                 default is  *LINLEN  which means  the  same length  as
                 specified for the LINLEN parameter.

                 The first line  may be a different length  than all of
                 the  other lines  to be formatted.   It  can be longer
                 or shorter.    If  you  substring out  of  the  return
                 variable, this must  be the length of  the first line.
                 The length must be between 20 and 200 bytes.

   FMTCHAR       A  *YES/*NO/*IBM value that determines  if any special
                 formatting options found in  the INPUT string will  be
                 considered.  The default is *NO.

*IBM must  be  specified if  you are  displaying a  system message  and
want  the same  formatting characters  as used  by  ADDMSGD.   A LINLEN
value  of 78  should be  used to  make the  message appear the  same as

*YES must  be  specified if  you want  the  special formatting  options
supplied for FMTLIN.

See the prior discussion of the valid formatting options.


  **   Because  FMTLIN returns  a  variable, the  command  can only  be
       used  in a CL  program.  The  CPP can be used  directly from any
       HLL program.


The following TAA Tools must be on your system:

     SNDESCMSG    Send escape message


None, the tool is ready to use.

Objects used by the tool

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   FMTLIN        *CMD                   TAACLPX       QATTCMD
   TAACLPXC      *PGM       CLP         TAACLPXC      QATTCL

Added to TAA Productivity tools May 1, 1996

Home Page Up to Top