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 logical name is specified and a mailbox
with the specified name already exists, the $CREMBX service
assigns a channel to the existing mailbox.
Format
SYS$CREMBX [prmflg] ,chan ,[maxmsg] ,[bufquo] ,[promsk]
,[acmode] ,[lognam] ,[flags] ,[nullarg]
C Prototype
int sys$crembx (char prmflg, unsigned short int *chan,
unsigned int maxmsg, unsigned int bufquo,
unsigned int promsk, unsigned int acmode, void
*lognam,...);
1 – Arguments
prmflg
OpenVMS usage:boolean
type: byte (unsigned)
access: read only
mechanism: by value
Indicator specifying whether the created mailbox is to be
permanent or temporary. The prmflg argument is a byte value.
The first bit specifies a permanent mailbox; the value 0, which
is the default, specifies a temporary mailbox. Any other values
result in an error.
chan
OpenVMS usage:channel
type: word
access: write only
mechanism: by reference
Channel number assigned by $CREMBX to the mailbox. The chan
argument is the address of a word into which $CREMBX writes the
channel number.
maxmsg
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Maximum size (in bytes) of a message that can be sent to the
mailbox. The maxmsg argument is a longword value containing this
size.
The maximum value you can specify for the maxmsg argument is
65535. If you do not specify a value or specify the value
as 0, the operating system provides a default value from the
DEFMBXBUFQUO system parameter.
bufquo
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of bytes of system dynamic memory that can be used to
buffer messages sent to the mailbox. The bufquo argument is a
value containing this number. If you do not specify the bufquo
argument or specify it as 0, the operating system provides a
default value from the DEFMBXBUFQUO system parameter.
For a temporary mailbox, this value must be less than or equal to
the process buffer quota.
Note that as of Version 7.3-1, the maximum value limit for the
bufquo argument is the amount of available non-paged pool.
promsk
OpenVMS usage:file_protection
type: longword (unsigned)
access: read only
mechanism: by value
Protection mask to be associated with the created mailbox. The
promsk argument is a longword value that is the combined value
of the bits set in the protection mask. Cleared bits grant access
and set bits deny access to each of the four classes of user:
world, group, owner, and system. The following diagram depicts
these protection bits:
|------------|------------|------------|------------|
| World | Group | Owner | System |
|------------|------------|------------|------------|
| L P W R | L P W R | L P W R | L P W R |
|------------|------------|------------|------------|
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
If you do not specify the promsk argument or specify it as 0, the
mailbox template is used.
The logical access bit must be clear for the class of user
requiring access to the mailbox. The access bit must be clear
for all categories of user because logical access is required to
read or write to a mailbox; thus, setting or clearing the read
and write access bits is meaningless unless the logical access
bit is also cleared.
The physical access bit is ignored for all categories of user.
Logical access also allows you to queue read or write attention
ASTs.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the channel to which the
mailbox is assigned. The acmode argument is a longword containing
the access mode.
The $PSLDEF macro defines the following symbols for the four
access modes:
Symbol Access Mode Numeric Value
PSL$C_KERNEL Kernel 0
PSL$C_EXEC Executive 1
PSL$C_SUPER Supervisor 2
PSL$C_USER User 3
The most privileged access mode used is the access mode of
the caller. The specified access mode and the access mode of
the caller are compared. The less privileged (but the higher
numeric valued) of the two access modes becomes the access
mode associated with the assigned channel. I/O operations on
the channel can be performed only from equal or more privileged
access modes.
lognam
OpenVMS usage:logical_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Logical name to be assigned to the mailbox. The lognam argument
is the address of a character string descriptor pointing to the
logical name string.
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_ When this flag is specified, $CREMBX assigns
READONLY 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_ When this flag is specified, $CREMBX assigns
WRITEONLY 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 HP 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 HP.