server_pwu (BPX1SPW, BPX4SPW) — Server process work unit

Function

The server_pwu callable service provides a general purpose interface for managing and processing work using the Work Load Manager (WLM). It lets a program put work requests onto the WLM work queues, obtain work from the WLM work queues, transfer work to other WLM work servers, end units of work, delete WLM enclaves, and refresh WLM work servers.

Requirements

Parameters

FcnCode

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains one or more of the following values indicating the function that is requested. The following are the supported values:

SRV_PUT_NEWWRK

A new work request is to be put onto the WLM work queue for the application environment that is identified by the ApplEnv parameter, as part of a newly created WLM enclave. This value cannot be combined with any other FcnCode value.

SRV_PUT_SUBWRK

A new work request is to be put onto the WLM work queue for the application environment that is identified by the ApplEnv parameter, as part of the existing WLM enclave that is associated with the calling thread. This value can be combined only with the SRV_END_WRK FcnCode value.

SRV_TRANSFER_WRK

The work request that is associated with the WLM enclave of the calling thread is to be transferred to the work queue of the target application environment that is identified by the ApplEnv parameter. As part of the transfer, the calling thread is disassociated from its WLM Enclave. This value cannot be combined with any other FcnCode value.

SRV_GET_WRK

A new work request is to be obtained from the WLM work queue for the calling application environment server. The SRV_GET_WRK FcnCode also results in the association of the calling thread with the WLM enlcave that was created when the obtained work request was put onto a WLM work queue. If the calling thread is already associated with a WLM enclave, an implicit SRV_END_WRK is performed. This value can only be combined with the SRV_END_WRK and SRV_DEL_ENC FcnCode values.

SRV_REFRESH_WRK

The servers that are associated with the application environments that are managed by the calling work and queue manager are to be refreshed. This causes all servers to complete existing work requests and then terminate. New servers are then started to process new work.

SRV_END_WRK

The calling thread is to be disassociated from its WLM enclave. This value can only be combined with the SRV_GET_WRK, SRV_PUT_SUBWRK and SRV_DEL_ENC FcnCode values.

SRV_DEL_ENC

The WLM enclave that is associated with the calling thread is to be deleted. This value can only be combined with the SRV_GET_WRK and SRV_END_WRK FcnCode values. This value should not be used to delete an enclave before ending the work units in the enclave, to prevent erroneous workload management results

SRV_DISCONNECT

The calling server's connection to WLM is to be severed. Once a server is disconnected from WLM, it can no longer use this service to process more requests for the application environment for which it had been connected to WLM by a call to the server_init function. If a SRV_DISCONNECT is performed by a work and queue manager, all related server managers implicitly lose their connections to WLM. This means that the related server managers also lose their ability to process more requests via this service.

SRV_DISCONNECT_COND

The calling server's connection to WLM is to be severed only if the caller has no more WLM enclaves that it is still managing. A work and queue manager is still managing an enclave if it has yet to be serviced by a server manager. Once a server is disconnected from WLM, it can no longer use this service to process more requests for the application environment for which it had been connected to WLM by a call to the server_init function. If a SRV_DISCONNECT is performed by a work and queue manager, all related server managers implicitly lose their connection to WLM as well. This means that the related server managers also lose their ability to process more requests via this service.

These constants are defined in the BPXYCONS macro ( BPXYCONS — Constants used by services).

TransClass

Supplied parameter

Type:

Character string

Length:

8 bytes

The name of an 8-byte area that contains the name of the transaction class that is to be associated with the work request. This parameter is only valid when the SRV_PUT_NEWWRK FcnCode parameter value is specified. It is ignored for the other FcnCode parameter values, and ignored if a classification area is supplied. This parameter must be padded with blanks if the name contains fewer than 8 bytes.

ApplEnv

Supplied parameter

Type:

Character string

Length:

32 bytes

The name of a 32-byte area that contains the name of the application environment under which work requests are served. The character string must be padded with blanks, if the name contains fewer than 32 characters. This parameter is valid only when one of the SRV_PUT FcnCode parameter values is specified, or if the SRV_TRANSFER_WRK function code parameter value is specified and is ignored otherwise.

