set_dub_default (BPX1SDD, BPX4SDD) — Set the dub default service

Function

The set_dub_default service allows the calling address space to change the current default dub setting for tasks within the address space.

Requirements

Operation Environment
Authorization Supervisor state or problem state, any PSW key
Dispatchable unit mode Task
Cross memory mode PASN = HASN
AMODE (BPX1SDD) 31-bit
AMODE (BPX4SDD) 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.

Format

The syntax format is as follows:
CALL BPX1SDD,(Dub_setting,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4SDD with the same parameters.

Parameters

Dub_setting
Supplied parameter
Type
Integer
Length
Fullword

The name of a fullword that contains the dub setting value.

Specifies the name of a fullword field that must contain one of the following dub setting values:
DUBPROCESS
Dub the subtasks of the caller as new processes when each issues its first z/OS UNIX service call.
DUBTHREAD
Dub the subtasks of the caller as threads in the caller's process when each issues its first z/OS UNIX service call.
DUBTASKACEE
Dub each subtask of the caller with its own z/OS UNIX security environment, if the subtask has a task-level security environment (ACEE) associated with it.
DUBNOSIGNALS
Dub the caller as a process to which signals are not delivered.
DUBPROCESSDEFER
Dub each subtask of the caller as a new process when it issues its first z/OS UNIX service call. The address space is not dubbed when this call is issued. The first dub of the address space occurs when the next z/OS UNIX service call is issued (by this task or by another task in the address space).
DUBJOBPERM
Makes the entire job permanent. All processes that are dubbed in this job are considered permanent processes. A permanent process is a process that is not taken down during a z/OS UNIX shutdown. All z/OS UNIX callable services that are called from these processes during a shutdown and restart window will return in failure.
DUBABENDCALLS
All z/OS UNIX callable services that are called from a process that is registered as permanent during a shutdown and restart window will end abnormally. This option is only relevant when it is accompanied by the DUBJOBPERM option.
DUBNOJSTUNDUB
Does not undub the entire job step when the last dubbed task (other than the job step task) undubs.
DUBUNIQUEACEE
Indicates to the kernel that this address space does not share ACEEs between tasks for the life of the process.
DUBFAILNOTREADY
Any syscall that attempts to dub the caller as a process during a period when the z/OS UNIX kernel is shut down will result in a failing return code, EMVSINITIAL, and reason code JrKernelReady. If the syscall does not have a return code parameter, it will receive an EC6 retryable abend with reason code JNotUp.
See BPXYCONS — Constants used by services for the dub setting values.
Return_value
Returned parameter
Type
Integer
Length
Fullword
The name of a fullword in which the set_dub_default service returns:
0
  • If the calling task is a dubbed thread.
  • If the calling task is not dubbed and the request did not include the DubProcessDefer option.
1
  • If the calling task is a dubbed process.
  • If the calling task is not dubbed and the request included the DubProcessDefer option.
-1
If the call is unsuccessful.
Return_code
Returned parameter
Type
Integer
Length
Fullword
The name of a fullword in which the set_dub_default service stores the return code. The set_dub_default service returns Return_code only if Return_value is -1. For a list of return code values, see Return codes (errnos) in z/OS® UNIX System Services Messages and Codes. The set_dub_default service can return one of the following values in the Return_code parameter:
Return_code Explanation
EINVAL One of the parameters contains an unsupported or incorrect value. The following reason code can accompany the return code: JRDubSetting.
EPERM The calling process does not have the appropriate privilege to perform the requested operation. The following reason code can accompany the return code: JROK.
Reason_code
Returned parameter
Type
Integer
Length
Fullword

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

Summary of option behavior and requirements

Table 1. Options and requirements for set_dub_default
Option Function Defers dubbing Issue from job step task (JST) Dub required
DUBPROCESS All subtasks of this task are dubbed as processes. No No Yes
DUBTHREAD All subtasks of this task are dubbed as threads. Dubbing threads is the default behavior of dub processing. With this option, applications can switch back from dubbing subtasks as processes to dubbing tasks as threads. No No Yes
DUBTASKACEE This task and all subtasks of the caller are given its own z/OS UNIX security environment if the task has a security environment that is different than the address space (TCBSENV ^= ASCBSENV). Using this option, applications can create a process with a different user identity without incurring the performance overhead and storage constraints of fork() or spawn() with userid.

DUBTASKACEE is the default behavior of dub processing. If a task has a TCBSENV that is different from the address space, then that task is dubbed with the task level security, regardless of the DUBTASKACEE setting.

 No No No
DUBNOSIGNALS This task will not be interrupted for signal delivery. If the job step task was blind-dubbed, it is marked as not being able to receive signals. Any application that has a task that needs to remain active and cannot tolerate a terminating signal such as a SIGKILL can use this option. No No No
DUBPROCESSDEFER Dubs each subtask of the caller as a new process when it issues its first z/OS UNIX service call. Dub processing is deferred until the next syscall is issued.

This option must be issued from the job step task. If it is issued from any other task, the call is ignored.

 Yes Yes No
DUBJOBPERM Marks the process as permanent. The process is not terminated if F OMVS,SHUTDOWN is performed.

To ensure that all processes in the address space are marked permanent, use this option from the job step task before tasks in the address space issues syscalls. When the system is shut down, any syscalls that are issued from the process will result in a failure.

 Yes Yes No
DUBABENDCALLS For processes that are permanent (dubbed with DUBJOBPERM), changes the default behavior from dub failure to abending the task when a syscall is issued while the system is being shut down.

This option is only honored when DUBJOBPERM was also specified, either on the same call or another call. Like DUBJOBPERM, issue it from the job step task before any other processes are dubbed in the address space. Otherwise, the expected behavior might not occur for all tasks in the address space.

Yes Yes No
DUBNOJSTUNDUB If the JST was blind-dubbed, then does not undub the JST (and end the process) when the last thread in the address space ends.

Use this option to ensure that critical subsystem address spaces are not terminated during OMVS shutdown. Without this option, during shutdown or if an error causes a z/OS UNIX task to abnormally terminate, the entire job step is undubbed when the last dubbed task terminates.

 Yes No No
DUBUNIQUEACEE Indicates to the kernel that this address space does not share ACEEs between tasks for the life of the process. Address spaces that have tasks that redub can have the old USP associated with the ACEE deleted and a new USP obtained. Without this setting, a new USP is obtained, which then replaces the old USP. However, the old USP is not freed and the storage is lost until that address space ends. Yes No No
DUBFAILNOTREADY Any dubbing syscall that occurs during a non-kernel ready state will fail with the EMVSINITIAL return code or JRKernelReady reason code. For the syscalls that do not have a return code, an EC6 abend with reason code JNotUp is issued.

After DUBFAILNOTREADY is issued from any task in the address space, all future dubs in that address space will fail instead of wait.

 Yes No No

Usage notes for set_dub_default

  1. DUBTHREAD is the default setting for a process that has not called this service.
  2. This service can be called to override a previous call to the service.
  3. When a task that was not already dubbed issues its first z/OS UNIX service call, its TCB tree is searched to determine the default dub setting to use. The search starts at the caller's mother task and continues up the TCB tree until an ancestor task is found that is already dubbed. If the search finds a dubbed task, the default dub setting from that task is used. If a dubbed task is not found, the task is dubbed as a new process. A dubbed task is a task that has one or more of the following attributes:
    • It has issued a z/OS UNIX service call.
    • It was created as a result of a fork service call.
    • It was created as a result of an exec or execmvs service call.
    • It was created as a result of an attach_exec or attach_execmvs service call.
    • It was created as a result of a pthread_create service call.
  4. Start of changeDUBPROCESSDEFER is mutually exclusive with DUBPROCESS, DUBTASKACEE and DUBNOSIGNALS. Specifying DUBPROCESSDEFER with one or more of these options will cause the syscall to fail with -1/EINVAL/JRDUBSETTING. End of change
  5. If DUBNOSIGNALS is used in a POSIX(ON) environment, the behavior of the process is undefined.
  6. DUBPROCESSDEFER should only be used from the job step task. It is not honored when issued from other tasks in the address space.
  7. Start of changeAfter the job step task (JST) issues a set_dub_default syscall with the DUBPROCESSDEFER option:
    • If the JST causes the address space to get dubbed, a new process is created and the JST is dubbed as the initial thread task (ITT) of the newly created process. The new process will have one thread, the JST.
    • If a task other than the JST causes the address space to be dubbed, a new process is created. The JST is dubbed as the ITT and the non-JST is dubbed as a thread in the newly created process. The new process will have two threads, the non-JST task and the JST that was dubbed as the ITT. The dubbing of the JST is known as blind dubbing. The JST must be dubbed if any other task in the address space is dubbed.
    End of change
  8. The DUBJOBPERM, DUBABENDCALLS, and DUBNOJSTUNDUB options should be used from the job step task prior to the call to any other z/OS UNIX callable service that could dub the address space, or they may not have their intended effect.
  9. The DUBUNIQUEACEE option indicates whether an application is sharing ACEEs in a MultiProcess MultiUser (MpMu) address space. When specified, this option indicates that each process in the address space with a task level ACEE has a unique ACEE. That is, the ACEEs are not shared between tasks. When specified, it allows z/OS UNIX processing to do a clean-up of certain control blocks during the redubbing of a task in the address space.

    This option is honored only when it is specified on a BPX1SDD call prior to an address space dub. When issued from any task after the address space has already been dubbed, this option is ignored.

Characteristics and restrictions

  1. When you set the DUBTASKACEE option, each task is dubbed as a separate process and uses the task-level ACEE that was set up by the user. In this environment, there are numerous restrictions on which other services can be used. This environment is supported primarily to allow a server to access zFS files and socket services. You cannot use z/OS UNIX security functions, such as setuid. Threads that are created with pthread_create do not inherit the identity of the parent. Fork and spawn do not work correctly.
  2. Users of the DUBJOBPERM and DUBABENDCALLS options must meet 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).
    If these requirements are not met, the service will fail with return code EPERM.

Examples

For an example that uses this callable service, see BPX1SDD (setdubdefault) example.