oe_env_np (BPX1ENV, BPX4ENV) — Examine, change, or examine and change an environmental attribute

Function

The oe_env_np service examines, changes, or examines and changes an environmental attribute. The environmental attribute to be processed is determined by the value that is specified by the Function_code parameter.

Requirements

Parameters

Function_code

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword specifying a numeric value that identifies the environmental attribute the caller wants to examine, change, or both examine and change. Each environmental attribute has a specific Function_code value; these are defined in the BPXYCONS macro. See BPXYCONS — Constants used by services.

Constant	Function
DFP_CLEANUP_EXIT_REG	Registers a DFP cleanup exit that is to be called during process cleanup processing. No other input parameters are applicable for this function. Upon success, a return value of zero is supplied. No unique error codes apply to this function code.
ENQWAIT_PROCESS	Determines the kernel behavior when pthread_quiesce (freeze or term) and pthread_cancel encounter threads in MVS™ ENQ waits.
FREEZE_EXIT_REG	Registers/deregisters a user exit that is to be given control when a pthread_quiesce(freeze_exit) call is made.
MVS_USERID	Retrieves the MVS user ID of the invoker.
ENV_TOGGLE_SEC	Toggles the task-level security.
ENV_STOR_SERVICE	Modifies storage attributes of an address space.
SHUTDOWN_REG	Registers the caller for special treatment at OMVS shutdown time.
WRITE_DOWN	Sets, resets, or queries the setting of the write-down privilege in the target ACEE.
PIDXFER_QUERY	Determines if the current process image was the result of a PIDXFER-type exec.
QUERY_MODE	Returns the AMODE, RMODE, and AMODE capability of a target PID.
MUST_STAY_CLEAN	Sets or queries the address space MUST_STAY_CLEAN state. Once this state is set, any loads or execs are prevented to files that reside in uncontrolled libraries.

The value that is specified for the Function_code also determines the number and length of input and output parameters. See the usage notes for details on defined function codes.

InArgCount

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword specifying a numeric value that indicates the number of parameters pointed to by the InArgListPtr parameter. If no input arguments are required, specify the name of a fullword that contains 0. If 0 is specified, no environmental attributes are changed.

InArgListPtr

Supplied parameter

Type:

Address

Length:

Fullword (doubleword)

The name of a fullword (doubleword) containing an address that points to an array of addresses that point to parameters. If the value that is specified for InArgCount is 0, the value that is specified for the InArgListPtr is ignored. See the usage notes for details on how to specify input parameters.

OutArgCount

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword specifying a numeric value that indicates the number of parameters pointed to by the OutArgListPtr parameter. If no output arguments are required, specify the name of a fullword that contains 0. If 0 is specified, no environmental attributes are examined.

OutArgListPtr

Supplied parameter

Type:

Address

Length:

Fullword (doubleword)

The name of a fullword (doubleword) containing an address that points to an array of addresses that point to parameters. If the value that is specified for OutArgCount is 0, the value that is specified for the OutArgListPtr is ignored. See the usage notes for details on how to specify input parameters.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

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

