server_init (BPX1SIN, BPX4SIN) — Server initialization

Function

The server_init callable service allows a server address space to connect to Work Load Manager (WLM) for the purpose of queueing and servicing work requests.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN = HASN
AMODE (BPX1SIN):	31-bit task or SRB mode
AMODE (BPX4SIN):	64-bit task mode only
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.

Format

The syntax format is as follows:

CALL BPX1SIN,(ManagerType,
              SubSystemType,
              SubSystemName,
              ApplEnv,
              ParallelEu,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4SIN with the same parameters.

Parameters

ManagerType

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains one or more of the following values that indicate the type of WLM manager the caller is requesting to become. The following are the supported values:

SRV_WORKMGR: WLM work management services are to be made available to the calling address space. This value can be combined with the SRV_QUEUEMGR and SRV_SERVERMGR values.
SRV_QUEUEMGR: WLM queue management services are to be made available to the calling address space. This value can be combined with the SRV_WORKMGR and SRV_SERVERMGR values.
SRV_SERVERMGR: WLM server management services that are associated with a queue manager are to be made available to the calling address space. This value can be combined with the SRV_QUEUEMGR and SRV_WORKMGR values.

These constants are defined in the BPXYCONS macro; see BPXYCONS — Constants used by services.

SubSystemType

Supplied parameter

Type:: Character string
Length:: 4 bytes

The name of a 4-byte field that contains the generic subsystem type (such as CICS®, IMS™, and WEB). When SRV_WORKMGR is specified for the ManagerType parameter, this is the primary category under which WLM classification rules are grouped. This parameter must be padded with blanks if the name is less than 4 bytes. When SRV_QUEUEMGR is specified for the ManagerType parameter, the combination of the SubSystemType and SubSystemName parameter values must be unique to a single MVS™ system.

SubSystemName

Supplied parameter

Type:: Character string
Length:: 8 bytes

The name of an 8-byte field that contains the subsystem name to be used for classifying work requests when SRV_WORKMGR is specified for the ManagerType parameter. This parameter must be padded with blanks if the name is less than 8 bytes. When SRV_SERVERMGR is specified for the ManagerType parameter, the subsystem name must match the subsystem name that is specified on the corresponding call to server_init for a work manager (ManagerType = SRV_WORKMGR).

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 is less than 32 characters. This parameter is only valid when SRV_SERVERMGR is specified for the ManagerType parameter. It is ignored for all other ManagerType values.

ParallelEu

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the maximum number of tasks within the address space that will be created to process concurrent work requests. This parameter is only valid when SRV_SERVERMGR is specified for the ManagerType parameter. It is ignored for all other ManagerType values.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the server_init 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_init service stores the return code. The server_init 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_init service can return one of the following values in the Return_code parameter:

Return code	Explanation
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.
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.
EPERM	The calling thread's address space is not permitted to the BPX.WLMSERVER profile in the FACILITY class. The caller's address space must be permitted to the BPX.WLMSERVER profile in the FACILITY class. If the BPX.WLMSERVER resource profile is not defined, the calling process is not defined as a superuser (UID=0).
EMVSSAF2ERR	An error occurred in the security product. Consult Reason_code to determine the exact reason the error occurred.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the server_init service stores the reason code. The server_init 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

See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.
A successful call to server_init causes the calling address space to be connected to WLM for the WLM management services requested. Additionally, for a successful server manager connection call (SRV_SERVER_MGR ManagerType), the calling process is made a child of and placed in the session and process group of the corresponding work manager. The corresponding work manager is the process that called server_init for the ManagerType combination SRV_WORK_MGR+SRV_QUEUE_MGR with the same SubSystemType and SubSystemName values that were specified by the server manager process.
This parent child relationship facilitates the use of signals between the server manager and the work manager to communicate with each other. The server manager, for example, after calling this service can issue the getppid service call to obtain the work server's process id, and then send signals to the work server when necessary.

Because the server manager processes are child processes of the work manager/queue manager process, the work manager/queue manager process needs to ensure that terminated server manager processes get cleaned up. This requires the parent to either prevent the children processes from becoming zombie processes by using the sigaction service for the SIGCHLD signal, or clean up any terminated child processes by using the wait service.
This service should be used by a server that is designed to function in one of the following two ways:
The server is divided into multiple address spaces, with a work and queue manager (MANAGER_TYPE=SRV_WORK_MGR+SRV_QUEUE_MGR) address space obtaining work requests from an external source and then queueing the work requests to one or more server manager (MANAGER_TYPE=SRV_SERVER_MGR) address spaces to process the work requests.

A single server address space functions as the work and queue manager and as the server manager (MANAGER_TYPE=SRV_WORK_MGR+SRV_QUEUE_MGR+SRV_SERVER_MGR), with one or more threads obtaining work from an external source and then queueing the work requests to one or more server threads that process the work.

The first method is the recommended approach to using this service, since it takes best advantage of WLM's system workload balancing capabilities by allowing WLM to create and manage the server address spaces against all other work in the system.
The server_init service is a privileged service that requires the caller to be authorized in one of the following ways:
- Have read access to the BPX.WLMSERVER resource profile in the FACILITY class
- Have a UID of 0 when the BPX.WLMSERVER profile is not defined

Related services

server_pwu (BPX1SPW, BPX4SPW) — Server process work unit

Examples

For an example using this callable service, see BPX1SIN (server_init) example.