Customizing the REXX EXEC
You start the CICS BAC ISPF administration interface by invoking
by a REXX EXEC, which is supplied as member CBKRCBAC in the SCBKEXEC
data set. Before you attempt to use the CICS BAC administration interface,
first customize the REXX EXEC. When you customize the EXEC, it is
important that you apply your customization changes to a copy of CBKRCBAC,
and do not change the supplied CBKRCBAC member in SCBKEXEC. If you
modify the supplied version of CBKRCBAC in data set SCBKEXEC, your
changes could be overwritten by any future maintenance to the CICS BAC-supplied
member. You can use one of the following methods to avoid modifying
the original:
- Create a copy of CBKRCBAC with a new name in the SCBKEXEC data
set, choosing a name that suits your own naming standards, such as
CBKRCUST
- Create a copy of CBKRCBAC in a different REXX EXEC data set that
you plan to use for the ISPF administration interface, and keep the
name of the copy as CBKRCBAC
Where relevant, the discussion in this manual is based on the first
of these methods using the EXEC name CBKRCUST and the data set name
SCBKEXEC.
When you have created a copy of CBKRCBAC, customize it to suit
your installation standards. Some of the customization is required,
and some is optional. (Note that character strings need
to be enclosed in double quotation marks as shown in the parameter
descriptions.) The required changes are to REXX EXEC parameters
that specify data set names, and also the mirror transaction identifier,
described as follows:
- CBKCMIR = "CSMI"|"tranid"
- Specifies the name of the CICS® mirror
transaction to be specified on EXCI requests issued by CICS BAC ISPF
administration interface. When the EXCI request is executed in the
target CICS region, it runs under this transaction ID
as an MRO mirror transaction.
- CSMI
- This is the normal CICS EXCI default mirror transaction
ID.
- transid
- Specifies the 4-character name that you want CICS to
use as the name of the MRO mirror transaction when it executes the
EXCI requests it receives from CICS BAC ISPF administration interface.
To avoid confusion with other mirror transactions that might be running
in your CICS regions, you might want to choose a unique
ID to identify CICS BAC ISPF administration interface mirror transactions.
Define the appropriate transaction ID in the CICS region
for a CICS mirror transaction, ensuring the following:
- The program associated with the transaction ID must be DFHMIRS
- The profile for the transaction ID must be DFHCICSA.
You might consider using the CICS-supplied CSMI transaction definition
as a basis for this transaction ID.
- CBKLLIB="&hlq.SCBKLOAD"
- CBKEXEC="&hlq.SCBKEXEC"
- CBKMLIB="&hlq.SCBKMENU"
- CBKPLIB="&hlq.SCBKPENU"
- CBKTLIB="&hlq.SCBKTENU"
- Specify your own high-level qualifiers that you chose for these
five ISPF administration interface data sets when you installed them.
In CBKRCBAC, the data set names are defined on their respective parameters
with the prefix &hlq. Substitute the actual
high-level qualifier for the string &hlq.
The five parameters, and their corresponding data sets, are as follows:
- CBKLLIB
- Specifies SCBKLOAD, the CICS BAC module load library
- CBKEXEC
- Specifies SCBKEXEC, the CICS BAC REXX EXEC library
- CBKMLIB
- Specifies SCBKMENU, the CICS BAC ISPF administration interface
English messages data set
- CBKPLIB
- Specifies SCBKPENU, the CICS BAC ISPF administration interface
panels data set
- CBKTLIB
- Specifies SCBKTENU, the CICS BAC ISPF administration interface
English table data set containing the default PF key settings.
- CBKSUMLQ="middle_qualifier"
- Specifies the middle qualifier of the data set that the ISPF
administration interface uses to save information about each user
of the interface. This is referred to as the TSO user's CICS BAC ISPF
table. The REXX EXEC allocates the data set with a name in the
form TSOuserid.cbksumlq.CBKTABL, where TSOuserid is the TSO user ID, and cbksumlq is the middle qualifier. The first time you start the
ISPF administration interface it creates the CICS BAC TSO user data
set automatically for you, and thereafter allocates the data set each
time you start the interface.
- middle_qualifier
- Specifies the middle qualifier of the data set that the ISPF
administration interface maintains for each TSO user of the interface.
The high-level qualifier is the TSO user ID and the low-level name
is CBKTABL. The ISPF administration interface use this TSO
user's CICS BAC ISPF table to save your data when you select various
options from the primary menu. See Specifying the control file table data set and Selecting a target CICS region.
The remaining parameters in the EXEC that you can tailor for your
own needs are all optional.
- CBKCFTDS="table_dataset_name"
- Specifies a default control file table data set name. If you
specify this parameter, the ISPF administration interface uses this
table data set name whenever a user starts the ISPF administration
interface for the first time; that is, when the user data set specified
by the CBKSUMLQ does not exist. The default control file table data
set name specified by CBKCFTDS is stored in your TSO user's CICS BAC ISPF
table as an initial value, and is the same for all new user's of the CICS BAC ISPF
interface.
When the CICS BAC REXX EXEC starts, it checks to see if
the TSO user's CICS BAC ISPF table (as specified using the CBKSUMLQ
parameter) already exists, and if it does, the TSO user is not a new
user and the ISPF administration interface ignores the CBKCFTDS parameter.
If the TSO user's CICS BAC ISPF table does not exist, the ISPF
interface checks to see if CBKCFTDS specifies a data set name (that
is, not a null value). If CBKCFTDS specifies a valid data set name,
it is entered in the TSO user's CICS BAC ISPF table as the name of the
control file table data set name.
Using this parameter removes
the need for new users of the interface to specify their control file
table data set name using option 3 on the Primary Option Menu. However,
although the data set is specified by the CBKCFTDS parameter, it is
not selected for the ISPF session and you still have to select the
data set using option 2 on the Primary Option Menu.
Note:
If
you specify the CBKCFTDS in your CICS BAC REXX EXEC parameters, it is
used for all new users of the CICS BAC ISPF administration interface
and thus can be used only when the control file table data set name
specified is common to all users of the interface.
- CBKCFTCO
- Specifies a default control file table data set comment about
the data set specified on CBKCFTDS. This is used only when you also
specify the CBKCFTDS parameter.
- CBKSMAXD=12|number
- Specifies the maximum number of 4KB pages the ISPF interface
is to allocate as a buffer for downloading data from the target CICS
region. You can specify a number of pages in the range 1 through
999; the default is 12.
Note:
Note that a command fails if
the allocated buffer is too small for the command.
- CBKSBRWE=4096||number
- Specifies the maximum number of browse entries the ISPF interface
is to allow to be downloaded for any request. This affects the list
of resources for a selected region, as well as prompt lists for resource
types. You can specify a number in the range 1 to 4096; the default
is 4096.
- CBKSLPRM="N"|"Y"
- Specifies that the ISPF administration interface is automatically
to use the MV logical parmlib concatenation when looking for the control
file table CBKCFTBL.
- N
- On initial startup do not look for CBKCFTBL in the MVS parmlib
concatenation
- Y
- On initial startup, automatically look for CBKCFTBL in the MVS
parmlib concatenation.
All the required and optional customization fields are fully commented
in the CBKRCBAC REXX EXEC.
Starting the REXX EXEC
When you have completed the customization of your ISPF administration
interface CBKRCUST REXX EXEC, you can start the interface by entering
the following command on the ISPF Command Shell command line (the
ISPF Command Shell is usually option 6 on the ISPF Primary Option
Menu):
EXEC 'hlq.SCBKEXEC(CBKRCUST)'
If you've stored the EXEC in a different data set, replace hlq.SCBKEXEC with the your own data set name.
Tailoring existing ISPF menus
You can also add the CICS BAC ISPF administration interface to an
existing ISPF menu. The following is an example of the steps needed
to do this, where the administration interface is defined as option
C.
- First, add a line similar to the following to the ")AREA" section
of the menu panel source:
C CICS BAC CICS BAC ISPF administration interface
- Next, add the following line in the ")PROC" section of the menu
panel source:
C,'CMD(CBKRCUST) NOCHECK NEWAPPL(CBKA)'
Also ensure that the data set containing the REXX EXEC CBKRCUST
is added to your TSO logon PROC SYSPROC concatenation. The REXX EXEC
is the only CICS BAC data set you need to add to the logon PROC, because CICS BAC dynamically
allocates all the other required data sets during the ISPF administration
interface startup.