Using the Explorer GUI

Tabs

The navigation tree on the z/OS tab contains functions (scripts) that can be executed to perform a multitude of functions on MVS systems. Virtually any command or job that can be issued or executed on the host can be defined in a script to be invoked from the GUI command interface. New script files can be added and existing ones modified.

Database tab

The navigation tree on the Database tab contains functions (scripts) that can be executed to perform MySQL database queries against MON-RTM records (DADSM events) written from z/OS host systems.

Favorites

The Favorites folder is simply a way to quickly access the commands and views that are found in the Personal and Shared folders. To create a favorite entry, drag commands or views from the Personal and Shared folders and drop them on Favorites. The shortcuts in Favorites can be rearranged or organized as necessary.

Note: The items in Favorites are shortcut pointers to the real items found in the Personal or Shared folders.

Personal

The Personal folder contains command scripts and related views that are owned and managed by your current Windows login profile (that is, the scripts and views are stored in the Documents and Settings folder belonging to your ID). This allows different Explorer GUI users to share the same computer without modifying each other's work.

Shared

The Shared folder also contains command scripts and related views. However, the commands and views reside on a server, or storage shared by all Explorer GUI users.

Important: The Shared folder will not be displayed until a shared directory is specified using Options > Preferences > Command Tab: Shared Commands Location.

How scripts request data

When a user navigates the menu on the command tab and executes an entry, the related script typically sends a command request to one of two destinations:

a DIF started task running on a mainframe
a MySQL database server

DIF requests - The DIF requests are realtime command requests using the DIF command interface. The DIF started task executes a command request and returns the results to the Explorer GUI. For example, the script for the display active jobs MVS command uses the DIF OPERCMD interface to obtain the information. DIF runs the d a,a operator command in a subsystem console, and then returns the captured command output to the script. The display active jobs script parses the command output and displays the information in a grid format.

Other scripts make heavy use of the DIF MVSFUNC command to provide access to many host-based storage management functions. MVSFUNC also provides an interface to IDCAMS, DFDSS and FDRCOPY, and can run these utilities as subtasks within the DIF address space.

Scripts can also use the DIF DOWNLOAD facility to obtain data from host files generated by Monitor snapshot tasks. The data can be imported into a grid directly from the host file instead of waiting for a real-time Monitor request. Local files can also be saved to a PC or server and accessed by the scripts.

When a script requires more complicated functions, the DIF OSJOB command is usually executed. This DIF command initiates another started task on the host system. Many of the scripts that run OSJOB commands initiate a MONRUNM started task to execute a Monitor request. Since the Monitor is DIF aware, output is normally returned directly (record by record) through the DIF connection to the Explorer GUI.

Scripts that issue DIF OSJOB commands that do not use Monitor usually run the MONRUNP started task. This procedure is used to run third-party software products. Since these applications are not DIF aware, the procedure captures the output from the utility using the IPIO subsystem specified on the SYSPRINT DD statement used in the procedure. To use the IPIO subsystem, the SCCIPIO must be started by DIF. The subsystem interface connects the I/O requests to the DD statement with the Explorer GUI. The Explorer GUI receives the records as they are written to SYSPRINT.

MySQL requests - If the optional three tier Explorer database configuration has been installed, scripts can issue MySQL query requests against the database to perform data analysis and/or examine historical data. The result set from the query is displayed in a grid. For more information about the optional Explorer database tier, examine the sections entitled Install the Explorer Local Database and Install the Explorer History Database (Optional).

Returned data formats

Data is returned to the Explorer GUI as text messages or records. To view the returned raw data consisting of job message output and record schema, enable the Force Log Data option using Options > Preferences > Commands tab.

After enabling the option, when a script displays information, a Log tab will be available in addition to the formatted data in the grid. However, if text messages are returned that cannot be formatted into a grid, only a single main window will be displayed containing the text messages. Raw data records are only returned to the grid and not to the Log tab due to performance considerations; however the raw data records can be viewed on the host in the MONRUNM task SYSPRINT output.

Note: Returned data in either text form or from the Log tab can be copied and pasted by right-clicking in the window to get an edit selection menu. This does not apply to formatted grid data.

