OpenVMS System Services Reference Manual

Document revision date: 19 July 1999

OpenVMS System Services Reference Manual

Contents

Index

The equivalence name for the mailbox is MBAn. The equivalence name is marked with the terminal attribute. Processes can use the logical name to assign other I/O channels to the mailbox.

For permanent mailboxes, the $CREMBX service enters the specified logical name, if any, in the LNM$PERMANENT_MAILBOX logical name table and, for temporary mailboxes, into the LNM$TEMPORARY_MAILBOX logical name table.

flags

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

The flags argument is used for specifying options for the assign operation that occurs in $CREMBX. The flags argument is a longword bit mask that enables the user to specify that the channel assigned to the mailbox is a READ ONLY or WRITE ONLY channel. If the flags argument is not specified, then the default channel behavior is READ/WRITE. The $CMBDEF macro defines a symbolic name for each flag bit. The following table describes each flag.

Flag	Description
CMB$M_READONLY	When this flag is specified, $CREMBX assigns a read-only channel to the mailbox device. An attempt to issue a QIO WRITE operation on the mailbox channel results in an illegal I/O operation error.
CMB$M_WRITEONLY	When this flag is specified, $CREMBX assigns a write-only channel to the mailbox device. An attempt to issue a QIO READ operation on the mailbox channel results in an illegal I/O operation error.

For more information about the flags argument, see the OpenVMS I/O User's Reference Manual.

nullarg

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

Placeholding argument reserved by Compaq.

Description

The Create Mailbox and Assign Channel service creates a virtual mailbox device named MBAn and assigns an I/O channel to it. The system provides the unit number n when it creates the mailbox. If a mailbox with the specified name already exists, the $CREMBX service assigns a channel to the existing mailbox.
The $CREMBX service uses system dynamic memory to allocate a device database for the mailbox and for an entry in the logical name table (if a logical name is specified).
When a temporary mailbox is created, the process's buffered I/O byte count (BYTLM) quota is reduced by the amount specified in the bufquo argument. The size of the mailbox unit control block and the logical name (if specified) are also subtracted from the quota. The quota is returned to the process when the mailbox is deleted.
The initial security profile created for a mailbox is taken from the mailbox template for the device class. The owner is then set to the process UIC and the promsk argument replaces the protection mask.
After the process creates a mailbox, it and other processes can assign additional channels to it by calling the Assign I/O Channel ($ASSIGN) or Create Mailbox ($CREMBX) service. If the mailbox already exists, the $CREMBX service assigns a channel to that mailbox; in this way, cooperating processes need not consider which process must execute first to create the mailbox.
A channel assigned to the mailbox READ ONLY is considered a READER. A channel assigned to the mailbox WRITE ONLY is considered a WRITER. A channel assigned to the mailbox READ/WRITE is considered both a WRITER and READER.
A temporary mailbox is deleted when no more channels are assigned to it. A permanent mailbox must be explicitly marked for deletion with the Delete Mailbox ($DELMBX) service; its actual deletion occurs when no more channels are assigned to it.
A mailbox is treated as a shareable device; it cannot, however, be mounted or allocated.
The mailbox unit number is determined when the mailbox is created. A process can obtain the unit number of the created mailbox by calling the Get Device/Volume Information ($GETDVI) service using the channel returned by $CREMBX.
Mailboxes are assigned sequentially increasing numbers (from 1 to a maximum of 9999) as they are created. When all unit numbers have been used, the system starts numbering again at unit 1. Logical names or mailbox names should be used to identify a mailbox between cooperating processes.
Default values for the maximum message size and the buffer quota (an appropriate multiple of the message size) are determined for a specific system during system generation. The SYSGEN parameter DEFMBXMXMSG determines the maximum message size; the SYSGEN parameter DEFMBXBUFQUO determines the buffer quota. For termination mailboxes, the maximum message size must be at least as large as the termination message (currently 84 bytes).
When you specify a logical name for a temporary mailbox, the $CREMBX service enters the name into the LNM$TEMPORARY_MAILBOX logical name table.
Normally, LNM$TEMPORARY_MAILBOX specifies LNM$JOB, the jobwide logical name table; thus, only processes in the same job as the process that first creates the mailbox can use the logical name to access the temporary mailbox. If you want to use the temporary mailbox to enable communication between processes in different jobs, you must redefine LNM$TEMPORARY_MAILBOX in the process logical name directory table (LNM$PROCESS_DIRECTORY) to specify a logical name table that those processes can access.
For instance, if you want to use the mailbox as a communication device for processes in the same group, you must redefine LNM$TEMPORARY_MAILBOX to specify LNM$GROUP, the group logical name table. The following DCL command assigns temporary mailbox logical names to the group logical name table:
$ DEFINE/TABLE=LNM$PROCESS_DIRECTORY LNM$TEMPORARY_MAILBOX LNM$GROUP
When you specify a logical name for a permanent mailbox, the system enters the name in the logical name table specified by the logical name table name LNM$PERMANENT_MAILBOX, which normally specifies LNM$SYSTEM, the system logical name table. If you want the logical name that you specify for the mailbox to be entered in a logical name table other than the system logical name table, you must redefine LNM$PERMANENT_MAILBOX to specify the desired table. For more information about logical name tables, see the OpenVMS Programming Concepts Manual.
If you redefine either LNM$TEMPORARY_MAILBOX or LNM$PERMANENT_MAILBOX, be sure that the name of the new table appears in the logical name table LNM$FILE_DEV. OpenVMS RMS and the I/O system services use LNM$FILE_DEV to translate I/O device names. If the logical name table specified by either LNM$TEMPORARY_MAILBOX or LNM$PERMANENT_MAILBOX does not appear in LNM$FILE_DEV, the system will be unable to translate the logical name of your mailbox and therefore will be unable to access your mailbox as an I/O device.
If you redirect a logical name table to point to a process-private table, then the following occurs:

