Configuring File-AID/EX Executive
This section provides the information and procedures to customize the File-AID/EX Executive component of File-AID/EX Enterprise Edition once the SMP/E installation of File-AID Common Components has completed (see RFN SMP/E Installation of BMC AMI Mainframe Products” or “Appendix A, SMP/E Installation Using the EP Media Interface” in BMC Installer Mainframe Products SMP/E Installation).
Overview
File-AID/EX Enterprise Edition is an optional addition to File-AID/EX and includes File-AID/EX Executive. File-AID/EX Executive provides the MVS Access Modules that enable a developer to access mainframe data on z/OS. File-AID/EX Executive requires an APF load library. This section provides configuration instructions for the MVS Access Modules. You must set up a license before you can execute the MVS Access Modules.
The MVS Access Modules supply several 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 on a client workstation or from a remote File-AID/EX Execution Server connected over the network. The MVS Access Modules use TCP/IP communications connections to communicate over the network. The supported z/OS data sources are: VSAM KSDS, VSAM ESDS, QSAM, and GDG.
MVS Access Modules
Execute the MVS Executive as submitted JCL or as a Started Task.
The MVS Access Modules default installation assumes that the MVS Executive is executed as submitted JCL (RUNDCLE). An OMVS segment and a logon ID is required for RUNDCLE.
If the MVS Executive is executed as a started task, for Generation Data sets (GDG) access, this task must have “START” command authority to clone a task. The default clone task name is DCLECL. This name can be changed according to site standards and is documented later within the installation process.
- DCLECL along with FEJCL must reside in a system proclib.
- The cloned task, DCLECL, runs as long as a GDG task is running.
- If the MVS Executive is executed as a started task, a security entry is required for it to kick off DCLECL.
- An OMVS segment and a logon ID is required for DCLECL. If a security entry is not made, an error message may occur.
Configuration Procedures
Task 10.1 Generate Customized Objects
Use the following sample members in hlq.SXVJSAMP and follow the embedded instructions to adjust to your site’s requirements.
- RUNDCLESample JCL to execute the MVS Executive. An OMVS segment and a logon ID is required for RUNDCLE.
- DCLECLSample member for Clone process. The MVS ACCESS modules run in a persistent state. A member should reside in the system PROCLIB (or JCLLIB) that you have specified for this cloned task.
- FEJCLShould be copied to system PROCLIB (or JCLLIB) along with DCLECL to execute the MVS Executive.
Taking Advantage of VSAM Share Options
The MVS Executive attempts to protect the integrity of QSAM and VSAM data sets by checking the system ENQ status before allocating and opening a data set.
Normally, when access to a VSAM data set is requested, the data set will be allocated with DISP=SHR when opening a data set for input. This is indicated in the system with a shared ENQ. And typically a data set will be allocated with DISP=OLD when allocating for output or update which would be indicated in the system with an Exclusive ENQ.
If a data set has an Exclusive ENQ due to another user's DISP=OLD allocation, the Executive will not allocate the data set and will return the message:
Also, if the data set has a Shared ENQ, the Executive will perform an allocation for input; however, the allocation for output or update will be rejected and the above error message will be returned.
The above ENQ processing can be bypassed for VSAM data sets by including the DD statement
into your DCLE JCL stream. This will force all VSAM data set allocations performed by the Executive to be done with DISP=SHR. The file open will be honored depending on the VSAM share options used when the VSAM data set was defined:
SHAREOPTIONS Value | Type of Sharing |
|---|---|
(1,3) | No Sharing, single updater, or multiple readers |
(2,3) | Single updater and multiple readers |
(3,3) | Multiple updaters and multiple readers |
There are two caveats that should be noted:
If another process has an Exclusive ENQ on the VSAM data set, regardless of the share options, the following error message will be returned when the Executive attempts to allocate a VSAM data set:
Dynalloc for <vsam_datasetname> failed with error code=210, info code=0
The Language Environment (LE) limits a single instance of the Executive to a single open for output/update for a VSAM data set. If a second allocate for output/input is attempted, the LE returns the following error message:
EDC50591 An attempt to reposition a VSAM file failed.
Even though the above message is an informational message, the open of the VSAM data set fails.
Operator Commands and Messages
This section describes the commands and messages that are entered while the MVS Access Modules are running.
MVS Access Modules Operator Commands
The operator commands enable subtasks of the MVS Access Modules to be completed in an organized manner. The operator commands are entered by the database administrator at an operator console.
P DCLE and F DCLE,STOP
These commands shut down the MVS Access Modules. If client tasks are active, the MVS Access Modules wait up to 30 seconds for all client tasks to terminate. During this 30-second period new connections are not accepted.
F DCLE,QUIESCE
This command shuts down the MVS Access Modules after all client tasks have ended. While waiting for the client tasks to end new connections are not accepted.
F DCLE,KILL, client task ID
This command terminates a specific client task. The client task ID identifies the client task to be terminated and can be the TCB of the client task, the user ID of the logged on user, or the node ID of the client workstation.
F DCLE,LIST
This command lists all of the active client tasks to the operator console.
MVS Access Modules Operator Messages
The operator messages provide the database administrator with a status or an error regarding the MVS Access Modules. Following are the messages, explanations, system actions, and responses.
Number | Description |
|---|---|
XVJX000I DCLE | Remote Access Manager Version v.r.m Explanation: Displayed when MVS Access Modules are started. v.r.m is current version, release, and modification level. System Action: MVS Access Modules initialize. User Response: None. |
XVJX001I | Ready for communications Explanation: MVS Access Modules have successfully completed and are ready to accept client connections. System Action: MVS Access Modules wait for incoming client connections. User Response: None. |
XVJX003S | MVS environment initialization failed, Reason=rrrrrrr Explanation: An error occurred during initialization. rrrrrrr reason for the failure. System Action: MVS Access Modules terminate. User Response: Validate MVS Access Modules configuration. Restart MVS Access Modules; if error reoccurs, contact File-AID/EX customer support. |
XVJX004S | Unable to ATTACH the message writer Explanation: An error occurred while attaching the message writer subtask. This is probably caused by a system error. System Action: MVS Access Modules terminate. User Response: Correct system error and restart MVS Access Modules. If error reoccurs, contact File-AID/EX customer support. Have system log output and dumps available. |
XVJX005S | Unable to create the message queue Explanation: An internal error has occurred. System Action: MVS Access Modules terminate. User Response: Restart MVS Access Modules. If error reoccurs, contact File-AID/EX customer support. |
XVJX006I | DCLE Remote Access Manager ended Explanation: MVS Access Modules terminated. System Action: MVS Access Modules are removed from the system. User Response: None. |
XVJX007S | DCLE invalid PARM count Explanation: There was an invalid number of parms on the EXEC JCL statement. System Action: MVS Access Modules terminate. User Response: Refer to MVS Access Modules for correct startup parameters. |
XVJX008S | Unable to Open communications to MVS Access Modules operator console Explanation: An internal error occurred while opening communications to the operator console. System Action: MVS Access Modules terminate. User Response: Restart MVS Access Modules. If problem reoccurs, contact File-AID/EX customer support. Have SYSLOG information available. |
XVJX009S | Unable to open TCP/IP Connection: tcp/ip message Explanation: An error occurred when opening the TCP connection. tcp/ip message is a message issued by IBM TCP/IP. System Action: MVS Access Modules terminate. User Response: Refer to IBM manual for problem determination. |
XVJX010E | Invalid Command Explanation: An invalid MVS Access Modules operator command was entered. System Action: The command is ignored. User Response: Correct and reenter the command. |
XVJX011S | TCP Select error: tcp/ip message Explanation: An error occurred during a TCP/IP select function call. tcp/ip message is a message issued by IBM TCP/IP. System Action: MVS Access Modules terminate. User Response: Refer to IBM manual for problem determination. |
XVJX012I | DCLE Remote Access Manager is terminating Explanation: Acknowledgment to either a STOP or QUIESCE entered by operator. System Action: Termination processing begins. User Response: None. |
XVJX013I | DCLE termination complete Explanation: The termination, in response to a STOP or QUIESCE of all client tasks has completed. System Action: None. User Response: None. |
XVJX014I | Terminating with n active clients Explanation: 30 seconds following a STOP command, n client tasks had not terminated. MVS Access Modules terminate with an A03 abend. System Action: Termination processing continues. User Response: None. |
XVJX015I | Quiesce in progress Explanation: A QUIESCE is in progress and a subsequent QUIESCE command was entered. System Action: The subsequent QUIESCE command is ignored. User Response: None. |
XVJX016I | There are currently no active client tasks Explanation: The operator entered a LIST command and there were no active client tasks. System Action: None. User Response: None. |
XVJX017I | TCB User ID Node ID tttttttt uuuuuuuu nnnnnnnnnnnn Explanation: This message appears in response to a LIST command. tttttttt is TCB of client task, uuuuuuuu is user ID of user logged on to client task, and nnnnnnnnnnnn is node ID of client's work station. If a user has not logged on to client task, user ID will contain asterisks. System Action: None. User Response: None. |
XVJX018E | Client task does not exist Explanation: A KILL client task command was entered and the client task ID did not match that of any active client task. System Action: None. User Response: Enter LIST command to get list of active client tasks. Reenter KILL command with correct client task ID. |
What’s Next?
After you have completed the configuration for File-AID/EX Enterprise Edition, start File-AID/EX and verify the product installation. For suggested verification procedures, see File-AID/EX Getting Started Guide .