__wlm (BPX1WLM, BPX4WLM) — WLM interface service

Function

The __wlm callable service invokes a wide variety of Workload Manager (WLM) functions. You can also use it to invoke Enterprise Workload Manager™ (eWLM) ARM (Application Response Measurement) functions.

For information about the ARM functions, see IBM® Tivoli® eWorkload Management Version 1.

Requirements

Parameters

FunctionCode

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains a value that indicates the type of WLM or eWLM function that the caller is requesting. The following are the supported values:

Value	Description
WLM_QUERY_METRICS	Query WLM System Information
WLM_QUERY_SCHEDENV	Query WLM Scheduling Environment
WLM_CHECK_SCHEDENV	Check WLM Scheduling Environment
WLM_DISCONNECT	Disconnect from WLM
WLM_DELETE_WORKUNIT	Delete a WLM Work Unit
WLM_JOIN_WORKUNIT	Join a WLM Work Unit
WLM_LEAVE_WORKUNIT	Leave a WLM Work Unit
WLM_CONNECT_WORKMGR	Connect to WLM as a work manager
WLM_CONNECT_SERVERMGR	Connect to WLM as a server manager
WLM_CREATE_WORKUNIT	Create a WLM work unit (this function creates an independent WLM enclave)
WLM_CONTINUE_WORKUNIT	Continue WLM work unit (this function creates a dependent WLM enclave)
WLM_EXTRACT_WORKUNIT	Extract the WLM work unit token (this function returns the WLM enclave token)
WLM_EXPORT_WORKUNIT	Export a WLM work unit
WLM_UNDOEXPORT_WORKUNIT	Undo a prior export request for a WLM work unit
WLM_IMPORT_WORKUNIT	Import a WLM work unit
WLM_UNDOIMPORT_WORKUNIT	Undo a prior import request for a WLM work unit
WLM_QUERY_ENCLAVECLASS	Query enclave class information for a WLM work unit
WLM_CONNECT_EXPORTIMPORT	Connect a subsystem to WLM to export and import work units, but not to create them
ARM_BIND_THREAD	Indicates that the calling thread is performing on behalf of an ARM transaction
ARM_BLOCK_TRANSACTION	Indicates that a started transaction is blocked waiting for an external transaction or some other event to complete
ARM_DESTROY_APPLICATION	Indicates that the registration data about an application is no longer needed
ARM_DISCARD_TRANSACTION	Signals that a started ARM transaction should be ignored
ARM_GENERATE_CORRELATOR	Generates an ARM correlator for use with ARM_REPORT_TRANSACTION
ARM_GET_ARRIVAL_TIME	Stores a 64-bit integer representing the current time
ARM_REGISTER_APPLICATION	Informs ARM of metadata about the application
ARM_REGISTER_METRIC	Informs ARM of metadata about each metric the application provides
ARM_REGISTER_TRANSACTION	Informs ARM of metadata about the transaction measured by the application
ARM_REPORT_TRANSACTION	Reports statistics about a transaction that has already completed
ARM_START_APPLICATION	Indicates that an instance of an application has started running and is prepared to make ARM calls
ARM_START_TRANSACTION	Indicates that a transaction is beginning execution
ARM_STOP_APPLICATION	Indicates that the application instance is finished making ARM calls
ARM_STOP_TRANSACTION	Signals the end of a transaction
ARM_UNBIND_THREAD	Indicates that the calling thread is no longer performing on behalf of an ARM transaction
ARM_UNBLOCK_TRANSACTION	Indicates that a transaction is no longer waiting for a downstream transaction to complete
ARM_UPDATE_TRANSACTION	Signals that a transaction is still processing
EWLM_CLASSIFY_CORRELATOR	Creates an eWLM specific ARM correlator for classification purpose

These constants are defined in the BPXYWLM macro; see BPXYWLM — WLM constants and parameter list DSECTs.

For detailed information about the ARM function codes, see IBM Tivoli eWorkload Management Version 1.

ParmListPtr

Supplied parameter

Type:

Address

Length:

Fullword (doubleword)

The name of a fullword (doubleword) field that contains the address of the parameter list for the WLM function that is to be performed. See BPXYWLM — WLM constants and parameter list DSECTs for the mapping of the parameter lists for the various WLM functions.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the __wlm service returns the return value for the WLM function that was requested.

For the following set of WLM functions, the service returns 0 if the request is successful, or -1 if it is not successful:

• WLM_CHECK_SCHEDENV
• WLM_DISCONNECT
• WLM_DELETE_WORKUNIT
• WLM_JOIN_WORKUNIT
• WLM_LEAVE_WORKUNIT
• WLM_CREATE_WORKUNIT
• WLM_CONTINUE_WORKUNIT
• WLM_QUERY_METRICS
• WLM_QUERY_SCHEDENV
• WLM_EXTRACT_WORKUNIT
• WLM_EXPORT_WORKUNIT
• WLM_UNDOEXPORT_WORKUNIT
• WLM_IMPORT_WORKUNIT
• WLM_UNDOIMPORT_WORKUNIT
• WLM_QUERY_ENCLAVECLASS
• ARM_BIND_THREAD
• ARM_BLOCK_TRANSACTION
• ARM_DESTROY_APPLICATION
• ARM_DISCARD_TRANSACTION
• ARM_GENERATE_CORRELATOR
• ARM_GET_ARRIVAL_TIME
• ARM_REGISTER_APPLICATION
• ARM_REGISTER_METRIC
• ARM_REGISTER_TRANSACTION
• ARM_REPORT_TRANSACTION
• ARM_START_APPLICATION
• ARM_START_TRANSACTION
• ARM_STOP_APPLICATION
• ARM_STOP_TRANSACTION
• ARM_UNBIND_THREAD
• ARM_UNBLOCK_TRANSACTION
• ARM_UPDATE_TRANSACTION
• EWLM_CLASSIFY_CORRELATOR

