This paper is based on a session I presented at the Enterprise Modernisation Conference held in Stuttgart in May Updated March 19, 2010

Transcription

1 Enterprise Modernisation Customising RDz with Menu Manager Enterprise Modernisation Working Group, Stuttgart, May 29, 2008 Anthony Rudd DATEV eg This paper is based on a session I presented at the Enterprise Modernisation Conference held in Stuttgart in May Updated March 19, 2010 A.Rudd, Datev eg 1

2 Table of Contents Background General procedure for performing a Menu Manager entry Creating a Menu Manager entry Configuring the executed command Menu Manager sample application used to augment CARMA MVS (sub)projects substitution variables - description Example of a complex command Added action Customised generic menu Displayed parameter input pane Other fields can be selected from a pulldown list (possibly with default) Log output What runs on the mainframe? Example ISPF.conf Example FEK.V7.SFEKSAMP(FEKAPPCC) FEKFRSRV: TSO command server User-written command processor "Exporting" customised actions Finding the location of the local directory Environment variables Setting instance-related environment variables Importing customised actions Removing a previously imported file (from the pulldown list) Using Menu Manager with HATS (Host Access Transformation Services) Differences for HATS HATS Menu Manager properties HATS Menu Manager action invocation Performing the logon Invoked HATS application with passed argument What's missing (subjective assessment) A.Rudd, Datev eg 2

3 Background RDz Menu Manager can be used to make simple customisations for subproject objects. Such a customisation can be used to invoke a user-written command. The command type that can be invoked depends on the associated subproject type (MVS or USS). For example, a (batch) TSO command for an MVS subproject object. Such a command can be passed arguments. Two types of argument are possible: Predefined substitution variables that contain values for the associated object (for example, dataset name, object name) User-defined prompt fields (which can also contain default values and selection lists) This paper describes only the use of MVS subproject entries. Restrictions Menu Manager cannot be used from the RSE. Menu Manager cannot be used at the z/os project or subproject level. A.Rudd, Datev eg 3

4 Menu Manager execution (overview using APPC) MenuMan -> Actions and menus: save %TPFSHARE%\uss_base_file_actions.xml z/os projects view cmd arg Execution Runtime Initiation Definition FEKFRSRV APPC transaction program = TSO Commands service (predefined) FEKAPPCC // EXEC PGM=IJKEFT01, // PARM= ISPSTART CMD(FEKFRSVR) //STEPLIB DD //SYSPROC DD APPC server transaction (customised) <TPFSHARE>: Local environment variable: <installation path>\config\tpfshare directory Note: As of RDz 7.1, the default TSO Commands service is now provided by the optional SCLM Development Toolkit component. A.Rudd, Datev eg 4

5 1.1 General procedure for performing a Menu Manager entry Creating a Menu Manager entry Window -> Preferences -> Menu Manager -> Actions and Menus Actions tab New Local/Remote Action Basic tab Specify the (displayed) action name Specify the associated file type(s) Specify the run options, including the action type Specify the command to be performed together with any arguments A.Rudd, Datev eg 5

6 1.1.2 Configuring the executed command The executed command submits a batch TSO job (IKJEFT01 program). The standard job, FEKAPPCC, is contained in FEK.Vx.SFEKSAMP (Vx = version identification, for example, FEK.V7.SFEKSAMP). This job can be customised with installation-specific libraries. The standard TSO commands service program, FEKFRSRV, performs the specified command and its arguments from the SYSPROC file concatenation. More recent RDz versions can as alternative use the TSO/ISPF Client Gateway (now the default) to invoke TSO commands. In this case, the ISPF.conf file must be customised. 1.2 Menu Manager sample application used to augment CARMA Window -> Preferences A.Rudd, Datev eg 6

7 Menu Manager -> Actions and Menus Customising RDz with Menu Manager A.Rudd, Datev eg 7

8 Specify a file where the customised action is to be saved. Select an existing file from the pulldown menu or click [New ] to specify a new file. Here, the existing uss_base_file_actions.xml file is selected. File: %TPFSHARE%uss_base_file_actions.xml [New Local/Remote Action ] A.Rudd, Datev eg 8

