Configure and Use the Menu System and Web Interface

To install and customize the menu system and web interface, use the information in the following sections:
spool12
To install and customize the menu system and web interface, use the information in the following sections:
 
 
2
 
2
 
 
Environments
The 
CA Spool
 menu system operates under CICS, CA IDMS, TSO/ISPF, TSO, CA Roscoe, IMS, NATURAL, and directly under VTAM.
The 
CA Spool
 web interface is a special version of the 
CA Spool
 menu system that runs on a z/OS web server on the same MVS image as 
CA Spool
. An HTML presentation layer converts the 3270 data-stream into HTML on the fly.
Customization
All help texts and error messages in the menu system are contained in the source member ESFHTEXT, and can easily be changed. The layout of the printer and file displays is defined in the ESFHPARM module source and is easily changed. It is also possible to change the position of the separate fields and their headings and attributes (input/output field, highlight, color, reverse video).
Modules in the Menu System
The 
CA Spool
 menu system consists of the following modules:
  •  
    ESFHTSO
    Displays panels for TSO users (source)
  •  
    ESFHISPF
    Displays panels for ISPF users (source)
  •  
    ESFHIMS
    Displays panels for IMS users (source)
  •  
    ESFHCICS
    Displays panels for CICS users (source)
  •  
    ESFHIDMS
    Displays panels for CA IDMS users (source)
  •  
    ESFHESF
    Displays panels for VTAM menu (source)
  •  
    ESFHCI
    Communicates with one of the above modules and the 
    CA Spool
     address space (load)
  •  
    ESFHBROW
    File browse module (load)
  •  
    ESFHPARM
    Contains panel layouts (source)
  •  
    ESFHTEXT
    Contains fixed texts (source)
  •  
    ESFHWAIT
    Wait routines for all environments (source)
National Language Support
By default, the 
CA Spool
 menu system supports the following languages:
Danish
German
Swedish
English
Italian
French
Spanish
You can customize the language to be included in the menu system load-module based on your requirements. Other languages can also be employed.
Installation
 
To install the menu system
 
Define a communication channel in the 
CA Spool
 parameter deck (ESFPARM data set) with the generic name MENU.
CID MENU,USMR=NO,MAXPORT=10,OPENTYPE=U
Define the users in your external security package, or internally in 
CA Spool
. For more information, see Implement Security.
CICS Installation
 
To install the menu system in the CICS environment
 
  1. If you are running a version of CICS earlier than TS 3.1.0, add the following line after the &ESFCICS SETB statement in BQ4JCICS:
    &CTS310 SETB 0 1=CICS 310 or higher
  2. Run the job BQ4JCICS, if not already done during 
    CA Spool
     installation.
  3. Define the program and transaction for the 
    CA Spool
     CICS menu interface into the desired RDO group using CICS program DFHCSDUP:
    DEFINE PROGRAM(ESFMCICS) GROUP(ESF) LANGUAGE(ASSEMBLER) DEFINE TRANSACTION(ESFM) GROUP(ESF) PROGRAM(ESFMCICS) TWASIZE(0) TASKDATALOC(BELOW) TASKDATAKEY(USER)
    Add the RDO group to your CICS startup list (the SIT parameter GRPLIST=).
  4. Copy the ESFMCICS load-module from the 
    CA Spool
     load library to a library within the DFHRPL concatenation in the CICS startup JCL deck.
     When installing CICS support on to a 
    CA Spool
     task that has already been started, the modules loaded into the CSA must be reinitialized by issuing the "REINIT,MODULES,ON" command followed by a recycle of the 
    CA Spool
     started task.
New CICS Release
The BQ4JCICS job must be run again if a new version or release of CICS is installed on the system. For instructions about how to modify and run this job, see the first two steps in the preceding section, CICS Installation.
CICS Menu System Startup
The CICS menu system is started in either of two ways:
  • By entering the transaction ID directly on an empty CICS screen.
  • By invoking it from another CICS transaction or program.
Invoking the Menu System
 
Note:
 The invocation must be done using XCTL to the menu system program with a common area as specified in the following table:
 
Offset (decimal)
 
 
Length
 
 
Description
 
