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) +
                           FMTLINES(&OUT)
              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
 as:

        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
 parameter.

 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
 achieved.

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

 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
 occurs).

 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

                                    yyy

               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
               suppressed.

   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
                  discussion).

    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
                  bytes.

                  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
 DSPMSGD.

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

 See the prior discussion of the valid formatting options.

 Restrictions
 ------------

   **   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.

 Prerequisites
 -------------

 The following TAA Tools must be on your system:

      SNDESCMSG    Send escape message

 Implementation
 --------------

 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

Last modified on November 19, 2014 © 1995, 2014 - TAA Tools, Inc.