TAA Tools
APPVAL          APPLICATION VALUE                      TAAAPPA

The  Application  Value  tool  is  designed  to  allow  options  to  be
specified for a standard application.

To  understand  the  Application Value  tool  the  following terms  are
used:

  **   Application   designer.      The   person   that   designs   the
       application.   He could  be on  a  system other  than where  the
       application is going to be run.

  **   Application   installer.      The   person  who   installs   the
       application  and determines  the  options that  will be  used on
       his system.

  **   Application user.  The person who uses the application.

The Application  Value tool  lets an  'application  designer' create  a
set of  options called an  'Application Value' that  can be used  by an
'application  installer'  to  tailor  the  options  to  be used  in  an
application.  The  'application end  user' would normally  not see  the
Application Value.

Assume  an 'application  designer'  has  created an  application  which
provides standard  function, but allows the  'application installer' to
to decide the following options:

      - Name of a journal
           - An example of a name field
      - Name of a library where the journal is located
           - An example of a name field with a default
      - Whether to automatically submit some batch job
           - An example of a *YES/*NO option
      - The maximum number of records to allow in a file
           - An example of a decimal value

The  'application designer' would create  an Application Value with the
appropriate attributes.    Assume the  name  is APPX.    See the  later
discussion for how this would be done.

The  'application installer' would  use the  EDTAPPVAL command  to edit
the Application Value.

             EDTAPPVAL  APPVAL(APPX)

When  the  display  appears  it would  look  like  (note  that  all the
screens are slightly  modified from  that shown because  of the  source
length maximum):

**********************************************************************
*                                                                    *
*                     Edit Application Value                         *
*                                                                    *
*      App value:   APPX         Used for Application X              *
*                                                                    *
*   Type choices, press Enter.            For Help, use F1           *
*                                                                    *
*   Journal                        __________   Name                 *
*   Journal library                *LIBL_____   Name, *LIBL, *CURLIB *
*   Auto submit batch update       *YES         *YES, *NO            *
*   Maximum records                0000050000   Number               *
*                                                                    *
**********************************************************************

The 'application installer  would be required to enter  a journal name.
The other values would default as displayed.

If  the  'application installer'  is  not  sure of  what  to  do for  a
specific attribute,  he positions  the cursor  to the  entry field  and
presses F1.   The following would  be displayed for the  Journal field.

**********************************************************************
*                                                                    *
*                      Edit Application Value                        *
*                                                                    *
*      App value:  APPX        Used for Application X                *
*                                                                    *
*          Value:                                                    *
*                                                                    *
*   Keyword  . . . . . . . . . . . . :  JRNL                         *
*   Description  . . . . . . . . . . :  Journal                      *
*   Type . . . . . . . . . . . . . . :  *NAME                        *
*   Length . . . . . . . . . . . . . :  10                           *
*   Decimal  . . . . . . . . . . . . :                               *
*   Mandatory non-blank value  . . . :  Y                            *
*   Restricted values  . . . . . . . :                               *
*                                                                    *
*                                                                    *
*   Special values . . . . . . . . . :                               *
*                                                                    *
*   Range  . . . . . . . . . . . . . :                               *
*                                                                    *
*     The journal name to be used for journaling the data base file. *
*         If you do not have a journal to use, you must create one.  *
*                                                                    *
**********************************************************************

The  Application  would  use  the  RTVAPPVAL  command to  retrieve  the
values   stored  in  the  Application   Value.    The  application  can
determine  that  the  Application  Value  has  at  least  been  entered
correctly  by  checking  a  return  value  (STATUS)  on  the  RTVAPPVAL
command.

Application Value Object
------------------------

The  Application Value object is created on  the system as a user space
(*USRSPC) with an  object attribute  of APPVAL.   Special commands  are
provided  to   operate  on   the  user  space.     The   normal  system
save/restore  commands,  authorization  commands,  etc  operate on  any
user space object.  No special handling is needed.

Creating an Application Value
-----------------------------

The 'application  designer'  must  first create  an  Application  Value
description such as:

             CRTAPPVALD  APPVAL(xxx/APPX) TEXT('...')

This creates a *USRSPC object.

The 'application designer'  then enters the  attributes on a  series of
interactive displays with the command:

             EDTAPPVALD  APPVAL(xxx/APPX)

The first  screen that is  displayed allows the  'application designer'
to  enter a keyword  name for each attribute  to be defined.   Up to 10
attributes may be described for each Application Value.

When the  screen  is first  displayed,  all of  the  Keywords would  be
*NONE.  After  the 'application designer' has entered  the keywords for
the previously shown Application Value, the display would appear as:

**********************************************************************
*                                                                    *
*                 Edit Application Value Description                 *
*                                                                    *
*   Type choices by entering a 1 and press Enter.                    *
*                                                                    *
*  Opt   Keyword      Description                                    *
*   _    JRNL         Journal                                        *
*   _    JRNLIB       Journal library                                *
*   _    AUTOSBM      Auto submit batch update                       *
*   _    MAXRCDS      Maximum records                                *
*   _    *NONE                                                       *
*   _    *NONE                                                       *
*   _    *NONE                                                       *
*   _    *NONE                                                       *
*   _    *NONE                                                       *
*   _    *NONE                                                       *
*                                                                    *
*   F3=Exit     F12=Cancel                                           *
**********************************************************************

The  'application designer' would use  option 1 for each  keyword to be
entered.  After pressing Enter, the following display would appear:

**********************************************************************
*                                                                    *
*                 Edit Application Value Description                 *
*                                                                    *
*   Type choices, press Enter.                                       *
*                                                                    *
*   Keyword  . . . . . . . . . . . . :  __________  Name, *NONE      *
*   Description  . . . . . . . . . . :  ___________________________  *
*   Type . . . . . . . . . . . . . . :  _____       *CHAR, *DEC, *NA *
*   Length (such as 04)  . . . . . . :  __          Number (Max of 1 *
*   Decimals . . . . . . . . . . . . :  _           Number (Blank fo *
*   Default  . . . . . . . . . . . . :  __________  Value            *
*   Mandatory non-blank value  . . . :  _           Y or N           *
*   Restricted values  . . . . . . . :  __________  __________       *
*      __________  __________  ___________  __________  __________   *
*   Special values . . . . . . . . . :  __________  __________       *
*      __________  __________  ___________                           *
*   Choice description . . . . . . . :  *DFT______________________   *
*   Range (low and high) . . . . . . :  __________  __________       *
*         Enter any help text in the exact format it should be displ *
*      ____________________________________________________________  *
*      ____________________________________________________________  *
*      ____________________________________________________________  *
*                                                                    *
**********************************************************************

Sample entry displays
---------------------
The  following  displays   show  the   samples  used   to  create   the
Application Value that was previously displayed

The following is the display for the JRN keyword:

**********************************************************************
*                                                                    *
*                                                                    *
*                     Edit Application Value Description             *
*                                                                    *
*   Keyword  . . . . . . . . . . . . :  JRNL______  Name, *NONE      *
*   Description  . . . . . . . . . . :  Journal___________________   *
*   Type . . . . . . . . . . . . . . :  *NAME       *CHAR, *DEC, *NA *
*   Length (such as 04)  . . . . . . :  10          Number (Max of 1 *
*   Decimals . . . . . . . . . . . . :  _           Number (Blank fo *
*   Default  . . . . . . . . . . . . :  __________  Value            *
*   Mandatory non-blank value  . . . :  Y           Y or N           *
*   Restricted values  . . . . . . . :  __________  __________       *
*      __________  __________  ___________  __________  __________   *
*   Special values . . . . . . . . . :  __________  __________       *
*      __________  __________  ___________                           *
*   Choice description . . . . . . . :  *DFT______________________   *
*   Range (low and high) . . . . . . :  __________  __________       *
*         Enter any help text in the exact format it should be displ *
*      The journal name to be used for journaling the data base file *
*         If you do not have a journal to use, you must create one.  *
*                                                                    *
**********************************************************************

The following is the display for the JRNLIB keyword:

**********************************************************************
*                                                                    *
*                     Edit Application Value Description             *
*                                                                    *
*   Keyword  . . . . . . . . . . . . :  JRNLIB      Name, *NONE      *
*   Description  . . . . . . . . . . :  Journal library              *
*   Type . . . . . . . . . . . . . . :  *NAME       *CHAR, *DEC, *NA *
*   Length (such as 04)  . . . . . . :  10          Number (Max of 1 *
*   Decimals . . . . . . . . . . . . :              Number (Blank fo *
*   Default  . . . . . . . . . . . . :  *LIBL       Value            *
*   Mandatory non-blank value  . . . :  Y           Y or N           *
*   Restricted values  . . . . . . . :  __________  __________       *
*      __________  __________  ___________  __________  __________   *
*   Special values . . . . . . . . . :  *LIBL_____  *CURLIB___       *
*      __________  __________  ___________                           *
*   Choice description . . . . . . . :  *DFT______________________   *
*   Range (low and high) . . . . . . :  __________  __________       *
*         Enter any help text in the exact format it should be displ *
*      The library for the journal object___________________________ *
*                                                                    *
**********************************************************************

The following is the display for the AUTOSBM keyword:

**********************************************************************
*                                                                    *
*                     Edit Application Value Description             *
*                                                                    *
*   Keyword  . . . . . . . . . . . . :  AUTOSBM     Name, *NONE      *
*   Description  . . . . . . . . . . :  Auto submit batch update     *
*   Type . . . . . . . . . . . . . . :  *CHAR       *CHAR, *DEC, *NA *
*   Length (such as 04)  . . . . . . :  04          Number (Max of 1 *
*   Decimals . . . . . . . . . . . . :              Number (Blank fo *
*   Default  . . . . . . . . . . . . :  *YES        Value            *
*   Mandatory non-blank value  . . . :  Y           Y or N           *
*   Restricted values  . . . . . . . :  *YES        *NO              *
*                                                                    *
*   Special values . . . . . . . . . :                               *
*                                                                    *
*   Choice description . . . . . . . :  *DFT______________________   *
*   Range (low and high) . . . . . . :  __________  __________       *
*         Enter any help text in the exact format it should be displ *
*      Should an automatic submit of a batch job be done to update . *
*                                                                    *
**********************************************************************

The following is the display for the MAXRCDS keyword:

**********************************************************************
*                                                                    *
*                     Edit Application Value Description             *
*                                                                    *
*   Keyword  . . . . . . . . . . . . :  MAXRCDS     Name, *NONE      *
*   Description  . . . . . . . . . . :  Maximum records              *
*   Type . . . . . . . . . . . . . . :  *DEC        *CHAR, *DEC, *NA *
*   Length (such as 04)  . . . . . . :  10          Number (Max of 1 *
*   Decimals . . . . . . . . . . . . :  0           Number (Blank fo *
*   Default  . . . . . . . . . . . . :  0000050000  Value            *
*   Mandatory non-blank value  . . . :  Y           Y or N           *
*   Restricted values  . . . . . . . :                               *
*                                                                    *
*   Special values . . . . . . . . . :                               *
*                                                                    *
*   Choice description . . . . . . . :  *DFT______________________   *
*   Range (low and high) . . . . . . :  0000010000  0002000000       *
*         Enter any help text in the exact format it should be displ *
*      The maximum number of data base records to be allowed in the  *
*       file for the .... file.____________________________________  *
*                                                                    *
**********************************************************************

Validity checking
------------------

The  tool protects  most  entries that  an  'application designer'  can
make  when  entering the  data  required for  the  EDTAPPVALD displays.
Note that all  decimal values  are entered  as character  data and  the
exact number of digits must be entered without a decimal notation.

When the  'application installer'  enters the  data from the  EDTAPPVAL
display,   the  tool  protects   the  values   entered  based   on  the
information provided by the 'application designer'.

In  most  cases, the  validity  checking will  prevent  improper values
being passed to the application.

Note that the 'application  designer' can change the attributes  of the
keywords  even though data  already exists.   Care  must be  taken when
doing  this as once a value  or a default is  shown to the 'application
installer', the data will not  be changed even though the  'application
designer' changes the rules.

Comments on the Entry displays
------------------------------

  **   A maximum of a 45 byte character value may be entered.

  **   A maximum of a  10 digit decimal value may be entered.   Up to 9
       decimal positions may be declared.

  **   When  the  'application  installer'  uses  EDTAPPVAL, the  input
       fields are  shown  as  either  1, 5,  10,  or  45  positions  in
       length.   When  data  is  entered,  it is  checked  against  the
       declared  length of the  field.  If  excess data is  entered, an
       appropriate  error message  prevents the value  from being used.

Status
------

When  the 'application  designer'  enters  or modifies  an  Application
Value, the  status of the Application Value  is set so that  it must be
reviewed by the 'application installer'.

The  current  status  can  be seen  on  the  EDTAPPVAL  display  and is
included in the completion message.

Any change using  the EDTAPPVALD command  causes the status  to be  set
to EDTRQD.

When the  EDTAPPVAL command  is completed  successfully, the status  is
set  to VALIDATED.   Anytime  EDTAPPVAL  is ended  with the  Enter key,
validation of the values occurs.   Appropriate error messages are  sent
for  invalid values.   Even  if  the values  are  all 'default  values'
validation still occurs.

The  application  can  check   that  the  Application  Value  has  been
validated  by using  the RTVAPPVAL command  and requesting  a return of
the STATUS value.

Batch change method
-------------------

The CHGAPPVAL command is  designed for allowing changes to  an existing
Application Value to be  done in a batch job.  The  intended use of the
command  is to allow an application designer  to add a new attribute or
change an existing  attribute of  an Application Value  and retain  the
existing values.  This would take multiple commands.

Assume  in the  previous  example,  a new  attribute  is  to be  added,
additional help text, improved validity checking etc.

The  'application  designer'  would  use  EDTAPPVALD  and add  the  new
keywords, change the definition, etc.

Assume the 'application designer'  is on a  different system and  wants
to update the application with a re-install program.

The  'application   designer'  would   ship  a   new  version  of   the
Application Value and the following code:

            DCL           &JRN *CHAR LEN(45)
            DCL           &JRNLIB *CHAR LEN(45)
            DCL           &AUTOSBM *CHAR LEN(45)
            DCL           &MAXRCDS *CHAR LEN(45)
             .
            RTVAPPVAL     APPVAL(APPX) KEYWRD1(JRN) VALUE1(&JRN) +
                            KEYWRD2(JRNLIB) VALUE2(&JRNLIB) +
                            KEYWRD3(AUTOSBM) VALUE3(&AUTOSBM) +
                            KEYWRD4(MAXRCDS) VALUE4(&MAXRCDS)
            CHGAPPVAL     APPVAL(APPNEWX) KEYWRD1(JRN) VALUE1(&JRN) +
                            KEYWRD2(JRNLIB) VALUE2(&JRNLIB) +
                            KEYWRD3(AUTOSBM) VALUE3(&AUTOSBM) +
                            KEYWRD4(MAXRCDS) VALUE4(&MAXRCDS) +
                            STATUS(EDTRQD)
            DLTUSRSPC     USRSPC(APPX)
            RNMOBJ        OBJ(APPNEWX) OBJTYPE(*USRSPC) NEWOBJ(APPX)

CRTAPPVALD Command parameters                         *CMD
-----------------------------

   APPVAL        The  qualified  name of  the  Application  Value.   An
                 Application   Value  is   created  as   a  user  space
                 (*USRSPC) with  an attribute of  APPVAL.  The  library
                 value defaults to QGPL.

                 The  user  of  CRTAPPVALD  becomes the  owner  of  the
                 object.    The  *PUBLIC is  authorized  to  *USE which
                 allows any user  to use the  RTVAPPVAL command in  the
                 application.

   TEXT          The text description of the object.

EDTAPPVALD Command parameters                         *CMD
-----------------------------

   APPVAL        The  qualified name  of  the  Application Value.    An
                 Application  Value is a  user space  (*USRSPC) with an
                 attribute of APPVAL.   The library  value defaults  to
                 *LIBL.  *CURLIB may also be used.

EDTAPPVAL Command parameters                         *CMD
----------------------------

   APPVAL        The  qualified name  of  the  Application Value.    An
                 Application  Value is a  user space (*USRSPC)  with an
                 attribute  of APPVAL.   The library  value defaults to
                 *LIBL.  *CURLIB may also be used.

RTVAPPVAL Command parameters                         *CMD
----------------------------

   APPVAL        The qualified  name  of  the Application  Value.    An
                 Application Value  is a  user space (*USRSPC)  with an
                 attribute  of APPVAL.   The library  value defaults to
                 *LIBL.  *CURLIB may also be used.

   RTNLIB        The library  where the  Application Value  was  found.
                 This can be  of value if *LIBL or *CURLIB  is used for
                 the qualified library name.

   KEYWRD1       A  keyword name.  The  name used must be  a keyword in
                 the Application Value  object.   It does  not have  to
                 be the first one specified.

                 For  example,  you could  specify  KEYWRD1(JRN)  where
                 JRN   was   the  5th   keyword   defined  when   using
                 EDTAPPVALD.

                 If  the keyword does not exist,  TAA9897 is sent as an
                 escape message.

   VALUE1        The  return  value associated  with  Keyword  1.    If
                 used,  the value  must be  declared as  *CHAR LEN(45).
                 All  values are  left justified.   If a  decimal value
                 exists, the number of  digits returned will equal  the
                 length specified for the value.

   KEYWRD2-10    A  keyword  value.   Same  as  KEYWRD1 for  the  other
                 keywords.

   VALUE2-10     Same as VALUE1 for the other return values.

   STATUS        The  status  of the  Application Value.    This allows
                 the  application   to   check  if   the   'application
                 installer'  has successfully  edited  the  Application
                 Value.   If  used, the  variable  must be  declared as
                 *CHAR  LEN(10).  The value  returned will be EDTRQD or
                 VALIDATED.

   NBRKWD        The number  of  keywords that  exist.   If  used,  the
                 variable must be declared as *DEC LEN(3 0).

   TEXT          The  text of  the  Application Value.    If used,  the
                 variable must be declared as *CHAR LEN(50).

   RTNSTRUCT     The  return structure of the  Application Value.  This
                 is the  value as it  exists in  the user  space.   See
                 the section on Structure of an Application Value.

CHGAPPVAL Command parameters                         *CMD
----------------------------

   APPVAL        The  qualified name  of  the  Application Value.    An
                 Application  Value is a  user space  (*USRSPC) with an
                 attribute of APPVAL.   The library  value defaults  to
                 *LIBL.  *CURLIB may also be used.

   KEYWRD1       A keyword name.   The name  used must be a  keyword in
                 the  Application Value.   It does  not have to  be the
                 first one specified.

                 For  example,  you  could  specify  KEYWRD1(JRN) where
                 JRN   was  the   5th   keyword  defined   when   using
                 EDTAPPVALD.

                 If the keyword  does not exist, TAA9897 is  sent as an
                 escape message.

   VALUE1        The  new  value  to  set  for  the  keyword  named  in
                 KEYWRD1.   No  validation  is  performed  on  the  new
                 value.

   KEYWRD2-10    A  keyword  value.   Same  as  KEYWRD1 for  the  other
                 keywords.

   VALUE2-10     Same as VALUE1 for the other return values.

   STATUS        The   the  status  of  the   Application  Value  after
                 command is run.   The  default is  EDTRQD.   VALIDATED
                 may also  be specified if  the change will  not impact
                 the existing values.

RPLAPPVALD Command parameters                        *CMD
-----------------------------

   FROMAPPVAL    The  qualified  name of  the  From Application  Value.
                 An  Application Value  is a user  space (*USRSPC) with
                 an attribute of  APPVAL.   The library value  defaults
                 to *LIBL.  *CURLIB may also be used.

                 The  From Application Value  contains the  text, valid
                 entries  etc  that  you want  to  use  instead  of the
                 corresponding values in the To Application Value.

   TOAPPVAL      The qualified name  of the To  Application Value.   An
                 Application Value  is a  user space (*USRSPC)  with an
                 attribute  of  APPVAL.   The object  name  defaults to
                 *FROMVAL  meaning   the   same  object   as   in   the
                 FROMAPPVAL parameter.   The library value  defaults to
                 *LIBL.  *CURLIB may also be used.

                 The To  Application Value contains  the current values
                 for  the specified options that  you want to retain in
                 in the To Application Value.

Structure of an Application Value
---------------------------------

An Application Value is  a user space (*USRSPC) object that  is created
with a length of 8000 bytes.

                 Each keyword uses 750 bytes as follows:

               KWD1     1  -    750
               KWD2   751  -   1500
               KWD3  1551  -   2250
               KWD4  2251  -   3000
               KWD5  3001  -   3750
               KWD6  3751  -   4500
               KWD7  5251  -   5250
               KWD8  6001  -   6000
               KWD9  6751  -   6750
               KWD10 7501  -   7500

The following exists:

          7981   7990   Status of EDTRQD or VALIDATED
          7991   8000   Constant of APPVAL

                 Each keyword has the following layout:

             1     10   Keyword
            11     40   Text
            41     45   Type *CHAR, *DEC, *NAME
            46     47   Length
            48     48   Decimal
            49     58   Default
            59    148   Restricted values
           149    158   Reserved
           159    208   Special values
           209    238   Choice text
           239    248   Low range
           249    258   High range
           259    303   Value
           304    373   Help text 1
           374    443   Help text 2
           444    513   Help text 3
           514    514   Mandatory non-blank
           515    515   Keyword status
                          R = Edit required
                          V = Validated
           516    750   Reserved

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

If the  'application designer' changes  the definition of  an attribute
of  an existing value, it is possible  that the existing value will not
be valid.

There are restrictions on length of  the fields and how the fields  are
displayed.  See the prior discussion.

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

The following TAA Tools must be on your system:

     PMTOPR          Prompt operator
     RTVVALA         Retrieve value attributes
     SNDCOMPMSG      Send completion message
     SNDESCMSG       Send escape message

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

The  'application  designer'  must  create  an  Application  Value  and
define  it  with  the  proper  attributes  to  use  the concept  of  an
Application Value.

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

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

   EDTAPPVAL     *CMD                   TAAAPPA       QATTCMD
   EDTAPPVALD    *CMD                   TAAAPPA2      QATTCMD
   CRTAPPVALD    *CMD                   TAAAPPA3      QATTCMD
   RTVAPPVAL     *CMD                   TAAAPPA4      QATTCMD
   CHGAPPVAL     *CMD                   TAAAPPA5      QATTCMD
   RPLAPPVALD    *CMD                   TAAAPPA6      QATTCMD
   TAAAPPAC      *PGM       CLP         TAAAPPAC      QATTCL
   TAAAPPAC2     *PGM       CLP         TAAAPPAC2     QATTCL
   TAAAPPAC3     *PGM       CLP         TAAAPPAC3     QATTCL
   TAAAPPAC4     *PGM       CLP         TAAAPPAC4     QATTCL
   TAAAPPAC5     *PGM       CLP         TAAAPPAC5     QATTCL
   TAAAPPAC6     *PGM       CLP         TAAAPPAC6     QATTCL
   TAAAPPAD      *FILE      DSPF        TAAAPPAD      QATTDDS
   TAAAPPAE      *FILE      DSPF        TAAAPPAE      QATTDDS

Structure
---------

EDTAPPVAL   Cmd
   TAAAPPAC   CL pgm
     TAAAPPAD   Display file

EDTAPPVALD  Cmd
   TAAAPPAC2  CL pgm
     TAAAPPAE   Display file

CRTAPPVALD  Cmd
   TAAAPPAC3  CL pgm

RTVAPPVAL   Cmd
   TAAAPPAC4  CL pgm

CHGAPPVAL   Cmd
   TAAAPPAC5  CL pgm

RPLAPPVALD  Cmd
   TAAAPPAC6  CL pgm
					

Added to TAA Productivity tools May 1, 1996


Home Page Up to Top