manageUserExit utility for managing the installed user exit

The GLASYSG and GLAMDBG user exits create system resources that might need to be managed while they are in operation. The manageUserExit utility is a shell script that can be used to manage the system resources. The utility is included in the product samples directory in the hierarchical file system.

The following system resources might need to be managed:

manageUserExit.sh description

This utility manages the data space and program call modules that are controlled by the user exit. For example, you can use the utility to complete the following management actions:
  • Refresh the data space.
  • Refresh the program call modules.
  • Delete the data space, unload the program call modules, and uninstall the user exit from the MVS™ installation exit.
Important: Before you run the manageUserExit.sh utility, stop any instances of the z/OS Log Forwarder that are gathering z/OS SYSLOG data. This action prevents the z/OS Log Forwarder from trying to access or call a system resource that is being deleted. An abend might occur if the z/OS Log Forwarder accesses a non-existent data space or calls a non-existent program call module.

manageUserExit.sh details

Format
manageUserExit.sh -p[d] [environment_configuration_directory]
manageUserExit.sh -d[p] [environment_configuration_directory]
manageUserExit.sh -u [environment_configuration_directory]
Parameters
-d
Refreshes the data space by deleting and re-creating it.

For normal operations, refreshing the data space is not needed. However, for example, if you are requested to refresh the data space by IBM® Software Support, use this parameter to delete and re-create the data space. All z/OS SYSLOG data that is in the data space before deletion is lost.

-p
Refreshes the program call modules by unloading and reloading from the LPA.

Refreshing the program call modules might be necessary when maintenance is applied. Updates to the modules in the SGLALPA library must be reloaded by the user exit. Use this parameter to unload the previously loaded program call modules and load the new program call modules.

Tips:
  1. Before you refresh the program call modules, the modules must be loaded dynamically into the system LPA. If the program call modules are currently in the dynamic LPA, the user exit must be uninstalled, and the old program call modules must be deleted from the dynamic LPA before the new modules can be reloaded. The user exit must then be reinstalled on the MVS installation exit.
  2. If the application of maintenance requires a refresh of the program call modules, the maintenance information specifies that a refresh is necessary.
-u
Deletes the data space, unloads the program call modules, and uninstalls the user exit.
Examples
manageUserExit.sh -pd /etc/IBM/zscala/V2R1
This command refreshes both the data space and program call modules. In this example, the directory /etc/IBM/zscala/V2R1 contains the environment configuration file.
manageUserExit.sh -u
This command uses the ZLF_CONF environment variable to find the directory that contains the environment configuration file. It also deletes the data space, unloads the program call modules, and uninstalls the user exit.
Exit values
0
Successful completion
-1
Did not complete successfully
Messages
The utility issues messages to standard output. The messages have the prefix GLAK.

manageUserExit.sh usage notes

The following information describes some tips for using the manageUserExit.sh utility:
  • To run the manageUserExit.sh utility, you must specify at least one parameter.
  • Specification of the environment configuration directory is optional. However, if this directory is not specified, the ZLF_CONF environment variable must be set, and its value must be the working directory that contains the zlf.conf file that is used by the z/OS Log Forwarder.

    For example, if the zlf.conf file is in /etc/IBM/zscala/V2R1, either the environment configuration directory or the value of the ZLF_CONF environment variable must be this directory.

  • The -p and -d parameters cannot be used with the -u parameter.
  • The utility requests operations by using a system common storage area. The requested operation does not complete until the user exit is called by a system console message. The requested operations are not run synchronously by the utility.
  • The utility can be run even if the user exit is not active or installed. The requested operations are completed when the user exit is activated and is called by a system console message.
  • When the utility completes successfully, it indicates only that it made a request of the user exit. A system console message is issued by the user exit when it performs the requested operations.
Parent topic: User exits for gathering z/OS SYSLOG data