OpenVMS System Services Reference Manual

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

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 vector 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 vector by specifying the symbolic name of each desired privilege in a logical OR operation. Table SYS-5 gives the symbolic name and description of each privilege.

Table SYS-5 User Privileges
Privilege Symbolic Name Description

ACNT PRV$V_ACNT Create processes for which no accounting is done

ALLSPOOL PRV$V_ALLSPOOL Allocate a spooled device

ALTPRI PRV$V_ALTPRI Set (alter) any process priority

AUDIT PRV$V_AUDIT Generate audit records

BUGCHK PRV$V_BUGCHK Make bugcheck error log entries

BYPASS PRV$V_BYPASS Bypass UIC-based protection

CMEXEC PRV$V_CMEXEC Change mode to executive

CMKRNL PRV$V_CMKRNL Change mode to kernel

DETACH PRV$V_DETACH Create detached processes

DIAGNOSE PRV$V_DIAGNOSE Can diagnose devices

DOWNGRADE PRV$V_DOWNGRADE Can downgrade classification

EXQUOTA PRV$V_EXQUOTA Can exceed quotas

GROUP PRV$V_GROUP Group process control

GRPNAM PRV$V_GRPNAM Place name in group logical name table

GRPPRV PRV$V_GRPPRV Group access via system protection field

IMPORT PRV$V_IMPORT Mount a nonlabeled tape volume

LOG_IO PRV$V_LOG_IO Perform logical I/O operations

MOUNT PRV$V_MOUNT Issue mount volume QIO

NETMBX PRV$V_NETMBX Create a network device

OPER PRV$V_OPER All operator privileges

PFNMAP PRV$V_PFNMAP Map to section by physical page frame number

PHY_IO PRV$V_PHY_IO Perform physical I/O operations

PRMCEB PRV$V_PRMCEB Create permanent common event flag clusters

PRMGBL PRV$V_PRMGBL Create permanent global sections

PRMMBX PRV$V_PRMMBX Create permanent mailboxes

PSWAPM PRV$V_PSWAPM Change process swap mode

READALL PRV$V_READALL Possess read access to everything

SECURITY PRV$V_SECURITY Can perform security functions

SETPRV PRV$V_SETPRV Set any process privileges

SHARE PRV$V_SHARE Can assign a channel to a non-shared device

SYSGBL PRV$V_SYSGBL Create system global sections

SYSLCK PRV$V_SYSLCK Queue systemwide locks

SYSNAM PRV$V_SYSNAM Place name in system logical name table

SYSPRV PRV$V_SYSPRV Access files and other resources as if you have a system UIC

TMPMBX PRV$V_TMPMBX Create temporary mailboxes

UPGRADE PRV$V_UPGRADE Can upgrade classification

VOLPRO PRV$V_VOLPRO Override volume protection

WORLD PRV$V_WORLD World process control

**Table SYS-5 User Privileges**
Privilege	Symbolic Name	Description
ACNT	PRV$V_ACNT	Create processes for which no accounting is done
ALLSPOOL	PRV$V_ALLSPOOL	Allocate a spooled device
ALTPRI	PRV$V_ALTPRI	Set (alter) any process priority
AUDIT	PRV$V_AUDIT	Generate audit records
BUGCHK	PRV$V_BUGCHK	Make bugcheck error log entries
BYPASS	PRV$V_BYPASS	Bypass UIC-based protection
CMEXEC	PRV$V_CMEXEC	Change mode to executive
CMKRNL	PRV$V_CMKRNL	Change mode to kernel
DETACH	PRV$V_DETACH	Create detached processes
DIAGNOSE	PRV$V_DIAGNOSE	Can diagnose devices
DOWNGRADE	PRV$V_DOWNGRADE	Can downgrade classification
EXQUOTA	PRV$V_EXQUOTA	Can exceed quotas
GROUP	PRV$V_GROUP	Group process control
GRPNAM	PRV$V_GRPNAM	Place name in group logical name table
GRPPRV	PRV$V_GRPPRV	Group access via system protection field
IMPORT	PRV$V_IMPORT	Mount a nonlabeled tape volume
LOG_IO	PRV$V_LOG_IO	Perform logical I/O operations
MOUNT	PRV$V_MOUNT	Issue mount volume QIO
NETMBX	PRV$V_NETMBX	Create a network device
OPER	PRV$V_OPER	All operator privileges
PFNMAP	PRV$V_PFNMAP	Map to section by physical page frame number
PHY_IO	PRV$V_PHY_IO	Perform physical I/O operations
PRMCEB	PRV$V_PRMCEB	Create permanent common event flag clusters
PRMGBL	PRV$V_PRMGBL	Create permanent global sections
PRMMBX	PRV$V_PRMMBX	Create permanent mailboxes
PSWAPM	PRV$V_PSWAPM	Change process swap mode
READALL	PRV$V_READALL	Possess read access to everything
SECURITY	PRV$V_SECURITY	Can perform security functions
SETPRV	PRV$V_SETPRV	Set any process privileges
SHARE	PRV$V_SHARE	Can assign a channel to a non-shared device
SYSGBL	PRV$V_SYSGBL	Create system global sections
SYSLCK	PRV$V_SYSLCK	Queue systemwide locks
SYSNAM	PRV$V_SYSNAM	Place name in system logical name table
SYSPRV	PRV$V_SYSPRV	Access files and other resources as if you have a system UIC
TMPMBX	PRV$V_TMPMBX	Create temporary mailboxes
UPGRADE	PRV$V_UPGRADE	Can upgrade classification
VOLPRO	PRV$V_VOLPRO	Override volume protection
WORLD	PRV$V_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

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.