ClassifyAreaLen

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of the classification information area, as specified by the ClassifyAreaPtr parameter. This parameter is valid only with the SRV_PUT_NEWWRK FcnCode parameter value, and is ignored for the other FcnCode parameter values.

ClassifyAreaPtr

Supplied parameter

Type:

Address

Length:

Fullword

The name of a fullword that contains the address of the classification information for the work request in the form of the parameter list for the IWMCLSFY macro. This parameter is intended for use with the SRV_PUT_NEWWRK FcnCode parameter value only. The length of this area is supplied by the ClassifyAreaLen parameter. This parameter is ignored if the ClassifyAreaLen parameter contains a zero value. Some of the classification data that is pointed to by the IWMCLSFY parameter list is truncated if it exceeds the maximum supported length, as follows:

ACCTINFO

143 bytes maximum length

SUBSYSPM

255 bytes maximum length

SOURCELU

17 bytes maximum length

COLLECTION

18 bytes maximum length

CORRELATION

12 bytes maximum length

ApplDataLen

Supplied or returned parameter

Type:

Integer

Length:

Fullword

When one of the SRV_PUT or SRV_TRANSFER FcnCode parameter values is specified, this is a supplied parameter that is the name of a fullword that contains the length of the application data that is specified by the ApplDataPtr parameter.

When the SRV_GET_WRK FcnCode value is specified, this is a returned parameter that is the name of a fullword in which the server_pwu service is to return the length of the application data that is returned in the ApplDataPtr parameter.

This parameter is intended for use when one of the SRV_PUT, SRV_TRANSFER, or SRV_GET FcnCode parameter values is specified. The maximum length that is supported for the application data is 10 megabytes.

ApplDataPtr

Supplied or returned parameter

Type:

Address

Length:

Fullword

When one of the SRV_PUT or SRV_TRANSFER FcnCode parameter values is specified, this is a supplied parameter that is the name of a fullword that contains the address of the application data area that is to be associated with the work request. This application data allows the caller to uniquely identify the specific work that the caller is requesting.

When the SRV_GET_WRK FcnCode value is specified, this is a returned parameter that is the name of a fullword in which the server_pwu service is to return the address of the application data that is associated with the obtained work request. The returned data area is an identical copy of the data area that was supplied on the corresponding server_pwu call to put the work request on a WLM work queue.

This parameter is intended for use when one of the SRV_PUT, SRV_TRANSFER, or SRV_GET FcnCode parameter values is specified.

FdStrucPtr

Supplied or returned parameter

Type:

Address

Length:

Fullword

When one of the SRV_PUT or SRV_TRANSFER FcnCode parameter values is specified, this is a supplied parameter that is the name of a fullword that contains the address of the file descriptor list structure, as mapped by the BPXYSFDL mapping macro. The file descriptors that are specified in the list are to be propagated to the process that calls the server_pwu service to obtain the work request that is created by the call to this service. If the SFDLCLOSE flag is turned on in the SFDLFLAGS field of the supplied structure, all file descriptors in the list are closed in the calling process. If a null address is specified, no file descriptors are propagated.

When the SRV_GET_WRK FcnCode value is specified, this is a returned parameter that is the name of a fullword in which the server_pwu service is to return the address of the file descriptor list structure that is associated with the obtained work request. The returned file descriptor list structure contains a count of entries and a list of file descriptors that represent the list of file descriptors that have been remapped in the calling process for the obtained work request. The remapped file descriptor values correspond to the file descriptor values that were supplied on the server_pwu call to put the work request on a WLM work queue. A file descriptor list is only returned for a SRV_GET_WRK call if the list that was supplied on the corresponding SRV_PUT_WRK, SRV_PUT_SUBWRK or SRV_TRANSFER_WRK call had a file descriptor count of greater than zero.

This parameter is intended for use when one of the SRV_PUT, SRV_TRANSFER, or SRV_GET_WRK FcnCode parameter values is specified. The maximum number of file descriptors that are supported in the file descriptor list is 64.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the server_pwu service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the server_pwu service stores the return code. The server_pwu service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The server_pwu service can return one of the following values in the Return_code parameter:

