TAA Tools
CONARR          CONSTANT ARRAY                         TAAARAC

The Constant  Array tool is a  set of commands  that lets you  create a
data area  of constants and use them  in a CL program as  an array.  An
optional  alternating  entry  can  be  specified.    You  determine the
maximum number of entries to be defined from 1 to 45.

The following commands are included:

   CRTCONARR     Creates the data area  that will contain the  constant
                 array.

   EDTCONARR     Edits  the  constant  array.   Enters  new  values  or
                 changes  existing values in the array.   You must have
                 *CHANGE authority to the data area.

   DSPCONARR     Displays  the  constant   array.     No  changes   are
                 allowed.

   RTVCONARR     Retrieves an entry  from the constant array.   The RTV
                 command can be used to:

                      Validate that an entry exists.

                      Return the alternating entry

                      Step thru the array and return each entry.

There  is no DLT command.   Use DLTDTAARA  if you create  a CONARR data
area that is no longer needed.

Example
-------

Assume you  want  to create  an  array  with an  alternating  value  to
contain the entries for 'divisions' and a brief description such as:

           DIV1         Great Lakes
           DIV2         East Coast
           DIV3         West Coast

You would first create the constant array data area:

        CRTCONARR     DTAARA(DIVNAM) TEXT('Division names')
                        ENTLEN(4) ALTENTLEN(15)
                        ENTTXT('Division') ALTENTTXT('Name')

You would then use the EDT command to enter the values.

        EDTCONARR     DTAARA(DIVNAM)

The display would appear and you would enter the values:

********************************************************************
*                                                                  *
*      Edit Constant Array - Division names                        *
*                                                                  *
*   Type new/changed information, press Enter.                     *
*     To add an entry, type a value in both entries                *
*     To remove an entry, blank out both entries.                  *
*     To change positions of an entry, type new sequence number.   *
*                                                                  *
*                                                                  *
*    Sequence   Division     Len =  4       Names        Len = 15  *
*      010      DIV1________________        Great Lakes_________   *
*      020      DIV2________________        East Coast__________   *
*      030      DIV3________________        West Coast__________   *
*      040      ____________________        ____________________   *
*      050      ____________________        ____________________   *
*      060      ____________________        ____________________   *
*      070      ____________________        ____________________   *
*      080      ____________________        ____________________   *
*      090      ____________________        ____________________   *
*      100      ____________________        ____________________   *
*      110      ____________________        ____________________   *
*                 Any value                   Any value            *
*                                                                  *
*                                                     More ...     *
*    F12=Cancel     Enter=Update or refresh (if any changes occur) *
********************************************************************

The RTVCONARR command  would then be used  in a CL program  to retrieve
the information.  There are 3 typical uses.

  **   To check  if a division value is valid  (Message TAA9896 is sent
       as an escape message if the value does not exist):

            DCL           &DIV *CHAR LEN(4)
             .
            RTVCONARR     DTAARA(DIVNAM) ENTRY(&DIV)
            MONMSG        MSGID(TAA9896) EXEC(DO) /* Not found */
             .
             .
            ENDDO         /* Not found */

  **   To return the alternate entry

            DCL           &DIV *CHAR LEN(4)
            DCL           &DIVNAM *CHAR LEN(20)
             .
            RTVCONARR     DTAARA(DIVNAM) ENTRY(&DIV) RTNALT(&DIVNAM)

              Note  that you you  must declare the  &RTNALT variable as
              20 bytes even though the actual length may be less.

  **   To step  thru  the array  bringing back  both  entries (see  the
       RTVCONARR command discussion of the RTNNBR parameter)

            DCL           &DIV *CHAR LEN(20)
            DCL           &DIVNAM *CHAR LEN(20)
            DCL           &RTNNBR *DEC LEN(3 0)
             .
 LOOP:      RTVCONARR     DTAARA(DIVNAM) ENTRY(*NEXT) +
                            RTNENT(&DIV) RTNALT(&DIVNAM) +
                            RTNNBR(&RTNNBR)
            IF            (&RTNBR *GT 0) DO /* Found */
             .
             .            /* Process &DIV and &DIVNAM */
             .
            GOTO          LOOP
            ENDDO         /* Found */

              Note that  you you must  declare the &RTNENT  and &RTNALT
              variables  as 20 bytes even though  the actual length may
              be less.

