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
|
