Creates a process-private or shareable logical name table.
On Alpha and Integrity server systems, this service accepts 64-
bit addresses.
Format
SYS$CRELNT [attr] ,[resnam] ,[reslen] ,[quota]
,[promsk] ,[tabnam] ,partab ,[acmode]
C Prototype
int sys$crelnt (unsigned int *attr, void *resnam, unsigned
short int *reslen, unsigned int *quota,
unsigned short int *promsk, void *tabnam, void
*partab, unsigned char *acmode);
1 – Arguments
attr
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Attributes to affect the creation of the logical name table and
to be associated with the newly created logical name table. The
attr argument is the 32- or 64-bit address of a longword bit mask
specifying these attributes.
Each bit in the longword corresponds to an attribute and has a
symbolic name. These symbolic names are defined by the $LNMDEF
macro. To specify an attribute, specify its symbolic name or set
its corresponding bit. The longword bit mask is the logical OR of
all desired attributes. All unused bits in the longword must be
0.
If you do not specify this argument or specify it as 0 (no bits
set), no attributes are associated with the logical name table or
affect the creation of the new table.
The following table describes each attribute:
Attribute Description
LNM$M_CONFINE If set, the logical name table is not copied
from the process to its spawned subprocesses. You
create a subprocess with the DCL command SPAWN or
the Run-Time Library LIB$SPAWN routine. You can
specify this attribute only for process-private
logical name tables; it is ignored for shareable
tables.
The state of this bit is also propagated from
the parent table to the newly created table
and can be overridden only if the parent table
does not have the bit set. Thus, if the parent
table has the LNM$M_CONFINE attribute, the newly
created table will also have it, no matter what
is specified in the attr argument. On the other
hand, if the parent table does not have the
LNM$M_CONFINE attribute, the newly created table
can be given this attribute through the attr
argument.
The process-private directory table LNM$PROCESS_
DIRECTORY does not have the LNM$M_CONFINE
attribute.
LNM$M_CREATE_ This attribute applies to all types of logical
IF name tables except clusterwide logical name
tables. If set, a new logical name table is
created only if the specified table name is not
already entered at the specified access mode in
the appropriate directory table. If the table
name exists, a new table is not created and no
modification is made to the existing table name.
This holds true even if the existing name has
differing attributes or quota values, or even if
it is not the name of a logical name table.
If LNM$M_CREATE_IF is not set, the new logical
name table will supersede any existing table name
with the same access mode within the appropriate
directory table. Setting this attribute is useful
when two or more users want to create and use
the same table but do not want to synchronize its
creation.
Regardless of the setting of LNM$M_CREATE_IF:
o You cannot create a new clusterwide logical
name table with the same name and the same
mode as an existing clusterwide logical name
table until you delete the existing one.
o If you specify a new clusterwide logical name
table with the same name and access mode as
an existing local logical name table, the new
clusterwide logical name table is created,
and the local table and its logical names are
deleted.
LNM$M_NO_ If set, the name of the logical name table cannot
ALIAS be duplicated at an outer access mode within
the appropriate directory table. If this name
already exists at an outer access mode, it is
deleted. Note that this attribute does not apply
to clusterwide logical name tables.
resnam
OpenVMS usage:logical_name
type: character-coded text string
access: write only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Name of the newly created logical name table, returned by
$CRELNT. The resnam argument is the 32- or 64-bit address of a
descriptor pointing to this name. The name is a character string
whose maximum length is 31 characters.
reslen
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
Length in bytes of the name of the newly created logical name
table, returned by $CRELNT. The reslen argument is the 32- or
64-bit address of a word to receive this length.
quota
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Maximum number of bytes of memory to be allocated for logical
names contained in this logical name table. The quota argument is
the 32- or 64-bit address of a longword specifying this value.
If you specify no quota value, the logical name table has an
infinite quota. Note that a shareable table created with infinite
quota permits users with write access to that table to consume
system dynamic memory without limit.
promsk
OpenVMS usage:file_protection
type: word (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Protection mask to be associated with the newly created shareable
logical name table. The promsk argument is the 32- or 64-bit
address of a word that contains a value that represents four
4-bit fields. Each field grants or denies the type of access,
either delete, create, write, or read, allowed for system, owner,
group, and world users.
The following diagram depicts these protection bits:
|------------|------------|------------|------------|
| World | Group | Owner | System |
|------------|------------|------------|------------|
| D C W R | D C W R | D C W R | D C W R |
|------------|------------|------------|------------|
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
Create access is required to create a shareable table within
another shareable table.
Each field consists of 4 bits specifying protection for the
logical name table. The remaining bits in the protection mask
are as follows:
o Read privileges allow access to names in the logical name
table.
o Write privileges allow creation and deletion of names within
the logical name table.
o Delete privileges allow deletion of the logical name table.
If a bit is clear, access is granted.
The initial security profile for any shared logical name table is
taken from the logical name table template. The owner is then set
to the process UIC and, if the promsk argument is nonzero, that
value replaces the protection mask.
tabnam
OpenVMS usage:logical_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
The name of the new logical name table. The tabnam argument
is the 32- or 64-bit address of a character-string descriptor
pointing to this name string. Table names are contained in either
the process or system directory table (LNM$PROCESS_DIRECTORY or
LNM$SYSTEM_DIRECTORY); therefore, table names must consist of
alphanumeric characters, dollar signs ($), and underscores (_);
the maximum length is 31 characters. Names of logical name tables
must be in uppercase letters. If you specify a lowercase name,
the $CRELNT service automatically changes it to uppercase.
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
Name string for the parent table name. The partab argument is the
32- or 64-bit address 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 Integrity
servers)
Access mode to be associated with the newly created logical name
table. The acmode argument is the 32- or 64-bit address 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.