000
008
Reserved. Must be initialized to X'00'.
008
004
Restart transaction code. Must name a CICS transaction to invoke the menu system. It is used to regain control after giving control to CICS waiting for the user to enter new information.
012
004
New transaction code. If this field is non-blank, the value specified is used as "next-transaction-ID" when the menu system terminates.
016
008
Program name. If this field is non-blank and the new transaction code is blank, the 
CA Spool
 menu system will XCTL to this program when it terminates.
024
002
Command. If this field is non-blank it is used as a command for the 
CA Spool
 menu system, such as F/FA/P/PS/PB.
026
008
Related node. In this field is non-blank it is used as a related node equivalent to specifying RN 
xxxxxxxx
. It must be 8-characters long, padded with spaces.
034
006
Related group. If this field is non-blank it must be numeric with leading zeros. The value indicates the related group equivalent to specifying RG 999.
040
008
Owner prefix. If this field is non-blank it is used as the owner prefix equivalent to specifying OP 
xxxxxxxx
. The field must be 8-characters long and padded with spaces.
048
008
Printer prefix. If this field is non-blank it is used as the printer prefix equivalent to specifying PP 
xxxxxxxx
. The field must be 8-characters long and padded with spaces.
056
004
Subsystem name. If this field is non-blank it is used as the subsystem name equivalent to specifying SUB 
xxxx
. The field must be 4-characters long and padded with spaces.
060
008
NJE name. If this field is non-blank it is used as the NJE name equivalent to specifying NJE 
xxxxxxxx
. The field must be 8-characters long and padded with spaces.
068
002
Length of user field. This field must be a binary half word indicating the length of the following field.
070
--
User field. If the previous field specifies a length greater than zero, this field is passed as COMMAREA to the new transaction or new program, which gains control when the 
CA Spool
 menu system terminates.
CA IDMS/DC Installation
 
To install the menu system in the CA IDMS/DC environment
 
  1. Run the job BQ4JIDMS, if not already done during installation of 
    CA Spool
    .
  2. Define a suitable CA IDMS transaction pointing to the ESFMIDMS load-module.
TSO/ISPF Installation
 
To install the menu system under TSO/ISPF
 
  1. Copy the EHCPAN11 panel from the 
    CA Spool
     CBQ4PNL0 library to a library within the ISPPLIB concatenation in your TSO logon procedure.
  2. Copy the EHCBROW CLIST from the 
    CA Spool
     CBQ4CLS0 library to a library within the SYSPROC concatenation in your TSO logon procedure.
    CLIST EHCBROW contains a UNIT=VIO reference for the allocation of a temporary dataset to be used for browsing. Clients must verify that UNIT=VIO is a valid DASD allocation UNIT at their site, and if not, must change UNIT=VIO to a valid DASD type.
  3. Copy the ESFMENU CLIST from the 
    CA Spool
     CBQ4CLS0 library to a library within the SYSPROC concatenation in your TSO logon procedure.
You can start the TSO/ISPF menu system by invoking CLIST ESFMENU with the 
CA Spool
 subsystem name as parameter:
%ESFMENU ESF
where the operand ESF is the name of the subsystem you want to activate. You can also hard code a subsystem name in the CLIST.
 The ISPF menu interface supports dynamic screen sizes. The screen width limit is 132. The number of rows can be any number as long as the total screen area, row * columns, is less than 11880.
TSO Installation
To install the menu system in the TSO environment, copy the ESFMTSO load-module from the 
CA Spool
 link library to your TSO command library.
To start up, enter the following command:
ESFMTSO
CA Roscoe Installation
 
To install the menu system in the CA Roscoe environment
 
  1. Run BQ4JROSC, if not already done, during 
    CA Spool
     installation.
  2. Copy the ESFMTSO load-module from the 
    CA Spool
     load library to a library within the ETSOLIB concatenation in the CA Roscoe startup deck.
  3. Update the CA Roscoe eligible program list to include the ESFMTSO member as a CP-routine.
  4. Make the ROETSAPI module from the CA Roscoe load library available to the 
    CA Spool
     task using STEPLIB or linklist.
To start up, issue the command:
CALL ESFMTSO
IMS Installation
 
