Example of Using the Queueing Manager Services

This section describes how a queueing manager can use the services to:

• Isolate different types of requests into separate server address spaces for integrity, security, and operational reasons.
• Classify work into service classes according to business goals.
• Manage the application execution in the server address space as a continuation of the originating unit of work.
• Specify dynamic management of server address spaces, and other resources to meet the service class goals of the work requests.
• Report service class goals against actual service class performance
• Report response time information.

Figure 17 shows an example of how a queueing manager can use the services. The example shows the services used to achieve the objectives listed above. The services are intended to be used with the enclave services, and must be used independently of the execution delay monitoring services.

Figure 17. Services for a queueing manager

The figure shows a queueing manager address space starting up, connecting to workload management, and queueing work requests to workload management. The server address spaces are created dynamically by workload management as needed. When the server initializes, it connects to workload management, which allows it to select work from the queues. The server address space indicates to workload management when each request starts and ends, so the work request can be properly managed and its performance statistics reported. The following steps describe the flow illustrated in Figure 17.

1. Establish queueing manager

   The queueing manager address space starts up through either a manual start or customer automation. During its initialization, it issues the IWM4CON service with the QUEUE_MANAGER=YES parameter, and provides the subsystem type (SUBSYS parameter), the subsystem name (SUBSYSNM parameter), and, optionally, the node name (NODENM parameter) to identify the type of work associated with the queueing manager. If you need to create an independent enclave, then the queueing manager should also specify WORK_MANAGER=YES (the default) on IWM4CON. If you are creating dependent enclaves, you do not need to specify WORK_MANAGER=YES.

   If the queueing manager needs to take some action when workload management deletes work requests that the queueing manager previously queued, specify a connect exit routine on the QMGR_EXIT@= parameter. Workload management deletes all queue requests when the queue manager disconnects from workload management or the application environment is deleted. This exit gets control when workload management has deleted a work element from its queue. Input to the exit is mapped by the list form of the IWMQCXIT macro. For information about the IWMQCXIT exit, see Using the Queueing Manager Connect Exit. Workload management provides the exit with the information passed to workload management when a work element is queued and an indication that the work element has been removed from the queue.

2. Define dynamic application environment

   Optionally, you can define a dynamic application environment using the IWM4AEDF service. The scope of this newly defined DAE only applies to the queuing manager that invoked this service. For further information, refer to IWM4AEDF macro — WLM Define Dynamic Application Environments.

3. Create enclave

   The queueing manager receives a work request and must use an enclave to manage it. Depending on the environment, the queueing manager can use an existing enclave or create a new enclave, either dependent or independent, using the IWM4ECRE service.

   If running under the requestor's dispatchable unit, IWMESQRY can be used to determine whether the requestor belongs to an enclave and if so, which enclave. If running under a different dispatchable unit, it is the subsystem's responsibility to pass information on any existing enclave along with the work request. For example, the subsystem could pass information it obtained from IWMESQRY while running under the requestor's dispatchable unit.

   If the requestor does not belong to an enclave but has an address space transaction (for example, it is a TSO user or a batch job), the queueing manager can create a dependent enclave to represent a continuation of the requestor's transaction. This requires that the requestor be the home address space.

   If there is no existing enclave or address space transaction, such as when the requestor is on another system, the queueing manager must create an independent enclave to begin a new transaction. This requires the queueing manager to classify the work request.

4. Queue request

   The queueing manager uses the IWM4QIN service to add the work request to a workload management queue. The application environment, enclave token, and optional user ID for resource access control are provided as input to workload management. The service class is determined from the enclave token, and the request is added to a queue associated with that service class within the specified application environment. You can optionally pass information to the server address space when it selects this work request. Workload management does not read or modify this data in any way.

   Workload management stages work requests between the queueing manager address space and the server(s), but the queueing manager is still responsible for managing the flow of work requests and handling timeout and abnormal conditions where servers are failing to properly process requests. Workload management detects and reacts to certain error conditions such as JCL errors in the procedure used to start the server and repeated, unexpected terminations of the server address space. For more information, see “Defining Application Environments” in z/OS MVS Planning: Workload Management.

   If the queueing manager needs to remove a work request that it previously queued through the IWM4QIN service before it has been processed by the server, it uses the IWM4QDE service. This service is provided for exceptional circumstances, such as:

   • Timeout of the work request
   • An external request to cancel a queued request
   • Queueing manager recovery.

   A queueing manager must not insert requests for a dynamic and static application environment with the same application environment name concurrently.

