2.1 RLX Libraries ... 2-2 2.2 Basic file allocations for all environments
(batch, TSO, ISPF and NetView) ... 2-2 2.3 Additional library allocations to exploit the TSO/ISPF environment ... 2-4 2.4 Preallocating the RLX Libraries ... 2-4 2.5 How to dynamically allocate and free the
RLX libraries (on an application basis) ... 2-6 2.6 The ALTLIB command of TSO/E ... 2-6 2.6.1 ALTLIB Functions ... 2-7 2.6.2 ALTLIB Examples ... 2-8 2.6.3 ALTLIB Usage Notes ... 2-9 2.7 Verify that RLX is accessible ... 2-9 2.8 RLX User Facility ... 2-11 2.9 Stored Procedures Tester ... 2-12
This chapter describes the dataset allocations required to run RLX in the various environ-ments it supports -- which include MVS batch as well as batch and foreground versions of TSO and ISPF. (The unique requirements of the NetView environment are described in Chapter 7 of the RLX Installation Guide). The discussion assumes that RLX is already installed on the DB2 subsystem to which you will want to connect.
RLX may already be installed and deployed for general use in which case this material serves mainly as reference. Ask your RLX product administrator whether any further allocations are necessary to use RLX in the TSO/ISPF foreground. Section 3.4 provides sample JCL that illustrates how to run RLX execs natively in batch and Section 3.7 describes how to run RLX in the TSO/ISPF background.
Section 2.2 describes the basic dataset allocations required for all environments. Section 2.3 discusses the additional allocations required to exploit the ISPF environment. Section 2.4 describes and illustrates how the RLX libraries can be preallocated before the ISPF environment is entered while Section 2.5 describes the use of the ISPF LIBDEF service and the ALTLIB facility of TSO/E to dynamically allocate and release the RLX libraries on an application basis.
2.1 RLX Libraries
Figure 2.1 lists the RLX libraries and the DDnames to which they are allocated. The names of the RLX libraries in the figure are those restored from the distribution tape.
They may be different in your environment. Check with your RLX product adminis-trator to determine if these are the actual dataset names in use at your installation.
All RLX libraries can be shared among multiple users and multiple DB2 subsystems.
These include the RLX load module library, the RLXEXEC and RLXCLIST libraries and the ISPF panel, message and skeleton libraries.
Throughout this publication, VvRrMm refers to the target libraries created at your site during installation. Thus, all references to VvRrMm in this manual should be read as referring to the actual node name of the target datasets created at your site -- e.g.
V9R9M3. SYSPROC RLX.VvRrMm.RLXCLIST RLX CLIST library
RLX.VvRrMm.RLXEXEC RLX EXEC library (or allocate to SYSEXEC) SYSEXEC RLX.VvRrMm.RLXEXEC RLX EXEC library
ISPLLIB RLX.VvRrMm.RLXLOAD RLX load module library ISPMLIB RLX.VvRrMm.RLXMLIB RLX ISPF message library ISPPLIB RLX.VvRrMm.RLXPLIB RLX ISPF panel library
ISPSLIB RLX.VvRrMm.RLXSLIB RLX file tailoring skeleton library RLXTLIB RLX.VvRrMm.RLXTLIB RLX permanent ISPF tables
____________________________________________________________________________
Figure 2.1
2.2 Basic file allocations for all environments (batch, TSO, TSO/ISPF and NetView)
Two RLX library allocations -- the RLXLOAD and RLXMLIB datasets -- are required for all environments in which RLX procedures will run. The next section describes the additional library allocations that exploit the TSO/ISPF environment.
Ask your RLX product administrator whether the RLXLOAD and RLXMLIB datasets have been preallocated during installation. If so, you need not allocate them now.
Otherwise, the RLX libraries can be allocated through a TSO LOGON procedure or an EXEC or CLIST used to initialize the environment.
The RLX supplied versions of the REXX parameter modules IRXISPRM, IRXPARMS and IRXTSPRM must be accessible ahead of any other versions of these modules.
However, this requirement does not apply if the RLXS front end is employed to invoke
your REXX execs in an ISPF environment.
The load modules of the RLXLOAD library should be accessible through the standard MVS search order. In addition, unless you the RLXS command processor front end to invoke an RLX exec or CLIST within ISPF (as described in Chapter 3.2), you must ensure that the REXX parameter modules (IRXPARMS, IRXTSPRM and IRXISPRM) supplied with RLX are loaded from the RLXLOAD dataset and not from some other library. Otherwise, your RLX procedures will not work properly.
NOTE: One other option is to customize the REXX parameter modules to include definitions for the Host Command Environments and REXX function packages employed by RLX. Appendix D of the RLX Installation Guide describes the customization procedure for REXX parameter modules in detail.
MVS conducts its search for the requested module in the following sequence:
1. The job pack area queue
2. A task library (such as ISPLLIB) if one is allocated
3. A private STEPLIB or JOBLIB (If defined in the TSO LOGON procedure) 4. Link Pack Area
5. The Link list concatenation
The simplest and most reliable method is to allocate the RLXLOAD dataset to the ISPLLIB DDname. This file defines the task library from which load modules are fetched during an ISPF session. Alternatively, you can allocate a private STEPLIB or JOBLIB in your TSO LOGON procedure if you have the authority. Be cautioned that any dynamic STEPLIB facility you have available to you may not work properly for purposes of setting up the environment for RLX. This is because the appropriate REXX parameter modules are already loaded -- before you issue a command to alter the STEPLIB concatenation.
The RLX message library should be allocated to the DDname ISPMLIB -- in both ISPF and non-ISPF environments. RLX messages are maintained in an ISPF format but can be processed even if ISPF is not active. RLX has its own facilities to access the message library and conduct variable substitution to produce runtime message text. This allows the same messages to be utilized in all the environments that RLX supports such as NetView, MVS batch, TSO and TSO/ISPF.
2.3 Additional library allocations to exploit the TSO/ISPF environment
In addition to the RLXMLIB dataset (the RLX message library), the RLX panel library (RLXPLIB dataset) should be allocated in ISPF environments so RLX can display diagnostic messages on scrollable ISPF panels.
ISPMLIB RLX.VvRrMm.RLXMLIB RLX ISPF message library ISPPLIB RLX.VvRrMm.RLXPLIB RLX ISPF panel library ISPTLIB RLX.VvRrMm.RLXTLIB RLX permanent ISPF tables
The ISPF skeleton library (DDname ISPSLIB) and table library (DDnames ISPTLIB and ISPTABL) supplied with RLX are more typically of interest to users of RLX/Compile and/or AcceleREXX (both of which are documented in their own sections) or to product installers and administrators who will run the RLX installation, maintenance and administrative dialogs.
2.4 Preallocating the RLX Libraries
This section describes how to preallocate the RLX libraries for the ISPF environment.
Perhaps the easiest and most reliable way to allocate the RLX datasets is with a REXX exec or TSO CLIST which can be executed from the TSO READY prompt, before ISPF is entered. This option lets you concatenate your own run-time libraries as well.
The RLXEXEC library contains a member named RLXAPA that provides an illustrative -- but not executable -- procedure that issues TSO ALLOCATE commands to setup the TSO/ISPF environment for use with RLX. The RLXAPA exec appears below in Figure 2.2. In the figure, the datasets named base.xxxx.libraries refer to the set of TSO/ISPF libraries which are always allocated in your environment. The numbers in the figure's right margin correspond to the numbered, annotating paragraphs that follow.
NOTE: The RLX Installation Guide describes how to pre-allocate the RLX libraries via a variety of methods.
___________________________________________________________________________________
Exec RLXAPA /* REXX */
Address TSO
'free dd(sysproc sysexec ispllib ispmlib ispplib ispslib)'
"alloc dd(ispllib) da('rlx.VvRrMm.rlxload'", (1)
"'base.load.libraries'", (2)
") shr reuse"
"alloc dd(ispmlib) da('rlx.VvRrMm.rlxmlib'", (3)
"'base.message.libraries'",
(1) The DDname ISPLLIB is used as a task library when fetching load modules. It is searched prior to the system link libraries and the link pack area. The RLXLOAD library is concatenated ahead of other dialog datasets allocated to DDname ISPLLIB to ensure the RLX versions of the REXX parameter modules are loaded when referenced. In addition, be sure the system libraries that contain DB2 executable code are either in the link list or are also pre-allocated.
(2) The dataset referred to as 'base.load.libraries' refers to the set of load libraries that are typically allocated in your environment to the DDname ISPLLIB.
(3) The RLX message library is allocated to the file ISPMLIB (4) The RLX panels are allocated to the file ISPPLIB
(5) The RLX skeleton library is allocated to the file ISPSLIB
(6) In the TSO environment, the EXECUTIL SEARCHDD command governs the search for execs that are implicitly invoked. Specifying SEARCHDD(YES) directs the system to first search the datasets allocated to the SYSEXEC DDname. If not found, the search continues with the libraries allocated to SYSPROC. If you make use of
both execs and CLISTs, this technique will shorten the search for REXX execs.
(7) Exec libraries must be allocated before their members can be invoked implicitly.
The option illustrated here is to allocate them to the DDname SYSEXEC if the EXECUTIL SEARCHDD(YES) command is specified as in note (6). Alternatively in the TSO environment, exec libraries can be allocated along with TSO CLISTs to the SYSPROC file described in note (8). Lastly, TSO users in OS/390 and MVS/ESA environments can use the ALTLIB command (described in Section 2.6 of this manual and in the TSO/E Command Reference) to control the search for execs and CLISTs.
(8) CLIST libraries should be allocated to the DDname SYSPROC before CLISTs can be invoked implicitly. An alternative in the OS/390 and MVS/ESA environments is to use the ALTLIB command (described in Section 2.6). The SYSPROC concatenation can reference both exec and CLIST libraries.
2.5 How to dynamically allocate and free the RLX libraries (on an application basis)
You can use the RLXDYN exec in the ISPF environment to first dynamically allocate the RLX dialog libraries via a series of ISPF LIBDEF services and TSO ALTLIB commands and then call your exec or CLIST. Ask your RLX product administrator about the availability and use of the RLXDYN exec.
2.6 The ALTLIB command of TSO/E
The ALTLIB command, a TSO/E feature available in OS/390 and MVS/ESA environments provides users with greater speed and flexibility in specifying command procedure libraries from which REXX execs and TSO CLISTs can be implicitly executed.
REXX execs and TSO CLISTs may be invoked implicitly, simply by specifying the command procedure's name. (When invoked implicitly, the fully qualified dataset name of the library containing the target EXEC or CLIST is omitted.) Implicit execution is simpler to code and easier to read. In addition, implicit execution is required if the REXX exec or CLIST is invoked by the ISPF SELECT service or the RLXS command frontend (described in Chapter 3 of the RLX/SQL Reference).
Ordinarily, in order for REXX execs and TSO CLISTs to be invoked implicitly, they must reside in a library preallocated to file SYSEXEC (for REXX execs) or file SYSPROC (for either execs or TSO CLISTs).
However, pre-allocating files SYSPROC or SYSEXEC can be problematic if, for example:
• your TSO logon procedure cannot be modified
• the SYSEXEC and SYSPROC datasets are protected, or
• you need to mix exec or CLIST libraries with different dataset attributes.
The ALTLIB command solves such problems because with it you can:
• Easily activate and deactivate additional REXX exec and CLIST libraries for implicit execution without disturbing the list of datasets concatenated to files SYSEXEC and/or SYSPROC. Furthermore, you can issue the ALTLIB command from within the ISPF environment. There is no need to return to the TSO READY prompt.
• You can continue to access installation-wide REXX execs and CLISTs, since the SYSEXEC and SYSPROC file allocations remain undisturbed.
• Search time for the EXEC and CLISTs will be reduced since the system searches the ALTLIB libraries first, using the Virtual Lookaside Facility (VLF).
• The ALTLIB command lets you specify EXEC and CLIST libraries whose dataset characteristics (record format, record size, etc.) are different from those of the libraries already allocated to files SYSEXEC and SYSPROC.
2.6.1 ALTLIB Functions
The ALTLIB command offers four functions, which use the following operands:
• ACTIVATE Allows implicit execution of REXX execs and CLISTs
• DEACTIVATE Removes libraries from the search order
• DISPLAY Displays the current search order
• RESET Resets the search order to just the SYSEXEC and
SYSPROC datasets
The ACTIVATE and DEACTIVATE functions permit you to divide execution libraries into 3 groups (or levels) termed USER, APPLICATION and SYSTEM. The system conducts the search for an implicitly named EXEC in that order.
The USER level permits searching of datasets previously allocated to SYSUEXEC and SYSUPROC while the SYSTEM level affects the search of libraries allocated to files SYSEXEC and SYSPROC.
NOTE: Since SYSEXEC and SYSPROC libraries are already available for implicit execution, the primary advantage is increased library search speed for the EXECs and CLISTs.
The APPLICATION level lets you dynamically specify a list of command procedure libraries or a DDNAME of your choice, which should be searched for an implicitly named procedure. For this reason, the APPLICATION level is (arguably) the most useful and most-often used ALTLIB group.
Additional parameters on the ALTLIB command allow you to activate and/or deactivate REXX EXECs, TSO CLISTs or both EXECs and CLISTs at once.