To install the menu system in the IMS environment
 
  1. Run the job BQ4JIMS, if not already done during installation of 
    CA Spool
    .
  2. Define the program and transaction to IMS:
    APPLCTN PSB=ESFMIMS,PGMTYPE=(TP,,1) TRANSACT CODE=ESFMIMS,MODE=SNGL,SEGNO=400,SEGSIZE=0, PRTY=(03,05,00040),PROCLIM=(1,99),SPA=(18000,DASD), MSGTYPE=MULTSEG
    Be sure that the used PSB and PSBW buffer pool sizes are at least 2700 bytes.
  3. Copy the ESFMIMS load-module from the 
    CA Spool
     link library to a library accessible to the IMS message region in which it must execute.
     IMS preload is currently not supported for ESFMIMS.
  4. Run the job BQ4JPSB to generate a PSB for the menu system.
  5. Run the job BQ4JACB to generate an ACB for the menu system.
NATURAL Installation
 
To install the menu system under NATURAL
 
  1. Run the job BQ4JNALD to load the NATURAL program into the Natural system file.
  2. Add the name ESFHCI to the static list in the NATPARM module and assemble it.
  3. Make the following changes to your NATURAL link job:
    • Add the DD statement:
      //SESFLNK DD DSN=dsname,DISP=SHR"
    dsname
     is the name of your 
    CA Spool
     link library.
    • Add the following include statement:
      INCLUDE SESFLNK(ESFHCI)
To invoke the NATURAL menu system, enter 
ESFM
 on the NATURAL command line.
VTAM Installation
 
To install the menu system in the VTAM environment
 
  1. Copy the ESFMESF load-module from the 
    CA Spool
     link library to a library accessible to the 
    CA Spool
     started task.
  2. If you have changed the name of the ESFMESF load module, verify that the new name of the load-module is reflected by the ESFMESF keyword on the MODULES statement in the ESFPARM data set.
Install the Web Interface on z/OS 2.1 and Earlier Releases
Under z/OS 2.1 and earlier releases, the 
CA Spool
 web interface runs as a native CGI gateway program under the z/OS Domino HTTP server. This server is part of the z/OS base product for z/OS 2.1 and earlier releases. For information to configure the z/OS HTTP server, see the 
z/OS HTTP Server Planning, Installing, and Using 
guide.
 
Follow these steps:
 
  1. Customize your web server environment variables file installed in /cai/caspool/httpd.envvars as needed. This file can work without changes.
  2. Customize your web server configuration file in /cai/caspool/httpd.conf:
    • The HostName variable must specify the TCP/IP domain name of the MVS system where the web server is running.
    • The Port variable must specify the TCP/IP port number for use by the web server.
  3. Customize the CBQ4PROC(CAIQWEB) JCL procedure member as needed and copy it to an active PROCLIB library.
  4. Use an MVS 'S CAIQWEB' command to start the web server.
  5. Enter the following line in a web browser to invoke the 
    CA Spool
     web interface. Use the Hostname and Port values defined in Step 2.
    http://**HostName**:**port**/caspool/esfhweb
  6. (Optional) Customize the web interface for your environment.
Install the Web Interface on z/OS 2.2 and Later Releases
Starting with z/OS 2.2, the 
CA Spool
 web interface runs as a native CGI gateway program under the z/OS Apache HTTP server. This server is part of the z/OS base product.
 For information to configure the z/OS HTTP server, see the IBM Redpaper
 IBM HTTP Server on z/OS: Migrating from Domino-powered to Apache-powered
.
To install the 
CA Spool
 web interface on z/OS 2.2 and later, follow this process:
  1. Review and verify the assumptions.
  2. Install the Apache HTTP server.
  3. Confirm that the Apache HTTP server is installed correctly.
  4. Configure the Apache server to work with 
    CA Spool
     Web Interface.
  5. Create a started task to run the z/OS HTTP Apache server.
  6. Start and stop the z/OS HTTP Apache server.
  7. (Optional) Customize the web interface for your environment.
 
Step 1: Review and Verify the Assumptions
 
  1. Review and verify the following assumptions:
    • The product code for IBM HTTP Server powered by Apache is located at /usr/lpp/ihsa_zos.
    • The installation directory for 
      CA Spool
       is in your home directory, for example, /cai/caspool.
    If your environment uses a different value, specify that value instead as you perform the steps that follow.
 