If the WLM_QUERY_METRICS, WLM_QUERY_SCHEDENV, or WLM_QUERY_ENCLAVECLASS function fails with an error that indicates that the supplied buffer was too small, the supplied length field in the input parameter list is updated to contain the length that is required for the function to succeed.

For the following set of WLM functions, the service returns a WLM connect token if the request is successful, or -1 if it is not successful:

• WLM_CONNECT_WORKMGR
• WLM_CONNECT_SERVERMGR
• WLM_CONNECT_EXPORTIMPORT

Return_Code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the __wlm service stores the return code. The __wlm 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 __wlm 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 FunctionCode parameter contains a value that is not correct; or the function parameter list data is not correct.
EMVSWLMERROR	A WLM service failed. Consult Reason_code to determine the WLM service that failed and the reason for the error. See z/OS MVS System Messages, Vol 9 (IGF-IWM) for a list of WLM services (IWM*) error reason codes.
EMVSARMERROR	An ARM error occurred. Consult Reason_code to determine the reason for the error. The ARM reason codes are documented in the _Elmarm4.h header file.
EPERM	The calling thread's address space is not permitted to the BPX.WLMSERVER FACILITY class profile. The caller's address space must be permitted to the BPX.WLMSERVER FACILITY class profile. If BPX.WLMSERVER is not defined, the calling process is not defined as a superuser (UID=0).
EMVSSAF2ERR	An error occurred in the security product.
ESRCH	A WLM_EXTRACT_WORKUNIT request was issued, but the WLM enclave token was not returned. Consult Reason_code to determine the exact reason it was not returned. Most likely, the unit of work is not in an enclave.
EMVSERR	Recovery processing was entered for a reason other than EFAULT.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

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

ARM reason codes are documented in the _Elmarm4.h header file.

Usage notes

1. The WLM_CONNECT_WORKMGR and WLM_CONNECT_EXPORTIMPORT functions both enable use of the export and import functions, but only the former enables use of the create function.
2. For a WLM_CREATE_WORKUNIT function invocation, some of the classification data that is pointed to by the supplied IWMCLSFY parameter list is truncated if it exceeds the maximum supported length, as follows:

   Data	Maximum length
   ACCTINFO	143 bytes
   SUBSYSPM	255 bytes
   SOURCELU	17 bytes
   COLLECTION	18 bytes
   CORRELATION	12 bytes

Related services

None.

Characteristics and restrictions

1. Certain __wlm functions require that the caller have read access to the BPX.WLMSERVER FACILITY class profile, or a UID of 0 if the BPX.WLMSERVER FACILITY class profile is not defined. The following table shows the authorization required for each __wlm function:

   Table 1. Authorization requirements for __wlm functions

   Function	Authorization
   WLM_QUERY_METRICS WLM_CONNECT_SERVERMGR WLM_EXTRACT WORKUNIT	No authorization required
   WLM_CONNECT_EXPORTIMPORT	If the caller has not already made a WLM_CONNECT_EXPORTIMPORT call, read access to the BPX.WLMSERVER FACILITY or UID 0 are not required
   WLM_DELETE_WORKUNIT	If the caller has made a WLM_CONNECT_EXPORTIMPORT call, special authorization is not required.
   WLM_QUERY_SCHEDENV WLM_CHECK_SCHEDENV WLM_DISCONNECT WLM_JOIN_WORKUNIT WLM_LEAVE_WORKUNIT WLM_CONNECT_WORKMGR WLM_CREATE WORKUNIT WLM_IMPORT_WORKUNIT WLM_QUERY_ENCLAVECLASS WLM_UNDOIMPORT_WORKUNIT	Read access to the BPX.WLMSERVER FACILITY class profile, or a UID of 0 if the BPX.WLMSERVER FACILITY class profile is not defined.
   WLM_CONTINUE WORKUNIT	A process can have one dependent enclave active at a time without authorization. If a process needs to have more than one dependent enclave active at the same time, it must have read access to the BPX.WLMSERVER FACILITY class profile, or a UID of 0 if the BPX.WLMSERVER FACILITY class profile is not defined.
   WLM_EXPORT_WORKUNIT	A process can export the enclave it created using WLM_CONTINUE_WORKUNIT without authorization. To export some other enclave, the process must have read access to the BPX.WLMSERVER FACILITY class profile, or a UID of 0 if the BPX.WLMSERVER FACILITY class profile is not defined.
   WLM_UNDOEXPORT_WORKUNIT	A process can undo its prior WLM_EXPORT_WORKUNIT request without authorization. To export some other enclave, the process must have read access to the BPX.WLMSERVER FACILITY class profile, or a UID of 0 if the BPX.WLMSERVER FACILITY class profile is not defined.

2. All ARM services, with the exception of ARM_GET_ARRIVAL_TIME, require read access to the BPX.WLMSERVER FACILITY class profile, or a UID of 0 if the BPX.WLMSERVER FACILITY class profile is not defined.