Text messages - Text messages are typically free format message text. Many MVS operator command scripts display the console output as text messages. The script also has the option of parsing the text messages and displaying the information in grid format. For example, the Display Active Jobs script parses the output from the d a,a command. Returned text data can be copied and pasted by right-clicking in the output window to get an edit selection menu.

Records - If fixed format records are returned to the Explorer GUI, the script requires a matching record schema to load the returned data into a grid. The schema can be embedded in the returned data, internally defined in the script, or made available to the script in an external file on the PC. Scripts that execute the Monitor to obtain data usually request that the schema be returned with the records by specifying the Monitor RECORDS(SCHEMA) parameter.

Displaying data

The command script determines how the returned data is displayed. On the Active Jobs example below, all three display options are available: Data, Chart and Log.

Data tab

If the command request returns records, the script displays the Data tab in a formatted grid.

Chart tab

After configuring a chart using data from a grid, the user typically creates a chart view. When a chart view is used to request information, the Explorer GUI returns both the grid and chart information with the focus on the Chart tab.

Log tab

Text messages are generally returned in a Log tab, but the script has the option of parsing the messages and building a grid view that is displayed within the Data tab. Occasionally, scripts activate both the Data and Log tabs when displaying data.

The Log tab is generally displayed when the Force Log Data option has been enabled to help debug scripts, provided that there is data to be presented in a grid. For more information about setting the debug option, examine Step 2 - Setting Preferences (Optional).

Data view

Many of the scripts in the Explorer GUI receive records from DIF. The records are used to create a grid or table which is used to display information in a tabular format. The Explorer GUI grids contain many powerful features that allow you to visualize and analyze your data in a variety of ways:

Column sizing

You can change the width of the column in a table in one of several ways. The simplest way is to move the mouse to the right side of the header in the column you wish to size. When the mouse cursor changes to a resize cursor, click and drag the column to the desired width. If you want the Explorer GUI to automatically set the width of a column to the width of the largest item in the column, right-click in the column header and select the Best Fit menu item. To automatically set the width of all columns in the table, right-click on any column header and select Best Fit (all columns).

Column position

To change the position or order of a column in a table, click on the column header and drag horizontally to the left or right. When the double green arrows indicate the correct new position for the column, release the mouse button to drop the column into its new position.

Column alignment

To adjust the horizontal alignment of the information in a column, right-click in the column header and select either Align Left, Align Right, or Align Center from the Alignment submenu.

Sorting data

The order of the data in a table is determined by the table's default order. The default order of the tables in the Explorer GUI varies, but is typically by data set or volume name. To change the order of the data in a table you can specify by which column or columns you want to sort the data.

To select a column as the sort column for a table, click on the column header. The first time you click on a column header a small grey triangle will appear in the header indicating that the table is now sorted by this column in ascending order. Clicking a second time toggles the sort to descending. Subsequent clicks toggle the sort order.

In addition to clicking on the column header, you can sort on a column by right-clicking in the column header and selecting either Sort Ascending or Sort Descending. To clear or 'unsort' a column, click on the column header while holding down the Ctrl key.

You can sort by multiple columns at once by selecting the primary sort column, and then selecting subsequent sort columns while holding the Shift key.

Filtering data

Filtering allows you to view only a specific portion of data in a table. The Explorer GUI provides two ways to filter a table: quick filters and custom filters.

To use a quick filter, click the filter arrow button in the desired column heading and then select a value from the filter menu. After applying the filter, the table contains only rows with items that match the filter value you selected. You can continue to set quick filters on other columns; each column filter is logically combined with the AND operator. Selecting (All) from the filter menu for a column will remove that column filter.

Selecting (Custom) from the filter menu for a column allows you to specify a custom filter. Whenever a filter is defined for a table, a filter bar will appear at the bottom of the table which indicates the value of the current filter. The filter bar also contains a check box to activate/deactivate the filter, a close button to clear all filters, and a Customize... button that opens the Filter Builder form to create, edit, save, and recall advanced custom filters.

Grouping data

In the Explorer GUI you can group the data in a table by the values in a particular column. To group by a column, right-click on the column header and select Group By This Field. If it is not already visible, a group-by box will appear at the top of the table containing the column header of the group column. In the table, each group can be expanded by clicking the + button to show all the rows of that particular group.