Step 2: Install the Apache HTTP Server
 
  1. Create an installation directory for the server configuration files, for example:
    cd /cai/caspool mkdir websrv
  2. Change the directory to the HTTP Server product directory:
    cd /usr/lpp/ihsa_zos
  3. Run the installer program, bin/install_ihs, to perform these tasks:
    • Install the HTTP Server product files in your home directory
    • Perform the initial configuration
    • Create symbolic links from your home directory to the product directory
     On z/OS, the install_ihs command creates a separate directory for each instance without creating another copy of the product. Use the install_ihs command to create a new IBM HTTP Server instance directory. Do 
    not
     attempt to manually copy the IBM HTTP Server directories.
    Use these parameters to run the installer program:
    • The installation directory for the configuration files
    • The non-SSL port for the web server; select a port other than the default port of 80; for example, 8081 or 8082
    For example:
    ./bin/install_ihs /cai/caspool/websrv 8081
 
Step 3: Confirm That the Apache HTTP Server Is Installed Correctly 
 
  1. Change to the server's installation directory:
    cd /cai/caspool/websrv/bin
  2. Run these commands to verify that the Apache HTTP Server was successfully installed:
    apachectl -v apachectl configtest
  3. Review the output. For a successful installation, the output appears similar to the following example:
    # apachectl -v Server version: IBM_HTTP_Server/8.5.5.2 (Unix) Server built: Jul 11 2014 18:07:04 # apachectl configtest Syntax OK
 
Step 4: Configure the Apache Server to Work with 
CA Spool
 Web Interface
 
Customize your web server configuration file for the Apache server. To enable 
CA Spool
 Web interface on the new server, customize the following example for your environment, and add it to the end of your /cai/caspool/websrv/conf/httpd.conf file, as follows:
  1. Customize the location and filename of the CA Spool Web Interface configuration file, SetEnv ESF_WEBINI /caprod/caspool/$esfweb.ini.
  2. Customize the location and name of the CA Spool Web Interface SWAP directory, SetEnv ESF_SWAP /caprod/caspool/tmp/swap. Change the "Alias /caspool/swap" directive to the new SWAP directory name.
  3. If you Configure Web Interface to Let Users Convert AFP Files to PDF (AFP), change the A2PDPARM FDOutput parameter to the new SWAP directory name. 
  4. If you use the Java transformers to view AFP files as PDF files, change the CAIQENVA environment variable D2E_WEB_SWAP to the new SWAP directory name.
  5. If you configure the CA Spool Web Interface to view text files as PDF, RTF, or HTML (as explained later on this page), change the ESFPARM T2PD, T2HT, and T2RT DEFNODE PATH parameters to the new SWAP directory name.
    # SAF (RACF) authorization # ------------------------ # SAF authentication is provided by the mod_authnz_saf # module. The mod_authz_default and mod_auth_basic modules # provide basic authentication and authorization support # which is needed in mod_authnz_saf configurations. LoadModule authnz_saf_module modules/mod_authnz_saf.so # ============================================================ # CA Spool Web Interface # ------------------------------------------------------------ <Location /caspool/> AuthName "CA Spool" AuthType Basic AuthBasicProvider saf # CA Spool requires an authorized user Require valid-user SAFRunAs %%CLIENT%% # No translation by default for location /caspool/ CharsetSourceEnc IBM-1047 CharsetDefault ISO8859-1 </Location> # CA Spool help is in EBCDIC <Location /caspool/help/EN_US/> CharsetSourceEnc IBM-1047 CharsetDefault ISO8859-1 </Location> # # Map URIs to directories ScriptAlias /caspool/esfhweb /cai/caspool/esfhweb ScriptAliasMatch /caspool/ESF* /cai/caspool/esfhweb Alias /caspool/castyles.css /cai/caspool/castyles.css Alias /caspool/images /cai/caspool/images Alias /caspool/swap /cai/caspool/swap # # # Override location and filename of the CA Spool Web Interface # configuration file: #SetEnv ESF_WEBINI /caprod/caspool/$esfweb.ini # # Override location and name of the CA Spool Web Interface SWAP # directory: #SetEnv ESF_SWAP /caprod/caspool/tmp/swap # # Please note the above "Alias /caspool/swap" directive must be changed # to the new SWAP directory name. # # If the AFP transformers are being used to view AFP files as PDF, then # the A2PDPARM FDOutput = parameter must be changed to the new SWAP # directory name. # # If the Java transformers are being used to view AFP files as PDF, # then the CAIQENVA Environment Variable D2E_WEB_SWAP= must be changed # to the new SWAP directory name. # # If the CA Spool Web Interface has been configured to view Text files as # PDF, HTML or RTF, then the ESFPARM T2PD, T2HT and T2RT DEFNODE PATH= # parameters must be changed to the new SWAP directory name. # # ============================================================
    The Apache Server supports both native z/OS key management (gskkyman key database) and SAF keyrings, so you can use SSL to secure access. To enable SSL support, you need an additional LoadModule statement and virtual host definition in the httpd.conf file.
    Example 1
    This example shows the default SSL port of 443 and specifies a gskkyman key database as the key store.
    LoadModule ibm_ssl_module modules/mod_ibm_ssl.so Listen 443 <VirtualHost *:443> SSLEnable </VirtualHost> SSLDisable KeyFile /users/apache/keys.kdb
     
    Example 2
    This example uses a SAF keyring instead of a gskkyman key database. The SSLServerCert refers to the label name defined on the certificate when it was created. The /saf value on the KeyFile statement is a required literal when a SAF keyring is to be used. The keyring name follows the /saf literal.
    LoadModule ibm_ssl_module modules/mod_ibm_ssl.so Listen 443 <VirtualHost *:443> SSLEnable SSLServerCert spoolwebssl </VirtualHost> KeyFile /saf WEBRING SSLDisable
 
