WLM_REFRESH stored procedure

The WLM_REFRESH stored procedure refreshes a WLM environment. This stored procedure can recycle the environment in which it runs and in any other WLM environment.

Environment for WLM_REFRESH

The load module for WLM_REFRESH, DSNTWR, must reside in an APF-authorized library.

DSNTWR runs module DSNTWRE as a subtask. DSNTWRE retrieves a copy of the Db2 environment information block (EIB) for the Db2 subsystem. The DSNTWRE module has no APF-authorization requirement, but it must reside in an APF-authorized library to be available to DSNTWR.

Recommendation: Use WLM environment DSNWLM_GENERAL for running WLM_REFRESH. Installation job DSNTIJMV creates an address space procedure called DSNWLMG for this environment.

Authorization required for WLM_REFRESH

To execute the CALL statement, the SQL authorization ID of the process must have READ access or higher to the z/OS® Security Server System Authorization Facility (SAF) resource profile ssid.WLM_REFRESH.WLM-environment-name in resource class DSNR. This is a different resource profile from the ssid.WLMENV.WLM-environment-name resource profile, which Db2 uses to determine whether a stored procedure or user-defined function is authorized to run in the specified WLM environment.

WLM_REFRESH uses an extended MCS console to monitor the operating system response to a WLM environment refresh request. The privilege to create an extended MCS console is controlled by the resource profile MVS.MCSOPER.* in the OPERCMDS class. If the MVS.MCSOPER.* profile exists, or if the specific profile MVS.MCSOPER.DSNTWR exists, the task ID that is associated with the WLM environment in which WLM_REFRESH runs must have READ access to it.

If the MVS.VARY.* profile exists, or if the specific profile MVS.VARY.WLM exists, the task ID that is associated with the WLM environment in which WLM_REFRESH runs must have CONTROL access to it.

WLM_REFRESH syntax diagram

The WLM_REFRESH stored procedure refreshes a WLM environment. WLM_REFRESH can recycle the environment in which it runs, as well as any other WLM environment.

The following syntax diagram shows the SQL CALL statement for invoking WLM_REFRESH. The linkage convention for WLM_REFRESH is GENERAL WITH NULLS.

WLM_REFRESH option descriptions

WLM-environment

Specifies the name of the WLM environment that you want to refresh. This is an input parameter of type VARCHAR(32).

ssid

Specifies the subsystem ID of the Db2 subsystem with which the WLM environment is associated. If this parameter is NULL or blank, Db2 uses one of the following values for this parameter:

In a non-data sharing environment, Db2 uses the subsystem ID of the subsystem on which WLM_REFRESH runs.
In a data sharing environment, Db2 uses the group attach name for the data sharing group in which WLM_REFRESH runs.

This is an input parameter of type VARCHAR(4).

status-message

Contains an informational message about the execution of the WLM refresh. This is an output parameter of type VARCHAR(120).

return-code

Contains the return code from the WLM_REFRESH call, which is one of the following values:

0

WLM_REFRESH executed successfully.

4

One of the following conditions exists:

The SAF resource profile ssid.WLM_REFRESH.wlm-environment is not defined in resource class DSNR.
The SQL authorization ID of the process (CURRENT SQLID) is not defined to SAF.
The wait time to obtain a response from z/OS was exceeded.

8

The SQL authorization ID of the process (CURRENT SQLID) is not authorized to refresh the WLM environment.

990

DSNTWR received an unexpected SQLCODE while determining the current SQLID.

993

One of the following conditions exists:

The WLM-environment parameter value is null, blank, or contains invalid characters.
The ssid value contains invalid characters.

994

The extended MCS console was not activated within the number of seconds indicated by message DSNT5461.

995

DSNTWR is not running as an authorized program.

996

DSNTWR could not activate an extended MCS console. See message DSNT533I for more information.

997

DSNTWR made an unsuccessful request for a message from its extended MCS console. See message DSNT533I for more information.

998

The extended MCS console for DSNTWR posted an alert. See message DSNT534I for more information.

999

The operating system denied an authorized WLM_REFRESH request. See message DSNT545I for more information.

return-code is an output parameter of type INTEGER.

Example of WLM_REFRESH invocation

Suppose that you want to refresh WLM environment WLMENV1, which is associated with a Db2 subsystem with ID DSN. Assume that you already have READ access to the DSN.WLM_REFRESH.WLMENV1 SAF profile. The CALL statement for WLM_REFRESH looks like this:

strcpy(WLMENV,"WLMENV1");
strcpy(SSID,"DSN");      
EXEC SQL CALL SYSPROC.WLM_REFRESH(:WLMENV, :SSID, :MSGTEXT, :RC);

For a complete example of setting up access to an SAF profile and calling WLM_REFRESH, see job DSNTEJ6W, which is in data set prefix.SDSNSAMP.