9 Specify the name to be displayed on the menu. Name: CARMA-ADD [Next >] A.Rudd, Datev eg 9

10 Select the associated file types for which the action can be used. This also controls for which file types the action appears in the context menu (right-mouse click on the RSE entry). [Next >] [Select All] can be used to select all file types. A.Rudd, Datev eg 10

11 Run Options Check: Use existing action Select appropriate action type ID, for example, com.ibm.ftt.ui.menumanager.tsoaction -> TSO action Check: Show on generic menu Add variables A.Rudd, Datev eg 11

12 Click [Variables ] to display the list of substitution variables A.Rudd, Datev eg 12

13 Select the required variable from the MVS Projects list and click [Insert] to add it at the cursor position. Click [Close] after all variables have been added A.Rudd, Datev eg 13

14 Augment the parameter list with any required text, arguments, etc. A.Rudd, Datev eg 14

15 Completed command with parameters Customising RDz with Menu Manager [Finish] A.Rudd, Datev eg 15

16 1.3 MVS (sub)projects substitution variables - description $input $list $name $fullname $systemname $userid $projectname $datasetname $clientipaddress $systemhostname Prompted parameter input List of pulldown entries The (member) name of the selected entry The fully qualified name of the selected entry The name of the connection Userid of the logged-on user Project name Dataset name IP address of the client machine Host name The $input entry used to prompt for parameter input has the following format: $input(prompt string, default value [,$list{ selection entry, }]) The prompt string, default value and selection list can themselves contain substitution variables. Extraneous commas and $-characters (other than substitution variables) can cause unexpected results. For example $input(dsn,$datasetname,$list{test.load,my.load}) A.Rudd, Datev eg 16

17 1.3.1 Example of a complex command SEWDZSVW ADD PARM('$input(-P,), $input(-pv,,$list{1.0}), $input(-pgm,$name), $input(-pgmv,), $input(-pl,cobol,$list{asm,c,cobol,cpp}), $input(options,,$list{-delete,-newflag,-delete -NEWFLAG }), $input(-o,$userid), $input(-d,), $input(-c,), $input(-dsn,$fullname)') WARNING: Syntactical errors in the parameter list will cause the action to fail, but without any error message. A.Rudd, Datev eg 17

18 1.3.2 Added action [OK] A.Rudd, Datev eg 18

19 1.3.3 Customised generic menu Customising RDz with Menu Manager A.Rudd, Datev eg 19

20 1.3.4 Displayed parameter input pane Some fields are initialised automatically For example, $input(-pgm [Program Name]*,$name) A.Rudd, Datev eg 20

21 1.3.5 Other fields can be selected from a pulldown list (possibly with default) For example $input( -PL, COBOL,$list{ ASM,C,COBOL,CPP }) pulldown list entries default value displayed prompt The associated display: A.Rudd, Datev eg 21

22 1.3.6 Log output The DD:SYSTSPRT (SAY and TRACE) output is written either to the TPF Toolkit Console (standard) or as popup window (check: Show output in dialog). Example Output in TPF Toolkit Console Output in dialog window A.Rudd, Datev eg 22

