Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
| z/OS® UNIX |
both |
|
Format
#include <sys/server.h>
int __server_pwu(int fcncode, const char *transclass,
const char *applenv, server_classify_t classify,
int *appldatalen, void **appldata,
struct __srv_fd_list **fdlstruc);
General description
The __server_pwu() function provides a general purpose interface
for managing and processing work using WorkLoad Manager (WLM) services.
The capabilities this service provides include the ability to 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.
The parameters supported are:
- fcncode
- Contains one or more of the following values that indicate the
function that is requested:
- SRV_PUT_NEWWRK
- Indicates that a new work request be put onto the work queue
for an application environment server 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
- Indicates that a new work request be put onto the work queue
for an application environment server identified by the applenv parameter
as part of the WLM enclave associated with the calling thread. This
value can be combined with the SRV_END_WRK fcncode value.
- SRV_TRANSFER_WRK
- Indicates that the last work request obtained by the calling
thread be transferred to the work queue of the target application
environment server. 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
- Indicates that a new work request be obtained from the WLM work
queue for the calling application environment server. The SRV_GET_WRK fcncode also
results in the calling thread being associated with the WLM enclave
of the work request. If the calling thread is already associated
with a WLM enclave due to a prior call to __server_pwu() for SRV_GET_WRK,
it is disassociated from the prior WLM enclave, as well as associated
with the obtained work request. When the calling thread goes thru
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. This value can be combined
with the SRV_END_WRK and SRV_DEL_ENC fcncode values.
- SRV_REFRESH_WRK
- Indicates that the servers associated with the application environments
managed by the calling work and queue manager are to be refreshed.
This will cause all servers to complete existing work requests and
then terminate. New servers will then be started to process new work.
This value cannot be combined with any other fcncode value.
- SRV_END_WRK
- Indicates that the calling thread is to be disassociated from
its WLM enclave. This value can be combined with the SRV_DEL_ENC,
SRV_PUT_SUBWRK and SRV_GET_WRK fcncode values.
- SRV_DEL_ENC
- Indicates that the WLM enclave associated with the calling thread
is to be deleted. This value can be combined with the SRV_GET_WRK
and SRV_END_WRK fcncode values.
- SRV_DISCONNECT
- Indicates that 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
it had been connected to (using 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. This
also results in the related server managers losing their ability to
process more requests using this service.
- SRV_DISCONNECT_COND
- Indicates that 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 it had been connected
to (using a call to the server_init() function). If a SRV_DISCONNECT_COND
is performed by a work and queue manager, all related server managers
implicitly lose their connection to WLM. This also results in the
related server managers losing their ability to process more requests
using this service.
- *transclass
- Points to a NULL-terminated character string that represents
the name of the transaction class to be associated with the work request.
This parameter is only valid when the SRV_PUT_NEWWRK fcncode parameter
value is specified. It should be NULL for the other fcncode parameter
values. The character string can be up to 8 bytes in length.
- *applenv
- Points to a NULL-terminated character string that contains the
name of the application environment under which work requests are
served. This parameter is valid for the set of SRV_PUT fcncode values,
the SRV_TRANSFER_WRK fcncode value and the SRV_REFRESH_WRK fcncode value.
It should be NULL for the other fcncode parameter values.
The character string can be up to 32 bytes in length.
- *classify
- Points to a character string that contains the classification
information for the work request macro.
- *appldatalen
- When one of the SRV_PUT or SRV_TRANSFER fcncode parameter
values is specified this is a supplied parameter that points to an
integer containing the length of the application data specified by
the **appldata parameter. When the SRV_GET_WRK fcncode value
is specified, this is an output parameter where the __server_pwu()
function is to return the length of the application data associated
with the obtained work request. *appldatalen is only valid
when one of the SRV_PUT, SRV_GET_WRK or SRV_TRANSFER fcncode parameter
values is specified, it is ignored otherwise. The maximum length
supported for the application data is 10 megabytes.
- **appldata
- When one of the SRV_PUT or SRV_TRANSFER fcncode parameter
values is specified this is a supplied parameter that points to the
application data string. This application data allows the caller
to uniquely identify the specific work the caller is requesting.
When the SRV_GET_WRK fcncode value is specified, this is
an output parameter where the __server_pwu() function is to return
a pointer to the application data associated with the obtained work
request. The returned data area will be 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. **appldata is
only valid when one of the SRV_PUT, SRV_GET_WRK or SRV_TRANSER fcncode parameter
values is specified, it is ignored otherwise.
- **fdlstruct
- When one of the SRV_PUT or SRV_TRANSFER fcncode parameter
values is specified the **fdlstruc parameter is an input
parameter that contains a pointer to a __srv_fd_list structure. The
__srv_fd_list structure contains the following members:
int fdcount count of file descriptiors
int flags flag SRV_FDCLOSE
int fd(SRV_FDS) file descriptor list
The supplied
__srv_fd_list structure contains the count of file descriptors to
be propagated, followed by the list of file descriptors that are to
be propagated to the process that calls server_pwu() to obtain the
work request created by the call to this service. If the SRV_FDCLOSE
flag is turned on in the flags field of the __srv_fd_list structure,
all file descriptors in the list are closed in the calling process.
If a NULL pointer is specified, no file descriptors are propagated.
When the **fdlstruc 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, then this function cannot guarantee the proper
propagation of the specified file descriptors. When the SRV_GET_WRK fcncode parameter
value is specified the **fdlstruc parameter is an output
parameter where the __server_pwu() function returns a pointer to the
__srv_fd_list structure associated with the obtained work request.
The returned __srv_fd_list structure will contain the count of file
descriptors in the returned structure, followed by the list of remapped
file descriptor values in the calling process of the file descriptors
that were supplied in the __srv_fd_list structure on the corresponding
__server_pwu() call to put the work request on a WLM work queue.
The flags field in the returned __srv_fd_list structure will be NULL.
The **fdlstruc parameter is only valid when one of the SRV_PUT,
SRV_TRANSFER or SRV_GET_WRK fcncode parameter values are
specified. It is ignored otherwise. The maximum number of file descriptors
supported in the file descriptor list structure is 64.
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. By comparison, the SRV_PUT_SUBWRK and
SRV_TRANSFER_WRK fcncodes, queue work requests that are part
of the existing WLM enclave of the calling thread.
A successful call to __server_pwu() for the SRV_GET_WRK fcncode not
only results in the caller obtaining a work request from a WLM work
queue associated with the caller's application environment, but also
results in the calling thread being associated with the WLM enclave
associated with the obtained work request.
Usage of the server_pwu function requires the calling address space
to have successfully issued a call to the __server_init() function.
For the SRV_PUT_NEWWRK function 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_WORKMGR + SRV_QUEUEMGR
- SRV_WORKMGR + SRV_QUEUEMGR + SRV_SERVERMGR
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_WORKMGR + SRV_QUEUEMGR SRV_SERVERMGR
- SRV_SERVERMGR
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_WORKMGR + SRV_QUEUEMGR SRV_SERVERMGR
- SRV_SERVERMGR
For the SRV_REFRESH_WRK function to run successfully, the caller
must have successfully issued a call to the __server_init() service
for any of the following
managertype parameter combinations:
- SRV_WORK_MGR + SRV_QUEUE_MGR
- SRV_WORK_MGR + SRV_QUEUE_MGR + SRV_SERVER_MGR
Returned value
If successful, __server_pwu() returns 0.
If unsuccessful, __server_pwu() returns -1 and sets errno to one
of the following values:
- Error Code
- Description
- EAGAIN
- The requested service could not be performed at the current
time. Use __errno2() to obtain the reason code for the failure.
- EFAULT
- An argument of this service contained an address that was not
accessible to the caller.
- EINVAL
- The managertype parameter contains a value that is
not correct.
- EMVSERR
- A MVS™ environmental or
internal error has occurred. Use __errno2() to obtain the exact reason
for the failure.
- EMVSWLMERROR
- A WLM service failed. Use __errno2() to obtain the WLM service
reason code for the failure.