$CREPRC

From VSI OpenVMS Wiki
Revision as of 07:14, 9 July 2019 by Darya.zelenina (talk | contribs) (added a link to an example)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

$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.

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.

See also