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
|
