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

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 will not be 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

Make the entire job permanent. All processes dubbed in this job are to be considered permanent processes. A permanent process is one 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 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

Do not undub the entire jobstep when the last dubbed task (other than the jobstep task) undubs.

DUBUNIQUEACEE

Indicates to the kernal that this address space does not share ACEEs between tasks for the life of the process.

DUBFAILNOTREADY

Any syscall attempting to dub the caller as a process during a period when the z/OS UNIX kernel is shutdown 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 this is a dubbed thread and the call is successful
• 1 if this is a dubbed process and the call is successful
• -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 complete list of possible return code values, see 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 the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

1. The default dub setting for a process that has not called this service is DUBTHREAD.
2. This service can be called to override a previous call to the service.
3. When a task that is 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. DUBNOSIGNALS is mutually exclusive with DUBPROCESSDEFER. Specifying both options yields unpredictable results.
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. After the job step task issues a set_dub_default call with option DUBPROCESSDEFER:
   • If it is the first task in the address space to issue a z/OS UNIX syscall and be dubbed, the job step task becomes a process in the address space.
   • If another task in the address space has already issued a z/OS UNIX syscall and been dubbed, the job step task becomes a thread in that process.
8. The DUBJOBPERM, DUBABENDCALLS, and DUBNOJSTUNDUB options should be used from the jobstep 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 HFS 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.