HP OpenVMS System Services Reference Manual
Previous Contents Index

$CREPRC

Creates, on behalf of the calling process, a subprocess or detached process on the current node, or a detached process on another OpenVMS Cluster node.

Format

SYS$CREPRC [pidadr] ,[image] ,[input] ,[output] ,[error] ,[prvadr] ,[quota] ,[prcnam] ,[baspri] ,[uic] ,[mbxunt] ,[stsflg] ,[itmlst] ,[node] ,[home_rad]

C Prototype

int sys$creprc (unsigned int *pidadr, void *image, void *input, void *output, void *error, struct _generic_64 *prvadr, unsigned int *quota, void *prcnam, unsigned int baspri, unsigned int uic, unsigned short int mbxunt, unsigned int stsflg,...);

Arguments

pidadr


OpenVMS usage: process_id
type: longword (unsigned)
access: write only
mechanism: by reference

Process identification (PID) of the newly created process. The pidadr argument is the address of a longword into which $CREPRC writes the PID.

image


OpenVMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed-length string descriptor

Name of the image to be activated in the newly created process. The image argument is the address of a character string descriptor pointing to the file specification of the image.

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


OpenVMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed-length string descriptor

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


OpenVMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed-length string descriptor

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


OpenVMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed-length string descriptor

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


OpenVMS usage: mask_privileges
type: quadword (unsigned)
access: read only
mechanism: by reference

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.

Table SYS-20 gives the symbolic name and description of each privilege.

Table SYS-20 User Privileges
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 priority
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 group logical name table
GRPPRV PRV$M_GRPPRV Group access via system protection field
IMPERSONATE 1 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
READALL PRV$M_READALL Possess read access to everything
SECURITY PRV$M_SECURITY Can perform security functions
SETPRV PRV$M_SETPRV Set any process privileges
SHARE PRV$M_SHARE Can assign a channel to a nonshared device
SYSGBL PRV$M_SYSGBL 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

1This privilege replaces the DETACH privilege; however, the prior mask, PRV$M_DETACH, is still valid for existing programs.

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


OpenVMS usage: item_quota_list
type: longword (unsigned)
access: read only
mechanism: by reference

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.

For example, in MACRO you can specify a quota list, as follows: 


QLIST:  .BYTE   PQL$_PRCLM      ; Limit number of subprocesses 
        .LONG   2               ; Max = 2 subprocesses 
        .BYTE   PQL$_ASTLM      ; Limit number of asts 
        .LONG   6               ; Max = 6 outstanding asts 
        .BYTE   PQL$_LISTEND    ; End of quota list

The $PQLDEF macro defines symbolic names for quotas.

In C you can specify a quota list, as follows: 


#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}};

Individual Quota Descriptions

A description of each quota follows. 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.

To run SYSGEN to determine the minimum and default values of a quota, enter the following sequence of commands: 


$ RUN SYS$SYSTEM:SYSGEN
SYSGEN> SHOW/PQL

Minimum values are named PQL_Mxxxxx, where xxxxx are the characters of the quota name that follow "PQL$_" in the quota name.

Default values are named PQL_Dxxxxx, where xxxxx are the characters of the quota name that follow "PQL$_" in the quota name.

Individual Quotas

PQL$_ASTLM

Asynchronous system trap (AST) limit. This quota restricts both the number of outstanding AST routines specified in system service calls that accept an AST address and the number of scheduled wakeup requests that can be issued.
Minimum: PQL_MASTLM
Default: PQL_DASTLM
Nondeductible

PQL$_BIOLM

Buffered I/O limit. This quota limits the number of outstanding system-buffered I/O operations. A buffered I/O operation is one that uses an intermediate buffer from the system pool rather than a buffer specified in a process's $QIO request.
Minimum: PQL_MBIOLM
Default: PQL_DBIOLM
Nondeductible

PQL$_BYTLM

Buffered I/O byte count quota. This quota limits the amount of system space that can be used to buffer I/O operations or to create temporary mailboxes.
Minimum: PQL_MBYTLM
Default: PQL_DBYTLM
Pooled

PQL$_CPULM

CPU time limit, specified in units of 10 milliseconds. This quota limits the total amount of CPU time that a created process can use. When it has exhausted its CPU time limit quota, the created process is deleted and the status code SS$_EXCPUTIM is returned.

If you do not specify this quota and the created process is a detached process, the detached process receives a default value of 0, that is, unlimited CPU time.

If you do not specify this quota and the created process is a subprocess, the subprocess receives half the CPU time limit quota of the creating process.

