$CREPRC
$CREPRC is a system service that is used to create a subprocess or detached process on the current node, or a detached process on another node on behalf of the calling process.
Contents
Format
SYS$CREPRC [pidadr] ,[image] ,[input] ,[output] ,[error] ,[prvadr] ,[quota] ,[prcnam] ,[baspri] ,[uic] ,[mbxunt] ,[stsflg] ,[itmlst] ,[node] ,[home_rad]
pidadr
The address of a longword into which $CREPRC writes the PID of the newly created process.
image
The address of a character string descriptor pointing to the file specification of the image to be activated in the newly created proces.
The image name can have a maximum of 63 characters. If the image name contains a logical name, the logical name is translated in the created process and must therefore be in a logical name table that it can access.
To create a process that will run under the control of a command language interpreter (CLI), specify SYS$SYSTEM:LOGINOUT.EXE as the image name.
input
Equivalence name to be associated with the logical name SYS$INPUT in the logical name table of the created process. The input argument is the address of a character string descriptor pointing to the equivalence name string.
output
Equivalence name to be associated with the logical name SYS$OUTPUT in the logical name table of the created process. The output argument is the address of a character string descriptor pointing to the equivalence name string.
error
Equivalence name to be associated with the logical name SYS$ERROR in the logical name table of the created process. The error argument is the address of a character string descriptor pointing to the equivalence name string. Note that the error argument is ignored if the image argument specifies SYS$SYSTEM:LOGINOUT.EXE; in this case, SYS$ERROR has the same equivalence name as SYS$OUTPUT.
prvadr
Privileges to be given to the created process. The prvadr argument is the address of a quadword bit mask wherein each bit corresponds to a privilege; setting a bit gives the privilege. If the prvadr argument is not specified, the current privileges are used.
Each bit has a symbolic name; the $PRVDEF macro defines these names. You form the bit mask by specifying the symbolic name of each desired privilege in a logical OR operation.
| Privilege | Symbolic Name | Description |
|---|---|---|
| ACNT | PRV$M_ACNT | Create processes for which no accounting is done |
| ALLSPOOL | PRV$M_ALLSPOOL | Allocate a spooled device |
| ALTPRI | PRV$M_ALTPRI | Set (alter) any process privilege |
| AUDIT | PRV$M_AUDIT | Generate audit records |
| BUGCHK | PRV$M_BUGCHK | Make bugcheck error log entries |
| BYPASS | PRV$M-BYPASS | Bypass UIC-based protection |
| CMEXEC | PRV$M_CMEXEC | Change mode to executive |
| CMKRNL | PRV$M_CMKRNL | Change mode to kernel |
| DIAGNOSE | PRV$M_DIAGNOSE | Can diagnose devices |
| DOWNGRADE | PRV$M_DOWNGRADE | Can downgrade classification |
| EXQUOTA | PRV$M_EXQUOTA | Can exceed quotas |
| GROUP | PRV$M_GROUP | Group process control |
| GRPNAM | PRV$M_GRPNAM | Place name in a group logical name table |
| GRPPRV | PRV$M_GRPPRV | Group access via system protection field |
| IMPERSONATE | PRV$M_IMPERSONATE | Can create detached processes under another UIC |
| IMPORT | PRV$M_IMPORT | Mount a nonlabeled tape volume |
| LOG_IO | PRV$M_LOG_IO | Perform logical I/O operations |
| MOUNT | PRV$M_MOUNT | Issue mount volume QIO |
| NETMBX | PRV$M_NETMBX | Create a network device |
| OPER | PRV$M_OPER | All operator privileges |
| PFNMAP | PRV$M_PFNMAP | Map to section by physical page frame number |
| PHY_IO | PRV$M_PHY_IO | Perform physical I/O operations |
| PRMCEB | PRV$M_PRMCEB | Create permanent common event flag clusters |
| PRMGBL | PRV$M_PRMGBL | Create permanent global sections |
| PRMMBX | PRV$M_PRMMBX | Create permanent mailboxes |
| PSWAPM | PRV$M_PSWAPM | Change process swap mode |
| READAL | PRV$M_READALL | Posess read access to everything |
| SECURITY | PRV$M_SECURITY | Can perform security functions |
| SETPRV | PRV$M_SETPRV | Set any process privilege |
| SHARE | PRV$M_SHARE | Can assign a channel to a nonshared device |
| SYSGBL | PRV$M_SYSGBL | Can create system global sections |
| SYSLCK | PRV$M_SYSLCK | Queue systemwide locks |
| SYSNAM | PRV$M_SYSNAM | Place name in system logical name table |
| SYSPRV | PRV$M_SYSPRV | Access files and other resources as if you have a system UIC |
| TMPMBX | PRV$M_TMPMBX | Create temporary mailboxes |
| UPGRADE | PRV$M_UPGRADE | Can upgrade classification |
| VOLPRO | PRV$M_VOLPRO | Override volume protection |
| WORLD | PRV$M_WORLD | World process control |
You need the user privilege SETPRV to grant a process any privileges other than your own. If the caller does not have this privilege, the mask is minimized with the current privileges of the creating process; any privileges the creating process does not have are not granted, but no error status code is returned.
quota
Process quotas to be established for the created process. These quotas limit the created process's use of system resources. The quota argument is the address of a list of quota descriptors, where each quota descriptor consists of a 1-byte quota name followed by a longword that specifies the desired value for that quota. The list of quota descriptors is terminated by the symbolic name PQL$_LISTEND. If you do not specify the quota argument or specify it as 0, the operating system supplies a default value for each quota.
Example in C:
#include <pqldef.h>
...
#pragma member_alignment save
#pragma nomember_alignment
typedef struct
{
char Quota;
int Value;
} QUOTA_ENTRY_T;
#pragma member_alignment restore
...
QUOTA_ENTRY_T QuotaArray[] =
{{PQL$_PRCLM, 2}, {PQL$_ASTLM, 6}, {PQL$_LISTEND, 0}};
The description of each quota lists its minimum value (a system parameter), its default value (a system parameter), and whether it is deductible, nondeductible, or pooled. These terms have the following meanings:
| Minimum value | A process cannot be created with a quota less than this minimum. Any quota value you specify is maximized against this minimum. You obtain the minimum value for a quota by running SYSGEN to display the corresponding system parameter. |
| Default value | If the quota list does not specify a value for a particular quota, the system assigns the process this default value. You obtain the default value by running SYSGEN to display the corresponding system parameter. |
| Deductible quota | When you create a subprocess, the value for a deductible quota is subtracted from the creating process's current quota and is returned to the creating process when the subprocess is deleted. There is currently only one deductible quota, the CPU time limit. Note that quotas are never deducted from the creating process when a detached process is created. |
| Nondeductible quota | Nondeductible quotas are established and maintained separately for each process and subprocess. |
| Pooled quota | Pooled quotas are established when a detached process is created, and they are shared by that process and all its descendent subprocesses. Charges against pooled quota values are subtracted from the current available totals as they are used and are added back to the total when they are not being used. |
prcnam
Process name to be assigned to the created process. The prcnam argument is the address of a character string descriptor pointing to a process name string. If a subprocess is being created, the process name is implicitly qualified by the UIC group number of the creating process. If a detached process is being created, the process name is qualified by the group number specified in the uic argument.
baspri
Base priority to be assigned to the created process. The baspri argument is a longword value. The OpenVMS Alpha and Integrity servers range is 0 to 63, with real-time priorities in the range 32 to 63.
If you want a created process to have a higher priority than its creating process, you must have ALTPRI privilege to raise the priority level. If the caller does not have this privilege, the specified base priority is compared with the caller's priority and the lower of the two values is used.
A process with ALTPRI privilege running on a VAX node can create a process with a priority greater than 31 on an Alpha or Integrity servers node.
If the baspri argument is not specified, the priority defaults to 2 for VAX MACRO, VAX BLISS--32, and Pascal; it defaults to 0 for all other languages.
uic
User identification code (UIC) to be assigned to the created process. The uic argument is a longword value containing the UIC. If you do not specify the uic argument or specify it as 0 (the default), $CREPRC creates a process and assigns it the UIC of the creating process.
If you specify a nonzero value for the uic argument, $CREPRC creates a detached process. This value is interpreted as a 32-bit octal number, with two 16-bit fields:
bits 0--15---member number bits 16--31---group number You need IMPERSONATE or CMKRNL privilege to create a detached process with a UIC that is different from the UIC of the creating process.
If the image argument specifies the SYS$SYSTEM:LOGINOUT.EXE, the UIC of the created process will be the UIC of the caller of $CREPRC, and the UIC parameter is ignored.
mbxunt
Unit number of a mailbox to receive a termination message when the created process is deleted. The mbxunt argument is a word containing this number. If you do not specify the mbxunt argument or specify it as 0 (the default), the operating system sends no termination message when it deletes the process.
The Get Device/Volume Information ($GETDVI) service can be used to obtain the unit number of the mailbox.
If you specify the mbxunt argument, the mailbox is used when the created process actually terminates. At that time, the $ASSIGN service is issued for the mailbox in the context of the terminating process and an accounting message is sent to the mailbox. If the mailbox no longer exists, cannot be assigned, or is full, the error is treated as if no mailbox had been specified.
If you specify this argument when you create a process on another node, an accounting message will be written to the mailbox when the process terminates. If the node is removed from the cluster before the created process terminates, an accounting message will be simulated. The simulated message will contain the created process's PID and name and a final status of SS$_NODELEAVE, but will lack execution statistics.
Note that two processes on different nodes cannot use the termination mailbox for general interprocess communication.
The accounting message is sent before process rundown is initiated but after the process name has been set to null. Thus, a significant interval of time can occur between the sending of the accounting message and the final deletion of the process.
To receive the accounting message, the caller must issue a read to the mailbox. When the I/O completes, the second longword of the I/O status block, if one is specified, contains the process identification of the deleted process.
The $ACCDEF macro defines symbolic names for offsets of fields within the accounting message. The offsets, their symbolic names, and the contents of each field are shown in the following table. Unless stated otherwise, the length of the field is 4 bytes.
stsflg
Options selected for the created process. The stsflg argument is a longword bit vector wherein a bit corresponds to an option. Only bits 0 to 22 are used; the others are reserved and must be 0. Each option (bit) has a symbolic name, which the $PRCDEF macro defines.
itmlst
Reserved by VSI.
node
Name of the OpenVMS Cluster node on which the process is to be created. The node argument is the address of a character string descriptor pointing to a 1- to 6-character SCS node name string. If the argument is present but zero or if the string is zero length, the process is created on the current node.
home_rad
Sets the home resource affinity domain (RAD) of a process. The home RAD is determined by the operating system, unless you explicitly request one. If bit PRC$M_HOME_RAD in the stsflg is set, home_rad is the RAD on which the process is to start. Note that you may set this bit to 0 on non-RAD systems.
RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers.