Other processes cannot access the mailbox by its name.
If the creating process issues a second call to $CREMBX, a different mailbox is created and a channel is assigned to the new mailbox. (If the creating process issues a second call to $CREMBX using a shared logical name, a second channel is assigned to the existing mailbox.)
The logical name is not deleted when the mailbox disappears.

Required Access or Privileges

Depending on the operation, the calling process might need one of the following privileges to use $CREMBX:

TMPMBX privilege whenever the prmflg argument is specified as 0. However, a process that has PRMMBX privilege will also meet this requirement.
PRMMBX privilege whenever the prmflg argument is specified as 1.
SYSNAM privilege to place a logical name for a mailbox in the system logical name table.
GRPNAM privilege to place a logical name for a mailbox in the group logical name table.

Required Quota

The calling process must have sufficient buffer I/O byte count (BYTLM) quota to allocate the mailbox unit control block (UCB) or to satisfy buffer requirements. When a temporary mailbox is created, the process's buffered I/O byte count (BYTLM) quota is reduced by the amount specified in the bufquo argument. The size of the mailbox UCB and the logical name (if specified) are also subtracted from the quota. The quota is returned to the process when the mailbox is deleted.
Related Services

$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The logical name string or string descriptor cannot be read by the caller, or the channel number cannot be written by the caller.

SS$_BADPARAM The bufquo argument specified a value greater than approximately 65324, which is 65535 minus the size of a mailbox unit control block (UCB).

SS$_EXBYTLM The process has insufficient buffer I/O byte count (BYTLM) quota to allocate the mailbox UCB or to satisfy buffer requirements.

SS$_INSFMEM The system dynamic memory is insufficient for completing the service.

SS$_INTERLOCK The bit map lock for allocating mailboxes from the specified shared memory is locked by another process.

SS$_IVLOGNAM The logical name string has a length of 0 or has more than 255 characters.

SS$_IVSTSFLG The bit set in the prmflg argument is undefined; this argument can have a value of 1 or 0.

SS$_NOIOCHAN No I/O channel is available for assignment.

SS$_NOPRIV The process does not have the privilege to create a temporary mailbox, a permanent mailbox, a mailbox in memory that is shared by multiple processors, or a logical name.

SS$_NOSHMBLOCK No shared memory mailbox UCB is available for use to create a new mailbox.

SS$_OPINCOMPL A duplicate unit number was encountered while linking a shared memory mailbox UCB. If this condition value is returned, contact your Compaq support representative.

SS$_SHMNOTCNCT The shared memory named in the name argument is not known to the system. This error can be caused by a spelling error in the string, an improperly assigned logical name, or the failure to identify the multiport memory as shared at system generation time.

SS$_TOOMANYLNAM The logical name translation of the string named in the lognam argument exceeded the allowed depth.

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

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$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 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-5 gives the symbolic name and description of each privilege.

Table SYS-5 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 ¹ 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 non-shared 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

**Table SYS-5 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 ¹	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 non-shared 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

¹This 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 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.

Previous Next Contents Index

privacy and legal statement

4527PRO_016.HTML

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The logical name string or string descriptor cannot be read by the caller, or the channel number cannot be written by the caller.
SS$_BADPARAM	The bufquo argument specified a value greater than approximately 65324, which is 65535 minus the size of a mailbox unit control block (UCB).
SS$_EXBYTLM	The process has insufficient buffer I/O byte count (BYTLM) quota to allocate the mailbox UCB or to satisfy buffer requirements.
SS$_INSFMEM	The system dynamic memory is insufficient for completing the service.
SS$_INTERLOCK	The bit map lock for allocating mailboxes from the specified shared memory is locked by another process.
SS$_IVLOGNAM	The logical name string has a length of 0 or has more than 255 characters.
SS$_IVSTSFLG	The bit set in the prmflg argument is undefined; this argument can have a value of 1 or 0.
SS$_NOIOCHAN	No I/O channel is available for assignment.
SS$_NOPRIV	The process does not have the privilege to create a temporary mailbox, a permanent mailbox, a mailbox in memory that is shared by multiple processors, or a logical name.
SS$_NOSHMBLOCK	No shared memory mailbox UCB is available for use to create a new mailbox.
SS$_OPINCOMPL	A duplicate unit number was encountered while linking a shared memory mailbox UCB. If this condition value is returned, contact your Compaq support representative.
SS$_SHMNOTCNCT	The shared memory named in the name argument is not known to the system. This error can be caused by a spelling error in the string, an improperly assigned logical name, or the failure to identify the multiport memory as shared at system generation time.
SS$_TOOMANYLNAM	The logical name translation of the string named in the lognam argument exceeded the allowed depth.

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

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

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

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.