23 1.4 What runs on the mainframe? Depending on the method use to invoke TSO commands, either the TSO/ISPF Client Gateway (now default) or the FEKAPPCC APPC transaction is used to invoke the specified TSO command. In both cases, either the ISPF.conf configuration file or the FEKAPPCC JCL will need to be customised with any application-specific libraries. The customised libraries are shown italicised in the following examples Example ISPF.conf By default, the ISPF.conf configuration file is contained in the /etc/rdz/ directory. ispmlib=sys1.sispmenu,tsse000.sewb.mlib isptlib=sys1.sisptenu ispplib=sys1.sisppenu ispslib=sys1.sispslib,tsse000.sewb.slib ispllib=tsse000.fset.ispllib,tsse000.sewb.load sysproc=fek.v75.sfekproc,sys1.sispclib, TSSE000.SEWBBAT.EXEC,TSSE000.SEWB.EXEC,TSRCVW.SRCVW.DIALOG Example FEK.V7.SFEKSAMP(FEKAPPCC) The customised FEKAPPCC job in FEK.Vx.SFEKSAMP (x = RDz version) is submitted. This batch TSO job starts the specified TSO command server (FEKFRSRV). //WDZTSO EXEC PGM=IKJEFT01,DYNAMNBR=50, // PARM='ISPSTART CMD(%FEKFRSRV TIMEOUT=60) NEWAPPL(ISR)' //STEPLIB DD DISP=SHR,DSN=TSSE000.FSET.ISPLLIB // DD DISP=SHR,DSN=TSSE000.SEWB.LOAD //SYSHELP DD DISP=SHR,DSN=SYS1.HELP //SYSPROC DD DISP=SHR,DSN=FEK.V7.SFEKPROC // DD DISP=SHR,DSN=SYS1.SISPCLIB // DD DISP=SHR,DSN=TSSE000.SEWBBAT.EXEC // DD DISP=SHR,DSN=TSSE000.SEWB.EXEC // DD DISP=SHR,DSN=TSRCVW.SRCVW.DIALOG //ISPPLIB DD DISP=SHR,DSN=SYS1.SISPPENU //ISPMLIB DD DISP=SHR,DSN=SYS1.SISPMENU // DD DISP=SHR,DSN=TSSE000.SEWB.MLIB //ISPTLIB DD DISP=SHR,DSN=SYS1.SISPTENU //ISPSLIB DD DISP=SHR,DSN=SYS1.SISPSENU // DD DISP=SHR,DSN=SYS1.SISPSLIB // DD DISP=SHR,DSN=TSSE000.SEWB.SLIB //ISPLIST DD SYSOUT=*,DCB=(BLKSIZE=1210,RECFM=FBA,LRECL=121) //ISPPROF DD DISP=(NEW,DELETE,DELETE),DSN=&&PROF, // SPACE=(TRK,(1,1,5)),LRECL=80,RECFM=FB //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSTSIN DD DUMMY DLM2 A.Rudd, Datev eg 23

24 DLM1 QT A.Rudd, Datev eg 24

25 1.4.3 FEKFRSRV: TSO command server (prewritten, does not need to be customised) FEKFRSRV: Starts the TSO command server on a start-up request via APPC conversation. The server opens a TCP/IP socket, accepts connections from clients, and processes TSO commands. It terminates on a shutdown request. The command (and arguments) passed as options are processed. The user command is taken from the SYSPROC concatenation. In the shown example, SEWDZSVW. The user-written SEWDZSVW is essentially the router that invokes the specified command with its arguments. TSSE000.SEWBBAT.EXEC(SEWDZSVW): PROC 1 CMD PARM() PROFILE LIST MSGID NOPROMPT %SEWDZSV0 &CMD,&PARM END In this case, %SEWDZSV0, with the passed command (ADD)and the argument(s) (',,CICSECD,,COBOL,,T02161A,,,T02161A.ASM(CICSECD)'). A.Rudd, Datev eg 25

26 1.5 User-written command processor TSSE000.SEWBBAT.EXEC(SEWDZSV0): The user-written SEWDZSV0 procedure processes the passed TSO command. /* REXX - SEWDZSV0: SRCVW */ PARSE ARG cmd','parm SELECT WHEN cmd = 'ADD' THEN DO PARSE VAR parm, pj','pv','pgm','pgmv','pl','opts','ownr','descr','comm','dsn END WHEN cmd = 'PUT' THEN DO PARSE VAR parm, pj','pv','pgm','pgmv','pl','opts','comm','dsn END OTHERWISE SAY "unsupported command" EXIT END PARSE VAR parm SELECT WHEN cmd = 'ADD' THEN DO list = "-P" pj "-PGM" pgm "-PL" pl "-DSN '"dsn"'" opts IF pv <> '' THEN list = list '-PV' pv IF ownr = '' THEN ownr = USERID() IF descr = '' THEN descr = 'ohne Beschreibung' IF pgmv <> '' THEN list = list '-PGMV' pgmv IF comm <> '' THEN list = list '-C "'comm'"' list = list '-O' ownr list = list '-D' descr END ADDRESS TSO "SRCVW" cmd list /* perform command */ SAY "RC:" rc /* display return code */ This command processor issues the actual user command, here, SRCVW. A.Rudd, Datev eg 26

