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.
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1SPW): | 31-bit |
AMODE (BPX4SPW): | 64-bit |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
|
AMODE 64 callers use BPX4SPW with the same parameters.
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.
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.
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.
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.
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.
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.
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 | 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. |
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.
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.
Fds Supplied on SRV_PUT_NEWWRK Fds returned on SRV_GET_WRK
------------------------------ ---------------------------
0, 1, 2 0, 1, 2
Fds Supplied on SRV_PUT_NEWWRK Fds returned on SRV_GET_WRK
------------------------------ ---------------------------
0, 1, 2 12, 9, 14
For an example using this callable service, see BPX1SPW (server_pwu) example.