You can create multiple groups by selecting additional columns with Group By This Field, or by dragging column headers into the group-by box. If the group-by box is not displayed, right-click on any column header and select Group By Box.

Summarizing columns

Depending on the type of data in the column, you can apply various summarization types to columns. To summarize a column, right-click on any column header and select Footer if the footer is not already displayed. Then, in the footer directly below the column, right-click and select the type of summarization.

Adding/removing columns

To remove a column from a table right-click on the column header and select Remove This Column. To add a column that was previously removed or not displayed, right-click on any column header and select Field Chooser. This displays a Customization dialog listing all column headers that can be added. To add a column, click on the column header in the Customization dialog and drag it to the table header. When the double green arrows indicate the correct position for the column, release the mouse button to drop the column onto the table.

Printing a grid

For most tables in the Explorer GUI there is a Print Preview button in the toolbar above the table. Clicking this button displays the Print Preview window where you can set print settings, preview the output, and send the table to the printer.

Chart view

Charts can be produced from any Explorer GUI command script that creates a grid. Therefore, the Chart tab will always be available to scripts that produce a grid.

A chart is also tied to the grid data. Any filters that are applied to the grid will be immediately reflected in the chart view.

In most cases, the Explorer GUI user manipulates the grid data and then creates a chart view for the customer installation. For more information, see Creating chart views.

Log view

When a script in the Explorer GUI makes a command request to DIF, the resulting data is returned as text messages or records. The command script determines how the data is displayed. Generally, unformatted text messages are displayed as a Log View. If DIF returns records, the script displays the information in a grid format within the Data View.

For example, output from an MVS console command is message text. The Log View is simply a window containing the message output from the command.

The Log View can also be helpful in debugging scripts that receive records and then display the records in a grid format. To view the returned Monitor task messages, control statements, and record schema, enable the Force Log Data option via Options > Preferences > Command tab. After enabling the option, when a script displays grid information, a Log tab will always be available. Returned Log data can be copied and pasted by right-clicking in the Log window to get an edit selection menu.

Creating views

When a command script returns data in a grid format, the grid has a default set of display attributes established by the command script. You can use the grid functions to modify the grid, and then save the grid as a view. A view is linked to the original script and contains all the modifications and filters you made to the original grid.

When you execute a view, the original script linked to the view is executed, and the view attributes are applied before the grid is displayed.

A view is typically used to:

sort, order, or hide columns
apply filters
group data
apply functions to columns

To create a view: After modifying a grid to suit your needs, use the Create View button to save the grid configuration for future requests. The Explorer GUI will create a new entity on the command menu with "(view)" appended to the command name. By default, the new view will be located on the same node in the navigation pane as the command script.

Creating chart views

The Explorer GUI charting facility allows customers to create more than 10 different types of charts including pie, bar, and line charts with multiple data series on the same chart.

Charts can be produced from any command script that creates a grid. The chart facility can use calculated totals by selecting Summary or Function in the Data Source tab.

Step 1 - create a grid for the chart data

Execute a script to produce grid data. The sample chart produced in this section uses the DASD > Pools > Volumes in Pool script to obtain data about the volumes in the DTSPOOL.

Then select the Chart tab.

Step 2 - select chart type

When creating a chart, the Chart tab will start with a blank chart. Click on the Properties menu item to open the Chart Properties dialog.

Select the Series tab beneath the Chart tab and then click on the Add.. button to open the Chart Gallery. Each of the tabs on the chart gallery displays multiple chart types.

Select one of the chart types by clicking on your selection. A small drop-down arrow will appear in the lower left corner of the chart selection. Use the drop-down arrow to select a chart subtype. In this example, the Bar Chart is selected. Double-click on the Normal subtype. Then click on the OK button.

Step 3 - create the data series

After selecting the chart type, the Chart Properties dialog displays the Series tab. The chart icon displays the type of chart for the series, and a colored box indicates the chart color (for example, red).

Double click on the Series1 line item to open the Series properties. Select the Data Source tab, and then select Dataset from the drop-down box. Connect the chart to the grid data by selecting Dataset: GridData. The chart properties will then read the column headings from the grid and make them available to the Labels, X and Bar fields. First, use the Labels drop-down to create the horizontal axis - select the VOLUME label. Now, select the vertical axis variable using the Bar drop-down and select FREE CYL. Then click on the Apply button.