Step 5: Create a Started Task to Run the z/OS HTTP Apache Server
 
  1. Customize the CBQ4PROC(CAIQWEBA) JCL procedure member as needed and copy it to an active PROCLIB library.
  2. Define the user ID for CAIQWEBA.
  3. Define a RACF (or other SAF) STARTED rule to map the CAIQWEBA started task to the user ID.
 
Step 6: Start and Stop the z/OS HTTP Apache Server
 
  1. Use an MVS 'S CAIQWEBA' command to start the z/OS HTTP Apache Web Server.
  2. Go to SYSLOG and search for messages issued by the CAIQWEBA STC until you find the following message:
    STC51452 00000094 IHS is active. Use jobname CAIQWEBx for MVS commands.
    Remember the assigned jobname CAIQWEBx.
  3. Verify that the Apache HTTP Server is running successfully by loading the default 
    CA Spool
     Web Interface web page with the host name or IP address of your z/OS system and the defined port number.
    For example:
    http://**HostName**:**port**/caspool/esfhweb
  4. Use an MVS ‘P CAIQWEBx’ command to stop the Web Server.
Customize the Web Interface
To customize the web interface, modify the default initial configuration of the $esfweb.ini USS HFS file, as follows:
You 
may
 have already completed this specification if you performed the steps in the section Install the Web Interface on z/OS 2.2, earlier on this page. A sample file follows.
 The Web Interface module reads this configuration file from the same directory where the module resides. However, you can change this default by creating an environment variable, ESF_WEBINI, and specifying an alternate directory and name.
