 |
HP OpenVMS System Services Reference Manual
$CREATE_USER_PROFILE can also return any error returned by the $GETUAI
or $FIND_HELD services.
$CRELNM
Creates a logical name and specifies its equivalence names.
On Alpha and I64 systems, this service accepts 64-bit addresses.
Format
SYS$CRELNM [attr] ,tabnam ,lognam ,[acmode] ,[itmlst]
C Prototype
int sys$crelnm (unsigned int *attr, void *tabnam, void *lognam,
unsigned char *acmode, void *itmlst);
Arguments
attr
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64) |
| mechanism: |
by 32-bit reference (VAX) |
Attributes to be associated with the logical name. The
attr argument is the 32-bit address (on VAX systems)
or the 32- or 64-bit address (on Alpha and I64 systems) 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
undefined 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.
The attributes are as follows:
| Attribute |
Description |
|
LNM$M_CONFINE
|
If set, the logical name is not copied from the process to its spawned
subprocesses. You create a subprocess with the DCL command SPAWN or the
LIB$SPAWN Run-Time Library routine. If the logical name is placed into
a process-private table that has the CONFINE attribute, the CONFINE
attribute is automatically associated with the logical name. This
applies only to process-private logical names.
|
|
LNM$M_NO_ALIAS
|
If set, the logical name cannot be duplicated in this table at an outer
access mode. If another logical name with the same name already exists
in the table at an outer access mode, it is deleted.
|
tabnam
| OpenVMS usage: |
logical_name |
| 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 of the table in which to create the logical name. The
tabnam argument is the 32-bit address (on VAX systems)
or the 32- or 64-bit address (on Alpha and I64 systems) of a descriptor
that points to the name of this table. This argument is required and
must be specified in uppercase.
The name must be entered in uppercase letters. (This requirement
differs from the $CRELNT system service, which automatically changes
tabnam to uppercase.)
If tabnam is not the name of a logical name table, it
is assumed to be a logical name and is translated iteratively until
either the name of a logical name table is found or the number of
translations allowed by the system has been performed. If
tabnam translates to a list of logical name tables,
the logical name is entered into the first table in the list.
lognam
| OpenVMS usage: |
logical_name |
| 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 of the logical name to be created. The lognam
argument is the 32-bit address (on VAX systems) or the 32- or 64-bit
address (on Alpha and I64 systems) of a descriptor that points to the
logical name string.
Logical name strings of logical names created within either the system
or process directory table must consist of uppercase alphanumeric
characters, dollar signs ($), hyphens (-), and underscores (_); the
maximum length is 31 characters. The maximum length of logical name
strings created within other tables is 255 characters with no
restrictions on the types of characters that can be used. 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 logical name. 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 that
specifies the access mode.
The access mode associated with the logical name is determined by
maximizing the access mode of the caller with the access mode
specified by the acmode argument, which means that the
less privileged of the two is used. Symbols for the four access modes
are defined by the $PSLDEF macro.
You cannot specify an access mode more privileged than that of the
containing table. However, if the caller has SYSNAM privilege, then the
specified access mode is associated with the logical name regardless of
the access mode of the caller.
If you omit this argument or specify it as 0, the access mode of the
caller is associated with the logical name.
itmlst
| OpenVMS usage: |
32-bit item_list_3 or 64-bit item_list 64b |
| type: |
longword (unsigned) for 32-bit; quadword (unsigned) for
64-bit |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64) |
| mechanism: |
by 32-bit reference (VAX) |
Item list describing the equivalence names to be defined for the
logical name and information to be returned to the caller. The
itmlst argument is the 32-bit address (on VAX systems)
or the 32- or 64-bit address (on Alpha and I64 systems) of a list of
item descriptors, each of which specifies information about an
equivalence name. An item list in 32-bit format is terminated by a
longword of 0; an item list in 64-bit format is terminated by a
quadword of 0. All items in an item list must be of the same
format---either 32-bit or 64-bit.
Note that it is possible to create a logical that has no equivalence
names. This is done by either omitting the itmlst
argument to $CRELNM, or by not including the LNM$_STRING item code to
the itmlst data structure that is passed into $CRELNM.
It is not possible to create this kind of logical using DCL.
The following diagram depicts the 32-bit format of a single item
descriptor:
The following table defines the item descriptor fields for 32-bit item
list entries:
| Descriptor Field |
Definition |
|
Buffer length
|
A word specifying the number of bytes in the buffer pointed to by the
buffer address field. The length of the buffer needed depends on the
item code specified in the item code field of the item descriptor. If
the value of buffer length is too small, the service truncates the data.
|
|
Item code
|
A word containing a symbolic code that describes the information in the
buffer or the information to be returned to the buffer, pointed to by
the buffer address field. The item codes are listed in the Item Codes
section.
|
|
Buffer address
|
A longword containing the 32-bit address of the buffer that receives or
passes information.
|
|
Return length address
|
A longword containing the 32-bit address of a word specifying the
actual length in bytes of the information returned by $CRELNM in the
buffer pointed to by the buffer address field. The return length
address field is used only when the item code specified is LNM$_TABLE.
Although this field is ignored for all other item codes, it must
nevertheless be present as a placeholder in each item descriptor.
|
The following diagram depicts the 64-bit format of a single item
descriptor:
The following table defines the item descriptor fields for 64-bit item
list entries:
| Descriptor Field |
Definition |
|
MBO
|
The field must contain a 1. The MBO and MBMO fields are used to
distinguish 32-bit and 64-bit item list entries.
|
|
Item code
|
A word containing a symbolic code that describes the information in the
buffer or the information to be returned to the buffer, pointed to by
the buffer address field. The item codes are listed in the Item Codes
section.
|
|
MBMO
|
The field must contain a --1. The MBMO and MBO fields are used to
distinguish 32-bit and 64-bit item list entries.
|
|
Buffer length
|
A quadword specifying the number of bytes in the buffer pointed to by
the buffer address field. The length of the buffer needed depends on
the item code specified in the item code field of the item descriptor.
If the value of buffer length is too small, the service truncates the
data.
|
|
Buffer address
|
A quadword containing the 64-bit address of the buffer that receives or
passes information.
|
|
Return length address
|
A quadword containing the 64-bit address of a word specifying the
actual length in bytes of the information returned by $CRELNM in the
buffer pointed to by the buffer address field. The return length
address field is used only when the item code specified is LNM$_TABLE.
Although this field is ignored for all other item codes, it must
nevertheless be present as a placeholder in each item descriptor.
|
Item Codes
LNM$_ATTRIBUTES
When you specify LNM$_ATTRIBUTES, the buffer address field of the item
descriptor points to a longword bit mask that specifies the current
translation attributes for the logical name. The current translation
attributes are applied to all subsequently specified equivalence
strings until another LNM$_ATTRIBUTES item descriptor is encountered in
the item list. The symbolic names for these attributes are defined by
the $LNMDEF macro. The symbolic name and description of each attribute
are as follows:
| Attribute |
Description |
|
LNM$M_CONCEALED
|
If set, OpenVMS RMS interprets the equivalence name as a device name or
logical name with the LNM$M_CONCEALED attribute.
|
|
LNM$M_TERMINAL
|
If set, further iterative logical name translation on the equivalence
name is not to be performed.
|
LNM$_CHAIN
When you specify LNM$_CHAIN, the buffer address field of the item
descriptor points to another item list that $CRELNM is to process
immediately after it has processed the current item list.
If you specify the LNM$_CHAIN item code, it must be the last item code
in the current item list.
You can chain together 32-bit and 64-bit item lists.
LNM$_STRING
When you specify LNM$_STRING, the buffer address field of the item
descriptor points to a buffer containing a user-specified equivalence
name for the logical name. The maximum length of the equivalence string
is 255 characters.
When $CRELNM encounters an item descriptor with the item code
LNM$_STRING, it creates an equivalence name entry for the logical name
using the most recently specified values for LNM$_ATTRIBUTES. The
equivalence name entry includes the following information:
- Name specified by LNM$_STRING.
- Next available index value. Each equivalence is assigned a unique
value from 0 to 127.
- Attributes specified by the most recently encountered item
descriptor with item code LNM$_ATTRIBUTES (if these are present in the
item list).
Therefore, you should construct the item list so that the
LNM$_ATTRIBUTES item codes immediately precede the LNM$_STRING item
code or codes to which they apply.
Note that it is possible to create a logical that has no equivalence
names. This is done by either omitting the itmlst
argument to $CRELNM, or by not including the LNM$_STRING item code to
the itmlst data structure that is passed into $CRELNM.
It is not possible to create this kind of logical using DCL.
LNM$_TABLE
When you specify LNM$_TABLE, the buffer address field of the item
descriptor points to a buffer in which $CRELNM writes the name of the
logical name table in which it entered the logical name. The return
length address field points to a word that contains a buffer that
specifies the length in bytes of the information returned by $CRELNM.
The maximum length of the name of a logical name table is 31 characters.
This item code can appear anywhere in the item list.
Description
The Create Logical Name service creates a logical name and specifies
its equivalence name. Note that logical names are case sensitive.
Required Access or Privileges
The calling process must have the following:
- Write access to shareable tables to create logical names in those
tables
- GRPNAM or GRPPRV privilege to enter a logical name into the group
logical name table
- SYSNAM or SYSPRV privilege to enter a logical name into the system
logical name table
Required Quota
The quota for the specified logical name table must be sufficient for
the creation of the logical name.
Related Services
$CRELNT, $DELLNM, $TRNLNM
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully; the logical name has been created.
However, if you attempted to create a new clusterwide logical name with
the same access mode and identical equivalence names and attributes as
an existing clusterwide logical name, this message indicates only that
the service completed successfully. Because an identical clusterwide
logical name already exists, and because a clusterwide update would
adversely affect performance, the name is not created.
|
|
SS$_SUPERSEDE
|
The service completed successfully; the logical name has been created
and a previously existing logical name with the same name has been
deleted.
|
|
SS$_BUFFEROVF
|
The service completed successfully; the buffer length field in an item
descriptor specified an insufficient value, so the buffer was not large
enough to hold the requested data.
|
|
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 logical name table
name or logical name was not specified. Or, an item list containing
both 32-bit and 64-bit item list entries was found.
|
|
SS$_DUPLNAM
|
An attempt was made to create a logical name with the same name as an
already existing logical name, and the existing logical name was
created at a more privileged access mode and with the LNM$M_NO_ALIAS
attribute.
|
|
SS$_EXLNMQUOTA
|
The quota associated with the specified logical name table for the
creation of the logical name is insufficient.
|
|
SS$_INSFMEM
|
The dynamic memory is insufficient for the creation of the logical
name, or there is insufficient dynamic memory to build a message
describing the creation of a clusterwide name.
|
|
SS$_IVLOGNAM
|
The
tabnam argument, the
lognam argument, or the equivalence string specifies a
string whose length is not in the required range of 1 through 255
characters. The
lognam argument specifies a string whose length is not
in the required range of 1 to 31 characters for directory table entries.
|
|
SS$_IVLOGTAB
|
The
tabnam argument does not specify a logical name table.
|
|
SS$_NOLOGTAB
|
Either the specified logical name table does not exist or the logical
name translation of the table name exceeded the allowable depth of 10
translations.
|
|
SS$_NOPRIV
|
The caller lacks the necessary privilege to create the logical name.
|
|
SS$_TOOMANYLNAM
|
An attempt was made to create a logical name with more than 128
equivalence names.
|
$CRELNT
Creates a process-private or shareable logical name table.
On Alpha and I64 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);
Arguments
attr
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64) |
| mechanism: |
by 32-bit reference (VAX) |
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-bit address (on VAX systems)
or the 32- or 64-bit address (on Alpha and I64 systems) 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_IF
|
This attribute applies to all types of logical 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:
- 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.
- 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_ALIAS
|
If set, the name of the logical name table cannot 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
(Alpha and I64) |
| mechanism: |
by 32-bit descriptor--fixed-length string descriptor
(VAX) |
Name of the newly created logical name table, returned by $CRELNT. The
resnam argument is the 32-bit address (on VAX systems)
or the 32- or 64-bit address (on Alpha and I64 systems) 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 (Alpha and I64) |
| mechanism: |
by 32-bit reference (VAX) |
Length in bytes of the name of the newly created logical name table,
returned by $CRELNT. The reslen argument is the 32-bit
address (on VAX systems) or the 32- or 64-bit address (on Alpha and I64
systems) 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 (Alpha and I64) |
| mechanism: |
by 32-bit reference (VAX) |
Maximum number of bytes of memory to be allocated for logical names
contained in this logical name table. The quota
argument is the 32-bit address (on VAX systems) or the 32- or 64-bit
address (on Alpha and I64 systems) 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 (Alpha and I64) |
| mechanism: |
by 32-bit reference (VAX) |
Protection mask to be associated with the newly created shareable
logical name table. The promsk argument is the 32-bit
address (on VAX systems) or the 32- or 64-bit address (on Alpha and I64
systems) 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:
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:
- Read privileges allow access to names in the logical name table.
- Write privileges allow creation and deletion of names within the
logical name table.
- 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
(Alpha and I64) |
| mechanism: |
by 32-bit descriptor--fixed-length string descriptor
(VAX) |
The name of the new logical name table. The tabnam
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. 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 latters. If you specify a lowercase name, the $CRELNT
service automatically changes it to uppercase.
|