Return code	Explanation
EAGAIN	The requested service could not be performed at the current time. The following reason code can accompany this return code: JRENCLAVESEXIST
EINVAL	The FcnCode parameter contains a value that is not correct.
EMVSWLMERROR	A WLM service failed. Consult Reason_code to determine the WLM service that failed and the reason the error occurred. See z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO for a list of WLM services (IWM*) error reason codes.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the server_pwu service stores the reason code. The server_pwu service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

1. Usage of the various server_pwu functions requires that the calling address space has successfully issued a call to the server_init service.
2. For the SRV_PUT_NEWWRK and SRV_REFRESH_WRK functions to run successfully, the caller must have successfully issued a call to the server_init service for one of the following ManagerType parameter combinations:
   • SRV_WORK_MGR + SRV_QUEUE_MGR
   • SRV_WORK_MGR + SRV_QUEUE_MGR + SRV_SERVER_MGR
3. For the SRV_PUT_SUBWRK and SRV_TRANSFER_WRK functions to run successfully, the caller must have successfully issued a call to the server_init service for one of the following ManagerType parameter combinations:
   • SRV_WORK_MGR + SRV_QUEUE_MGR + SRV_SERVER_MGR
   • SRV_SERVER_MGR
4. For the SRV_GET_WRK, SRV_END_WRK and SRV_DEL_ENC functions to run successfully, the caller must have successfully issued a call to the server_init service for one of the following ManagerType parameter combinations:
   • SRV_WORK_MGR + SRV_QUEUE_MGR + SRV_SERVER_MGR
   • SRV_SERVER_MGR
5. A successful call to server_pwu for the SRV_PUT_NEWWRK FcnCode not only creates a work request that is placed onto a WLM work queue, but it also creates a new WLM enclave for that work to run in when the work request is obtained. The newly created WLM enclave is classified based on the classification information that is supplied in the input classify area, or based on the input transaction class. Unlike SRV_PUT_NEWWRK, the SRV_PUT_SUBWRK and SRV_TRANSFER_WRK FcnCodes queue work requests that eventually are associated with the WLM enclave of the calling thread when the work request is obtained.
6. A successful call to server_pwu for the SRV_GET_WRK FcnCode not only results in the caller's obtaining a work request from a WLM work queue that is associated with the caller's application environment, but it also results in the associating of the calling thread with the WLM enclave that is associated with the obtained work request. When the calling thread goes through task termination, or when its process is terminated, the work request is ended and the associated WLM enclave is deleted if it is owned by the terminating task or process. The SRV_GET_WRK caller owns the enclave if the work was queued using the SRV_PUT_NEWWRK or SRV_TRANSFER_WRK functions. If the caller is a thread created using pthread_create (pthread), the thread task owns the enclave. If the caller is not a pthread, the process owns the enclave.

   When the FdStrucPtr parameter is used to propagate file descriptors, the caller must ensure that all of the file descriptors in the list are valid open file descriptors in the caller's process and are not being closed during the processing of this service. If this is not the case, this service cannot guarantee the proper propagation of the specified file descriptors.

7. The following demonstrates some sample usage scenarios for the FdStrucPtr parameter:
   • The queue manager process puts work on a work queue for a single–threaded server manager with no open file descriptors. The queued work has a supplied file descriptor structure with 3 file descriptors specified:

     Fds Supplied on SRV_PUT_NEWWRK      Fds returned on SRV_GET_WRK
     ------------------------------      ---------------------------
     0, 1, 2                             0, 1, 2

   • The queue manager process puts work on a work queue for a multithreaded server manager with open file descriptors. The queued work has a supplied file descriptor structure with 3 file descriptors specified:

     Fds Supplied on SRV_PUT_NEWWRK      Fds returned on SRV_GET_WRK
     ------------------------------      ---------------------------
     0, 1, 2                             12, 9, 14

Related services

server_init (BPX1SIN, BPX4SIN) — Server initialization