Return_code	Explanation
EFAULT	The InArgListPtr, OutArgListPtr or associated parameter lists point to a location that is partially or completely outside of the addressable storage range.
EINVAL	The Function_code value specified is not defined, or the InArgCount or OutArgCount parameter contains an incorrect count for the specified Function_code. The following reason codes can accompany the return code: JRFuncUndefined, JRBadArgCount or JRBadInputValue. If the SHUTDOWN_REG function was requested, the following reason codes can accompany the return code: JRJSTMustBeRegistered, JRAlreadyInShutDown, JRBlockPermAlreadyRegistered, JRBlockPermNotRegistered, JRBadInputValue, or JRAlreadyInShutDown.
EMVSSAF2ERR	There was an internal error in the security product. The hexadecimal reason code value contains the two-byte security product return code xx and reason code yy.
EMVSERR	The BPX.DAEMON FACILITY class profile is not defined. Reason code JRNoDaemon can accompany this return code.
EPERM	One of the following conditions occurred: The calling process does not have the appropriate privilege to perform the requested operation. The reason code JROK can accompany this return code. If the SHUTDOWN_REG function was requested, the caller must be given read permission to the BPX.SHUTDOWN resource in the FACILITY class. A call was made to register as a permanent process or job but the calling process was started with the respawn attribute. Reason code JRRespawnNotAllowed can accompany this return code.
ENOSYS	The implementation does not support this memory locking interface. Reason code JRNotBpxStorSwap can accompany this return code.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the oe_env_np service stores the reason code. The oe_env_np 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. If the value that is specified by InArgCount or OutArgCount is 0, the corresponding InArgListPtr or OutArgListPtr is ignored. They must still be specified, but the value that is contained in the named field is irrelevant.
2. The oe_env_np service can examine, change, or examine and change environmental attributes based on the argument counts that are specified by the caller. If only an InArgCount is specified, an environmental attribute is changed, but the previous value is not returned. If only an OutArgCount is specified, the current setting of an environmental attribute is examined and returned but not changed. If both an InArgCount and OutArgCount are specified, the environmental attribute is changed and the previous setting is returned. If neither InArgCount nor OutArgCount are specified, no environmental attributes are examined or changed (NOOP), and the oe_env_np service sets Return_value to 0.
3. The InArgListPtr and OutArgListPtr parameters each contain a fullword address that points to an array. The argument count (InArgCount and OutArgCount) defines the number of elements in each of these arrays. Each element in the arrays contains a fullword address that points to a parameter. The length of each parameter varies according to the Function_code specified.

   The following figure is an example of an input or output parameter list as specified by the InArgListPtr and OutArgListPtr parameter.

   
4. The following table defines the number of input and output arguments (if specified) and the scope of each defined Function_code.
   The scope of an environmental attribute is the range of influence the attribute has in the kernel. The highest level of scope is ADDRESS SPACE: these attributes have influence over all processes and threads in an address space. The next level of scope is PROCESS: these attributes have influence over a single process. The lowest level of scope is THREAD: these attributes have influence over a single thread.

   Function_code	# Input Args	# Output Args	Scope
   ENQWAIT_PROCESS	1	1	Process
   FREEZE_EXIT_REG	1	1	Process
   MVS_USERID	0	1	Thread
   ENV_TOGGLE_SEC	0	0	Thread
   ENV_STOR_SERVICE	1	0	Address space
   SHUTDOWN_REG	4	0	Process or address space
   WRITE_DOWN	1	0 or 1	Address space or thread
   PIDXFER_QUERY	0	1	Process
   QUERY_MODE	1	3	Address space (AMODE, RMODE) or process (AMODE capability)
   MUST_STAY_CLEAN	1	1	Address space