27 1.6 "Exporting" customised actions The customised actions cannot be exported directly. The created customised action file must be moved manually to a shared USS file that can be imported by other users. By default, actions are created in the %TPFSHARE%uss_base_file_actions.xml file where %TPFSHARE% is a WINDOWS environment variable that defines the local directory where the file is stored. A.Rudd, Datev eg 27

28 1.7 Finding the location of the local directory Listing environment variables The following three screenshots are taken from the German version of Windows XP. Desktop (Arbeitsplatz) icon (context menu) -> Properties (Eigenschaften) A.Rudd, Datev eg 28

29 System properties -> Extended Customising RDz with Menu Manager Click [Environment variables] (Umgebungsvariablen) A.Rudd, Datev eg 29

30 1.8 Environment variables Customising RDz with Menu Manager The TPFSHARE environment variable points to the base installation directory for the RDz system. WARNING: Only one TSPFSHARE environment variable exists even if more than one RDz version is currently installed Setting instance-related environment variables A batch file can be used to set appropriate the TPFSHARE environment variable for the RDz instance. Sample batch file: echo off setlocal set TPFSHARE=f:\programme\config\TPFSHARE F:\Programme\eclipse.exe -product com.ibm.rational.rad.product.ide endlocal A.Rudd, Datev eg 30

31 2.1 Importing customised actions A previously exported customised actions file can be imported. Such a file can be either a local (Windows mapped file) or a USS file. RDz: Window -> Preferences A.Rudd, Datev eg 31

32 Menu Manager -> Actions and Menus -> Import A.Rudd, Datev eg 32

33 Resource Type: File Click [Browse ] A.Rudd, Datev eg 33

34 Navigate to directory (the directory used here is only an example) host connection -> USS Files -> Root -> etc Note: host connection is any host connection Note: This is not really an import of the specified file s contents, but more correctly should be called create a link to the specified resource. The current contents are always obtained. A.Rudd, Datev eg 34

35 Continue navigating to the send directory (example) etc/wd4z/datev/customizedactions and select file uss_base_file_actions.xml Click [Finish] A.Rudd, Datev eg 35

36 The imported actions now appear in the Actions list Click [OK] A.Rudd, Datev eg 36

37 2.1.1 Removing a previously imported file (from the pulldown list) Click [Remove File] Note: If a system file is involved, click No to prevent the send file from being deleted (this is NOT the default) A.Rudd, Datev eg 37

38 3.1 Using Menu Manager with HATS (Host Access Transformation Services) A HATS application can also be invoked as a Menu Manager application Differences for HATS Action ID: com.ibm.ftt.ui.menumanager.mfiaction Parameters prefixed with "hatsgv_<varname>=" where varname is the name of the associated HATS global variable. Example: hatsgv_dsn=$fullname The HATS global variable DSN is assigned the complete dataset name for which the command was invoked. A.Rudd, Datev eg 38

39 3.1.2 HATS Menu Manager properties Customising RDz with Menu Manager A.Rudd, Datev eg 39

40 3.1.3 HATS Menu Manager action invocation A.Rudd, Datev eg 40

41 3.1.4 Performing the logon A.Rudd, Datev eg 41

42 3.1.5 Invoked HATS application with passed argument The HATS customisation assigned the global variable DSN to the "Data set name" input field. This is initialised with the passed argument, the $fullname value for the associated object. A.Rudd, Datev eg 42

43 4. 1 What's missing (subjective assessment) Menu Manager "commands" can be assigned only to z/os project objects (POmember or PS level) Menu Manager "commands" cannot be assigned to RSE objects Not all properties are available as variables Explicit population of prompt variables is not possible Restriction on the run options available to z/os object (for example, Remote Command and Events File not available) A.Rudd, Datev eg 43

44 Mainframe Neuheiten 2 DATEV eg; alle Rechte November 14th 2008 vorbehalten 44