The Retrieve Column  Heading command is  a program (TAADBLRR)  that may
be called  to retrieve the column headings  for a field in a  file.  An
externally  described data structure (TAADBLRP)  is used to communicate
with the program.   The  intent of the  program is  to allow a  general
purpose print program  where neither the file nor  the fields are known
when  the program  is written.   Either  the field  name or  the column
headings (as described in  DDS can be  returned) and are justified  for
printing.

Assume you  want to write a  generalized print program that  will print
a  field in  a data  base without  knowing ahead  of time  the specific
file or field.  If you want column headings, you generally want:

  **   Either the  field name  or  the DDS  column  headings (up  to  3
       lines).

  **   If it  is a  character field  where the data  length is  greater
       than or  equal to the column heading,  the column heading should
       be left justified.

  **   If  it is a decimal field where  the data length is greater than
       or equal  to the column  heading, the  column heading should  be
       right justified and  additional spaces if an edit  code is used.

  **   If  the  data length  is shorter  than  the column  heading, the
       data should be centered under the column heading.

The purpose  of RTVCOLHDG  is to  return information  that will  assist
you  in  printing the  field  with  an appropriately  justified  column
heading.

The companion  tool is RTVFLDDTA which will  retrieve data either left,
right, or centered to work in conjunction with RTVCOLHDG.

The  TAADBLRP  externally   described  data   structure  provides   for
communication  to  and  from  the  TAADBLRR  program.    The  following
parameters exist:

  **   RDRQST.   *CHAR LEN(8).   Input.   For normal use  pass *COLHDG.
       The  program remains open to allow  another column heading to be
       retrieved.  When all  column headings are retrieve, pass  *CLOSE
       which close  the program  without performing any  column heading
       processing.

  **   RDRTNC.    *CHAR  LEN(8).    Blank.    The  space  is  used  for
       communication with  a  sub program.    Any  errors such  as  the
       field  name  does  not  exist are  reported  back  using  escape
       messages.

  **   RDFILE.   *CHAR LEN(10).  Input.  The  file name to retrieve the
       field from.

  **   RDLIB.   *CHAR LEN(10).   Input.   The  library where  the  file
       exists.

  **   RDFLD.   *CHAR LEN(10).   Input.  The  field name to  retrieve a
       column heading for.

  **   RDMXLN.   *CHAR  LEN(3).   Input.    The maximum  length  of the
       field  intended to be printed.   '000' means use the full length
       of the field.   A specific  value may be  passed if you  want to
       print less  than the  full length  of the field.   This  is only
       valid for a *CHAR type field.

  **   RDCOLT.   *CHAR  LEN(8).  Input.   The  column type  to be used.
       Either *COLHDG (use  the DDS  column headings)  or *FLDNAM  (use
       the field name) must be passed.

  **   RDEDIT.   *CHAR LEN(1).   Input.   The edit  code to  be passed.
       Use '*'  to mean use the editing  from the DDS field definition.
       Use '%' to  mean no  editing is  performed.  Either  '*' or  '%'
       must be passed for a  *CHAR field.  A normal edit  code may also
       be passed (eg 1-4).

  **   RDRTYP.    *CHAR LEN(1).    Output.   The  type  of field  being
       returned.   This is one byte code.   The values can be seen with
       the DSPDTATYP TAA command.

  **   RDMXWT.   *CHAR  LEN(3).   Output.   The  maximum width  of  the
       field  including the  column  heading.   This  will include  any
       possible editing characters.

  **   RDDTAW.   *CHAR LEN(5).  Output.   The maximum width of the data
       including any editing characters.

  **   RDSDTA.  *CHAR  LEN(3).  Output.   The position  where the  data
       starts within the column.

  **   RDRCL1.   *CHAR  LEN(44).   Output.   The first  line of  column
       headings.  See the later discussion.

  **   RDRCL2.   *CHAR  LEN(44).   Output.  The  second line  of column
       headings.  See the later discussion.

  **   RDRCL3.   *CHAR LEN(44).   Output.   The  third line  of  column
       headings.  See the later discussion.

  **   RDRSV.   *CHAR LEN(100).   Reserved.   Reserved area for  future
       parameters.

The column heading  return values are designed to be  printed as 1 to 3
lines.   If  only one  line exists  (if RDCOLT  = *FLDNAM) or  there is
only one  line, RDRCL3 will  have data  and RDRCL1  and RDRCL2 will  be
blank.   If  there  are 2  lines  of column  headings,  RDRCL1 will  be
blank.   The return values are 44 bytes to  allow a 30 digit field with
editing to be considered.

The following code may  be copied to an  RPG program to interface  with
the RTVCOLHDG program.

     I* RTVCOLHDG DS
     I              'TAATOOL/TAADBLRR'    C         GETCOL
     ICOLDTA    E DSTAADBLRP
     .
     C* It is generally preferable to have the following code in a
     C*  subroutine which allows it to be called with a request
     C*  value of *COLHDG or *CLOSE.
     C                     CALL GETCOL                     Get key
     C                     PARM           COLDTA           Column data

RTVCOLHDG escape messages you can monitor for
---------------------------------------------

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

CPF9898 is sent  for a variety of  error conditions such as  the RDFILE
or RDLIB parameters are blank.

RTVCOLHDG command parameters
----------------------------

No command exists.

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

None.

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

The following TAA Tools must be on your system:

     RTVFLDA         Retrieve field attributes
     RTVVALA         Retrieve field value
     SNDESCMSG       Send escape message

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

None, the tool is ready to use.

Objects used by the tool
------------------------

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

   TAADBLRC      *PGM       CLP         TAADBLRC      QATTCL
   TAADBLRR      *PGM       RPG         TAADBLRR      QATTRPG
   TAADBLRP      *FILE      PF          TAADBLRP      QATTDDS

The TAADBLRR  program should be called  by your program.   It calls the
TAADBLRC sub program.