View source for $CREMBX

'''$CREMBX''' is a [[System Service|system service]] that creates a virtual [[Mailbox|mailbox]] device and assigns an I/O channel to it.

=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|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 [[$DELMBX|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 [[$GETDVI|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, see the [https://support.hpe.com/hpsc/doc/public/display?docId=emr_na-c04621447 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.

=Syntax=
 <nowiki>SYS$CREMBX [</nowiki>[[#prmflg|prmflg]]<nowiki>] ,</nowiki>[[#chan|chan]]<nowiki> ,[</nowiki>[[#maxmsg|maxmsg]]<nowiki>] ,[</nowiki>[[#bufquo|bufquo]]<nowiki>] ,[</nowiki>[[#promsk|promsk]]<nowiki>] ,[</nowiki>[[#acmode|acmode]]<nowiki>] ,[</nowiki>[[#lognam|lognam]]<nowiki>]
,[</nowiki>[[#flags|flags]]<nowiki>] ,[</nowiki>[[#nullarg|nullarg]]<nowiki>]</nowiki>

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==
{{SyservArgument|boolean|byte (unsigned)|read only|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==
{{SyservArgument|channel|word|write only|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==
{{SyservArgument|longword_unsigned|longword (unsigned)|read only|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==
{{SyservArgument|longword_unsigned|longword (unsigned)|read only|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 [[OpenVMS Version 7.3-1]], the maximum value limit for the '''bufquo''' argument is the amount of available non-paged pool.

==promsk==
{{SyservArgument|file_protection|longword (unsigned)|read only|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 diagram on the right depicts these protection bits:
[[File:Снимок.png|thumb]]

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==
{{SyservArgument|access_mode|longword (unsigned)|read only|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:

{| class="wikitable"
! colspan="col" | Symbol
! colspan="col" | Access Mode
! colspan="col" | 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==
{{SyservArgument|logical_name|character-coded text string|read only|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==
{{SyservArgument|mask_longword|longword (unsigned)|read only|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:

{| class="wikitable"
! colspan="col" | Flag
! colspan="col" | Description
|-
| CMB$M_READONLY 
| When this flag is specified, $CREMBX assigns a readonly 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 writeonly 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 {{Template:IO}}.

==nullarg==
{{SyservArgument|null_arg|longword (unsigned)|read only|by value}}

Placeholding argument reserved by VSI.

=Condition Values Returned=
{| class="wikitable"
! colspan="col" | Value
! colspan="col" | Description
|-
| 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 VSI 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.
|}

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

=See also=
* [http://www.eight-cubed.com/examples/framework.php?file=sys_crembx.c A C example by James Duff]
* [[$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]]

[[Category:System Services]]