The MBX utility Version V1.2 © Marc Van Dyck, 01-JUN-1999 Installation guide User's guide Programmer's guide Release notes The MBX utility Page 2 CONTENTS CHAPTER 1 INTRODUCTION CHAPTER 2 INSTALLATION CHAPTER 3 DESCRIPTION CHAPTER 4 COMMAND SYNTAX 4.1 MBX/CREATE . . . . . . . . . . . . . . . . . . . . 4-1 4.1.1 Parameters . . . . . . . . . . . . . . . . . . . 4-1 4.1.2 Qualifiers . . . . . . . . . . . . . . . . . . . 4-1 4.1.3 Status Codes Returned . . . . . . . . . . . . . 4-2 4.2 MBX/DELETE . . . . . . . . . . . . . . . . . . . . 4-3 4.2.1 Parameters . . . . . . . . . . . . . . . . . . . 4-3 4.2.2 Qualifiers . . . . . . . . . . . . . . . . . . . 4-3 4.2.3 Status Codes Returned . . . . . . . . . . . . . 4-3 4.3 MBX/ATTACH . . . . . . . . . . . . . . . . . . . . 4-4 4.3.1 Parameters . . . . . . . . . . . . . . . . . . . 4-4 4.3.2 Qualifiers . . . . . . . . . . . . . . . . . . . 4-4 4.3.3 Status Codes Returned . . . . . . . . . . . . . 4-4 4.4 MBX/DETACH . . . . . . . . . . . . . . . . . . . . 4-5 4.4.1 Parameters . . . . . . . . . . . . . . . . . . . 4-5 4.4.2 Qualifiers . . . . . . . . . . . . . . . . . . . 4-5 4.4.3 Status Codes Returned . . . . . . . . . . . . . 4-5 4.5 MBX/RECEIVE . . . . . . . . . . . . . . . . . . . 4-6 4.5.1 Parameters . . . . . . . . . . . . . . . . . . . 4-6 4.5.2 Qualifiers . . . . . . . . . . . . . . . . . . . 4-6 4.5.3 Status Codes Returned . . . . . . . . . . . . . 4-7 4.6 MBX/SEND . . . . . . . . . . . . . . . . . . . . . 4-8 4.6.1 Parameters . . . . . . . . . . . . . . . . . . . 4-8 4.6.2 Qualifiers . . . . . . . . . . . . . . . . . . . 4-8 4.6.3 Status Codes Returned . . . . . . . . . . . . . 4-9 CHAPTER 5 CALLABLE INTERFACE 5.1 MBX_CREATE . . . . . . . . . . . . . . . . . . . . 5-1 5.1.1 Functionality . . . . . . . . . . . . . . . . . 5-1 5.1.2 General Syntax . . . . . . . . . . . . . . . . . 5-2 5.1.3 Pascal Declaration . . . . . . . . . . . . . . . 5-2 5.1.4 Arguments . . . . . . . . . . . . . . . . . . . 5-2 5.1.5 Returns . . . . . . . . . . . . . . . . . . . . 5-4 5.2 MBX_DELETE . . . . . . . . . . . . . . . . . . . . 5-6 5.2.1 Functionality . . . . . . . . . . . . . . . . . 5-6 5.2.2 General Syntax . . . . . . . . . . . . . . . . . 5-6 5.2.3 Pascal Declaration . . . . . . . . . . . . . . . 5-6 5.2.4 Arguments . . . . . . . . . . . . . . . . . . . 5-6 5.2.5 Returns . . . . . . . . . . . . . . . . . . . . 5-7 The MBX utility Page 3 5.3 MBX_ATTACH . . . . . . . . . . . . . . . . . . . . 5-9 5.3.1 Functionality . . . . . . . . . . . . . . . . . 5-9 5.3.2 General Syntax . . . . . . . . . . . . . . . . . 5-9 5.3.3 Pascal Declaration . . . . . . . . . . . . . . . 5-9 5.3.4 Arguments . . . . . . . . . . . . . . . . . . . 5-9 5.3.5 Returns . . . . . . . . . . . . . . . . . . . 5-10 5.4 MBX_DETACH . . . . . . . . . . . . . . . . . . . 5-11 5.4.1 Functionality . . . . . . . . . . . . . . . . 5-11 5.4.2 General Syntax . . . . . . . . . . . . . . . . 5-11 5.4.3 Pascal Declaration . . . . . . . . . . . . . . 5-11 5.4.4 Arguments . . . . . . . . . . . . . . . . . . 5-11 5.4.5 Returns . . . . . . . . . . . . . . . . . . . 5-12 5.5 MBX_SEND . . . . . . . . . . . . . . . . . . . . 5-13 5.5.1 Functionality . . . . . . . . . . . . . . . . 5-13 5.5.2 General Syntax . . . . . . . . . . . . . . . . 5-13 5.5.3 Pascal Declaration . . . . . . . . . . . . . . 5-13 5.5.4 Arguments . . . . . . . . . . . . . . . . . . 5-13 5.5.5 Returns . . . . . . . . . . . . . . . . . . . 5-16 5.6 MBX_RECEIVE . . . . . . . . . . . . . . . . . . 5-18 5.6.1 Functionality . . . . . . . . . . . . . . . . 5-18 5.6.2 General Syntax . . . . . . . . . . . . . . . . 5-18 5.6.3 Pascal Syntax . . . . . . . . . . . . . . . . 5-18 5.6.4 Arguments . . . . . . . . . . . . . . . . . . 5-18 5.6.5 Returns . . . . . . . . . . . . . . . . . . . 5-21 CHAPTER 6 RETURN CODES AND ERROR MESSAGES 6.1 CALLABLE INTERFACE . . . . . . . . . . . . . . . . 6-1 6.1.1 Success Codes : . . . . . . . . . . . . . . . . 6-1 6.1.2 Informational Codes : . . . . . . . . . . . . . 6-1 6.1.3 Warning Codes : . . . . . . . . . . . . . . . . 6-1 6.1.4 Error Codes : . . . . . . . . . . . . . . . . . 6-2 6.1.5 Fatal Codes : . . . . . . . . . . . . . . . . . 6-2 6.2 DCL INTERFACE . . . . . . . . . . . . . . . . . . 6-2 CHAPTER 7 HISTORY, KNOWN PROBLEMS, AND FUTURE PLANS 7.1 HISTORY . . . . . . . . . . . . . . . . . . . . . 7-1 7.1.1 Version 1.0 . . . . . . . . . . . . . . . . . . 7-1 7.1.2 Version 1.1 . . . . . . . . . . . . . . . . . . 7-1 7.1.3 Version 1.2 . . . . . . . . . . . . . . . . . . 7-1 7.2 PLANS . . . . . . . . . . . . . . . . . . . . . . 7-1 7.3 KNOWN PROBLEMS . . . . . . . . . . . . . . . . . . 7-2 CHAPTER 1 INTRODUCTION The MBX utility has been written with three goals in mind : 1. Offer the possibility to use mailboxes directly from DCL (a feature which is sorely missed in the standard DCL); 2. Present a framework in which many VMS programming features (CLI, MSG, ...) and tools (DECset) will be exercised. 3. Offer a small demonstration of the capabilities of the PASCAL language. Enhancements, remarks and suggestions are welcome. Please mail to Marc.Vandyck@skynet.be The sources of this package can be distributed free of charge provided that the name of the author remains visible in the header comments. Modifications and enhancements are ok provided that they are duly annotated before further distribution. The author assumes no liability in case the software would not perform as expected or described in this documentation. Execution of this sofware on any platform takes place under the exclusive responsibility of the user, including any damage, loss of data or revenue that it may cause. There is no warranty that enhanced versions, maintenance releases, bug fixes, or support will be available. The current version of MBX, at today's date of 16-JUN-1999, is V1.2 and has been developped to work on OpenVMS Alpha V6.2 and on OpenVMS VAX V5.5-2. It won't work on earlier versions, unless the executables can be successfully rebuilt from the sources under this version. CHAPTER 2 INSTALLATION The MBX utility is distributed as a VMSinstal kit (MBX012.A), which must be installed with the command $ @SYS$UPDATE:VMSINSTAL MBX_ where is VAX or AXP, depending on the system where the installation takes place, and is the name of the device and directory where the kit is stored. Alternatively, on OpenVMS Alpha, MBX is also distributed as a PCSI kit, which must be installed with the command $ PRODUCT INSTALL MBX /SOURCE = where is the name of the device and directory where the kit is stored. If possible, the PCSI installation should be preferred, because PCSI offers many interesting features, and notably the possibility to remove this package from your system with the command $ PRODUCT REMOVE MBX Those who have installed MBX with VMSINSTAL and whish to remove it from their system must look at the kit contents below and perform all deletions manually. That difference aside, both methods are functionnaly equivalent. Both installations will define a new command MBX in the system's DCL tables as well as a new topic MBX in the system's VMS help library, and will provide the following files : SYS$COMMON:[SYSHLP]MBX.LNI (MBX Documentation, e.g. this file) SYS$COMMON:[SYS$STARTUP]MBX$STARTUP.COM (MBX startup command file) SYS$COMMON:[SYSEXE]MBX_CLI.EXE (MBX executable image , DCL interface) SYS$COMMON:[SYSLIB]MBX_ROUTINES.EXE (MBX shareable image, callable routines) INSTALLATION Page 2-2 SYS$COMMON:[SYSMSG]MBX_MESSAGES.EXE (MBX shareable image, message file) SYS$COMMON:[SYSLIB]MBX_DECLARATIONS.PEN (Declarations of the MBX callable routines, constants and datatypes in Pascal ENvironment format) SYS$COMMON:[SYSLIB]MBX_DECLARATIONS.SDL (Declarations of the MBX callable routines, constants and datatypes in SDL syntax) SYS$COMMON:[SYSLIB]MBX_MESSAGES.PEN (Declarations of the MBX status codes in Pascal ENvironment format) SYS$COMMON:[SYSLIB]MBX_MESSAGES.SDL (Declarations of the MBX status codes in SDL syntax) The startup file SYS$STARTUP:MBX$STARTUP.COM must be executed before the MBX package can be used. It is recommended to invoke this file from the site specific startup command file. The main purpose of this file is to install the images with the right characteristics. It can be edited by the system manager to suit the local needs. CHAPTER 3 DESCRIPTION The MBX utility allows to perform the following manipulations on mailboxes : 1. Create 2. Delete 3. Attach 4. Detach 5. Send 6. Receive The first process that will use the mailbox must create it. Other processes will only have to attach it. Send and receive operations can then be performed. Once finished, all processes must detach the mailbox. If the mailbox is temporary, it will be deleted automatically when the last attached process detaches. Permanent mailboxes have to be deleted explicitely. The delete operation is however deferred until there are no more processes attached. Creation of permanent mailboxes require special attention because they are created using system resources that are not checked against any quota; if used on a large scale, it could deplete those resources until the system operations are seriously compromised. As such, this operation is reserved to users having the PRMMBX privilege. In addition, the SYSNAM privilege is also required, unless the logical LNM$PERMANENT_MAILBOX is redefined to point to a less-protected logical name table than LNM$SYSTEM. The MBX utility creates the mailboxes in supervisor mode. As there is no documented way to change a process mode to supervisor, all operations performed on the mailboxes are done in executive mode. Also, the logical names that are used to store the channel number between the operations are all kernel mode logicals, so that they can't be messed up with by DCL users (There is no DEFINE/KERNEL). The privilege CMKRNL is therefore required to use MBX. As this is a DESCRIPTION Page 3-2 dangerous privilege to give away, the MBX image is installed with CMKRNL privilege at startup time so that non-privileged users can make use of it. Error messages have been implemented using the VMS message facility. All MBX commands end up with a successful message if /LOG was requested, and a success code in R0/$STATUS, unless an error occured. In that case, an MBX message will be displayed (and a failure status left in R0/$STATUS), followed if possible by a more descriptive message explaining the reason of the failure. The DCL commands $ SET MESSAGE SYS$MESSAGE:MBX_MESSAGES and WRITE SYS$OUTPUT F$MESSAGE($status) can be used to interpret the numeric values left in $STATUS. End of file conditions leave a warning completion code, time-out and buffer truncation leave an error completion code, and all other errors are fatal. The DCL commands that are used to activate the MBX utility are implemented with the SET COMMAND utility and integrated in the system's DCL tables. MBX is entirely coded in PASCAL (there is one macro source for the transfer vector used to ensure upward compatibility of the shareable image, under OpenVMS VAX. Under OpenVMS Alpha, the transfer vector is provided by the linker). The undocumented feature MESSAGE/SDL and the SDL package are used to transcode the message global symbols into PASCAL constants. SDL is also used to define the entry points of the callable interface in a language-independent way. The code is stored in a CMS library, the build done by MMS, the editing done with LSE. The analysis data generated by the pascal compiler are loaded into a SCA library. The functionality of the package has been described in a suite of DCL test scripts, which are used as a base for regression tests with DTM each time the sources are touched. The tests have been screened by PCA to ensure that all code branches have been exercised. CHAPTER 4 COMMAND SYNTAX 4.1 MBX/CREATE This command creates a mailbox and attaches it to the process that created it. 4.1.1 Parameters This command accepts only one parameter : the name that will be given to the mailbox. This will be a logical name, entered in the logical name table referenced by LNM$TEMPORARY_MAILBOX if the mailbox is temporary, or by LNM$PERMANENT_MAILBOX if the mailbox is permanent. This parameter is required. 4.1.2 Qualifiers 4.1.2.1 /MESSAGE_SIZE = {positive Integer Value} - This qualifier defines the size of one message in the mailbox. There can be many messages in the mailbox, all of the same size. The maximum size allowed is 1024 bytes. This qualifier is required. 4.1.2.2 /POSITIONS = {positive Integer Value} - This qualifier defines the maximum amount of messages that the mailbox can hold simultaneously. There is no maximum value for this qualifier, but the product <# of messages> * may not exceed 60.000. The size of temporary mailboxes is also limited by the available BYTLM quota of the process that creates it. This qualifier is required. COMMAND SYNTAX Page 4-2 4.1.2.3 /[NO]PERMANENT - This qualifier specifies whether the mailbox should be temporary or permanent. The creation of permanent mailboxes requires the PRMMBX privilege, as well as write access to the logical name table pointed by LNM$PERMANENT_MAILBOX (usually LNM$SYSTEM). This qualifier is optional; the default is NOPERMANENT. 4.1.2.4 /PROTECTION = ([S:[R][W]],[O:[R][W]],[G:[R][W]],[W:[R][W]]) - Specifies the protection mask for the mailbox. This qualifier is optional; if not specified, the system default is applied. The system default can be obtained via the DCL command "$ SHOW SECURITY /CLASS = SECURITY_CLASS DEVICE". 4.1.2.5 /LOG - If specified, success and/or informational confirmation message will be displayed to SYS$OUTPUT at the end of a successful operation. If not specified, informational messages only will be displayed. If explicitely negated, messages will appear only in case of error (warning, error, and fatal). 4.1.3 Status Codes Returned Successful completion : SS$_NORMAL Failure : MBX_MBXNOTCRE + a message explaining the cause of the error COMMAND SYNTAX Page 4-3 4.2 MBX/DELETE This command deletes an existing mailbox. Note that this action is only needed for permanent mailboxes : temporary mailboxes are deleted by VMS automatically as soon as there are no processes connected to it anymore, i.e. after all processes that have issued a $MBX /CREATE or $ MBX /ATTACH command have also issued a $ MBX /DETACH command for that mailbox. The deletion of a permanent mailbox can be requested in advance : it will anyway be deleted only after there are no processes attached to it anymore. 4.2.1 Parameters This command only accepts one parameter : the logical name that has been used for the creation of this mailbox. This parameter is required. 4.2.2 Qualifiers 4.2.2.1 /LOG - If specified, success and/or informational confirmation message will be displayed to SYS$OUTPUT at the end of a successful operation. If not specified, informational messages only will be displayed. If explicitely negated, messages will appear only in case of error (warning, error, and fatal). 4.2.3 Status Codes Returned Successful completion : SS$_NORMAL Failure : MBX_MBXNOTDEL + a message explaining the cause of the error COMMAND SYNTAX Page 4-4 4.3 MBX/ATTACH This commands establishes a connection between the process that issued the command and the mailbox designated by the parameter P1. The mailbox can be connected only if the logical name that designates it is visible; that is, temporary mailboxes, by default, can only be connected to by processes that are in the same job as the mailbox creator. 4.3.1 Parameters This command only accepts one parameter : the logical name that has been used for the creation of this mailbox. 4.3.2 Qualifiers 4.3.2.1 /LOG - If specified, success and/or informational confirmation message will be displayed to SYS$OUTPUT at the end of a successful operation. If not specified, informational messages only will be displayed. If explicitely negated, messages will appear only in case of error (warning, error, and fatal). 4.3.3 Status Codes Returned Successful completion : SS$_NORMAL Failure : MBX_MBXNOTATT + a message explaining the cause of the error COMMAND SYNTAX Page 4-5 4.4 MBX/DETACH This commands deletes the connection between the process that issued the command and the mailbox designated by the parameter P1. 4.4.1 Parameters This command only accepts one parameter : the logical name that has been used for the creation of this mailbox. 4.4.2 Qualifiers 4.4.2.1 /LOG - If specified, success and/or informational confirmation message will be displayed to SYS$OUTPUT at the end of a successful operation. If not specified, informational messages only will be displayed. If explicitely negated, messages will appear only in case of error (warning, error, and fatal). 4.4.3 Status Codes Returned Successful completion : SS$_NORMAL Failure : MBX_MBXNOTDET + a message explaining the cause of the error COMMAND SYNTAX Page 4-6 4.5 MBX/RECEIVE This command extracts a message from the mailbox designated by the parameter P1 and places it in the symbol passed as argument P2. A connection between the process and the mailbox, created by either MBX/CREATE or by MBX/ATTACH, must exist before this command is issued. 4.5.1 Parameters This command accepts two parameters : 4.5.1.1 P1 - The first one is the logical name that designates the mailbox; this parameter is mandatory. 4.5.1.2 P2 - The second parameter is the symbol into which the message must be written. The symbol specified in the second parameter will remain undefined (i.e. it will not be an empty string) if the mailbox is empty and the read performed without /WAIT , or if the message read is an end of file marker. 4.5.2 Qualifiers This command accepts the following qualifiers : 4.5.2.1 /WAIT [ = {seconds} ] - This qualifier, when specified, forces the process to wait until a message is available for reading in the mailbox. The process reads and exits directly is a message is already waiting, or waits for a message to be deposited if the mailbox is empty. If a value is entered for the qualifier, the process will wait only for the number of seconds specified. If after the delay no message has entered the mailbox, the read request will abort, and the control will return to DCL. In that case, an error status will be returned in $STATUS. COMMAND SYNTAX Page 4-7 4.5.2.2 /PID = {symbol Name} - If specified, the symbol specified as value for this qualifier will contain the PID of the process that wrote the message into the mailbox. Also valid if the message read is an end of file marker. If the mailbox was empty, and the read operation done without /WAIT, the returned pid will be "00000000". 4.5.2.3 /LOG - If specified, success and/or informational confirmation message will be displayed to SYS$OUTPUT at the end of a successful operation. If not specified, informational messages only will be displayed. If explicitely negated, messages will appear only in case of error (warning, error, and fatal). 4.5.3 Status Codes Returned Successful completion : SS$_NORMAL End of file marker : SS$_ENDOFFILE (warning) Time out : SS$_TIMEOUT - 2 (to convert it from fatal to error) Truncation : SS$_RESULTOVF - 2 (to convert it from fatal to error) Failure : MBX_MSGNOTRCV + a message explaining the cause of the error COMMAND SYNTAX Page 4-8 4.6 MBX/SEND This command inserts in the mailbox designated by the parameter P1 a message equal to the symbol passed as argument P2. A connection between the process and the mailbox, created by either MBX/CREATE or by MBX/ATTACH, must exist before this command is issued. The message passed to MBX must fit in the mailbox message size, otherwise a truncation error will be reported. Also, if all message positions in the mailbox are already occupied, a mailbox full error will be reported and the message will not be sent. 4.6.1 Parameters This command accepts two parameters. 4.6.1.1 P1 - The first parameter is the logical name that designates the mailbox; this parameter is mandatory. 4.6.1.2 P2 - A quoted string : the message to be sent to the mailbox. The parameter P2 may not be specified if either /EOF or /SYMBOL are present. 4.6.2 Qualifiers This command accepts the following qualifiers : 4.6.2.1 /EOF - Instead of writing a message, the process deposits a end of file mark into the mailbox. If this qualifier is specified, the command may not contain a P2 parameter. The process that will read the end of file marker will signal a warning SS$_ENDOFFILE and this status will be returned to it in $STATUS at DCL level. The qualifier /EOF may not be specified if either P2 or /SYMBOL are present. COMMAND SYNTAX Page 4-9 4.6.2.2 /WAIT [ = {seconds} ] - This qualifier, when specified, forces the process to wait until another process reads the messsage deposited into the mailbox. If a value is entered for the qualifier, the process will wait only for the number of seconds specified. If after the delay no process has read the mailbox, the write request will abort, and the control will return to DCL. In that case, an error status will be returned in $STATUS. 4.6.2.3 /PID = {symbol Name} - If specified, the symbol specified as value for this qualifier will contain the PID of the process that read the message from the mailbox. It is valid only if used with /WAIT. 4.6.2.4 /SYMBOL = {symbol Name} - If specified, takes the message to be sent from the symbol rather than from the parameter P2. This allows to send longer messages : a symbol can be up to 1024 characters long, much longer than a DCL command line. This qualifier may not be specified if either /EOF or P2 are present. 4.6.2.5 /LOG - If specified, success and/or informational confirmation message will be displayed to SYS$OUTPUT at the end of a successful operation. If not specified, informational messages only will be displayed. If explicitely negated, messages will appear only in case of error (warning, error, and fatal). 4.6.3 Status Codes Returned Successful completion : SS$_NORMAL Time out : SS$_TIMEOUT - 2 (to convert it from fatal to error) Truncation : SS$_RESULTOVF - 2 (to convert it from fatal to error) Failure : MBX_MSGNOTSNT + a message explaining the cause of the error CHAPTER 5 CALLABLE INTERFACE The image shareable SYS$LIBRARY:MBX_ROUTINES.EXE can be linked with any other program that needs mailbox services. This image is built with a transfer vector, so that future versions can be installed without relinking the applications using it. The kit provides two SDL definition files in SYS$LIBRARY, MBX_DECLARATIONS.SDL which contains every constant, data type, and routine entry point description needed to use the package, and MBX_MESSAGES.SDL which contains all MBX return codes. Using the SDL V3.2 package from the freeware CD, those definitions can be translated into almost any language for which DEC ever made a compiler. PASCAL users don't even need to go through that step, because those definitions are also provided by the kit in Pascal Environment (PEN) format, ready to be inherited by other Pascal programs. Those files are MBX_DECLARATIONS.PEN and MBX_MESSAGES.PEN in SYS$LIBRARY. The usage of those 6 routines requires possession of the CMKRNL privilege, either as a native process privilege (i.e. from SYSUAF) or as a privileged inherited from a priv-installed executable image. Remember that it is not possible to install a shareable image with privileges. In addition, the creation and deletion of permanent mailboxes are restricted to users or installed images with the PRMMBX privilege. Note : reading this chapter might appear cumbersome but will provide interesting details even for those who will only use the DCL interface ... The following routines are available : 5.1 MBX_CREATE 5.1.1 Functionality Creates a mailbox according to the user specifications, defines a logical name that points to the mailbox physical name, opens an executive I/O channel to it, and stores this I/O channel in a kernel mode process logical name. CALLABLE INTERFACE Page 5-2 5.1.2 General Syntax status <- mbx_create ( name, permanent, msg_size, msg_count, protection, iochan, device ) 5.1.3 Pascal Declaration Note : the types used in the declaration below and in all subsequent ones are all defined in the Pascal environment file SYS$LIBRARY:MBX_DECLARATIONS.PEN . [ GLOBAL ] FUNCTION mbx_create ( name : mbx_name_type ; permanent : perm_flag_type ; msg_size : msg_size_type ; msg_count : msg_count_type ; protection : prot_mask_type ; VAR iochan : mbx_chan_type ; VAR device : dev_name_type ) : UNSIGNED ; 5.1.4 Arguments 5.1.4.1 Name - 1. Contents : User-chosen name of the mailbox to be created. Will be used for all future operations on the mailbox. 2. Structure : Character string, varying length, maximum 247 bytes, actual length in two extra bytes upfront (ASCIC) . 3. Access : Read. 4. Mechanism : By copy of reference. 5. Default : None. Required parameter. 5.1.4.2 Permanent - 1. Contents : Flag defining whether the mailbox must be temporary or permanent 2. Structure : Longword, lowest bit only is significant, other ones must be zero. 3. Values : 1 is permanent, 0 is temporary. CALLABLE INTERFACE Page 5-3 4. Access : Read. 5. Mechanism : By copy of reference 6. Default : None. Required parameter. 5.1.4.3 Msg_size - 1. Contents : The maximum size of each message that will be stored in the mailbox. Maximum 1024 bytes. 2. Structure : Unsigned longword. 3. Access : Read. 4. Mechanism : By copy of reference. 5. Default : None. Required parameter. 5.1.4.4 Msg_count - 1. Contents : The maximum number of messages that the mailbox will contain. Maximum 60.000/msg_size. 2. Structure : Unsigned longword. 3. Access : Read. 4. Mechanism : By copy of reference. 5. Default : None. Required parameter. 5.1.4.5 Protection - 1. Contents : RWLP/SOGW protection bit mask for the mailbox. Physical protection is irrelevant; Logical protection must be granted in all cases; Read and write define what can be done on the mailbox. 2. Structure : Unsigned word. Array of 4 arrays of 4 bits . Bits 0..3 = System, bits 4..7 = Owner, bits 8..11 = Group, bits 12..15 = World. First bit=Read, Second bit=Write, Third bit=Logical, Fourth bit=Physical. Access is granted if bit is 0. CALLABLE INTERFACE Page 5-4 3. Values : The 16 bits to 0 causes VMS to apply the system default protection mask.. 4. Access : Read. 5. Mechanism : By copy of reference. 6. Default : None. Required parameter. 5.1.4.6 Iochan - 1. Contents : The I/O channel that must be used to communicate with the mailbox. This I/O channel will also be stored in a kernel process logical name _CHANNEL. 2. Structure : Unsigned word. 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.1.4.7 Device - 1. Contents : Physical name of the mailbox that has been created. 2. Structure : Character string, varying length, maximum 8 bytes, actual length in two extra bytes upfront (ASCIC) . 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.1.5 Returns 1. Contents : VMS condition code. 2. Structure : Unsigned longword. CALLABLE INTERFACE Page 5-5 3. Valuess : 1. MBX_MBXCRE : Success, the mailbox has been created 2. MBX_NAMALXTS : Fatal, the logical name already exists 3. Any error code returned by $CRELNM, $TRNLNM, $CMKRNL, $CMEXEC, $CREMBX, $ASSIGN . 4. Access : Write. 5. Mechanism : By reference. CALLABLE INTERFACE Page 5-6 5.2 MBX_DELETE 5.2.1 Functionality Deletes an existing mailbox, and all structures associated to it. The deletion takes place only after the last I/O channel associated with it has been de-assigned. 5.2.2 General Syntax status <- mbx_delete ( name, iochan, device ) 5.2.3 Pascal Declaration [ GLOBAL ] FUNCTION mbx_delete ( name : mbx_name_type ; VAR iochan : mbx_chan_type ; VAR device : dev_name_type ) : UNSIGNED ; 5.2.4 Arguments 5.2.4.1 Name - 1. Contents : The name of the mailbox to delete. Supply the name that has been used at the mailbox creation. 2. Structure : Character string, varying length, maximum 247 bytes, actual length in two extra bytes upfront (ASCIC) . 3. Access : Read. 4. Mechanism : By copy of reference. 5. Default : None. Required parameter, 5.2.4.2 Iochan - 1. Contents : The I/O channel that was used to communicate with the mailbox. The kernel logical name that stored this I/O channel has also been deleted. 2. Structure : Unsigned word. CALLABLE INTERFACE Page 5-7 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.2.4.3 Device - 1. Contents : Physical name of the mailbox that has been deleted. 2. Structure : Character string, varying length, maximum 8 bytes, actual length in two extra bytes upfront (ASCIC) . 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.2.5 Returns 1. Contents : VMS condition code. 2. Structure : Unsigned longword. 3. Values : 1. MBX_MBXDEL : Success, the mailbox has been deleted. 2. MBX_MBXMKDEL : Informational, the mailbox has been marked for deletion. 3. MBX_INTERR : Fatal, internal error. 4. MBX_DEVNOTMBX : Fatal, The name specified points to a device which is not a mailbox. 5. MBX_NOCHANATT : Fatal, the mailbox exists but does not have an I/O channel attached which is known by MBX. 6. or any error code returned by $TRNLNM, $DELLNM, $CMKRNL, $CMEXEC, $DELMBX, $DASSGN . 4. Access : Write. CALLABLE INTERFACE Page 5-8 5. Mechanism : By reference. CALLABLE INTERFACE Page 5-9 5.3 MBX_ATTACH 5.3.1 Functionality Opens an I/O channel to an existing mailbox, and stores the channel number in a kernel process logical name. 5.3.2 General Syntax status <- mbx_attach ( name, iochan, device ) 5.3.3 Pascal Declaration [ GLOBAL ] FUNCTION mbx_attach ( name : mbx_name_type ; VAR iochan : mbx_chan_type ; VAR device : dev_name_type ) : UNSIGNED ; 5.3.4 Arguments 5.3.4.1 Name - 1. Contents : The name of the mailbox to attach. Supply the name that has been used at the mailbox creation. 2. Structure : Character string, varying length, maximum 247 bytes, actual length in two extra bytes upfront (ASCIC) . 3. Access : Read. 4. Mechanism : By copy of reference. 5. Default : None. Required parameter, 5.3.4.2 Iochan - 1. Contents : The I/O channel that will be used to communicate with the mailbox. The kernel logical name that stores this I/O channel has also been defined. 2. Structure : Unsigned word. 3. Access : Write. CALLABLE INTERFACE Page 5-10 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.3.4.3 Device - 1. Contents : Physical name of the mailbox that has been attached. 2. Structure : Character string, varying length, maximum 8 bytes, actual length in two extra bytes upfront (ASCIC) . 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.3.5 Returns 1. Contents : VMS condition code. 2. Structure : Unsigned longword. 3. Values : 1. MBX_MBXATT : Success, the mailbox has been attached. 2. MBX_MBXALRATT : Informational, the mailbox was already attached. 3. MBX_INTERR : Fatal, internal error. 4. MBX_DEVNOTMBX : Fatal, The logical name specified points to a device which is not a mailbox. 5. or any error code returned by $TRNLNM, $CRELNM, $CMKRNL, $CMEXEC, $ASSIGN . 4. Access : Write. 5. Mechanism : By reference. CALLABLE INTERFACE Page 5-11 5.4 MBX_DETACH 5.4.1 Functionality Closes the I/O channel between the specified mailbox and the current process. Also deletes the kernel process logical name that stores the channel number. 5.4.2 General Syntax status <- mbx_detach ( name, iochan, device ) 5.4.3 Pascal Declaration [ GLOBAL ] FUNCTION mbx_detach ( name : mbx_name_type ; VAR iochan : mbx_chan_type ; VAR device : dev_name_type ) : UNSIGNED ; 5.4.4 Arguments 5.4.4.1 Name - 1. Contents : The name of the mailbox to detach. Supply the name that has been used at the mailbox creation. 2. Structure : Character string, varying length, maximum 247 bytes, actual length in two extra bytes upfront (ASCIC) . 3. Access : Read. 4. Mechanism : By copy of reference. 5. Default : None. Required parameter, 5.4.4.2 Iochan - 1. Contents : The I/O channel that was used to communicate with the mailbox. The kernel logical name that stored this I/O channel has also been deleted. 2. Structure : Unsigned word. CALLABLE INTERFACE Page 5-12 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.4.4.3 Device - 1. Contents : Physical name of the mailbox that has been detached. 2. Structure : Character string. 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.4.5 Returns 1. Contents : VMS condition code. 2. Structure : Unsigned longword. 3. Values : 1. MBX_MBXDET : Success, the mailbox has been detached. 2. MBX_INTERR : Fatal, internal error. 3. MBX_DEVNOTMBX : Fatal, The logical name specified points to a device which is not a mailbox. 4. MBX_NOCHANATT : Fatal, the mailbox exists but does not have an I/O channel attached which is known by MBX. 5. or any error code returned by $TRNLNM, $DELLNM, $CMKRNL, $CMEXEC, $DELMBX, $DASSGN . 4. Access : Write. 5. Mechanism : By reference. CALLABLE INTERFACE Page 5-13 5.5 MBX_SEND 5.5.1 Functionality Sends a message, or an end of file marker, to a mailbox. 5.5.2 General Syntax status <- mbx_send ( name, send_eof, synchronize, time_out, message, sendlen, device, pid ) 5.5.3 Pascal Declaration [ GLOBAL ] FUNCTION mbx_send ( name : mbx_name_type ; send_eof : sendeof_flag := FALSE ; synchronize : synch_flag := FALSE ; time_out : time_out_type := 0 ; message : message_type ; VAR sendlen : string_length ; VAR device : dev_name_type ; VAR pid : pid_type ) : UNSIGNED ; 5.5.4 Arguments 5.5.4.1 Name - 1. Contents : The name of the mailbox to send to. Supply the name that has been used at the mailbox creation. 2. Structure : Character string, varying length, maximum 247 bytes, actual length in two extra bytes upfront (ASCIC) .. 3. Access : Read. 4. Mechanism : By copy of reference. 5. Default : None. Required parameter, 5.5.4.2 Send_eof - 1. Contents : Flag indicating that an EOF marker must be sent, rather than a message. CALLABLE INTERFACE Page 5-14 2. Structure : Byte. Only lowest bit is significant, other bits must be 0. 3. Values : True or 1 for sending an EOF marker, False or 0 for sending a message. 4. Access : Read. 5. Mechanism : By copy of reference. 6. Default : False, 0. 5.5.4.3 Synchronize - 1. Contents : Flag indicating that the I/O request should hang until another process reads the mailbox. 2. Structure : Byte. Only lowest bit is significant, other bits must be 0. 3. Values : True or 1 for synchronization, False or 0 for immediate return. 4. Access : Read. 5. Mechanism : By copy of reference. 6. Default : False, 0. 5.5.4.4 Time_out - 1. Contents : Number of seconds to wait for synchronization, until the I/O operation is aborted. If time-out happens, the message is NOT sent ! 2. Structure : Unsigned longword. 3. Values : 0 means no time-out. 4. Access : Read. 5. Mechanism : By copy of reference. 6. Default : 0. CALLABLE INTERFACE Page 5-15 5.5.4.5 Message - 1. Contents : Message to be sent to the mailbox. Ignored if send_eof is set to true, or if time-out occurs. 2. Structure : Character string, varying length, maximum 1024 bytes, actual length in two extra bytes upfront (ASCIC) . 3. Access : Read. 4. Mechanism : By copy of reference. 5. Default : None. Required parameter. 5.5.4.6 Sendlen - 1. Contents : Number of bytes that have effectively been sent to the mailbox. 2. Structure : Unsigned word. 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.5.4.7 Iochan - 1. Contents : The I/O channel that is used to communicate with the mailbox. 2. Structure : Unsigned word 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.5.4.8 Device - 1. Contents : Physical name of the mailbox that has been used. CALLABLE INTERFACE Page 5-16 2. Structure : Character string, varying length, maximum 8 bytes, actual length in two extra bytes upfront (ASCIC) . 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.5.4.9 Pid - 1. Contents : PID of the process that has read the message. 2. Structure : Unsigned longword. 3. Values : 0, means that it has been impossible to provide the information, for whatever reason. 4. Access : Write. 5. Mechanism : By reference. 6. Default : None. Required parameter. 5.5.5 Returns 1. Contents : VMS condition code. 2. Structure : Longword. 3. Values 1. MBX_MSGSNT : Success, the message has been sent. 2. MBX_EOFSNT : Success, the requested eof marker has been sent. 3. MBX_TIMMSGSNT : Error, time out occured. 4. MBX_TRCMSGSNT : Error, the message has been truncated (the mailbox message size is too small for the message) . 5. MBX_INTERR : Fatal, internal error 6. MBX_DEVNOTMBX : Fatal, The logical name specified points to a device which is not a mailbox. CALLABLE INTERFACE Page 5-17 7. MBX_NOCHANATT : Fatal, the mailbox exists but does not have an I/O channel attached which is known by MBX. 8. or any error code returned by $TRNLNM, $CMEXEC, $QIOW, $CANCEL, $BINTIM, $SETIMR, $CANTIM 4. Access : Write. 5. Mechanism : By reference. CALLABLE INTERFACE Page 5-18 5.6 MBX_RECEIVE 5.6.1 Functionality Receives a message from a mailbox. 5.6.2 General Syntax status <- mbx_receive ( name, synchronize, time_out, message, reclen, device, pid ) 5.6.3 Pascal Syntax [ GLOBAL ] FUNCTION mbx_receive ( name : mbx_name_type ; synchronize : synch_flag := FALSE ; time_out : time_out_type := 0 ; VAR message : message_type ; VAR reclen : string_length ; VAR device : dev_name_type ; VAR pid : pid_type ) : UNSIGNED ; 5.6.4 Arguments 5.6.4.1 Name - 1. Contents : The name of the mailbox to read from. Supply the name that has been used at the mailbox creation. 2. Structure : Character string, varying length, maximum 247 bytes, actual length in two extra bytes upfront (ASCIC) . 3. Access : Read. 4. Mechanism : By copy of reference. 5. Default : None. Required parameter, 5.6.4.2 Synchronize - 1. Contents : Flag indicating that the I/O request should hang until a message appears the mailbox. Completes immediately if a message was there already. CALLABLE INTERFACE Page 5-19 2. Structure : Byte. Only lowest bit is significant, other bits must be 0. 3. Values : True or 1 for synchronization, False or 0 for immediate return. 4. Access : Read. 5. Mechanism : By copy of reference. 6. Default : False, 0. 5.6.4.3 Time_out - 1. Contents : Number of seconds to wait for synchronization, until the I/O operation is aborted. 2. Structure : Unsigned longword. 3. Values : 0 means no time-out. 4. Access : Read. 5. Mechanism : By copy of reference. 6. Default : 0. 5.6.4.4 Message - 1. Contents : Buffer for the message to be read from the mailbox. Ignored if EOF marker is received, or if time-out occurs. 2. Structure : Character string, varying length, maximum 1024 bytes, actual length in the first word (ASCIC). 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.6.4.5 Reclen - CALLABLE INTERFACE Page 5-20 1. Contents : Number of bytes that have effectively been read from the mailbox. 2. Structure : Unsigned word. 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.6.4.6 Iochan - 1. Contents : The I/O channel that is used to communicate with the mailbox. 2. Structure : Unsigned word. 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.6.4.7 Device - 1. Contents : Physical name of the mailbox that has been used. 2. Structure : Character string, varying length, maximum 8 bytes, actual length in two extra bytes upfront (ASCIC) . 3. Access : Write. 4. Mechanism : By reference. 5. Default : None. Required parameter. 5.6.4.8 Pid - 1. Contents : PID of the process that has sent the message. 2. Structure : Unsigned longword. 3. Values : 0, means that it has been impossible to provide the information, for whatever reason. CALLABLE INTERFACE Page 5-21 4. Access : Write. 5. Mechanism : By reference. 6. Default : None. Required parameter. 5.6.5 Returns 1. Contents : VMS condition code. 2. Structure : Longword. 3. Values : 1. MBX_MSGRCV : Success, a message has been received. 2. MBX_EOFRCV : Warning, an eof marker has been received. 3. MBX_TIMMSGSNT : Error, time out occured. 4. MBX_TRCMSGSNT : Error, the message has been truncated (the user buffer is too small to contain the message) . 5. MBX_INTERR : Fatal, internal error 6. MBX_DEVNOTMBX : Fatal, The logical name specified points to a device which is not a mailbox. 7. MBX_NOCHANATT : Fatal, the mailbox exists but does not have an I/O channel attached which is known by MBX. 8. or any error code returned by $TRNLNM, $CMEXEC, $QIOW, $CANCEL, $BINTIM, $SETIMR, $CANTIM, $GETDVIW 4. Access : Write. 5. Mechanism : By reference. CHAPTER 6 RETURN CODES AND ERROR MESSAGES 6.1 CALLABLE INTERFACE The MBX callable interface does not signal any error message, but it can return several completion codes. Some are VMS standard ones : they are returned from VMS system services. The other ones are implemented for and by MBX, available in SYS$LIBRARY:MBX_MESSAGES.PEN/.SDL, and documented below. 6.1.1 Success Codes : MBX_MBXCRE Mailbox created MBX_MBXDEL Mailbox deleted MBX_MBXATT Channel attached MBX_MBXDET Channel detached MBX_MSGRCV Message received MBX_MSGSNT Message sent MBX_EOFSNT EOF marker sent 6.1.2 Informational Codes : MBX_MBXALRATT Mailbox already attached MBX_MBXMKDEL Mailbox marked for deletion 6.1.3 Warning Codes : MBX_EOFRCV EOF marker received RETURN CODES AND ERROR MESSAGES Page 6-2 6.1.4 Error Codes : MBX_TRCMSGSNT Truncated message sent MBX_TRCMSGRCV Truncated message received MBX_TIMMSGSNT Time-out expired while waiting for a reader MBX_TIMMSGRCV Time-out expired while waiting for a message 6.1.5 Fatal Codes : MBX_MBXINTERR Internal error detected - please submit an SPR MBX_NAMALRXTS Logical name already exists MBX_NOCHANATT Mailbox has no channel attached 6.2 DCL INTERFACE The MBX DCL interface can signal several messages. However, to make the usage of the utility easier in command procedures, the following has been implemented : 1. All operations that complete successfully return SS$NORMAL in $STATUS. A success message will only be displayed if /LOG has been specified. An informational message will only be displayed if /NOLOG has not been specified. 2. All situations that cause the requested operation to fail completely, result in a fatal error code returned in $STATUS, that can be trapped by an instruction "$ ON SEVERE THEN ..." . This message will be followed by a secondary one explaining the cause of the failure. 3. Situations where the requested operation completed in an unexpected way return a warning or error code in $STATUS : Recieving an end of file marker returns a WARNING completion code ; Message truncation (on both send and receive) or time-out conditions return an ERROR completion code. 4. If /NOLOG has not been specified, wait states will cause the display of an informational message, when the wait state begins. CHAPTER 7 HISTORY, KNOWN PROBLEMS, AND FUTURE PLANS 7.1 HISTORY 7.1.1 Version 1.0 Version 1.0, never released, contained only the bare functionality needed to use the package. 7.1.2 Version 1.1 Version 1.1, released to field test sites only, added synchronization, sender/receiver PID identification, MBX error messages, and the /LOG qualifier on all commands. 7.1.3 Version 1.2 Version 1.2, the current one and the first one released, adds the possibility to specify a time out for both MBX/SEND and MBX/RECEIVE with /WAIT, as well as the possibility to pass either a character string expression or a symbol to MBX/SEND. The internal structure of MBX has also been completely reviewed, with only 3 images (message, shareable, and executable) instead of 7. A consequence of this re-work is that MBX now offers a fully documented API (a.k.a. callable interface). Version 1.2 also offers an OpenVMS VAX version, and a PCSI package for installation under OpenVMS Alpha. 7.2 PLANS Version 1.3 is not planned yet, and will only be developped if there is sufficient interest (i.e. requests for enhancements and/or bug fixes). Considered for this release are the implementation of a condition handler, a new DCL command and callable routine to obtain the number of messages waiting to be read in a mailbox, and the replacement of the kernel mode logical names (used to store the I/O channel numbers) by a safer and more performant mechanism (permanent HISTORY, KNOWN PROBLEMS, AND FUTURE PLANS Page 7-2 global section ?). 7.3 KNOWN PROBLEMS There is currently only one known problem, under AXP/VMS V6.2 : the LIB$SET_SYMBOL routine does not work as documented. Its documentation states that the symbol's equivalence string can contain up to 1024 characters. However, when using it, passing for the equivalence string parameter any string containing more than 255 characters causes the routine to return LIB$_INVARG. As this routine is used by MBX/RECEIVE to pass the result back to DCL, strings of more than 255 characters cannot be used. This problem is supposedly solved in OpenVMS V7.2, in which the routine LIB$SET_SYMBOL routine has apparently been fixed.