Individual Quota Descriptions

A description of each quota follows. The description of each quota lists its minimum value (a SYSGEN parameter), its default value (a SYSGEN parameter), and whether it is deductible, nondeductible, or pooled. These terms have the following meaning:

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 SYSGEN 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 SYSGEN 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 pages (on VAX systems) or pagelets (adjusted up or down to represent CPU-specific pages on Alpha systems) 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 pages (on VAX systems) or pagelets (adjusted up or down to represent CPU-specific pages on Alpha systems) 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:

It constructs a default quota list for the process being created, assigning it the default values for all quotas. Default values are SYSGEN parameters and so might vary from system to system.
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.

For each item in the updated quota list, it compares the quota value with the minimum value required (also a SYSGEN parameter) and uses the larger value. Then, the following occurs:

If a subprocess is being created or if a detached process is being created and the creating process does not have DETACH or CMKRNL privilege, the resulting value is compared with the current value of the corresponding quota of the creating process and the lesser value is used.
Then, if the quota is a deductible quota, that value is deducted from the creating process's quota, and a check is performed to ensure that the creating process will still have at least the minimum quota required. If not, the condition value SS$_EXQUOTA is returned and the subprocess or detached process is not created.
Pooled quota values are ignored.
If a detached process is being created and the creating process has DETACH or CMKRNL privilege, the resulting value is not compared with the current value of the corresponding quota of the creating process and the resulting value is not deducted from the creating process's quota. A process with DETACH or CMKRNL privilege is allowed to create a detached process with quota values larger than it has.

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

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 DETACH 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.
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 SYSGEN parameters.
It updates the default list with the corresponding values from the quota list.
For each item in the updated quota list, it compares the quota value with the minimum value required based on that node's SYSGEN 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 VAX range is 0 to 31, where 31 is the highest priority and 0 is the lowest. Usual priorities are in the range 0 to 15, and real-time priorities are in the range 16 to 31. The OpenVMS Alpha 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 node.

If the baspri argument is not specified, the priority defaults to 2 for VAX MACRO and VAX BLISS--32 and 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 DETACH 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.

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 if the process was created on the same node. If it was created on a different OpenVMS Cluster node, the second longword of the I/O status block contains 0.

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.

Offset Symbolic Name Contents

0 ACC$W_MSGTYP MSG$_DELPROC (2 bytes)

2 Not used (2 bytes)

4 ACC$L_FINALSTS Exit status code

8 ACC$L_PID External process identification

12 Not used (4 bytes)

16 ACC$Q_TERMTIME Current time in system format at process termination (8 bytes)

24 ACC$T_ACCOUNT Account name for process, blank filled (8 bytes)

32 ACC$T_USERNAME User name, blank filled (12 bytes)

44 ACC$L_CPUTIM CPU time used by the process, in 10-millisecond units

48 ACC$L_PAGEFLTS Number of page faults incurred by the process

52 ACC$L_PGFLPEAK Peak paging file usage

56 ACC$L_WSPEAK Peak working set size

60 ACC$L_BIOCNT Count of buffered I/O operations performed by the process

64 ACC$L_DIOCNT Count of direct I/O operations performed by the process

68 ACC$L_VOLUMES Count of volumes mounted by the process

72 ACC$Q_LOGIN Time, in system format, that process logged in (8 bytes)

80 ACC$L_OWNER Process identification of owner

Offset	Symbolic Name	Contents
0	ACC$W_MSGTYP	MSG$_DELPROC (2 bytes)
2		Not used (2 bytes)
4	ACC$L_FINALSTS	Exit status code
8	ACC$L_PID	External process identification
12		Not used (4 bytes)
16	ACC$Q_TERMTIME	Current time in system format at process termination (8 bytes)
24	ACC$T_ACCOUNT	Account name for process, blank filled (8 bytes)
32	ACC$T_USERNAME	User name, blank filled (12 bytes)
44	ACC$L_CPUTIM	CPU time used by the process, in 10-millisecond units
48	ACC$L_PAGEFLTS	Number of page faults incurred by the process
52	ACC$L_PGFLPEAK	Peak paging file usage
56	ACC$L_WSPEAK	Peak working set size
60	ACC$L_BIOCNT	Count of buffered I/O operations performed by the process
64	ACC$L_DIOCNT	Count of direct I/O operations performed by the process
68	ACC$L_VOLUMES	Count of volumes mounted by the process
72	ACC$Q_LOGIN	Time, in system format, that process logged in (8 bytes)
80	ACC$L_OWNER	Process identification of owner

  4527P015.HTM
  OSSG Documentation
  22-NOV-1996 12:59:05.09

Legal

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