Close the Chart Properties dialog, and the sample chart is displayed:

Step 4 - additional chart tailoring

Double-click on the chart to reopen the properties dialog to continue tailoring the chart.

Change the Series Name - When a data series is added to the chart, the chart facility generates series-n names. Use the Series tab to select the data series, and then click on the Title... button to open the Change Series Title dialog. Enter Free Cylinders, and then click on the OK button to complete the name change.

Add a Title to the Chart - With the Chart tab selected, click on Titles. You can enter two title lines at the top of the chart and two lines at the bottom using the drop-down box. For the example, set the Title Text to Free Cylinders by Volume and the Foot to DTS Volumes. You can also use the properties dialog to change the title format, font, alignment, etc.

Step 5 - create the chart view

Create a Chart View to save the definition. Click on the Create View option to add the new view to the navigation panel. The view will be added near the original query. You can change the name of the View by right-clicking on the new view entry, and selecting Modify. The view properties can be used to change the view name.

You can now recreate the chart by simply clicking on the chart view.

Note: You can add additional Series to the chart but you should use the same horizontal variable, and the vertical values should be similar. For example, if you are charting percentages that range from 1 to 100 and Free Cylinders that could be several thousand cylinders, the percentages will be lost.

Command and SQL query scripts

Script files are also referred to as commands or queries.

Commands are executed to perform a multitude of MVS system host functions including operator commands and dataset utility functions. Virtually any job that can be executed on the host can be defined in a script to be invoked from the Explorer GUI command interface.

Queries are executed to perform SQL queries against the MySQL databases, both local and history.

New script files can be added and existing ones modified. The following topics in this chapter contain general information about executing, modifying and adding scripts. For more detailed information, refer to the The Explorer GUI Scripting Language section.

z/OS and Database tabs

The z/OS and Database tabs contain script files that are logically arranged in folders of various categories.

The folders can be expanded by clicking the plus sign (+) to view the scripts. Double-clicking a script file name will execute the script, and the generated output returned in a window in the content pane will be in the format of a table or free-form log. A single right-click on the script file name will bring up a submenu in which other functions can be performed on the script, for example, Execute Script, Modify, Delete, Execution Mode, Schedule, or Email the script. Right-clicking on the folder name will also bring up submenu choices of New Command, Import Command, New Folder, Expand Folders, Collapse Folders, and Delete Folder.

Add script

To add a new script, right-click on a folder in the Command panel and a submenu will be displayed with the options of New Command, Import Command, New Folder, Expand Folders, Collapse Folders, and Delete Folder.

When New Command is selected a new window will be displayed in the content area of the main window. The command text can be typed directly into the window or text can be copied and pasted from another script and modified by right-clicking in the command window of the existing script to get an edit selection menu. Cloning an existing script is the easiest way to add a new command.

Execute script

Double-clicking a script file name will execute the script, or a single right-click on the script file name will bring up a submenu in which the Execute function can be selected.

When a script executes, the generated output, returned in a window in the content pane, will be in the format of a table, free-form log or both. The Data tab displays the table and the Log tab displays the native command output. A menu of functions can be performed against the generated table data: Export to a file, Print, Filter data, and create an alternate View. Additional scripts can be executed from the output of the primary script by right-clicking on a row in the grid and selecting commands from the displayed submenu.

Also, if a column heading is clicked, the list will be sorted. Each time the column heading is clicked again, the sort order will change from ascending to descending and a small triangle will appear beside the column heading to indicate the current sort direction.

Some scripts prompt for user input prior to execution.

Export

The Export facility saves the generated output from the executed script into a file on a local disk or network drive. The available formats are text, MS Excel, HTML and XML.

Print

The output generated from the executed script can be sent to a printer. The Print Preview enables you to manipulate the appearance of the report prior to printing. Background colors, margins and page layouts can be changed.

The Design option (File > Design...) allows you to further format the report output by adding headers, footers, captions, symbols, titles, etc.

Filter builder

The Filter Builder allows data to be omitted from the script output. Filter properties are applied during script execution. To begin building filter criteria, click on the Filter button in the top-left corner. This displays a submenu with the choices Add Group and Add Condition.