See the later example on using object names in the entries.

EDTCONARR Display
-----------------

Up to  45  entries  may be  entered.    The  number to  be  entered  is
controlled by the  MAXENT parameter on CRTCONARR.   Rollup and rolldown
are used for additional pages of the display.

The  length  of the  entry  cannot  exceed 20  bytes.    The length  is
specified  on  the  CRTCONARR  command.    The  display  describes  the
maximum length  as  part of  the column  heading  of the  field and  an
error  message will describe  any entry that  exceeds the maximum.   It
is  invalid  to have  a blank  value (where  only an  alternating entry
exists).  A value of *NEXT cannot be used.

If the entry  is defined  as an 'object  name', then  the rules for  an
object are  followed (e.g.  the  first character must  be A-Z,$,#,@ and
the remaining non-blank characters must be A-Z, 0-9, $,#,@).

Two forms of object name are supported:

  **   Simple name.  Must adhere to the object name rules.

         --   Special  name.  Must  adhere to the object  name rules or
              be *LIBL or *CURLIB.

Two forms  of qualified object  name are  supported.   The object  name
must  appear in  positions  1-10  of the  entry  and  the library  must
appear in 11-20.

  **   Both names must adhere to the object name rules.

         --   The  library value must  adhere to the  object name rules
              or be *LIBL or *CURLIB.

The length of the alternate entry  cannot exceed 20 bytes.  The  length
is specified  on  the CRTCONARR  command.   The  display describes  the
maximum  length as  part of  the  column heading  of the  field  and an
error  message will  describe any entry  that exceeds the  maximum.  If
ALTENTLEN(*NONE)  is  specified on  CRTCONARR,  no  input  fields  will
exist for the  alternating value on the edit display  and it is invalid
to use RTNALT on the RTVCONARR command.

It is  invalid to have a blank value (where  only an entry exists).  If
your application allows  a blank alternating value,  you could enter  a
special value such as *BLANK and program for the special value.

If the  entry is defined  as an  'object name', then  the rules  for an
object  are followed (e.g.   the first character must  be A-Z,$,#,@ and
the remaining non-blank characters must be A-Z, 0-9, $,#,@).

Two forms of object name are supported:

  **   Simple name.  Must adhere to the object name rules.

         --   Special name.  Must  adhere to the  object name rules  or
              be *LIBL or *CURLIB.

Two forms  of qualified  object name  are supported.   The object  name
must  appear  in  positions  1-10  of  the alternating  entry  and  the
library must appear in 11-20.

  **   Both names must adhere to the object name rules.

         --   The  library value must  adhere to the  object name rules
              or be *LIBL or *CURLIB.

CRTCONARR Command parameters                          *CMD
----------------------------

   DTAARA        The qualified data  area name of  the data area.   The
                 library value defaults to *CURLIB.

   TEXT          Up to  30 bytes  of text may  be specified.   The text
                 will  appear  on  the EDTCONARR  display  and  is also
                 used as  part of  the text  description  for the  data
                 area.

   ENTLEN        Entry  length.   A  value between  1  and  20 must  be
                 specified to describe the length of each entry.

   ALTENTLEN     Alternate  entry length.   A  value  between 1  and 20
                 must be  specified  to  describe the  length  of  each
                 alternate entry if  one exists.  *NONE is  the default
                 and must be used if no alternating value exists.

   MAXENT        The  maximum number  of entries  that may  be entered.
                 A  value  between  1  and 45  must  be  entered.   The
                 default is 45.

   ENTTXT        Entry text.   Up  to 12 bytes  can be  entered as  the
                 column  heading  to  help  describe the  value  to  be
                 entered  on  the EDTCONARR  display.   The  default is
                 'Entry value'.

   ALTENTTXT     Alternate Entry text.  Up  to 12 bytes can be  entered
                 as the  column heading to  help describe the  value to
                 be entered  on the EDTCONARR display.   The default is
                 'Alter value'.

   OBJNAM        The default  is  *NO  meaning any  characters  may  be
                 entered into  the entry.   The other  valid parameters
                 all  request some form  of object or  qualified object
                 name.    The rules  for a  valid  object name  must be
                 followed  (e.g.     the   first   character  must   be
                 A-Z,$,#,@  and  the   remaining  non-blank  characters
                 must be A-Z, 0-9, $,#,@, or _.

                 *OBJ1  means  the value  must  be  up to  20  bytes in
                 length and must adhere to the object name rules.

                 *OBJ2 means  the  value must  be  up  to 20  bytes  in
                 length and  must adhere  to the  object name  rules or
                 be *LIBL or *CURLIB.

                 *QLF1  means  the value  must  be 20  bytes  in length
                 with the object in positions  1-10 and the library  in
                 positions 11-20.   Both  parts of  the qualified  name
                 must adhere to the object name rules.

                 *QLF2  means the  value  must  be 20  bytes  in length
                 with  the object in positions  1-10 and the library in
                 positions 11-20.   Both  parts of  the qualified  name
                 must  adhere  to  the   object  name  rules,  but  the
                 library value can be *LIBL or *CURLIB.

   ALTOBJNAM     The  default  is  *NO meaning  any  characters  may be
                 entered into the alternating  entry.  The other  valid
                 parameters  all   request  some  form  of   object  or
                 qualified object  name.  The rules  for a valid object
                 name must  be  followed  (e.g.   the  first  character
                 must  be   A-Z,$,#,@  and   the  remaining   non-blank
                 characters must be A-Z, 0-9, $,#,@).

                 *OBJ1  means  the value  must  be up  to  10 bytes  in
                 length and must adhere to the object name rules.

                 *OBJ2  means  the  value must  be  up to  10  bytes in
                 length and  must adhere to  the object  name rules  or
                 be *LIBL or *CURLIB.

                 *QLF1  means the  value  must be  20  bytes in  length
                 with  the object in positions 1-10  and the library in
                 positions 11-20.   Both  parts of  the qualified  name
                 must adhere to the object name rules.

                 *QLF2  means the  value  must be  20  bytes in  length
                 with the  object in positions 1-10  and the library in
                 positions 11-20.   Both  parts of  the qualified  name
                 must  adhere  to  the  object   name  rules,  but  the
                 library value can be *LIBL or *CURLIB.

   AUT           Authority.   The  authority  to  the data  area.   The
                 default  is  *USE  which  will allow  the  use  of the
                 RTVCONARR  command.    With  *USE,  only  a  user  who
                 created the  data area or  a user who  is subsequently
                 authorized  to  *CHANGE  can  use  EDTCONARR.    Other
                 values which may be  entered are *LIBCRTAUT,  *CHANGE,
                 *ALL, or *EXCLUDE.

EDTCONARR Command parameters                         *CMD
----------------------------

   DTAARA        The qualified  data area name of  the data area.   The
                 library  value defaults  to *LIBL.   Only a  data area
                 created by CRTCONARR may be specified.

DSPCONARR Command parameters                         *CMD
----------------------------

   DTAARA        The qualified data area  name of the  data area.   The
                 library value  defaults to  *LIBL.   Only a data  area
                 created by CRTCONARR may be specified.

RTVCONARR Command parameters                          *CMD
----------------------------

RTVCONARR  may be used  to determine  if an  entry exists.   TAA9896 is
sent if it does not.  For example,

        RTVCONARR    DTAARA(CONARR1) ENTRY(xxx)
        MONMSG       MSGID(TAA9896) EXEC(DO) /* Not found */

It  may also be used to retrieve all  of the entries.  See the previous
example.

   DTAARA        The qualified data  area name of  the data area.   The
                 library  value defaults to  *LIBL.   Only a  data area
                 created by CRTCONARR may be specified.

   ENTRY         The  entry to be  retrieved.  *NEXT may  be entered to
                 step thru  the  constant array.    If *NEXT  is  used,
                 RTNNBR must be specified.

   RTNENT        The return entry.   Normally, this keyword  would only
                 be used  if ENTRY(*NEXT) was specified.   If used, the
                 return variable must be declared as *CHAR LEN(20).

   RTNALT        The return  alternate entry.   This  keyword can  only
                 be used  if the array  was originally created  with an
                 alternate  entry.  If  used, the return  variable must
                 be declared as *CHAR LEN(20).

                 A  special value *NONE  may be specified  when the CPP
                 for RTVCONARR is  used directly.  This  specifies that
                 no alternate entry exists.

   RTNNBR        The  return number.    This keyword  must  be used  if
                 ENTRY(*NEXT)  is specified.  The  return variable must
                 be declared as *DEC  LEN(3 0).  It  is used to  define
                 the next  entry to  be returned.   The  value must  be
                 specified as  one less than the  entry to be returned.
                 If you want the first entry, specify a value of 0.

                 When the  RTVCONARR command  returns, the  value  will
                 contain  the  relative entry  number.    The  relative
                 entry  number is probably  of no significant  value to
                 the  program other than  to be used  on the subsequent
                 RTVCONARR  command  if  you  are  stepping   thru  the
                 array.

                 When  no more  entries exist,  a value  of -1  will be
                 returned.    Any  value specified  on  the  command as
                 less  than 0  will  cause  an  escape  message.    The
                 normal  method of  coding  is  shown previously  where
                 the  program continues  to loop as  long as  the value
                 is greater than zero.

                 You can  reprocess the  array  by setting  the  RTNNBR
                 value to 0.

Using object names in the entries
---------------------------------

Both the ENTOBJ or  ALTENTOBJ keywords support the same  special values
to ensure that a valid object name is being entered.

*OBJ1 means that the name is a simple valid object name.

*OBJ2 means  that the name  is a simple  valid object name,  but allows
*LIBL or *CURLIB.

*QLF1  means the entry  is a double  entry with both  parts being valid
object names.    The object  name must  be in  positions  1-10 and  the
library in positions 11-20 such as:

        1        11
        .         .
        FILEA     LIB1
        PGMX      LIB2

*QLF2  is the  same as  *QLF1,  but allows  the library  portion to  be
*LIBL, or *CURLIB such as:

        1        11
        .         .
        FILEA     LIB1
        PGMX      LIB2
        FILEB     *LIBL
        FILEC     *CURLIB

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

Up  to 45  entries may  be  made.   Each entry  cannot exceed  20 bytes
maximum and it is invalid to have  a blank entry or an entry of  *NEXT.

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

The following TAA Tools must be on your system:

          SNDCOMPMSG     Send completion message
          SNDESCMSG      Send escape message

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

None, the tool is ready to use.

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

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

   CRTCONARR     *CMD                   TAAARAC       QATTCMD
   EDTCONARR     *CMD                   TAAARAC2      QATTCMD
   RTVCONARR     *CMD                   TAAARAC3      QATTCMD
   DSPCONARR     *CMD                   TAAARAC4      QATTCMD
   TAAARACC      *PGM       CLP         TAAARACC      QATTCL
   TAAARACC2     *PGM       CLP         TAAARACC2     QATTCL
   TAAARACC3     *PGM       CLP         TAAARACC3     QATTCL
   TAAARACC4     *PGM       CLP         TAAARACC4     QATTCL
   TAAARACR2     *PGM       RPG         TAAARACR2     QATTRPG
   TAAARACR4     *PGM       RPG         TAAARACR4     QATTRPG
   TAAARACD      *FILE      DSPF        TAAARACD      QATTDDS
   TAAARACE      *FILE      DSPF        TAAARACE      QATTDDS

Structure
---------

CRTCONARR   Cmd
   TAAARACC   CL pgm

EDTCONARR  Cmd
   TAAARACC2   CL pgm
     TAAARACR2   RPG Pgm
       TAAARACD    Display file

RTVCONARR  Cmd
   TAAARACC3   CL pgm

DSPCONARR  Cmd
   TAAARACC4   CL pgm
     TAAARACR4   RPG Pgm
       TAAARACE    Display file
					

Added to TAA Productivity tools May 1, 1996


Home Page Up to Top