For doing "Table" Searches and variable substitutions similar
to that done by ISPF file tailoring.
The ENBPIU00 tool is a generic "Table lookup" Rexx routine
that processes all/selected rows of an input table, and
produces output based on each row's content and a
"Model" (similar to a dialog skeleton). One or more
models may contain symbolics that are replaced during
the processing of a "Table" by the ENBPIU00 utility.
The values for the symbolics, and the choice(s) for the
"Model", may be selected from each row of the table.
Features:
- Allows simple, user-friendly methods for
defining input data and for formatting of outputs
- Provides optional searching for
user-provided search criteria
- Frequently a simple alternative to writing your
own program
- Developed by the Services team at CA Technologies
Unlike file tailoring, ENBPIU00 has these advantages:
- Does not require ISPF services... ie can run under IRXJCL
or as a compiled rexx or load module.
- Allows variable names to be a mixture of upper and lower
case characters, and up to 250 characters in length. Not
limited to 8 character upper case variable names like
file tailoring.
- Provides a "smart" variable substitution. Only variables
that have values assigned to them are substituted.
Other variables are written to the output still without
being substituted. This feature allows a cascading
affect where you may want to use multiple tables to
provide values for substitutions against a single table.
You can use ENBPIU00 to bypass substitutions for PROC
variables, Endevor variables and others that you want
remain untouched. You do not have to count the periods
as you do in file tailoring. If needed, you can use a
$delimiter value when concatentaing variables. For
example, if $delimiter = "^" then,
&variable#1^&variable#2
concatenates values correctly.
- Provides a dynamic specification for inputs and outputs.
There must be one input file given a name of TABLE.
Files used by ENBPIU00 include the following:
o TABLE - required input file in one of 3 allowed formats:
1) A report image. The first line contains a special
character in column 1 which defines the line as a
'heading'. All remaining lines of the Table are
detail rows of the Table. Variable names are the
words found found in the heading.
2) A fixed-data format. Each field falls into a fixed
position. No 'heading' is present. Instead, a
DDname of POSITION defines the beginning and
ending locations for each variable. Variable names
(and their locations) are defined in the POSITION
file.
3) A Comma Separated Value format. This type of table
does not easily support searching of tables since the
variables are defined by the CSV header.
o MODEL - (1 or more input files)
to define the format of output data.
A model is 'expanded' by ENBPIU00 to produce output.
There must be at least one MODEL, but there may be
multiples. The name 'MODEL' can be changed by
references on the TABLE and/or by references in
OPTIONS and/or by references on a 'PARMLIST'.
o OPTIONS - (1 or more input files)
to define the overrides if any.
You can use "//OPTIONS DD DUMMY" if there are
no overrides.
There must be at least one
OPTIONS, but there may be multiples. The name
'OPTIONS' can be changed by references on a
'PARMLIST' .
Any valid single-line Rexx statement can be coded
within the contents of the OPTIONS file. All
variables that are assigned values in the OPTIONS
file are eligible to be used in the Model
substitution. Uses of the OPTIONS file include:
- Calculating new variables from variables on the
Table.
- Providing override values for variables on
the Table.
- Setting or checking internal Table Tool
variable values.
- Cause multiple Table searches.
o POSITION - (optional input file)
Must be provided only when the Table appears
in a A fixed-data format. Positions must
contain variable names and start & stop
locations when the Table is fixed-format.
o PARMLIST - (optional input file) Used only when the
ENBPIU00 parameter string value is 'PARMLIST'.
An input DDname of PARMLIST must be provided that
lists one or more search requests for a single
Table. The format of the search request in the
PARMLIST file is:
<Model> <Tblout> <Options> <Calling Parm value>
Where:
<Model> - the name of an input Model DD or '*'
to use the default name (MODEL), or
allow OPTIONS to specify a name, or
the name to be designated on the
TABLE.
<Tblout>- the name of an output Tblout DD or '*'
to use the default name (TBLOUT), or
allow OPTIONS to specify a name, or
the name to be designated on the
TABLE.
<Options>- the name of an input Options DD or '*'
to use the default name (OPTIONS).
<Calling Parm value> - 'A' / number / 'M' and search
values as described above in
the Calling Parm value format.
o TBLOUT - (1 or more output files)
Variables from TABLE and/or OPTIONS are expanded
within a MODEL and written to a TBLOUT file.
There must be at least one TBLOUT, but there may be
multiples. The name 'TBLOUT' can be changed by
references on the TABLE and/or by references in
OPTIONS and/or by references on a 'PARMLIST'.
By default, TABLE, MODEL, TBLOUT and OPTIONS are DDnames
in the ENBPIU00 step. You can use TABLE variables or
OPTIONS statements to specify multiple MODEL and TBLOUT
files. Whatever names you specify must also be DDnames
in the ENBPIU00 step.
The simplest method of execution causes each row of a
Table to be processed with one MODEL. Both TABLE and
MODEL are DDnames in the jobstep of a ENBPIU00 execution.
Each row of the TABLE is used for substitution of variables
in the MODEL, and the result is written to the output DDname
TBLOUT.
Alternatively, the "Table" may include a variable entitled
"MODEL". In this case, each unique value under the "MODEL"
heading must also be a DDName in the running JCL.
An input file with the DDName of OPTIONS can add
additional functionality. Any standard REXX variables
assigned values in OPTIONS, are variables that can be
substituted in the Model. For example,
DB2_SUBSYS = 'DB2Q'
Any REXX variables assigned values in OPTIONS and which
appear as a header on the table, keep the value assigned
in OPTIONS. This feature enables OPTIONS to provide
override values to entries on the Table.
IF C1STAGE is a variable (from the Table or OPTIONS) and
its value matches a prefix for an OPTIONS statement, then
the prefix is truncated and the resulting statement is
evaluated. For example, a column in the table is DB2-SUBSYS,
and is given a value of 'DB2Q', then the following OPTIONS
would change the value to 'DB2R' at the Endevor QA stage.
//OPTIONS DD *
C1STAGE = &C1STAGE
QA_DB2_SUBSYS = 'DB2R'
Calling Parameters:
You can use a single PARM value to be passed to ENBPIU00, or
you can specify multiple Parm values to be used in a single
execution of ENBPIU00 within a PARMLIST file.
The Calling Parm value specifies which method Parms are
provided.
Calling Parm value format:
The first word in the parameter string indicates which
rows of the Table are to be processed:
A - indicates all rows of Table are to be processed.
<number> - indicates a fixed number of rows.
Optionally search values may also be provided.
M - indicates only rows matching the provided
search values. The search values must appear
in the Calling Parm string following the 'M'.
PARMLIST - a PARMLIST file is being used to provide
multiple PARM values for a single execution of
ENBPIU00. If the first word in the Calling Parm is
'PARMLIST' then, all other values in the Calling Parm
are ignored. A PARMLIST DD must be provided in the
step to provide one or more parm search values.
You can specify search values in the PARM string, for an
'M" option or a <number> option. Multiple values may be
present, but must be separated by at least one space. Each
of these are paired as a search value with a column from
the table. The first value is used as selection criteria
for the first column in the table. The second value (if
provided) is used as selection critieria for the second
column in the table. Each subsequent value provided is
used as selection critieria for the next column in the
table. When a row is found which contains values that
Match all passed PARMs, then the row is selected. If no
rows $Match, then a return-code 4 is returned. If the
Table depends on a POSITION dd to define the fields, then
the matching is made using the order or definitions.
For example,
if the PARM='1 Green Apples'
then using a top to bottom search, the first row
that has 'Green' in the first column and
'Apples' in the second column is the row selected.
If the "A" (all rows) option is designated, then no other
parameters are necessary.
OPTIONs can cause Table Tool to search a table multiple
times when:
- The Table Tool parameter indicates searching 'M' for
one table column
- OPTIONS provides an override for the Search column
variable and specifies multiple space-delimited
values. Table Tool searches the table for each
space-delimited value.
For example. If LIST-TYPE is the first column in the TABLE.
And OPTIONS contains this statement:
LIST-TYPE = 'BIND1 BIND2'
... causes a search through the table where
LIST-TYPE = 'BIND1'
... and a second search through the table where
LIST-TYPE = 'BIND2'