Group filters can be joined with AND/OR/NOT types of conditions.

Condition filters can contain one or multiple conditions where field names contained in the table are compared to values. Note that the values used for comparison are case sensitive.

When the green field name is clicked, a selection list of valid fields to filter on will be displayed in a drop-down box.

When the red operator name is clicked, a selection list of comparison operations will be displayed in a drop-down box.

Once all criteria has been entered into the filter builder, click the Apply button to apply the filter criteria. The filter criteria can be saved in a file by clicking the Save As... button and then reopened at a later execution of the script.

When a script generates a tabular grid, each column heading/field has a blue arrow which when clicked displays a window containing a list of grid values for that column as well as a [Custom...] selection item.

If one or more literal values are selected, then the table will be filtered to contain only rows that equal the selected values.

If (Custom...) is selected from the drop-down list, a new window will be displayed giving the ability to enter filtering criteria for the column, similar to the Filter Builder option. To use wild-card representation, use _ (underscore) to represent any single character and % (percent) to represent any series of characters. Also, any values compared are case sensitive.

View

Scripts that generate tabular output can be modified and alternate views created. For example, columns can be removed from a grid, moved, or resized.

Once the table view has been customized it can be saved for future execution. When the Create View menu item is clicked, the new view is saved in the command list under the Personal folder with the generic name View. To rename the view to something descriptive, right-click the entry and select the Modify option. A window will be displayed with information about the view. The Name section can be changed to a user-defined name and then saved.

Modify script

To modify an existing script, select the script name from the command menu and right-click. Then select Modify from the submenu. A window will be displayed containing the name of the script and a menu of additional options. The script code is displayed in the Script tab, and can be changed and saved, or script code can be copied and pasted by right-clicking in the command window to get an edit selection menu. For more information, refer to The Explorer GUI Scripting Language for a detailed script language explanation.

When working with the script, the Execution Mode can be specified. The script can also be executed during modification or printed.

The Properties tab displays information about the script. The Name field can be changed and Notes can be kept for the script. The Filename displays the location of the .ecd script file. The Associations field pertains to the record type used in script execution when generating context menus. The Modified field will contain a date/time/user/machine stamp if the script has been modified. This prevents the modified script from being overwritten by new releases when performing updates to the Explorer GUI.

Note: It is not recommended to modify the original shipped script. Instead, create a new script with the desired changes. If the original script is modified and you want it replaced during a web update, delete the modified script prior to the update.

Execution mode

The script Execution Mode pertains to where the data is obtained when a script is executed. The data can either be obtained from local files saved on the PC, directly from the host, or using a database query. Note: if the data is obtained using a database query, the execution mode is not applicable for that script.

Real time specifies that whenever a script is executed, the data obtained will always be either a current snapshot from the host, or a dataset download from the most recent snapshot.

System default specifies that whatever is indicated in the Commands Preference will be the execution mode used for the script.

Local data indicates that a file contained on a PC or network drive will be used for the data that is displayed in the window or table output. The first time a script is executed, no local data file will exist, so the real-time data will be obtained and saved in a file for subsequent executions. Although local data is not current, due to performance or response considerations, local data may be desirable instead of real-time data.

If Local Data execution mode is specified, the Local Filename will be displayed in the Execution Mode window under Local File. There are also check boxes for additional options to be applied to the data file (for example, Compress or Append). If the Load and Clear boxes are checked, these options will appear in the submenu displayed when right-clicking a script name in the commands menu. If Clear Local Data is selected, the Local Filename will be deleted. Alternate local filenames can be saved and reloaded.

Local data w/Refresh is the same as local data, except that a user-specified time interval is applied. If the time interval has been exceeded, current data will be reobtained and saved in the local data file. The Execution Mode window contains entries which can be modified to specify the refresh interval time in days and/or hours.

Schedule scripts

The Explorer GUI contains an interface to the Windows Scheduler, and can be used to schedule a script to execute at a requested time and interval. Scripts are often scheduled to execute during off-hours to off-load CPU or I/O intensive requests. The scheduling facility was designed to create local data files or send email alerts. The scheduled command script pre-loads the local data file, and the data will be available when the user wants to access the information using the Explorer GUI. Note: The scheduler facility operates in batch mode and not interactively, meaning that the Explorer GUI application does not have to be active; only the PC must be powered on. Also, no visual data display (table/grid data or messages) can be returned from a scheduled script, only data files.

