Task 5.2 Install File-AID/EX Mainframe Components

File-AID Executive is an optional addition to File-AID/EX. It provides the MVS Access Modules that enable a developer to access mainframe data on z/OS.

The MVS Access Modules supply many z/OS data sources to the File-AID/EX execution server. The access modules can accept requests from a File-AID/EX execution server running locally or from a remote File-AID/EX execution server connected over the network. The MVS Access Modules use TCP/IP connections to communicate over the network. The supported z/OS data sources are: IMS, QSAM, VSAM ESDS, and VSAM KSDS. By moving related DB2 data types to a distributed database, File-AID/RDX extract files are also supported.

Following figure represents the flow of communication among the facilities of File-AID/EX.

File-AID/EX Communication Flow

Task 5.2.1 Install File-AID Executive

Refer to the File-AID Installation and Configuration space for instructions on installing and configuring File-AID Executive.

Task 5.2.2 Install File-AID/EX Scheduling Agent (FEAgent)

File-AID/EX can be run using a scheduler on z/OS. When a conversion completes, a return code is sent to the system. The following sections detail the File-AID/EX Scheduling Agent and return codes.

Perform this task only if you plan to use trigger File-AID EX from a JCL configured on a scheduler on the z/OS. A z/OS UNIX console tool (for example, TELNET or OMVS) must be used to install the FEAgent.

Considerations

• If using OMVS, ensure the TSO region size is large enough to run Java.
• FEAgent requires less than 100 KB of initial space. Sufficient space should be available in the upload and target directories to contain the files.
• The user ID must have a default OMVS segment (or something equivalent) specifying a valid non-zero z/OS UNIX user ID (UID), home directory, and shell command.
• The user ID should have authority to write to the directory in which the FEAgent will be installed.

Procedure

Use the following steps to install the FEAgent in z/OS UNIX on a target LPAR.

1. Run setup.exe on TED media image downloaded from an electronic distribution order, or from the Topaz Enterprise Data media.
2. Select the FEAgent tab in the media browser and select the Install FEAgent for z/OS UNIX link.
3. Use the built-in FTP facility to transfer the FEAgent files to z/OS UNIX.
   • Supply the host, userID, password, and the target path name of an existing z/OS UNIX directory where the FEAgent is to be executed.
   • Select the Upload Files to the Mainframe button to initiate the FTP transfer.
     For example, host LP01 directory /usr/local/Compuware/feagent
4. In z/OS UNIX, locate the path to a current Java Virtual Machine (JVM). The FEAgent requires a minimum of Java JRE 1.8 or higher. (For example, /usr/lpp/java/java8). For validation purposes, execute the shell command:
   
   [path]/bin/java -version
   where [path] is the pathname to the JVM
   (for example: /usr/lpp/java/java8/bin/java -version).
5. Edit the uploaded feagent.sh file.
   1. Update the path of the JVM from the example /PATH/TO/JAVA/ON/USS/bin/java to the actual value.
   2. Update the path to the feagent.jar file: /PATH/TO/FEAGENT/INSTALL/feagent.jar.
   3. v1 — No change to be made.
   4. v2 and v3 are required when both optional parameters PROPERTY_LOCATION and LOG_LOCATION will be customized and supplied from the JCL. When only one of optional parameters is to be customized, then only v2 is required. In either case, v2 and v3 must follow after the required v1 parameter. When the default is taken, neither v2 or v3 should be specified.

Starting FEAGENT

To execute FEAGENT on the mainframe you must submit a JCL that will execute the feagent program via the shell script mentioned in the install instructions. The following sample can be used to build on.

1. Update the PARM for the BPXBATCH program, with the absolute path of the feagent.sh file (which was modified in the previous step on the z/OS UNIX).

2. Update the STDENV with the parameters v1 (required), v2 and v3 (optional).

   Parameter v1

   This is a mandatory parameter and must appear first in the list supplied parameters. The format of this parameter consists of five ordered values, each separated by a space.

   <TCP/IP Address> <PORT> <Specification Type> <File Path> <File Name>

   <TCP/IP Address> is the TCP/IP address that the File-AID/EX execution server is running
   
   <Port> is the port that the File-AID/EX execution server is running
   
   <Specification Type> can be ConverterPro, Extract or Loader.
   
   <File Path> is the absolute path of the directory where the specification file resides. Please note that directory path should not contain spaces. Please note that this parameter is optional, and if not supplied the program would look for the specification file in the location: <File-AID/EX_Install_Path>/Conversion/
   
   <File Name> is the name of the specification file with its file extension.

   Example: 10.100.10.10 4900 ConverterPro c:\Specs TestSpec.xml

   Parameters v2 and v3

   The following two parameters are optional, and if both are supplied, their order does not matter but must follow parameter v1.

   PROPERTY_LOCATION: is the absolute path of the feagentSecurity.properties file. If a value is not provided, the program defaults to looking for it in the same folder where the feagent.jar resides. If it is not present in that location, the program exits with an error message.

   LOG_LOCATION: is the absolute path where generated log files are to be written to. When this location is supplied, that directory path location must already exist. If the program is not able to write to the specified directory or if not able to create the default logs location, the program would log into the STDERR.txt file that the log files could not be created. Though there will be no execution logs in such a case, the program will not continue to execute normally. not supplied, the program creates a sub-directory named logs under the feagent.jar file’s parent directory.

   Error

   Warning

   Ensure the program has sufficient read/write privileges in order to create log files in the chosen directory.

   Scenario 1: When both the PROPERTY_LOCATION and LOG_LOCATION parameters are to have customized locations. Supply the two variables in the JCL and ensure the feagent.sh file has the v2 and v3 parameters specified after the v1 parameter.

   v2=PROPERTY_LOCATION=/usr/local/compuware/fb/feagent

   v3=LOG_LOCATION=/usr/local/compuware/fb/feagent/logs

   Scenario 2: When only one of the two parameters needs customized, for example the LOG_LOCATION. In this case, just specify v2 in the feagent.sh file, and only include the following after v1 definition in the JCL.

   v2=LOG_LOCATION=/usr/local/compuware/fb/feagent/logs

   Scenario 3: If both parameters are to use the default locations, then you do not specify either v2 and v3 in the feagent.sh file. Only specify v1 in the JCL, for the STDENV.

3. Update the path for the stdout.txt and stderr.txt to the desired location. The recommended location would be the same as the directory where the faegent.jar is present.
   
   

Return Code Processing

When the specification completes, the File-AID/EX execution server sends a Return Code to the FEAGENT, which sends the code back to the calling operation and FEAGENT terminates. The following are the Return codes returned by the File-AID/EX execution server:

File-AID/EX Return Code Values

Changing the Heartbeat Signal Frequency for the Execution Server

A heartbeat signal is sent from the execution server back to the FEAgent, to indicate that the process it submitted is still running on the execution server.

The default frequency of this signal is set at 900 seconds (15 minutes). This value can be adjusted based on the needs, for instance, related to the network timeout. For example, if the timeout interval on the network is 600 seconds, then the value of the heartbeat signal can be reduced to 570 seconds such that it occurs prior to the network’s timeout.

To change the default heartbeat signal frequency:

1. Shut down the execution server
2. Open the engine.properties file located by default at \ProgramData\Compuware\FAEX\Cfg.
3. Change FEAgentHeartbeatFrequency = 900 to the desired duration.
4. Save and close the file.
5. Restart the execution server

Additional information can be found in the engine.properties file.