5. Function_code and argument definitions:
   • ENQWAIT_PROCESS

     The purpose of the ENQWAIT_PROCESS Function_code is to register with the kernel the behavior desired when a pthread_quiesce(freeze or term) or pthread_cancel encounters a thread in an ENQ wait in the caller's process.

     When ENQWAIT_PROCESS is disabled, the kernel does not interrupt threads that are found in ENQ waits. This means that pthread_quiesce(freeze or term) and pthread_cancel events are not delivered to a thread until after the ENQ wait has completed. This is the default behavior for all processes.

     When ENQWAIT_PROCESS is enabled, the kernel interrupts threads that are found in ENQ waits. The kernel delivers pthread_quiesce(freeze) events to threads by scheduling an IRB on top of the SVRB for the ENQ wait, and freezing the thread from the IRB. For pthread_quiesce(term) or pthread_cancel events, the kernel abends threads in ENQ waits with a retryable 422 abend, reason code X'00000189'.

     To get pending pthread_cancel and pthread_quiesce(term) events delivered, applications that invoke ENQ need to do the following:

     • Establish an ESTAE before invoking ENQ.
     • Have the ESTAE retry and check for the 422 abend with reason code X'00000189'.
     • When the abend is detected, call sigprocmask and block all signals. On return from sigprocmask the pthread_cancel or pthread_quiesce(term) events are delivered.
     When a pthread_cancel interrupts a thread in an ENQ, the target thread is abended (S0422-189). If an ESTAE has not been established or just percolates, the entire process is terminated. This behavior is required for standards compliance.

     • Input arguments:
       • 1st argument (fullword):

         Value	Definition
         0	Disable ENQ wait interrupt support in the caller's process.
         1	Enable ENQ wait interrupt support in the caller's process.

     • Output arguments:
       • 1st argument (fullword):

         Value	Definition
         0	ENQ wait interrupt support is disabled in the caller's process.
         1	ENQ wait interrupt support is enabled in the caller's process.

   • FREEZE_EXIT_REG

     The purpose of the FREEZE_EXIT_REG Function_code is to register with the kernel the address of an exit that is to get control when the Freeze-Exit function code of the pthread_quiesce service is requested. The exit gets control once on each thread processed by the pthread_quiesce(Freeze_Exit) service.

     If a FREEZE_EXIT_REG is registered, the kernel gives control to the specified exit as a result of the pthread_quiesce(freeze_exit) call.

     The user exit is given control while the pthread_quiesce service is still in progress. The user exit should not attempt to use any service that alters or terminates the current process. No callable services should be requested. If such services are attempted, the results are unpredictable.

     The register usage on entry to the user exit is:

     • R0: Undefined
     • R1: Address of the parameter list defined by PpsdSIRParms. The first word of this parameter list is the address of the Ppsd.
     • R2–R15: Undefined
     When the exit returns, there are no expected return values or codes. The exit routine should terminate via SVC 3.

     • Input arguments:
       • 1st argument (fullword):

         Value	Definition
         address	Pthread_quiesce(Freeze_Exit) exit address.
         0	Clear pthread_quiesce(Freeze_exit) address. Specifying zero unregisters an exit address.

     • Output arguments:
       • 1st argument (fullword):

         Value	Definition
         address	Pthread_quiesce(Freeze_Exit) exit address.
         0	No exit has been registered with the kernel.

   • MVS_USERID

     The purpose of the MVS_USERID Function_code is to query the current MVS identity of the caller. The MVS user ID that is returned can be affected by the presence of a task-level security environment. If a task-level security environment has been created by the pthread_security_np service, the user ID that is associated with the task is returned.

     The InArgCount must be 0, and the OutArgCount must be 1.

     • Input arguments:
       • 1st argument (None)

         Value	Definition
         N/A	N/A

     • Output arguments:
       • 1st argument (Char 8)

         Value	Definition
         The current MVS user ID	8-character user ID padded on the right with blanks.

   • ENV_TOGGLE_SEC

     The purpose of the ENV_TOGGLE_SEC Function_code is to toggle the task-level security. If the calling task has a task-level security environment, it is saved, and the task security is set back to the process level. If the calling task has a saved security environment and currently has no task-level security, the saved security environment is reinstated. If the calling task has not made a prior call to pthread_security_np, this call has no effect.

     There are no additional input or output arguments, so the InArgCount and the OutArgCount must be 0.

   • ENV_STOR_SERVICE

     The purpose of the ENV_STOR_SERVICE Function_code is to modify the storage attributes of the caller's address space. The caller's address space cannot be made swappable unless it has previously been made non-swappable by this function. If the function is called to make an address space non-swappable and the current address space has already been made non-swappable by this function, the call is ignored and the address space remains non-swappable.

     The InArgCount must be 1, and the OutArgCount must be 0.

     • Input arguments:
       • 1st argument (Structure):

         ENV_STOR_FLAGS (Supplied Parameter)

         ENV_STOR_FLAGS can be set to the following values defined in BPXYCONS macro:

         Value	Definition
         BPX_SWAP	Makes the address space swappable. The caller needs at least READ access to the BPX.STOR.SWAP resource in the FACILITY class.
         BPX_NONSWAP	Makes the address space non-swappable. The caller needs at least READ access to the BPX.STOR.SWAP resource in the FACILITY class. When an application makes an address space non-swappable, it may cause additional real storage in the system to be converted to preferred storage. Preferred storage cannot be configured offline. Use of this service can therefore reduce an installation's ability to reconfigure storage in the future. Any application using this service should warn the customer about this side effect in the installation documentation.

     • Output arguments:
       • 1st argument (None)

         Value	Definition
         N/A	N/A

   • SHUTDOWN_REG

     The purpose of the SHUTDOWN_REG Function_code is to request special treatment for the caller at OMVS shutdown time.

     The SHUTDOWN_REG exit receives control in the caller's address space with it being both the home and primary address space. For a process-level registration, the exit runs in task mode from an IRB running on the initial thread task of the process that called the BPXnENV registration service. For a job-level registration, it runs on the initial thread task of the first process in the address space. The authorization state of the exit will be the same PSW key and PSW state of the caller of BPXnENV. The exit receives no parameters. Because the exit is driven from an IRB, it might not be able to issue other z/OS® UNIX callable services; therefore, it should not depend on doing so.

     The following is the register usage on entry to the exit:

     • R0–R12: Undefined
     • R13: Address of a 96-byte work area in the same key as the caller that registered the exit
     • R14: The return address from the exit to the operating system. The exit must preserve this address to be used to return to the operating system.
     • R15: The address of the exit

     There are constants defined in BPXYCONS for use with the SHUTDOWN_REG function. See BPXYCONS — Constants used by services.

     The InArgCount must be 4, and the OutArgCount must be 0.

     • Input arguments:
       • 1st parameter (fullword):
         The first parameter contains a value that indicates the type of shutdown registration being requested:

         Value	Definition
         1	Register as a blocking process or job
         2	Register as a permanent process or job
         3	Unregister as a blocking process or job
         4	Unregister as a permanent process or job
         5	Register for notification of shutdown
         6	Unregister for notification of shutdown

       • 2nd parameter (fullword):
         The second parameter contains a value that indicates the scope of shutdown registration being requested:

         Value	Definition
         1	Register for the calling job
         2	Register for the calling process

         The values in the first two parameters are mutually exclusive; they cannot be combined.
       • 3rd parameter (fullword):
         The third parameter contains a value that indicates the registration options being requested:

         Value	Definition
         1	Block system calls that are waiting for restart (valid for permanent registration only).
         2	Abend system calls during shutdown/restart (valid for permanent registration only). This option is mutually exclusive with option value 1.
         4	Send a SIGTERM signal when shutdown is initiated.
         8	Invoke a specified exit when shutdown is initiated. This option is mutually exclusive with option 4 (send a SIGTERM).

       • 4th parameter (fullword):

         The fourth parameter contains the address of the exit that is to receive control at shutdown time, or 0.

     • Output arguments:
       • (None)
   • WRITE_DOWN

     The purpose of the WRITE_DOWN Function_code is to set, reset, or query the setting of the write-down privilege in the target ACEE.

     The InArgCount must be 2, and the OutArgCount must be 0 or 1.

     • Input arguments:
       • 1st argument (Fullword):
         The first argument contains a value that indicates the type of operation to be performed:

         Value	Definition
         0	Query the current setting of the write-down privilege.
         1	Activate the write-down privilege.
         2	Deactivate the write-down privilege.
         3	Reset the write-down privilege to its default value.

       • 2nd argument (fullword):
         The second argument contains a value that indicates the scope of the write-down privilege operation to be performed:

         Value	Definition
         1	Perform write-down operation on address-space level ACEE (WD_SCOPE_AS).
         2	Perform write-down operation on task-level ACEE (WD_SCOPE_THD).

     • Output arguments:
       • 1st argument (fullword):

         This argument is only returned when the OutArgCount is 1. If the OutArgCount is 0, this argument is ignored.

         Value	Definition
         0	Write-down privilege is inactive for ACEE (WD_IS_INACTIVE).
         1	Write-down privilege is active for ACEE (WD_IS_ACTIVE).

   • PIDXFER_QUERY

     The purpose of the PIDXFER_QUERY Function_code is to determine if the caller's current process image was created as the result of a PIDXFER-type exec.

     The InArgCount must be 0, and the OutArgCount must be 1.

     • Input arguments:
       • 1st argument: None.
     • Output arguments:
       • 1st argument (fullword):

         Value	Definition
         0	The current process image was not the result of a PIDXFER exec (PIDXFER_NO).
         1	The current process image was the result of a PIDXFER exec (PIDXFER_YES).

   • QUERY_MODE
     The purpose of the QUERY_MODE Function_code is to query:

     • The addressing mode (AMODE) of the target PID
     • The residency mode (RMODE) of the target PID
     • The ability of the address space in which the PID is running to support an AMODE 64 program; in other words, whether storage can be obtained above the bar

     The service records the modes at the time the process was created (dubbed), or at the time of the last executed program. If a process has multiple threads, the service reports on the AMODE of the initial thread of the process.

     The InArgCount must be 1, and the OutArgCount must be 3.

     • Input arguments:
       • 1st argument: PID of the target process.
     • Output arguments:
       • 1st argument (fullword):

         The first argument contains a value that indicates the AMODE of the target process:

         Value	Definition
         1	24-bit AMODE
         2	31-bit AMODE
         3	64-bit AMODE

       • 2nd argument (fullword):

         The second argument contains a value that indicates the RMODE of the target process:

         Value	Definition
         1	24-bit RMODE
         2	31-bit RMODE
         3	64-bit RMODE

       • 3rd argument (fullword):

         The third argument contains a value that indicates the AMODE capability of the target process:

         Value	Definition
         1	24-bit AMODE capability
         2	31-bit AMODE capability
         3	64-bit AMODE capability

   • MUST_STAY_CLEAN

     The purpose of the MUST_STAY_CLEAN Function_code is to ensure that a process and its children are, and will remain program-controlled. A process must be program-controlled in order to enable the MUST_STAY_CLEAN state. If a process is not program-controlled, this service will fail with a return code of EMVSERR and a reason code of JRENVDIRTY. Also, message BPXP015I is written to the console indicating the program that made the process uncontrolled. Once set, a process will not be able to load, execute, or spawn any files that are not from program-controlled libraries. Since this state is also propagated to children during a fork or spawn, the processes involved can fully trust one another.

     The typical usage is for a process to set this state, create any children, and then in any child processes query the state. In order to trust the parent the child must issue the query service before any other security-related services are used in the child process. (For a list of these security services see Setting up the BPX.* FACILITY class profiles in z/OS UNIX System Services Planning.) In this way the child can be sure that it has inherited the state instead of the state being set by an action of the child. If the child recognizes that the state is enabled, all processes involved can trust one another. Usage of this service to enable the MUST_STAY_CLEAN state requires the BPX.DAEMON FACILITY class profile to be defined. If it is not defined the service will fail with a return code of EMVSERR and a reason code of JRNODAEMON.

     • Input arguments:
       • First argument (fullword):

         Value	Definition
         0	Query the current MUST_STAY_CLEAN state. The current state is returned in the first output argument.
         1	Enable MUST_STAY_CLEAN state.

     • Output arguments:
       • 1st argument (fullword):

         Value	Definition
         0	MUST_STAY_CLEAN state is disabled.
         1	MUST_STAY_CLEAN state is enabled.
         2	MUST_STAY_CLEAN state is conditional.

