Exec Invocation
2. The RLXS command must be specified as a CMD (command) rather than a PGM (program) to the ISPF SELECT service. RLXS will issue a warning message and
immediately terminate if you incorrectly specify RLXS as a PGM rather than a CMD. The following illustrates correct and incorrect coding of the PROC section of an ISPF Selection Menu:
&ZSEL = TRANS(TRUNC (&ZCMD,'.')
1,'CMD(RLXS TARGET PARM)' Correct
2,'PGM(RLXS TARGET PARM)' Incorrect
The same restriction applies if the ISPF SELECT service is issued within a dialog via the ISPEXEC command. For example:
ISPEXEC SELECT CMD(RLXS TARGET PARM) Correct
ISPEXEC SELECT PGM(RLXS) PARM(PARM) Incorrect
3. The last cautionary item pertains to the use of the ISPF CONTROL service within the context of a dialog running under the RLXS front-end. Internally, RLX switches among several concurrently active ISPF dialog functions, each with its own ISPF dialog error handling environment. This effectively masks any ISPF CONTROL ERRORS setting your dialog may explicitly issue.
For this reason you should use the RLX CONTROL ISPERROR service in the RLX/TSO environment in lieu of the ISPEXEC CONTROL ERRORS service to set the error mode for the ISPF dialog environment. The RLX command resets the ISPF dialog error handling mode to the setting specified by your RLX CONTROL ISPERROR request -- before returning control to your EXEC.
Note that your dialog always starts with an initial RLX CONTROL ISPERROR setting of CANCEL. Any ISPERROR mode you specify will not become effective until the first RLX command is issued, even when specified through the RLX Profile or through the RLXS main invocation panel described in Section 3.5.5. For full details, see the reference sections that describe the RLX CONTROL ISPERROR service in Chapter 6.
3.5.1 Invoking the RLXS Command on the TSO Command line
You can issue the RLXS command on any ISPF panel that contains a TSO Command line. The following fragment illustrates how to invoke an exec named EXAMPLE with the RLXS front-end and pass it two parameters:
COMMAND ===> TSO RLXS EXAMPLE PARM1 PARM2
By prefixing the command string with the TSO keyword, ISPF knows to pass the command to TSO for execution. When TSO receives 'RLXS EXAMPLE PARM1 PARM2' as a command string, it attaches RLXS as a TSO command processor and passes the rest of the string 'EXAMPLE PARM1 PARM2' as a parameter. You can use this technique to invoke an RLX/TSO dialog from any ISPF panel which contains a command field.
The RLXS command establishes the RLX session environment and invokes the target command procedure (always specified as the first positional parameter). Thus, you can edit and test your RLX procedures repeatedly within the same ISPF Edit session. You can make revisions and, as soon as you SAVE the current version, execute another trial.
While an RLX/TSO application is being developed and tested, the RLXSRUN command provides an even more convenient way to invoke the EXEC via the RLXS front-end -- from within ISPF Edit. You can run the exec or CLIST currently being edited -- directly from the Edit command line. RLXSRUN is further described in the RLX/SDK Reference.
SUGGESTION: It is possible to equate a PF key with a command string which will invoke an RLX procedure via the ISPF command 'KEYS'. For example: PF1 ===> TSO RLXS EXAMPLE PARM1 PARM2
3.5.2 Invoking the RLXS Command from within another EXEC
One of the methods to create a seamless interface to an RLX dialog function is to invoke the RLXS Command from within another exec. In the following example, the exec which invokes the RLXS command contains no embedded SQL statements.
/* REXX */
"RLXS example" parm1 parm2 (1)
Return
where,
(1) The RLXS command string invokes the target exec named EXAMPLE and passes it a pair of positional parameters, PARM1 and PARM2
NOTE: You can issue the RLXS command from within a REXX exec or TSO CLIST when the RLX session environment is already active.
RLX processes an RLXS command issued during an active RLXS session as an implicit EXEC command - e.g. %EXAMPLE PARM1 PARM2
3.5.3 Invoking the RLXS Command as an ISPF SELECTION Menu Option
The remaining two methods make use of the ISPF SELECT service to invoke the RLXS front-end and a target exec or TSO CLIST. The following fragment in Figure 3.5 illustrates RLXS invocation as an ISPF selection menu option. The next section illustrates the use of the ISPF SELECT service.
________________________________________________________________
OPTION ===>_ZCMD
1 - RLX EXAMPLE Dialog )PROC
ZSEL = TRANS( TRUNC (ZCMD,'.')
1,'CMD(RLXS EXAMPLE PARM1 PARM2)' ...
________________________________________________________________
Figure 3.5
IMPORTANT: The RLXS command must be specified to the ISPF SELECT service as a CMD (command) rather than a PGM (program).
RLXS will issue a warning message and immediately terminate if you incorrectly specify RLXS as a PGM rather than a CMD.
3.5.4 Invoking the RLXS Command through the ISPEXEC SELECT service
The ISPEXEC SELECT service can also be issued from within an exec to achieve the result illustrated in the previous section.
address ispexec 'SELECT CMD(RLXS TARGET PARM1 PARM2)'
By default, the RLXS command runs as an ISPF dialog function within whatever ISPF application is currently active. You can use the NEWAPPL option of the SELECT service to switch to a new ISPF application ID when you invoke your RLX dialog as illustrated below.
address ispexec 'SELECT CMD(RLXS TARGET PARM1 PARM2) NEWAPPL(NEW)'
The same options apply to the ISPSTART service. ISPSTART provides a seamless means to invoke ISPF at logon and immediately launch an RLX application that runs as an ISPF dialog.
3.5.5 Main Invocation Panel
It is possible to issue the RLXS command without designating a target exec or CLIST.
When you do so, the RLX Main Invocation Panel illustrated in Figure 3.6 is displayed.
This panel lets you specify the name of the command procedure (REXX exec or TSO CLIST) you wish to execute along with any parameters it requires. At this time, you can also review and revise the attributes of your RLX Profile which are retained across RLX sessions.
The panel prompts labeled Target RLX Procedure and Permit Update are discussed in this section immediately following the figure. The rest of the prompts presented during the RLX Main Invocation dialog are the same as those of the RLX User Profile Facility which is detailed in Chapter 4.
___________________________________________________________________________________
RLX --- Relational Language Executive --- Command ===>
In the following panel fragment, the prompt labeled Target RLX Dialog Name elicits the name of the REXX exec or TSO CLIST that you wish to execute. The Dialog Parms field elicits the parameters, if any, to be passed to the procedure.
Target RLX Dialog (REXX exec or TSO CLIST) Dialog Name ===> EXAMPLE
Dialog Parms ===>
The Permit Update option governs whether the second and third RLX User Profile panels will be displayed. If this field is modifiable and you specify a value of 'Y', you will have an opportunity to review and revise these settings as necessary. Note: The Permit Update
field may contain an ‘N’ and be non-modifiable. This means that the option to prevent users from updating their RLX session profile through the RLX Profile panels was selected when RLX was installed.
Environmental Parameters
Permit Update ===> Y (Can user change their RLX profile?)
3.6 RLXS Keyword Parameters
The RLXS command can be passed Session Profile information via a set of keyword parameters whose names begin with the letters RLX. See Section 4.1 for other means to specify (or accept defaults for) the attributes which collectively constitute (and are referred to as) your RLX Session Profile.
RLXS keyword parameters and their associated values must appear as the last tokens in an RLXS command string -- as illustrated below -- following any parameters to be passed to the target RLX EXEC.
RLXS TARGET PARM1 PARM2 RLXPROF(PROFNAME) RLXS TARGET PARM1 PARM2 RLXDSN(DSN)
Please remember: Developers who use the RLXS command front-end should avoid the use of execs, CLISTs or keyword parameters whose names begin with the letters 'RLX'.
The RLXS keyword parameters are described below in alphabetical order.
• The RLXAUTH keyword parameter provides a means to specify a DB2 authorization ID to qualify any unqualified DB2 table and/or view names referenced by RLX SQL statements executed at runtime.
• The RLXDSN keyword parameter identifies the DB2 subsystem with which RLXS should connect. The RLXDSN parameter is useful in migrating an RLX application from one DB2 subsystem to another without impacting the application's users.
• The RLXISPRM keyword parameter specifies the name of the REXX parameter module RLX should use within ISPF to explicitly create a REXX language processor environment (and associated REXX Environment Block). The default value is RLXISPRM.
• The RLXMODE keyword parameter directs RLX to operate in shared thread mode when RLXMODE(SHARE_THREAD) is specified. This advanced feature is described in detail in Chapter 24 of this publication.
• The RLXPGM keyword parameter specifies the name of the RLX SQL load module to use during an RLX session. This load module executes the SQL statements issued by your RLX exec and CLIST procedures.
• The RLXPLAN keyword parameter specifies the name of the DB2 application plan to use during an RLX session. The name can specify one of the dynamic plans shipped with RLX or a static plan created with RLX/Compile. See the RLX/Compile Reference for further information.
• The RLXPROF keyword parameter names an RLX shared profile whose values will set the RLX Session Profile for the current session only. No update to the RLX User Profile will occur. The RLXPROF mechanism enables the RLX application developer to specify Session Profile attributes for all users of a particular dialog -- without disturbing those users' individual profiles. See the RLX Installation and Customization Guide or ask your RLX product administrator for information on defining RLX Shared Profiles.
• The specification RLXSTAX(NOPROMPT) suppresses issuance of prompting message RLX994I when a dialog user presses the ATTN key. By default, the RLX attention exit driven by an attention interruption issues the following prompt:
‘RLX994I RLX command interrupted. Clear the screen and press the ENTER key.'
3.7 Running RLX / TSO applications in the TSO / ISPF background
Figure 3.7 illustrates the JCL to run an RLX/TSO application in batch under TSO and ISPF. The following job runs the same TBLNAMES EXEC that was described and illustrated earlier in this chapter in Figure 3.2. The jobstream exists in machine readable form as the member RLXBTSO of the RLXCNTL dataset.
Batch executions of RLX/TSO procedures require the same library allocations as their TSO foreground counterparts. See Chapter 2 for a more complete discussion. In addition, the diagnostics issued by RLX/TSO in background mode are comparable to those available in the TSO/ISPF foreground.
//STEPLIB DD DSN=RLX.VvRrMm.LOAD,DISP=SHR, *** RLX program library // UNIT=sysda,VOL=SER=volser
//SYSPROC DD DSN=RLX.VvRrMm.EXEC,DISP=SHR, *** both CLISTs and execs // UNIT=sysda,VOL=SER=volser
// DD DSN=RLX.VvRrMm.CLIST,DISP=SHR, // UNIT=sysda,VOL=SER=volser
//SYSEXEC DD DSN=RLX.VvRrMm.EXEC,DISP=SHR, *** REXX execs only // UNIT=sysda,VOL=SER=volser
//*--- //* ISPF dialog libraries
//*---
//ISPMLIB DD DSN=RLX.VvRrMm.RLXMLIB,DISP=SHR, *** RLX message library // UNIT=sysda,VOL=SER=volser
// DD DSN=ISP.VvRrMm.SISPMENU,DISP=SHR, // UNIT=sysda,VOL=SER=volser
//ISPPLIB DD DSN=RLX.VvRrMm.RLXPLIB,DISP=SHR, *** RLX panel library // UNIT=sysda,VOL=SER=volser
// DD DSN=ISP.VvRrMm.SISPPENU,DISP=SHR, // UNIT=sysda,VOL=SER=volser
//ISPSLIB DD DSN=RLX.VvRrMm.RLXSLIB,DISP=SHR, *** RLX skeleton library // UNIT=sysda,VOL=SER=volser
// DD DSN=ISP.VvRrMm.SISPSENU,DISP=SHR,
// UNIT=sysda,VOL=SER=volser
//RLXLOAD DD DSN=RLX.VvRrMm.LOAD,DISP=SHR, *** Private RLX program library // UNIT=sysda,VOL=SER=volser
//*--- //* REXX output and RLX diagnostics //*--- //SYSTSPRT DD SYSOUT=*
ISPSTART CMD(RLXS TBLNAMES SYSIBM RLXDSN(DSN) RLXPLAN(RLXPLANC) RLXPGM(RLXSQL)
___________________________________________________________________________________
Figure 3.7 RLX/TSO Batch Jobstream
The RLXEXEC library (dataset RLX.VvRrMm.RLXEXEC) must be allocated to DDname SYSPROC and/or SYSEXEC. Allocate the RLX message library (dataset RLX.VvRrMm.RLXMLIB) to the file named ISPMLIB. Lastly, allocate DDname SYSTSPRT to SYSOUT or to a sequential print dataset of your choosing. The SYSTSPRT file receives the batch diagnostics.