5. Establish server address space

   When the first request is queued to an application environment, workload management detects that there are no active servers for the request, and automatically starts one. The MVS™ procedure name and start parameters are taken from the application environment definition in the service definition. As the workload fluctuates, workload management adjusts the number of server address spaces so the goals of the work are met.

   When the server initializes, it must establish itself as a server address space using the IWM4CON service with SERVER_MANAGER=YES parameter, and indicate which application environment it is servicing. The subsystem type and name specified on the server connect must match the values specified on the associated queueing manager connect.

   Workload management creates as many server address spaces as are needed to meet the goals of the work running in the servers, unless the application has limited the number of server instances that workload management can create using IWM4SLI.

   Immediately after invoking IWM4CON, you have the option of using IWM4SLI to control the number of server instances that WLM will create. Use the AE_SERVERMAX parameter to establish a maximum number — this is particularly useful for applications such as MQSeries® Workflow that connect to backend applications supporting a limited number of parallel connections. Use the AE_SERVERMIN parameter to establish a minimum number — this allows an application to keep a number of servers active, even during low utilization periods. In addition, you can specify AE_SPREADMIN=YES to ensure that the defined minimum number of servers are distributed evenly across all of the service classes used to execute work requests in the application environment.

   There will be at least as many servers for an application environment as there are unique service classes associated with the work requests, even if the workload is low. This is so workload management can separately manage work with different service class goals.

   Applications can optionally give workload management the control about the number of server instances per server address space.Directly after IWM4CON, you can use IWMSINF to obtain recommendations from workload management about the number of server instances to be started. WLM will pass the number of instances to be started in addition to the already running server instances to the server address space. The caller must have previously connected to WLM using the IWM4CON service specifying SERVER_MANAGER=YES, SERVER_TYPE=QUEUE, and MANAGER_TASKS=YES. See Managing the Number of Server Instances per Server Address Space for a more detailed explanation on using IWMSINF.

   Because the workload management services used by server address spaces are available to problem programs, a SAF call is made as part of the connection process to allow the installation to protect against malicious use or damage due to incorrect startup definitions. This SAF check permits the server address space to be totally unauthorized (no APF authorization required). The RACF-supported resource for this call is of the class SERVER and has the name:

      sstype.subsys.applenv[.nodenm]

   where:

   • sstype is the subsystem type
   • subsys is the subsystem name of the queueing manager address space
   • applenv is the name of the application environment being serviced
   • nodenm is an optional qualifier of the queuing manager

   Workload management picks up these values from the IWM4CON parameters, SUBSYS=, SUBSYSNM=, APPLENV=, and NODENM respectively. For more information, see “Workload Management Migration” in z/OS MVS Planning: Workload Management.

6. Process work request

   The server uses the IWM4SSL service to remove a work request from the queue associated with its application environment and service class. If no requests are queued, workload management suspends the task issuing the IWM4SSL until work is available. After a request is selected, the server uses the IWM4STBG service to indicate the processing of the request is beginning. At this point the task joins the enclave identified when the work was queued through IWM4QIN. When the server is finished processing the request, it uses the IWM4STEN service to cause the task to leave the enclave.

   Almost all of the processing in a server address space should be on behalf of a work request and occur between the IWM4STBG and IWM4STEN calls. A server address space should not have other tasks performing unrelated processing as this could interfere with effectively managing the enclave to its goals.

   If the queueing manager provided a user ID on the IWM4QIN service, IWM4STBG sets up a SAF environment for the work request to control access to resources.

   Alternative task structures:

   This example shows a single task issuing the IWM4SSL, IWM4STBG, and IWM4STEN services: one task within the server address space selects work from the queue, processes the request, then loops back to select more work. Queueing manager services does not impose any rules limiting the ways a server can organize its tasks. The following task structures are also possible:

   • Multiple tasks with single thread execution.

     One task selects work from the queue, selects a “worker” subtask to process the request, posts the worker task, and then waits to be posted by the worker task when the processing of the request is complete.

   • Multiple tasks with parallel work selection and execution.

     There is a set of “worker” subtasks within the server address space, each of whom selects work from the queue, processes the request, and loops back to obtain a new request.

   At the time the server connects to workload management (IWM4CON), the server must specify how many tasks will execute work in parallel (PARALLEL_EU).

7. Delete enclave

   The server address space informs the queueing manager using its own interface that a work request is complete. If the queueing manager had previously created an enclave for the work request, it determines if there are other work requests active for the same enclave. If there are none, the queueing manager deletes the enclave and returns to the originator of the request.

8. Terminate server address space

   Under normal circumstances, it is expected that a server address space will continue to select work until told by workload management that the space is no longer needed through a return and reason code (x'0C14') on the IWM4SSL service. The server is then expected to complete any work requests already selected, clean up, disconnect from workload management through the IWM4DIS service, and terminate. Possible reasons for this IWM4SSL return code are:

   • The operator entered one of the following commands for the application environment:
     • VARY WLM,APPLENV=,QUIESCE
     • VARY WLM, DYNAPPL=,QUIESCE or
     • VARY WLM,APPLENV=,REFRESH
     • VARY WLM,DYNAPPL=,REFRESH
   • A policy was activated from a new service definition which no longer includes the application environment associated with the server.
   • WLM determines that the server is not needed to meet the goals of the enclave's service class.

   The server should make reasonable recovery attempts when errors occur. If the server encounters a failure that forces it to terminate, it should disconnect from workload management as part of its shutdown. If the server address space terminates without explicitly disconnecting from workload management, workload management detects the termination and performs the IWM4DIS processing at that time. If workload management detects five unexpected server disconnects or address space terminations within ten minutes, it will put the application environment into a STOPPED state. This means that no new servers are created for the application environment until the VARY WLM,APPLENV=,RESUME or VARY WLM, DYNAPPL=RESUME command is issued for it. Existing server address spaces continue to run work while the application environment is in the STOPPED state, as long as they are operating normally.

9. Terminate queueing manager address space

   When the queueing manager terminates normally, it is expected to quiesce its activities, drain its queues of pending work, and disconnect from workload management using the IWM4DIS service. If the queueing manager address space terminates without first disconnecting from workload management, workload management detects the termination and performs the IWM4DIS processing at that time.

   Workload management returns control immediately to the caller of IWM4DIS, and asynchronously performs server clean up. It purges all queued, but unselected, requests and attempts to terminate all associated server address spaces. Because workload management depends on server address spaces to terminate voluntarily when requested, and because workload management must wait for a server to request work prior to telling it to terminate, server address spaces could remain for a significant amount of time after the queueing manager terminates.