# # CA Spool Web Interface ini file # ESF_ID=ESF Default ESF Subsystem Name ESF_TEXT=0 Default Text Language (0 - 6) # 0 - English # 1 - German # 2 - French # 3 - Spanish # 4 - Italian # 5 - Swedish # 6 - Danish ESF_FORM=0 Default Panel Format ESF_SCRZ=2 Default Screen Size: # 2 - 1024 x 768 # 3 - 1152 x 864 # 4 - 1280 x 1024 ESF_PRTX=1 Printer Index (0=OFF, 1=ON) ESF_ACMD=1 Action Commands (0=OFF, 1=ON) ESF_NCMD=1 Native Commands (0=OFF, 1=ON) ESF_TRAC=0 Web Trace (0=OFF, 1=ON) ESF_PRTM=1 Printer Metrics (0=OFF, 1=ON) ESF_WIND=2 Separate Window (0=No, 1=Yes, # 2=Multiple) ESF_MBAR=0 Window Menu Bar (0=No, 1=Yes) ESF_ASIS=0 Windows Viewer (0=No, 1=Yes) ESF_A2PD=0 View AFP as PDF (0=No, 1=Page, # 2=Line, 3=All, 4=A2PDREPT) # If the AFP transformers are being used to view AFP as PDF the # A2PDPARM FDOutput = must point to the Web Interface SWAP directory. # If the Java transformers are being used to view AFP files as PDF, # the CAIQENVA Environment Variable D2E_WEB_SWAP= must point to the # Web Interface SWAP directory. # ESF_T2YY=1 View Text as (0=3270, 1=PDF, # 2=HTML, 3=RTF) # If ESF_T2YY>0 the ESFPARM T2PD, T2HT and T2RT DEFNODE definitions # must be updated to point to the Web Interface SWAP directory. # ESF_IPAD=2 Printer TCP/IP Address (0=Hyperlink, # 1=Static Text, 2=Editable Text) ESF_TIME=0 Time Display (0=GMT, 1=Local) ESF_AUTO=10 Auto Display (0=OFF, 1-255 Seconds) # ESF_SCLU=0 Swap cleanup (0=OFF, 1-999 Min.) ESF_BCLU=0 Browse cleanup (0=OFF, 10-999 Sec.) # #NJE-WEB Nje-Node=HTTPhost:HTPPport #NJE_WEB A31IESF1=usilca31:8080 #NJE_WEB A11IESF1=usilca11:8080
 ESF_IPAD allows a change in access to the options that are displayed. Hyperlink is the default option whether ESF_IPAD is set or not. ESF_IPAD=1 allows access to the options Hyperlink and Static Text. ESF_IPAD=2 allows access to all options, Hyperlink, Static Text, and Editable Text.
Configure Web Interface to Let Users Convert Text Files to HTML, PDF, or RTF
Follow these steps to configure the 
CA Spool
 Web Interface to transform text files into PDF, HTML, or RTF automatically when users open them to browse them:
  1. Open the CAIQPOOL/ESFPARM file and verify that it specifies the following parameter:
    X2YY START=YES
  2. Open the default parameters member, CAI.CBQ4PARM(CAIQPARM). Locate the following DEFNODE statements, and verify that each TCPHOST points to the swap directory. Use the following statements as models.
    DEFNODE T2PD,TEXT2PDF,TCPDRIV=DISKH,TRANS=C037T19U, TCPHOST='PATH=/cai/caspool/swap,FILENAME=*.PDFLB' DEFNODE T2HT,TEXT2HTM,TCPDRIV=DISKH,TRANS=C037T19U, TCPHOST='PATH=/cai/caspool/swap' DEFNODE T2RT,TEXT2RTF,TCPDRIV=DISKH,TRANS=C037T19U, TCPHOST='PATH=/cai/caspool/swap'
  3. Locate the $esfweb.ini file.
    This file is the web server initialization file for the 
    CA Spool
     web interface. By default, this file is installed in the /cai/caspool directory. If the file does not exist there, you likely specified a custom location for the file during the installation. Review your SMP/E Apply output to find the location of the file.
  4. Verify that the $esfweb.ini file is accessible by the web server, as follows:
    1. Enter the ls - l command:
      ls - l $esfweb.ini
    2. Verify that the permission level is 755 or 777.
  5. Open the $esfweb.ini file and update the value of the ESF_T2YY parameter to 1, 2 or 3, as follows:
    ESF_T2YY=2 View Text as (0=3270, 1=PDF, # 2=HTML, 3=RTF) ESF_A2PD=1
    The value that you specify becomes the default format for web interface users to view text files. For example, if you specify 2, then, by default, when web interface users open text files, the files are automatically converted to HTML format.
  6. Start the 
    CA Spool
     Web Interface and open the Options menu. Verify that the View Text files option is set according to your specifications in the previous step.
  7. Inform web interface end users that they can optionally override the default setting by selecting a different value in the View Text files option on their Options menus.
Language Support
The menu system permits up to 10 different languages from which you can select the desired one. As each of these languages contains large text portions, it is recommended to include only the languages that you require at your installation.
Your users can select the languages, by issuing a command TEXT 
n
 in the menu system, where 
n
 is a number between 0 and 9. You can decide which value to use for which language. The language with the value zero is the default language for startup. If no language included is assigned the value zero, the menu system does not start.