Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

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.

## $CRELNT

> Creates a process-private or shareable logical name table.

> On Alpha 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)
> 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 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.

> #### 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)
> 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 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)
> 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 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)
> 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 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)
> 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 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)
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 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.

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)
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 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)
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 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: | longword (unsigned)
> access: | read only
> mechanism: | by value

> Indicator specifying whether the created mailbox is to be permanent or temporary. The prmflg argument is a longword value. The value 1 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.

> #### 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 word value containing this number. If you do not specify the bufquo argument or specify it as 0, the operating system provides a default value.

> The maximum value that you can specify with the bufquo argument is 60000. For a temporary mailbox, this value must be less than or equal to the process buffer quota.

> #### 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.

Previous | Next | Contents | Index

| privacy and legal statement |
4527PRO_017.HTML