6. If the MUST_STAY_CLEAN service returns EMVSSAF2ERR, then the propagated failing 1-byte return code and 1-byte reason code of the IRRENS00 service is found in the last two bytes of the reason code returned by BPX1ENV/BPX4ENV.
7. A returned state of MSC_ENABLED indicates the state was set by this service and will continue even after exec()s that cause a job step to terminate. A returned state of MSC_ENABLED_COND indicates a previous security service, such as BPX1PWD, enabled the clean state and will be reset when the next job step runs.

Related services

• pthread_cancel (BPX1PTB, BPX4PTB) — Cancel a thread
• pthread_quiesce (BPX1PTQ, BPX4PTQ) — Quiesce threads in a process
• pthread_security_np, pthread_security_applid_np (BPX1TLS, BPX4TLS) — Create|delete thread-level security

Characteristics and restrictions

1. Users of the blocking and permanent registration options of the SHUTDOWN_REG function must meet one of the following requirements:
   • The calling address space must be a system started task address space.
   • The caller must be running authorized (APF-authorized, system key 0–7, or supervisor state).
   • The caller must be a privileged z/OS UNIX process. It must have either superuser identity or read permission to the BPX.SHUTDOWN profile in the FACILITY class.
2. For the write-down privilege to be activated, the user ID in the target ACEE must be permitted to the IRR.WRITEDOWN.BYUSER profile in the FACILITY class. The FACILITY class must be active and RACLISTed, and the SETROPTS MLS option must be active.