For example, if a user wants to find the 100 largest data sets on the system, the request must access every volume on the system to build a list containing data set names and the related size. The list is sorted, and the names of the 100 largest datasets are returned to a data file. On very large systems with thousands of volumes, this request may take some time. For most environments, the list probably doesn't change often.

The Largest data sets script can be copied to a new script and modified to create an output file instead of tabular data within a grid, and scheduled to run every Sunday at 3:00 am. For the rest of the week, Explorer GUI users could use the script to display the information in the file by changing the execution mode to use Local Data and specify the file name.

Schedule a script

Command Scripts can be scheduled in two ways — either method opens the Schedule Wizard:

Right-click on a script in the Explorer GUI, and then select Schedule
Open the Schedule Manager (Options > Schedule Mgr) from the Explorer GUI menu. Then drag and drop the script into the Schedule Manager.

Script: The Script field contains the location of the command script that will be executed by the scheduler.

Parameters: The Parameters field can be used to specify the values for variables in the script. These variables are typically used by the script to get information from users using prompt dialogs. Since the script is running in a batch environment, parameters can be specified using the format field=value. If multiple field/value pairs are required, separate the pairs with semicolons (;).

Comments: Enter an optional comment that will be displayed in the Schedule Manager window.

Enter a name for the scheduled task, and select how often the task should run. Click Next to continue.

Enter the start time and which day of the week the task should be run. Select Every 1 weeks if you want the task to run weekly.

Enter the Windows user account information that will be used for the scheduled task. This is usually your Windows logon credentials (not your TSO logon ID).

Click Finish to add the task to the Windows Scheduler. The task can be viewed using Options > Schedule Mgr from the Explorer GUI menu, or using the Scheduled Tasks control panel application (Start > Settings > Control Panel > Scheduled Tasks).

Modify a scheduled script

The scheduled tasks can be viewed using Options > Schedule Mgr from the Explorer GUI menu, or using the Scheduled Tasks control panel application (Start > Settings > Control Panel > Scheduled Tasks).

To modify a scheduled task, select an entry from the Schedule Manager and click on Properties.

Use the Properties dialog to change settings.

Delete a scheduled script

Scheduled tasks can be deleted using Options > Schedule Mgr from the Explorer GUI menu, or using the Scheduled Tasks control panel application (Start > Settings > Control Panel > Scheduled Tasks). To delete a scheduled task using the Schedule Manager, select an entry and click on the Delete menu item.

Drag and drop rules

When dragging from the Favorites folder

Folders and items can only be moved within the Favorites folder.

When dragging from the Personal folder

If the target is the Favorites folder, a shortcut is created in Favorites.
If the target is within the Personal folder, the folder, script or view item is moved.
If the target is within the Shared folder, only folders and scripts can be copied to the Shared folder. Views and the views in a folder cannot be copied to the Shared folder.
If the item being dragged is a view and the target is a script in either the Personal or Shared folder, the view in the Personal folder will be connected to the script.

When dragging from the Shared folder

If the target is the Favorites folder, a shortcut is created in Favorites.
If the target is within the Shared folder, the script or view item is moved.
If the target is within the Personal folder, scripts and views are copied to the Personal folder. If dragging a view, the new view in Personal remains related to the script in the Shared folder.
If the item being dragged is a view and the target is a script in either the Shared or Personal folder, the view in the Shared folder will be connected to the script. Note: A view in the Shared folder cannot be connected to a script in the Personal folder.

Backup/restore scripts and system configuration

It is recommended that a Backup Configuration be done when changes are made to the Explorer GUI interface. Changes to be backed up can include the following:

modified scripts
new scripts added
system or database connections added or modified

From the Explorer GUI application File menu select Backup Configuration.

When a web update is performed to get the latest version of the Explorer GUI software, the configuration is not overwritten, so all changes will remain intact. However, if an uninstall and reinstall is performed, all modifications will be lost. If a Backup Configuration is performed the configuration can be restored either entirely or selectively.