If you specify this quota as 0, the created process has unlimited CPU time, provided the creating process also has unlimited CPU time. If, however, the creating process does not have unlimited CPU time, the created process receives half the CPU time limit quota of the creating process.

The CPU time limit quota is a consumable quota; that is, the amount of CPU time used by the created process is not returned to the creating process when the created process is deleted.

Minimum: PQL_MCPULM
Default: PQL_DCPULM
Deductible

PQL$_DIOLM

Direct I/O quota. This quota limits the number of outstanding direct I/O operations. A direct I/O operation is one for which the system locks the pages containing the associated I/O buffer in memory for the duration of the I/O operation.
Minimum: PQL_MDIOLM
Default: PQL_DDIOLM
Nondeductible

PQL$_ENQLM

Lock request quota. This quota limits the number of lock requests that a process can queue.
Minimum: PQL_MENQLM
Default: PQL_DENQLM
Pooled

PQL$_FILLM

Open file quota. This quota limits the number of files that a process can have open at one time.
Minimum: PQL_MFILLM
Default: PQL_DFILLM
Pooled

PQL$_JTQUOTA

Job table quota. This quota limits the number of bytes of system paged pool used for the job logical name table. If the process being created is a subprocess, this item is ignored.

A value of 0 represents an unlimited number of bytes.

Minimum: PQL_MJTQUOTA
Default: PQL_DJTQUOTA
Nondeductible

PQL$_PGFLQUOTA

Paging file quota. This quota limits the number of pagelets (adjusted up or down to represent CPU-specific pages) that can be used to provide secondary storage in the paging file for the execution of a process.
Minimum: PQL_MPGFLQUOTA
Default: PQL_DPGFLQUOTA
Pooled

PQL$_PRCLM

Subprocess quota. This quota limits the number of subprocesses a process can create.
Minimum: PQL_MPRCLM
Default: PQL_DPRCLM
Pooled

PQL$_TQELM

Timer queue entry quota. This quota limits both the number of timer queue requests a process can have outstanding and the creation of temporary common event flag clusters.
Minimum: PQL_MTQELM
Default: PQL_DTQELM
Pooled

PQL$_WSDEFAULT

Default working set size. This quota defines the number of pagelets (adjusted up or down to represent CPU-specific pages) in the default working set for any image the process executes. The working set size quota determines the maximum size you can specify for this quota.
Minimum: PQL_MWSDEFAULT
Default: PQL_DWSDEFAULT
Nondeductible

PQL$_WSEXTENT

Working set expansion quota. This quota limits the maximum size to which an image can expand its working set size with the Adjust Working Set Limit ($ADJWSL) system service.
Minimum: PQL_MWSEXTENT
Default: PQL_DWSEXTENT
Nondeductible

PQL$_WSQUOTA

Working set size quota. This quota limits the maximum size to which an image can lock pages in its working set with the Lock Pages in Memory ($LCKPAG) system service.
Minimum: PQL_MWSQUOTA
Default: PQL_DWSQUOTA
Nondeductible

Use of the Quota List

The values specified in the quota list are not necessarily the quotas that are actually assigned to the created process. The $CREPRC service performs the following steps to determine the quota values that are assigned when you create a process on the same node:

  1. It constructs a default quota list for the process being created, assigning it the default values for all quotas. Default values are system parameters and so might vary from system to system.
  2. It reads the specified quota list, if any, and updates the corresponding items in the default list. If the quota list contains multiple entries for a quota, only the last specification is used.
  3. For each item in the updated quota list, it compares the quota value with the minimum value required (also a system parameter) and uses the larger value. Then, the following occurs:

When you create a detached process on another OpenVMS Cluster node, the quotas assigned to the process are determined in the following way:

  1. The $CREPRC service reads the specified quota list, if any. If it contains multiple entries for a quota, only the last specification is used. If the process does not have IMPERSONATE or CMKRNL privilege, the service compares each value in the list with the current value of the corresponding quota of the creating process and uses the lesser value. It sends the resulting quota list to the node on which the new process is to be created.
  2. On that node, the $CREPRC service constructs a default quota list for the process being created, assigning it default values for all quotas based on that node's system parameters.
  3. It updates the default list with the corresponding values from the quota list.
  4. For each item in the updated quota list, it compares the quota value with the minimum value required based on that node's system parameters and uses the larger value.

prcnam


OpenVMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed-length string descriptor

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


OpenVMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value

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


OpenVMS usage: uic
type: longword (unsigned)
access: read only
mechanism: by value

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


OpenVMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by value

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.

Previous Next Contents Index