HP OpenVMS System Services Reference Manual
This argument is required for clusterwide logical name tables. For all
other logical name tables, if you do not specify this argument, a
default name in the format LNM$xxxx is used, where
xxxx is a unique hexadecimal number.
You need SYSPRV privilege or write access to LNM$SYSTEM_DIRECTORY to
specify the name of a shareable logical name table.
partab
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32- or 64-bit descriptor--fixed-length string descriptor
(Alpha and I64) |
| mechanism: |
by 32-bit descriptor--fixed-length string descriptor
(VAX) |
Name string for the parent table name. The partab
argument is the 32-bit address (on VAX systems) or the 32- or 64-bit
address (on Alpha and I64 systems) of a character string descriptor
pointing to this name string.
If the parent table is shareable, then the newly created table is
shareable and is entered into the system directory
LNM$SYSTEM_DIRECTORY. If the parent table is process-private, then the
newly created table is process-private and is entered in the process
directory LNM$PROCESS_DIRECTORY.
You need SYSPRV privilege or write access to the system directory table
to create a named shareable table. This argument is required.
acmode
| OpenVMS usage: |
access_mode |
| type: |
byte (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64) |
| mechanism: |
by 32-bit reference (VAX) |
Access mode to be associated with the newly created logical name table.
The acmode argument is the 32-bit address (on VAX
systems) or the 32- or 64-bit address (on Alpha and I64 systems) of a
byte containing this access mode. The $PSLDEF macro defines symbolic
names for the four access modes.
If you do not specify the acmode argument or specify
it as 0, the access mode of the caller is associated with the newly
created logical name table.
The access mode associated with the logical name table is determined by
maximizing the access mode of the caller with the access mode
specified by the acmode. The less privileged of the
two access modes is used.
However, if the caller has SYSNAM privilege, then the specified access
mode is associated with the logical name table, regardless of the
access mode of the caller.
Access modes associated with logical name tables govern logical name
table processing and provide a protection mechanism that prevents the
deletion of inner access mode logical name tables by nonprivileged
users. You cannot specify an access mode more privileged than that of
the parent table.
A logical name table with supervisor mode access can contain supervisor
mode and user mode logical names and can be a parent to supervisor mode
and user mode logical name tables, but cannot contain executive or
kernel mode logical names or be a parent to executive or kernel mode
logical name tables.
You need SYSNAM privilege to specify executive or kernel mode access
for a logical name table.
Description
The Create Logical Name Table service creates a process-private or a
shareable logical name table.
The $CRELNT service uses the following system resources:
- System paged dynamic memory to create a shareable logical name table
- Process dynamic memory to create a process-private logical name
table
The parent table governs whether the new table is process-private or
shareable. If the parent table is process-private, so is the new table;
if the parent table is shareable, so is the new table.
Note that logical names are case sensitive.
Required Access or Privileges
Create access to the parent table and either SYSPRV privilege or write
access to the system directory table are required.
You need the SYSNAM privilege to create a table at an access mode more
privileged than that of the calling process.
Required Quota
The parent table must have sufficient quota for the creation of the new
table.
Related Services
$CRELNM, $DELLNM, $TRNLNM
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully; the logical name table already
exists.
|
|
SS$_LNMCREATED
|
The service completed successfully; the logical name table was created.
|
|
SS$_SUPERSEDE
|
The service completed successfully; the logical name table was created
and its logical name superseded the already existing logical names in
the directory table.
|
|
SS$_ACCVIO
|
The service cannot access the locations specified by one or more
arguments.
|
|
SS$_BADPARAM
|
One or more arguments have an invalid value, or a parent logical name
table was not specified.
|
|
SS$_DUPLNAM
|
You attempted to create a logical name table with the same name as an
already existing name within the appropriate directory table, and the
existing name was created at a more privileged access mode with the
LNM$M_NO_ALIAS attribute.
|
|
SS$_EXLNMQUOTA
|
The parent table has insufficient quota for the creation of the new
table.
|
|
SS$_INSFMEM
|
The dynamic memory is insufficient for the creation of the table, or
there is insufficient dynamic memory to build a message describing the
creation of a clusterwide logical name table.
|
|
SS$_IVLOGNAM
|
The
partab argument specifies a string whose length is not
within the required range of 1 to 31 characters.
|
|
SS$_IVLOGTAB
|
The
tabnam argument is not alphanumeric or specifies a
string whose length is not within the required range of 1 to 31
characters, or the TABNAM argument is omitted from a clusterwide
$CRELNT call.
|
|
SS$_NOLOGTAB
|
The parent logical name table does not exist.
|
|
SS$_NOPRIV
|
The caller lacks the necessary privilege to create the table.
|
|
SS$_PARENT_DEL
|
The creation of the new table would have resulted in the deletion of
the parent table.
|
|
SS$_RESULTOVF
|
The table name buffer is not large enough to contain the name of the
new table.
|
$CREMBX
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,...);
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:
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_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, refer
to 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.
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 system parameter DEFMBXMXMSG
determines the maximum message size; the system 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, refer to 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
|
One or more of the arguments has an invalid value. One possible problem
is the
flags argument has both the CMB$M_READONLY and
CMB$M_WRITEONLY flags set; however, only one of these values is allowed.
|
|
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 HP
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.
|
|
